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Preface 

Open Watcom C is an implementation of ISO/ANSI 9899:1990 Programming Language C. The standard 
was developed by the ANSI X3J11 Technical Committee on the C Programming Language. In addition to 
the full C language standard, the compiler supports numerous extensions for the Intel 80x86-based personal 
computer environment. The compiler is also partially compliant with the ISO/IEC 9899:1999 
Programming Language C standard. 

Open Watcom C++ is an implementation of the Draft Proposed International Standard for Information 
Systems Programming Language C++ (ANSI X3J16, ISO WG21). In addition to the full C++ language 
standard, the compiler supports numerous extensions for the Intel 80x86-based personal computer 
environment. 

Open Watcom is well known for its language processors having developed, over the last decade, compilers 
and interpreters for the APL, BASIC, COBOL, FORTRAN and Pascal programming languages. From the 
start. Open Watcom has been committed to developing portable software products. These products have 
been implemented on a variety of processor architectures including the IBM 370, the Intel 8086 family, the 
Motorola 6809 and 68000, the MOS 6502, and the Digital PDP11 and VAX. In most cases, the tools 
necessary for porting to these environments had to be created first. Invariably, a code generator had to be 
written. Assemblers, linkers and debuggers had to be created when none were available or when existing 
ones were inadequate. 

Over the years, much research has gone into developing the "ultimate" code generator for the Intel 8086 
family. We have continually looked for new ways to improve the quality of the emitted code, never being 
quite satisfied with the results. Several major revisions, including some entirely new approaches to code 
generation, have ensued over the years. Our latest version employs state of the art techniques to produce 
very high quality code for the 8086 family. We introduced the C compiler in 1987, satisfied that we had a 
C software development system that would be of major benefit to those developing applications in C for the 
IBM PC and compatibles. 

The Open Watcom C/C++ User’s Guide describes how to use Open Watcom C/C++ on Intel 80x86-based 
personal computers with DOS, Windows, Windows NT, or OS/2. 
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1 About This Manual 


This manual contains the following chapters: 

Chapter 1 — "About This Manual". 

This chapter provides an overview of the contents of this guide. 

Chapter 2 — "Open Watcom C/C++ Compiler Options" on page 5. 

This chapter provides a summary and reference section for all the C and C++ compiler 
options. 

Chapter 3 — "The Open Watcom C/C++ Compilers" on page 65. 

This chapter describes how to compile an application from the command line. This chapter 
also describes compiler environment variables, benchmarking hints, compiler diagnostics, 
#include file processing, the preprocessor, predefined macros, extended keywords, and the 
code generator. 

Chapter 4 — "Precompiled Headers" on page 101. 

This chapter describes the use of precompiled headers to speed up compilation. 

Chapter 5 — "The Open Watcom C/C++ Libraries" on page 105. 

This chapter describes the Open Watcom C/C++ library directory structure, C libraries, 
class libraries, math libraries, 80x87 math libraries, alternate math libraries, the "N087" 
environment variable, and the run-time initialization routines. 

Chapter 6 — "16-bit Memory Models" on page 117. 

This chapter describes the Open Watcom C/C++ memory models (including code and data 
models), the tiny memory model, the mixed memory model, linking applications for the 
various memory models, creating a tiny memory model application, and memory layout in 
an executable. 

Chapter 7 — "16-bit Assembly Language Considerations" on page 123. 

This chapter describes issues relating to 16-bit interfacing such as parameter passing 
conventions. 

Chapter 8 — "16-bit Pragmas" on page 139. 

This chapter describes the use of pragmas with the 16-bit compilers. 

Chapter 9 — "32-bit Memory Models" on page 185. 
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This chapter describes the Open Watcom C/C++ memory models (including code and data 
models), the flat memory model, the mixed memory model, linking applications for the 
various memory models, and memory layout in an executable. 

Chapter 10 — "32-bit Assembly Language Considerations" on page 189. 

This chapter describes issues relating to 32-bit interfacing such as parameter passing 
conventions. 


Chapter 11 — "32-bit Pragmas" on page 207. 

This chapter describes the use of pragmas with the 32-bit compilers. 

Chapter 12 — "In-line Assembly Language" on page 255. 

This chapter describes in-line assembly language programming using the auxiliary pragma. 

Chapter 13 — "Creating ROM-based Applications" on page 289. 

This chapter discusses some embedded systems issues as they pertain to the C library. 

Appendix A. — "Use of Environment Variables" on page 295. 

This appendix describes all the environment variables used by the compilers and related 
tools. 

Appendix B. — "Open Watcom C Diagnostic Messages" on page 305. 

This appendix lists all of the Open Watcom C diagnostic messages with an explanation for 
each. 


Appendix C. — "Open Watcom C++ Diagnostic Messages" on page 337. 

This appendix lists all of the Open Watcom C++ diagnostic messages with an explanation 
for each. 

Appendix D. — "Open Watcom C/C++ Run-Time Messages" on page 533. 

This appendix lists all of the C/C++ run-time diagnostic messages with an explanation for 
each. 
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2 Open Watcom C/C++ Compiler Options 


Source files can be compiled using either the IDE or command-line compilers. This chapter describes all 
the compiler options that are available. 

For information about compiling applications from the IDE, see the Open Watcom Graphical Tools User’s 
Guide. 

For information about compiling applications from the command line, see the chapter entitled "The Open 
Watcom C/C++ Compilers" on page 65. 

The Open Watcom C/C++ compiler command names ( compiler_name ) are: 

WCC the Open Watcom C compiler for 16-bit Intel platforms. 

WPP the Open Watcom C++ compiler for 16-bit Intel platforms. 

WCC386 the Open Watcom C compiler for 32-bit Intel platforms. 

WPP386 the Open Watcom C++ compiler for 32-bit Intel platforms. 


2.1 Compiler Options - Summarized Alphabetically 

In this section, we present a terse summary of compiler options. This summary is displayed on the screen 
by simply entering the compiler command name with no arguments. 

Option: Description: 

0 (16-bit only) 8088 and 8086 instructions (default for 16-bit) (see "0" on page 51) 

1 (16-bit only) 188 and 186 instructions (see "1" on page 51) 

2 (16-bit only) 286 instructions (see "2" on page 51) 

3 (16-bit only) 386 instructions (see "3" on page 51) 

4 (16-bit only) 486 instructions (see "4" on page 51) 

5 (16-bit only) Pentium instructions (see "5" on page 51) 

6 (16-bit only) Pentium Pro instructions (see "6" on page 51) 

3r (32-bit only) generate 386 instructions based on 386 instruction timings and use 

register-based argument passing conventions (see "3{rlsj" on page 51) 

3s (32-bit only) generate 386 instructions based on 386 instruction timings and use 

stack-based argument passing conventions (see "3{rls}" on page 51) 

4r (32-bit only) generate 386 instructions based on 486 instruction timings and use 

register-based argument passing conventions (see "4{rls}" on page 52) 

4s (32-bit only) generate 386 instructions based on 486 instruction timings and use 

stack-based argument passing conventions (see "4{rls}" on page 52) 

5r (32-bit only) generate 386 instructions based on Intel Pentium instruction timings and use 

register-based argument passing conventions (default for 32-bit) (see "5{rls}" on page 53) 
5s (32-bit only) generate 386 instructions based on Intel Pentium instruction timings and use 

stack-based argument passing conventions (see "5{rls}" on page 53) 

6r (32-bit only) generate 386 instructions based on Intel Pentium Pro instruction timings and 

use register-based argument passing conventions (see "6{rls}" on page 53) 
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6s (32-bit only) generate 386 instructions based on Intel Pentium Pro instruction timings and 

use stack-based argument passing conventions (see "6{rls}" on page 53) 
ad[=<file_name>] generate make style automatic dependency file (see "ad[=<file_name>]" on page 31) 
adbs force path separators generated in auto-dependency files to backslashes (see "adbs" on 

page 32) 

add[=<file_name>] specify source dependency name generated in make style auto-dependency file (see 
"add|=<ftle_name>]" on page 32) 

adhp[=<file_name> ] specify path to use for headers with no path given (see "adhp|=<path_name>]" on 
page 32) 

adfs force path separators generated in auto-dependency files to forward slashes (see "adfs" on 

page 32) 

adt[=<target_name>] specify target name generated in make style auto-dependency file (see 
"adt[=<target_name>]" on page 32) 

be build target is a console application (see "be" on page 15) 

bd build target is a Dynamic Link Library (DLL) (see "bd" on page 16) 

bg build target is a GUI application (see "bg" on page 16) 

bm build target is a multi-thread environment (see "bm" on page 16) 

br build target uses DLL version of C/C++ run-time libraries (see "br" on page 16) 

bt[=<os>] build target for operating system <os> (see "bt|=<os>]" on page 16) 

bw build target uses default windowing support (see "bw" on page 17) 

dO (C++ only) no debugging information (see "dO" on page 22) 

dl line number debugging information (see "dl" on page 22) 

dl+ (C only) line number debugging information plus typing information for global symbols 

and local structs and arrays (see "dl+" on page 22) 
d2 full symbolic debugging information (see "d2" on page 23) 

d2i (C++ only) d2 and debug inlines; emit inlines as external out-of-line functions (see "d2i" 

on page 23) 

d2s (C++ only) d2 and debug inlines; emit inlines as static out-of-line functions (see "d2s" on 

page 23) 

d2t (C++ only) full symbolic debugging information, without type names (see "d2t" on page 

23) 

d3 full symbolic debugging with unreferenced type names (see "d3" on page 23) ,* 

d3i (C++ only) d3 plus debug inlines; emit inlines as external out-of-line functions (see "d3i" 

on page 23) 

d3s (C++ only) d3 plus debug inlines; emit inlines as static out-of-line functions (see "d3s" on 

page 23) 

d<name>[=text] preprocessor #define name [text] (see "d<name>[=text]" on page 25) 
d+ allow extended -d macro definitions (see "d+" on page 25) 

db generate browsing information (see "db" on page 33) 

e<number> set error limit number (default is 20) (see "e<number>" on page 27) 

ecc set default calling convention to_cdecl (see "ecc" on page 38) 

ecd set default calling convention to_stdcall (see "ecd" on page 38) 

ecf set default calling convention to_fastcall (see "ecf" on page 38) 

ecp set default calling convention to_pascal (see "ecp" on page 38) 

ecr set default calling convention to_fortran (see "ecr" on page 38) 

ecs set default calling convention to_syscall (see "ecs" on page 38) 

ecw set default calling convention to_watcall (default) (see "ecw" on page 38) 

ee call epilogue hook routine (see "ee" on page 24) 

ef use full path names in error messages (see "ef" on page 27) 

ei force enum base type to use at least an int (see "ei" on page 38) 

em force enum base type to use minimum (see "em" on page 38) 

en emit routine name before prologue (see "en" on page 24) 
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ep[<number>] call prologue hook routine with number of stack bytes available (see "ep|<number>]" on 
page 24) 

eq do not display error messages (they are still written to a file) (see "eq" on page 27) 

er (C++ only) do not recover from undefined symbol errors (see "er" on page 27) 

et Pentium profiling (see "et" on page 24) 

ew (C++ only) generate less verbose messages (see "ew" on page 28) 

ez (32-bit only) generate Phar Lap Easy OMF-386 object file (see "ez" on page 33) 

fc=<file_name> (C++ only) specify file of command lines to be batch processed (see "fc=<file_name>" on 
page 33) 

fh[q][=<file_name>] use precompiled headers (see "fh[q][=<file_name>]" on page 33) 
fhd store debug info for pre-compiled header once (DWARF only) (see "fhd" on page 33) 

fhr (C++ only) force compiler to read pre-compiled header (see "fhr" on page 34) 

fhw (C++ only) force compiler to write pre-compiled header (see "fhw" on page 34) 

fhwe (C++ only) don’t include pre-compiled header warnings when "we" is used (see "fhwe" 

on page 34) 

fi=<file_name> force file_name to be included (see "fi=<file_name>" on page 34) 
fo=<file_name> set object or preprocessor output file specification (see "fo[=<file_name>] 

(preprocessor)" on page 26) (see "fo[=<file_name>]" on page 34) 
fpc generate calls to floating-point library (see "fpc" on page 44) 

fpi (16-bit only) generate in-line 80x87 instructions with emulation (default) 

(32-bit only) generate in-line 387 instructions with emulation (default) (see "fpi" on page 
44) 

fpi87 (16-bit only) generate in-line 80x87 instructions 


fp2 

fp3 

fp5 

fp6 

fpd 

fpr 

fr=<file_name> 

ft 

fti 

fa 

fzh 

fzs 

g=<codegroup> 

h{w,d,c} 

i=<directory> 

j 

k 


nc=<name> 

nd=<name> 


(32-bit only) generate in-line 387 instructions (see "fpi87" on page 45) 
generate in-line 80x87 instructions (see "fp2" on page 45) 
generate in-line 387 instructions (see "fp3" on page 45) 

generate in-line 80x87 instructions optimized for Pentium processor (see "fp5" on page 
46) 

generate in-line 80x87 instructions optimized for Pentium Pro processor (see "fp6" on 
page 46) 

enable generation of Pentium FDIV bug check code (see "fpd" on page 46) 
generate 8087 code compatible with older versions of compiler (see "fpr" on page 63) 
set error file specification (see "fr[=<file_name>]" on page 34) 

(C++ only) try truncated (8.3) header file specification (see "ft" on page 35) 

(C only) track include file opens (see "fti" on page 35) 

(C++ only) do not try truncated (8.3) header file specification (see "fx" on page 35) 

(C++ only) do not automatically append extensions for include files (see "fzh" on page 
35) 

(C++ only) do not automatically append extensions for source files (see "fzs" on page 35) 
set code group name (see "g=<codegroup>" on page 47) 

set debug output format (Open Watcom, Dwarf, CodeView) (see "h{w,d,c}" on page 25) 
add directory to list of include directories (see "i=<directory>" on page 35) 
change char default from unsigned to signed (see "j" on page 39) 

(C++ only) continue processing files (ignore errors) (see "k" on page 36) 
memory model — mf=flat (see "mf" on page 53), ms=small (see "ms" on page 53), 
mm=medium (see "mm" on page 53), mc=compact (see "me" on page 54), ml=large (see 
"ml" on page 54), mh=huge (see "mh" on page 54) (default is "ms" for 16-bit and 
Netware, "mf" for 32-bit) 

set name of the code class (see "nc=<name>" on page 47) 
set name of the "data" segment (see "nd=<name>" on page 47) 
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nm=<name> set module name different from filename (see "nm=<name>" on page 48) 
nt=<name> set name of the "text" segment (see "nt=<name>" on page 48) 

o{a,b,c,d,eJ,f+,h,i,i+,k,l,l+,m,n,o,p,r,s,t,ii,x,zj control optimization (see "oa" on page 56) (see "of" on page 
18) 

pil preprocessor ignores #line directives (see "pil" on page 26) 

p{e,l,c,w=<num>} preprocess file only, sending output to standard output; "c" include comments; "e" 

encrypt identifiers (C++ only); "1" include #line directives; w=<num> wrap output lines 
at <num> columns (zero means no wrap) (see "p{e,l,c,w=<num>}" on page 26) 
q operate quietly (see "q" on page 28) 

r save/restore segment registers (see "r" on page 63) 

ri return chars and shorts as ints (see "ri" on page 39) 

s remove stack overflow checks (see "s" on page 25) 

sg generate calls to grow the stack (see "sg" on page 19) 

st touch stack through SS first (see "st" on page 20) 

t=<num> (C++ only) set tab stop multiplier (see "t=<num>" on page 28) 

u<name> preprocessor #undef name (see "u<name>" on page 27) 

v output function declarations to .def file (with typedef names) (see "v" on page 36) 

vc... (C++ only) VC++ compatibility options (see "vc..." on page 62) 

w<number> set warning level number (default is wl) (see "w<number>" on page 28) 
wcd=<num> warning control: disable warning message <num> (see "wcd=<number>" on page 28) 

wce=<num> warning control: enable warning message <num> (see "wce=<number>" on page 28) 

we treat all warnings as errors (see "we" on page 28) 

wo (C only) (16-bit only) warn about problems with overlaid code (see "wo" on page 28) 

wx set warning level to maximum setting (see "wx" on page 29) 

x preprocessor ignores environment variables (see "x" on page 36) 

xd (C++ only) disable exception handling (default) (see "xd" on page 60) 

xdt (C++ only) disable exception handling (same as "xd") (see "xdt" on page 61) 

xds (C++ only) disable exception handling (table-driven destructors) (see "xds" on page 61) 

xr (C++ only) enable RTTI (see "xr" on page 39) 

xs (C++ only) enable exception handling (see "xs" on page 61) 

xst (C++ only) enable exception handling (direct calls for destruction) (see "xst" on page 61) 

xss (C++ only) enable exception handling (table-driven destructors) (see "xss" on page 61) 

xx ignore default directories for file search (.,../h,../c,...) (see "xx" on page 36) 

z{a,e} disable/enable language extensions (default is ze) (see "za" on page 29) (see "ze" on page 

29) 

zam disable all predefined old extension macros (keyword macros, non-ISO names) (see 

"zam" on page 36) 

zat (C++ only) disable alternative tokens (see "zat" on page 36) 

zc place literal strings in code segment (see "zc" on page 39) 

zdff,p} allow DS register to "float" or "peg" it to DGROUP (default is zdp) (see "zdjf.p}" on 

page 55) 

zdl (32-bit only) load DS register directly from DGROUP (see "zdl" on page 55) 

zev (C only, Unix extension) enable arithmetic on void derived types (see "zev" on page 55) 

zf (C++ only) let scope of for loop initialization extend beyond loop (see "zf" on page 36) 

zftf,p} allow FS register to be used (default for all but flat memory model) or not be used 

(default for flat memory model) (see "zfjf.p)" on page 55) 
zfw generate FWAIT instructions on 386 and later (see "zfw" on page 55) 

zg output function declarations to .def (without typedef names) (see "zg" on page 37) 

Zglf.p} allow GS register to be used or not used (see "zgjf.p}" on page 55) 

zkO double-byte char support for Kanji (see "zk{0,1,2,1}" on page 61) 

zkOu translate Kanji double-byte characters to UNICODE (see "zkOu" on page 62) 

zkl double-byte char support for Chinese/Taiwanese (see "zk{0,l,2,l}" on page 61) 
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zk2 

zkl 

zku=<codepage> 

zl 

zld 

zlf 

zls 

zm 

zmf 

zp[{l,2,4,8,16}] 

zpw 

zq 

zri 

zro 

zs 

zt<number> 

zu 

zv 

zw 

zW 

zWs 

zz 


double-byte char support for Korean (see "zk{0,1,2,1}" on page 61) 

double-byte char support if current code page has lead bytes (see "zk{0,l,2,l}" on page 

61) 

load UNICODE translate table for specified code page (see "zku=<codepage>" on page 
62) 

suppress generation of library file names and references in object file (see "zl" on page 
37) 

suppress generation of file dependency information in object file (see "zld" on page 37) 
add default library information to object files (see "zlf" on page 38) 
remove automatically inserted symbols (such as runtime library references) (see "zls" on 
page 38) 

place each function in separate segment (near functions not allowed) (see "zm" on page 
49) 

place each function in separate segment (near functions allowed) (see "zmf" on page 50) 

set minimal structure packing (member alignment) (see "zp[{ 1,2,4,8,16}]" on page 39) 

output warning when padding is added in a struct/class (see "zpw" on page 41) 

operate quietly (see "zq" on page 31) 

inline floating point rounding code (see "zri" on page 55) 

omit floating point rounding code (see "zro" on page 56) 

syntax check only (see "zs" on page 31) 

set data threshold (default is zt32767) (see "zt<number>" on page 41) 
do not assume that SS contains segment of DGROUP (see "zu" on page 56) 

(C++ only) enable virtual function removal optimization (see "zv" on page 42) 

Microsoft Windows prologue/epilogue code sequences (see "zw" on page 20) 

(16-bit only) Microsoft Windows optimized prologue/epilogue code sequences (see "zW 
(optimized)" on page 21) 

(16-bit only) Microsoft Windows smart callback sequences (see "zWs" on page 21) 
remove "@size" from_stdcall function names (10.0 compatible) (see "zz" on page 63) 


2.2 Compiler Options ■ Summarized By Category 

In the following sections, we present a terse summary of compiler options organized into categories. 


2.2.1 Target Specific 


Option: Description: 


be 

bd 

bg 

bm 

br 

bt[=<os>] 

bw 

of 

of+ 

sg 

St 

zw 


build target is a console application (see "be" on page 15) 

build target is a Dynamic Link Library (DLL) (see "bd" on page 16) 

build target is a GUI application (see "bg" on page 16) 

build target is a multi-threaded environment (see "bm" on page 16) 

build target uses DLL version of C/C++ run-time library (see "br" on page 16) 

build target for operating system <os> (see "bt[=<os>]" on page 16) 

build target uses default windowing support (see "bw" on page 17) 

generate traceable stack frames as needed (see "of' on page 18) 

always generate traceable stack frames (see "of+" on page 18) 

generate calls to grow the stack (see "sg" on page 19) 

touch stack through SS first (see "st" on page 20) 

generate code for Microsoft Windows (see "zw" on page 20) 
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zW (16-bit only) Microsoft Windows optimized prologue/epilogue code sequences (see "zW 

(optimized)" on page 21) 

zWs (16-bit only) Microsoft Windows smart callback sequences (see "zWs" on page 21) 

2.2.2 Debugging/Profiling 

Option: Description: 

dO (C++ only) no debugging information (see "dO" on page 22) 

dl line number debugging information (see "dl" on page 22) 

dl + (C only) line number debugging information plus typing information for global symbols 

and local structs and arrays (see "dl+" on page 22) 
d2 full symbolic debugging information (see "d2" on page 23) 

d2i (C++ only) d2 and debug inlines; emit inlines as external out-of-line functions (see "d2i" 

on page 23) 

d2s (C++ only) d2 and debug inlines; emit inlines as static out-of-line functions (see "d2s" on 

page 23) 

d2t (C++ only) d2 but without type names (see "d2t" on page 23) 

d3 full symbolic debugging with unreferenced type names (see "d3" on page 23) 

d3i (C++ only) d3 plus debug inlines; emit inlines as external out-of-line functions (see "d3i" 

on page 23) 

d3s (C++ only) d3 plus debug inlines; emit inlines as static out-of-line functions (see "d3s" on 

page 23) 

ee call epilogue hook routine (see "ee" on page 24) 

en emit routine names in the code segment (see "en" on page 24) 

ep[<number> ] call prologue hook routine with number stack bytes available (see "ep[<number>]" on 
page 24) 

et Pentium profiling (see "et" on page 24) 

h{w,d,c} set debug output format (Open Watcom, DWARF, CodeView) (see "h{ w,d,c}" on page 

25) 

s remove stack overflow checks (see "s" on page 25) 

2.2.3 Preprocessor 

Option: Description: 

d<name>[=text] precompilation #define name [text] (see "d<name>[=text]" on page 25) 
d+ allow extended "d" macro definitions on command line (see "d+" on page 25) 

fo[=<file_name>] set preprocessor output file name (see "fo[=<file_name>] (preprocessor)" on page 26) 
pit preprocessor ignores #line directives (see "pil" on page 26) 

p{e,l,c,w=<num>} preprocess file 

c preserve comments 

e encrypt identifiers (C++ only) 

/ insert #line directives 

w=<num> wrap output lines at <num> columns. Zero means no wrap. 

(see "p{e,l,c,w=<num>}" on page 26) 
u<name> undefine macro name (see "u<name>" on page 27) 
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2.2.4 Diagnostics 

Option: Description: 


e<number> 

ef 

eq 

er 

ew 

q 

t—<num> 

w<number> 

wcd=<num> 

wce=<num> 

we 

wx 

z{a,e} 

zq 

zs 


set error limit number (see "e<number>" on page 27) 
use full path names in error messages (see "ef" on page 27) 

do not display error messages (they are still written to a file) (see "eq" on page 27) 
(C++ only) do not recover from undefined symbol errors (see "er" on page 27) 

(C++ only) alternate error message formatting (see "ew" on page 28) 

operate quietly (see "q" on page 28) 

set tab stop multiplier (see "t=<num>" on page 28) 

set warning level number (see "w<number>" on page 28) 

warning control: disable warning message <num> (see "wcd=<number>" on page 28) 

warning control: enable warning message <num> (see "wce=<number>" on page 28) 

treat all warnings as errors (see "we" on page 28) 

set warning level to maximum setting (see "wx" on page 29) 

disable/enable language extensions (see "za" on page 29) (see "ze" on page 29) 

operate quietly (see "zq" on page 31) 

syntax check only (see "zs" on page 31) 


2.2.5 Source/Output Control 

Option: Description: 

ad[=<file_name>] generate make style auto-dependency file (see "ad[=<file_name>]" on page 31) 
adbs force path separators generated in make style auto-dependency file to backslashes (see 

"adbs" on page 32) 

add[=<file_name>] set source name (the first dependency) for make style auto-dependency file (see 
"add|=<ftle_name>]" on page 32) 

adhp[=<path prefix>] set default path for header dependencies which result in filename only (see 
"adhp|=<path_name>]" on page 32) 

adfs force path separators generated in make style auto-dependency file to forward slashes 

(see "adfs" on page 32) 

adt[=<target_name> ] specify target name generated in make style auto-dependency file (see 
"adt[=<target_name>]" on page 32) 
db generate browsing information (see "db" on page 33) 

ez generate PharLap EZ-OMF object files (see "ez" on page 33) 

fc=<file_name> (C++ only) specify file of command lines to be batch processed (see "fc=<file_name>" on 
page 33) 

fh[q][=<file_name>] use precompiled headers (see "fh|q][=<file_name>]" on page 33) 
fhd store debug info for pre-compiled header once (DWARF only) (see "fhd" on page 33) 

fhr (C++ only) force compiler to read pre-compiled header (will never write) (see "fhr" on 

page 34) 

fhw (C++ only) force compiler to write pre-compiled header (will never read) (see "fhw" on 

page 34) 

fhwe (C++ only) don't include pre-compiled header warnings when "we" is used (see "fhwe" 

on page 34) 

fi=<file_name> force file_name to be included (see "fi=<file_name>" on page 34) 
fo[=<file_name>] set object or preprocessor output file name (see "fo[=<file_name>]" on page 34) 
fr[=<file_name>] set error file name (see "fr[=<file_name>]" on page 34) 
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ft (C++ only) try truncated (8.3) header file specification (see "ft" on page 35) 

fti (C only) track include file opens (see "fti" on page 35) 

fx (C++ only) do not Uy truncated (8.3) header file specification (see "fx" on page 35) 

fzh (C++ only) do not automatically append extensions for include files (see "fzh" on page 

35) 

fzs (C++ only) do not automatically append extensions for source files (see "fzs" on page 35) 

i=<directory> another include directory (see "i=<directory>" on page 35) 
k continue processing files (ignore errors) (see "k" on page 36) 

v output function declarations to .def (see "v" on page 36) 

x ignore environment variables when searching for include files (see "x" on page 36) 

xx ignore default directories for file search (.,../h,../c,...) (see "xx" on page 36) 

zam disable all predefined old extension macros (keyword macros, non-ISO names) (see 

"zam" on page 36) 

zat (C++ only) disable alternative tokens (see "zat" on page 36) 

zf (C++ only) let scope of for loop initialization extend beyond loop (see "zf" on page 36) 

zg generate function prototypes using base types (see "zg" on page 37) 

zl remove default library information (see "zl" on page 37) 

zld remove file dependency information (see "zld" on page 37) 

zlf add default library information to object files (see "zlf" on page 38) 

zls remove automatically generated symbols references (see "zls" on page 38) 

2.2.6 Code Generation 

Option: Description: 

ecc set default calling convention to_cdecl (see "ecc" on page 38) 

ecd set default calling convention to_stdcall (see "ecd" on page 38) 

ecf set default calling convention to_fastcall (see "ecf" on page 38) 

ecp set default calling convention to_pascal (see "ecp" on page 38) 

ecr set default calling convention to_fortran (see "ecr" on page 38) 

ecs set default calling convention to_syscall (see "ecs" on page 38) 

ecw set default calling convention to_watcall (default) (see "ecw" on page 38) 

ei force enum base type to use at least an int (see "ei" on page 38) 

em force enum base type to use minimum (see "em" on page 38) 

j change char default from unsigned to signed (see "j" on page 39) 

ri return chars and shorts as ints (see "ri" on page 39) 

xr (C++ only) enable RTTI (see "xr" on page 39) 

zc place literal strings in the code segment (see "zc" on page 39) 

zp{l,2,4,8,16} pack structure members (see "zp[{ 1,2,4,8,16}]" on page 39) 

zpw output warning when padding is added in a struct/class (see "zpw" on page 41) 

zt<number> set data threshold (see "zt<number>" on page 41) 

zv (C++ only) enable virtual function removal optimization (see "zv" on page 42) 


2.2.780x86 Floating Point 

Option: Description: 

fpc calls to floating-point library (see "fpc" on page 44) 

fpi in-line 80x87 instructions with emulation (see "fpi" on page 44) 

fpi87 in-line 80x87 instructions (see "fpi87" on page 45) 
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fp2 generate floating-point for 80x87 (see "fp2" on page 45) 

fp3 generate floating-point for 387 (see "fp3" on page 45) 

fp5 optimize floating-point for Pentium (see "fp5" on page 46) 

fp6 optimize floating-point for Pentium Pro (see "fp6" on page 46) 

fpd enable generation of Pentium FDIV bug check code (see "fpd" on page 46) 


2.2.8 Segments/Modules 


Option: Description: 


g=<codegroup> 

nc=<name> 

nd=<name> 

nm=<name> 

nt—<name> 

zm 

zmf 


set code group name (see "g=<codegroup>" on page 47) 
set code class name (see "nc=<name>" on page 47) 
set data segment name (see "nd=<name>" on page 47) 
set module name (see "nm=<name>" on page 48) 
set name of text segment (see "nt=<name>" on page 48) 

place each function in separate segment (near functions not allowed) (see "zm" on page 
49) 

(C++ only) place each function in separate segment (near functions allowed) (see "zmf" 
on page 50) 


2.2.9 80x86 Run-time Conventions 


Option: Description: 


0 

1 

2 

3 

4 

5 

6 
3r 
3s 
4r 
4s 
5r 
5s 
6r 
6s 

mff,s,m,c,l,h} 

zdf 

zdp 

zdl 

zff 

zfp 

zgf 

Zgp 

zri 

zro 

zu 


(16-bit only) 8088 and 8086 instructions (see "0" on page 51) 

(16-bit only) 188 and 186 instructions (see "1" on page 51) 

(16-bit only) 286 instructions (see "2" on page 51) 

(16-bit only) 386 instructions (see "3" on page 51) 

(16-bit only) 486 instructions (see "4" on page 51) 

(16-bit only) Pentium instructions (see "5" on page 51) 

(16-bit only) Pentium Pro instructions (see "6" on page 51) 

(32-bit only) 386 register calling conventions (see "3{rls}" on page 51) 

(32-bit only) 386 stack calling conventions (see "3{rls}" on page 51) 

(32-bit only) 486 register calling conventions (see "4{rlsJ" on page 52) 

(32-bit only) 486 stack calling conventions (see "4{rls}" on page 52) 

(32-bit only) Pentium register calling conventions (see "5{rls}" on page 53) 
(32-bit only) Pentium stack calling conventions (see "5{rls}" on page 53) 

(32-bit only) Pentium Pro register calling conventions (see "6{rls}" on page 53) 
(32-bit only) Pentium Pro stack calling conventions (see "6{rls}" on page 53) 
memory model (FIat,Small,Medium,Compact,Large,Huge) (see "mf" on page 53) 
DS floats i.e. not fixed to DGROUP (see "zd{f,p}" on page 55) 

DS is pegged to DGROUP (see "zd{f,p}" on page 55) 

Load DS directly from DGROUP (see "zdl" on page 55) 

FS floats i.e. not fixed to a segment (see "zfjf.p}" on page 55) 

FS is pegged to a segment (see "zfjf.p}" on page 55) 

GS floats i.e. not fixed to a segment (see "zgjf.p}" on page 55) 

GS is pegged to a segment (see "zgjf.p}" on page 55) 

Inline floating point rounding code (see "zri" on page 55) 

Omit floating point rounding code (see "zro" on page 56) 

SS != DGROUP (see "zu" on page 56) 
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2.2.10 Optimizations 

Option: Description: 

oa relax aliasing constraints (see "oa" on page 56) 

ob enable branch prediction (see "ob" on page 57) 

oc disable <call followed by return> to <jump> optimization (see "oc" on page 57) 

od disable all optimizations (see "od" on page 57) 

oe[=<num>] expand user functions in-line. <num> controls max size (see "oe=<num>" on page 57) 

oh enable repeated optimizations (longer compiles) (see "oh" on page 57) 

oi expand intrinsic functions in-line (see "oi" on page 57) 

oi+ (C++ only) expand intrinsic functions in-line and set inline_depth to maximum (see "oi+" 

on page 58) 

ok enable control flow prologues and epilogues (see "ok" on page 58) 

ol enable loop optimizations (see "ol" on page 58) 

o/+ enable loop optimizations with loop unrolling (see "ol+" on page 58) 

om generate in-line 80x87 code for math functions (see "om" on page 58) 

on allow numerically unstable optimizations (see "on" on page 58) 

oo continue compilation if low on memory (see "oo" on page 59) 

op generate consistent floating-point results (see "op" on page 59) 

or reorder instructions for best pipeline usage (see "or" on page 59) 

os favor code size over execution time in optimizations (see "os" on page 59) 

ot favor execution time over code size in optimizations (see "ot" on page 59) 

ou all functions must have unique addresses (see "ou" on page 59) 

ox equivalent to -obmiler -s (see "ox" on page 59) 

oz NULL points to valid memory in the target environment (see "oz" on page 59) 

2.2.11 C++ Exception Handling 

Option: Description: 

xd disable exception handling (default) (see "xd" on page 60) 

xdt disable exception handling (same as "xd") (see "xdt" on page 61) 

xds disable exception handling (table-driven destructors) (see "xds" on page 61) 

xs enable exception handling (see "xs" on page 61) 

xst enable exception handling (direct calls for destruction) (see "xst" on page 61) 

xss enable exception handling (table-driven destructors) (see "xss" on page 61) 

2.2.12 Doubie-Byte/Unicode Characters 

Option: Description: 

zk{0,1,2,1} double-byte char support: 0=Kanji,l=Chinese/Taiwanese,2=Korean,l=local (see 

"zk{0,1,2,1}" on page 61) 

zkOu translate double-byte Kanji to UNICODE (see "zkOu" on page 62) 

zku=<codepage> load UNICODE translate table for specified code page (see "zku=<codepage>" on page 
62) 
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2.2.13 Compatibility with Microsoft Visual C++ 

Option: Description: 

vc... VC++ compatibility options (see "vc..." on page 62) 

vcap allow alloca() or _alloca() in a parameter list 

2.2.14 Compatibility with Older Versions of the 80x86 Compilers 

Option: Description: 

r save/restore segment registers across calls (see "r" on page 63) 

fpr generate backward compatible 80x87 code (see "fpr" on page 63) 

zz generate backward compatible_stdcall conventions by removing the "@size" from 

_stdcall function names (10.0 compatible) (see "zz" on page 63) 

2.3 Compiler Options ■ Full Description 

In the following sections, we present complete descriptions of compiler options organized into categories. 

2.3.1 Target Specific 

This group of options deals with characteristics of the target application; for example, simple executables 
versus Dynamic Link Libraries, character-mode versus graphical user interface, single-threaded versus 
multi-threaded, and so on. 


(OS/2, Winl6/32 only) This option causes the compiler to emit into the object file references to the 
appropriate startup code for a character-mode console application. The presence of LibMain/DLLMain 
or WinMain/wWinMain in the source code does not influence the selection of startup code. Only main 
and wmain are significant. 

If none of "be", "bd", "bg" or "bw" are specified then the order of priority in determining which 
combination of startup code and libraries to use are as follows. 

1. The presence of one of LibMain or DLLMain implies that the DLL startup code and libraries 
should be used. 

2. The presence of WinMain or wWinMain implies that the GUI startup code and libraries should 
be used. 

3. The presence of main or wmain implies that the default startup code and libraries should be 
used. 

If both a wide and non-wide version of an entry point are specified, the "wide" entry point will be used. 
Thus wWinMain is called when both WinMain and wWinMain are present. Similarly, wmain is called 
when both main and wmain are present (and WinMain/wWinMain are not present). By default, if both 
wmain and WinMain are included in the source code, then the startup code will attempt to call 
wWinMain (since both "wide" and "windowed" entry points were included). 
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bd 

(OS/2, Winl6/32 only) This option causes the compiler to emit into the object file references to the 

run-time DLL startup code (reference to the_ DLLstart_ symbol) and, if required, special versions of 

the run-time libraries that support DLLs. The presence of main/wmain or WinMain/wWinMain in the 
source code does not influence the selection of startup code. Only LibMain and DLLMain are significant 
(see "be" on page 15). If you are building a DLL with statically linked C runtime (the default), it is 
recommended that you compile at least one of its object files with the "bd" switch to ensure that the DLL’s 
C runtime is properly initialized. The macro_ SW_ BD will be predefined if "bd" is selected. 

bg 

(OS/2, Winl6/32 only) This option causes the compiler to emit into the object file references to the 
appropriate startup code for a windowed (GUI) application. The presence of LibMain/DLLMain or 
main/wmain in the source code does not influence the selection of startup code. Only WinMain and 
wWinMain are significant (see "be" on page 15). 

bm 

(Netware, OS/2, Win32 only) This option causes the compiler to emit into the object file references to the 

appropriate multi-threaded library name(s). The macros _ MT and_ SW_ BM will be predefined if "bm" is 

selected. 

br 

(OS/2, Win32 only) This option causes the compiler to emit into the object file references to the run-time 
DLL library name(s). The run-time DLL libraries are special subsets of the Open Watcom C/C++ run-time 
libraries that are available as DLLs. When you use this option with an OS/2 application, you must also 

specify the "CASEEXACT" option to the Open Watcom Linker. The macros _ DLL and_ SW_ BR will be 

predefined if "br" is selected. 

bt[=<os>] 

This option causes the compiler to define the "build" target. This option is used for cross-development 
work. It prevents the compiler from defining the default build target (which is based on the host system the 
compiler is running on). The default build targets are: 

DOS when the host operating system is DOS, 

OS2 when the host operating system is OS/2, 

NT when the host operating system is Windows NT (including Windows 95), 

QNX when the host operating system is QNX. or 

LINUX when the host operating system is Linux. 

It also prevents the compiler from defining the default target macro. Instead the compiler defines a macro 
consisting of the string "<os>" converted to uppercase and prefixed and suffixed with two underscores. 

The default target macros are described in the section entitled "Open Watcom C/C++ Predefined Macros" 
on page 76. 

For example, specifying the option: 
bt=foo 
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would cause the compiler to define the macro 
_ FOO _ 


and prevent it from defining MSDOS, _ DOS and_ DOS _if the compiler was being run under DOS, 

_OS 2 _if using the OS/2 hosted compiler^ NT _if using the Windows NT or Windows 95 hosted 

compiler,_ QNX _and_ UNIX _if using the QNX hosted version. _or_ LINUX _and_ UNIX _if 

using the Linux hosted version. Any string consisting of letters, digits, and the underscore character may 
be used for the target name. 

The compiler will also construct an environment variable called <os>_INCLUDE and see if it has been 
defined. If the environment variable is defined then each directory listed in it is searched (in the order that 
they were specified). For example, the environment variable WINDOWS_INCLUDE will be searched if 
bt=WINDOWS option was specified. 

Example: 

set windows_ include=\watcom\h\win 


Include file processing is described in the section entitled "Open Watcom C/C++ #include File Processing" 
on page 72. 

Several target names are recognized by the compiler and perform additional operations. 

Target name Additional operation 

Defines the macros _ DOS andMSDOS. 


DOS 

WINDOWS 

NETWARE 

QNX 

LINUX 


Same as specifying one of the "zw" options. Defines the macros _ WINDOWS (16-bit 
only) and_ WINDOWS_ 38 6_(32-bit only). 

(32-bit only) Causes the compiler to use stack-based calling conventions. Also defines 
the macro_ NETWARE_ 386_. 

Defines the macro_ UNIX_. 

Defines the macro UNIX 


Specifying "bt" with no target name following restores the default target name. 


(Winl6 only) This option causes the compiler to import a special symbol so that the default windowing 
library code is linked into your application. The presence of LibMain/DLLMain in the source code does 
not influence the selection of startup code. Only main, wmain, WinMain and wWinMain are 
significant (see "be" on page 15). The macro_ SW_ BW will be predefined if "bw" is selected. 


This option selects the generation of traceable stack frames for those functions that contain calls or require 
stack frame setup. 

(16-bit only) To use Open Watcom’s "Dynamic Overlay Manager" (DOS only), you must compile all 
modules using one of the "of" or "of+" options ("of' is sufficient). 

For near functions, the following function prologue sequence is generated. 
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(16-bit only) 
push BP 
mov BP,SP 

(32-bit only) 
push EBP 
mov EBP,ESP 

For far functions, the following function prologue sequence is generated. 

(16-bit only) 
inc BP 
push BP 
mov BP,SP 

(32-bit only) 
inc EBP 
push EBP 
mov EBP,ESP 

The BP/EBP value on the stack will be even or odd depending on the code model. 

For 16-bit DOS systems, the Dynamic Overlay Manager uses this information to determine if the return 
address on the stack is a short address (16-bit offset) or long address (32-bit segment:offset). 

Do not use this option for 16-bit Windows applications. It will alter the code sequence generated for 
"_export" functions. 

Example: 

C>compiler_name toaster -of 
The macro_ SW_ OF will be predefined if "of" is selected. 


This option selects the generation of traceable stack frames for all functions regardless of whether they 
contain calls or require stack frame setup. This option is intended for developers of embedded systems 
(ROM-based applications). 

To use Open Watcom’s "Dynamic Overlay Manager" (16-bit DOS only), you must compile all modules 
using one of the "of" or "of+" options ("of" is sufficient). 

For near functions, the following function prologue sequence is generated. 

(16-bit only) 
push BP 
mov BP,SP 

(32-bit only) 
push EBP 
mov EBP,ESP 

For far functions, the following function prologue sequence is generated. 
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(16-bit only) 
inc BP 
push BP 
mov BP,SP 

(32-bit only) 
inc EBP 
push EBP 
mov EBP,ESP 

The BP/EBP value on the stack will be even or odd depending on the code model. 

For 16-bit DOS systems, the Dynamic Overlay Manager uses this information to determine if the return 
address on the stack is a short address (16-bit offset) or long address (32-bit segment:offset). 

Do not use this option for 16-bit Windows applications. It will alter the code sequence generated for 
"_export" functions. 

Example: 

C>compiler_name toaster -of+ 


This option is useful for 32-bit OS/2 and Win32 multi-threaded applications. It requests the code generator 
to emit a run-time call at the start of any function that has more than 4K bytes of automatic variables 
(variables located on the stack). 

Under 32-bit OS/2, the stack is grown automatically in 4K pages for any threads, other than the primary 
thread, using the stack "guard page" mechanism. The stack consists of in-use committed pages topped off 
with a special guard page. A memory reference into the 4K guard page causes the operating system to 
grow the stack by one 4K page and to add a new 4K guard page. This works fine when there is less than 
4K of automatic variables in a function. When there is more than 4K of automatic data, the stack must be 
grown in an orderly fashion, 4K bytes at a time, until the stack has grown sufficiently to accommodate all 
the automatic variable storage requirements. Hence the requirement for a stack-growing run-time routine. 
The stack-growing run-time routine is called_ GRO. 

The "stack=" linker option specifies how much stack is available and committed for the primary thread 
when an executable starts. The stack size parameter to _ beginthread () specifies how much stack is 
available for a child thread. The child thread starts with just 4k of stack committed. The stack will not 
grow to be bigger than the size specified by the stack size parameter. 

Under 32-bit Windows (Win32), the stack is grown automatically in 4K pages for all threads using a 
similar stack "guard page" mechanism. The stack consists of in-use committed pages topped off with a 
special guard page. The techniques for growing the stack in an orderly fashion are the same as that 
described above for OS/2. 

The "stack=" linker option specifies how much stack is available for the primary thread when an executable 
starts. The "commit stack=" linker directive specifies how much of that stack is committed when the 
executable starts. If no "commit stack=" directive is used, it defaults to the same value as the stack size. 

The stack size parameter to _ beginthread () specifies how much stack is committed for a child thread. 
If the size is set to zero, the size of the primary thread stack is used for the child thread stack. When the 
child thread executes, the stack space is not otherwise restricted. 

The macro_ SW_ SG will be predefined if "sg" is selected. 
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This option causes the code generator to ensure that the first reference to the stack in a function is to the 
stack "bottom" using the SS register. If the memory for this part of the stack is not mapped to the task, a 
memory fault will occur involving the SS register. This permits an operating system to allocate additional 
stack space to the faulting task. 

Suppose that a function requires 100 bytes of stack space. The code generator usually emits an instruction 
sequence to reduce the stack pointer by the required number of bytes of stack space, thereby establishing a 
new stack bottom. When the "st" option is specified, the code generator will ensure that the first reference 
to the stack is to a memory location with the lowest address. If a memory fault occurs, the operating 
system can determine that it was a stack reference (since the SS register is involved) and also how much 
additional stack space is required. 

See the description of the "sg" option for a more general solution to the stack allocation problem. The 
macro_ SW_ ST will be predefined if "st" is selected. 


(16-bit only) This option causes the compiler to generate the prologue/epilogue code sequences required for 
Microsoft Windows applications. The following "fat" prologue/epilogue sequence is generated for any 
functions declared to be "far _expoit" or "far pascal". 

far pascal func(...) 

far _ export func(...) 

far _ export pascal func (...) 


push 

DS 

pop 

AX 

nop 


inc 

BP 

push 

BP 

mov 

BP, SP 

push 

DS 

mov 

DS, AX 


pop DS 
pop BP 
dec BP 
retf n 

The macro_ WINDOWS _will be predefined if "zw" is selected. 

(32-bit only) This option causes the compiler to generate any special code sequences required for 32-bit 

Microsoft Windows applications. The macro_WINDOWS_and_ WINDOWS_ 38 6_will be 

predefined if "zw" is selected. 

zW (optimized) 

(16-bit only) This option is similar to "zw" but causes the compiler to generate more efficient 
prologue/epilogue code sequences in some cases. This option may be used for Microsoft Windows 
applications code other than user callback functions. Any functions declared as "far _export" will be 
compiled with the "fat" prologue/epilogue code sequence described under the "zw" option. 
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far _ export func(...) 

far _ export pascal func(...) 

The following "skinny" prologue/epilogue sequence is generated for functions that are not declared to be 
"far _export". 

far pascal func(...) 
far func (...) 

inc BP 
push BP 
mov BP,SP 


pop BP 
dec BP 
retf n 

The macro_ WINDOWS _will be predefined if "zW" is selected. 


zWs 

(16-bit only) This option is similar to "zW" but causes the compiler to generate "smart callbacks". This 
option may be used for Microsoft Windows user callback functions in executables only. It is not permitted 
for DLLs. Normally, a callback function cannot be called directly. You must use MakeProcInstance to 
obtain a function pointer with which to call the callback function. 

If you specify "zWs" then you do not need to use MakeProcInstance in order to call your own callback 
functions. Any functions declared as "far _export" will be compiled with the "smart" prologue code 
sequence described here. 

The following example shows the usual prologue code sequence that is generated when the "zWs" option is 
NOT used. 

Example: 

compiler_name winapp -me -bt=windows -dl 


short FAR PASCAL _export Functionl( short varl. 






long 

varlong, 





short 

var2 ) 

0000 

le 


FUNCTIONI 

push 

ds 

0001 

58 



pop 

ax 

0002 

90 



nop 


0003 

45 



inc 

b P 

0004 

55 



push 

b P 

0005 

89 

e5 


mov 

bp, sp 

0007 

le 



push 

ds 

0008 

8e 

d8 


mov 

ds, ax 


The following example shows the "smart" prologue code sequence that is generated when the "zWs" option 
is used. The assumption here is that the SS register contains the address of DGROUP. 
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Example: 

compiler_name winapp -me -bt=windows -dl -zWs 


short FAR PASCAL _export Functionl( short varl, 

long varlong, 
short var2 ) 


0000 

8c dO 

FUNCTIONl 

mov 

ax, ss 

0002 

45 


inc 

bp 

0003 

55 


push 

bp 

0004 

89 e5 


mov 

bp, sp 

0006 

le 


push 

ds 

0007 

00 

CD 

a 

00 


mov 

ds, ax 


2.3.2 Debugging/Profiling 

This group of options deals with all the forms of debugging information that can be included in an object 
file. Support for profiling of Pentium code is also described. 


dO 

(C++ only) No debugging information is included in the object file. 

dl 

Line number debugging information is included in the object file. This option provides additional 
information to the Open Watcom Debugger (at the expense of larger object files and executable files). Line 
numbers are handy when debugging your application with the Open Watcom Debugger at the source code 
level. Code speed is not affected by this option. To avoid recompiling, the Open Watcom Strip Utility can 
be used to remove debugging information from the executable image. 

d1+ 

(C only) Line number debugging information plus typing information for global symbols and local structs 
and arrays is included in the object file. Although global symbol information can be made available to the 
Open Watcom Debugger through a Open Watcom Linker option, typing information for global symbols 
and local structs and arrays must be requested when the source file is compiled. This option provides 
additional information to the Open Watcom Debugger (at the expense of larger object files and executable 
files). Code speed is not affected by this option. To avoid recompiling, the Open Watcom Strip Utility can 
be used to remove debugging information from the executable image. 

d2 

In addition to line number information, local symbol and data type information is included in the object 
file. Although global symbol information can be made available to the Open Watcom Debugger through a 
Open Watcom Linker option, local symbol and typing information must be requested when the source file 
is compiled. This option provides additional information to the Open Watcom Debugger (at the expense of 
larger object files and executable files). 

By default, the compiler will select the "od" level of optimization if "d2" is specified (see the description of 
the "od" option). Starting with version 11.0, the compiler now expands functions in-line where appropriate. 
This means that symbolic information for the in-lined function will not be available. 

The use of this option will make the debugging chore somewhat easier at the expense of code speed and 
size. To create production code, you should recompile without this option. 
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d2i 

(C++ only) This option is identical to "d2" but does not permit in-lining of functions. Functions are emitted 
as external out-of-line functions. This option can result in larger object and/or executable files than with 
"d2" (we are discussing both "code" and "file" size here). 

d2s 

(C++ only) This option is identical to "d2" but does not permit in-lining of functions. Functions are emitted 
as static out-of-line functions. This option can result in larger object and/or executable files than with "d2" 
or "d2i" (we are discussing both "code" and "file" size here). Link times are faster than "d2i" (fewer 
segment relocations) but executables are slightly larger. 

d2t 

(C++ only) This option is identical to "d2" but does not include type name debugging information. This 
option can result in smaller object and/or executable files (we are discussing "file" size here). 

d3 

This option is identical to "d2" but also includes symbolic debugging information for unreferenced type 
names. Note that this can result in very large object and/or executable files when header files like 
WINDOWS . H or OS 2 . H are included. 

d3i 

(C++ only) This option is identical to "d3" but does not permit in-lining of functions. Functions are emitted 
as external out-of-line functions. This option can result in larger object and/or executable files than with 
"d3" (we are discussing both "code" and "file" size here). 

d3s 

(C++ only) This option is identical to "d3" but does not permit in-lining of functions. Functions are emitted 
as static out-of-line functions. This option can result in larger object and/or executable files than with "d3" 
or "d3i" (we are discussing both "code" and "file" size here). Link times are faster than "d3i" (fewer 
segment relocations) but executables are slightly larger. 

ee 

This option causes the compiler to generate a call to_ EPI in the epilogue sequence at the end of every 

function. This user-written routine can be used to collect/record profiling information. Other related 
options are "ep[<number>]" and "en". The macro_ SW_ EE will be predefined if "ee" is selected. 

en 

The compiler will emit the function name into the object code as a string of characters just before the 
function prologue sequence is generated. The string is terminated by a byte count of the number of 
characters in the string. 

; void Toaster ( int arg ) 

db "Toaster", 7 

public Toaster 
Toaster label byte 


ret 
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This option is intended for developers of embedded systems (ROM-based applications). It may also be 
used in conjunction with the "ep" option for special user-written profiling applications. The macro 
_SW_ EN will be predefined if "en" is selected. 

ep[<number>] 

This option causes the compiler to generate a call to a user-written_ PRO routine in the prologue sequence 

at the start of every function. This routine can be used to collect/record profiling information. The optional 
argument <number> can be used to cause the compiler to allocate that many bytes on the stack as a place 

for_ PRO to store information. Other related options are "ee" on page 23 and "en" on page 23. The 

macro_SW_ EP will be predefined if "ep" is selected. 


(Pentium only) This option causes the compiler to generate code into the prolog of each function to count 
exactly how much time is spent within that function, in clock ticks. This option is valid only for Pentium 
compatible processors (i.e., the instructions inserted into the code do not work on 486 or earlier 
architectures). The Pentium "rdtsc" opcode is used to obtain the instruction cycle count. 

At the end of the execution of the program, a file will be written to the same location as the executable, 
except with a ".prf" extension. The contents of the file will look like this: 


Example: 


1903894223 

1785232334 

1882249150 

1830895850 

225730118 


1 main 

1376153 StageA 
13293 StageB 
2380 StageC 
99 StageD 


The first column is the total number of clock ticks spent inside of the function during the execution of the 
program, the second column is the number of times it was called and the third column is the individual 
function name. The total number of clock ticks includes time spent within functions called from this 
function. 


The overhead of the profiling can be somewhat intrusive, especially for small leaf functions (i.e., it may 
skew your results somewhat). 


h{w,d,c} 

The type of debugging information that is to be included in the object file is one of "Open Watcom", 
"DWARF" or "CodeView". The default is "DWARF". 

If you wish to use the Microsoft CodeView debugger, then choose the "he" option (this option causes 
CodeView Level 4 information to be generated). It will be necessary to run the Microsoft Debugging 
Information Compactor, CVPACK, on the executable once the linker has created it. For information on 
requesting the linker to automatically run CVPACK, see the section entitled "OPTION CVPACK" in the 
Open Watcom Linker User’s Guide. Alternatively, you can run CVPACK from the command line. 

When linking the application, you must also choose the appropriate Open Watcom Linker DEBUG 
directive. See the Open Watcom Linker User’s Guide for more information. 


Stack overflow checking is omitted from the generated code. By default, the compiler will emit code at the 
beginning of every function that checks for the "stack overflow" condition. This option can be used to 
disable this feature. The macro_ SW_ S will be predefined if "s" is selected. 
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2.3.3 Preprocessor 

This group of options deals with the compiler preprocessor. 

d<name>[=text] 

This option can be used to define a preprocessor macro from the command line. If =text is not specified, 
then 1 is assumed. In other words, specifying -dDBGON is equivalent to specifying -dDBGON=l on the 
command line. 

If = text is specified, then this option is equivalent to including the following line in your source code. 

#define name text 
Consider the following example. 

Example: 

d_ MODDATE="87.05.04" 

The above example is equivalent to a line in the source file containing: 

#define _ MODDATE "87.05.04" 


The syntax of any "d" option which follows on the command line is extended to include C/C++ tokens as 
part of "text". The token string is terminated by a space character. This permits more complex syntax than 
is normally allowed. 

Example: 

-d+ -d_ radx=x*3.1415926/180 
This is equivalent to specifying the following in the source code. 

Example: 

♦define _ radx x*3.1415926/180 

Open Watcom C++ extends this feature by allowing parameterized macros. When a parameter list is 
specified, the "=" character must not be specified. It also permits immediate definition of the macro as 
shown in the second line of the example. 

Example: 

-d+ -d_ rad(x)x*3.1415926/180 
-d+_ rad(x)x*3.1415926/180 

This is equivalent to specifying the following in the source code. 

Example: 

♦define _ rad(x) x*3.1415926/180 

fo[=<file_name>] (preprocessor) 

The "fo" option is used with any form of the "p" (preprocessor) option to name the output file drive, path, 
file name and extension. If the output file name is not specified, it is constructed from the source file name. 
If the output file extension is not specified, it is ",i" by default. 
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Example: 

C>compiler_rtame report -p -fo=d: \pro j\prep\ 

A trailing "\" must be specified for directory names. If, for example, the option was specified as 
f o=d: \pro j \prep then the output file would be called d: \pro j \prep. i. A default filename 
extension must be preceded by a period 

Example: 

C>compiler_name report -p -f o=d: \pro j\prep\ . cpr 


pil 

By default, #line directives embedded in source files are processed and will be used as a basis for file name 

and line number information in error messages,_FILE_and_LINE_symbols, etc. The "pil" option 

causes the preprocessor to ignore #line directives and refer to actual file names and line numbers. 

p{e,l,c,w=<num>} 

The input file is preprocessed and, by default, is written to the standard output file. The "fo" option may be 
used to redirect the output to a file with default extension ".i". 

Specify "pc" if you wish to include the original source comments in the Open Watcom C/C++ preprocessor 
output file. 

(C++ Only) Specify "pe" if you wish to encrypt the original identifiers when they are written to the Open 
Watcom C/C++ preprocessor output file. 

Specify "pi" if you wish to include #line directives. 

Specify "pci" or "pic" if you wish both source comments and #line directives. 

Use the "w=<num>" suffix if you wish to wish output lines to wrap at <num> columns. Zero means no 
wrap. 

Example: 

C>compiler_name report -pcelw=80 

The input file is preprocessed only. When only "p" is specified, source comments and #line directives are 
not included. You must request these using the "c" and "1" suffixes. When the output of the preprocessor is 
fed into the compiler, the #line directive enables the compiler to issue diagnostics in terms of line 
numbers of the original source file. 

The options which are supported when the Open Watcom C/C++ preprocessor is requested are: "d", "fi", 
"fo", "i", "m?", and "u". 


u<name> 

The "u" option may be used to turn off the definition of a predefined macro. If no name is specified then all 
predefined macros are undefined. 

Example: 

C>compiler_name report -uM_ 138 6 
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2.3.4 Diagnostics 

This group of options deals with the control of compiler diagnostics. 


e<number> 

The compiler will stop compilation after reaching <number> errors. By default, the compiler will stop 
compilation after 20 errors. 


ef 


This option causes the compiler to display full path names for files in error messages. 


eq 


This option causes the compiler to not display error messages on the console; however, they are still written 
to a file (see "fr[=<file_name>]" on page 34). 


er 


ew 


(C++ only) This option causes the C++ compiler to not recover from undefined symbol errors. By default, 
the compiler recovers from "undefined symbol" errors by injecting a special entry into the symbol table that 
prevents further issuance of diagnostics relating to the use of the same name. Specify the "er" option if you 
want all uses of the symbol to be diagnosed. 


Example: 


struct S 

} ; 

{ 



void foo1 

: S *p ) 

{ 


p->m 

= 1; // 

member 'm' has not been 

declared in 

} 

void bar I 

: S *p ) 

{ 


p->m 

= 2; // 

no error unless "er" is 

specified 


} 


(C++ only) This option causes the C++ compiler to generate equivalent but less verbose diagnostic 
messages. 


q 


This option is equivalent to the "zq" option (see "zq" on page 31). 


t=<num> 

(C++ only) The "t" option is used to set the tab stop interval. By default, the compiler assumes a tab stop 
occurs at multiples of 8 (1+n x 8 = 1, 9, 17, ... for n=0, 1, 2, ...). When the compiler reports a line number 
and column number in a diagnostic message, the column number has been adjusted for intervening tabs. If 
the default tab stop setting for your text editor is not a multiple of 8, then you should use this option. 

Example: 

C>compiler_name report -t=4 
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w<number> 

The compiler will issue only warning type messages of severity <number> or below. Type 1 warning 
messages are the most severe while type 3 warning messages are the least severe. Specify "wO" to prevent 
warning messages from being issued. Specify "wx" to obtain all warning messages. 


wcd=<number> 

The compiler will not issue the warning message indicated by <number>. 


wce=<number> 

The compiler will issue the warning message indicated by <number> despite any pragmas that may have 
disabled it. 


we 

By default, the compiler will continue to create an object file when there are warnings produced. This 
option can be used to treat all warnings as errors, thereby preventing the compiler from creating an object 
file if there are warnings found within a module. 

WO 

(C only ) (16-bit only) This option tells the compiler to emit warnings for things that will cause problems 
when compiling code for use in overlays. 

WX 

This option sets the warning level to its maximum setting. 

za 

This option helps to ensure that the module to be compiled conforms to the ISO/ANSI C or C++ 
programming language specification (depending on the compiler which is selected). The macro 
N0_ EXT_ KEYS (no extended keywords) will be predefined if "za" is selected. The "ou" option will be 
enabled (see "ou" on page 59). This option also suppress all predefined macros which name is not 
ISO/ANSI C/C++ standard compliant. See also the description of the "ze" option. 

When using the C compiler, there is an exception to the enforcement of the ISO C standard programming 
language specification. The use of C++ style comments (// comment) are not diagnosed. 

ze 

The "ze" option (default) enables the use of the following compiler extensions: 

1. The requirement for at least one external definition per module is relaxed. 

2. When using the C compiler, some forgiveable pointer type mismatches become warnings instead 
of errors. 

3. In-line math functions are allowed (note that errno will not be set by in-line functions). 

4. When using the C compiler, anonymous structs/unions are allowed (this is always permitted in 
C++). 
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Example: 

struct { 
int a; 
union { 

int b; 
float alt_ b; 

} ; 

int c; 

} x; 

In the above example, "x.b" is a valid reference to the "b" field. 

5. For C only, ISO function prototype scope rules are relaxed to allow the following program to 
compile without any errors. 

Example: 

void foo ( struct a * _p ); 

struct a { 
int b; 
int c; 

} ; 

void bar( void ) 

{ 

struct a x; 
foo( &x ); 

} 

According to a strict interpretation of the ISO C standard, the function prototype introduces a 
new scope which is terminated at the semicolon (;). The effect of this is that the structure tag "a" 
in the function "foo" is not the same structure tag "a" defined after the prototype. A diagnostic 
must be issued for a conforming ISO C implementation. 

6. A trailing comma (,) is allowed after the last constant in an enum declaration. 

Example: 

enum colour { RED, GREEN, BLUE, } ; 

7. The ISO requirement that all enums have a base type of int is relaxed. The motivation for this 
extension is conservation of storage. Many enums can be represented by integral types that are 
smaller in size than an int. 

Example: 

enum colour { RED, GREEN, BLUE, } ; 

void foo( void ) 

{ 

enum colour x; 
x = RED ; 

} 

In the example, "x" can be stored in an unsigned char because its values span the range 0 to 2. 
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8. The ISO requirement that the base type of a bitfield be int or unsigned is relaxed. This allows a 
programmer to allocate bitfields from smaller units of storage than an int (e.g., unsigned char). 

Example: 

struct { 


unsigned 

char a 

i; 

unsigned 

char b 

i; 

unsigned 

char c 

i; 

} x; 



struct { 



unsigned 

a : 1; 


unsigned 

b : 1; 


unsigned 

c : 1; 



} y; 


In the above example, the size of "x" is the same size as an unsigned char whereas the size of "y" 
is the same size as an unsigned int. 

9. Enable all predefined macros which name is not ISO/ANSI C/C++ compliant. The following 
macros are defined. 

_ near, near 

_ far, far, SOMDLINK (16-bit) 

_ huge, huge 
_ based 
_segment 
_ segname 
_ self 

_ cdecl, cdecl, SOMLINK (16-bit) 

_ pascal, pascal 
_ fastcall 
_ fortran, fortran 
_ inline 

_ interrupt, interrupt 
_ export 
_ loadds 
_saveregs 
_stdcall 

_ syscall, SOMLINK (32-bit), SOMDLINK (32-bit) 

_ farl6 

See also the description of the "za" option. 


zq 

The "quiet mode" option causes the informational messages displayed by the compiler to be suppressed. 
Normally, messages are displayed identifying the compiler and summarizing the number of lines compiled. 
As well, a dot is displayed every few seconds while the code generator is active, to indicate that the 
compiler is still working. These messages are all suppressed by the "quiet mode" option. Error and 
warning messages are not suppressed. 

zs 

The compiler will check the source code only and omit the generation of object code. Syntax checking, 
type checking, and so on are performed as usual. 
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2.3.5 Source/Output Control 

This group of options deals with control over the input files and output files that the compiler processes 
and/or creates. 

ad[=<fiie_name>] 

This option enables generation of automatic dependency infomation in makefile format, as a list of targets 
and their dependents. If the name of the automatic dependency file is not specified, it is constructed from 
the source file name. If the dependency extension is not specified, it is ".d" by default. 

Example: 

C>compiler_name report -ad=d: \pro j\ob j\ 

A trailing "\" must be specified for directory names. If, for example, the option was specified as 
f o=d: \pro j \ ob j then the dependency file will be called d: \pro j \ ob j . d. 

A default filename extension must be preceded by a period 

Example: 

C> compiler_name report -ad=d: \pro j\obj\. dep 
The content of the generated file has the following format: 

Example: 

<targetname>:<input source file> <included header files...> 

Note that the header files listed in the dependency file normally do not include the standard library headers. 


adbs 

When generating make style automatic dependency files, this option forces all path separators ("/" or "\") to 
be a backslash ("\"). Certain usage may result in mixed path separators; this options helps generating 
automatic dependency information in a format appropriate for the make tool used. 

add[=<file_name>] 

Set the first dependency name in a make style automatic dependency file. By default, the name of the 
source file to be compiled is used, (see "ad|=<file_name>]" on page 31) 

adhp[=<path_name>] 

When including a file with "" delimiters, the resulting filename in make style automatic dependency files 
will have no path. This option allows such files to be given a path; said path may be relative. The 
path_name argument is directly prepended to the filename, therefore a trailing path separator must be 
specified. 

This issue only affects headers found in the current directory, that is, the directory current at the time of 
compilation. If a header is located in an including file’s directory, it will automatically receive a path. 

This option is useful in situations where the current directory at the time when the automatic dependency 
information is evaluated is not the same as the current directory at the time of compilation (i.e., when the 
automatic dependency information was generated). 
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adfs 

When generating make style automatic dependency files, this option forces all path separators ("/" or "\") to 
be a forward slash ("/"). Certain usage may result in mixed path separators; this options helps generating 
automatic dependency information in a format appropriate for the make tool used. 

adt[=<target_name>] 

This option enables generation of automatic dependency infomation in the form of a makefile. The target 
in the makefile can be specified. If the automatic dependency target is not specified through this option, it 
is constructed from the source file name. If the target extension is not specified, it is ".obj" by default. 

Example: 

C>compiler_name report -adt=d: \pro j\ob j\ 

A trailing "\" must be specified for directory names. If, for example, the option was specified as 
f o=d: \pro j \ob j then the dependency file would be called d:\proj\obj.obj. 

A default filename extension must be preceded by a period 

Example: 

C>compiler_name report -adt=d: \pro j\obj\.dep 
The generated file has the following contents: 

Example: 

<targetname>:<input source file> <included header files...> 

Note that the header files listed in the dependency file normally do not include the standard library headers. 


db 

Use this option to generate browsing information. The browsing information is recorded in a file whose 
name is constructed from the source file name and the extension ".mbr". 

ez 

(32-bit only) The compiler will generate an object file in Phar Lap Easy OMF-386 (object module format) 
instead of the default Microsoft OMF. The macro_SW_ EZ will be predefined if "ez" is selected. 

fc=<file_name> 

(C++ only) The specified "batch" file contains a list of command lines to be processed. This enables the 
processing of a number of source files together with options for each file with one single invocation of the 
compiler. Only one "fc" option is allowed and no source file names are permitted on the command line. 

Example: 

[batch.txt] 

main -onatx -zp4 

parti part2 -onatx -zp4 -dl 

part3 -onatx -zp4 -d2 

C >compiler_name -fc=\watcom\h\batch. txt 

Each line in the file is treated stand-alone. In other words, the options from one line do not carry over to 
another line. However, any options specified on the command line or the associated compiler environment 
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variable will carry over to the individual command lines in the batch file. When the compiler diagnoses 
errors in a source file, processing of subsequent command lines is halted unless the "k" option was specified 
(see "k" on page 36). 

fh[q][=<file_name>] 

The compiler will generate/use a precompiled header for the first header file referenced by ((include in 
the source file. See the chapter entitled "Precompiled Headers" on page 101 for more information. 


fhd 

The compiler will store debug info for the pre-compiled header once (DWARF only). See the chapter 
entitled "Precompiled Headers" on page 101 for more information. 

fhr 

(C++ only) This option will force the compiler to read the pre-compiled header if it appears to be 
up-to-date; otherwise, it will read the header files included by the source code. It will never write the 
pre-compiled header (even when it is out-of-date). See the chapter entitled "Precompiled Headers" on page 
101 for more information. 

fhw 

(C++ only) This option will force the compiler to write the pre-compiled header (even when it appears to 
be up-to-date). See the chapter entitled "Precompiled Headers" on page 101 for more information. 

fhwe 

(C++ only) This option will ensure that pre-compiled header warnings are not counted as errors when the 
"we" (treat warnings as errors) option is specified. 


fi=<file_name> 

The specified file is included as if a 
♦include "<file_ name>" 
directive were placed at the start of the source file. 

Example: 

C>compiler_name report -f i=\watcom\h\stdarg. h 

fo[=<file_name>] 

When generating an object file, the "fo" option may be used to name the object file drive, path, file name 
and extension. If the object file name is not specified, it is constructed from the source file name. If the 
object file extension is not specified, it is ".obj" by default. 

Example: 

C>compiler_name report -fo=d: \pro j\ob j\ 

A trailing "\" must be specified for directory names. If, for example, the option was specified as 
f o=d: \pro j \ ob j then the object file would be called d: \pro j \ob j .obj. 

A default filename extension must be preceded by a period ("."). 
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Example: 

C>compiler_name report -fo=d: \pro j\obj\.dbo 

fr[=<file_name>] 

The "fr" option is used to name the error file drive, path, file name and extension. If the error file name is 
not specified, it is constructed from the source file name. If the output file extension is not specified, it is 
".err" by default. If no part of the name is specified, then no error file is produced (i.e., -fr disables 
production of an error file). 

Example: 

C>compiler_name report -fr=d: \pro j\errs\ 

A trailing "\" must be specified for directory names. If, for example, the option was specified as 
f r=d: \pro j \ errs then the output file would be called d: \pro j \ errs .err. A default filename 
extension must be preceded by a period 

Example: 

C>compiler_name report -fr=d: \pro j\errs\.erf 


ft 

(C++ only) If the compiler cannot open a header file whose file name is longer than 8 letters or whose file 
extension is longer than 3 letters, it will truncate the name at 8 letters and the extension at 3 letters and try 
to open a file with the shortened name. This is the default behaviour for the compiler. 

For example, if the compiler cannot open the header file called strstream. h, it will attempt to open a 
header file called strstrea . h . 

fti 

(C only) Whenever a file is open as a result of #include directive processing, an informational message 
is printed. The message contains the file name and line number identifying where the ((include directive 
was located. 

fx 

(C++ only) This option can be used to disable the truncated header filename processing that the compiler 
does by default (see "ft" above). 

fzh 

(C++ only) This option can be used to stop the compiler from automatically adding extensions to include 
files. The default behaviour of the compiler is to search for the specified file, then to try known extensions 
if the file specifier does not have an extension. Thus, ((include <string> could be matched by ’string’, 

’string.h’ or ’string.hpp’ (see "fzs" below). The macro_ SW_ FZH will be defined when this switch is 

used. 

fzs 

(C++ only) This option can be used to stop the compiler from automatically adding extensions to source 
files. The default behaviour of the compiler is to search for the specified file, then to try known extensions 
if the file specifier does not have an extension. Thus, ’src_file’ could be matched by ’src_file’, 

’src_file.cpp’ or ’src_file.cc’ (see "fzh" above). The macro_ SW_ FZS will be defined when this switch is 

used. 
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i=<directory> 

where "<directory>" takes the form 
[d:]path;[d:]path... 

The specified paths are added to the list of directories in which the compiler will search for "include" files. 
See the section entitled "Open Watcom C/C++ #include File Processing" on page 72 for information on 
directory searching. 


k 

(C++ only) This option instructs the compiler to continue processing subsequent source files after an error 
has been diagnosed in the current source file. See the option "fc=<file_name>" on page 32 for information 
on compiling multiple source files. 

V 

Open Watcom C will output function declarations to a file with the same filename as the C source file but 
with extension ".def". The "definitions" file may be used as an "include" file when compiling other 
modules in order to take advantage of the compiler’s function and argument type checking. 

X 

The compiler ignores the INCLUDE and <os>_INCLUDE environment variables, if they exist, when 
searching for include files. See the section entitled "Open Watcom C/C++ #include File Processing" on 
page 72 for information on directory searching. 

XX 

The compiler behaviour for file search changes following way: 

• current directory is ignored when searching for include files 

• adjacent . . \h directory is ignored when searching for include files 

• don't do recursive search for parent directories when searching for include files 

• adjacent . . \ c directory is ignored when searching for source file 

See the section entitled "Open Watcom C/C++ #include File Processing" on page 72 for information on 
directory searching. 

zam 

Open Watcom define many extension macros for compatibility with old MS C compiler (far, _far, near, 
_near, cdecl, _cdecl, etc.). For details see Open Watcom compilers predefined macros. These macros use 
names which are not ISO C/C++ compliant. The option disables all these predefined macros. 

zat 

ISO C++ defines a number of alternative tokens that can be used instead of certain traditional tokens. For 
example "and" instead of "&&", "or" instead of "II", etc. See section 2.5 of the ISO C++ 98 standard for the 
complete list of such tokens. The "zat" option disables support for these tokens so that the names "and", 
"or", etc are no longer reserved. 
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zf 


Starting with Open Watcom 1.3, the scope of a variable declared in the initialization expression of a for 
loop header is by default limited to the body of the loop. This is in accordance with the ISO C++ standard. 
The "zf" option causes the compiler to revert to the behavior it had before Open Watcom 1.3. In particular, 
it causes the scope of variables declared in the initialization expression of a for loop header to extend 
beyond the loop. 


Example: 

♦include <iostream> 


void f() 

{ 

for( int i = 0; i < 10; ++i 
std::cout << i << "\n"; 

} 

std::cout << "Value of i at 


) 1 

loop termination: 


" « i « " \n"; 


The above code will not compile with Open Watcom 1.3 or later because the variable "i" is out of scope in 
the last output statement. The "zf" option will allow such code to compile by extending the scope of "i" 
beyond the loop. 


The "zg" option is similar to the "v" option except that function declarations will be output to the "DEF" 
file using base types (i.e., typedefs are reduced to their base type). 

Example: 

typedef unsigned int UINT; 

UINT f( UINT x ) 

{ 

return( x + 1 ) ; 

} 

If you use the "v" option, the output will be: 

extern UINT f (UINT ) ; 

If you use the "zg" option, the output will be: 

extern unsigned int f(unsigned int ); 


By default, the compiler places in the object file the names of the C libraries that correspond to the memory 
model and floating-point options that were selected. The Open Watcom Linker uses these library names to 
select the libraries required to link the application. If you use the "zl" option, the library names will not be 
included in the generated object file. 

The compiler may generate external references for library code that conveniently cause the linker to link in 
different code. One such case is: if you have any functions that pass or return floating-point values (i.e., 
float or double), the compiler will insert an external reference that will cause the floating-point formatting 
routines to be included in the executable. The "zl" option will disable these external references. 

Use this option when you wish to create a library of object modules which do not contain Open Watcom 
C/C++ library name references. 
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zld 

By default, the compiler places in the object file the names and time stamps of all the files referenced by the 
source file. This file dependency information can then be used by WMAKE to determine that this file 
needs to be recompiled if any of the referenced files has been modified since the object file was created. 
This option causes the compiler to not emit this information into the object file. 

zlf 

The "zlf" option tells the compilers to emit references for all default library information into the compiled 
object file. See also the options "zl", "zld" and "zls". 

zls 

The "zls" option tells the compilers to remove automatically inserted symbols. These symbols are usually 
used to force symbol references to be fixed up from the run-time libraries. An example would be the 

symbol_DLLstart_, that is inserted into any object file that has a DllMain() function defined within its 

source file. 

2.3.6 Code Generation 

This group of options deals with controlling some aspects of the code that is generated by the compiler. 

ecc 

set default calling convention to_cdecl 

ecd 

set default calling convention to_stdcall 

ecf 

set default calling convention to_fastcall 

ecp 

set default calling convention to_pascal 

ecr 

set default calling convention to_fortran 

ecs 

set default calling convention to_syscall 

ecw 

set default calling convention to_watcall (default) 

ei 

This option can be used to force the compiler to allocate at least an "int" for all enumerated types. The 
macro_SW_ EI will be predefined if "ei" is selected. 


Compiler Options - Full Description 37 




Open Watcom C/C++ User’s Guide 


em 

This option can be used to force the compiler to allocate the smallest storage unit required to hold all 
possible values given for an enumerated list. This option is the default for the x86 architecture. The macro 
_SW_ EM will be predefined if "em" is selected. 

i 

The default char type is changed from an unsigned to a signed quantity. The macros 
_CHAR_ SIGNED_and SW_ J will be predefined if "j" is selected. 

ri 

Functions declared to return integral types such as chars and shorts are promoted to returning ints. This 
allows non-ISO-conforming source code which does not properly declare the return types of functions to 
work properly. The use of this option should be avoided. 

xr 

The "xr" option is used to to enable the use of the C++ feature called Run-Time Type Information (RTTI). 
RTTI can only be used with classes that have virtual functions declared. This restriction implies that if you 
enable RTTI, the amount of storage used for a class in memory does not change. The RTTI information is 
added to the virtual function information block so there will be an increase in the executable size if you 
choose to enable RTTI. There is no execution penalty at all unless you use the dynamic_cast<> feature in 
which case, you should be aware that the operation requires a lookup operation in order to perform the 
conversion properly. You can mix and match modules compiled with and without "xr", with the caveat that 
dynamic_cast<> and typcidO may not function (return NULL or throw an exception) if used on a class 
instance that was not compiled with the "xr" option. 

zc 

The "zc" option causes the code generator to place literal strings and const items in the code segment. 
Example: 

extern const int cvar = 1; 
int var = 2; 

const int ctable[ 5 ] = { 1, 2, 3, 4, 5 } ; 
char *birds[ 3 ] = { "robin", "finch", "wren" }; 

In the above example, cvar and ctable and the strings "robin" , "finch" , etc. are placed in the 
code segment. This option is supported in large data or flat memory models only, or if the item is explicitly 
"far". The macro_SW_ ZC will be predefined if "zc" is selected. 

zp[{1,2,4,8,16}] 

The "zp" option allows you to specify the alignment of members in a structure. The default is "zp2" for the 
16-bit compiler and "zp8" for 32-bit compiler. The alignment of structure members is described in the 
following table. If the size of the member is 1, 2, 4, 8 or 16, the alignment is given for each of the "zp" 
options. If the member of the structure is an array or structure, the alignment is described by the row "x". 
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sizeof(member) 
1 
2 
4 
8 

16 

x 


\ 


zpl zp2 zp4 zp8 


0 

0 

0 

0 

0 


0 

2 

2 

2 

2 


0 

2 

4 

4 

4 


0 

2 

4 

8 

8 


aligned to largest member 


zpl 6 


0 

2 

4 

8 

16 


An alignment of 0 means no alignment, 2 means word boundary, 4 means doubleword boundary, etc. 

Note that packed structures are padded to ensure that consecutive occurrences of the same structure in 
memory are aligned appropriately. This is illustrated when the following example is compiled with "zp4". 
The amount of padding is determined as follows. If the largest member of structure "s" is 1 byte then "s" is 
not aligned. If the largest member of structure "s" is 2 bytes then "s" is aligned according to row 2. If the 
largest member of structure "s" is 4 bytes then "s" is aligned according to row 4. If the largest member of 
structure "s" is 8 bytes then "s" is aligned according to row 8. At present, there are no scalar objects that 
can have a size of 16 bytes. If the largest member of structure "s" is an array or structure then "s" is aligned 
according to row "x". Padding is the inclusion of slack bytes at the end of a structure in order to guarantee 
the alignment of consecutive occurrences of the same structure in memory. 

To understand why structure member alignment may be important, consider the following example. 


Example: 

♦include <stdio.h> 
♦include <stddef.h> 


typedef struct memo_ el { 

char date[9]; 

struct memo_ el *prev,*next; 
int ref_ number; 

char sex; 

} memo; 


void main ( ) 


printf( 

"Offset 

of %s is %d\n". 


"date", 

offsetof( memo, date ) ) ; 

printf( 

"Offset 

of %s is %d\n". 


"prev", 

offsetof( memo, prev ) ) ; 

printf( 

"Offset 

of %s is %d\n". 


"next", 

offsetof( memo, next ) ) ; 

printf( 

"Offset 

of %s is %d\n". 


"ref_ number", offsetof ( memo, ref_ number 

printf( 

"Offset 

of %s is %d\n". 


" sex ", 

offsetof( memo, sex ) ) ; 

printf( 

"Size of %s is %d\n". 


"memo", 

sizeof( memo ) ) ; 

printf( 

"Number 

of padding bytes is %d\n". 


sizeof( 

memo ) 


- (offsetof ( memo, sex ) + sizeof ( char )) ); 


Compiler Options - Full Description 39 






Open Watcom C/C++ User’s Guide 


In the above example, the default alignment "zp8" will cause the pointer and integer items to be aligned on 
even addresses although the array "date" is 9 bytes in length. The items are 2-byte aligned when 
sizeof(item) is 2 and 4-byte aligned when sizeoflitem) is 4. 

On computer systems that have a 16-bit (or 32-bit) bus, improved performance can be obtained when 
pointer, integer and floating-point items are aligned on an even boundary. This could be done by careful 
rearrangement of the fields of the structure or it can be forced by use of the "zp" option. 

16-bit output when compiled zpl: 

Offset of date is 0 

Offset of prev is 9 

Offset of next is 11 

Offset of ref_ number is 13 

Offset of sex is 15 

Size of memo is 16 

Number of padding bytes is 0 

16-bit output when compiled zp4: 

Offset of date is 0 

Offset of prev is 10 

Offset of next is 12 

Offset of ref_ number is 14 

Offset of sex is 16 

Size of memo is 18 

Number of padding bytes is 1 

32-bit output when compiled zpl: 

Offset of date is 0 

Offset of prev is 9 

Offset of next is 13 

Offset of ref_ number is 17 

Offset of sex is 21 

Size of memo is 22 

Number of padding bytes is 0 

32-bit output when compiled zp4: 

Offset of date is 0 

Offset of prev is 12 

Offset of next is 16 

Offset of ref_ number is 20 

Offset of sex is 24 

Size of memo is 28 

Number of padding bytes is 3 


zpw 

The compiler will output a warning message whenever padding is added to a struct/class for alignment 
purposes. 

zt<number> 

The "data threshold" option is used to set the maximum size for data objects to be included in the default 
data segment. This option can be used with the compact, large, and huge (16-bit) memory models only. 
These are memory models where there can be more than one data segment. Normally, all data objects 
whose size is less than or equal to the threshold value are placed in the default data segment "_DATA" 
unless they are specifically declared to be far items. When there is a large amount of static data, it is 
often useful to set the data threshold size so that all objects larger than this size are placed in another (far) 
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data segment. For example, the option "ztlOO" causes all data objects larger than 100 bytes in size to be 
implicitly declared as far and grouped in other data segments. 

The default data threshold value is 32767. Thus, by default, all objects greater than 32767 bytes in size are 
implicitly declared as far and will be placed in other data segments. If the "zt" option is specified without 
a size, the data threshold value is 256. The largest value that can be specified is 32767 (a larger value will 
result in 256 being selected). 

If the "zt" option is used to compile any module in a program, then you must compile all the other modules 
in the program with the same option (and value). 

Care must be exercised when declaring the size of objects in different modules. Consider the following 
declarations in two different C files. Suppose we define an array in one module as follows: 

extern int Array[100] = { 0 }; 

and, suppose we reference the same array in another module as follows: 

extern int Array[10]; 

Assuming that these modules were compiled with the option "ztlOO", we would have a problem. In the first 
module, the array would be placed in another segment since Array [100] is bigger than the data 
threshold. In the second module, the array would be placed in the default data segment since Array [10] 
is smaller than the data threshold. The extra code required to reference the object in another data segment 
would not be generated. 

Note that this problem can also occur even when the "zt" option is not used (i.e., for objects greater than 
32767 bytes in size). There are two solutions to this problem: (1) be consistent when declaring an object’s 
size, or, (2) do not specify the size in data reference declarations. 


ZV 

(C++ only) Enable virtual function removal optimization. 

2.3.780x86 Floating Point 

This group of options deals with control over the type of floating-point instructions that the compiler 
generates. There are two basic types — floating-point calls (FPC) or floating-point instructions (FPI). 
They are selectable through the use of one of the compiler options described below. You may wish to use 
the following list when deciding which option best suits your requirements. Here is a summary of 
advantages/disadvantages to both. 

FPC 


1. not IEEE floating-point 

2. not tailorable to processor 

3. uses coprocessor if present; simulates otherwise 

4. 32-bit/64-bit accuracy 

5. runs somewhat faster if coprocessor present 

6. faster emulation (fewer bits of accuracy) 

7. leaner "math" library 

8. fatter application code (calls to library rather than in-line instructions) 

9. application cannot trap floating-point exceptions 

10. ideal for ROM applications 
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FPI, FPI87 


1. IEEE floating-point 

2. tailorable to processor (see fp2, fp3, fp5, fp6) 

3. uses coprocessor if present; emulates IEEE otherwise 

4. up to 80-bit accuracy 

5. runs "full-tilt" if coprocessor present 

6. slower emulation (more bits of accuracy) 

7. fatter "math" library 

8. leaner application code (in-line instructions) 

9. application can trap floating-point exceptions 

10. ideal for general-purpose applications 

To see the difference in the type of code generated, consider the following small example. 
Example: 

♦include <stdio.h> 

♦include <time.h> 

void main() 

{ 

clock_ t cstart, cend; 
cstart = clock (); 

/* 


*/ 

cend = clock (); 

printf ( "%4.2f seconds to calculate\n", 



The following 32-bit code is generated by the Open Watcom C compiler (wcc386) using the "fpc" option. 


push 

ebx 



push 

edx 



call 

clock_ 



mov 

edx,eax 



call 

clock_ 



call 

_ U4FS ; 

unsigned 

4 to floating single 

mov 

ebx,eax 



mov 

eax,edx 



call 

_ U4FS ; 

unsigned 

4 to floating single 

mov 

edx,eax 



mov 

eax,ebx 



call 

_FSS ; 

floating 

single subtract 

mov 

edx,3c23d70aH 


call 

_FSM ; 

floating 

single multiply 

call 

_ FSFD ; 

floating 

single to floating double 

push 

edx 



push 

eax 



push 

offset LI 



call 

printf_ 



add 

esp,OOOOOOOcH 


pop 

edx 



pop 

ebx 



ret 





The following 32-bit code is generated by the Open Watcom C compiler (wcc386) using the "fpi" option. 
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push 

ebx 


push 

edx 


sub 

esp,00000010H 


call 

clock_ 


mov 

edx,eax 


call 

clock_ 


xor 

ebx,ebx 


mov 

[esp],eax 


mov 

+4H[esp],ebx 


mov 

+8H[esp],edx 


mov 

+0cH[esp],ebx 


fild 

qword ptr [esp] 

; integer to double 

fild 

qword ptr +8H[esp] 

; integer to double 

f subp 

st(1),St 

; subtract 

fmul 

dword ptr L2 

; multiply 

sub 

esp,00000008H 


f stp 

qword ptr [esp] 

; store into memory 

push 

offset LI 


call 

printf_ 


add 

esp,OOOOOOOcH 


add 

esp,00000010H 


pop 

edx 


pop 

ebx 


ret 




fpc 

All floating-point arithmetic is done with calls to a floating-point emulation library. If a numeric data 
processor is present in the system, it will be used by the library; otherwise floating-point operations are 
simulated in software. This option should be used for any of the following reasons: 

1. Speed of floating-point emulation is favoured over code size. 

2. An application containing floating-point operations is to be stored in ROM and an 80x87 will not 
be present in the system. 

The macro_ SW_ FPC will be predefined if "fpc" is selected. 


Note: When any module in an application is compiled with the "fpc" option, then all modules must be 
compiled with the "fpc" option. 

Different math libraries are provided for applications which have been compiled with a particular 
floating-point option. See the section entitled "Open Watcom C/C++ Math Libraries" on page 109. 


See the section entitled "The N087 Environment Variable" on page 111 for information on testing the 
floating-point simulation code on personal computers equipped with a coprocessor. 

fpi 

(16-bit only) The compiler will generate in-line 80x87 numeric data processor instructions into the object 
code for floating-point operations. Depending on which library the code is linked against, these 
instructions will be left as is or they will be replaced by special interrupt instructions. In the latter case, 
floating-point will be emulated if an 80x87 is not present. This is the default floating-point option if none 
is specified. 

(32-bit only ) The compiler will generate in-line 387-compatible numeric data processor instructions into 
the object code for floating-point operations. When any module containing floating-point operations is 
compiled with the "fpi" option, coprocessor emulation software will be included in the application when it 
is linked. 
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For 32-bit Open Watcom Windows-extender applications or 32-bit applications run in Windows 3.1 DOS 
boxes, you must also include the WEMU387.386 file in the [386enh] section of the SYSTEM. INI file. 

Example: 

device=C:\WATCOM\binw\wemu387.386 

Note that the WDEBUG .386 file which is installed by the Open Watcom Installation software contains the 
emulation support found in the WEMU3 8 7.386 file. 

Thus, a math coprocessor need not be present at run-time. This is the default floating-point option if none 
is specified. The macros_ FPI _and_ SW_ FPI will be predefined if "fpi" is selected. 


Note: When any module in an application is compiled with a particular "floating-point" option, then all 
modules must be compiled with the same option. 

If you wish to have floating-point emulation software included in the application, you should select the 
"fpi" option. A math coprocessor need not be present at run-time. 

Different math libraries are provided for applications which have been compiled with a particular 
floating-point option. See the section entitled "Open Watcom C/C++ Math Libraries" on page 109. 


See the section entitled "The N087 Environment Variable" on page 111 for information on testing the math 
coprocessor emulation code on personal computers equipped with a coprocessor. 


fp\87 

(16-bit only) The compiler will generate in-line 80x87 numeric data processor instructions into the object 
code for floating-point operations. An 8087 or compatible math coprocessor must be present at run-time. 

If the "2" option is used in conjunction with this option, the compiler will generate 287 and upwards 
compatible instructions; otherwise, the compiler will generate 8087 compatible instructions. 

(32-bit only) The compiler will generate in-line 387-compatible numeric data processor instructions into 
the object code for floating-point operations. When the "fpi87" option is used exclusively, coprocessor 
emulation software is not included in the application when it is linked. A 387 or compatible math 
coprocessor must be present at run-time. 

The macros_ FPI _and_ SW_ FPI87 will be predefined if "fpi87" is selected. See Note with 

description of "fpi" option. 

fp2 

The compiler will generate in-line 80x87 numeric data processor instructions into the object code for 
floating-point operations. For Open Watcom compilers generating 16-bit code, this option is the default. 
For 32-bit applications, use this option if you wish to support those few 386 systems that are equipped with 
a 287 numeric data processor ("fp3" is the default for Open Watcom compilers generating 32-bit code). 
However, for 32-bit applications, the use of this option will reduce execution performance. Use this option 

in conjunction with the "fpi" or "fpi87" options. The macro_ SW_ FP2 will be predefined if "fp2" is 

selected. 

fp3 

The compiler will generate in-line 387-compatible numeric data processor instructions into the object code 
for floating-point operations. For 16-bit applications, the use of this option will limit the range of systems 
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on which the application will run but there are execution performance improvements. For Open Watcom 
compilers generating 32-bit code, this option is the default. Use this option in conjunction with the "fpi" or 
"fpi87" options. The macro_ SW_ FP3 will be predefined if "fp3" is selected. 


fp5 

The compiler will generate in-line 80x87 numeric data processor instructions into the object code for 
floating-point operations. The sequence of floating-point instructions will be optimized for greatest 
possible performance on the Intel Pentium processor. For 16-bit applications, the use of this option will 
limit the range of systems on which the application will run but there are execution performance 

improvements. Use this option in conjunction with the "fpi" or "fpi87" options. The macro_ SW_ FP5 

will be predefined if "fp5" is selected. 

fp6 

The compiler will generate in-line 80x87 numeric data processor instructions into the object code for 
floating-point operations. The sequence of floating-point instructions will be optimized for greatest 
possible performance on the Intel Pentium Pro processor. For 16-bit applications, the use of this option 
will limit the range of systems on which the application will run but there are execution performance 

improvements. Use this option in conjunction with the "fpi" or "fpi87" options. The macro_ SW_ FP6 

will be predefined if "fp6" is selected. 

fpd 

A subtle problem was detected in the FDIV instruction of Intel’s original Pentium CPU. In certain rare 
cases, the result of a floating-point divide could have less precision than it should. Contact Intel directly for 
more information on the issue. 

As a result, the run-time system startup code has been modified to test for a faulty Pentium. If the FDIV 
instruction is found to be flawed, the low order bit of the run-time system variable_chipbug will be set. 

extern unsigned _ near _ chipbug; 

If the FDIV instruction does not show the problem, the low order bit will be clear. If the Pentium FDIV 
flaw is a concern for your application, there are two approaches that you could take: 

1. You may test the_chipbug variable in your code in all floating-point and memory models 

and take appropriate action (such as display a warning message or discontinue the application). 

2. Alternately, you can use the "fpd" option when compiling your code. This option directs the 
compiler to generate additional code whenever an FDIV instruction is generated which tests the 

low order bit of_chipbug and, if on, calls the software workaround code in the math 

libraries. If the bit is off, an in-line FDIV instruction will be performed as before. 

If you know that your application will never run on a defective Pentium CPU, or your analysis shows that 

the FDIV problem will not affect your results, you need not use the "fpd" option. The macro_ SW_ FPD 

will be predefined if "fpd" is selected. 

2.3.8 Segments/Modules 

This group of options deals with object file data structures that are generated by the compiler. 
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g=<codegroup> 

The generated code is placed in the group called "<codegroup>". The default "text" segment name will be 
"<codegroup>_TEXT" but this can be overridden by the "nt" option. 

Example: 

C>compiler_name report -g=RPTGROUP -s 
(16-bit only) « 

This is useful when compiling applications for small code models where the total application will contain 
more than 64 kilobytes of code. Each group can contain up to 64 kilobytes of code. The application 
follows a "mixed" code model since it contains a mix of small and large code (intra-segment and 
inter-segment calls). Memory models are described in the chapter entitled "16-bit Memory Models" on 
page 117. The far keyword is used to describe routines that are referenced from one group/segment but 
are defined in another group/segment. 

For small code models, the "s" option should be used in conjunction with the "g" option to prevent the 

generation of calls to the C run-time "stack overflow check" routine (_ STK ). You must also avoid calls 

to other "small code" C run-time library routines since inter-segment "near" calls to C library routines are 
not possible. 

» (16-bit only) 


nc=<name> 

The default "code" class name is "CODE". The small code model "_TEXT" segment and the large code 
model "nrodule_name_TEXT" segments belong to the "CODE" class. This option allows you to select a 
different class name for these code segments. The name of the "code" class is explicitly set to "<name>". 

Note that the default "data" class names are "DATA" (for the "CONST", "CONST2" and "_DATA" 
segments) and "BSS" (for the "_BSS" segment). There is no provision for changing the data class names. 


nd=<name> 

This option permits you to define a special prefix for the "CONST", "CONST2", "_DATA", and "_BSS" 
segment names. The name of the group to which these segments belong is also changed from "DGROUP" 
to "<name>_GROUP". This option is especially useful in the creation of 16-bit Dynamic Link Library 
(DLL) routines. 

Example: 

C>compiler_name report -nd=spec 

In the above example, the segment names become "specCONST", "specCONST2", "spec_DATA", and 
"spec_BSS" and the group name becomes "spec_GROUP". 

By default, the data group "DGROUP" consists of the "CONST", "CONST2", "_DATA", and "_BSS" 
segments. The compiler places certain types of data in each segment. The "CONST" segment contains 
constant literals that appear in your source code. 

Example: 

char *birds[ 3 ] = { "robin", "finch", "wren" }; 
printf( "Hello world\n" ) ; 
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In the above example, the strings "Hello world\n", "robin", "finch", etc. appear in the "CONST" segment. 
The "CONST2" segment contains initialized read-only data. 

Example: 


extern const 

int 

cvar 

= i; 


int var = 2; 
int table[ 5 

] = 

{ 1, 

2, 3, 4, 

5 } ; 

char *birds[ 

3 ] 

= { 

"robin", 

"finch", "wren" }; 


In the above example, the constant variable cvar is placed in the "CONST2" segment. 

The "_BSS" segment contains uninitialized data such as scalars, structures, or arrays. 

Example: 

int varl; 

int arrayl[ 400 ]; 

Other data segments containing data, specifically declared to be far or exceeding the data threshold (see 
"zt" option), are named either "module_nameN_DATA" when using the C compiler or 
"module_name_DATAN" when using the C++ compiler where "N" is some integral number. 

Example: 

int far array2[400]; 

In the above example, array2 is placed in the segment "reportl 1_DATA" (C) or "report_DATAll" 
(C++) provided that the module name is "report". 

The macro_ SW_ ND will be predefined if "nd" is selected. 


nm=<name> 

By default, the object file name and the module name that is placed within it are constructed from the 
source file name. When the "nm" option is used, the module name that is placed into the object file is 
"<name>". For large code models, the "text" segment name is "<name>_TEXT" unless the "nt" option is 
used. 

In the following example, the preprocessed output from report. c is stored on drive "D" under the name 
temp. c . The file is compiled with the "nm" option so that the module name imbedded into the object file 
is "REPORT" rather than "TEMP". 

Example: 

C>compiler_name report -pi -f o=d:\temp. c 
C >compiler_name d:\temp -nm=report -fo=report 

Since the "fo" option is also used, the resultant object file is called report. ob j . 


nt=<name> 

The name of the "text" segment is explicitly set to "<name>". By default, the "text" segment name is 
"_TEXT" for small code models and "module_name_TEXT" for large code models. 
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Application 

Memory 

Code 



Type 

Model 

Segment 



16-bit 

tiny 

_ TEXT 



32-bit 

flat 

_ TEXT 



16/32-bit 

small 

_ TEXT 



16/32-bit 

medium 

module_ 

name_ 

TEXT 

16/32-bit 

compact 

_ TEXT 



16/32-bit 

large 

module_ 

name_ 

TEXT 

16-bit 

huge 

module_ 

name_ 

TEXT 


The "zm" option instructs the code generator to place each function into a separate segment. 

In small code models, the segment name is "_TEXT" by default. 

(C only) In large code models, the segment name is composed of the function name concatenated with the 
string "_TEXT". 

(C++ only) In large code models, the segment name is composed of the module name concatenated with the 
string "_TEXT" and a unique integral number. 

The default string "_TEXT" can be altered using the "nt" option (see "nt=<name>" on page 47). 

The advantages to this option are: 

1. Since each function is placed in its own segment, functions that are not required by an 
application are omitted from the executable by the linker (when "OPTION ELIMINATE" is 
specified). 

2. This can result in smaller executables. 

3. This benefit applies to both small and large code models. 

4. This option allows you to create granular libraries without resorting to placing each function in a 
separate file. 

Example: 

static int too( int x ) 

{ 

return x — 1; 

} 

static int near fool( int x ) 

{ 

return x + 1; 

} 

int foo2( int y ) 

{ 

return foo(y) * fool(y-l); 

} 

int foo3 ( int x, int y ) 

{ 

return x + y * x; 

} 
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The disadvantages to this option are: 

1. The "near call" optimization for static functions in large code models is disabled (e.g., the 
function f oo in the example above will never be "near called". Static functions will always be 
"far called" in large code models. 

2. Near static functions will still be "near called" (e.g., the function fool is "near called" in the 
example above). However, this can lead to problems at link time if the caller function ends up in 
a different segment from the called function (the linker will issue a message if this is the case). 

3. The "common epilogue" optimization is lost. 

4. The linker "OPTION ELIMINATE" must be specified when linking an application to take 
advantage of the granularity inherent in object files/libraries compiled with this option. 

5. Any assumptions about relative position of functions are invalid. Consider the following code 
which attempts to determine the size of a code region by subtracting function addresses: 

Example: 

region_ size = (unsigned long)&function2 - (unsigned 
long)functionl; 

When "zm" is in effect, region_ size may be extremely large or even a negative value. For 
the above code to work as intended, both functionl and function2 (and every function 
intended to be located between them) must reside in a single code segment. 

This option can be used in paging environments where special segment ordering may be employed. The 
"alloc_text" pragma is often used in conjunction with this option to place functions into specific segments. 

The macro_ SW_ ZM will be predefined if "zm" is selected. 


(C++ only) This option is identical to the "zm" option (see "zm" on page 48) except for the following large 
code model consideration. 

Instead of placing each function in a segment with a different name, the code generator will place each 
function in a segment with the same name (the name of the module suffixed by "_TEXT"). 

The advantages to this option are: 

1. All functions in a module will reside in the same physical segment in an executable. 

2. The "near call" optimization for static functions in large code models is not disabled (e.g., the 
function f oo in the example above will be "near called". Static functions will always be "near 
called" in large code models. 

3. The problem associated with calling "near" functions goes away since all functions in a module 
will reside in the same physical segment (e.g., the function fool is "near" in the example 
above). 

The disadvantages to this option are: 

1. The size of a physical segment is restricted to 64K in 16-bit applications. Although this may 
limit the number of functions that can be placed in the segment, the restriction is only on a "per 
module" basis. 

2. Although less constricting, the size of a physical segment is restricted to 4G in a 32-bit 
application. 
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2.3.9 80x86 Run-time Conventions 

This group of options deals with the 80x86 run-time environment. 

0 

(16-bit only ) The compiler will make use of only 8086 instructions in the generated object code. This is the 

default. The resulting code will run on 8086 and all upward compatible processors. The macro_ SW_ 0 

will be predefined if "0" is selected. 

1 

(16-bit only) The compiler will make use of 186 instructions in the generated object code whenever 
possible. The resulting code probably will not run on 8086 compatible processors but it will run on 186 
and upward compatible processors. The macro_ SW_ 1 will be predefined if "1" is selected. 

2 

(16-bit only) The compiler will make use of 286 instructions in the generated object code whenever 
possible. The resulting code probably will not run on 8086 or 186 compatible processors but it will run on 
286 and upward compatible processors. The macro_ SW_ 2 will be predefined if "2" is selected. 

3 

(16-bit only) The compiler will make use of some 386 instructions and FS or GS (if "zff" or "zgf' options 
are used) in the generated object code whenever possible. The code will be optimized for 386 processors. 
The resulting code probably will not run on 8086, 186 or 286 compatible processors but it will run on 386 
and upward compatible processors. The macro_ SW_ 3 will be predefined if "3" is selected. 

4 

(16-bit only) The compiler will make use of some 386 instructions and FS or GS (if "zff" or "zgf' options 
are used) in the generated object code whenever possible. The code will be optimized for 486 processors. 
The resulting code probably will not run on 8086, 186 or 286 compatible processors but it will run on 386 
and upward compatible processors. The macro_ SW_ 4 will be predefined if "4" is selected. 

5 

(16-bit only) The compiler will make use of some 386 instructions and FS or GS (if "zff" or "zgf' options 
are used) in the generated object code whenever possible. The code will be optimized for the Intel Pentium 
processor. The resulting code probably will not run on 8086, 186 or 286 compatible processors but it will 
run on 386 and upward compatible processors. The macro_ SW_ 5 will be predefined if "5" is selected. 

6 

(16-bit only) The compiler will make use of some 386 instructions and FS or GS (if "zff" or "zgf' options 
are used) in the generated object code whenever possible. The code will be optimized for the Intel Pentium 
Pro processor. The resulting code probably will not run on 8086, 186 or 286 compatible processors but it 

will run on 386 and upward compatible processors. The macro_ SW_ 6 will be predefined if "6" is 

selected. 

3{rls} 

(32-bit only) The compiler will generate 386 instructions based on 386 instruction timings (see "4", "5" and 
"6" below). 
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If the "r" suffix is specified, the following machine-level code strategy is employed. 

• The compiler will pass arguments in registers whenever possible. This is the default method used to 
pass arguments (unless the "bt=netware" option is specified). 

• All registers except EAX are preserved across function calls. 

• When any form of the "fpi" option is used, the result of functions of type "float" and "double" is 
returned in ST(0). 

• When the "fpc" option is used, the result of a function of type "float" is returned in EAX and the 
result of a function of type "double" is returned in EDX:EAX. 

• The resulting code will be smaller than that which is generated for the stack-based method of passing 
arguments (see "3s" below). 

• The default naming convention for all global functions is such that an underscore character ("_") is 
suffixed to the symbol name. The default naming convention for all global variables is such that an 
underscore character ("_") is prefixed to the symbol name. 

If the "s" suffix is specified, the following machine-level code strategy is employed. 

• The compiler will pass all arguments on the stack. 

• The EAX, ECX and EDX registers are not preserved across function calls. 

• The FS and GS registers are not preserved across function calls. 

• The result of a function of type "float" is returned in EAX. The result of a function of type "double" 
is returned in EDX:EAX. 

• The resulting code will be larger than that which is generated for the register method of passing 
arguments (see "3r" above). 

• The naming convention for all global functions and variables is modified such that no underscore 
characters ("_") are prefixed or suffixed to the symbol name. 

The "s" conventions are similar to those used by the MetaWare High C 386 compiler. 

By default, "r" is selected if neither "r" nor "s" is specified. 

The macro_SW_ 3 will be predefined if "3" is selected. The macro _ SW_ 3R will be predefined if "r" is 

selected (or defaulted). The macro_SW_ 3S will be predefined if "s" is selected. 


4{rls} 

(32-bit only) This option is identical to "3{rls}" except that the compiler will generate 386 instructions 
based on 486 instruction timings. The code is optimized for 486 processors rather than 386 processors. By 

default, "r" is selected if neither "r" nor "s" is specified. The macro_SW_ 4 will be predefined if "4" is 

selected. The macro_SW_ 3R will be predefined if "r" is selected (or defaulted). The macro _ SW_ 3S 

will be predefined if "s" is selected. 
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5{rls} 

(32-bit only) This option is identical to "3{rls}" except that the compiler will generate 386 instructions 
based on Intel Pentium instruction timings. This is the default. The code is optimized for Intel Pentium 
processors rather than 386 processors. By default, "r" is selected if neither "r" nor "s" is specified. The 

macro_SW_ 5 will be predefined if "5" is selected. The macro _ SW_ 3R will be predefined if "r" is 

selected (or defaulted). The macro_SW_ 3S will be predefined if "s" is selected. 

6{rls} 

(32-bit only) This option is identical to "3{rls}" except that the compiler will generate 386 instructions 
based on Intel Pentium Pro instruction timings. The code is optimized for Intel Pentium Pro processors 
rather than 386 processors. By default, "r" is selected if neither "r" nor "s" is specified. The macro 

_SW_ 6 will be predefined if "6" is selected. The macro _ SW_ 3R will be predefined if "r" is selected (or 

defaulted). The macro_SW_ 3S will be predefined if "s" is selected. 

mf 

(32-bit only) The "flat" memory model (code and data up to 4 gigabytes) is selected. By default, the 32-bit 
compiler will select this memory model unless the target system is Netware in which case "small" is 
selected. The following macros will be predefined. 

_SW_ MF 

_FLAT_ 

M_ 38 6FM 
_ M_ 38 6FM 

ms 

The "small" memory model (small code, small data) is selected. By default, the 16-bit compiler will select 
this memory model. When the target system is Netware, the 32-bit compiler will select this memory model. 
The following macros will be predefined. 

_SW_ MS 

_ SMALL_ 

additional for 16-bit compiler 

M_ I86SM 
_ M_ I8 6SM 

additional for 32-bit compiler 

M_ 386SM 
_ M_ 38 6SM 

mm 

The "medium" memory model (big code, small data) is selected. The following macros will be predefined. 

_SW_ MM 

_ MEDIUM_ 

additional for 16-bit compiler 

M_ I86MM 
_ M_ 18 6 MM 
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additional for 32-bit compiler 

M_ 3 8 6MM 
_ M_ 38 6MM 


me 

The "compact" memory model (small code, big data) is selected. The following macros will be predefined. 

_SW_ MC 

_ COMPACT_ 


additional for 16-bit compiler 

M_ I86CM 
_ M_ I8 6CM 


additional for 32-bit compiler 

M_ 38 6CM 
_ M_ 38 6CM 


ml 

The "large" memory model (big code, big data) is selected. The following macros will be predefined. 

_SW_ ML 

_ LARGE_ 


additional for 16-bit compiler 

M_ I86LM 
_ M_ I8 6LM 

additional for 32-bit compiler 

M_ 38 6LM 
_ M_ 38 6LM 


mh 


(16-bit only) The "huge" memory model (big code, huge data) is selected. The following macros will be 
predefined. 

_SW_ MH 

_ HUGE_ 

M_ I86HM 
_ M_ I8 6HM 


Memory models are described in the chapters entitled "16-bit Memory Models" on page 117 and "32-bit 
Memory Models" on page 185. Other architectural aspects of the Intel 86 family such as pointer size are 
discussed in the sections entitled "Sizes of Predefined Types" on page 128 in the chapter entitled "16-bit 
Assembly Language Considerations" or "Sizes of Predefined Types" on page 194 in the chapter entitled 
"32-bit Assembly Language Considerations" 
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zd{f,p} 

The "zdf" option allows the code generator to use the DS register to point to other segments besides 
"DGROUP" This is the default in the 16-bit compact, large, and huge memory models (except for 16-bit 
Windows applications). 

The "zdp" option informs the code generator that the DS register must always point to "DGROUP" This is 
the default in the 16-bit small and medium memory models, all of the 16-bit Windows memory models, and 

the 32-bit small and flat memory models. The macro_ SW_ ZDF will be predefined if "zdf' is selected. 

The macro_ SW_ ZDP will be predefined if "zdp" is selected. 

zdl 

(32-bit only) The "zdl" option causes generation of code to load the DS register directly from DGROUP 
(rather than the default run-time call ). This option causes the generation of a segment relocation. This 
option is used with the "zdp" option but not the "zdf" option. 

zev 

The "zev" option is an extension to the Watcom C compiler to allow arithmetic operations on void derived 
types. This option has been added for compatibility with some Unix compilers and is not ISO compliant. 

The use of this option should be avoided. 

zf{f,p} 

The "zff" option allows the code generator to use the FS register (default for all but flat memory model). 

The "zfp" option informs the code generator that the FS register must not be used (default in flat memory 

model). The macro_SW_ ZFF will be predefined if "zff" is selected. The macro _ SW_ ZFP will be 

predefined if "zfp" is selected. 

zfw 

The "zfw" option turns on generation of FWAIT instructions on 386 and later CPUs. Note that when 
targeting 286 and earlier, this option has no effect because FWAITs are always required for 
synchronization between CPU and FPU. 

This option generates larger and slower code and should only be used when restartable floating-point 
exceptions are required. 

The macro_ SW_ ZFW will be predefined if "zfw" is selected. 

zg{f,p} 

The "zgf" option allows the code generator to use the GS register (default for all memory models). The 

"zgp" option informs the code generator that the GS register must not be used. The macro_ SW_ ZGF will 

be predefined if "zgf" is selected. The macro_ SW_ ZGP will be predefined if "zgp" is selected. 

zri 

(32-bit only) The "zri" option inlines the code for floating point rounding. Normally a function call is 
generated for each float to int conversion which may not be desirable. 

The macro_ SW_ ZRI will be predefined if "zri" is selected. 
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zro 

The "zro" option omits the code for floating point rounding. This results in non-conformant code - the 
rounding mode is not ISO/ANSI C compliant - but the code generated is very fast. 

The macro_ SW_ ZRO will be predefined if "zro" is selected. 

ZU 

The "zu" option relaxes the restriction that the SS register contains the base address of the default data 
segment, "DGROUP". Normally, all data items are placed into the group "DGROUP" and the SS register 
contains the base address of this group. When the "zu" option is selected, the SS register is volatile 
(assumed to point to another segment) and any global data references require loading a segment register 
such as DS with the base address of "DGROUP". 

(16-bit only ) This option is useful when compiling routines that are to be placed in a Dynamic Link Library 
(DLL) since the SS register points to the stack segment of the calling application upon entry to the function. 

The macro_ SW_ ZU will be predefined if "zu" is selected. 

2.3.10 Optimizations 

When specified on the command line, optimization options may be specified individually (oa, oi) or the 
letters may be strung together (oailt). 


oa 


Alias checking is relaxed. When this option is specified, the code optimizer will assume that global 
variables are not indirectly referenced through pointers. This assumption may reduce the size of the code 
that is generated. The following example helps to illustrate this point. 

Example: 

extern int i; 

void rtn( int *pi ) 

{ 

int k; 

for ( k = 0; k < 10; ++k ) { 

(*pi)++; 
i++; 

} 

} 

In the above example, if "i" and "*pi" referenced the same integer object then "i" would be incremented by 
2 each time through the "for" loop and we would call the pointer reference "*pi" an alias for the variable 
"i". In this situation, the compiler could not bind the variable "i" to a register without making sure that the 
"in-memory" copy of "i" was kept up-to-date. In most cases, the above situation does not arise. Rarely 
would we reference the same variable directly by name and indirectly through a pointer in the same routine. 
The "oa" option instructs the code generator that such cases do not arise in the module to be compiled. The 
code generator will be able to produce more efficient code when it does not have to worry about the alias 
"problem". 

The macro_ SW_ OA will be predefined if "oa" is selected. 
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ob 

When the "ob" option is specified, the code generator will try to order the blocks of code emitted such that 
the "expected" execution path (as determined by a set of simple heuristics) will be straight through, with 
other cases being handled by jumps to separate blocks of code "out of line". This will result in better cache 
utilization on the Pentium. If the heuristics do not apply to your code, it could result in a performance 
decrease. 

oc 

This option may be used to disable the optimization where a "CALL" followed by a "RET" (return) is 
changed into a "JMP" (jump) instruction. 

(16-bit only) This option is required if you wish to link an overlayed program using the Microsoft DOS 
Overlay Linker. The Microsoft DOS Overlay Linker will create overlay calls for a "CALL" instruction 
only. This option is not required when using the Open Watcom Linker. 

The macro_SW_ OC will be predefined if "oc" is selected. 

od 

Non-optimized code sequences are generated. The resulting code will be much easier to debug when using 
the Open Watcom Debugger. By default, the compiler will select "od" if "d2" is specified. If "d2" is 
followed by one of the other "o?" options then "od" is overridden. 

Example: 

C>compiler_name report -d2 -os 
The macro_SW_ OD will be predefined if "od" is selected. 

oe=<num> 

Certain user functions are expanded in-line. The criteria for which functions are selected for in-line 
expansion is based on the "size" of the function in terms of the number of "tree nodes" generated by the 
function. Functions are internally represented as tree structures, where each operand and each operator is a 
node of the tree. For example, the statement a = -b * (c + d) can be represented as a tree with 8 
nodes, one for each operand and operator. 

The number of "nodes" generated corresponds closely with the number of operators used in an expression. 
Functions which require more than "<num>" nodes are not expanded in-line. The default number is 20. 
With larger "<num>" values, more (larger) functions will be expanded in-line. This optimization is 
especially useful when locally-referenced functions are small in size. 

Example: 

C>compiler_name dhrystone -oe 

oh 

This option enables repeated optimizations (which can result in longer compiles). 

0 / 

Certain library functions are generated in-line. You must include the appropriate header file containing the 
prototype for the desired function so that it will be generated in-line. The functions that can be generated 
in-line are: 
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abs 

_ fmemcmp 
_ fstrlen 
_ lrotl (2) 
movedata 
strcat 


_ disable 
_ fmemcpy 
inpd (2) 

_lrotr (2 
outpd (2) 
strchr 


div 

_ fmemset 
inpw 
memchr 
outpw 
strcmp (1) 


_ enable 
_ fstrcat 
inp 

memcmp 

outp 

strcpy 


fabs _ fmemchr 

_ fstrcmp _ fstrcpy 
labs ldiv (2) 

memcpy memset (1) 

_ rotl _ rotr 

strlen 


*1 16-bit only 
*2 32-bit only 

The macros_INLINE_ FUNCTIONS_and SW_ 01 will be predefined if "oi" is selected. 


oi+ 

(C++ only) This option encompasses "oi" but also sets inline_depth to its maximum (255). By default, 
inline_depth is 3. The inline_depth can also be changed by using the C++ inline_ depth pragma. 

ok 

This option enables flowing of register save (from prologue) down into the function’s flow graph. This 
means that register save/restores will not be executed when it is not necessary (as can be the case when a 
function consists of an if-else construct with a simple part that does little and a more complex part that does 
a lot). 

oi 

Loop optimizations are performed. This includes moving loop-invariant expressions outside the loops. 

The macro_ SW_ OL will be predefined if "ol" is selected. 

ol+ 

Loop optimizations are performed including loop unrolling. This includes moving loop-invariant 

expressions outside the loops and turning some loops into straight-line code. The macro_ SW_ OL will be 

predefined if "ol+" is selected. 

om 

Generate in-line 80x87 code for math functions like sin, cos, tan, etc. If this option is selected, it is the 
programmer’s responsibility to make sure that arguments to these functions are within the range accepted 
by the fsin, fcos, etc. instructions since no run-time check is made. For 16-bit, you must also 
include the "fp3" option to get in-line 80x87 code (except for fabs). The functions that can be generated 
in-line are: 

atan cos exp fabs loglO log sin sqrt tan 
The macro_ SW_ OM will be predefined if "om" is selected. 

on 

This option allows the compiler to replace floating-point divisions with multiplications by the reciprocal. 

This generates faster code, but the result may not be the same because the reciprocal may not be exactly 
representable. The macro_ SW_ ON will be predefined if "on" is selected. 
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oo 

By default, the compiler will abort compilation if it runs low on memory. This option forces the compiler 
to continue compilation even when low on memory, however, this can result in very poor code being 
generated. The macro_SW_ OO will be predefined if "oo" is selected. 

op 

This option causes the compiler to store intermediate floating-point results into memory in order to generate 
consistent floating-point results rather than keeping values in the 80x87 registers where they have more 
precision. The macro_SW_ OP will be predefined if "op" is selected. 

or 

This option enables reordering of instructions (instruction scheduling) to achieve better performance on 
pipelined architectures such as the Intel 486 and Pentium processors. This option is essential for generating 
fast code for the Intel Pentium processor. Selecting this option will make it slightly more difficult to debug 
because the assembly language instructions generated for a source statement may be intermixed with 

instructions generated for surrounding statements. The macro_SW_ OR will be predefined if "or" is 

selected. 

OS 

Space is favoured over time when generating code (smaller code but possibly slower execution). By 

default, the compiler selects a balance between "space" and "time". The macro_SW_ OS will be 

predefined if "os" is selected. 

Of 

Time is favoured over space when generating code (faster execution but possibly larger code). By default, 

the compiler selects a balance between "space" and "time". The macro_SW_ OT will be predefined if "ot" 

is selected. 

ou 

This option forces the compiler to make sure that all function labels are unique. Thus the compiler will not 
place two function labels at the same address even if the code for the two functions are identical. This 

option is automatically selected if the "za" option is specified. The macro_SW_ OU will be predefined if 

"ou" is selected. 

OX 

The "obmiler" and "s" (no stack overflow checking) options are selected. 

oz 

This option prevents the compiler from omitting NULL pointer checks on pointer conversions. By default, 
the compiler omits NULL pointer checks on pointer conversions when it is safe to do so. Consider the 
following example. 
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struct B1 { 
int bl; 

}; 

struct B2 { 
int b2; 

} ; 

struct D : Bl, B2 { 
int d; 

} ; 

void clear_ D( D *p ) 

{ 

p->d = 0; 

Bl *pl = p; 
pl->bl = 0; 

B2 *p2 = p; 
p2->b2 = 0; 

} 

In this example, the C++ compiler must ensure that pi and p2 become NULL if p is NULL (since no 
offset adjustment is allowed for a NULL pointer). However, the first executable statement implies that p is 
not NULL since, in most operating environments, the executing program would crash at the first executable 
statement if p was NULL. The "oz" option will prevent the compiler from omitting the check for a NULL 
pointer. 

The macro_SW_ OZ will be predefined if "oz" is selected. 

When "ox" is combined with the "on", "oa" and "ot" options ("onatx") and the "zp4" option, the code 
generator will attempt to give you the fastest executing code possible irrespective of architecture. Other 
options can give you architecture specific optimizations to further improve the speed of your code. Note 
that specifying "onatx" is equivalent to specifying "onatblimer" and "s". See the section entitled 
"Benchmarking Hints" on page 69 for more information on generating fast code. 

2.3.11 C++ Exception Handling 

The "xd..." options disable exception handling. Consequently, it is not possible to use throw , try, or catch 
statements, or to specify a function exception specification. If your program (or a library which it includes) 
throws exceptions, then one of the "xs..." options should be used to compile all the modules in your 
program; otherwise, any active objects created within the module will not be destmcted during exception 
processing. 

Multiple schemes are possible, allowing experimentation to determine the optimal scheme for particular 
circumstances. You can mix and match schemes on a module basis, with the proviso that exceptions should 
be enabled wherever it is possible that a created object should be destructed by the exception mechanism. 


This option disables exception handling. It is the default option if no exception handling option is 
specified. When this option is specified (or defaulted): 

• Destruction of objects is caused by direct calls to the appropriate destructors 

• Destructor functions are implemented with direct calls to appropriate destructors to destruct base 
classes and class members. 
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xdt 

This option is the same as "xd" (see "xd" on page 59). 

xds 

This option disables exception handling. When this option is specified: 

• Destruction of objects is caused by direct calls to the appropriate destructors. 

• Destruction of base classes and class members is accomplished by interpreting tables. 

• This option, in general, generates smaller code, with increased execution time and with more 
run-time system routines included by the linker. 


xs 

This option enables exception handling using a balanced scheme. When this option is specified: 

• Tables are interpreted to effect destruction of temporaries and automatic objects; destructor functions 
are implemented with direct calls to appropriate destructors to destruct base classes and class 
members. 


xst 

This option enables exception handling using a time-saving scheme. When this option is specified: 

• Destruction of temporaries and automatic objects is accomplished with direct calls to appropriate 
destructors; destructor functions are implemented with direct calls to appropriate destructors to 
destruct base classes and class members. 

• This scheme will execute faster, but will use more space in general. 


xss 

This option enables exception handling using a space-saving scheme. When this option is specified: 

• Tables are interpreted to effect destruction of temporaries and automatic objects; destruction of base 
classes and class members is accomplished by interpreting tables. 

• This option, in general, generates smaller code, with increased execution time. 

2.3.12 Double-Byte/Unicode Characters 

This group of options deals with compile-time aspects of character sets used in the source code. 

zk{0,1,2,1} 

This option causes the compiler to recognize double-byte characters in strings. When the compiler scans a 
text string enclosed in quotes ("), it will recognize the first byte of a double-byte character and suppress 
lexical analysis of the second byte. This will prevent the compiler from misinterpreting the second byte as 
a "\" or quote (") character. 
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zk, zkO These options cause the compiler to process strings for Japanese double-byte characters 

(range 0x81 - 0x9F and OxEO - OxFC). The characters in the range AO - DF are single-byte 
Katakana. 

zkl This option causes the compiler to process strings for Traditional Chinese and Taiwanese 

double-byte characters (range 0x81 - OxFC). 

zk2 This option causes the compiler to process strings for Korean Hangeul double-byte 

characters (range 0x81 - OxFD). 

zkl This option causes the compiler to process strings using the current code page. If the local 

character set includes double-byte characters then string processing will check for lead 
bytes. 

The macro_ SW_ ZK will be predefined if any "zk" option is selected. 


zkOu 

This option causes the compiler to process strings for Japanese double-byte characters (range 0x81 - 0x9F 
and OxEO - OxFC). The characters in the range AO - DF are single-byte Katakana. All characters, including 
Kanji, in wide characters (F’c’) and wide strings (L"string") are translated to UNICODE. 

When the compiler scans a text string enclosed in quotes ("), it will recognize the first byte of a double-byte 
character and suppress lexical analysis of the second byte. This will prevent the compiler from 
misinterpreting the second byte as a "\" or quote (") character. 


zku=<codepage> 

Characters in wide characters (F’c’) and wide strings (F"string") are translated to UNICODE. The 
UNICODE translate table for the specified code page is loaded from a file. The compiler locates this file 
by searching the paths listed in the PATH environment variable. The following table lists the supported 
code pages. 

codepage | character set | file name 


437 

US-ASCII 

(DOS) 

Unicode. 

437 

850 

Latin-1 

(DOS) 

Unicode. 

850 

852 

Latin-2 

(DOS) 

Unicode. 

852 

1250 

Latin-2 

(Win32) 

unicodel 

.250 

1252 

Latin-1 

(Win32) 

unicodel 

.252 


2.3.13 Compatibility with Microsoft Visual C++ 

This group of options deals with compatibility with Microsoft’s Visual C++ compiler. 

VC... 

The "vc" option prefix is used to introduce a set of Microsoft Visual C++ compatibility options. At present, 
there is only one: vcap. 

vcap 

This options tells the compiler to allow _alloca() to be used in a parameter list. The optimizer has to do 
extra work to allow this but since it is rare (and easily worked around if you can), you have to ask the 
optimizer to handle this case. You also may get less efficient code in some cases. 
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2.3.14 Compatibility with Older Versions of the 80x86 Compilers 

This group of options deals with compatibility with older versions of Open Watcom’s 80x86 compilers. 


r 

This option instructs the compiler to generate function prologue and epilogue sequences that save and 
restore any segment registers that are modified by the function. Caution should be exercised when using 
this option. If the value of the segment register being restored matches the value of a segment that was 
freed within the function, a general protection fault will occur in protected-mode environments. When this 
option is used, the compiler also assumes that called functions save and restore segment registers. By 
default, the compiler does not generate code to save and restore segment registers. This option is provided 
for compatibility with the version 8.0 release. The macro_SW_ R will be predefined if "r" is selected. 

fpr 

Use this option if you want to generate floating-point instructions that will be compatible with version 9.0 
or earlier of the compilers. For more information on floating-point conventions see the sections entitled 
"Using the 80x87 to Pass Arguments" on page 179 and "Using the 80x87 to Pass Arguments" on page 248. 

ZZ 

Use this option if you want to generate_stdcall function names that will be compatible with version 10.0 

of the compilers. When this option is omitted, all C symbols (extern "C" symbols in C++) are suffixed by 
"@nnn" where "nnn" is the sum of the argument sizes (each size is rounded up to a multiple of 4 bytes so 
that char and short are size 4). When the argument list contains the "@nnn" suffix is omitted. This 

convention is compatible with Microsoft. For more information on the_stdcall convention see the section 

entitled "Open Watcom C/C++ Extended Keywords" on page 81. 
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This chapter covers the following topics. 

• Command line syntax (see "Open Watcom C/C++ Command Line Format") 

• Environment variables used by the compilers (see "Environment Variables" on page 66) 

• Examples of command line syntax (see "Open Watcom C/C++ Command Line Examples" on page 
67) 

• Interpreting diagnostic messages (see "Compiler Diagnostics" on page 71) 

• #include file handling (see "Open Watcom C/C++ #include File Processing" on page 72) 

• Using the preprocessor built into the compilers (see "Open Watcom C/C++ Preprocessor" on page 
75) 

• System-dependent macros predefined by the compilers (see "Open Watcom C/C++ Predefined 
Macros" on page 76) 

• Additional keywords supported by the compilers (see "Open Watcom C/C++ Extended Keywords" 
on page 81) 

• Based pointer support in the compilers (see "Based Pointers" on page 88) 

• Notes about the Code Generator (see "The Open Watcom Code Generator" on page 99) 


3.1 Open Watcom C/C++ Command Line Format 

The formal Open Watcom C/C++ command line syntax is shown below. 


compiler_name [options] [file_spec] [options] [ @ extra_opts] 


The square brackets [ ] denote items which are optional. 

compiler_name is one of the Open Watcom C/C++ compiler command names. 

WCC is the Open Watcom C compiler for 16-bit Intel platforms. 

WPP is the Open Watcom C++ compiler for 16-bit Intel platforms. 

WCC.Vi6 is the Open Watcom C compiler for 32-bit Intel platforms. 

WPP386 is the Open Watcom C++ compiler for 32-bit Intel platforms. 
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file_spec is the file name specification of one or more files to be compiled. If file_spec is specified 

as the single character an input file is read from standard input and the output file name 
defaults to stdin.obj. 

If no drive is specified, the default drive is assumed. 

If no path is specified, the current working directory is assumed. 

If the "xx" option was not specified and the file is not in the current directory then an 
adjacent "C" directory (i.e., . . \c) is searched if it exists. 

If no file extension is specified, the compiler will check for a file with one of the following 
extensions in the order listed: 

.CPP (C++ only) 

.CC (C++ only) 

.C (C/C++) 

If a period is specified but not the extension, the file is assumed to have no filename 
extension. 

If only the compiler name is specified then the compiler will display a list of available 
options. 

options is a list of valid compiler options, each preceded by a slash ("/") or a dash ("—"). Options 

may be specified in any order. 

extra_opts is the name of an environment variable or file which contains additional command line 
options to be processed. If the specified environment variable does not exist, a search is 
made for a file with the specified name. If no file extension is included in the specified 
name, the default file extension is ".occ". A search of the current directory is made. If not 
successful, an adjacent "OCC" directory (i.e., . . \occ) is searched if it exists. 

3.2 Open Watcom C/C++ DLL-based Compilers 

The compilers are also available in Dynamic Link Library (DLL) form. 

WCCD is the DLL version of the Open Watcom C compiler for 16-bit Intel platforms. 

WPPDI86 is the DLL version of the Open Watcom C++ compiler for 16-bit Intel platforms. 

WCCD386 is the DLL version of the Open Watcom C compiler for 32-bit Intel platforms. 

WPPD386 is the DLL version of the Open Watcom C++ compiler for 32-bit Intel platforms. 

The DLL versions of the compilers can be loaded from the Open Watcom Integrated Development 
Environment (IDE) and Open Watcom Make. 
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3.3 Environment Variables 

Environment variables can be used to specify commonly used compiler options. There is one environment 
variable for each compiler (the name of the environment variable is the same as the compiler name). The 
Open Watcom C/C++ environment variable names are: 

WCC used with the Open Watcom C compiler for 16-bit Intel platforms 

Example: 

C>set wcc=-dl -ot 

WPP used with the Open Watcom C++ compiler for 16-bit Intel platforms 

Example: 

C>set wpp=-dl -ot 

WCC386 used with the Open Watcom C compiler for 32-bit Intel platforms 
Example: 

C>set wcc386=-dl -ot 

WPP386 used with the Open Watcom C++ compiler for 32-bit Intel platforms 
Example: 

C>set wpp386=-dl -ot 

The options specified in environment variables are processed before options specified on the command line. 
The above examples define the default options to be "dl" (include line number debugging information in 
the object file), and "ot" (favour time optimizations over size optimizations). 

Whenever you wish to specify an option that requires the use of an "=" character, you can use the "#" 
character in its place. This is required by the syntax of the "SET" command. 

Once a particular environment variable has been defined, those options listed become the default each time 
the associated compiler is used. The compiler command line can be used to override any options specified 
in the environment string. 

These environment variables are not examined by the Open Watcom Compile and Link utilities. Since the 
Open Watcom Compile and Link utilities pass the relevant options found in their associated environment 
variables to the compiler command line, their environment variable options take precedence over the 
options specified in the environment variables associated with the compilers. 
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Hint: If you are running DOS and you use the same compiler options all the time, you may find it 
handy to define the environment variable in your DOS system initialization file, AUTOEXEC . BAT . 

If you are running Windows NT, use the "System" icon in the Control Panel to define environment 
variables. 

If you are running OS/2 and you use the same compiler options all the time, you may find it handy to 
define the environment variable in your OS/2 system initialization file, CONFIG. SYS . 


3.4 Open Watcom C/C++ Command Line Examples 

The following are some examples of using Open Watcom C/C++ to compile C/C++ source programs. 
Example: 

C>compiler_name report -dl -s 

The compiler processes report. c (pp) producing an object file which contains source line number 
information. Stack overflow checking is omitted from the object code. 

Example: 

C>compiler_name -mm -fpc calc 

The compiler compiles calc . c (pp) for the Intel "medium" memory model and generates calls to 
floating-point library emulation routines for all floating-point operations. Memory models are described in 
the chapter entitled "16-bit Memory Models" on page 117. 

Example: 

C>compiler_name kwikdraw -2 -fpi87 -oaxt 

The compiler processes kwikdraw. c (pp) producing 16-bit object code for an Intel 286 system 
equipped with an Intel 287 numeric data processor (or any upward compatible 386/387, 486DX, or Pentium 
system). While the choice of these options narrows the number of microcomputer systems where this code 
will execute, the resulting code will be highly optimized for this type of system. 

Example: 

C>compiler_name -mf -3s calc 

The compiler compiles calc . c (pp) for the Intel 32-bit "flat" memory model. The compiler will 
generate 386 instructions based on 386 instruction timings using the stack-based argument passing 
convention. The resulting code will be optimized for Intel 386 systems. Memory models are described in 
the chapter entitled "32-bit Memory Models" on page 185. Argument passing conventions are described in 
the chapter entitled "32-bit Assembly Language Considerations" on page 189. 

Example: 

C>compiler_name kwikdraw -4r -fpi87 -oaimxt 

The compiler processes kwikdraw. c (pp) producing 32-bit object code for an Intel 386-compatible 
system equipped with a 387 numeric data processor. The compiler will generate 386 instructions based on 
486 instruction timings using the register-based argument passing convention. The resulting code will be 
highly optimized for Intel 486 systems. 
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Example: 

C>compiler_name . .\source\modabs -d2 

The compiler processes . . \source\modabs . c (pp) (a file in a directory which is adjacent to the 
current one). The object file is placed in the current directory. Included with the object code and data is 
information on local symbols and data types. The code generated is straight-forward, unoptimized code 
which can be readily debugged with the Open Watcom Debugger. 

Example: 

C>set compiler_name=- i#\includes -me 
C >compiler_name \cprogs\grep . tst -fi=iomods.c 

The compiler processes the program contained in the file \cprogs\grep. tst. The file iomods . c is 
included as if it formed part of the source input stream. The include search path and memory model 
options are defaults each time the compiler is invoked. The memory model option could be overridden on 
the command line. After looking for an "include" file in the current directory, the compiler will search each 
directory listed in the "i" path. See the section entitled "Open Watcom C/C++ #include File Processing" on 
page 72 for more information. 

Example: 

C>compiler_name grep -fo=..\obj\ 

The compiler processes the program contained in the file grep. c (pp) which is located in the current 
directory. The object file is placed in the directory . . \ob j under the name grep. ob j . 

Example: 

C>compiler_name -dDBG=l grep -fo=. .\obj\.dbo 

The compiler processes the program contained in the file grep. c (pp) which is located in the current 
directory. The macro "DBG" is defined so that conditional debugging statements that have been placed in 
the source are compiled. The object file is placed in the directory . . \ob j and its filename extension will 
be ".dbo" (instead of ".obj"). Selection of a different filename extension permits easy identification of 
object files that have been compiled with debugging statements. 

Example: 

C>compiler_name -g=GKS -s \gks\gopks 

The compiler generates code for gopks . c (pp) and places it into the "GKS" group. If the "g" option had 
not been specified, the code would not have been placed in any group. Assume that this file contains the 
definition of the routine gopengks as follows: 

void far gopengks( int workstation, long int h ) 

{ 


} 

For a small code model, the routine gopengks must be defined in this file as far since it is placed in 
another group. The "s" option is also specified to prevent a run-time call to the stack overflow check 
routine which will be placed in a different code segment at link time. The gopengks routine must be 
prototyped by C routines in other groups as 

void far gopengks( int workstation, long int h ) ; 
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since it will appear in a different code segment. 

3.5 Benchmarking Hints 

The Open Watcom C/C++ compiler contains many options for controlling the code to be produced. It is 
impossible to have a certain set of compiler options that will produce the absolute fastest execution times 
for all possible applications. With that said, we will list the compiler options that we think will give the 
best execution times for most applications. You may have to experiment with different options to see 
which combination of options generates the fastest code for your particular application. 

The recommended options for generating the fastest 16-bit Intel code are: 

Pentium Pro -onatx -oh -oi+ -ei -zp8 -6 -fpi87 -fp6 

Pentium -onatx -oh -oi+ -ei -zp8 -5 -fpi87 -fp5 

486 -onatx -oh -oi+ -ei -zp8 -4 -fpi87 -fp3 

386 -onatx -oh -oi+ -ei -zp8 -3 -fpi87 -fp3 

286 -onatx -oh -oi+ -ei -zp8 -2 -fpi87 -fp2 

186 -onatx -oh -oi+ -ei -zp8 -1 -fpi87 

8086 -onatx -oh -oi+ -ei -zp8 -0 -fpi87 

The recommended options for generating the fastest 32-bit Intel code are: 

Pentium Pro -onatx -oh -oi+ -ei -zp8 -6 -fp6 

Pentium -onatx -oh -oi+ -ei -zp8 -5 -fp5 

486 -onatx -oh -oi+ -ei -zp8 -4 -fp3 

386 -onatx -oh -oi+ -ei -zp8 -3 -fp3 

The "oi+" option is for C++ only. Under some circumstances, the "ob" and "ol+" optimizations may also 
give better performance with 32-bit Intel code. 

Option "on" causes the compiler to replace floating-point divisions with multiplications by the reciprocal. 
This generates faster code (multiplication is faster than division), but the result may not be the same 
because the reciprocal may not be exactly representable. 

Option "oe" causes small user written functions to be expanded in-line rather than generating a call to the 
function. Expanding functions in-line can further expose other optimizations that couldn’t otherwise be 
detected if a call was generated to the function. 

Option "oa" causes the compiler to relax alias checking. 

Option "ot" must be specified to cause the code generator to select code sequences which are faster without 
any regard to the size of the code. The default is to select code sequences which strike a balance between 
size and speed. 
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Option "ox" is equivalent to "obmiler" and "s" which causes the compiler/code generator to do branch 
prediction ("ob"), generate 387 instructions in-line for math functions such as sin, cos, sqrt ("om"), expand 
intrinsic functions in-line ("oi"), perform loop optimizations ("ol"), expand small user functions in-line 
("oe"), reorder instructions to avoid pipeline stalls ("or"), and to not generate any stack overflow checking 
("s"). Option "or" is very important for generating fast code for the Pentium and Pentium Pro processors. 

Option "oh" causes the compiler to attempt repeated optimizations (which can result in longer compiles but 
more optimal code). 

Option "oi+" causes the C++ compiler to expand intrinsic functions in-line (just like "oi") but also sets the 
inline_depth to its maximum (255). By default, inline_depth is 3. The inline_depth can also be changed by 
using the C++ inline_ depth pragma. 

Option "ei" causes the compiler to allocate at least an "int" for all enumerated types. 

Option "zp8" causes all data to be aligned on 8 byte boundaries. The default is "zp2" for the 16-bit 
compiler and "zp8" for 32-bit compiler. If, for example, "zpl" packing was specified then this would pack 
all data which would reduce the amount of data memory required but would require extra clock cycles to 
access data that is not on an appropriate boundary. 

Options "0", "1", "2", "3", "4", "5" and "6" emit Intel code sequences optimized for processor-specific 
instruction set features and timings. For 16-bit Intel applications, the use of these options may limit the 
range of systems on which the application will run but there are execution performance improvements. 

Options "fp2", "fp3", "fp5" and "fp6" emit Intel floating-point operations targetted at specific features of 
the math coprocessor in the Intel series. For 16-bit Intel applications, the use of these options may limit the 
range of systems on which the application will run but there are execution performance improvements. 

Option "fpi87" causes in-line Intel 80x87 numeric data processor instructions to be generated into the 
object code for floating-point operations. Floating-point instruction emulation is not included so as to 
obtain the best floating-point performance in 16-bit Intel applications. 

For 32-bit Intel applications, the use of the "fp5" option will give good performance on the Intel Pentium 
but less than optimal performance on the 386 and 486. The use of the "5" option will give good 
performance on the Pentium and minimal, if any, impact on the 386 and 486. Thus, the following set of 
options gives good overall performance for the 386, 486 and Pentium processors. 

-onatx -oh -oi+ -ei -zp8 -5 -fp3 

3.6 Compiler Diagnostics 

If the compiler prints diagnostic messages to the screen, it will also place a copy of these messages in a file 
in your current directory. The file will have the same file name as the source file and an extension of ".err". 
The compiler issues two types of diagnostic messages, namely warnings or errors. A warning message 
does not prevent the production of an object file. However, error messages indicate that a problem is 
severe enough that it must be corrected before the compiler will produce an object file. The error file is a 
handy reference when you wish to correct the errors in the source file. 

Just to illustrate the diagnostic features of Open Watcom C/C++, we will modify the "hello" program in 
such a way as to introduce some errors. 


Compiler Diagnostics 69 




Open Watcom C/C++ User’s Guide 


Example: 

♦include <stdio.h> 

int main() 

{ 

int x; 

printf( "Hello world\n" ) ; 
return( y ); 

} 

The equivalent C++ program follows: 

Example: 

♦include <iostream.h> 

♦include <iomanip.h> 

int main () 

{ 

int x; 

cout << "Hello world" << endl; 
return( y ); 

} 

In this example, we have added the lines: 
int x; 


and 


return ( y ); 

and changed the keyword void to int. 

We compile the program with the "warning" option. 

Example: 

C>compiler_name hello -w3 
For the C program, the following output appears on the screen. 

hello.c(7): Error! E1011: Symbol 'y' has not been declared 
hello.c(5): Warning! W202: Symbol 'x' has been defined, but not 

referenced 

hello.c: 8 lines, included 174, 1 warnings, 1 errors 

For the C++ program, the following output appears on the screen. 

hello.cpp(8): Error! E029: (col 13) symbol 'y' has not been declared 
hello.cpp(9): Warning! W014: (col 1) no reference to symbol 'x' 
hello.cpp(9): Note! N392: (col 1) 'int x' in 'int main( void )' 
defined in: hello.cpp(6) (col 9) 
hello.cpp: 9 lines, included 1628, 1 warning, 1 error 

Here we see an example of both types of messages. An error and a warning message have been issued. As 
indicated by the error message, we require a declarative statement for the identifier y. The warning 
message indicates that, while it is not a violation of the rules of C/C++ to define a variable without ever 
using it, we probably did not intend to do so. Upon examining the program, we find that: 
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1. the variable x should have been assigned a value, and 

2. the variable y has probably been incorrectly typed and should have been entered as x. 

The complete list of Open Watcom C/C++ diagnostic messages is presented in an appendix of this guide. 

3.7 Open Watcom C/C++ include File Processing 

When using the #include preprocessor directive, a header is identified by a sequence of characters 
placed between the "<" and ">" delimiters (e.g., <file>) and a source file is identified by a sequence of 
characters enclosed by quotation marks (e.g., "file"). Open Watcom C/C++ makes a distinction between 
the use of "<>" or quotation marks to surround the name of the file to be included. The search techniques 
for header files and source files are slightly different. Consider the following example. 

Example: 

♦include <stdio.h> /* a system header file */ 

♦include "stdio.h" /* your own header or source file */ 

You should use "<" and ">" when referring to standard or system header files and quotation marks when 
referring to your own header and source files. 

The character sequence placed between the delimiters in an ♦include directive represents the name of 
the file to be included. The file name may include drive, path, and extension. 

It is not necessary to include the drive and path specifiers in the file specification when the file resides on a 
different drive or in a different directory. Open Watcom C/C++ provides a mechanism for looking up 
include files which may be located in various directories and disks of the computer system. Open Watcom 
C/C++ searches directories for header and source files in the following order (the search stops once the file 
has been located): 

1. If the file specification enclosed in quotation marks ("file-spec") or angle brackets (<file-spec>) 
contains the complete drive and path specification, that file is included (provided it exists). No 
other searching is performed. The drive need not be specified in which case the current drive is 
assumed. 

2. Next, if the "xx" option was not specified and the file specification is enclosed in quotation 
marks then the current directory is searched. 

3. Next, if the file specification is enclosed in quotation marks, the directory of the file containing 
the ♦include directive is searched. 

4. Next, if the "xx" option was not specified and the current file is also an ♦include file then the 
directory of the parent file is searched next. This search continues recursively through all the 
nested ♦include files until the original source file’s directory is searched. 

5. Next, if the file specification enclosed in quotation marks ("file-spec") or in angle brackets 
(<file-spec>), each directory listed in the "i" path is searched (in the order that they were 
specified). 

6. Next, if the "x" option was not specified, each directory listed in the <os>_INCLUDE 
environment variable is searched (in the order that they were specified). The environment 
variable name is constructed from the current build target name. The default build targets are: 
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DOS when the host operating system is DOS, 

OS2 when the host operating system is OS/2, 

NT when the host operating system is Windows NT/95, or 

QNX when the host operating system is QNX. 

LINUX when the host operating system is Linux. 

For example, the environment variable OS2_INCLUDE will be searched if the build target is 
"OS2". The build target would be OS/2 if: 

1. the host operating system is OS/2 and the "bt" option was not specified, or 

2. the "bt=OS2" option was explicitly specified. 

7. Next, if the "x" option was not specified, each directory listed in the INCLUDE environment 
variable is searched (in the order that they were specified). 

8. Finally, if the "xx" option was not specified and the file specification is enclosed in quotation 
marks then an adjacent "H" directory (i.e., . . \h) is searched if it exists. 

In the above example, <stdio . h> and " stdio. h" could refer to two different files if there is a 
stdio . h in the current directory and one in the Open Watcom C/C++ include file directory 
( \WATCOM\H) and the current directory is not listed in an "i" path or the INCLUDE environment 
variable. 

The compiler will search the directories listed in "i" paths (see description of the "i" option) and the 
INCLUDE environment variable in a manner analogous to that which the operating system shell will use 
when searching for programs by using the PATH environment variable. 

The "SET" command is used to define an INCLLTDE environment variable that contains a list of 
directories. A command of the form 

SET INCLUDE=[d:]path;[d:]path... 

is issued before running Open Watcom C/C++ the first time. The brackets indicate that the drive "d:" is 
optional and the ellipsis indicates that any number of paths may be specified. For Windows NT, use the 
"System" icon in the Control Panel to define environment variables. 

We illustrate the use of the ((include directive in the following example. 

Example: 

♦include <stdio.h> 

♦include <time.h> 

♦include <dos.h> 
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♦include "common.c" 

int main() 

{ 

initialize(); 
update_ files(); 
create_ report(); 
finalize(); 

} 

♦include "parti.c" 

♦include "part2.c" 

If the above text is stored in the source file report. c in the current directory then we might issue the 
following commands to compile the application. 

Example: 

Orem — Two places to look for include files 
C>set include=c:\watcom\h;b:\headers 
Orem — Now compile application specifying a 
Orem third location for include files 
C >compiler_name report -fo=..\obj\ -i=. Asource 

In the above example, the "SET" command is used to define the INCLUDE environment variable. It 
specifies that the \watcom\h directory (of the "C" disk) and the \headers directory (a directory of the 
"B" disk) are to be searched. 

The Open Watcom C/C++ "i" option defines a third place to search for include files. The advantage of the 
INCLUDE environment variable is that it need not be specified each time the compiler is run. 


3.8 Open Watcom C/C++ Preprocessor 

The Open Watcom C/C++ preprocessor forms an integral part of Open Watcom C/C++. When any form of 
the "p" option is specified, only the preprocessor is invoked. No code is generated and no object file is 
produced. The output of the preprocessor is written to the standard output file, although it can also be 
redirected to a file using the "fo" option. Suppose the following C/C++ program is contained in the file 
msgid.c. 
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Example: 

♦define _ IBMPC 0 
♦define _ IBMPS2 1 

♦ if _ TARGET == _ IBMPS2 
char *SysId = { "IBM PS/2" }; 

♦ else 

char *SysId = { "IBM PC" }; 

♦endif 

/* Return pointer to System Identification */ 

char *GetSysId() 

{ 

return( Sysld ) ; 

} 

We can use the Open Watcom C/C++ preprocessor to generate the C/C++ code that would actually be 
compiled by the compiler by issuing the following command. 

Example: 

C>compiler_name msgid -pic -fo -d_ TARGET=_ IBMPS2 
The file msgid. i will be created and will contain the following C/C++ code. 

♦line 1 "msgid.c" 


char *SysId = { "IBM PS/2" }; 

♦line 9 "msgid.c" 

/* Return pointer to System Identification */ 

char *GetSysId() 

{ 

return( Sysld ); 

} 

Note that the file msgid. i can be used as input to the compiler. 

Example: 

C>compiler_name msgid. i 

Since ♦line directives are present in the file, the compiler can issue error messages in terms of the 
original source file line numbers. 
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3.9 Open Watcom C/C++ Predefined Macros 

In addition to the standard ISO-defined macros supported by the Open Watcom C/C++ compilers, several 
additional system-dependent macros are also defined. These are described in this section. See the Open 
Watcom C Language Reference manual for a description of the standard macros. 

The Open Watcom C/C++ compilers run on various host operating systems including DOS, OS/2, 

Windows NT, Windows 95 and QNX. Any of the supported host operating systems can be used to develop 
applications for a number of target systems. By default, the target operating system for the application is 
the same as the host operating system unless some option or combination of options is specified. For 
example, DOS applications are built on DOS by default, OS/2 applications are built on OS/2 by default, 
and so on. But the flexibility is there to build applications for other operating systems/environments. 


The macros described below may be used to identify the target system for which the application is being 

compiled. (Note: In several places in the following text, a pair of underscore characters appears as_ 

which resembles a single, elongated underscore.) 

The Open Watcom C/C++ compilers support both 16-bit and 32-bit application development. The 
following macros are defined for 16-bit and 32-bit target systems. 

16-bit 32-bit 


_X8 6_ _X86_ 

_186_ _ 386_ 

M_ 186 M_ 1386 

_ M_ 186 _ M_ 1386 

_ M_ 1X8 6 _ M_ 1X8 6 


Notes: 

1. The_X8 6_identifies the target as an Intel environment. 

2. The_18 6_ 1+ 18 6 and_ M_ 18 6 macros identify the target as a 16-bit Intel environment. 

3. The_ 3 8 6_ 1+ 138 6 and_ M_ 138 6 macros identify the target as a 32-bit Intel environment. 

4. The _ M_ 1X8 6 macro is identically equal to 100 times the architecture compiler option value (-0, 
-1, -2, -3, -4, -5, etc.). If "-5" (Pentium instruction timings) was specified as a compiler option, 
then the value of _ M_ 1X8 6 would be 500. 

The Open Watcom C/C++ compilers support application development for a variety of operating systems. 

The following macros are defined for particular target operating systems. 


Target 

Macros 



DOS 

_ _ DOS_, 

-DOS, MSDOS 

OS/2 

_OS2_ 



QNX 

_QNX_, 

_ UNIX_ 

Netware 

_ NETWARE_ 

— r 

_NETWARE- 386_ 

NT 

_NT_ 



Windows 

_ WINDOWS- 

— r 

-WINDOWS,_WINDOWS- 

Linux 

_ LINUX_ 

r — _ 

_ UNIX_ 
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Notes: 

1. The_DOS_DOS andMSDOS macros are defined when the build target is "DOS" (16-bit 

DOS or 32-bit extended DOS). 

2. The_OS2_macro is defined when the build target is "OS2" (16-bit or 32-bit OS/2). 

3. The_QNX_and_ UNIX_macros are defined when the build target is "QNX" (16-bit or 

32-bit QNX). 

4. The_NETWARE_and_ NETWARE_ 38 6_macros are defined when the build target is 

"NETWARE" (Novell NetWare). 

5. The_NT_macro is defined when the build target is "NT" (Windows NT and Windows 95). 

6. The_WINDOWS_macro is defined when the build target is "WINDOWS" or one of the "zw", 

"zW", "zWs" options is specified (identifies the target operating system as 16-bit Windows or 
32-bit extended Windows but not Windows NT or Windows 95). 

7. The _ WINDOWS macro is defined when the build target is "WINDOWS" or one of the "zw", 

"zW", "zWs" options is specified and you are using a 16-bit compiler (identifies the target 
operating system as 16-bit Windows). 

8. The_WINDOWS_ 38 6_macro is defined when the build target is "WINDOWS" or the "zw" 

option is specified and you are using a 32-bit compiler (identifies the target operating system as 
32-bit extended Windows). 

9. The_LINUX_and_ UNIX_macros are defined when the build target is "LINUX" (32-bit 

Linux). 

The following macros are defined for the indicated options. 


Option 

Macro 

bm 

_ MT 

br 

_ DLL 

fpi 

_FPI_ 

fpi87 

_FPI_ 

j 

_ CHAR_ SIGNED_ 

oi 

_INLINE_ FUNCTIONS_ 

xr 

_ CPPRTTI (C++ only) 

xs 

_ CPPUNWIND (C++ only) 

xss 

_ CPPUNWIND (C++ only) 

xst 

_ CPPUNWIND (C++ only) 

za 

NO_ EXT_ KEYS 

zw 

_WINDOWS. 

zW 

_WINDOWS- 

zWs 

WINDOWS 


The following memory model macros are defined for the indicated memory model options. 
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Option 

All 

16- 

■bit only 


32-bit only 



mf 

FLAT 





M 386FM M : 

386FM 

ms 

_ SMALL_ 

_ M_ 

_ I86SM 

M_ 

I86SM 

_ M_ 386SM 

M_ 

386SM 

mm 

_ MEDIUM_ 

_ M_ 

_I86MM 

M_ 

I8 6MM 

_ M_ 386MM 

M_ 

38 6MM 

me 

_COMPACT_ 

_ M_ 

_ I86CM 

M_ 

I8 6CM 

_ M_ 386CM 

M_ 

38 6CM 

ml 

_ LARGE_ 

_ M_ 

_I86LM 

M_ 

I8 6LM 

_ M_ 386LM 

M_ 

38 6LM 

mh 

HUGE 

M 

I86HM 

M 

I8 6HM 





The following macros indicate which compiler is compiling the C/C++ source code. 

_ cplusplm Open Watcom C++ predefines the macro_cplusplus to identify the compiler as a 

C++ compiler. 


WATCOMC_ 

Open Watcom C/C++ predefines the macro_ WATCOMC _to identify the compiler as one 

of the Open Watcom C/C++ compilers. 

The value of the macro depends on the version number of the compiler. The value is 100 
times the version number (version 8.5 yields 850, version 9.0 yields 900, etc.). Note that 
for Open Watcom 1.0, the value of this macro is 1200, for Open Watcom 1.1 it is 1210 etc. 

WATCOMJCPLUSPLUS _ 

Open Watcom C++ predefines the macro_ WATCOM_ CPLUSPLUS _to identify the 

compiler as one of the Open Watcom C++ compilers. 


The value of the macro depends on the version number of the compiler. The value is 100 
times the version number (version 10.0 yields 1000, version 10.5 yields 1050, etc.). Note 
that for Open Watcom 1.0, the value of this macro is 1200, for Open Watcom 1.1 it is 1210 
etc. 

The following macros are defined for compatibility with Microsoft. 

_ CPPRTTI Open Watcom C++ predefines the_ CPPRTTI macro to indicate that C++ Run-Time 

Type Information (RTTI) is in force. This macro is predefined if the Open Watcom C++ 
"xr" compile option is specified and is not defined otherwise. 

_ CPP UNWIND 

Open Watcom C++ predefines the_ CPPUNWIND macro to indicate that C++ exceptions 

supported. This macro is predefined if any of the Open Watcom C++ "xs", "xss" or "xst" 
compile options are specified and is not defined otherwise. 

_INTEGRAL_MAX_BITS 

Open Watcom C/C++ predefines the _ INTEGRAL_ MAX_ BITS macro to indicate that 

maximum number of bits supported in an integral type (see the description of the "_int64" 

keyword in the next section). Its value is 64 currently. 

_P USHPOP_S VPPORTED 

Open Watcom C/C++ predefines the _ PUSHPOP_ SUPPORTED macro to indicate that 
♦pragma pack (push) and #pragma pack (pop) are supported. 

STDCA UNSUPPORTED 

Open Watcom C/C++ predefines the _ STDCALL_ SUPPORTED macro to indicate that the 
standard 32-bit Win32 calling convention is supported. 
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The following table summarizes the predefined macros supported by the compilers and the values that the 
respective compilers assign to them. A "yes" under the column means that the compiler supports the macro 
with the indicated value. Note that the C and C++ compilers sometime support the same macro but with 
different values (including no value which means the symbol is defined without a value). 
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Predefined Macro Supported by Compiler 


and Setting 

wcc 

wcc386 

wpp 

wpp386 

note 

386 =1 


Yes 


Yes 


3R =1 




Yes 


_ based=_based 

Yes 

Yes 

Yes 

Yes 

extension 

cdecl= cdecl 

Yes 

Yes 

Yes 

Yes 

extension 

cdecl=_cdecl 

Yes 

Yes 

Yes 

Yes 

extension 

_ cplusplus=l 



Yes 

Yes 


_ CPPRTTI=1 



Yes 

Yes 


_ CPPUNWIND=1 



Yes 

Yes 


_ export=_export 

Yes 

Yes 

Yes 

Yes 

extension 

far!6= farl6 

Yes 

Yes 

Yes 

Yes 

extension 

_ far=_far 

Yes 

Yes 

Yes 

Yes 

extension 

far=_far 

Yes 

Yes 

Yes 

Yes 

extension 

_ fastcall=_ fastcall 

Yes 

Yes 

Yes 

Yes 

extension 

FLAT =1 


Yes 


Yes 


_ fortran=_fortran 

Yes 

Yes 

Yes 

Yes 

extension 

fortran=_fortran 

Yes 

Yes 

Yes 

Yes 

extension 

_FPI_=1 

Yes 

Yes 

Yes 

Yes 


_ huge=_huge 

Yes 

Yes 

Yes 

Yes 

extension 

huge=_huge 

Yes 

Yes 

Yes 

Yes 

extension 

186 =1 

Yes 


Yes 



_ inline=_inline 

Yes 

Yes 

Yes 

Yes 

extension 

INTEGRAL MAX BITS=64 

Yes 

Yes 

Yes 

Yes 


_ interrupt=_interrupt 

Yes 

Yes 

Yes 

Yes 

extension 

interrupt=_ interrupt 

Yes 

Yes 

Yes 

Yes 

extension 

loadds= loadds 

Yes 

Yes 

Yes 

Yes 

extension 

_ M_ 386FM=1 


Yes 


Yes 


M_ 386FM=1 


Yes 


Yes 

extension 

_ M_ 1386=1 


Yes 


Yes 


M_ 1386=1 


Yes 


Yes 

extension 

_ M_ 18 6=1 

Yes 


Yes 



M_ 186=1 

Yes 


Yes 


extension 

_ M_ I86SM=1 

Yes 


Yes 



M_ I86SM=1 

Yes 


Yes 


extension 

_ M_ 1X86=0 

Yes 


Yes 



_ M_ 1X86=500 


Yes 


Yes 


_ near=_near 

Yes 

Yes 

Yes 

Yes 

extension 

near=_near 

Yes 

Yes 

Yes 

Yes 

extension 

_NT_=1 (on Win32 platform) Yes 

Yes 

Yes 

Yes 

_ pascal=_pascal 

Yes 

Yes 

Yes 

Yes 

extension 

pascal=_pascal 

Yes 

Yes 

Yes 

Yes 

extension 

_ saveregs=_saveregs 

Yes 

Yes 

Yes 

Yes 

extension 

_ segment =_segment 

Yes 

Yes 

Yes 

Yes 

extension 

_ segname=_segname 

Yes 

Yes 

Yes 

Yes 

extension 

self= self 

Yes 

Yes 

Yes 

Yes 

extension 

_SMALL_=1 

Yes 


Yes 



SOMDLINK=_far 

Yes 




extension 

SOMDLINK=_ Syscall 


Yes 


Yes 

extension 

SOMLINK=_cdecl 

Yes 




extension 

SOMLINK=_ Syscall 


Yes 


Yes 

extension 

_ STDCALL_ SUPPORTED=l 


Yes 


Yes 


_ SW_ 0 = 1 

Yes 


Yes 



_ SW_ 3R=1 


Yes 


Yes 


_ SW_ 5=1 


Yes 


Yes 


_ SW_ FP287 = 1 



Yes 



_ SW_ FP2 = 1 

Yes 





_ SW_ FP387 = 1 




Yes 


_ SW_ FP3=1 


Yes 




SW FP1=1 

Yes 

Yes 

Yes 

Yes 


_SW_ MF=1 


Yes 


Yes 


SW MS=1 

Yes 


Yes 



_SW_ ZDP=1 

Yes 

Yes 

Yes 

Yes 


SW ZFP=1 

Yes 

Yes 

Yes 

Yes 


_SW_ ZGF=1 


Yes 


Yes 


SW ZGP=1 

Yes 


Yes 



_ stdcall=_stdcall 

Yes 

Yes 

Yes 

Yes 

extension 

_ syscall=_syscall 

Yes 

Yes 

Yes 

Yes 

extension 

WATCOM CPLUSPLUS = 

2000 


Yes 

Yes 


WATCOMC =2000 

Yes 

Yes 

Yes 

Yes 
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_X86_=1 Yes Yes Yes Yes 

Note: "extension" mean it is old extension macros (non-ISO compliant names). Thay are suppressed by 
following options: -zam, -za, -zA 


3.10 Open Watcom C/C++ Extended Keywords 

Open Watcom C/C++ supports the use of some special keywords to describe system dependent attributes of 
functions and other object names. These attributes are inspired by the Intel processor architecture and the 
plethora of function calling conventions in use by compilers for this architecture. In keeping with the ISO 

C and C++ language standards. Open Watcom C/C++ uses the double underscore (i.e., "_") or single 

underscore followed by uppercase letter (e.g., "_S") prefix with these keywords. To support compatibility 
with other C/C++ compilers, alternate forms of these keywords are also supported through predefined 
macros. 


near 


-Jar 


huge 


based 


Open Watcom C/C++ supports the_near keyword to describe functions and other object 

names that are in near memory and pointers to near objects. 

Open Watcom C/C++ predefines the macros near and _ near to be equivalent to the 
_near keyword. 

Open Watcom C/C++ supports the_far keyword to describe functions and other object 

names that are in far memory and pointers to far objects. 

Open Watcom C/C++ predefines the macros far, _ far andSOMDLINK (16-bit only) to 
be equivalent to the_far keyword. 

Open Watcom C/C++ supports the_huge keyword to describe functions and other object 

names that are in huge memory and pointers to huge objects. The 32-bit compilers treat 
these as equivalent to far objects. 

Open Watcom C/C++ predefines the macros huge and _ huge to be equivalent to the 
_huge keyword. 

Open Watcom C/C++ supports the_based keyword to describe pointers to objects that 

appear in other segments or the objects themselves. See the section entitled "Based 
Pointers" on page 88 for an explanation of the_based keyword. 

Open Watcom C/C++ predefines the macro _ based to be equivalent to the_based 

keyword. 


segment Open Watcom C/C++ supports the_segment keyword which is used when describing 

objects of type segment. See the section entitled "Based Pointers" on page 88 for an 
explanation of the_segment keyword. 

Open Watcom C/C++ predefines the macro _ segment to be equivalent to the 
_segment keyword. 

segname Open Watcom C/C++ supports the_segname keyword which is used when describing 

segname constant based pointers or objects. See the section entitled "Based Pointers" on 
page 88 for an explanation of the_segname keyword. 
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self 


restrict 


Packed 


cdecl 


_ pascal 


fortran 


Open Watcom C/C++ predefines the macro _ segname to be equivalent to the 
_segname keyword. 

Open Watcom C/C++ supports the_self keyword which is used when describing self 

based pointers. See the section entitled "Based Pointers" on page 88 for an explanation of 
the_self keyword. 

Open Watcom C/C++ predefines the macro _ self to be equivalent to the_ self 

keyword. 

Open Watcom C/C++ provides the_ restrict type qualifier as an alternative to the ISO C99 

restrict keyword; it is supported even when C99 keywords aren't visible. This type 
qualifier is used as an optimization hint. Any object accessed through a restrict qualified 
pointer may only be accessed through that pointer and the compiler may assume that there 
will be no aliasing. 

Open Watcom C/C++ supports the _ Packed keyword which is used when describing a 
structure. If specified before the struct keyword, the compiler will force the structure to be 
packed (no alignment, no gaps) regardless of the setting of the command-line option or the 
#pragma controlling the alignment of members. 

Open Watcom C/C++ supports the_ cdecl keyword to describe C functions that are 

called using a special convention. 

Notes: 

1. All symbols are preceded by an underscore character. 

2. Arguments are pushed on the stack from right to left. That is, the last argument 
is pushed first. The calling routine will remove the arguments from the stack. 

3. Floating-point values are returned in the same way as structures. When a 
structure is returned, the called routine returns a pointer in register AX/EAX to 
the return value which is stored in the data segment (DGROUP). 

4. For the 16-bit compiler, registers AX, BX, CX and DX, and segment register ES 
are not saved and restored when a call is made. 

5. For the 32-bit compiler, registers EAX, ECX and EDX are not saved and 
restored when a call is made. 

Open Watcom C/C++ predefines the macros cdecl, _ cdecl,_ Cdecl andSOMLINK 
(16-bit only) to be equivalent to the_ cdecl keyword. 

Open Watcom C/C++ supports the_pascal keyword to describe Pascal functions that 

are called using a special convention described by a pragma in the "stddef.h" header file. 

Open Watcom C/C++ predefines the macros pascal, _ pascal and_ Pascal to be 
equivalent to the_ pascal keyword. 

Open Watcom C/C++ supports the_ fortran keyword to describe functions that are 

called from FORTRAN. It converts the name to uppercase letters and suppresses the 
which is appended to the function name for certain calling conventions. 
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Open Watcom C/C++ predefines the macros fortran and _ fortran to be equivalent to 
the_fortran keyword. 

interrupt Open Watcom C/C++ supports the_ interrupt keyword to describe a function that is 

an interrupt handler. 

Example: 

♦include <i86.h> 

void _ interrupt intlO( union INTPACK r ) 

{ 


} 

The code generator will emit instructions to save all registers. The registers are saved on 
the stack in a specific order so that they may be referenced using the "INTPACK" union as 
shown in the DOS example above. The code generator will emit instructions to establish 
addressability to the program’s data segment since the DS segment register contents are 
unpredictable. The function will return using an "IRET" (16-bit) or "IRETD" (32-bit) 
(interrupt return) instruction. 

Open Watcom C/C++ predefines the macros interrupt and _ interrupt to be 
equivalent to the_interrupt keyword. 

declspec( modifier ) 

Open Watcom C/C++ supports the_declspec keyword for compatibility with 

Microsoft C++. The_declspec keyword is used to modify storage-class attributes of 

functions and/or data. There are several modifiers that can be specified with the 

_declspec keywordthread, naked, noreturn, farss, dllimport, 

dllexport,_pragma ( "string" )„_cdecL,_pascal,_fortran, 

_stdcall, and_syscall. These attributes are a property only of the declaration of 

the object or function to which they are applied. Unlike the_near and_far 

keywords, which actually affect the type of object or function (in this case, 2- and 4-byte 
addresses), these storage-class attributes do not redefine the type attributes of the object 

itself. The_pragma modifier is supported by Open Watcom C++ only. 'T’hithread 

attribute affects data and objects only. The naked, noreturn, farss,_pragma, 

_cdecl,_pascal,_fortran,_stdcall, and_syscall attributes affect 

functions only. The dllimport and dllexport attributes affect functions, data, and 

objects. For more information on the_declspec keyword, please see the section 

entitled "The_declspec Keyword" on page 92. 

export Open Watcom C/C++ supports the_export keyword to describe functions and other 

object names that are to be exported from a Microsoft Windows DLL, OS/2 DLL, or 
Netware NLM. See also the description of the "zu" option. 

Example: 

void_export _ Setcolor ( int color ) 

{ 


} 
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loadds 


saveregs 


stdcall 


Open Watcom C/C++ predefines the macro _ export to be equivalent to the_export 

keyword. 

Open Watcom C/C++ supports the_loadds keyword to describe functions that require 

specific loading of the DS register to establish addressability to the function’s data 
segment. This keyword is useful in describing a function that will be placed in a Microsoft 
Windows or OS/2 1.x Dynamic Link Library (DLL). See also the description of the "nd" 
and "zu" options. 

Example: 

void_export_loadds _ Setcolor ( int color ) 

{ 


} 

If the function in an OS/2 1 .x Dynamic Link Library requires access to private data, the 
data segment register must be loaded with an appropriate value since it will contain the DS 
value of the calling application upon entry to the function. 

Open Watcom C/C++ predefines the macro _ loadds to be equivalent to the_loadds 

keyword. 

Open Watcom C/C++ recognizes the_saveregs keyword which is an attribute used by 

C/C++ compilers to describe a function that must save and restore all registers. 

Open Watcom C/C++ predefines the macro _ saveregs to be equivalent to the 
_saveregs keyword. 

(32-bit only) The_stdcall keyword may be used with function definitions, and 

indicates that the 32-bit Win32 calling convention is to be used. 

Notes: 

1. All symbols are preceded by an underscore character. 

2. All C symbols (extern "C" symbols in C++) are suffixed by "@nnn" where 
"nnn" is the sum of the argument sizes (each size is rounded up to a multiple of 4 
bytes so that char and short are size 4). When the argument list contains the 
"@nnn" suffix is omitted. 

3. Arguments are pushed on the stack from right to left. That is, the last argument 
is pushed first. The called routine will remove the arguments from the stack. 

4. When a structure is returned, the caller allocates space on the stack. The address 
of the allocated space will be pushed on the stack immediately before the call 
instruction. Upon returning from the call, register EAX will contain address of 
the space allocated for the return value. Floating-point values are returned in 
80x87 register ST(0). 

5. Registers EAX, ECX and EDX are not saved and restored when a call is made. 
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_ syscall (32-bit only) The_syscall keyword may be used with function definitions, and 

indicates that the calling convention used is compatible with functions provided by 32-bit 
OS/2. 

Notes: 

1. Symbols names are not modified, that is, they are not adorned with leading or 
trailing underscores. 

2. Arguments are pushed on the stack from right to left. That is, the last argument 
is pushed first. The calling routine will remove the arguments from the stack. 

3. When a structure is returned, the caller allocates space on the stack. The address 
of the allocated space will be pushed on the stack immediately before the call 
instruction. Upon returning from the call, register EAX will contain address of 
the space allocated for the return value. Floating-point values are returned in 
80x87 register ST(0). 

4. Registers EAX, ECX and EDX are not saved and restored when a call is made. 

Open Watcom C/C++ predefines the macros _ syscall^ System.SOMLINK (32-bit 
only) and SOMDLINK (32-bit only) to be equivalent to the_ syscall keyword. 

far 16 (32-bit only) Open Watcom C/C++ recognizes the_f ar 16 keyword which can be used 

to define far 16-bit (farl6) pointers (16-bit selector with 16-bit offset) or far 16-bit function 
prototypes. This keyword can be used under 32-bit OS/2 to call 16-bit functions from your 
32-bit flat model program. Integer arguments will automatically be converted to 16-bit 
integers, and 32-bit pointers will be converted to farl6 pointers before calling a special 
thunking layer to transfer control to the 16-bit function. 

Open Watcom C/C++ predefines the macros _ f ar 16 and_ Far 16 to be equivalent to the 
_f ar 16 keyword. This keyword is compatible with Microsoft C. 

In the OS/2 operating system (version 2.0 or higher), the first 512 megabytes of the 4 
gigabyte segment referenced by the DS register is divided into 8192 areas of 64K bytes 
each. A farl6 pointer consists of a 16-bit selector referring to one of the 64K byte areas, 
and a 16-bit offset into that area. 

A pointer declared as, 

[type]_farl6 *name; 

defines an object that is a farl6 pointer. If such a pointer is accessed in the 32-bit 
environment, the compiler will generate the necessary code to convert between the farl6 
pointer and a "flat" 32-bit pointer. 

For example, the declaration, 

char _farl6 *bufptr; 

declares the object bufptr to be a farl6 pointer to char. 

A function declared as. 
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_Segl6 


[type]_farl6 func( [arg_list]); 

declares a 16-bit function. Any calls to such a function from the 32-bit environment will 
cause the compiler to convert any 32-bit pointer arguments to farl6 pointers, and any int 
arguments from 32 bits to 16 bits. (In the 16-bit environment, an object of type int is only 
16 bits.) Any return value from the function will have its return value converted in an 
appropriate manner. 

For example, the declaration, 

char * _farl6 Scan( char *buffer, int len, short err ); 

declares the 16-bit function Scan. When this function is called from the 32-bit 
environment, the buffer argument will be converted from a flat 32-bit pointer to a farl6 

pointer (which, in the 16-bit environment, would be declared as char_far *. The 

len argument will be converted from a 32-bit integer to a 16-bit integer. The err 
argument will be passed unchanged. Upon returning, the farl6 pointer (far pointer in the 
16-bit environment) will be converted to a 32-bit pointer which describes the equivalent 
location in the 32-bit address space. 

(32-bit only) Open Watcom C/C++ recognizes the _ Segl 6 keyword which has a similar 

but not identical function as the_f ar 16 keyword described above. This keyword is 

compatible with IBM C Set/2 and IBM VisualAge C++. 

In the OS/2 operating system (version 2.0 or higher), the first 512 megabytes of the 4 
gigabyte segment referenced by the DS register is divided into 8192 areas of 64K bytes 
each. A farl6 pointer consists of a 16-bit selector referring to one of the 64K byte areas, 
and a 16-bit offset into that area. 

Note that _ Segl 6 is not interchangeable with_f ar 16. 

A pointer declared as, 

[type] * _Segl6 name; 

defines an object that is a farl6 pointer. Note that the _ Segl 6 appears on the right side of 
the * which is opposite to the_f ar 16 keyword described above. 

For example, 

char * _ Segl6 bufptr; 

declares the object bufptr to be a farl6 pointer to char (the same as above). 

The _ Segl 6 keyword may not be used to describe a 16-bit function. A #pragma directive 
must be used instead. A function declared as, 

[type] * _Segl6 func( [parm_list]); 

declares a 32-bit function that returns a farl6 pointer. 

For example, the declaration, 

char * _ Segl6 Scan( char * buffer, int len, short err ); 
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declares the 32-bit function Scan. No conversion of the argument list will take place. 

The return value is a farl6 pointer. 

_ pragma Open Watcom C++ supports the_pragma keyword to support in-lining of member 

functions. The_pragma keyword must be followed by parentheses containing a string 

that names an auxiliary pragma. Here is a simplified example showing usage and syntax. 

Example: 

#pragma aux fast_ mul = \ 

"imul eax,edx" \ 

parm caller [eax] [edx] \ 

value struct; 

struct fixed { 
unsigned v; 

In¬ 
fixed _pragma! "fast_mul") operator *( fixed, fixed ); 

fixed two = { 2 }; 
fixed three = { 3 }; 

fixed foo() 

{ 

return two * three; 

} 

See the chapters entitled "16-bit Pragmas" on page 139 and "32-bit Pragmas" on page 207 
for more information on pragmas. 

_ iutS Open Watcom C/C++ supports the_int8 keyword to define 8-bit integer data objects. 

Example: 

static _int8 smalllnt; 

Also supported are signed and unsigned 8-bit integer constants. The_int8 data type 

will be unsigned by default if the compiler is invoked with the -j switch. 

_ hit16 Open Watcom C/C++ supports the_int 16 keyword to define 16-bit integer data objects. 

Example: 

static _intl6 shortlnt; 

Also supported are signed and unsigned 16-bit integer constants. 

_ int32 Open Watcom C/C++ supports the_int32 keyword to define 32-bit integer data objects. 

Example: 

static _int32 longlnt; 

Also supported are signed and unsigned 32-bit integer constants. 

_ hit64 Open Watcom C/C++ supports the_int 64 keyword to define 64-bit integer data objects. 
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Example: 

static _int64 biglnt; 

Also supported are signed and unsigned 64-bit integer constants. 

signed _ int64 Use the "i64" suffix for a signed 64-bit integer constant. 

Example: 

12345i64 

12345164 

unsigned _ int64 Use the "ui64" suffix for an unsigned 64-bit integer constant. 

Example: 

12345Ui64 

12345uI64 

The run-time library supports formatting of_int64 items (see the description of the 

print f library function). 

Example: 

#include <stdio.h> 

♦include <limits.h> 

void main() 

{ 

_int64 bigint; 

_int64 bigint2; 

bigint2 = 8164 * (LONG_ MAX + 1164); 
for ( bigint = 0; 

bigint <= bigint2; 
bigint += bigint2 / 16 ) { 

printf( "Hello world %Ld\n", bigint ); 

} 

} 

Restrictions 

switch An_ int 64 expression cannot be used in a switch statement. 

bit fields More than 32 bits in a 64-bit bitfield is not supported. 


3.11 Based Pointers 


Near pointers are generally the most efficient type of pointer because they are small, and the compiler can 
assume knowledge about what segment of the computer’s memory the pointer (offset) refers to. Far 
pointers are the most flexible because they allow the programmer to access any part of the computer’s 
memory, without limitation to a particular segment. However, far pointers are bigger and slower because 
of the additional flexibility. 

Based pointers are a compromise between the efficiency of near pointers and the flexibility of far pointers. 
With based pointers, the programmer takes responsibility to tell the compiler which segment a near pointer 
(offset) belongs to, but may still access segments of the computer’s memory outside of the normal data 
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segment (DGROUP). The result is a pointer type which is as small as and almost as efficient as a near 
pointer, but with most of the flexibility of a far pointer. 

An object declared as a based pointer falls into one of the following categories: 

• the based pointer is in the segment described by another object, 

• the based pointer, used as a pointer to another object of the same type (as in a linked list), refers to 
the same segment, 

• the based pointer is an offset to no particular segment, and must be combined explicitly with a 
segment value to produce a valid pointer. 

To support based pointers, the following keywords are provided: 

_based 

_ segment 

_ segname 

_self 

The following operator is also provided: 

: > 

These keywords and operator are described in the following sections. 

Two macros, defined in malloc . h, are also provided: 

_ NULLSEG 
_ NULLOFF 

They are used in a manner similar to NULL, but are used with objects declared as_segment and 

_based respectively. 

3.11.1 Segment Constant Based Pointers and Objects 

A segment constant based pointer or object has its segment value based on a specific, named segment. A 
segment constant based object is specified as: 

[type]_based!_segname( "segment")) object_name; 

and a segment constant based pointer is specified as: 

[type]_based!_segname! "segment")) *object-name; 

where segment is the name of the segment in which the pointer or object is based. As shown above, the 
segment name is always specified as a string. There are four special segment names recognized by the 
compiler: 

CODE" 

CONST" 

DATA" 

STACK" 

The CODE" segment is the default code segment. The"_ CONST" segment is the segment containing 
constant values. The DATA" segment is the default data segment. The"_ STACK" segment is the 
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segment containing the stack. If the segment name is not one of the recognized names, then a segment will 
be created with that name. If a segment constant based object is being defined, then it will be placed in the 
named segment. If a segment constant based pointer is being defined, then it can point at objects in the 
named segment. 

The following examples illustrate segment constant based pointers and objects. 

Example: 

int_based (_segname ( CODE" ) ) ival = 3; 

int_based (_segname ( CODE" ) ) *iptr; 

ival is an object that resides in the default code segment, iptr is an object that resides in the data 
segment (the usual place for data objects), but points at an integer which resides in the default code 
segment, iptr is suitable for pointing at ival. 

Example: 

char_based (_segname ( "GOODTHINGS" ) ) thing; 

thing is an object which resides in the segment GOODTHINGS, which will be created if it does not 
already exist. (The creation of segments is done by the linker, and is a method of grouping objects and 
functions. Nothing is implicitly created during the execution of the program.) 

3.11.2 Segment Object Based Pointers 

A segment object based pointer derives its segment value from another named object. A segment object 
based pointer is specified as follows: 

[type]_based( segment) *name; 

where segment is an object defined as type_segment. 

An object of type_segment may contain a segment value. Such an object is particularly designed for 

use with segment object based pointers. 

The following example illustrates a segment object based pointer: 

Example: 

_ segment seg; 

char_based( seg ) *cptr; 

The object seg contains only a segment value. Whenever the object cptr is used to point to a character, 
the actual pointer value will be made up of the segment value found in seg and the offset value found in 
cptr. The object seg might be assigned values such as the following: 

• a constant value (e.g., the segment containing screen memory), 

• the result of the library function bheapseg, 

• the segment portion of another pointer value, by casting it to the type_segment. 
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3.11.3 Void Based Pointers 


A void based pointer must be explicitly combined with a segment value to produce a reference to a memory 
location. A void based pointer does not infer its segment value from another object. The : > (base) 
operator is used to combine a segment value and a void based pointer. 

For example, on a personal computer running DOS with a color monitor, the screen memory begins at 
segment 0xB800, offset 0. In a video text mode, to examine the first character currently displayed on the 
screen, the following code could be used: 


Example: 

extern void main() 

{ 

_ segment screen; 

char _based( void ) *scrptr; 


} 


screen = 0xB800; 
scrptr = 0; 

printf ( "Top left character is '%c'.\n", 
*(screen:>scrptr) ); 


The general form of the : > operator is: 
segment :> offset 

where segment is an expression of type_segment, and>f f set is an expression of type_based ( 

void ) *. 


3.11.4 Self Based Pointers 

A self based pointer infers its segment value from itself. It is particularly useful for structures such as 
linked lists, where all of the list elements are in the same segment. A self based pointer pointing to one 
element may be used to access the next element, and the compiler will use the same segment as the original 
pointer. 

The following example illustrates a function which will print the values stored in the last two members of a 
linked list: 

Example: 

struct a { 

struct a_ based!_self ) *next; 

int number; 

} ; 
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extern void PrintLastTwo( struct a far *list ) 

{ 

_ segment seg; 

struct a _based( seg ) *aptr; 

seg = FP_ SEG( list ); 
aptr = FP_ OFF( list ); 

for ( ; aptr != _NULLOFF; aptr = aptr->next ) { 

if( aptr->next == _ NULLOFF ) { 

printf ( "Last item is %d\n", 
aptr->number ); 

} else if ( aptr->next->next == _ NULLOFF ) { 

printf( "Second last item is %d\n", 
aptr->number ); 

} 

} 


The argument to the function PrintLastTwo is a far pointer, pointing to a linked list structure anywhere 
in memory. It is assumed that all members of a particular linked list of this type reside in the same segment 
of the computer’s memory. ( Another instance of the linked list might reside entirely in a different 
segment.) The object seg is given the segment portion of the far pointer. The object aptr is given the 
offset portion, and is described as being based in the segment stored in seg. 

The expression aptr->next refers to the next member of the structure stored in memory at the offset 
stored in aptr and the segment implied by aptr, which is the value stored in seg. So far, the behavior 
is no different than if next had been declared as, 

struct a *next; 

The expression aptr->next->next illustrates the difference of using a self based pointer. The first 
part of the expression ( aptr->next) occurs as described above. However, using the result to point to 
the next member occurs by using the offset value found in the next member and combining it with the 
segment value of the pointer used to get to that member, which is still the segment implied by aptr, 

which is the value stored in seg. If next had not been declared using_based (_self ) , then 

the second pointing operation would refer to the offset value found in the next member, but with the 
default data segment (DGROUP), which may or may not be the same segment as stored in seg. 


3.12 The _declspec Keyword 

Open Watcom C/C++ supports the_declspec keyword for compatibility with Microsoft C++. The 

_declspec keyword is used to modify storage-class attributes of functions and/or data. 

declspec( thread ) is used to define thread local storage (TLS). TLS is the mechanism by which each 
thread in a multithreaded process allocates storage for thread-specific data. In standard 
multithreaded programs, data is shared among all threads of a given process, whereas 
thread local storage is the mechanism for allocating per-thread data. 
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Example: 

_declspec(thread) static int tls_ data = 0; 

The following rules apply to the use of the thread attribute. 

• The thread attribute can be used with data and objects only. 

• You can specify the thread attribute only on data items with static storage 
duration. This includes global data objects (both static and extern), local static 
objects, and static data members of classes. Automatic data objects cannot be 
declared with the thread attribute. The following example illustrates this error: 

Example: 

#define TLS _ declspec( thread 

void fund () 

{ 

TLS int tls_ data; 

} 

int func2 ( TLS int tls_ data ) // Wrong! 

{ 

return tls_ data; 

} 

• The thread attribute must be used for both the declaration and the definition of a 
thread local object, whether the declaration and definition occur in the same file or 
separate files. The following example illustrates this error: 

Example: 

#define TLS _declspec( thread ) 

extern int tls_ data; // This generates an error, 
because the 

TLS int tls_ data; // declaration and the 
definition differ. 

• Classes cannot use the thread attribute. However, you can instantiate class 
objects with the thread attribute, as long as the objects do not need to be 
constructed or destructed. For example, the following code generates an error: 

Example: 

#define TLS _ declspec( thread ) 

TLS class A // Wrong! Classes are not objects 

{ 

// Code 

} ; 

A AObject; 

Because the declaration of objects that use the thread attribute is permitted, these 
two examples are semantically equivalent: 


) 

// Wrong! 
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Example: 

#define TLS 
TLS class B 
{ 

// Code 
} BObject; 
local. 

class C 
{ 

// Code 

} ; 

TLS C CObject; // Okay! CObject declared thread 
local. 

• Standard C permits initialization of an object or variable with an expression 
involving a reference to itself, but only for objects of non-static extent. Although 
C++ normally permits such dynamic initialization of an object with an expression 
involving a reference to itself, this type of initialization is not permitted with thread 
local objects. 

Example: 

#define TLS _ 

TLS int tls_ i 
int j = j; 
error 

TLS int t1s_ k 

C++ 

Note that a sizeof expression that includes the object being initialized does not 
constitute a reference to itself and is allowed in C and C++. 

_declspec( naked ) indicates to the code generator that no prologue or epilogue sequence is to be 

generated for a function. Any statements other than "_asm" directives or auxiliary pragmas 
are not compiled. _asm Essentially, the compiler will emit a "label" with the specified 
function name into the code. 

Example: 

♦include <stdio.h> 

int _declspec( naked ) foo( int x ) 

{ 

_ asm { 

#if defined!_ 386_ ) 

inc eax 

♦ else 

inc ax 

♦endif 

ret 

} 

} 

void main() 

{ 

printf ( "%d\n", foo ( 1 ) ); 

} 


_ declspec( thread ) 

= tls_ i; // C and C++ error 

// Okay in C++; C 

= sizeof( tls_ k ) ; // Okay in C and 


declspec! thread ) 


// Okay! BObject declared thread 
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The following rules apply to the use of the naked attribute. 

• The naked attribute cannot be used in a data declaration. The following declaration 
would be flagged in error. 

Example: 

_declspec(naked) static int data_ object = 0; 

_declspec( noreturn ) indicates to the C/C++ compiler that function does not return. 

Example: 

♦include <stdio.h> 

int _ declspec( noreturn ) foo( int x ) 

{ 

x = -x; 
exit( x ); 

} 

void main() 

{ 

foo ( 0 ) ; 

} 

foo is defined to be a function that does not return. For example, it call exit to return to 
the system. In this case. Open Watcom C/C++ generates a "jmp" instruction instead of a 
"call" instruction to invoke foo. 

The following rules apply to the use of the noreturn attribute. 

• The noreturn attribute cannot be used in a data declaration. The following 
declaration would be flagged in error. 

Example: 

_declspec(noreturn) static int data_ object = 0; 

_declspec( farss ) indicates to the C/C++ compiler that function suppose SS != DS. Function uses far 

pointer to access automatic variables on the stack. It is alternative to -zu compiler option 
and can be used per function. 

Example: 

_ declspec( farss ) char * foo( char *s ); 

The following rules apply to the use of the farss attribute. 

• The farss attribute cannot be used in a data declaration. 

_declspec( dllimport) is used to declare functions, data and objects imported from a DLL. 
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Example: 

♦define DLLImport _declspec(dllimport) 

DLLImport void dll_ func(); 

DLLImport int dll_ data; 

Functions, data and objects are exported from a DLL by use of 

_declspec (dllexport) ct, the_ export keyword (for which 

_declspec (dllexport ) is the replacement), or through linker "EXPORT" 

directives. 

Note: When calling functions imported from other modules, it is not strictly necessary to 

use the_ declspec (dllimport ) modifier to declare the functions. This modifier 

however must always be used when importing data or objects to ensure correct behavior. 

_declspec( dllexport) is used to declare functions, data and objects exported from a DLL. Declaring 
functions as dllexport eliminates the need for linker "EXPORT" directives. The 
_declspec (dllexport) attribute is a replacement for the_export keyword. 

_declspec( _ pragma( "string") ) is used to declare functions which adhere to the conventions described 

by the pragma identified by "string". 

Example: 
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♦include <stdio.h> 

♦pragma aux my_ stdcall *" \ 
parm routine [] \ 
value struct struct caller [] \ 
modify [eax ecx edx]; 

struct list { 

struct list 
int 
float 

} ; 

♦ define STDCALL declspec( pragma ( "my_ stdcall" ) ) 

STDCALL struct list foo( int x, char *y, double z ); 

void main() 

{ 

int a = 1; 

char *b = "Hello there"; 
double c = 3.1415926; 
struct list t; 

t = foo (a, b, c ) ; 
printf ( "%d\n", t.value ); 

} 


struct list foo( int x, char *y, double z ) 

{ 

struct list tmp; 

printf( "%s\n", y ); 
tmp.next = NULL; 
tmp.value = x; 
tmp.flt_ value = z; 
return( tmp ); 

} 

It is also possible to modify the calling convention of all methods of a class or just an 
individual method. 

Example: 

♦pragma aux my_ thiscall *" \ 
parm routine [ecx] \ 
value struct struct caller [] \ 
modify [eax ecx edx] ; 

♦ define THISCALL_declspec (_pragma ( "my_ thiscall" ) ) 

class THISCALL IWatcom: public IUnknown{ 
virtual int method_ a ( void ) = 0; 
virtual int method_ b( void ) = 0; 
virtual int_cdecl method_ c ( void ) = 0; 

} ; 


*next; 
value; 
flt_ value; 
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In this example, any calls generated to the virtual methods ’method_a’ or ’method_b’ will 
use the THISCALL ( my_thiscall) calling convention. Calls generated to ’method_c’ will 
use the prefefined_ cdecl calling convention. 

It is also possible to forward define the class with modifiers for occasions where you do not 
want to change original source code. 

Example: 

♦pragma aux my_ thiscall *" \ 
parm routine [ecx] \ 
value struct struct caller [] \ 
modify [eax ecx edx] ; 

♦ define THISCALL_declspec (_pragma ( "my_ thiscall" ) ) 

class THISCALL IWatcom; 

class IWatcom: public IUnknown! 

virtual int method_ a ( void ) = 0; 
virtual int method_ b ( void ) = 0; 
virtual int_cdecl method_ c ( void ) = 0; 

} ; 


The_ pragma modifier is supported by Open Watcom C++ only. 

_declspec( _ cdecl) is used to declare functions which conform to the Microsoft compiler calling 

convention. 

_declspec( _ pascal) is used to declare functions which conform to the OS/2 1.x and Windows 3.x 

calling convention. 

_declspec( fortran ) is used to declare functions which conform to the fortran calling convention. 
Example: 

♦include <stdio.h> 

♦define DLLFunc _declspec(dllimport _fortran) 

♦define DLLData _declspec(dllimport) 

♦ifdef _ cplusplus 

extern "C" { 

♦endif 

DLLFunc int dll_ func( int, int, int ); 

DLLData int dll_ data; 

♦ifdef _ cplusplus 

} ; 

♦endif 

void main() 

{ 

printf ( "%d %d\n", dll_ func ( 1,2,3 ), dll_ data ); 

} 


_declspec( _ stdcall) is used to declare functions which conform to the 32-bit Win32 "standard" calling 

convention. 
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Example: 

♦include <stdio.h> 


♦define DLLFunc declspec(dllimport stdcall) 

♦define DLLData declspec(dllimport) 


DLLFunc int 
DLLData int 


dll_ func ( int, int, int ); 
dll_ data; 


void main () 

{ 

printf ( "%d %d\n", dll_ func ( 1,2,3 ), dll_ data ); 

} 


_declspec( _ syscall) is used to declare functions which conform to the 32-bit OS/2_ syscall calling 

convention. 


3.13 The Open Watcom Code Generator 

The Open Watcom Code Generator performs such optimizations as common subexpression elimination, 
global flow analysis, and so on. 

In some cases, the code generator can do a better job of optimizing code if it could utilize more memory. 
This is indicated when a 

Not enough memory to optimize procedure 'xxxx' 

message appears on the screen as the source program is compiled. In such an event, you may wish to make 
more memory available to the code generator. 

A special environment variable may be used to obtain memory usage information or set memory usage 
limits on the code generator. The WCGMEMORY environment variable may be used to request a report 
of the amount of memory used by the compiler’s code generator for its work area. 

Example: 

C>set WCGMEMORY=? 

When the memory amount is "?" then the code generator will report how much memory was used to 
generate the code. 

It may also be used to instruct the compiler’s code generator to allocate a fixed amount of memory for a 
work area. 

Example: 

C>set WCGMEMORY=128 

When the memory amount is "nnn" then exactly "nnnK" bytes will be used. In the above example, 128K 
bytes is requested. If less than "nnnK" is available then the compiler will quit with a fatal error message. If 
more than "nnnK" is available then only "nnnK" will be used. 

There are two reasons why this second feature may be quite useful. In general, the more memory available 
to the code generator, the more optimal code it will generate. Thus, for two personal computers with 
different amounts of memory, the code generator may produce different (although correct) object code. If 
you have a software quality assurance requirement that the same results (i.e., code) be produced on two 
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different machines then you should use this feature. To generate identical code on two personal computers 
with different memory configurations, you must ensure that the WCGMEMORY environment variable is 
set identically on both machines. 

The second reason where this feature is useful is on virtual memory paging systems (e.g., OS/2) where an 
unlimited amount of memory can be used by the code generator. If a very large module is being compiled, 
it may take a very long time to compile it. The code generator will continue to allocate more and more 
memory and cause an excessive amount of paging. By restricting the amount of memory that the code 
generator can use, you can reduce the amount of time required to compile a routine. 
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4 Precompiled Headers 


4.1 Using Precompiled Headers 

Open Watcom C/C++ supports the use of precompiled headers to decrease the time required to compile 
several source files that include the same header file. 


4.2 When to Precompile Header Files 

Using precompiled headers reduces compilation time when: 

• You always use a large body of code that changes infrequently. 

• Your program comprises multiple modules, all of which use the same first include file and the same 
compilation options. In this case, the first include file along with all the files that it includes can be 
precompiled into one precompiled header. 

Because the compiler only uses the first include file to create a precompiled header, you may want to create 
a master or global header file that includes all the other header files that you wish to have precompiled. 

Then all source files should include this master header file as the first #include in the source file. Even 
if you don’t use a master header file, you can benefit from using precompiled headers for Windows 
programs by using #include <windows . h> as the first include file, or by using #include 
<af xwin. h> as the first include file for MFC applications. 

The first compilation — the one that creates the precompiled header file — takes a bit longer than 
subsequent compilations. Subsequent compilations can proceed more quickly by including the precompiled 
header. 

You can precompile C and C++ programs. In C++ programming, it is common practice to separate class 
interface information into header files which can later be included in programs that use the class. By 
precompiling these headers, you can reduce the time a program takes to compile. 


Note: Although you can use only one precompiled header (. PCH) file per source file, you can use 
multiple . PCH files in a project. 


4.3 Creating and Using Precompiled Headers 

Precompiled code is stored in a file called a precompiled header when you use the precompiled header 
option ( -fh or -fhq) on the command line. The -fh option causes the compiler to either create a 
precompiled header or use the precompiled header if it already exists. The -fhq option is similar but 
prevents the compiler from issuing informational or warning messages about precompiled header files. The 
default name of the precompiled header file is one of WCC . PCH, WCC386.PCH, WPP.PCH, or 
WPP386 . PCH (depending on the compiler used). You can also control the name of the precompiled 
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header that is created or used with the -fh=filename or -fhq=filename ("specify precompiled header 
filename") options. 

Example: 

-fh=projectx.pch 
-fhq=projectx.pch 

4.4 The "-fh[q]“ (Precompiled Header) Option 

The -fh option instructs the compiler to use a precompiled header file with a default name of WCC . PCH, 
WCC386 . PCH, WPP . PCH, or WPP38 6 . PCH (depending on the compiler used) if it exists or to create 
one if it does not. The file is created in the current directory. You can use the -fh=filename option to 
change the default name (and placement) of the precompiled header. Add the letter "q" (for "quiet") to the 
option name to prevent the compiler from displaying precompiled header activity information. 

The following command line uses the -fh option to create a precompiled header. 

Example: 

wpp -fh myprog.cpp 
wpp386 -fh myprog.cpp 

The following command line creates a precompiled header named myprog. pch and places it in the 
\projpch directory. 

Example: 

wpp -fh=\projpch\myprog.pch myprog.cpp 
wpp386 -fh=\projpch\myprog.pch myprog.cpp 

The precompiled header is created and/or used when the compiler encounters the first #include directive 
that occurs in the source file. In a subsequent compilation, the compiler performs a consistency check to 
see if it can use an existing precompiled header. If the consistency check fails then the compiler discards 
the existing precompiled header and builds a new one. 

The -fhq form of the precompiled header option prevents the compiler from issuing warning or 
informational messages about precompiled header files. For example, if you change a header file, the 
compiler will tell you that it changed and that it must regenerate the precompiled header file. If you specify 
-fhq then the compiler just generates the new precompiled header file without displaying a message. 

4.5 Consistency Rules for Precompiled Headers 

If a precompiled header file exists (either the default file or one specified by -fh=filename), it is compared 
to the current compilation for consistency. A new precompiled header file is created and the new file 
overwrites the old unless the following requirements are met: 

• The current compiler options must match those specified when the precompiled header was created. 

• The current working directory must match that specified when the precompiled header was created. 

• The name of the first ((include directive must match the one that was specified when the 
precompiled header was created. 
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• All macros defined prior to the first #include directive must have the same values as the macros 
defined when the precompiled header was created. A sequence of #def ine directives need not 
occur in exactly the same order because there are no semantic order dependencies for #def ine 
directives. 

• The value and order of include paths specified on the command line with -i options must match 
those specified when the precompiled header was created. 

• The time stamps of all the header files (all files specified with # include directives) used to build 
the precompiled header must match those that existed when the precompiled header was created. 
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5 The Open Watcom C/C++ Libraries 


The Open Watcom C/C++ library routines are described in the Open Watcom C Library Reference 
manual, and the Open Watcom C++ Class Library Reference manual. 


5.1 Open Watcom C/C++ Library Directory Structure 

Since Open Watcom C/C++ supports both 16-bit and 32-bit application development, libraries are grouped 
under two major subdirectories. The LIB28 6 directory is used to contain libraries for 16-bit application 
development. The LIB3 8 6 directory is used to contain libraries for 32-bit application development. 

For 16-bit application development, the Intel x86 processor-dependent libraries are placed under the 
\WATCOM\LIB286 directory. 

For 32-bit application development, the Intel 386 and upward-compatible processor-dependent libraries are 
placed under the \WATCOM\LIB38 6 directory. 

Since Open Watcom C/C++ also supports several operating systems, including DOS, OS/2, Windows 3.x 
and Windows NT, system-dependent libraries are grouped under different directories underneath the 
processor-dependent directories. 

For DOS applications, the system-dependent libraries are placed in \WATCOM\LIB286\DOS (16-bit 
applications) and \WATCOM\LIB386\DOS (32-bit applications). 

For OS/2 applications, the system-dependent libraries are placed in \WATCOM\LIB286\OS2 (16-bit 
applications) and \WATCOM\LIB386\OS2 (32-bit applications). 

For Microsoft Windows applications, the system-dependent libraries are placed in 
\WATCOM\LIB286\WIN (16-bit applications) and \WATCOM\LIB386\WIN (32-bit applications). 

For Microsoft Windows NT applications, the system-dependent libraries are placed in 
\WATCOM\LIB386\NT (32-bit applications). 

For Novell NetWare 386 applications, the system-dependent libraries are placed in 
\WATCOM\LIB386\NETWARE (32-bit applications). 



\watcom 





lib286 



lib38 6 



os2 

win dos 

os2 

win 

nt 

netware 
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5.2 Open Watcom C/C++ C Libraries 

Due to the many code generation strategies possible in the 80x86 family of processors, a number of 
versions of the libraries are provided. You must use the libraries which coincide with the particular 
architecture, operating system, and code generation strategy or model that you have selected. For the type 
of code generation strategy or model that you intend to use, refer to the description of the "m?" memory 
model compiler option. The various code models supported by Open Watcom C/C++ are described in the 
chapters entitled "16-bit Memory Models" on page 117 and "32-bit Memory Models" on page 185. 

We have selected a simple naming convention for the libraries that are provided with Open Watcom 
C/C++. Letters are affixed to the file name to indicate the particular strategy with which the modules in the 
library have been compiled. 

16-bit only 

S denotes a version of the Open Watcom C/C++ libraries which have been compiled for the 

"small" memory model (small code, small data). 

M denotes a version of the Open Watcom C/C++ libraries which have been compiled for the 

"medium" memory model (big code, small data). 

C denotes a version of the Open Watcom C/C++ libraries which have been compiled for the 

"compact" memory model (small code, big data). 

L denotes a version of the Open Watcom C/C++ libraries which have been compiled for the 

"large" memory model (big code, big data). 

H denotes a version of the Open Watcom C/C++ libraries which have been compiled for the 

"huge" memory model (big code, huge data). 

MT denotes a version of the Open Watcom C/C++ libraries which may be used with OS/2 

multi-threaded applications. 

DL denotes a version of the Open Watcom C/C++ libraries which may be used when creating 

an OS/2 Dynamic Link Library. 

32-bit only 

3R denotes a version of the Open Watcom C/C++ libraries that will be used by programs 

which have been compiled for the "flat/small" memory models using the "3r", "4r", "5r" or 
"6r" option. 

3S denotes a version of the Open Watcom C/C++ libraries that will be used by programs 

which have been compiled for the "flat/small" memory models using the "3s", "4s", "5s" or 
"6s" option. 

The Open Watcom C/C++ 16-bit libraries are listed below by directory. 
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Under \WATCOM\LIB286\DOS 


CLIBS.LIB 
CLIBM.LIB 
CLIBC.LIB 
CLIBL.LIB 
CLIBH.LIB 
GRAPH.LIB 
DOSLFNS.LIB 
DOSLFNM.LIB 
DOSLFNC.LIB 
DOSLFNL.LIB 
DOSLFNH.LIB 


(DOS small model support) 

(DOS medium model support) 

(DOS compact model support) 

(DOS large model support) 

(DOS huge model support) 

(model independent, DOS graphics support) 
(DOS LFN small model support) 

(DOS LFN medium model support) 

(DOS LFN compact model support) 

(DOS LFN large model support) 

(DOS LFN huge model support) 


Under \WATCOM\LIB286\OS2 


CLIBS.LIB 

(OS/2 

CLIBM.LIB 

(OS/2 

CLIBC.LIB 

(OS/2 

CLIBL.LIB 

(OS/2 

CLIBH.LIB 

(OS/2 

CLIBMTL.LIB 

(OS/2 

CLIBDLL.LIB 

(OS/2 

DOSPMS.LIB 

(Phar 

DOSPMM.LIB 

(Phar 

DOSPMC.LIB 

(Phar 

DOSPML.LIB 

(Phar 

DOSPMH.LIB 

(Phar 


small model support) 

medium model support) 

compact model support) 

large model support) 

huge model support) 

multi-thread, large model support) 

DLL, large model support) 

Lap 286 PM small model support) 

Lap 286 PM medium model support) 
Lap 286 PM compact model support) 
Lap 286 PM large model support) 

Lap 286 PM huge model support) 


Under \WATCOM\LIB286\WIN 


CLIBS.LIB 
CLIBM.LIB 
CLIBC.LIB 
CLIBL.LIB 
WINDOWS.LIB 


(Windows small model support) 
(Windows medium model support) 
(Windows compact model support) 
(Windows large model support) 
(Windows API library) 


The Open Watcom C/C++ 32-bit libraries are listed below by directory. 


Under \WATCOM\LIB386\DOS 


CLIB3R.LIB 
CLIB3S.LIB 
GRAPH.LIB 
DOSLFN3R.LIB 

D0SLFN3S.LIB 


(flat/small 

(flat/small 

(flat/small 

(flat/small 


models, 

models, 

models, 

models. 


(flat/small models. 


"3r", "4r", "5r" or "6r" 

"3s", "4s", "5s" or "6s" 

DOS graphics support) 

DOS LFN support, 

"3r", "4r", "5r" or "6r" 

DOS LFN support, 

"3s", "4s", "5s" or "6s" 


The graphics library GRAPH. LIB is independent of the argument passing conventions. 


option) 

option) 

option) 

option) 
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Under \WATCOM\LIB386\OS2 


CLIB3R.LIB 

(flat/small 

models. 

" 3 r " , 

" 4 r " , 

" 5 r " 

or 

" 6 r " 

option) 

CLIB3S.LIB 

(flat/small 

models. 

"3s", 

"4s", 

"5s" 

or 

"6s" 

option) 

Under \WATCOM\LIB386\WIN 








CLIB3R.LIB 

(flat/small 

models. 

" 3 r " , 

" 4 r " , 

" 5 r " 

or 

" 6 r " 

option) 

CLIB3S.LIB 

(flat/small 

models. 

"3s", 

"4s", 

"5s" 

or 

"6s" 

option) 

WIN386.LIB 

(32-bit Windows API) 







Under \WATCOM\LIB386\NT 








CLIB3R.LIB 

(flat/small 

models. 

" 3 r " , 

" 4 r " , 

" 5 r " 

or 

" 6 r " 

option) 

CLIB3S.LIB 

(flat/small 

models. 

"3s", 

"4s", 

"5s" 

or 

"6s" 

option) 


5.3 Open Watcom C/C++ Class Libraries 

The Open Watcom C/C++ Class Library routines are described in the Open Watcom C++ Class Library 

Reference manual. 

The Open Watcom C++ 16-bit Class Libraries are listed below. 

Under \WATCOM\LIB286 

(iostream and string class libraries) 

PLIBS.LIB (small model support) 

PLIBM.LIB (medium model support) 

PLIBC.LIB (compact model support) 

PLIBL.LIB (large model support) 

PLIBH.LIB (huge model support) 

PLIBMTL.LIB (OS/2 multi-thread, large model support) 

PLIBDLL.LIB (OS/2 DLL, large model support) 

(complex class library for "fpc" option) 

CPLXS.LIB (small model support) 

CPLXM.LIB (medium model support) 

CPLXC.LIB (compact model support) 

CPLXL.LIB (large model support) 

CPLXH.LIB (huge model support) 

(complex class library for "fpi..." options) 

CPLX7S.LIB (small model support) 

CPLX7M.LIB (medium model support) 

CPLX7C.LIB (compact model support) 

CPLX7L.LIB (large model support) 

CPLX7H.LIB (huge model support) 

These libraries are independent of the operating system (except those designated for OS/2). The "7" 

designates a library compiled with the "7" option. 

The Open Watcom C++ 32-bit Class Libraries are listed below. 
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Under \WATCOM\LIB386 


(iostream and string class libraries) 


PLIB3R.LIB 

(flat 

models. 

" 3 r " , 

'» 4 r »» 

r 

" 5 r " 

or " 

6 r" 

option) 

PLIB3S.LIB 

(flat 

models. 

"3s", 

"4s" 

r 

"5s" 

or " 

6 s" 

option) 

PLIBMT3R.LIB 

(multi 

.-thread 

library for 

OS/2 

and 

Windows NT) 

PLIBMT3S.LIB 

(multi 

.-thread 

library for 

OS/2 

and 

Windows NT) 

(complex 

class 

library- 

for " 

fpc" 

option) 




CPLX3R.LIB 

(flat 

models. 

" 3 r " , 

" 4 r " 

r 

" 5 r " 

or " 

6 r" 

option) 

CPLX3S.LIB 

(flat 

models. 

"3s", 

"4s" 

r 

"5s" 

or " 

6 s" 

option) 

(complex 

class 

library 

for " 

fpi. . 

. 

" options) 



CPLX73R.LIB 

(flat 

models. 

" 3 r " , 

»» 4 r »» 

r 

" 5 r " 

or " 

6 r " 

option) 

CPLX73S.LIB 

(flat 

models. 

"3s", 

"4s" 

r 

"5s" 

or " 

6 s" 

option) 


These libraries are independent of the operating system (except those designated for OS/2 and Windows 
NT). The "3R" and "3S" suffixes refer to the argument passing convention used. The "7" designates a 
library compiled with the "7" option. 

5.4 Open Watcom C/C++ Math Libraries 

In general, a Math library is required when floating-point computations are included in the application. The 
Math libraries are operating-system independent. 

For the 286 architecture, the Math libraries are placed under the \WATC0M\LIB2 8 6 directory. 

For the 386 architecture, the Math libraries are placed under the \WATC0M\LIB3 8 6 directory. 

An 80x87 emulator library, emu87 . lib, is also provided which is both operating-system and architecture 
dependent. 

The following situations indicate that one of the Math libraries should be included when linking the 
application. 

1. When one or more of the functions described in the math. h header file is referenced, then a 
Math library must be included. 

2. If an application is linked and the message 

fltused_ is an undefined reference" 
appears, then a Math library must be included. 

3. (16-bit only) If an application is linked and the message 

"_init_ 87_ emulator is an undefined reference" 

appears, then one of the modules in the application was compiled with one of the "fpi", "fpi87", 
"fp2", "fp3" or "fp5" options. If the "fpi" option was used, the 80x87 emulator library ( 
emu87 . lib ) or the 80x87 fixup library ( noemu87 . lib ) should be included when linking 
the application. 

If the "fpi87" option was used, the 80x87 fixup library noemu87 . lib should be included when 
linking the application. 
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The 80x87 emulator is contained in emu87 . lib. Use noemu87 . lib in place of 
emu8 7 . lib when the emulator is not wanted. 

4. (32-bit only) If an application is linked and the message 

"_init_ 387_ emulator is an undefined reference" 

appears, then one of the modules in the application was compiled with one of the "fpi", "fpi87", 
"fp2", "fp3" or "fp5" options. If the "fpi" option was used, the 80x87 emulator library ( 
emu387 . lib) should be included when linking the application. 

If the "fpi87" option was used, the empty 80x87 emulator library noemu387 . lib should be 
included when linking the application. 

The 80x87 emulator is contained in emu387 . lib. Use noemu387 . lib in place of 
emu387 . lib when the emulator is not wanted. 

Normally, the compiler and linker will automatically take care of this. Simply ensure that the WATCOM 
environment variable includes the location of the Open Watcom C/C++ libraries. 


5.5 Open Watcom C/C++ 80x87 Math Libraries 

One of the following Math libraries must be used if any of the modules of your application were compiled 
with one of the Open Watcom C/C++ "fpi", "fpi87", "fp2", "fp3" or "fp5" options and your application 
requires floating-point support for the reasons given above. 


16-bit libraries: 


(small model) 
(medium model) 
(compact model) 
(large model) 
(huge model) 


MATH87S.LIB 
MATH87M.LIB 
MATH87C.LIB 
MATH87L.LIB 
MATH87H.LIB 
NOEMU87.LIB 

DOS\EMU87.LIB (DOS dependent) 
OS2\EMU87.LIB (OS/2 dependent) 
WIN\EMU87.LIB (Windows dependent) 
WIN\MATH87C.LIB (Windows dependent 
WIN\MATH87L.LIB (Windows dependent 


) 

) 


32-bit libraries: 

MATH387R.LIB (flat/small models, "3r", "4r", "5r" or "6r" option) 
MATH387S.LIB (flat/small models, "3s", "4s", "5s" or "6s" option) 
DOS\EMU387.LIB (DOS dependent) 

WIN\EMU387.LIB (Windows dependent) 

OS2\EMU387.LIB (OS/2 dependent) 

NT\EMU387.LIB (Windows NT dependent) 


The "fpi" option causes an 80x87 numeric data processor emulator to be linked into your application in 
addition to any 80x87 math routines that were referenced. This emulator will decode and emulate 80x87 
instructions when an 80x87 is not present in the system or if the environment variable N087 has been set 
(this variable is described below). 
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For 32-bit Open Watcom Windows-extender applications or 32-bit applications run in Windows 3.1 DOS 
boxes, you must also include the WEMU387.386 file in the [386enh] section of the SYSTEM. INI file. 

Example: 

device=C:\WATCOM\binw\wemu387.386 

Note that the WDEBUG .386 file which is installed by the Open Watcom Installation software contains the 
emulation support found in the WEMU3 8 7.386 file. 

When the "fpi87" option is used exclusively, the emulator is not included. In this case, the application must 
be run on personal computer systems equipped with the numeric data processor. 

5.6 Open Watcom C/C++ Alternate Math Libraries 

One of the following Math libraries must be used if any of the modules of your application were compiled 
with the Open Watcom C/C++ "fpc" option and your application requires floating-point support for the 
reasons given above. The following Math libraries include support for floating-point which is done 
out-of-line through run-time calls. 

16-bit libraries: 

MATHS.LIB (small model) 

MATHM.LIB (medium model) 

MATHC.LIB (compact model) 

MATHL.LIB (large model) 

MATHH.LIB (huge model) 

WIN\MATHC.LIB (Windows dependent) 

WIN\MATHL.LIB (Windows dependent) 

32-bit libraries: 

MATH3R.LIB (flat/small models, "3r", "4r", "5r" or "6 r" option) 
MATH3S.LIB (flat/small models, "3s", "4s", "5s" or "6 s" option) 

Applications which are linked with one of these libraries do not require a numeric data processor for 
floating-point operations. If one is present in the system, it will be used; otherwise floating-point 
operations are simulated in software. The numeric data processor will not be used if the environment 
variable N087 has been set (this variable is described below). 


5.7 The N087Environment Variable 

If you have a numeric data processor (math coprocessor) in your system but you wish to test a version of 
your application that will use floating-point emulation ("fpi" option) or simulation ("fpc" option), you can 
define the N087 environment variable. 

(16-bit only) The application must be compiled using the "fpc" (floating-point calls) option and linked with 
the appropriate math? . lib library or the "fpi" option (default) and linked with the appropriate 
math87? . lib and emu87 . lib libraries. 

(32-bit only) The application must be compiled using the "fpc" (floating-point calls) option and linked with 
the appropriate math3? . lib library or the "fpi" option (default) and linked with the appropriate 
math387 ? . lib library. 
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Using the "SET" command, define the environment variable as follows: 

C>SET N087=l 

Now, when you run your application, the 80x87 will be ignored. To undefine the environment variable, 
enter the command: 

C>SET N087= 

5.8 The LFN Environment Variable 


If you have the application compiled and linked to use DOS Long file name support (LFN) then you can 
define the LFN environment variable to suppress usage of DOS LFN on run-time. 

Using the "SET" command, define the environment variable as follows: 

C>SET LFN=N 

Now, when you run your application, DOS LFN support will be ignored. To undefine the environment 
variable, enter the command: 

C>SET LFN= 


5.9 The Open Watcom C/C++ Run-time Initialization Routines 

Source files are included in the package for the Open Watcom C/C++ application startup (or initialization) 
sequence. 

(16-bit only) The initialization code directories/files are listed below: 

Under \WATCOM\SRC\STARTUP 

WILDARGV.C (wild card processing for argv) 

8087CW.C (value loaded into 80x87 control word) 


Under \WATCOM\SRC\STARTUP\DOS (DOS initialization) 


CSTRT086.ASM 
DOS16M.ASM 
CMAIN086,C 
MDEF.INC 


(startup for 16-bit apps) 

(startup code for Tenberry Software's DOS/16M) 
(final part of initialization sequence) 

(macros included by assembly code) 


Under \WATCOM\SRC\STARTUP\WIN (Windows initialization) 


CSTRTW16.ASM 
LIBENTRY.ASM 
MDEF.INC 


(startup for 16-bit 
(startup for 16-bit 
(macros included by 


Windows apps) 
Windows DLLs) 
assembly code) 
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Under \WATC0M\SRC\STARTUP\0S2 (OS/2 initialization) 

CMAIN086.C (final part of initialization sequence) 

MAIN016.C (middle part of initialization sequence) 

CSTRT016.ASM (startup for 16-bit OS/2) 

EXITWMSG.H (header file required by MAIN016.C) 

W0S2.H (header file required by MAIN016.C) 

INITFINI.H (header file required by MAIN016.C) 

MDEF.INC (macros included by assembly code) 

The following is a summary description of the startup files for DOS. The startup files for Windows and 
OS/2 are similar. The assembler file CSTRTO 8 6 . ASM contains the first part of the initialization code and 
the remainder is continued in the file CMAINO 8 6 . C . It is CMAINO 8 6 . C that calls your main routine 
(main) . 

The DOS16M. ASM file is a special version of the CSTRTO 8 6 .ASM file which is required when using the 
Tenberry Software, Inc. DOS/16M 286 DOS extender. 

(32-bit only) The initialization code directories/files are listed below: 

Under \WATCOM\SRC\STARTUP 

WILDARGV.C (wild card processing for argv) 

8087CW.C (value loaded into 80x87 control word) 

Under \WATCOM\SRC\STARTUP\386 

CSTRT386.ASM (startup for most DOS Extenders) 

CSTRTW32.ASM (startup for 32-bit Windows) 

CSTRTX32.ASM (startup for FlashTek DOS Extender) 

CMAIN386.C (final part of initialization sequence) 

The assembler files CSTRT* . ASM contain the first part of the initialization code and the remainder is 
continued in the file CMAIN386 . C . It is CMAIN386 . C that calls your main routine (main) . 

The source code is provided for those who wish to customize the initialization sequence for special 
applications. 

The file wildargv. c contains an alternate form of "argv" processing in which wild card command line 
arguments are transformed into lists of matching file names. Wild card arguments are any arguments 
containing or "?" characters unless the argument is placed within quotes ("). Consider the following 
example in which we run an application called "TOUCH" with the argument "*.c". 

C>touch *.c 

Suppose that the application was linked with the object code for the file wildargv . c . Suppose that the 
files apl. c, ap2 . c and ap3 . c are stored in the current directory. The single argument "*.c" is 
transformed into a list of arguments such that: 

argc == 4 

argv[l] points to "apl.c" 
argv[2] points to "ap2.c" 
argv[3] points to "ap3.c" 
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The source file wildargv. c must be compiled to produce the object file wildargv. ob j . This file 
must be specified before the Open Watcom C/C++ libraries in the linker command file in order to replace 
the standard "argv" processing. 
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6.1 Introduction 


This chapter describes the various 16-bit memory models supported by Open Watcom C/C++. Each 
memory model is distinguished by two properties; the code model used to implement function calls and the 
data model used to reference data. 


6.216-bit Code Models 


There are two code models; 

1. the small code model and 

2. the big code model. 

A small code model is one in which all calls to functions are made with near calls. In a near call, the 
destination address is 16 bits and is relative to the segment value in segment register CS. Hence, in a small 
code model, all code comprising your program, including library functions, must be less than 64K. 

A big code model is one in which all calls to functions are made with far calls. In a far call, the destination 
address is 32 bits (a segment value and an offset relative to the segment value). This model allows the size 
of the code comprising your program to exceed 64K. 


Note: If your program contains less than 64K of code, you should use a memory model that employs 
the small code model. This will result in smaller and faster code since near calls are smaller instructions 
and are processed faster by the CPU. 


6.3 16-bit Data Models 


There are three data models; 

1. the small data model, 

2. the big data model and 

3. the huge data model. 

A small data model is one in which all references to data are made with near pointers. Near pointers are 16 
bits; all data references are made relative to the segment value in segment register DS. Hence, in a small 
data model, all data comprising your program must be less than 64K. 

A big data model is one in which all references to data are made with far pointers. Far pointers are 32 bits 
(a segment value and an offset relative to the segment value). This removes the 64K limitation on data size 
imposed by the small data model. However, when a far pointer is incremented, only the offset is adjusted. 
Open Watcom C/C++ assumes that the offset portion of a far pointer will not be incremented beyond 64K. 
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The compiler will assign an object to a new segment if the grouping of data in a segment will cause the 
object to cross a segment boundary. Implicit in this is the requirement that no individual object exceed 64K 
bytes. For example, an array containing 40,000 integers does not fit into the big data model. An object 
such as this should be described as huge. 

A huge data model is one in which all references to data are made with far pointers. This is similar to the 
big data model. However, in the huge data model, incrementing a far pointer will adjust the offset and the 
segment if necessary. The limit on the size of an object pointed to by a far pointer imposed by the big data 
model is removed in the huge data model. 

Notes: 

1. If your program contains less than 64K of data, you should use the small data model. This will 
result in smaller and faster code since references using near pointers produce fewer instructions. 

2. The huge data model should be used only if needed. The code generated in the huge data model 
is not very efficient since a run-time routine is called in order to increment far pointers. This 
increases the size of the code significantly and increases execution time. 

6.4 Summary of 16-bit Memory Models 

As previously mentioned, a memory model is a combination of a code model and a data model. The 
following table describes the memory models supported by Open Watcom C/C++. 


Memory 

Model 

Code 

Model 

Data 

Model 

Default 

Code 

Pointer 

Default 

Data 

Pointer 

tiny 

small 

small 

near 

near 

small 

small 

small 

near 

near 

medium 

big 

small 

far 

near 

compact 

small 

big 

near 

far 

large 

big 

big 

far 

far 

huge 

big 

huge 

far 

huge 


6.5 Tiny Memory Model 

In the tiny memory model, the application’s code and data must total less than 64K bytes in size. All code 
and data are placed in the same segment. Use of the tiny memory model allows the creation of a COM file 
for the executable program instead of an EXE file. For more information, see the section entitled "Creating 
a Tiny Memory Model Application" in this chapter. 

6.6 Mixed 16-bit Memory Model 

A mixed memory model application combines elements from the various code and data models. A mixed 
memory model application might be characterized as one that uses the near, far, or huge keywords when 
describing some of its functions or data objects. 

For example, a medium memory model application that uses some far pointers to data can be described as a 
mixed memory model. In an application such as this, most of the data is in a 64K segment (DGROUP) and 
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hence can be referenced with near pointers relative to the segment value in segment register DS. This 
results in more efficient code being generated and better execution times than one can expect from a big 
data model. Data objects outside of the DGROUP segment are described with the far keyword. 

6.7 Linking Applications for the Various 16-bit Memory 
Models 


Each memory model requires different run-time and floating-point libraries. Each library assumes a 
particular memory model and should be linked only with modules that have been compiled with the same 
memory model. The following table lists the libraries that are to be used to link an application that has 
been compiled for a particular memory model. 


Memory 

Model 

Run-time 

Library 

Floating-Point 
Calls Library 

Floating-Point 
Library (80x87) 

tiny 

CLIBS.LIB 
+CSTART_ T . 

MATHS.LIB 

.OBJ 

MATH87S.LIB 
+(NO)EMU87.LIB* 

small 

CLIBS.LIB 

MATHS.LIB 

MATH87S.LIB 
+(NO)EMU87.LIB* 

medium 

CLIBM.LIB 

MATHM.LIB 

MATH87M.LIB 
+(NO)EMU87.LIB* 

compact 

CLIBC.LIB 

MATHC.LIB 

MATH87C.LIB 
+(NO)EMU87.LIB* 

large 

CLIBL.LIB 

MATHL.LIB 

MATH87L.LIB 
+(NO)EMU87.LIB* 

huge 

CLIBH.LIB 

MATHH.LIB 

MATH87H.LIB 
+(NO)EMU87.LIB* 


* One of emu87 . lib or noemu87 . lib will be used with the 80x87 math libraries depending on the use 
of the "fpi" (include emulation) or "fpi87" (do not include emulation) options. 


6.8 Creating a Tiny Memory Model Application 

Tiny memory model programs are created by compiling all modules with the small memory model option 
and linking in the special initialization file "CSTART_T.OBJ". This file is found in the Open Watcom 
C/C++ LIB2 8 6\DOS directory. It must be the first object file specified when linking the program. 

The following sequence will create the executable file "MYPROG.COM" from the file "MYPROG.C": 
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Example: 

C>wcc myprog /ms 

C>wlink system com file myprog 

Most of the details of linking a "COM" program are handled by the "SYSTEM COM" directive (see the 
wl system. Ink file for details). When linking a "COM" program, the message "Stack segment not 
found" is issued. This message may be ignored. 

6.9 Memory Layout 

The following describes the segment ordering of an application linked by the Open Watcom Linker. Note 
that this assumes that the "DOSSEG" linker option has been specified. 

1. all segments not belonging to group "DGROUP" with class "CODE" 

2. all other segments not belonging to group "DGROUP" 

3. all segments belonging to group "DGROUP" with class "BEGDATA" 

4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

5. all segments belonging to group "DGROUP" with class "BSS" 

6. all segments belonging to group "DGROUP" with class "STACK" 

A special segment belonging to class "BEGDATA" is defined when linking with Open Watcom run-time 
libraries. This segment is initialized with the hexadecimal byte pattern "01" and is the first segment in 
group "DGROUP" so that storing data at location 0 can be detected. 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 

In addition to these special segments, the following conventions are used by Open Watcom C/C++. 

1. The "CODE" class contains the executable code for your application. In a small code model, this 
consists of the segment "_TEXT". In a big code model, this consists of the segments 
"<module>_TEXT" where <module> is the file name of the source file. 

2. The "FAR_DATA" class consists of the following: 

(a) data objects whose size exceeds the data threshold in large data memory models 
(the data threshold is 32K unless changed using the "zt" compiler option) 

(b) data objects defined using the "FAR" or "HUGE" keyword, 

(c) literals whose size exceeds the data threshold in large data memory models (the 
data threshold is 32K unless changed using the "zt" compiler option) 
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(d) literals defined using the "FAR" or "HUGE" keyword. 

You can override the default naming convention used by Open Watcom C/C++ to name segments. 

1. The Open Watcom C/C++ "nm" option can be used to change the name of the module. This, in 
turn, changes the name of the code segment when compiling for a big code model. 

2. The Open Watcom C/C++ "nt" option can be used to specify the name of the code segment 
regardless of the code model used. 
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7 16-bit Assembly Language Considerations 


7.1 Introduction 


This chapter will deal with the following topics. 

1. The data representation of the basic types supported by Open Watcom C/C++. 

2. The memory layout of a Open Watcom C/C++ program. 

3. The method for passing arguments and returning values. 

4. The two methods for passing floating-point arguments and returning floating-point values. 

One method is used when one of the Open Watcom C/C++ "fpi" or "fpi87" options is specified 
for the generation of in-line 80x87 instructions. When the "fpi" option is specified, an 80x87 
emulator is included from a math library if the application includes floating-point operations. 
When the "fpi87" option is used exclusively, the 80x87 emulator will not be included. 

The other method is used when the Open Watcom C/C++ "fpc" option is specified. In this case, 
the compiler generates calls to floating-point support routines in the alternate math libraries. 

An understanding of the Intel 80x86 architecture is assumed. 

7.2 Data Representation 

This section describes the internal or machine representation of the basic types supported by Open Watcom 
C/C++. 

7.2.1 Type "char" 

An item of type "char" occupies 1 byte of storage. Its value is in the following range. 

0 <= n <= 255 

Note that "char" is, by default, unsigned. The Open Watcom C/C++ compiler option "j" can be used to 
change the default from unsigned to signed. If "char" is signed, an item of type "char" is in the following 
range. 

-128 <= n <= 127 

You can force an item of type "char" to be unsigned or signed regardless of the default by defining them to 
be of type "unsigned char" or "signed char" respectively. 
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7.2.2 Type "short int" 

An item of type "short int" occupies 2 bytes of storage. Its value is in the following range. 

-32768 <= n <= 32767 

Note that "short int" is signed and hence "short int" and "signed short int" are equivalent. If an item of type 
"short int" is to be unsigned, it must be defined as "unsigned short int". In this case, its value is in the 
following range. 

0 <= n <= 65535 


7.2.3 Type "long int" 

An item of type "long int" occupies 4 bytes of storage. Its value is in the following range. 

-2147483648 <= n <= 2147483647 

Note that "long int" is signed and hence "long int" and "signed long int" are equivalent. If an item of type 
"long int" is to be unsigned, it must be defined as "unsigned long int". In this case, its value is in the 
following range. 

0 <= n <= 4294967295 

7.2.4 Type "int" 

An item of type "int" occupies 2 bytes of storage. Its value is in the following range. 

-32768 <= n <= 32767 

Note that "int" is signed and hence "int" and "signed int" are equivalent. If an item of type "int" is to be 
unsigned, it must be defined as "unsigned int". In this case its value is in the following range. 

0 <= n <= 65535 

If you are generating code that executes in 16-bit mode, "short int" and "int" are equivalent, "unsigned short 
int" and "unsigned int" are equivalent, and "signed short int" and "signed int" are equivalent. This may not 
be the case in other environments where "int" and "long int" are 4 bytes. 

7.2.5 Type "float" 

A datum of type "float" is an approximate representation of a real number. Each datum of type "float" 
occupies 4 bytes. If m is the magnitude of x (an item of type "float") then x can be approximated if 

2~126 <= m < 2 128 

or in more approximate terms if 

1.175494e-38 <= m <= 3.402823e38 

Data of type "float" are represented internally as follows. Note that bytes are stored in memory with the 
least significant byte first and the most significant byte last. 
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+—+- 


s 

Biased 


Exponent 


+—+-+- 

31 30-23 


Significand 


22-0 


Notes 


S 

Exponent 

Significand 

Zero 

Infinity 


S = Sign bit (O=positive, l=negative) 

The exponent bias is 127 (i.e., exponent value 1 represents 2' 126 ; exponent value 127 
represents 2°; exponent value 254 represents 2 127 ; etc.)- The exponent field is 8 bits long. 

The leading bit of the significand is always 1, hence it is not stored in the significand field. 
Thus the significand is always "normalized". The significand field is 23 bits long. 

A real zero quantity occurs when the sign bit, exponent, and significand are all zero. 

When the exponent field is all 1 bits and the significand field is all zero bits then the 
quantity represents positive or negative infinity, depending on the sign bit. 


Not Numbers When the exponent field is all 1 bits and the significand field is non-zero then the quantity 
is a special value called a NAN (Not-A-Number). 

When the exponent field is all 0 bits and the significand field is non-zero then the quantity 
is a special value called a "denormal" or nonnormal number. 


7.2.6 Type "double" 

A datum of type "double" is an approximate representation of a real number. The precision of a datum of 
type "double" is greater than or equal to one of type "float". Each datum of type "double" occupies 8 bytes. 
If m is the magnitude of x (an item of type "double") then x can be approximated if 

2-1022 <= m < 2 1024 

or in more approximate terms if 

2,2250738585072e-308 <= m <= 1.79769313486232e308 

Data of type "double" are represented internally as follows. Note that bytes are stored in memory with the 
least significant byte first and the most significant byte last. 

+-+-+-+ 


S 

Biased 

Significand 


Exponent 



+-+-+-+ 

63 62-52 51-0 
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Notes: 

S = Sign bit (O=positive, l=negative) 

The exponent bias is 1023 (i.e., exponent value 1 represents 2" 1022 ; exponent value 1023 
represents 2°; exponent value 2046 represents 2 1023 ; etc.). The exponent field is 11 bits 
long. 

The leading bit of the significand is always 1, hence it is not stored in the significand field. 
Thus the significand is always "normalized". The significand field is 52 bits long. 

A double precision zero quantity occurs when the sign bit, exponent, and significand are all 
zero. 

When the exponent field is all 1 bits and the significand field is all zero bits then the 
quantity represents positive or negative infinity, depending on the sign bit. 

When the exponent field is all 1 bits and the significand field is non-zero then the quantity 
is a special value called a NAN (Not-A-Number). 

When the exponent field is all 0 bits and the significand field is non-zero then the quantity 
is a special value called a "denormal" or nonnormal number. 

7.3 Memory Layout 

The following describes the segment ordering of an application linked by the Open Watcom Linker. Note 
that this assumes that the "DOSSEG" linker option has been specified. 

1. all segments not belonging to group "DGROUP" with class "CODE" 

2. all other segments not belonging to group "DGROUP" 

3. all segments belonging to group "DGROUP" with class "BEGDATA" 

4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

5. all segments belonging to group "DGROUP" with class "BSS" 

6. all segments belonging to group "DGROUP" with class "STACK" 

A special segment belonging to class "BEGDATA" is defined when linking with Open Watcom run-time 
libraries. This segment is initialized with the hexadecimal byte pattern "01" and is the first segment in 
group "DGROUP" so that storing data at location 0 can be detected. 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 

In addition to these special segments, the following conventions are used by Open Watcom C/C++. 


S 

Exponent 

Significand 

Zero 

Infinity 

Not Numbers 
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1. The "CODE" class contains the executable code for your application. In a small code model, this 
consists of the segment "_TEXT". In a big code model, this consists of the segments 
"<module>_TEXT" where <module> is the file name of the source file. 

2. The "FAR_DATA" class consists of the following: 

(a) data objects whose size exceeds the data threshold in large data memory models 
(the data threshold is 32K unless changed using the "zt" compiler option) 

(b) data objects defined using the "FAR" or "HUGE" keyword, 

(c) literals whose size exceeds the data threshold in large data memory models (the 
data threshold is 32K unless changed using the "zt" compiler option) 

(d) literals defined using the "FAR" or "HUGE" keyword. 

You can override the default naming convention used by Open Watcom C/C++ to name segments. 

1. The Open Watcom C/C++ "nm" option can be used to change the name of the module. This, in 
turn, changes the name of the code segment when compiling for a big code model. 

2. The Open Watcom C/C++ "nt" option can be used to specify the name of the code segment 
regardless of the code model used. 

7.4 Calling Conventions for Non-80x87 Applications 

The following sections describe the calling convention used when compiling with the "fpc" compiler 
option. 

7.4.1 Passing Arguments Using Register-Based Calling Conventions 

How arguments are passed to a function with register-based calling conventions is determined by the size 
(in bytes) of the argument and where in the argument list the argument appears. Depending on the size, 
arguments are either passed in registers or on the stack. Arguments such as structures are almost always 
passed on the stack since they are generally too large to fit in registers. Since arguments are processed 
from left to right, the first few arguments are likely to be passed in registers (if they can fit) and, if the 
argument list contains many arguments, the last few arguments are likely to be passed on the stack. 

The registers used to pass arguments to a function are AX, BX, CX and DX. The following algorithm 
describes how arguments are passed to functions. 

Initially, we have the following registers available for passing arguments: AX, DX, BX and CX. Note that 
registers are selected from this list in the order they appear. That is, the first register selected is AX and the 
last is CX. For each argument Ai, starting with the left most argument, perform the following steps. 

1. If the size of Ai is 1 byte, convert it to 2 bytes and proceed to the next step. If Ai is of type 
"unsigned char", it is converted to an "unsigned int". If Ai is of type "signed char", it is 
converted to a "signed int". If Ai is a 1-byte structure, the padding is determined by the 
compiler. 

2. If an argument has already been assigned a position on the stack, Ai will also be assigned a 
position on the stack. Otherwise, proceed to the next step. 


Calling Conventions for Non-80x87 Applications 127 




16-bit Topics 


3. If the size of Ai is 2 bytes, select a register from the list of available registers. If a register is 
available, Ai is assigned that register. The register is then removed from the list of available 
registers. If no registers are available, Ai will be assigned a position on the stack. 

4. If the size of Ai is 4 bytes, select a register pair from the following list of combinations: [DX 
AX] or [CX BX]. The first available register pair is assigned to Ai and removed from the list of 
available pairs. The high-order 16 bits of the argument are assigned to the first register in the 
pair; the low-order 16 bits are assigned to the second register in the pair. If none of the above 
register pairs is available, Ai will be assigned a position on the stack. 

5. If the type of Ai is "double" or "float" (in the absence of a function prototype), select [AX BX 
CX DX] from the list of available registers. All four registers are removed from the list of 
available registers. The high-order 16 bits of the argument are assigned to the first register and 
the low-order 16 bits are assigned to the fourth register. If any of the four registers is not 
available, Ai will be assigned a position on the stack. 

6. All other arguments will be assigned a position on the stack. 

Notes: 

1. Arguments that are assigned a position on the stack are padded to a multiple of 2 bytes. That is, 
if a 3-byte structure is assigned a position on the stack, 4 bytes will be pushed on the stack. 

2. Arguments that are assigned a position on the stack are pushed onto the stack starting with the 
rightmost argument. 

7A.2 Sizes of Predefined Types 

The following table lists the predefined types, their size as returned by the "sizeof" function, the size of an 
argument of that type and the registers used to pass that argument if it was the only argument in the 
argument list. 


Basic Type 

"sizeof" 

Argument 

Size 

Registers 

Used 

char 

1 

2 

[AX] 

short int 

2 

2 

[AX] 

int 

2 

2 

[AX] 

long int 

4 

4 

[DX AX] 

float 

4 

8 

[AX BX CX DX] 

double 

8 

8 

[AX BX CX DX] 

near pointer 

2 

2 

[AX] 

far pointer 

4 

4 

[DX AX] 

huge pointer 

4 

4 

[DX AX] 

Note that the size of the argument 

listed in the table assumes that no function prototypes are specified. 

Function prototypes affect the way arguments 

are passed. This will be discussed in the section entitled 


"Effect of Function Prototypes on Arguments". 
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Notes: 


1. Provided no function prototypes exist, an argument will be converted to a default type as 
described in the following table. 


Argument Type Passed As 


char 

signed char 
unsigned char 
float 


unsigned int 
signed int 
unsigned int 
double 


7.4.3 Size of Enumerated Types 

The integral type of an enumerated type is determined by the values of the enumeration constants. In strict 
ISO/ANSI C mode, all enumerated constants are of type int. In the extensions mode, the compiler will 
use the smallest integral type possible (excluding long ints) that can represent all values of the enumerated 
type. For instance, if the minimum and maximum values of the enumeration constants are in the range 
-128 and 127, the enumerated type will be equivalent to a signed char (size = 1 byte). All references 
to enumerated constants in the previous instance will have type signed char. An enumerated constant 
is always promoted to an int when passed as an argument. 


7.4.4 Effect of Function Prototypes on Arguments 

Function prototypes define the types of the formal parameters of a function. Their appearance affects the 
way in which arguments are passed. An argument will be converted to the type of the corresponding 
formal parameter in the function prototype. Consider the following example. 

void prototype( float x, int i ) ; 

void main() 

{ 

float x; 
int i; 

x = 3.14; 
i = 314; 

prototype ( x, i ); 
rtn( x, i ); 

} 

The function prototype for prototype specifies that the first argument is to be passed as a "float" and the 
second argument is to be passed as an "int". This results in the first argument being passed in registers DX 
and AX and the second argument being passed in register BX. 

If no function prototype is given, as is the case for the function rtn, the first argument will be passed as a 
"double" and the second argument would be passed as an "int". This results in the first argument being 
passed in registers AX, BX, CX and DX and the second argument being passed on the stack. 

Note that even though both prototype and rtn were called with identical argument lists, the way in 
which the arguments were passed was completely different simply because a function prototype for 
prototype was specified. Function prototyping is an excellent way to guarantee that arguments will be 
passed as expected to your assembly language function. 
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7.4.5 Interfacing to Assembly Language Functions 

Consider the following example. 

Example: 

void main() 

{ 

long int x; 
int i; 

long int y; 

x = 7; 
i = 77; 

Y = 777; 

myrtn( x, i, y ); 

} 

myrtn is an assembly language function that requires three arguments. The first argument is of type "long 
int", the second argument is of type "int" and the third argument is again of type "long int". Using the rules 
for register-based calling conventions, these arguments will be passed to myrtn in the following way: 

1. The first argument will be passed in registers DX and AX leaving BX and CX as available 
registers for other arguments. 

2. The second argument will be passed in register BX leaving CX as an available register for other 
arguments. 

3. The third argument will not fit in register CX (its size is 4 bytes) and hence will be pushed on the 
stack. 


Let us look at the stack upon entry to myrtn . 


Small Code Model 


Offset 

+-+ 

0 | return address | <- SP points here 

+-+ 

2 argument #3 

+-+ 

6 I I 


Big Code Model 
Offset 


0 

4 

8 


+-+ 

return address | <- SP points here 

+-+ 

argument #3 

+-+ 
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Notes: 


1. The return address is the top element on the stack. In a small code model, the return address is 1 
word (16 bits); in a big code model, the return address is 2 words (32 bits). 

Register SP cannot be used as a base register to address the third argument on the stack. Register BP is 
normally used to address arguments on the stack. Upon entry to the function, register BP is set to point to 
the stack but before doing so we must save its contents. The following two instructions achieve this. 

push BP ; save current value of BP 

mov BP,SP ; get access to arguments 


After executing these instructions, the stack looks like this. 
Small Code Model 


Offset 

+-+ 

0 | saved BP | <- BP and SP point here 

+-+ 

2 | return address | 

+-+ 

4 argument #3 

+-+ 

8 I I 


Big Code Model 


Offset 

+-+ 

0 | saved BP | <- BP and SP point here 

+ - + 

2 return address | 

+ - + 

6 argument #3 

+ - + 

10 I I 


As the above diagrams show, the third argument is at offset 4 from register BP in a small code model and 
offset 6 in a big code model. 


Upon exit from myrtn, we must restore the value of BP. The following two instructions achieve this. 

mov SP,BP ; restore stack pointer 

pop BP ; restore BP 


The following is a sample assembly language function which implements myrtn . 
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Small Memory Model (small code, small data) 
DGROUP group _ DATA, _ BSS 

_ TEXT segment byte public 'CODE' 

assume CS:_TEXT 
assume DS:DGROUP 




public 

myrtn_ 





myrtn_ 


proc 

near 







push 

BP 

r 

save BP 





mov 

BP, SP 

r 

get access 

to 

arguments 

r 

; body 

of 

function 






r 


mov 

SP, BP 

r 

restore SP 





pop 

BP 

r 

restore BP 





ret 

4 

r 

return and 

pop 

last arg 

myrtn_ 


endp 






_ TEXT 


ends 






Large Memory Model (big code, big data) 





DGROUP 


group 

_ DATA, _ 

BSS 




MYRTN_ 

TEXT segment 

byte public 'CODE' 





assume 

CS:MYRTN_ 

. TEXT 






public 

myrtn_ 





myrtn_ 


proc 

far 







push 

BP 

r 

save BP 





mov 

BP, SP 

r 

get access 

to 

arguments 

r 

; body 

of 

function 






r 


mov 

SP, BP 

r 

restore SP 





pop 

BP 

r 

restore BP 





ret 

4 

r 

return and 

pop 

last arg 

myrtn_ 


endp 







MYRTN_ TEXT ends 
Notes: 

1. Global function names must be followed with an underscore. Global variable names must be 
preceded with an underscore. 

2. All used 80x86 registers must be saved on entry and restored on exit except those used to pass 
arguments and return values, and AX, which is considered a stratch register. Note that segment 
registers only have to saved and restored if you are compiling your application with the "r" 
option. 

3. The direction flag must be clear before returning to the caller. 

4. In a small code model, any segment containing executable code must belong to the segment 
"_TEXT" and the class "CODE". The segment "_TEXT" must have a "combine" type of 
"PUBLIC". On entry, CS contains the segment address of the segment "_TEXT". In a big code 
model there is no restriction on the naming of segments which contain executable code. 

5. In a small data model, segment register DS contains the segment address of the group 
"DGROUP". This is not the case in a big data model. 
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6. When writing assembly language functions for the small code model, you must declare them as 
"near". If you wish to write assembly language functions for the big code model, you must 
declare them as "far". 

7. In general, when naming segments for your code or data, you should follow the conventions 
described in the section entitled "Memory Layout" in this chapter. 

8. If any of the arguments was pushed onto the stack, the called routine must pop those arguments 
off the stack in the "ret" instruction. 


7.4.6 Functions with Variable Number of Arguments 

A function prototype with a parameter list that ends with has a variable number of arguments. In this 
case, all arguments are passed on the stack. Since no prototyping information exists for arguments 
represented by those arguments are passed as described in the section "Passing Arguments". 

7.4.7Returning Values from Functions 

The way in which function values are returned depends on the size of the return value. The following 
examples describe how function values are to be returned. They are coded for a small code model. 

1. 1-byte values are to be returned in register AL. 

Example: 

_ TEXT segment byte public 'CODE' 
assume CS:_TEXT 
public Retl_ 

Retl_ proc near ; char Retl() 
mov AL, ' G' 

ret 

Retl_ endp 

_ TEXT ends 

end 

2. 2-byte values are to be returned in register AX. 

Example: 

_ TEXT segment byte public 'CODE' 
assume CS:_TEXT 
public Ret2_ 

Ret2_ proc near ; short int Ret2() 

mov AX,77 

ret 

Ret2_ endp 

_ TEXT ends 

end 

3. 4-byte values are to be returned in registers DX and AX with the most significant word in 
register DX. 


Calling Conventions for Non-80x87 Applications 133 




16-bit Topics 


Example: 


_ TEXT 

segment 

byte public 'CODE' 


assume 

CSTEXT 


public 

Ret4_ 

Ret4_ 

proc 

near ; long int Ret 


mov 

AX,word ptr CS:Val4+0 


mov 

DX,word ptr CS:Val4+2 


ret 


Val4 

dd 

7777777 


Ret4_ endp 
_ TEXT ends 
end 


4. 8-byte values, except structures, are to be returned in registers AX, BX, CX and DX with the 
most significant word in register AX. 


Example: 

_ TEXT 

Ret8_ 


Val8 : 
Ret8_ 
_ TEXT 


. 8087 


segment 

assume 

public 

proc 

mov 

mov 

mov 

mov 

ret 

dq 

endp 

ends 

end 


byte public 'CODE' 
CS TEXT 
Ret8_ 


near ; double Ret8() 
DX,word ptr 


CX,word ptr 
BX,word ptr 
AX,word ptr 


CS:Val8+0 
CS:Val8+2 
CS:Val8+4 
CS:Val8+6 


7.7 


The ".8087" pseudo-op must be specified so that all floating-point constants are generated in 
8087 format. When using the "fpc" (floating-point calls) option, "float" and "double" are 
returned in registers. See section "Returning Values in 80x87-based Applications" when using 
the "fpi" or "fpi87" options. 

5. Otherwise, the caller allocates space on the stack for the return value and sets register SI to point 
to this area. In a big data model, register SI contains an offset relative to the segment value in 
segment register SS. 
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Example: 

_ TEXT segment byte public 'CODE' 
assume CS:_TEXT 
public RetX_ 

r 

; struct int_ values { 

; int valuel, value2, value3, value4, value5; 


r 

r 


} 

r 



RetX_ 

proc 

near 

; struct int. 

_ values RetX() 


mov 

word 

ptr 

SS : 0 [SI], 

71 


mov 

word 

ptr 

SS : 4 [SI], 

72 


mov 

word 

ptr 

SS : 8 [SI], 

73 


mov 

word 

ptr 

SS:12 [SI] 

,74 

RetX_ 

_ TEXT 

mov 

ret 

endp 

ends 

end 

word 

ptr 

SS:16 [SI] 

,75 


When returning values on the stack, remember to use a segment override to the stack segment 
(SS). 


The following is an example of a Open Watcom C/C++ program calling the above assembly language 
subprograms. 


♦include <stdio.h> 

struct int_ values { 
int valuel; 
int value2; 
int value3; 
int value4; 
int value5; 

} ; 

Retl(void); 
Ret2(void); 
Ret4(void); 
Ret8(void); 
values RetX(void); 


extern char 
extern short int 
extern long int 
extern double 
extern struct int 


void main() 

{ 

struct int_ values x; 


printf( 

"Retl = 

% c \ n " , 

Retl() ) ; 


printf( 

"Ret2 = 

%d\n", 

Ret2 () ) ; 


printf( 

"Ret4 = 

%ld\n", 

Ret4 () ) ; 


printf( 

"Ret8 = 

% f \ n " , 

Ret8 () ) ; 


x = RetX(); 




printf( 

"RetXl 

= %d\n". 

x.valuel 

; 

printf( 

"RetX2 

= %d\n". 

x.value2 

; 

printf( 

"RetX3 

= %d\n". 

x.value3 

; 

printf( 

"RetX4 

= %d\n". 

x.value4 

; 

printf( 

"RetX5 

= %d\n". 

x.value5 

; 
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The above function should be compiled for a small code model (use the "ms" or "me" compiler option). 


7.5 Calling Conventions for 80x87-based Applications 

When a source file is compiled by Open Watcom C/C++ with one of the "fpi" or "fpi87" options, all 
floating-point arguments are passed on the 80x86 stack. The rules for passing arguments are as follows. 

1. If the argument is not floating-point, use the procedure described earlier in this chapter. 

2. If the argument is floating-point, it is assigned a position on the 80x86 stack. 

7.5.1 Passing Values in 80x87-based Applications 

Consider the following example. 

Example: 

extern void myrtn(int,float,double,long int); 

void main() 

{ 

float x; 

double y; 

int i; 

long int j; 

x = 7.7; 
i = 7; 
y = 77.77 
j = 77; 

myrtn( i, x, y, j ); 

} 

myrtn is an assembly language function that requires four arguments. The first argument is of type "int" ( 
2 bytes), the second argument is of type "float" (4 bytes), the third argument is of type "double" (8 bytes) 
and the fourth argument is of type "long int" (4 bytes). These arguments will be passed to myrtn in the 
following way: 

1. The first argument will be passed in register AX leaving BX, CX and DX as available registers 
for other arguments. 

2. The second argument will be passed on the 80x86 stack since it is a floating-point argument. 

3. The third argument will also be passed on the 80x86 stack since it is a floating-point argument. 

4. The fourth argument will be passed on the 80x86 stack since a previous argument has been 
assigned a position on the 80x86 stack. 

Remember, arguments are pushed on the stack from right to left. That is, the rightmost argument is pushed 
first. 

Any assembly language function must obey the following rule. 

1. All arguments passed on the stack must be removed by the called function. 


136 Calling Conventions for 80x87-based Applications 




16-bit Assembly Language Considerations 


The following is a sample assembly language function which implements myrtn . 
Example: 

.8087 

_ TEXT segment byte public 'CODE' 
assume CS:_TEXT 
public myrtn_ 
myrtn_ proc near 

r 

; body of function 

r 

ret 16 ; return and pop arguments 

myrtn_ endp 
_ TEXT ends 
end 


Notes: 

1. Function names must be followed by an underscore. 

2. All used 80x86 registers must be saved on entry and restored on exit except those used to pass 
arguments and return values, and EAX, which is considered a stratch register. Note that segment 
registers only have to saved and restored if you are compiling your application with the "r" 
option. In this example, AX does not have to be saved as it was used to pass the first argument. 
Floating-point registers can be modified without saving their contents. 

3. The direction flag must be clear before returning to the caller. 

4. This function has been written for a small code model. Any segment containing executable code 
must belong to the class "CODE" and the segment "_TEXT". On entry, CS contains the segment 
address of the segment "_TEXT". The above restrictions do not apply in a big code memory 
model. 

5. When writing assembly language functions for a small code model, you must declare them as 
"near". If you wish to write assembly language functions for a big code model, you must declare 
them as "far". 


7.5.2 Returning Values in 80x87-based Applications 

Floating-point values are returned in ST(0) when using the "fpi" or "fpi87" options. All other values are 
returned in the manner described earlier in this chapter. 
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8.1 Introduction 


A pragma is a compiler directive that provides the following capabilities. 

• Pragmas allow you to specify certain compiler options. 

• Pragmas can be used to direct the Open Watcom C/C++ code generator to emit specialized 
sequences of code for calling functions which use argument passing and value return techniques that 
differ from the default used by Open Watcom C/C++. 

• Pragmas can be used to describe attributes of functions (such as side effects) that are not possible at 
the C/C++ language level. The code generator can use this information to generate more efficient 
code. 

• Any sequence of in-line machine language instructions, including DOS and BIOS function calls, can 
be generated in the object code. 

Pragmas are specified in the source file using the pragma directive. The following notation is used to 
describe the syntax of pragmas. 

keywords A keyword is shown in a mono-spaced courier font. 

program-item A program-item is shown in a roman bold-italics font. A program-item is a symbol name 
or numeric value supplied by the programmer. 

punctuation A punctuation character shown in a mono-spaced courier font must be entered as 
is. 

A punctuation character shown in a roman bold-italics font is used to describe syntax. 

The following syntactical notation is used. 

[abc] The item abc is optional. 

{abc} The item abc may be repeated zero or more times, 

alblc One of a, b or c may be specified, 

a ::= b The item a is defined in terms of b. 

(a) Item a is evaluated first. 

The following classes of pragmas are supported. 


Introduction 139 




16-bit Topics 


• pragmas that specify options 

• pragmas that specify default libraries 

• pragmas that describe the way structures are stored in memory 

• pragmas that provide auxiliary information used for code generation 

8.2 Using Pragmas to Specify Options 

Currently, the following options can be specified with pragmas: 

unreferenced The "unreferenced" option controls the way Open Watcom C/C++ handles unused symbols. 
For example, 

♦pragma on (unreferenced); 

will cause Open Watcom C/C++ to issue warning messages for all unused symbols. This is 
the default. Specifying 

♦pragma off (unreferenced); 

will cause Open Watcom C/C++ to ignore unused symbols. Note that if the warning level 
is not high enough, warning messages for unused symbols will not be issued even if 
"unreferenced" was specified. 

check_stack The "check_stack" option controls the way stack overflows are to be handled. For 
example, 

♦pragma on (check_ stack); 
will cause stack overflows to be detected and 
♦pragma off (check_ stack); 

will cause stack overflows to be ignored. When "check_stack" is on. Open Watcom C/C++ 
will generate a run-time call to a stack-checking routine at the start of every routine 
compiled. This run-time routine will issue an error if a stack overflow occurs when 
invoking the routine. The default is to check for stack overflows. Stack overflow checking 
is particularly useful when functions are invoked recursively. Note that if the stack 
overflows and stack checking has been suppressed, unpredictable results can occur. 

If a stack overflow does occur during execution and you are sure that your program is not 
in error (i.e. it is not unnecessarily recursing), you must increase the stack size. This is 
done by linking your application again and specifying the "STACK" option to the Open 
Watcom Linker with a larger stack size. 

It is also possible to specify more than one option in a pragma as illustrated by the 
following example. 

♦pragma on (check_ stack unreferenced); 
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reuse-duplicate _strings (C only) (C Only) The "reuse_duplicate_strings" option controls the way Open 
Watcom C handles identical strings in an expression. For example, 

#pragma on (reuse_ duplicate_ strings); 

will cause Open Watcom C to reuse identical strings in an expression. This is the default. 
Specifying 

#pragma off (reuse_ duplicate_ strings) ; 

will cause Open Watcom C to generate additional copies of the identical string. The 
following example shows where this may be of importance to the way the application 
behaves. 

Example: 

♦include <stdio.h> 

♦pragma off (reuse_ duplicate_ strings) 


void poke( char *, char * ); 

void main() 

{ 

poke( "Hello world\n", "Hello world\n" ); 

} 

void poke( char *x, char *y ) 

{ 

x[3] = 'X'; 
printf( x ); 
y[4] = 'Y'; 
printf( y ) ; 

} 

/* 

Default output: 

HelXo world 
HelXY world 
*/ 


8.3 Using Pragmas to Specify Default Libraries 

Default libraries are specified in special object module records. Library names are extracted from these 
special records by the Open Watcom Linker. When unresolved references remain after processing all 
object modules specified in linker "FILE" directives, these default libraries are searched after all libraries 
specified in linker "LIBRARY" directives have been searched. 

By default, that is if no library pragma is specified, the Open Watcom C/C++ compiler generates, in the 
object file defining the main program, default libraries corresponding to the memory model and 
floating-point model used to compile the file. For example, if you have compiled the source file containing 
the main program for the medium memory model and the floating-point calls floating-point model, the 
libraries "clibm" and "mathm" will be placed in the object file. 

If you wish to add your own default libraries to this list, you can do so with a library pragma. Consider the 
following example. 
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#pragma library (mylib); 

The name "mylib" will be added to the list of default libraries specified in the object file. 

If the library specification contains characters such as ’V, or (i.e., any character not allowed in a C 
identifier), you must enclose it in double quotes as in the following example. 

♦pragma library ("\watcom\lib286\dos\graph.lib"); 

♦pragma library ("\watcom\lib386\dos\graph.lib"); 

If you wish to specify more than one library in a library pragma you must separate them with spaces as in 
the following example. 

♦pragma library (mylib "\watcom\lib286\dos\graph.lib"); 

♦pragma library (mylib "\watcom\lib386\dos\graph.lib") ; 

8.4 The ALIAS Pragma (C Only) 

The "alias" pragma can be used to emit alias records in the object file, causing the linker to substitute 
references to a specified symbol with references to another symbol. Either identifiers or names (strings) 
may be used. Strings are used verbatim, while names corresponding to identifiers are derived as 
appropriate for the kind and calling convention of the symbol. The following describes the form of the 
"alias" pragma. 


♦pragma alias ( alias, subst ) [;] 


where description: 

alias is either a name or an identifier of the symbol to be aliased. 

subst is either a name or an identifier of the symbol that references to alias will be replaced 

with. 

Consider the following example. 

extern int var; 

void fn( void ) 

{ 

var = 3; 

} 

♦pragma alias ( var, "other_ var" ) ; 

Instead of var the linker will reference symbol named "other_var". Symbol var need not be defined, 
although "other_var" has to be. 
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8.5 The ALLOC_TEXT Pragma (C Only) 

The "alloc_text" pragma can be used to specify the name of the text segment into which the generated code 
for a function, or a list of functions, is to be placed. The following describes the form of the "alloc_text" 
pragma. 


♦pragma alloc_ text ( seg_name, fn {, fn} ) [;] 


where description: 

segjiame is the name of the text segment. 

fn is the name of a function. 

Consider the following example. 

extern int fnl (int); 
extern int fn2(void); 

♦pragma alloc_ text ( my_text, fnl, fn2 ); 

The code for the functions fnl and fn2 will be placed in the segment my_ text. Note: function 
prototypes for the named functions must exist prior to the "alloc_text" pragma. 

8.6 The CODE_SEG Pragma 

The "code_seg" pragma can be used to specify the name of the text segment into which the generated code 
for functions is to be placed. The following describes the form of the "code_seg" pragma. 


♦pragma code_ seg ( seg_name [, class_name] ) [;] 


where description: 

segjiame is the name of the text segment optionally enclosed in quotes. Also, seg_ name may be a 
macro as in: 

♦ define seg_ name "MY_ CODE_ SEG" 

♦pragma code_ seg ( seg_ name ) ; 


class jiame is the optional class name of the text segment and may be enclosed in quotes. Please note 

that in order to be recognized by the linker as code, a class name has to end in "CODE". 
Also, class_ name may be a macro as in: 

♦define class_ name "MY_ CODE" 

♦pragma code_ seg ( "MY_ CODE_ SEG", class_ name ); 


Consider the following example. 


The CODE_SEG Pragma 143 





16-bit Topics 


♦pragma code_ seg ( my_ text ) ; 

int incr( int i ) 

{ 

return( i + 1 ); 

} 

int deer( int i ) 

{ 

return( i - 1 ); 

} 

The code for the functions incr and deer will be placed in the segment my_ text. 

To return to the default segment, do not specify any string between the opening and closing parenthesis, 
♦pragma code_ seg (); 


8.7 The COMMENT Pragma 

The "comment" pragma can be used to place a comment record in an object file or executable file. The 
following describes the form of the "comment" pragma. 


♦pragma comment ( comment_type [, "comment_string"] ) [;] 


where description: 

comment Jype specifies the type of comment record. The allowable comment types are: 

lib Default libraries are specified in special object module records. Library 

names are extracted from these special records by the Open Watcom 
Linker. When unresolved references remain after processing all object 
modules specified in linker "FILE" directives, these default libraries are 
searched after all libraries specified in linker "LIBRARY" directives have 
been searched. 

The "lib" form of this pragma offers the same features as the "library" 
pragma. See the section entitled "Using Pragmas to Specify Default 
Libraries" on page 141 for more information. 

" commentjstring" is an optional string literal that provides additional information for some comment 
types. 

Consider the following example. 

♦pragma comment ( lib, "mylib" ); 
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8.8 The DATA_SEG Pragma 

The "data_seg" pragma can be used to specify the name of the segment into which data is to be placed. The 
following describes the form of the "data_seg" pragma. 


♦pragma data_ seg ( seg_name [, class_name] ) [;] 


where description: 

segjiame is the name of the data segment and may be enclosed in quotes. Also, seg_ name may be 

a macro as in: 

♦ define seg_ name "MY_ DATA_ SEG" 

♦pragma data_ seg ( seg_ name ) ; 

class_name is the optional class name of the data segment and may be enclosed in quotes. Also, 
class_ name may be a macro as in: 

♦define class_ name "MY_ CLASS" 

♦pragma data_ seg ( "MY_ DATA_ SEG", class_ name ) ; 

Consider the following example. 

♦pragma data_ seg ( my_ data ) ; 

static int i; 
static int j; 

The data for i and j will be placed in the segment my_ data . 

To return to the default segment, do not specify any string between the opening and closing parenthesis, 
♦pragma data_ seg (); 

8.9 The DISABLE_MESSAGE Pragma 

The "disable_message" pragma disables the issuance of specified diagnostic messages. The form of the 
"disable_message" pragma is as follows. 


♦pragma disable_ message ( msg_num {, msg_num} ) [;] 


where description: 

msg_num is the number of the diagnostic message. This number corresponds to the number issued by 
the compiler and can be found in the appendix entitled "Open Watcom C Diagnostic 
Messages" on page 305. Make sure to strip all leading zeroes from the message number (to 
avoid interpretation as an octal constant). 
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See also the description of "The ENABLE_MESSAGE Pragma". 


8.10 The DUMP_OBJECT_MODEL Pragma (C++ Only) 

The "dump_object_model" pragma causes the C++ compiler to print information about the object model for 
an indicated class or an enumeration name to the diagnostics file. For class names, this information 
includes the offsets and sizes of fields within the class and within base classes. For enumeration names, 
this information consists of a list of all the enumeration constants with their values. 

The general form of the "dump_object_model" pragma is as follows. 


♦pragma dump_ object_ model class [;] 
♦pragma dump_ object_ model enumeration [;] 
class ::= a defined C++ class free of errors 
enumeration ::= a defined C++ enumeration name 


This pragma is designed to be used for information purposes only. 


8.11 The ENABLE_MESSAGE Pragma 

The "enable_message" pragma re-enables the issuance of specified diagnostic messages that have been 
previously disabled. The form of the "enable_message" pragma is as follows. 


♦pragma enable_ message ( msg_num {, msg_num} ) [;] 


where description: 

msgjium is the number of the diagnostic message. This number corresponds to the number issued by 
the compiler and can be found in the appendix entitled "Open Watcom C Diagnostic 
Messages" on page 305. Make sure to strip all leading zeroes from the message number (to 
avoid interpretation as an octal constant). 

See also the description of "The DISABLE_MESSAGE Pragma" on page 145. 


8.12 The ENUM Pragma 

The "enum" pragma affects the underlying storage-definition for subsequent enum declarations. The forms 
of the "enum" pragma are as follows. 


♦pragma 

♦pragma 

♦pragma 

♦pragma 


enum int [;] 
enum minimum [;] 
enum original [;] 
enum pop [;] 
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where description: 

int Make int the underlying storage definition (same as the "ei" compiler option). 

minimum Minimize the underlying storage definition (same as not specifying the "ei" compiler 
option). 

original Reset back to the original compiler option setting (i.e., what was or was not specified on the 

command line). 

pop Restore the previous setting. 

The first three forms all push the previous setting before establishing the new setting. 


8.13 The ERROR Pragma 

The "error" pragma can be used to issue an error message with the specified text. The following describes 
the form of the "error" pragma. 


♦pragma error "error text" [;] 


where description: 

"error text" is the text of the message that you wish to display. 

You should use the ISO #error directive rather than this pragma. This pragma is provided for compatibility 
with legacy code. The following is an example. 

#if defined(_ 386_) 

♦elseif defined!_86_) 

♦ else 

♦pragma error ( "neither_ 386_or_86_defined" ); 

♦endif 


8.14 The EXTREF Pragma 

The "extref" pragma is used to generate a reference to an external function or data item. The form of the 
"extref" pragma is as follows. 


♦pragma extref name [;] 
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where description: 

name is the name of an external function or data item. It must be declared to be an external 

function or data item before the pragma is encountered. In C++, when name is a function, 
it must not be overloaded. 

This pragma causes an external reference for the function or data item to be emitted into the object file even 
if that function or data item is not referenced in the module. The external reference will cause the linker to 
include the module containing that name in the linked program or DLL. 

This is useful for debugging since you can cause debugging routines (callable from within debugger) to be 
included into a program or DLL to be debugged. 

In C++, you can also force constructors and/or destructors to be called for a data item without necessarily 
referencing the data item anywhere in your code. 

8.15 The FUNCTION Pragma 

Certain functions, such as those listed in the description of the "oi" and "om" options, have intrinsic forms. 
These functions are special functions that are recognized by the compiler and processed in a special way. 
For example, the compiler may choose to generate in-line code for the function. The intrinsic attribute for 
these special functions is set by specifying the "oi" or "om" option or using an "intrinsic" pragma. The 
"function" pragma can be used to remove the intrinsic attribute for a specified list of functions. 

The following describes the form of the "function" pragma. 


♦pragma function ( fn {, fn} ) [;] 


where description: 

fn is the name of a function. 

Suppose the following source code was compiled using the "om" option so that when one of the special 
math functions is referenced, the intrinsic form will be used. In our example, we have referenced the 
function sin which does have an intrinsic form. By specifying sin in a "function" pragma, the intrinsic 
attribute will be removed, causing the function sin to be treated as a regular user-defined function. 

♦include <math.h> 

♦pragma function( sin ) ; 

double test ( double x ) 

{ 

return( sin( x ) ); 

} 
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8.16 The INCLUDE_ALIAS Pragma 

In certain situations, it can be advantageous to remap the names of include files. Most commonly this 
occurs on systems that do not support long file names when building source code that references header 
files with long names. 

The form of the "include_alias" pragma follows. 


♦pragma 

include_ 

alias 

( "alias_name", "real_name" ) 

' [;] 

♦pragma 

include_ 

alias 

( <alias_name>, <real_name> ) 

' [;] 


where description: 

alias jiame is the name referenced in include directives in source code. 
realjiame is the translated name that the compiler will reference instead. 

The following is an example. 

♦pragma include_ alias( "LongFileName.h", "lfn.h" ) 

♦include "LongFileName.h" 

In the example, the compiler will attempt to read lfn.h when LongFileName.h was included. 

Note that only simple textual substitution is performed. The aliased name must match exactly, including 
double quotes or angle brackets, as well as any directory separators. Also, double quotes and angle 
brackets may not be mixed a single pragma. 

The value of the predefined_ FILE _symbol, as well as the filename reported in error messages, will be 

the true filename after substitution was performed. 

8.17 Setting Priority of Static Data Initialization (C++ Only) 

The "initialize" pragma sets the priority for initialization of static data in the file. This priority only applies 
to initialization of static data that requires the execution of code. For example, the initialization of a class 
that contains a constructor requires the execution of the constructor. Note that if the sequence in which 
initialization of static data in your program takes place has no dependencies, the "initialize" pragma need 
not be used. 

The general form of the "initialize" pragma is as follows. 


♦pragma initialize [before I after] priority [;] 
priority ::= n I library I program 
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where description: 

n is a number representing the priority and must be in the range 0-255. The larger the 

priority, the later the point at which initialization will occur. 

Priorities in the range 0-20 are reserved for the C++ compiler. This is to ensure that proper initialization of 
the C++ run-time system takes place before the execution of your program. The "library" keyword 
represents a priority of 32 and can be used for class libraries that require initialization before the program is 
initialized. The "program" keyword represents a priority of 64 and is the default priority for any compiled 
code. Specifying "before" adjusts the priority by subtracting one. Specifying "after" adjusts the priority by 
adding one. 

A source file containing the following "initialize" pragma specifies that the initialization of static data in the 
file will take place before initialization of all other static data in the program since a priority of 63 will be 
assigned. 

Example: 

♦pragma initialize before program 

If we specify "after" instead of "before", the initialization of the static data in the file will occur after 
initialization of all other static data in the program since a priority of 65 will be assigned. 

Note that the following is equivalent to the "before" example 

Example: 

♦pragma initialize 63 
and the following is equivalent to the "after" example. 

Example: 

♦pragma initialize 65 

The use of the "before", "after", and "program" keywords are more descriptive in the intent of the pragmas. 

It is recommended that a priority of 32 (the priority used when the "library" keyword is specified) be used 
when developing class libraries. This will ensure that initialization of static data defined by the class 
library will take place before initialization of static data defined by the program. The following "initialize" 
pragma can be used to achieve this. 

Example: 

♦pragma initialize library 

8.18 The INUNE_DEPTH Pragma (C++ Only) 

When an in-line function is called, the function call may be replaced by the in-line expansion for that 
function. This in-line expansion may include calls to other in-line functions which can also be expanded. 
The "inline_depth" pragma can be used to set the number of times this expansion of in-line functions will 
occur for a call. 

The form of the "inline_depth" pragma is as follows. 
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♦pragma inline_ depth [(] n [)] [;] 


where description: 

n is the depth of expansion. If n is 0, no expansion will occur. If n is 1, only the original call 

is expanded. If n is 2, the original call and the in-line functions invoked by the original 
function will be expanded. The default value for n is 3. The maximum value for n is 255. 
Note that no expansion of recursive in-line functions occur unless enabled using the 
"inline_recursion" pragma. 

8.19 The INLINE_RECURSION Pragma (C++ Only) 

The "inline_recursion" pragma controls the recursive expansion of inline functions. The form of the 
"inline_recursion" pragma is as follows. 


♦pragma inline_ recursion [(] on I off [)] [;] 


Specifying "on" will enable expansion of recursive inline functions. The depth of expansion is specified by 
the "inline_depth" pragma. The default depth is 3. Specifying "off" suppresses expansion of recursive 
inline functions. This is the default. 


8.20 The INTRINSIC Pragma 

Certain functions, those listed in the description of the "oi" option, have intrinsic forms. These functions 
are special functions that are recognized by the compiler and processed in a special way. For example, the 
compiler may choose to generate in-line code for the function. The intrinsic attribute for these special 
functions is set by specifying the "oi" option or using an "intrinsic" pragma. 

The following describes the form of the "intrinsic" pragma. 


♦pragma intrinsic ( fn {, fn} ) [;] 


where description: 

fn is the name of a function. 

Suppose the following source code was compiled without using the "oi" option so that no function had the 
intrinsic attribute. If we wanted the intrinsic form of the sin function to be used, we could specify the 
function in an "intrinsic" pragma. 
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♦include <math.h> 

♦pragma intrinsic( sin ) ; 

double test ( double x ) 

{ 

return( sin( x ) ); 

} 


8.21 The MESSAGE Pragma 

The "message" pragma can be used to issue a message with the specified text to the standard output without 
terminating compilation. The following describes the form of the "message" pragma. 


♦pragma message ( "message text" ) [;] 


where description: 

"message text" is the text of the message that you wish to display. 

The following is an example. 

♦ if defined!_ 386_) 

♦ else 

♦pragma message ( "assuming 16-bit compile" ); 
♦endif 


8.22 The ONCE Pragma 

The "once" pragma can be used to indicate that the file which contains this pragma should only be opened 
and processed "once". The following describes the form of the "once" pragma. 


♦pragma once [;] 


Assume that the file "foo.h" contains the following text. 


Example: 

♦ ifndef _ F00_ H_ INCLUDED 
♦define _ F00_ H_ INCLUDED 
♦pragma once 


♦endif 

The first time that the compiler processes "foo.h" and encounters the "once" pragma, it records the file’s 
name. Subsequently, whenever the compiler encounters a ♦include statement that refers to "foo.h", it 
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will not open the include file again. This can help speed up processing of #include files and reduce the 
time required to compile an application. 

8.23 The PACK Pragma 

The "pack" pragma can be used to control the way in which structures are stored in memory. There are 4 
forms of the "pack" pragma. 

The following form of the "pack" pragma can be used to change the alignment of structures and their fields 
in memory. 


♦pragma pack ( n ) [;] 


where description: 

n is 1, 2, 4, 8 or 16 and specifies the method of alignment. 


The alignment of structure members is described in the following table. If the size of the member is 1,2, 4, 
8 or 16, the alignment is given for each of the "zp" options. If the member of the structure is an array or 
structure, the alignment is described by the row "x". 


sizeof(member) 
1 
2 
4 
8 

16 

x 


\ 


zpl zp2 zp4 zp8 


0 

0 

0 

0 

0 


0 

2 

2 

2 

2 


aligned to 


0 

2 

4 

4 

4 


0 

2 

4 

8 

8 


largest member 


zpl 6 


0 

2 

4 

8 

16 


An alignment of 0 means no alignment, 2 means word boundary, 4 means doubleword boundary, etc. If the 
largest member of structure "x" is 1 byte then "x" is not aligned. If the largest member of structure "x" is 2 
bytes then "x" is aligned according to row 2. If the largest member of structure "x" is 4 bytes then "x" is 
aligned according to row 4. If the largest member of structure "x" is 8 bytes then "x" is aligned according 
to row 8. If the largest member of structure "x" is 16 bytes then "x" is aligned according to row 16. 

If no value is specified in the "pack" pragma, a default value of 2 is used. Note that the default value can be 
changed with the "zp" Open Watcom C/C++ compiler command line option. 

The following form of the "pack" pragma can be used to save the current alignment amount on an internal 
stack. 


♦pragma pack ( push ) [;] 


The following form of the "pack" pragma can be used to save the current alignment amount on an internal 
stack and set the current alignment. 
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♦pragma pack ( push, number ) [;] 


The following form of the "pack" pragma can be used to restore the previous alignment amount from an 
internal stack. 


♦pragma pack ( pop ) [;] 


8.24 The READ_ONLY_FILE Pragma 

Explicit listing of dependencies in a makefile can often be tedious in the development and maintenance 
phases of a project. The Open Watcom C/C++ compiler will insert dependency information into the object 
file as it processes source files so that a complete snapshot of the files necessary to build the object file are 
recorded. The "read_only_file" pragma can be used to prevent the name of the source file that includes it 
from being included in the dependency information that is written to the object file. 

This pragma is commonly used in system header files since they change infrequently (and, when they do, 
there should be no impact on source files that have included them). 

The form of the "read_only_file" pragma follows. 


♦pragma read_ only_ file [;] 


For more information on make dependencies, see the section entitled "Automatic Dependency Detection 
(.AUTODEPEND)" in the Open Watcom C/C++ Tools User’s Guide. 

8.25 The TEMPLA TE_DEPTH Pragma (C++ Only) 

The "template_depth" pragma provides a hard limit for the amount of nested template expansions allowed 
so that infinite expansion can be detected. 

The form of the "template_depth" pragma is as follows. 


♦pragma template_ depth [(] n [)] [;] 


where description: 

n is the depth of expansion. If the value of n is less than 2, if will default to 2. If n is not 

specified, a warning message will be issued and the default value for n will be 100. 

The following example of recursive template expansion illustrates why this pragma can be useful. 
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Example: 

♦pragma template_ depth(10); 

template <class T> 
struct S { 

S<T*> x; 

} ; 


S<char> v; 


8.26 The WARNING Pragma (C++ Only) 

The "warning" pragma sets the level of warning messages. The form of the "warning" pragma is as 
follows. 


♦pragma warning msg_num level [;] 


where description: 

msg_num is the number of the warning message. This number corresponds to the number issued by 
the compiler and can be found in the appendix entitled "Open Watcom C++ Diagnostic 
Messages" on page 337. If msg_ num is the level of all warning messages is changed 
to the specified level. Make sure to strip all leading zeroes from the message number (to 
avoid interpretation as an octal constant). 

level is a number from 0 to 9 and represents the level of the warning message. When a value of 

zero is specified, the warning becomes an error. 

8.27 Auxiliary Pragmas 

The following sections describe the capabilities provided by auxiliary pragmas. 

8.27.1 Specifying Symbol Attributes 

Auxiliary pragmas are used to describe attributes that affect code generation. Initially, the compiler defines 
a default set of attributes. Each auxiliary pragma refers to one of the following. 

1. a symbol (such as a variable or function) 

2. a type definition that resolves to a function type 

3. the default set of attributes defined by the compiler 

When an auxiliary pragma refers to a particular symbol, a copy of the current set of default attributes is 
made and merged with the attributes specified in the auxiliary pragma. The resulting attributes are assigned 
to the specified symbol and can only be changed by another auxiliary pragma that refers to the same 
symbol. 

An example of a type definition that resolves to a function type is the following. 
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typedef void (*func_ type) (); 

When an auxiliary pragma refers to a such a type definition, a copy of the current set of default attributes is 
made and merged with the attributes specified in the auxiliary pragma. The resulting attributes are assigned 
to each function whose type matches the specified type definition. 

When "default" is specified instead of a symbol name, the attributes specified by the auxiliary pragma 
change the default set of attributes. The resulting attributes are used by all symbols that have not been 
specifically referenced by a previous auxiliary pragma. 

Note that all auxiliary pragmas are processed before code generation begins. Consider the following 
example. 

code in which symbol x is referenced 
♦pragma aux y <attrs_ 1>; 
code in which symbol y is referenced 
code in which symbol z is referenced 
♦pragma aux default <attrs_ 2>; 

♦pragma aux x <attrs_ 3>; 

Auxiliary attributes are assigned to x, y and z in the following way. 

1. Symbol x is assigned the initial default attributes merged with the attributes specified by 
<attrs_ 2> and<attrs_ 3> . 

2. Symbol y is assigned the initial default attributes merged with the attributes specified by 
<attrs_ 1>. 

3. Symbol z is assigned the initial default attributes merged with the attributes specified by 
<attrs_ 2>. 

8.27.2 Alias Names 

When a symbol referred to by an auxiliary pragma includes an alias name, the attributes of the alias name 
are also assumed by the specified symbol. 

There are two methods of specifying alias information. In the first method, the symbol assumes only the 
attributes of the alias name; no additional attributes can be specified. The second method is more general 
since it is possible to specify an alias name as well as additional auxiliary information. In this case, the 
symbol assumes the attributes of the alias name as well as the attributes specified by the additional auxiliary 
information. 

The simple form of the auxiliary pragma used to specify an alias is as follows. 


♦pragma aux ( sym, alias ) [;] 
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where description: 

sym is any valid C/C++ identifier. 

alias is the alias name and is any valid C/C++ identifier. 

Consider the following example. 

♦pragma aux push_ args parm [] ; 

♦pragma aux ( rtn, push_ args ) ; 

The routine rtn assumes the attributes of the alias name push_ args which specifies that the arguments 
to rtn are passed on the stack. 

Let us look at an example in which the symbol is a type definition. 

typedef void (func_type) (int) ; 

♦pragma aux push_ args parm []; 

♦pragma aux ( func_ type, push_ args ) ; 

extern func_ type rtnl; 
extern func_ type rtn2; 

The first auxiliary pragma defines an alias name called push_ args that specifies the mechanism to be 
used to pass arguments. The mechanism is to pass all arguments on the stack. The second auxiliary 
pragma associates the attributes specified in the first pragma with the type definition f unc_ type . Since 
rtnl and rtn2 are of type func_ type, arguments to either of those functions will be passed on the 
stack. 

The general form of an auxiliary pragma that can be used to specify an alias is as follows. 


♦pragma aux ( alias ) sym aux_attrs [;] 


where description: 

alias is the alias name and is any valid C/C++ identifier. 

sym is any valid C/C++ identifier. 

aux_attrs are attributes that can be specified with the auxiliary pragma. 
Consider the following example. 


♦pragma aux MS_ C *" \ 


♦pragma 

aux 

parm caller [] 

value struct float struct routine 
modify [ax bx cx dx es]; 

(MS_ C) rtnl; 

\ 

[ax] \ 

♦pragma 

aux 

(MS_ C) rtn2; 


♦pragma 

aux 

(MS_ C) rtn3; 
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The routines rtnl, rtn2 and rtn3 assume the same attributes as the alias name MS_ C which defines the 
calling convention used by the Microsoft C compiler. Whenever calls are made to rtnl, rtn2 and 
rtn3, the Microsoft C calling convention will be used. 

Note that if the attributes of MS_ C change, only one pragma needs to be changed. If we had not used an 
alias name and specified the attributes in each of the three pragmas for rtnl, rtn2 and rtn3 , we would 
have to change all three pragmas. This approach also reduces the amount of memory required by the 
compiler to process the source file. 

WARNING! The alias name MS_ C is just another symbol. IfMS_ C appeared in your source code, it 
would assume the attributes specified in the pragma for MS_ C . 


8.27.3 Predefined Aliases 

A number of symbols are predefined by the compiler with a set of attributes that describe a particular 
calling convention. These symbols can be used as aliases. The following is a list of these symbols. 

_ cdecl _cdecl ocdecl defines the calling convention used by Microsoft compilers. 

fastcall _f astcall of astcall defines the calling convention used by Microsoft compilers. 

fortran _fortran of ortran defines the calling convention used by Open Watcom 

FORTRAN compilers. 

_ pascal _pascal opascal defines the calling convention used by OS/2 1.x and Windows 3.x 

API functions. 

_ stdcall _stdcall ostdcall defines the calling convention used by Microsoft compilers. 

_ watcall _watcall owatcall defines the calling convention used by Open Watcom 

compilers. 

The following describes the attributes of the above alias names. 

8.27.3.1 Predefined "_cded" Alias 

♦pragma aux_cdecl *" \ 

parm caller [] \ 

value struct float struct routine [ax] \ 
modify [ax bx cx dx es] 

Notes: 

1. All symbols are preceded by an underscore character. 

2. Arguments are pushed on the stack from right to left. That is, the last argument is pushed first. 
The calling routine will remove the arguments from the stack. 

3. Floating-point values are returned in the same way as structures. When a structure is returned, 
the called routine allocates space for the return value and returns a pointer to the return value in 
register AX. 
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4. Registers AX, BX, CX and DX, and segment register ES are not saved and restored when a call 
is made. 

8.27.3.2 Predefined "_pascal" Alias 

#pragma aux_pascal " A " \ 

parm reverse routine [] \ 

value struct float struct caller [] \ 

modify [ax bx cx dx es] 


Notes: 

1. All symbols are mapped to upper case. 

2. Arguments are pushed on the stack in reverse order. That is, the first argument is pushed first, 
the second argument is pushed next, and so on. The routine being called will remove the 
arguments from the stack. 

3. Floating-point values are returned in the same way as structures. When a structure is returned, 
the caller allocates space on the stack. The address of the allocated space will be pushed on the 
stack immediately before the call instruction. Upon returning from the call, register AX will 
contain address of the space allocated for the return value. 

4. Registers AX, BX, CX and DX, and segment register ES are not saved and restored when a call 
is made. 

8.27.3.3 Predefined "_watcall" Alias 

♦pragma aux_watcall " \ 

parm routine [ax bx cx dx] \ 
value struct caller 


Notes: 

1. Symbol names are followed by an underscore character. 

2. Arguments are processed from left to right. The leftmost arguments are passed in registers and 
the rightmost arguments are passed on the stack (if the registers used for argument passing have 
been exhausted). Arguments that are passed on the stack are pushed from right to left. The 
calling routine will remove the arguments if any were pushed on the stack. 

3. When a structure is returned, the caller allocates space on the stack. The address of the allocated 
space is put into SI register. The called routine then places the return value there. Upon 
returning from the call, register AX will contain address of the space allocated for the return 
value. 

4. Floating-point values are returned using 80x86 registers ("fpc" option) or using 80x87 
floating-point registers ("fpi" or "fpi87" option). 

5. All registers must be preserved by the called routine. 
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8.27.4 Alternate Names for Symbols 

The following form of the auxiliary pragma can be used to describe the mapping of a symbol from its 
source form to its object form. 

♦pragma aux sym obj_name [;] 

where description: 

sym is any valid C/C++ identifier. 

objjiame is any character string enclosed in double quotes. 

When specifying ob j_ name, some characters have a special meaning: 
where description: 

* is unmodified symbol name 

A is symbol name converted to uppercase 

/ is symbol name converted to lowercase 

# is a placeholder for "@nnn", where nnn is size of all function parameters on the stack; it is 
ignored for functions with variable argument lists, or for symbols that are not functions 

\ next character is treated as literal 

Several examples of source to object form symbol name translation follow: 

In the following example, the name "MyRtn" will be replaced by "MyRtn_" in the object file. 

♦pragma aux MyRtn 
This is the default for all function names. 

In the following example, the name "MyVar" will be replaced by "_MyVar" in the object file. 

♦pragma aux MyVar 
This is the default for all variable names. 

In the following example, the lower case version "myrtn" will be placed in the object file. 

♦pragma aux MyRtn 

In the following example, the upper case version "MYRTN" will be placed in the object file. 

♦pragma aux MyRtn " A "; 

In the following example, the name "MyRtn" will be replaced by "_MyRtn@nnn" in the object file, "nnn" 
represents the size of all function parameters. 
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#pragma aux MyRtn *#"; 

In the following example, the name "MyRtn" will be replaced by "_MyRtn#" in the object file. 
#pragma aux MyRtn *\#"; 

The default mapping for all symbols can also be changed as illustrated by the following example. 
#pragma aux default *_ 

The above auxiliary pragma specifies that all names will be prefixed and suffixed by an underscore 
character 

8.27.5 Describing Calling Information 

The following form of the auxiliary pragma can be used to describe the way a function is to be called. 


♦pragma aux sym far [;] 
or 

♦pragma aux sym near [;] 
or 

♦pragma aux sym = in line [;] 

in_line ::= { const I (seg id) I (offset id) I (reloff id) 
I (float fpinst) I "asm" } 


where description: 

sym is a function name. 

const is a valid C/C++ integer constant. 

id is any valid C/C++ identifier. 

fpinst is a sequence of bytes that forms a valid 80x87 instruction. The keyword float must 

precede fpinst so that special fixups are applied to the 80x87 instruction. 

seg specifies the segment of the symbol id. 

offset specifies the offset of the symbol id. 

reloff specifies the relative offset of the symbol id for near control transfers. 

asm is an assembly language instruction or directive. 

In the following example. Open Watcom C/C++ will generate a far call to the function myrtn. 
♦pragma aux myrtn far; 
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Note that this overrides the calling sequence that would normally be generated for a particular memory 
model. In other words, a far call will be generated even if you are compiling for a memory model with a 
small code model. 

In the following example. Open Watcom C/C++ will generate a near call to the function myrtn . 
♦pragma aux myrtn near; 

Note that this overrides the calling sequence that would normally be generated for a particular memory 
model. In other words, a near call will be generated even if you are compiling for a memory model with a 
big code model. 

In the following DOS example. Open Watcom C/C++ will generate the sequence of bytes following the "=" 
character in the auxiliary pragma whenever a call to mode 4 is encountered, mode4 is called an in-line 
function. 

void mode4(void) ; 

♦pragma aux mode4 = \ 


0xb4 

0x00 

/* 

mov 

AH, 0 

*/ 

\ 

OxbO 

0x04 

/* 

mov 

AL, 4 

*/ 

\ 

Oxcd 

0x10 

/* 

int 

10H 

*/ 

\ 


modify [ AH AL ]; 


The sequence in the above DOS example represents the following lines of assembly language instructions. 


mov 

AH, 0 

; select function "set mode" 

mov 

AL, 4 

; specify mode (mode 4) 

int 

10H 

; BIOS video call 


The above example demonstrates how to generate BIOS function calls in-line without writing an assembly 
language function and calling it from your C/C++ program. The C prototype for the function mode4 is not 
necessary but is included so that we can take advantage of the argument type checking provided by Open 
Watcom C/C++. 

The following DOS example is equivalent to the above example but mnemonics for the assembly language 
instructions are used instead of the binary encoding of the assembly language instructions. 

void mode4(void); 

♦pragma aux mode4 = \ 

"mov AH,0", \ 

"mov AL,4", \ 

"int 10H" \ 

modify [ AH AL ]; 

If a sequence of in-line assembly language instructions contains 80x87 floating-point instructions, each 
floating-point instruction must be preceded by "float". Note that this is only required if you have specified 
the "fpi" compiler option; otherwise it will be ignored. 

The following example generates the 80x87 "square root" instruction. 

double mysqrt(double); 

♦pragma aux mysqrt parm [8087] = \ 
float 0xd9 Oxfa /* fsqrt */; 

A sequence of in-line assembly language instructions may contain symbolic references. In the following 
example, a near call to the function myalias is made whenever myrtn is called. 
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extern void myalias(void) ; 
void myrtn(void); 

♦pragma aux myrtn = \ 

0xe8 reloff myalias /* near call */; 

In the following example, a far call to the function myalias is made whenever myrtn is called. 

extern void myalias(void); 
void myrtn(void); 

♦pragma aux myrtn = \ 

0x9a offset myalias seg myalias /* far call */; 

8.27.5.1 Loading Data Segment Register 

An application may have been compiled so that the segment register DS does not contain the segment 
address of the default data segment (group "DGROUP"). This is usually the case if you are using a large 
data memory model. Suppose you wish to call a function that assumes that the segment register DS 
contains the segment address of the default data segment. It would be very cumbersome if you were forced 
to compile your application so that the segment register DS contained the default data segment (a small data 
memory model). 

The following form of the auxiliary pragma will cause the segment register DS to be loaded with the 
segment address of the default data segment before calling the specified function. 


♦pragma aux sym parm loadds [;] 


where description: 

sym is a function name. 

Alternatively, the following form of the auxiliary pragma will cause the segment register DS to be loaded 
with the segment address of the default data segment as part of the prologue sequence for the specified 
function. 


♦pragma aux sym loadds [;] 


where description: 

sym is a function name. 

8.27.5.2 Defining Exported Symbols in Dynamic Link Libraries 

An exported symbol in a dynamic link library is a symbol that can be referenced by an application that is 
linked with that dynamic link library. Normally, symbols in dynamic link libraries are exported using the 
Open Watcom Linker "EXPORT" directive. An alternative method is to use the following form of the 
auxiliary pragma. 
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♦pragma aux sym export [;] 


where description: 

sym is a function name. 

8.27.5.3 Defining Windows Callback Functions 

When compiling a Microsoft Windows application, you must use the "zW" option so that special 
prologue/epilogue sequences are generated. Furthermore, callback functions require larger 
prologue/epilogue sequences than those generated when the "zW" compiler option is specified. The 
following form of the auxiliary pragma will cause a callback prologue/epilogue sequence to be generated 
for a callback function when compiled using the "zW" option. 


♦pragma aux sym export [;] 


where description: 

sym is a callback function name. 

Alternatively, the "zw" compiler option can be used to generate callback prologue/epilogue sequences. 
However, all functions contained in a module compiled using the "zw" option will have a callback 
prologue/epilogue sequence even if the functions are not callback functions. 

8.27.5.4 Forcing a Stack Frame 

Normally, a function contains a stack frame if arguments are passed on the stack or an automatic variable is 
allocated on the stack. No stack frame will be generated if the above conditions are not satisfied. The 
following form of the auxiliary pragma will force a stack frame to be generated under any circumstance. 


♦pragma aux sym frame [;] 


where description: 

sym is a function name. 

8.27.6 Describing Argument Information 

Using auxiliary pragmas, you can describe the calling convention that Open Watcom C/C++ is to use for 
calling functions. This is particularly useful when interfacing to functions that have been compiled by 
other compilers or functions written in other programming languages. 

The general form of an auxiliary pragma that describes argument passing is the following. 
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#pragma aux sym parm { pop_info I reverse I {reg_set} } [;] 
pop_info ::= caller I routine 

where description: 

sym is a function name. 

reg_set is called a register set. The register sets specify the registers that are to be used for 

argument passing. A register set is a list of registers separated by spaces and enclosed in 
square brackets. 

8.27.6.1 Passing Arguments in Registers 

The following form of the auxiliary pragma can be used to specify the registers that are to be used to pass 
arguments to a particular function. 

♦pragma aux sym parm {reg_set} [;] 


where description: 

sym is a function name. 

reg_set is called a register set. The register sets specify the registers that are to be used for 

argument passing. A register set is a list of registers separated by spaces and enclosed in 
square brackets. 

Register sets establish a priority for register allocation during argument list processing. Register sets are 
processed from left to right. However, within a register set, registers are chosen in any order. Once all 
register sets have been processed, any remaining arguments are pushed on the stack. 

Note that regardless of the register sets specified, only certain combinations of registers will be selected for 
arguments of a particular type. 

Note that arguments of type float and double are always pushed on the stack when the "fpi" or "fpi87" 
option is used. 

double Arguments of type double can only be passed in the following register combination: 

AX:BX:CX:DX. For example, if the following register set was specified for a routine 
having an argument of type double, 

[AX BX SI DI] 

the argument would be pushed on the stack since a valid register combination for 8-byte 
arguments is not contained in the register set. Note that this method for passing arguments 
of type double is supported only when the "fpc" option is used. Note that this argument 
passing method does not include the passing of 8-byte structures. 
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far pointer A far pointer can only be passed in one of the following register pairs: DX: AX, CX:BX, 
CX:AX, CX:SI, DX:BX, DI:AX, CX:D1, DX:SI, DI:BX, STAX, CX:DX, DX:DI, DI:SI, 
SI:BX, BX:AX, DS:CX, DS:DX, DS:DI, DS:SI, DS:BX, DS:AX, ES:CX, ES:DX, ES:D1, 
ES:SI, ES:BX or ES:AX. For example, if a far pointer is passed to a function with the 
following register set, 

[ES BP] 

the argument would be pushed on the stack since a valid register combination for a far 
pointer is not contained in the register set. 

long int, float The only registers that will be assigned to 4-byte arguments (e.g„ arguments of type long 
int,) are: DX:AX, CX:BX, CX:AX, CX:SI, DX:BX, DI:AX, CX:DI, DX:SI, DI:BX, 
STAX, CX:DX, DX:DI, DI:SI, SI:BX and BX:AX. For example, if the following register 
set was specified for a routine with one argument of type long int, 

[ES DI] 

the argument would be pushed on the stack since a valid register combination for 4-byte 
arguments is not contained in the register set. Note that this argument passing method 
includes 4-byte structures. Note that this argument passing method includes arguments of 
type float but only when the "fpc" option is used. 

int The only registers that will be assigned to 2-byte arguments (e.g., arguments of type int) 

are: AX, BX, CX, DX, SI and DI. For example, if the following register set was specified 
for a routine with one argument of type int, 

[BP] 

the argument would be pushed on the stack since a valid register combination for 2-byte 
arguments is not contained in the register set. 

char Arguments whose size is 1 byte (e.g., arguments of type char) are promoted to 2 bytes and 

are then assigned registers as if they were 2-byte arguments. 

others Arguments that do not fall into one of the above categories cannot be passed in registers 

and are pushed on the stack. Once an argument has been assigned a position on the stack, 
all remaining arguments will be assigned a position on the stack even if all register sets 
have not yet been exhausted. 

Notes: 

1. The default register set is [AX BX CX DX]. 

2. Specifying registers AH and AL is equivalent to specifying register AX. Specifying registers 
DH and DL is equivalent to specifying register DX. Specifying registers CH and CL is 
equivalent to specifying register CX. Specifying registers BH and BL is equivalent to specifying 
register BX. 

3. If you are compiling for a memory model with a small data model, or the "zdp" compiler option 
is specified, any register combination containing register DS becomes illegal. In a small data 
model, segment register DS must remain unchanged as it points to the program’s data segment. 
Note that the "zdf" compiler option can be used to specify that register DS does not contain that 
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segment address of the program’s data segment. In this case, register combinations containing 
register DS are legal. 

Consider the following example. 

♦pragma aux myrtn parm [ax bx cx dx] [bp si]; 

Suppose myrtn is a routine with 3 arguments each of type long int. 

1. The first argument will be passed in the register pair DX: AX. 

2. The second argument will be passed in the register pair CX:BX. 

3. The third argument will be pushed on the stack since BP:SI is not a valid register pair for 
arguments of type long int. 

It is possible for registers from the second register set to be used before registers from the first register set 
are used. Consider the following example. 

♦pragma aux myrtn parm [ax bx cx dx] [si di]; 

Suppose myrtn is a routine with 3 arguments, the first of type int and the second and third of type long 
int. 


1. The first argument will be passed in the register AX. 

2. The second argument will be passed in the register pair CX:BX. 

3. The third argument will be passed in the register set DI:SI. 

Note that registers are no longer selected from a register set after registers are selected from subsequent 
register sets, even if all registers from the original register set have not been exhausted. 

An empty register set is permitted. All subsequent register sets appearing after an empty register set are 
ignored; all remaining arguments are pushed on the stack. 

Notes: 

1. If a single empty register set is specified, all arguments are passed on the stack. 

2. If no register set is specified, the default register set [AX BX CX DX] is used. 

8.27.6.2 Forcing Arguments into Specific Registers 

It is possible to force arguments into specific registers. Suppose you have a function, say "mycopy", that 
copies data. The first argument is the source, the second argument is the destination, and the third 
argument is the length to copy. If we want the first argument to be passed in the register SI, the second 
argument to be passed in register DI and the third argument to be passed in register CX, the following 
auxiliary pragma can be used. 

void mycopy( char near *, char *, int ); 

♦pragma aux mycopy parm [SI] [DI] [CX] ; 

Note that you must be aware of the size of the arguments to ensure that the arguments get passed in the 
appropriate registers. 
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8.27.6.3 Passing Arguments to In-Line Functions 

For functions whose code is generated by Open Watcom C/C++ and whose argument list is described by an 
auxiliary pragma. Open Watcom C/C++ has some freedom in choosing how arguments are assigned to 
registers. Since the code for in-line functions is specified by the programmer, the description of the 
argument list must be very explicit. To achieve this. Open Watcom C/C++ assumes that each register set 
corresponds to an argument. Consider the following DOS example of an in-line function called 
scrollactivepgup. 

void scrollactivepgup(char,char,char,char,char,char); 

♦pragma aux scrollactivepgup = \ 

"mov AH,6" \ 

"int lOh" \ 

parm [ch] [cl] [dh] [dl] [al] [bh] \ 
modify [ah]; 

The BIOS video call to scroll the active page up requires the following arguments. 

1. The row and column of the upper left corner of the scroll window is passed in registers CH and 
CL respectively. 

2. The row and column of the lower right corner of the scroll window is passed in registers DH and 
DL respectively. 

3. The number of lines blanked at the bottom of the window is passed in register AL. 

4. The attribute to be used on the blank lines is passed in register BH. 

When passing arguments. Open Watcom C/C++ will convert the argument so that it fits in the register(s) 
specified in the register set for that argument. For example, in the above example, if the first argument to 
scrollactivepgup was called with an argument whose type was int, it would first be converted to 
char before assigning it to register CH. Similarly, if an in-line function required its argument in register 
pair DX:AX and the argument was of type short int, the argument would be converted to long int before 
assigning it to register pair DX:AX. 

In general. Open Watcom C/C++ assigns the following types to register sets. 

1. A register set consisting of a single 8-bit register (1 byte) is assigned a type of unsigned char. 

2. A register set consisting of a single 16-bit register (2 bytes) is assigned a type of unsigned short 
int. 

3. A register set consisting of two 16-bit registers (4 bytes) is assigned a type of unsigned long int. 

4. A register set consisting of four 16-bit registers (8 bytes) is assigned a type of double. 

8.27.6.4 Removing Arguments from the Stack 

The following form of the auxiliary pragma specifies who removes from the stack arguments that were 
pushed on the stack. 
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♦pragma aux sym parm (caller I routine) [;] 


where description: 

sym is a function name. 

"caller" specifies that the caller will pop the arguments from the stack; "routine" specifies that the called 
routine will pop the arguments from the stack. If "caller" or "routine" is omitted, "routine" is assumed 
unless the default has been changed in a previous auxiliary pragma, in which case the new default is 
assumed. 

8.27.6.5 Passing Arguments in Reverse Order 

The following form of the auxiliary pragma specifies that arguments are passed in the reverse order. 


♦pragma aux sym parm reverse [;] 


where description: 

sym is a function name. 

Normally, arguments are processed from left to right. The leftmost arguments are passed in registers and 
the rightmost arguments are passed on the stack (if the registers used for argument passing have been 
exhausted). Arguments that are passed on the stack are pushed from right to left. 

When arguments are reversed, the rightmost arguments are passed in registers and the leftmost arguments 
are passed on the stack (if the registers used for argument passing have been exhausted). Arguments that 
are passed on the stack are pushed from left to right. 

Reversing arguments is most useful for functions that require arguments to be passed on the stack in an 
order opposite from the default. The following auxiliary pragma demonstrates such a function. 

♦pragma aux rtn parm reverse []; 

8.27.7 Describing Function Return Information 

Using auxiliary pragmas, you can describe the way functions are to return values. This is particularly 
useful when interfacing to functions that have been compiled by other compilers or functions written in 
other programming languages. 

The general form of an auxiliary pragma that describes the way a function returns its value is the following. 


♦pragma aux sym value {no8087 I reg_set I struct_info} [;] 
struct_info ::= struct {float I struct I (routine I caller) I reg_set} 
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where description: 

sym is a function name. 

reg_set is called a register set. The register sets specify the registers that are to be used for 

argument passing. A register set is a list of registers separated by spaces and enclosed in 
square brackets. 

8.27.7.1 Returning Function Values in Registers 

The following form of the auxiliary pragma can be used to specify the registers that are to be used to return 
a function’s value. 


♦pragma aux sym value reg_set [;] 


where 

description: 

sym 

is a function name. 

reg_set 

is a register set. 


Note that the method described below for returning values of type float or double is supported only when 
the "fpc" option is used. 

Depending on the type of the return value, only certain registers are allowed in reg_set. 

1- byte For 1-byte return values, only the following registers are allowed: AL, AH, DL, DH, BL, 

BH, CL or CH. If no register set is specified, register AL will be used. 

2- byte For 2-byte return values, only the following registers are allowed: AX, DX, BX, CX, SI or 

DI. If no register set is specified, register AX will be used. 

4-byte For 4-byte return values (except far pointers), only the following register pairs are allowed: 

DX:AX, CX:BX, CX:AX, CX:SI, DX:BX, DLAX, CX:DI, DX:SI, DI:BX, SI:AX, 

CX:DX, DX:DI, DI:SI, SI:BX or BX:AX. If no register set is specified, registers DX:AX 
will be used. This form of the auxiliary pragma is legal for functions of type float when 
using the "fpc" option only. 

far pointer For functions that return far pointers, the following register pairs are allowed: DX:AX, 

CX:BX, CX:AX, CX:SI, DX:BX, DLAX, CX:DI, DX:SI, DLBX, SI:AX, CX:DX, DX:DI, 
DI:SI, SI:BX, BX:AX, DS:CX, DS:DX, DS:DI, DS:SI, DS:BX, DS:AX, ES:CX, ES:DX, 
ES:DI, ES:SI, ES:BX or ES:AX. If no register set is specified, the registers DX:AX will be 
used. 

8-byte For 8-byte return values (including functions of type double), only the following register 

combination is allowed: AX:BX:CX:DX. If no register set is specified, the registers 
AX:BX:CX:DX will be used. This form of the auxiliary pragma is legal for functions of 
type double when using the "fpc" option only. 
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Notes: 

1. An empty register set is not allowed. 

2. If you are compiling for a memory model which has a small data model, any of the above 
register combinations containing register DS becomes illegal. In a small data model, segment 
register DS must remain unchanged as it points to the program’s data segment. 

8.27.7.2 Returning Structures 

Typically, structures are not returned in registers. Instead, the caller allocates space on the stack for the 
return value and sets register SI to point to it. The called routine then places the return value at the location 
pointed to by register SI. 

The following form of the auxiliary pragma can be used to specify the register that is to be used to point to 
the return value. 


♦pragma aux sym value struct (callerlroutine) reg_set [;] 


where 

description: 

sym 

is a function name. 

reg_set 

is a register set. 


"caller" specifies that the caller will allocate memory for the return value. The address of the memory 
allocated for the return value is placed in the register specified in the register set by the caller before the 
function is called. If an empty register set is specified, the address of the memory allocated for the return 
value will be pushed on the stack immediately before the call and will be returned in register AX by the 
called routine. It is assumed that the memory for the return value is allocated from the stack segment (the 
stack segment is contained in segment register SS). 

"routine" specifies that the called routine will allocate memory for the return value. Upon returning to the 
caller, the register specified in the register set will contain the address of the return value. An empty 
register set is not allowed. 

Only the following registers are allowed in the register set: AX, DX, BX, CX, SI or DI. Note that in a big 
data model, the address in the return register is assumed to be in the segment specified by the value in the 
SS segment register. 

If the size of the structure being returned is 1, 2 or 4 bytes, it will be returned in registers. The return 
register will be selected from the register set in the following way. 

1. A 1-byte structure will be returned in one of the following registers: AL, AH, DL, DH, BL, BH, 
CL or CH. If no register set is specified, register AL will be used. 

2. A 2-byte structure will be returned in one of the following registers: AX, DX, BX, CX, SI or DI. 
If no register set is specified, register AX will be used. 
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3. A 4-byte structure will be returned in one of the following register pairs: DX:AX, CX:BX, 

CX:AX, CX:SI, DX:BX, D1:AX, CX:DI, DX:SI, DI:BX, SI:AX, CX:DX, DX:DI, DI:SI, SI:BX 
or BX:AX. If no register set is specified, register pair DX:AX will be used. 

The following form of the auxiliary pragma can be used to specify that structures whose size is 1, 2 or 4 
bytes are not to be returned in registers. Instead, the caller will allocate space on the stack for the structure 
return value and point register SI to it. 


♦pragma aux sym value struct struct [;] 


where description: 

sym is a function name. 

8.27.7.3 Returning Floating-Point Data 

There are a few ways available for specifying how the value for a function whose type is float or double is 
to be returned. 

The following form of the auxiliary pragma can be used to specify that function return values whose type is 
float or double are not to be returned in registers. Instead, the caller will allocate space on the stack for the 
return value and point register SI to it. 


♦pragma aux sym value struct float [;] 


where description: 

sym is a function name. 

In other words, floating-point values are to be returned in the same way structures are returned. 

The following form of the auxiliary pragma can be used to specify that function return values whose type is 
float or double are not to be returned in 80x87 registers when compiling with the "fpi" or "fpi87" option. 
Instead, the value will be returned in 80x86 registers. This is the default behaviour for the "fpc" option. 
Function return values whose type is float will be returned in registers DX:AX. Function return values 
whose type is double will be returned in registers AX:BX:CX:DX. This is the default method for the "fpc" 
option. 


♦pragma aux sym value no8087 [;] 


where description: 

sym is a function name. 

The following form of the auxiliary pragma can be used to specify that function return values whose type is 
float or double are to be returned in ST(0) when compiling with the "fpi" or "fpi87" option. This form of 
the auxiliary pragma is not legal for the "fpc" option. 
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♦pragma aux sym value [8087] [;] 


where description: 

sym is a function name. 

8.27.8 A Function that Never Returns 

The following form of the auxiliary pragma can be used to describe a function that does not return to the 
caller. 

♦pragma aux sym aborts [;] 


where description: 

sym is a function name. 

Consider the following example. 

♦pragma aux exitrtn aborts; 
extern void exitrtn(void); 

void rtn() 

{ 

exitrtn(); 

} 

exitrtn is defined to be a function that does not return. For example, it may call exit to return to the 
system. In this case. Open Watcom C/C++ generates a "jmp" instruction instead of a "call" instruction to 
invoke exitrtn. 


8.27.9 Describing How Functions Use Memory 

The following form of the auxiliary pragma can be used to describe a function that does not modify any 
memory (i.e., global or static variables) that is used directly or indirectly by the caller. 


♦pragma aux sym modify nomemory [;] 


where description: 

sym is a function name. 

Consider the following example. 
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♦pragma off (check_ stack); 

extern void myrtn(void); 

int i = { 1033 }; 

extern Rtn() { 

while ( i < 10000 ) { 

i += 383; 

} 

myrtn(); 
i += 13143; 

} ; 


To compile the above program, "rtn.c", we issue the following command. 

C>wcc rtn -oai -dl 
C>wpp rtn -oai -dl 
C>wcc386 rtn -oai -dl 
C>wpp386 rtn -oai -dl 

For illustrative purposes, we omit loop optimizations from the list of code optimizations that we want the 
compiler to perform. The "dl" compiler option is specified so that the object file produced by Open 
Watcom C/C++ contains source line information. 

We can generate a file containing a disassembly of rtn. ob j by issuing the following command. 
C>wdis rtn -1 -s -r 

The "s" option is specified so that the listing file produced by the Open Watcom Disassembler contains 
source lines taken from rtn. c . The listing file rtn. 1st appears as follows. 

Module: rtn.c 

Group: 'DGROUP' CONST,_ DATA 

Segment: TEXT' BYTE 0026 bytes 

#pragma off (check_ stack) ; 

extern void MyRtn( void ) ; 

int i = { 1033 }; 

extern Rtn() 

{ 


0000 

52 



Rtn_ 

push 

DX 

0001 

8b 

16 

00 00 


mov 

DX,_ i 

while( 

i 

< 10000 ) 

{ 



0005 

81 

fa 

10 27 

LI 

cmp 

DX,2710H 

0009 

7d 

06 



jge 

L2 

1 

i 

+= 

383; 




/ 

000b 

81 

c2 

7 f 01 


add 

DX,017fH 

OOOf 

eb 

f 4 



jmp 

LI 
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MyRtn (); 


0011 

89 16 00 

00 L2 

mov 

X 

Q 

•H 

1 

0015 

e8 00 00 


call 

MyRtn_ 

0018 

8b 16 00 

00 

mov 

DX,_ i 

i 

+= 13143; 




001c 

81 c2 57 

33 

add 

DX,3357H 

0020 

89 16 00 

00 

mov 

_ i, DX 

}; 

0024 

5a 


pop 

DX 

0025 

c3 


ret 



No disassembly errors 


Segment: DATA' WORD 0002 bytes 

0000 09 04 _ i 

No disassembly errors 


Let us add the following auxiliary pragma to the source file, 
♦pragma aux myrtn modify nomemory; 


If we compile the source file with the above pragma and disassemble the object file using the Open 
Watcom Disassembler, we get the following listing file. 


Module: rtn.c 

Group: 'DGROUP' CONST,_ DATA 

Segment: TEXT' BYTE 0022 bytes 

#pragma off (check_ stack) ; 

extern void MyRtn( void ) ; 

#pragma aux MyRtn modify nomemory; 

int i = { 1033 }; 

extern Rtn() 

{ 


0000 

52 



Rtn_ 

push 

DX 

0001 

8b 16 

00 

00 


mov 

DX,_ i 

while( i 

< 

10000 ) 

{ 



0005 

81 fa 

10 

27 

LI 

cmp 

DX,2710H 

0009 

7d 06 




jge 

L2 

1 

i += 

383; 




/ 

000b 

81 c2 

7 f 

01 


add 

DX,017fH 

OOOf 

eb f 4 




jmp 

LI 

My Rtn () ; 






0011 

89 16 

00 

00 

L2 

mov 

_ i, DX 

0015 

e8 00 

00 



call 

MyRtn_ 

i 

+= 13143; 





0018 

81 c2 

57 

33 


add 

DX,3357H 

001c 

89 16 

00 

00 


mov 

_ i, DX 

}; 

0020 

5a 




pop 

DX 

0021 

c3 




ret 
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No disassembly errors 


Segment: DATA' WORD 0002 bytes 

0000 09 04 _ i 

No disassembly errors 


Notice that the value of i is in register DX after completion of the "while" loop. After the call to myrtn, 
the value of i is not loaded from memory into a register to perform the final addition. The auxiliary 
pragma informs the compiler that myrtn does not modify any memory (i.e., global or static variables) that 
is used directly or indirectly by Rtn and hence register DX contains the correct value of i . 

The preceding auxiliary pragma deals with routines that modify memory. Let us consider the case where 
routines reference memory. The following form of the auxiliary pragma can be used to describe a function 
that does not reference any memory (i.e., global or static variables) that is used directly or indirectly by the 
caller. 


♦pragma aux sym parm nomemory modify nomemory [;] 


where 

description: 

sym 

is a function name. 

Notes: 



1. You must specify both "parm nomemory" and "modify nomemory". 

Let us replace the auxiliary pragma in the above example with the following auxiliary pragma. 

♦pragma aux myrtn parm nomemory modify nomemory; 

If you now compile our source file and disassemble the object file using WDIS, the result is the following 
listing file. 

Module: rtn.c 

Group: 'DGROUP' CONST,_ DATA 
Segment: TEXT' BYTE OOle bytes 

#pragma off (check_ stack) ; 
extern void MyRtn( void ) ; 

#pragma aux MyRtn parm nomemory modify nomemory; 
int i = { 1033 }; 
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extern 

r 

Rtn () 






i 

0000 

52 




Rtn_ 

push 

DX 

0001 

8b 

16 

00 

00 


mov 

DX,_ i 

while 

( i 

< 

10000 ) 

{ 



0005 

81 

fa 

10 

27 

LI 

cmp 

DX,2710H 

0009 

7d 

06 




jge 

L2 

1 

i 

+= 

383; 




/ 

000b 

81 

c2 

11 

01 


add 

DX,017fH 

OOOf 

eb 

f 4 




jmp 

LI 

MyRtn 

0 ; 






0011 

e8 

00 

00 


L2 

call 

MyRtn_ 

i 

+= : 

13143; 





0014 

81 

c2 

57 

33 


add 

DX,3357H 

0018 

89 

16 

00 

00 


mov 

X 

Q 

■rH 

1 

}; 








001c 

5a 





pop 

DX 

OOld 

c3 





ret 



No disassembly errors 


Segment: DATA' WORD 0002 bytes 

0000 09 04 _ i 

No disassembly errors 


Notice that after completion of the "while" loop we did not have to update i with the value in register DX 
before calling myrtn . The auxiliary pragma informs the compiler that myrtn does not reference any 
memory (i.e., global or static variables) that is used directly or indirectly by myrtn so updating i was not 
necessary before calling myrtn. 

8.27.10 Describing the Registers Modified by a Function 

The following form of the auxiliary pragma can be used to describe the registers that a function will use 
without saving. 


♦pragma aux sym modify [exact] reg_set [;] 


where 

description: 

sym 

is a function name. 

reg_set 

is a register set. 


Specifying a register set informs Open Watcom C/C++ that the registers belonging to the register set are 
modified by the function. That is, the value in a register before calling the function is different from its 
value after execution of the function. 

Registers that are used to pass arguments are assumed to be modified and hence do not have to be saved 
and restored by the called function. Also, since the AX register is frequently used to return a value, it is 
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always assumed to be modified. If necessary, the caller will contain code to save and restore the contents 
of registers used to pass arguments. Note that saving and restoring the contents of these registers may not 
be necessary if the called function does not modify them. The following form of the auxiliary pragma can 
be used to describe exactly those registers that will be modified by the called function. 



where 

description: 

sym 

is a function name. 

reg_set 

is a register set. 


The above form of the auxiliary pragma tells Open Watcom C/C++ not to assume that the registers used to 
pass arguments will be modified by the called function. Instead, only the registers specified in the register 
set will be modified. This will prevent generation of the code which unnecessarily saves and restores the 
contents of the registers used to pass arguments. 

Also, any registers that are specified in the value register set are assumed to be unmodified unless 
explicitly listed in the exact register set. In the following example, the code generator will not generate 
code to save and restore the value of the stack pointer register since we have told it that "GetSP" does not 
modify any register whatsoever. 

Example: 

unsigned GetSP(void); 

#if defined(_ 386_) 

♦pragma aux GetSP = value [esp] modify exact []; 

♦ else 

♦pragma aux GetSP = value [sp] modify exact []; 

♦endif 

8.27.11 An Example 

As mentioned in an earlier section, the following pragma defines the calling convention for functions 
compiled by Microsoft C. 

♦pragma aux MS_ C *" \ 

parm caller [] \ 

value struct float struct routine [ax]\ 
modify [ax bx cx dx es]; 

Let us discuss this pragma in detail. 

" specifies that all function and variable names are preceded by the underscore character (_) 

when translated from source form to object form. 

parm caller [] specifies that all arguments are to be passed on the stack (an empty register set was 
specified) and the caller will remove the arguments from the stack. 

value struct marks the section describing how the called routine returns structure information. 
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float specifies that floating-point arguments are returned in the same way as 

structures are returned. 

struct specifies that 1, 2 and 4-byte structures are not to be returned in registers. 

routine specifies that the called routine allocates storage for the return structure and 

returns with a register pointing at it. 

[ax] specifies that register AX is used to point to the structure return value. 

modify [ax bx cx dx es] 

specifies that registers AX, BX, CX, DX and ES are not preserved by the called routine. 

Note that the default method of returning integer values is used; 1-byte characters are returned in register 
AL, 2-byte integers are returned in register AX, and 4-byte integers are returned in the register pair 
DX:AX. 

8.27.12 Auxiliary Pragmas and the 80x87 

This section deals with those aspects of auxiliary pragmas that are specific to the 80x87. The discussion in 
this chapter assumes that one of the "fpi" or "fpi87" options is used to compile functions. The following 
areas are affected by the use of these options. 

1. passing floating-point arguments to functions, 

2. returning floating-point values from functions and 

3. which 80x87 floating-point registers are allowed to be modified by the called routine. 

8.27.12.1 Using the 80x87 to Pass Arguments 

By default, floating-point arguments are passed on the 80x86 stack. The 80x86 registers are never used to 
pass floating-point arguments when a function is compiled with the "fpi" or "fpi87" option. However, they 
can be used to pass arguments whose type is not floating-point such as arguments of type "int". 

The following form of the auxiliary pragma can be used to describe the registers that are to be used to pass 
arguments to functions. 


♦pragma aux sym parm {reg_set} [;] 


where description: 

sym is a function name. 

reg_set is a register set. The register set can contain 80x86 registers and/or the string "8087". 


A uxiliary Pragmas 179 







16-bit Topics 


Notes: 

1. If an empty register set is specified, all arguments, including floating-point arguments, will be 
passed on the 80x86 stack. 

When the string "8087" appears in a register set, it simply means that floating-point arguments can be 
passed in 80x87 floating-point registers if the source file is compiled with the "fpi" or "fpi87" option. 

Before discussing argument passing in detail, some general notes on the use of the 80x87 floating-point 
registers are given. 

The 80x87 contains 8 floating-point registers which essentially form a stack. The stack pointer is called ST 
and is a number between 0 and 7 identifying which 80x87 floating-point register is at the top of the stack. 
ST is initially 0. 80x87 instructions reference these registers by specifying a floating-point register number. 
This number is then added to the current value of ST. The sum (taken modulo 8) specifies the 80x87 
floating-point register to be used. The notation ST(n), where "n" is between 0 and 7, is used to refer to the 
position of an 80x87 floating-point register relative to ST. 

When a floating-point value is loaded onto the 80x87 floating-point register stack, ST is decremented 
(modulo 8), and the value is loaded into ST(0). When a floating-point value is stored and popped from the 
80x87 floating-point register stack, ST is incremented (modulo 8) and ST(1) becomes ST(0). The 
following illustrates the use of the 80x87 floating-point registers as a stack, assuming that the value of ST is 
4 (4 values have been loaded onto the 80x87 floating-point register stack). 


+-+ 

0 | 4th from top | ST(4) 

+-+ 

1 | 5th from top | ST(5) 

+-+ 

2 | 6th from top | ST(6) 

+-+ 

3 | 7th from top | ST(7) 

+-+ 

ST -> 4 | top of stack | ST(0) 

+-+ 

5 | 1st from top | ST(1) 

+-+ 

6 | 2nd from top | ST(2) 

+-+ 

7 | 3rd from top | ST(3) 

+-+ 


Starting with version 9.5, the Open Watcom compilers use all eight of the 80x87 registers as a stack. The 
initial state of the 80x87 register stack is empty before a program begins execution. 

Note: For compatibility with code compiled with version 9.0 and earlier, you can compile with 

the "fpr" option. In this case only four of the eight 80x87 registers are used as a stack. 
These four registers were used to pass arguments. The other four registers form what was 
called the 80x87 cache. The cache was used for local floating-point variables. The state of 
the 80x87 registers before a program began execution was as follows. 

1. The four 80x87 floating-point registers that form the stack are uninitialized. 

2. The four 80x87 floating-point registers that form the 80x87 cache are initialized 
with zero. 
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Hence, initially the 80x87 cache was comprised of ST(0), ST(1), ST(2) and ST(3). ST had 
the value 4 as in the above diagram. When a floating-point value was pushed on the stack 
(as is the case when passing floating-point arguments), it became ST(0) and the 80x87 
cache was comprised of ST(1), ST(2), ST(3) and ST(4). When the 80x87 stack was full, 
ST(0), ST(1), ST(2) and ST(3) formed the stack and ST(4), ST(5), ST(6) and ST(7) formed 
the 80x87 cache. Version 9.5 and later no longer use this strategy. 

The rules for passing arguments are as follows. 

1. If the argument is not floating-point, use the procedure described earlier in this chapter. 

2. If the argument is floating-point, and a previous argument has been assigned a position on the 
80x86 stack (instead of the 80x87 stack), the floating-point argument is also assigned a position 
on the 80x86 stack. Otherwise proceed to the next step. 

3. If the string "8087" appears in a register set in the pragma, and if the 80x87 stack is not full, the 
floating-point argument is assigned floating-point register ST(0) (the top element of the 80x87 
stack). The previous top element (if there was one) is now in ST(1). Since arguments are 
pushed on the stack from right to left, the leftmost floating-point argument will be in ST(0). 
Otherwise the floating-point argument is assigned a position on the 80x86 stack. 

Consider the following example. 

♦pragma aux myrtn parm [8087]; 

void main() 

{ 


float 

x; 

double 

y; 

int 

i; 

long int 

j; 

x = 7.7; 


i = 7; 


y = 77.77 

r 

j = 77; 



myrtn( x, i, y, j ); 

} 

myrtn is an assembly language function that requires four arguments. The first argument of type float (4 
bytes), the second argument is of type int (2 bytes), the third argument is of type double (8 bytes) and the 
fourth argument is of type long int (4 bytes). These arguments will be passed to myrtn in the following 
way. 

1. Since "8087" was specified in the register set, the first argument, being of type float, will be 
passed in an 80x87 floating-point register. 

2. The second argument will be passed on the stack since no 80x86 registers were specified in the 
register set. 

3. The third argument will also be passed on the stack. Remember the following rule: once an 
argument is assigned a position on the stack, all remaining arguments will be assigned a position 
on the stack. Note that the above rule holds even though there are some 80x87 floating-point 
registers available for passing floating-point arguments. 
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4. The fourth argument will also be passed on the stack. 

Let us change the auxiliary pragma in the above example as follows. 

♦pragma aux myrtn parm [ax 8087] ; 

The arguments will now be passed to myrtn in the following way. 

1. Since "8087" was specified in the register set, the first argument, being of type float will be 
passed in an 80x87 floating-point register. 

2. The second argument will be passed in register AX, exhausting the set of available 80x86 
registers for argument passing. 

3. The third argument, being of type double, will also be passed in an 80x87 floating-point register. 

4. The fourth argument will be passed on the stack since no 80x86 registers remain in the register 
set. 

8.27.12.2 Using the 80x87 to Return Function Values 

The following form of the auxiliary pragma can be used to describe a function that returns a floating-point 
value in ST(0). 


♦pragma aux sym value reg_set [;] 


where description: 

sym is a function name. 

reg_set is a register set containing the string "8087", i.e. [8087], 

8.27.12.3 Preserving 80x87 Floating-Point Registers Across Calls 

The code generator assumes that all eight 80x87 floating-point registers are available for use within a 
function unless the "fpr" option is used to generate backward compatible code (older Open Watcom 
compilers used four registers as a cache). The following form of the auxiliary pragma specifies that the 
floating-point registers in the 80x87 cache may be modified by the specified function. 


♦pragma aux sym modify reg_set [;] 


where description: 

sym is a function name. 

reg_set is a register set containing the string "8087", i.e. [8087]. 

This instructs Open Watcom C/C++ to save any local variables that are located in the 80x87 cache before 
calling the specified routine. 
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9 32-bit Memory Models 


9.1 Introduction 


This chapter describes the various 32-bit memory models supported by Open Watcom C/C++. Each 
memory model is distinguished by two properties; the code model used to implement function calls and the 
data model used to reference data. 


9.2 32-bit Code Models 


There are two code models; 

1. the small code model and 

2. the big code model. 

A small code model is one in which all calls to functions are made with near calls. In a near call, the 
destination address is 32 bits and is relative to the segment value in segment register CS. Hence, in a small 
code model, all code comprising your program, including library functions, must be less than 4GB. 

A big code model is one in which all calls to functions are made with far calls. In a far call, the destination 
address is 48 bits (a 16-bit segment value and a 32-bit offset relative to the segment value). This model 
allows the size of the code comprising your program to exceed 4GB. 


Note: If your program contains less than 4GB of code, you should use a memory model that employs 
the small code model. This will result in smaller and faster code since near calls are smaller instructions 
and are processed faster by the CPU. 


9.3 32-bit Data Models 


There are two data models; 

1. the small data model and 

2. the big data model. 

A small data model is one in which all references to data are made with near pointers. Near pointers are 32 
bits; all data references are made relative to the segment value in segment register DS. Hence, in a small 
data model, all data comprising your program must be less than 4GB. 

A big data model is one in which all references to data are made with far pointers. Far pointers are 48 bits 
(a 16-bit segment value and a 32-bit offset relative to the segment value). This removes the 4GB limitation 
on data size imposed by the small data model. However, when a far pointer is incremented, only the offset 
is adjusted. Open Watcom C/C++ assumes that the offset portion of a far pointer will not be incremented 
beyond 4GB. The compiler will assign an object to a new segment if the grouping of data in a segment will 
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cause the object to cross a segment boundary. Implicit in this is the requirement that no individual object 
exceed 4GB. 


Note: If your program contains less than 4GB of data, you should use the small data model. This will 
result in smaller and faster code since references using near pointers produce fewer instructions. 


9.4 Summary of 32-bit Memory Models 

As previously mentioned, a memory model is a combination of a code model and a data model. The 
following table describes the memory models supported by Open Watcom C/C++. 


Memory 

Model 

Code 

Model 

Data 

Model 

Default 

Code 

Pointer 

Default 

Data 

Pointer 

flat 

small 

small 

near 

near 

small 

small 

small 

near 

near 

medium 

big 

small 

far 

near 

compact 

small 

big 

near 

far 

large 

big 

big 

far 

far 


9.5 Flat Memory Model 

In the flat memory model, the application’s code and data must total less than 4GB in size. Segment 
registers CS, DS, SS and ES point to the same linear address space (this does not imply that the segment 
registers contain the same value). That is, a given offset in one segment refers to the same memory location 
as that offset in another segment. Essentially, a flat model operates as if there were no segments. 

9.6 Mixed 32-bit Memory Model 

A mixed memory model application combines elements from the various code and data models. A mixed 
memory model application might be characterized as one that uses the near, far, or huge keywords when 
describing some of its functions or data objects. 

For example, a medium memory model application that uses some far pointers to data can be described as a 
mixed memory model. In an application such as this, most of the data is in a 4GB segment (DGROUP) and 
hence can be referenced with near pointers relative to the segment value in segment register DS. This 
results in more efficient code being generated and better execution times than one can expect from a big 
data model. Data objects outside of the DGROUP segment are described with the far keyword. 
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9.7 Linking Applications for the Various 32-bit Memory 
Models 


Each memory model requires different run-time and floating-point libraries. Each library assumes a 
particular memory model and should be linked only with modules that have been compiled with the same 
memory model. The following table lists the libraries that are to be used to link an application that has 
been compiled for a particular memory model. Currently, only libraries for the flat/small memory model 
are provided. 


Memory Run-time Floating-Point Floating-Point 

Model Library Library (80x87) Library (f-p calls) 


flat/small CLIB3R.LIB 
CLIB3S.LIB 
PLIB3R.LIB 
PLIB3S.LIB 


MATH387R.LIB 
MATH387S.LIB 
CPLX73R.LIB 
CPLX73S.LIB 


MATH3R.LIB 
MATH3S.LIB 
CPLX3R.LIB 
CPLX3S.LIB 


The letter "R" or "S" which is affixed to the file name indicates the particular strategy with which the 
modules in the library have been compiled. 

R denotes a version of the Open Watcom C/C++ 32-bit libraries which have been compiled 

for the "flat/small" memory models using the "3r", "4r" or "5r" option. 

S denotes a version of the Open Watcom C/C++ 32-bit libraries which have been compiled 

for the "flat/small" memory models using the "3s", "4s" or "5s" option. 


9.8 Memory Layout 

The following describes the segment ordering of an application linked by the Open Watcom Linker. Note 
that this assumes that the "DOSSEG" linker option has been specified. 

1. all "USE16" segments. These segments are present in applications that execute in both real 
mode and protected mode. They are first in the segment ordering so that the "REALBREAK" 
option of the "RUNTIME" directive can be used to separate the real-mode part of the application 
from the protected-mode part of the application. Currently, the "RUNTIME" directive is valid 
for Phar Lap executables only. 

2. all segments not belonging to group "DGROUP" with class "CODE" 

3. all other segments not belonging to group "DGROUP" 

4. all segments belonging to group "DGROUP" with class "BEGDATA" 

5. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

6. all segments belonging to group "DGROUP" with class "BSS" 

7. all segments belonging to group "DGROUP" with class "STACK" 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
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"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 

In addition to these special segments, the following conventions are used by Open Watcom C/C++. 

1. The "CODE" class contains the executable code for your application. In a small code model, this 
consists of the segment "_TEXT". In a big code model, this consists of the segments 
"<module>_TEXT" where <module> is the file name of the source file. 

2. The "FARJDATA" class consists of the following: 

(a) data objects whose size exceeds the data threshold in large data memory models 
(the data threshold is 32K unless changed using the "zt" compiler option) 

(b) data objects defined using the "FAR" or "HUGE" keyword, 

(c) literals whose size exceeds the data threshold in large data memory models (the 
data threshold is 32K unless changed using the "zt" compiler option) 

(d) literals defined using the "FAR" or "HUGE" keyword. 

You can override the default naming convention used by Open Watcom C/C++ to name segments. 

1. The Open Watcom C/C++ "nm" option can be used to change the name of the module. This, in 
turn, changes the name of the code segment when compiling for a big code model. 

2. The Open Watcom C/C++ "nt" option can be used to specify the name of the code segment 
regardless of the code model used. 
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10.1 Introduction 


This chapter will deal with the following topics. 

1. The data representation of the basic types supported by Open Watcom C/C++. 

2. The memory layout of a Open Watcom C/C++ program. 

3. The method for passing arguments and returning values. 

4. The two methods for passing floating-point arguments and returning floating-point values. 

One method is used when one of the Open Watcom C/C++ "fpi" or "fpi87" options is specified 
for the generation of in-line 80x87 instructions. When the "fpi" option is specified, an 80x87 
emulator is included from a math library if the application includes floating-point operations. 
When the "fpi87" option is used exclusively, the 80x87 emulator will not be included. 

The other method is used when the Open Watcom C/C++ "fpc" option is specified. In this case, 
the compiler generates calls to floating-point support routines in the alternate math libraries. 

An understanding of the Intel 80x86 architecture is assumed. 

10.2 Data Representation 

This section describes the internal or machine representation of the basic types supported by Open Watcom 
C/C++. 

10.2.1 Type "char" 

An item of type "char" occupies 1 byte of storage. Its value is in the following range. 

0 <= n <= 255 

Note that "char" is, by default, unsigned. The Open Watcom C/C++ compiler option "j" can be used to 
change the default from unsigned to signed. If "char" is signed, an item of type "char" is in the following 
range. 

-128 <= n <= 127 

You can force an item of type "char" to be unsigned or signed regardless of the default by defining them to 
be of type "unsigned char" or "signed char" respectively. 
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10.2.2 Type "short int" 

An item of type "short int" occupies 2 bytes of storage. Its value is in the following range. 

-32768 <= n <= 32767 

Note that "short int" is signed and hence "short int" and "signed short int" are equivalent. If an item of type 
"short int" is to be unsigned, it must be defined as "unsigned short int". In this case, its value is in the 
following range. 

0 <= n <= 65535 

10.2.3 Type "long int" 

An item of type "long int" occupies 4 bytes of storage. Its value is in the following range. 

-2147483648 <= n <= 2147483647 

Note that "long int" is signed and hence "long int" and "signed long int" are equivalent. If an item of type 
"long int" is to be unsigned, it must be defined as "unsigned long int". In this case, its value is in the 
following range. 

0 <= n <= 4294967295 

10.2.4 Type "int" 

An item of type "int" occupies 4 bytes of storage. Its value is in the following range. 

-2147483648 <= n <= 2147483647 

Note that "int" is signed and hence "int" and "signed int" are equivalent. If an item of type "int" is to be 
unsigned, it must be defined as "unsigned int". In this case its value is in the following range. 

0 <= n <= 4294967295 

If you are generating code that executes in 32-bit mode, "long int" and "int" are equivalent, "unsigned long 
int" and "unsigned int" are equivalent, and "signed long int" and "signed int" are equivalent. This may not 
be the case in other environments where "int" and "short int" are 2 bytes. 

10.2.5 Type "float" 

A datum of type "float" is an approximate representation of a real number. Each datum of type "float" 
occupies 4 bytes. If m is the magnitude of x (an item of type "float") then x can be approximated if 

2~126 <= m < 2 128 

or in more approximate terms if 

1.175494e-38 <= m <= 3.402823e38 

Data of type "float" are represented internally as follows. Note that bytes are stored in memory with the 
least significant byte first and the most significant byte last. 
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+—+- 


s 

Biased 


Exponent 


+—+-+- 

31 30-23 


Significand 


22-0 


Notes 


S 

Exponent 

Significand 

Zero 

Infinity 


S = Sign bit (O=positive, l=negative) 

The exponent bias is 127 (i.e., exponent value 1 represents 2' 126 ; exponent value 127 
represents 2°; exponent value 254 represents 2 127 ; etc.)- The exponent field is 8 bits long. 

The leading bit of the significand is always 1, hence it is not stored in the significand field. 
Thus the significand is always "normalized". The significand field is 23 bits long. 

A real zero quantity occurs when the sign bit, exponent, and significand are all zero. 

When the exponent field is all 1 bits and the significand field is all zero bits then the 
quantity represents positive or negative infinity, depending on the sign bit. 


Not Numbers When the exponent field is all 1 bits and the significand field is non-zero then the quantity 
is a special value called a NAN (Not-A-Number). 

When the exponent field is all 0 bits and the significand field is non-zero then the quantity 
is a special value called a "denormal" or nonnormal number. 


10.2.6 Type "double" 

A datum of type "double" is an approximate representation of a real number. The precision of a datum of 
type "double" is greater than or equal to one of type "float". Each datum of type "double" occupies 8 bytes. 
If m is the magnitude of x (an item of type "double") then x can be approximated if 

2-1022 <= m < 2 1024 

or in more approximate terms if 

2,2250738585072e-308 <= m <= 1.79769313486232e308 

Data of type "double" are represented internally as follows. Note that bytes are stored in memory with the 
least significant byte first and the most significant byte last. 

+-+-+-+ 


S 

Biased 

Significand 


Exponent 



+-+-+-+ 

63 62-52 51-0 
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Notes: 

S = Sign bit (O=positive, l=negative) 

The exponent bias is 1023 (i.e., exponent value 1 represents 2 -1022 ; exponent value 1023 
represents 2°; exponent value 2046 represents 2 1023 ; etc.). The exponent field is 11 bits 
long. 

The leading bit of the significand is always 1, hence it is not stored in the significand field. 
Thus the significand is always "normalized". The significand field is 52 bits long. 

A double precision zero quantity occurs when the sign bit, exponent, and significand are all 
zero. 

When the exponent field is all 1 bits and the significand field is all zero bits then the 
quantity represents positive or negative infinity, depending on the sign bit. 

When the exponent field is all 1 bits and the significand field is non-zero then the quantity 
is a special value called a NAN (Not-A-Number). 

When the exponent field is all 0 bits and the significand field is non-zero then the quantity 
is a special value called a "denormal" or nonnormal number. 

10.3 Memory Layout 

The following describes the segment ordering of an application linked by the Open Watcom Linker. Note 
that this assumes that the "DOSSEG" linker option has been specified. 

1. all "USE16" segments. These segments are present in applications that execute in both real 
mode and protected mode. They are first in the segment ordering so that the "REALBREAK" 
option of the "RUNTIME" directive can be used to separate the real-mode part of the application 
from the protected-mode part of the application. Currently, the "RUNTIME" directive is valid 
for Phar Lap executables only. 

2. all segments not belonging to group "DGROUP" with class "CODE" 

3. all other segments not belonging to group "DGROUP" 

4. all segments belonging to group "DGROUP" with class "BEGDATA" 

5. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

6. all segments belonging to group "DGROUP" with class "BSS" 

7. all segments belonging to group "DGROUP" with class "STACK" 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 


S 

Exponent 

Significand 

Zero 

Infinity 

Not Numbers 
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In addition to these special segments, the following conventions are used by Open Watcom C/C++. 

1. The "CODE" class contains the executable code for your application. In a small code model, this 
consists of the segment "_TEXT". In a big code model, this consists of the segments 
"<module>_TEXT" where <module> is the file name of the source file. 

2. The "FAR_DATA" class consists of the following: 

(a) data objects whose size exceeds the data threshold in large data memory models 
(the data threshold is 32K unless changed using the "zt" compiler option) 

(b) data objects defined using the "FAR" or "HUGE" keyword, 

(c) literals whose size exceeds the data threshold in large data memory models (the 
data threshold is 32K unless changed using the "zt" compiler option) 

(d) literals defined using the "FAR" or "HUGE" keyword. 

You can override the default naming convention used by Open Watcom C/C++ to name segments. 

1. The Open Watcom C/C++ "nm" option can be used to change the name of the module. This, in 
turn, changes the name of the code segment when compiling for a big code model. 

2. The Open Watcom C/C++ "nt" option can be used to specify the name of the code segment 
regardless of the code model used. 

10.4 Calling Conventions for Non-80x87 Applications 

The following sections describe the calling convention used when compiling with the "fpc" compiler 
option. 

10.4.1 Passing Arguments Using Register-Based Calling Conventions 

How arguments are passed to a function with register-based calling conventions is determined by the size 
(in bytes) of the argument and where in the argument list the argument appears. Depending on the size, 
arguments are either passed in registers or on the stack. Arguments such as structures are almost always 
passed on the stack since they are generally too large to fit in registers. Since arguments are processed 
from left to right, the first few arguments are likely to be passed in registers (if they can fit) and, if the 
argument list contains many arguments, the last few arguments are likely to be passed on the stack. 

The registers used to pass arguments to a function are EAX, EBX, ECX and EDX. The following 
algorithm describes how arguments are passed to functions. 

Initially, we have the following registers available for passing arguments: EAX, EDX, EBX and ECX. 

Note that registers are selected from this list in the order they appear. That is, the first register selected is 
EAX and the last is ECX. For each argument Ai, starting with the left most argument, perform the 
following steps. 

1. If the size of A; is 1 byte or 2 bytes, convert it to 4 bytes and proceed to the next step. If Ai is of 
type "unsigned char" or "unsigned short int", it is converted to an "unsigned int". If Ai is of type 
"signed char" or "signed short int", it is converted to a "signed int". If Ai is a 1-byte or 2-byte 
structure, the padding is determined by the compiler. 
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2. If an argument has already been assigned a position on the stack, Ai will also be assigned a 
position on the stack. Otherwise, proceed to the next step. 

3. If the size of Ai is 4 bytes, select a register from the list of available registers. If a register is 
available, Ai is assigned that register. The register is then removed from the list of available 
registers. If no registers are available, Ai will be assigned a position on the stack. 

4. If the type of Ai is "far pointer", select a register pair from the following list of combinations: 
[EDX EAX] or [ECX EBX]. The first available register pair is assigned to Ai and removed from 
the list of available pairs. The segment value will actually be passed in register DX or CX and 
the offset in register EAX or EBX. If none of the above register pairs is available, Ai will be 
assigned a position on the stack. Note that 8 bytes will be pushed on the stack even though the 
size of an item of type "far pointer" is 6 bytes. 

5. If the type of Ai is "double" or "float" (in the absence of a function prototype), select a register 
pair from the following list of combinations: [EDX EAX] or [ECX EBX], The first available 
register pair is assigned to Ai and removed from the list of available pairs. The high-order 32 
bits of the argument are assigned to the first register in the pair; the low-order 32 bits are 
assigned to the second register in the pair. If none of the above register pairs is available, Ai will 
be assigned a position on the stack. 

6. All other arguments will be assigned a position on the stack. 

Notes: 

1. Arguments that are assigned a position on the stack are padded to a multiple of 4 bytes. That is, 
if a 3-byte structure is assigned a position on the stack, 4 bytes will be pushed on the stack. 

2. Arguments that are assigned a position on the stack are pushed onto the stack starting with the 
rightmost argument. 

10.4.2 Sizes of Predefined Types 

The following table lists the predefined types, their size as returned by the "sizeof" function, the size of an 
argument of that type and the registers used to pass that argument if it was the only argument in the 
argument list. 


Basic Type 

"sizeof" 

Argument 

Size 

Registers 

Used 

char 

1 

4 

[EAX] 

short int 

2 

4 

[EAX] 

int 

4 

4 

[EAX] 

long int 

4 

4 

[EAX] 

float 

4 

8 

[EDX EAX] 

double 

8 

8 

[EDX EAX] 

near pointer 

4 

4 

[EAX] 

far pointer 

6 

8 

[EDX EAX] 


Note that the size of the argument listed in the table assumes that no function prototypes are specified. 
Function prototypes affect the way arguments are passed. This will be discussed in the section entitled 
"Effect of Function Prototypes on Arguments". 
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Notes: 


1. Provided no function prototypes exist, an argument will be converted to a default type as 
described in the following table. 


Argument Type Passed As 


char 

signed char 
unsigned char 
short 

signed short 
unsigned short 
float 


unsigned int 
signed int 
unsigned int 
unsigned int 
signed int 
unsigned int 
double 


10.4.3 Size of Enumerated Types 

The integral type of an enumerated type is determined by the values of the enumeration constants. In strict 
ISO/ANSI C mode, all enumerated constants are of type int. In the extensions mode, the compiler will 
use the smallest integral type possible (excluding long ints) that can represent all values of the enumerated 
type. For instance, if the minimum and maximum values of the enumeration constants are in the range 
-128 and 127, the enumerated type will be equivalent to a signed char (size = 1 byte). All references 
to enumerated constants in the previous instance will have type signed char. An enumerated constant 
is always promoted to an int when passed as an argument. 


10.4.4 Effect of Function Prototypes on Arguments 

Function prototypes define the types of the formal parameters of a function. Their appearance affects the 
way in which arguments are passed. An argument will be converted to the type of the corresponding 
formal parameter in the function prototype. Consider the following example. 

void prototype( float x, int i ) ; 

void main() 

{ 

float x; 
int i; 

x = 3.14; 
i = 314; 

prototype ( x, i ); 
rtn( x, i ); 

} 

The function prototype for prototype specifies that the first argument is to be passed as a "float" and the 
second argument is to be passed as an "int". This results in the first argument being passed in register EAX 
and the second argument being passed in register EDX. 

If no function prototype is given, as is the case for the function rtn, the first argument will be passed as a 
"double" and the second argument would be passed as an "int". This results in the first argument being 
passed in registers EDX and EAX and the second argument being passed in register EBX. 
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Note that even though both prototype and rtn were called with identical argument lists, the way in 
which the arguments were passed was completely different simply because a function prototype for 
prototype was specified. Function prototyping is an excellent way to guarantee that arguments will be 
passed as expected to your assembly language function. 

10.4.5 Interfacing to Assembly Language Functions 

Consider the following example. 

Example: 

void main() 

{ 

double x; 

int i; 

double y; 

x = 7; 
i = 77; 
y = 777; 

myrtn( x, i, y ); 

} 

myrtn is an assembly language function that requires three arguments. The first argument is of type 
"double", the second argument is of type "int" and the third argument is again of type "double". Using the 
rules for register-based calling conventions, these arguments will be passed to myrtn in the following 
way: 

1. The first argument will be passed in registers EDX and EAX leaving EBX and ECX as available 
registers for other arguments. 

2. The second argument will be passed in register EBX leaving ECX as an available register for 
other arguments. 

3. The third argument will not fit in register ECX (its size is 8 bytes) and hence will be pushed on 
the stack. 

Let us look at the stack upon entry to myrtn . 

Small Code Model 


Offset 

+-+ 

0 | return address | <- ESP points here 

+-+ 

4 argument #3 

+-+ 

12 I I 
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Big Code Model 
Offset 


0 

8 

16 


+-+ 

return address | <- ESP points here 

+-+ 

argument #3 

+-+ 


Notes: 


1. The return address is the top element on the stack. In a small code model, the return address is 1 
double word (32 bits); in a big code model, the return address is 2 double words (64 bits). 

Register EBP is normally used to address arguments on the stack. Upon entry to the function, register EBP 
is set to point to the stack but before doing so we must save its contents. The following two instructions 
achieve this. 

push EBP ; save current value of EBP 

mov EBP,ESP ; get access to arguments 

After executing these instructions, the stack looks like this. 

Small Code Model 


Offset 

+-+ 

0 | saved EBP | <- EBP and ESP point here 

+-+ 

4 | return address | 

+-+ 

8 | argument #3 


+ 

16 | 
Big Code Model 


Offset 

+-+ 

0 | saved EBP | <- EBP and ESP point here 

+-+ 

4 return address | 

+-+ 

12 | argument #3 


+ 

20 | 

As the above diagrams show, the third argument is at offset 8 from register EBP in a small code model and 
offset 12 in a big code model. 

Upon exit from myrtn, we must restore the value of EBP. The following two instructions achieve this. 
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mov ESP,EBP ; restore stack pointer 

pop EBP ; restore EBP 

The following is a sample assembly language function which implements myrtn . 

Small Memory Model (small code, small data) 

DGROUP group _ DATA, _ BSS 

_ TEXT segment byte public 'CODE' 

assume CS:_TEXT 

assume DS:DGROUP 

public myrtn_ 

myrtn_ proc near 

push EBP ; save EBP 

mov EBP,ESP ; get access to arguments 

r 

; body of function 

r 

mov ESP,EBP ; restore ESP 

pop EBP ; restore EBP 

ret 8 ; return and pop last arg 

myrtn_ endp 

_ TEXT ends 

Large Memory Model (big code, big data) 

DGROUP group _DATA, _ BSS 

MYRTN_ TEXT segment byte public 'CODE' 
assume CS:MYRTN_ TEXT 
public myrtn_ 

myrtn_ proc far 

push EBP ; save EBP 

mov EBP,ESP ; get access to arguments 

r 

; body of function 

r 

mov ESP,EBP ; restore ESP 

pop EBP ; restore EBP 

ret 8 ; return and pop last arg 

myrtn_ endp 

MYRTN_ TEXT ends 

Notes: 

1. Global function names must be followed with an underscore. Global variable names must be 
preceded with an underscore. 

2. All used 80x86 registers must be saved on entry and restored on exit except those used to pass 
arguments and return values, and AX, which is considered a stratch register. Note that segment 
registers only have to saved and restored if you are compiling your application with the "r" 
option. 

3. The direction flag must be clear before returning to the caller. 

4. In a small code model, any segment containing executable code must belong to the segment 
"_TEXT" and the class "CODE". The segment "_TEXT" must have a "combine" type of 
"PUBLIC". On entry, CS contains the segment address of the segment "_TEXT". In a big code 
model there is no restriction on the naming of segments which contain executable code. 
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5. In a small data model, segment register DS contains the segment address of the group 
"DGROUP". This is not the case in a big data model. 

6. When writing assembly language functions for the small code model, you must declare them as 
"near". If you wish to write assembly language functions for the big code model, you must 
declare them as "far". 

7. In general, when naming segments for your code or data, you should follow the conventions 
described in the section entitled "Memory Layout" in this chapter. 

8. If any of the arguments was pushed onto the stack, the called routine must pop those arguments 
off the stack in the "ret" instruction. 


10.4.6 Using Stack-Based Calling Conventions 

Let us now consider the example in the previous section except this time we will use the stack-based calling 
convention. The most significant difference between the stack-based calling convention and the 
register-based calling convention is the way the arguments are passed. When using the stack-based calling 
conventions, no registers are used to pass arguments. Instead, all arguments are passed on the stack. 

Let us look at the stack upon entry to myrtn . 


Small Code Model 


Offset 

+-+ 

0 | return address | <- ESP points here 

+-+ 

4 argument #1 

+ - + 

12 | argument #2 

+ - + 

16 | argument #3 

+ - + 

24 I I 


Big Code Model 
Offset 


0 

8 

16 

20 

28 


+-+ 

return address | <- ESP points here 

+-+ 

argument #1 

+-+ 

| argument #2 

+-+ 

| argument #3 

+-+ 
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Notes: 

1. The return address is the top element on the stack. In a small code model, the return address is 1 
double word (32 bits); in a big code model, the return address is 2 double words (64 bits). 

Register EBP is normally used to address arguments on the stack. Upon entry to the function, register EBP 
is set to point to the stack but before doing so we must save its contents. The following two instructions 
achieve this. 

push EBP ; save current value of EBP 

mov EBP,ESP ; get access to arguments 

After executing these instructions, the stack looks like this. 

Small Code Model 


Offset 

+-+ 

0 | saved EBP | <- EBP and ESP point here 

+-+ 

4 | return address | 

+-+ 

8 argument #1 

+-+ 

16 | argument #2 

+-+ 

20 | argument #3 

+-+ 

28 I 


Big Code Model 


Offset 

+-+ 

0 | saved EBP | <- EBP and ESP point here 

+-+ 

4 return address | 

+-+ 

12 | argument #1 

+-+ 

20 argument #2 

+-+ 

24 | argument #3 

+-+ 

32 I I 


As the above diagrams show, the argument are all on the stack and are referenced by specifying an offset 
from register EBP. 

Upon exit from myrtn, we must restore the value of EBP. The following two instructions achieve this. 
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mov ESP,EBP ; restore stack pointer 

pop EBP ; restore EBP 

The following is a sample assembly language function which implements myrtn . 

Small Memory Model (small code, small data) 

DGROUP group _ DATA, _ BSS 

_ TEXT segment byte public 'CODE' 

assume CS:_TEXT 

assume DS:DGROUP 

public myrtn 

myrtn proc near 

push EBP ; save EBP 

mov EBP,ESP ; get access to arguments 

r 

; body of function 

r 

mov ESP,EBP ; restore ESP 

pop EBP ; restore EBP 

ret 

; return 
myrtn endp 

_ TEXT ends 

Large Memory Model (big code, big data) 

DGROUP group _ DATA, _ BSS 

MYRTN_ TEXT segment byte public 'CODE' 
assume CS:MYRTN_ TEXT 
public myrtn 

myrtn proc far 

push EBP ; save EBP 

mov EBP,ESP ; get access to arguments 

r 

; body of function 

r 

mov ESP,EBP ; restore ESP 

pop EBP ; restore EBP 

ret 

; return 
myrtn endp 

MYRTN_ TEXT ends 

Notes: 

1. Global function names must not be followed with an underscore as was the case with the 
register-based calling convention. Global variable names must not be preceded with an 
underscore as was the case with the register-based calling convention. 

2. All used 80x86 registers except registers EAX, ECX and EDX must be saved on entry and 
restored on exit. Segment registers DS and ES must also be saved on entry and restored on exit. 
Segment register ES does not have to be saved and restored when using a memory model that is 
not a small data model. Note that segment registers only have to be saved and restored if you are 
compiling your application with the "r" option. 

3. The direction flag must be clear before returning to the caller. 
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4. In a small code model, any segment containing executable code must belong to the segment 
"_TEXT" and the class "CODE". The segment "_TEXT" must have a "combine" type of 
"PUBLIC". On entry, CS contains the segment address of the segment "_TEXT". In a big code 
model there is no restriction on the naming of segments which contain executable code. 

5. In a small data model, segment register DS contains the segment address of the group 
"DGROUP". This is not the case in a big data model. 

6. When writing assembly language functions for the small code model, you must declare them as 
"near". If you wish to write assembly language functions for the big code model, you must 
declare them as "far". 

7. In general, when naming segments for your code or data, you should follow the conventions 
described in the section entitled "Memory Layout" in this chapter. 

8. The caller is responsible for removing arguments from the stack. 

10.4.7 Functions with Variable Number of Arguments 

A function prototype with a parameter list that ends with has a variable number of arguments. In this 
case, all arguments are passed on the stack. Since no prototyping information exists for arguments 
represented by those arguments are passed as described in the section "Passing Arguments". 

10.4.8 Returning Values from Functions 

The way in which function values are returned depends on the size of the return value. The following 
examples describe how function values are to be returned. They are coded for a small code model. 

1. 1-byte values are to be returned in register AL. 

Example: 

_ TEXT segment byte public 'CODE' 
assume CS:_TEXT 
public Retl_ 

Retl_ proc near ; char Retl() 
mov AL, ' G' 

ret 

Retl_ endp 

_ TEXT ends 

end 

2. 2-byte values are to be returned in register AX. 

Example: 

_ TEXT segment byte public 'CODE' 
assume CS:_TEXT 
public Ret2_ 

Ret2_ proc near ; short int Ret2() 

mov AX,77 

ret 

Ret2_ endp 

_ TEXT ends 

end 
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3. 4-byte values are to be returned in register EAX. 


Example: 

_ TEXT 


Ret 4. 


Ret4_ 
_ TEXT 


segment byte public 'CODE' 
assume CS:_TEXT 
public Ret4_ 

proc near ; int Ret4() 
mov EAX,7777777 

ret 
endp 
ends 
end 


4. 8-byte values, except structures, are to be returned in registers EDX and EAX. When using the 
"fpc" (floating-point calls) option, "float" and "double" are returned in registers. See section 
"Returning Values in 80x87-based Applications" when using the "fpi" or "fpi87" options. 


Example: 

_ TEXT 

Ret8_ 


Val8 : 
Ret8_ 
_ TEXT 


. 8087 

segment byte public 'CODE' 
assume CS:_TEXT 
public Ret8_ 

proc near ; double Ret8() 
mov EDX,dword ptr CS:Val8+4 

mov EAX,dword ptr CS:Val8 

ret 

dq 7.7 

endp 
ends 
end 


The ".8087" pseudo-op must be specified so that all floating-point constants are generated in 
8087 format. 

5. Otherwise, the caller allocates space on the stack for the return value and sets register ESI to 
point to this area. In a big data model, register ESI contains an offset relative to the segment 
value in segment register SS. 

Example: 

_ TEXT segment byte public 'CODE' 
assume CS:_TEXT 
public RetX_ 

r 

; struct int_ values { 


r 

r 

int valuel 

, value2, 
1; 

value3, value4. 

value5; 

r 

RetX_ 

proc 

near ; struct int_ values 

RetX () 


mov 

dword ptr 

SS : 0[ESI],71 



mov 

dword ptr 

SS:4[ESI],72 



mov 

dword ptr 

SS:8[ESI],73 



mov 

dword ptr 

SS:12[ESI] , 74 



mov 

dword ptr 

SS:16[ESI] , 75 



ret 




RetX_ 

endp 




_ TEXT 

ends 

end 
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When returning values on the stack, remember to use a segment override to the stack segment 
(SS). 


The following is an example of a Open Watcom C/C++ program calling the above assembly language 
subprograms. 


♦include <stdio.h> 

struct int_ values { 
int valuel; 
int value2; 
int value3; 
int value4; 
int value5; 

}; 

Retl(void); 
Ret2(void); 
Ret4(void); 
Ret8(void); 
values RetX(void); 


extern char 
extern short int 
extern long int 
extern double 
extern struct int_ 


void main() 

{ 

struct int_ values x; 


printf( 

"Retl = 

% c \ n " , 

Retl () ) ; 


printf( 

"Ret2 = 

%d\n", 

Ret2 () ) ; 


printf( 

"Ret4 = 

%ld\n", 

Ret4 () ) ; 


printf( 

"Ret8 = 

% f \ n " , 

Ret8 () ) ; 


x = RetX(); 




printf( 

"RetXl 

= %d\n". 

x.valuel 

; 

printf( 

"RetX2 

= %d\n". 

x.value2 

; 

printf( 

"RetX3 

= %d\n". 

x.value3 

; 

printf( 

"RetX4 

= %d\n". 

x.value4 

; 

printf( 

"RetX5 

= %d\n". 

x.value5 

; 


The above function should be compiled for a small code model (use the "mf', "ms" or "me" compiler 
option). 


Note: Returning values from functions in the stack-based calling convention is the same as returning 
values from functions in the register-based calling convention when using the "fpc" option. 


10.5 Calling Conventions for 80x87-based Applications 

When a source file is compiled by Open Watcom C/C++ with one of the "fpi" or "fpi87" options, all 
floating-point arguments are passed on the 80x86 stack. The rules for passing arguments are as follows. 

1. If the argument is not floating-point, use the procedure described earlier in this chapter. 

2. If the argument is floating-point, it is assigned a position on the 80x86 stack. 
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Note: When compiling using the "fpi" or "fpi87" options, the method used for passing floating-point 
arguments in the stack-based calling convention is identical to the method used in the register-based 
calling convention. However, when compiling using the "fpi" or "fpi87" options, the method used for 
returning floating-point values in the stack-based calling convention is different from the method used 
in the register-based calling convention. The register-based calling convention returns floating-point 
values in ST(0), whereas the stack-based calling convention returns floating-point values in EDX and 
EAX. 


10.5.1 Passing Values in 80x87-based Applications 

Consider the following example. 

Example: 

extern void myrtn(int,float,double,long int); 

void main() 

{ 

float x; 

double y; 

int i; 

long int j; 

x = 7.7; 

1 = 7; 
y = 77.77 
j = 77; 

myrtn( i, x, y, j ); 

} 

myrtn is an assembly language function that requires four arguments. The first argument is of type "int" ( 
4 bytes), the second argument is of type "float" (4 bytes), the third argument is of type "double" (8 bytes) 
and the fourth argument is of type "long int" (4 bytes). 

When using the stack-based calling conventions, all of the arguments will be passed on the stack. When 
using the register-based calling conventions, the above arguments will be passed to myrtn in the following 
way: 

1. The first argument will be passed in register EAX leaving EBX, ECX and EDX as available 
registers for other arguments. 

2. The second argument will be passed on the 80x86 stack since it is a floating-point argument. 

3. The third argument will also be passed on the 80x86 stack since it is a floating-point argument. 

4. The fourth argument will be passed on the 80x86 stack since a previous argument has been 
assigned a position on the 80x86 stack. 

Remember, arguments are pushed on the stack from right to left. That is, the rightmost argument is pushed 
first. 

Any assembly language function must obey the following rule. 
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1. All arguments passed on the stack must be removed by the called function. 

The following is a sample assembly language function which implements myrtn . 

Example: 

.8087 

_ TEXT segment byte public 'CODE' 
assume CS:_TEXT 
public myrtn_ 

myrtn_ proc near 

r 

; body of function 

r 

ret 16 ; return and pop arguments 

myrtn_ endp 

_ TEXT ends 
end 

Notes: 

1. Function names must be followed by an underscore. 

2. All used 80x86 registers must be saved on entry and restored on exit except those used to pass 
arguments and return values, and EAX, which is considered a stratch register. Note that segment 
registers only have to saved and restored if you are compiling your application with the "r" 
option. In this example, EAX does not have to be saved as it was used to pass the first argument. 
Floating-point registers can be modified without saving their contents. 

3. The direction flag must be clear before returning to the caller. 

4. This function has been written for a small code model. Any segment containing executable code 
must belong to the class "CODE" and the segment "_TEXT". On entry, CS contains the segment 
address of the segment "_TEXT". The above restrictions do not apply in a big code memory 
model. 

5. When writing assembly language functions for a small code model, you must declare them as 
"near". If you wish to write assembly language functions for a big code model, you must declare 
them as "far". 

10.5.2 Returning Values in 80x87-based Applications 

When using the stack-based calling conventions with "fpi" or "fpi87", floating-point values are returned in 
registers. Single precision values are returned in EAX, and double precision values are returned in 
EDX:EAX. 

When using the register-based calling conventions with "fpi" or "fpi87", floating-point values are returned 
in ST(0). All other values are returned in the manner described earlier in this chapter. 
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11.1 Introduction 


A pragma is a compiler directive that provides the following capabilities. 

• Pragmas allow you to specify certain compiler options. 

• Pragmas can be used to direct the Open Watcom C/C++ code generator to emit specialized 
sequences of code for calling functions which use argument passing and value return techniques that 
differ from the default used by Open Watcom C/C++. 

• Pragmas can be used to describe attributes of functions (such as side effects) that are not possible at 
the C/C++ language level. The code generator can use this information to generate more efficient 
code. 

• Any sequence of in-line machine language instructions, including DOS and BIOS function calls, can 
be generated in the object code. 

Pragmas are specified in the source file using the pragma directive. The following notation is used to 
describe the syntax of pragmas. 

keywords A keyword is shown in a mono-spaced courier font. 

program-item A program-item is shown in a roman bold-italics font. A program-item is a symbol name 
or numeric value supplied by the programmer. 

punctuation A punctuation character shown in a mono-spaced courier font must be entered as 
is. 

A punctuation character shown in a roman bold-italics font is used to describe syntax. 

The following syntactical notation is used. 

[abc] The item abc is optional. 

{abc} The item abc may be repeated zero or more times, 

alblc One of a, b or c may be specified, 

a ::= b The item a is defined in terms of b. 

(a) Item a is evaluated first. 

The following classes of pragmas are supported. 
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• pragmas that specify options 

• pragmas that specify default libraries 

• pragmas that describe the way structures are stored in memory 

• pragmas that provide auxiliary information used for code generation 

11.2 Using Pragmas to Specify Options 

Currently, the following options can be specified with pragmas: 

unreferenced The "unreferenced" option controls the way Open Watcom C/C++ handles unused symbols. 
For example, 

♦pragma on (unreferenced); 

will cause Open Watcom C/C++ to issue warning messages for all unused symbols. This is 
the default. Specifying 

♦pragma off (unreferenced); 

will cause Open Watcom C/C++ to ignore unused symbols. Note that if the warning level 
is not high enough, warning messages for unused symbols will not be issued even if 
"unreferenced" was specified. 

check_stack The "check_stack" option controls the way stack overflows are to be handled. For 
example, 

♦pragma on (check_ stack) ; 
will cause stack overflows to be detected and 
♦pragma off (check_ stack) ; 

will cause stack overflows to be ignored. When "check_stack" is on. Open Watcom C/C++ 
will generate a run-time call to a stack-checking routine at the start of every routine 
compiled. This run-time routine will issue an error if a stack overflow occurs when 
invoking the routine. The default is to check for stack overflows. Stack overflow checking 
is particularly useful when functions are invoked recursively. Note that if the stack 
overflows and stack checking has been suppressed, unpredictable results can occur. 

If a stack overflow does occur during execution and you are sure that your program is not 
in error (i.e. it is not unnecessarily recursing), you must increase the stack size. This is 
done by linking your application again and specifying the "STACK" option to the Open 
Watcom Linker with a larger stack size. 

It is also possible to specify more than one option in a pragma as illustrated by the 
following example. 

♦pragma on (check_ stack unreferenced); 
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reuse-duplicate _strings (C only) (C Only) The "reuse_duplicate_strings" option controls the way Open 
Watcom C handles identical strings in an expression. For example, 

#pragma on (reuse_ duplicate_ strings); 

will cause Open Watcom C to reuse identical strings in an expression. This is the default. 
Specifying 

#pragma off (reuse_ duplicate_ strings) ; 

will cause Open Watcom C to generate additional copies of the identical string. The 
following example shows where this may be of importance to the way the application 
behaves. 

Example: 

♦include <stdio.h> 

♦pragma off (reuse_ duplicate_ strings) 


void poke( char *, char * ); 

void main() 

{ 

poke( "Hello world\n", "Hello world\n" ); 

} 

void poke( char *x, char *y ) 

{ 

x[3] = 'X'; 
printf( x ); 
y[4] = 'Y'; 
printf( y ) ; 

} 

/* 

Default output: 

HelXo world 
HelXY world 
*/ 


11.3 Using Pragmas to Specify Default Libraries 

Default libraries are specified in special object module records. Library names are extracted from these 
special records by the Open Watcom Linker. When unresolved references remain after processing all 
object modules specified in linker "FILE" directives, these default libraries are searched after all libraries 
specified in linker "LIBRARY" directives have been searched. 

By default, that is if no library pragma is specified, the Open Watcom C/C++ compiler generates, in the 
object file defining the main program, default libraries corresponding to the memory model and 
floating-point model used to compile the file. For example, if you have compiled the source file containing 
the main program for the flat memory model and the floating-point calls floating-point model, the libraries 
"clib3r" and "math3r" will be placed in the object file. 

If you wish to add your own default libraries to this list, you can do so with a library pragma. Consider the 
following example. 
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♦pragma library (mylib); 

The name "mylib" will be added to the list of default libraries specified in the object file. 

If the library specification contains characters such as ’V, or (i.e., any character not allowed in a C 
identifier), you must enclose it in double quotes as in the following example. 

♦pragma library ("\watcom\lib286\dos\graph.lib"); 

♦pragma library ("\watcom\lib386\dos\graph.lib"); 

If you wish to specify more than one library in a library pragma you must separate them with spaces as in 
the following example. 

♦pragma library (mylib "\watcom\lib286\dos\graph.lib"); 

♦pragma library (mylib "\watcom\lib386\dos\graph.lib"); 

11.4 The ALIAS Pragma (C Only) 

The "alias" pragma can be used to emit alias records in the object file, causing the linker to substitute 
references to a specified symbol with references to another symbol. Either identifiers or names (strings) 
may be used. Strings are used verbatim, while names corresponding to identifiers are derived as 
appropriate for the kind and calling convention of the symbol. The following describes the form of the 
"alias" pragma. 


♦pragma alias ( alias, subst ) [;] 


where description: 

alias is either a name or an identifier of the symbol to be aliased. 

subst is either a name or an identifier of the symbol that references to alias will be replaced 

with. 

Consider the following example. 

extern int var; 

void fn( void ) 

{ 

var = 3; 

} 

♦pragma alias ( var, "other_ var" ) ; 

Instead of var the linker will reference symbol named "other_var". Symbol var need not be defined, 
although "other_var" has to be. 
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11.5 The ALLOC_TEXTPragma (C Only) 

The "alloc_text" pragma can be used to specify the name of the text segment into which the generated code 
for a function, or a list of functions, is to be placed. The following describes the form of the "alloc_text" 
pragma. 


♦pragma alloc_ text ( seg_name, fn {, fn} ) [;] 


where description: 

segjiame is the name of the text segment. 

fn is the name of a function. 

Consider the following example. 

extern int fnl(int); 
extern int fn2(void); 

♦pragma alloc_ text ( my_text, fnl, fn2 ); 

The code for the functions fnl and fn2 will be placed in the segment my_ text. Note: function 
prototypes for the named functions must exist prior to the "alloc_text" pragma. 

11.6 The CODEJSEG Pragma 

The "code_seg" pragma can be used to specify the name of the text segment into which the generated code 
for functions is to be placed. The following describes the form of the "code_seg" pragma. 


♦pragma code_ seg ( seg_name [, class_name] ) [;] 


where description: 

segjiame is the name of the text segment optionally enclosed in quotes. Also, seg_ name may be a 
macro as in: 

♦ define seg_ name "MY_ CODE_ SEG" 

♦pragma code_ seg ( seg_ name ) ; 


class jiame is the optional class name of the text segment and may be enclosed in quotes. Please note 

that in order to be recognized by the linker as code, a class name has to end in "CODE". 
Also, class_ name may be a macro as in: 

♦define class_ name "MY_ CODE" 

♦pragma code_ seg ( "MY_ CODE_ SEG", class_ name ); 


Consider the following example. 


The CODEJSEG Pragma 211 





32-bit Topics 


♦pragma code_ seg ( my_ text ) ; 

int incr( int i ) 

{ 

return( i + 1 ); 

} 

int deer( int i ) 

{ 

return( i - 1 ); 

} 

The code for the functions incr and deer will be placed in the segment my_ text. 

To return to the default segment, do not specify any string between the opening and closing parenthesis, 
♦pragma code_ seg (); 


11.7 The COMMENT Pragma 

The "comment" pragma can be used to place a comment record in an object file or executable file. The 
following describes the form of the "comment" pragma. 


♦pragma comment ( comment_type [, "comment_string"] ) [;] 


where description: 

comment Jype specifies the type of comment record. The allowable comment types are: 

lib Default libraries are specified in special object module records. Library 

names are extracted from these special records by the Open Watcom 
Linker. When unresolved references remain after processing all object 
modules specified in linker "FILE" directives, these default libraries are 
searched after all libraries specified in linker "LIBRARY" directives have 
been searched. 

The "lib" form of this pragma offers the same features as the "library" 
pragma. See the section entitled "Using Pragmas to Specify Default 
Libraries" on page 209 for more information. 

" commentjstring" is an optional string literal that provides additional information for some comment 
types. 

Consider the following example. 

♦pragma comment ( lib, "mylib" ); 
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11.8 The DATA_SEG Pragma 

The "data_seg" pragma can be used to specify the name of the segment into which data is to be placed. The 
following describes the form of the "data_seg" pragma. 


♦pragma data_ seg ( seg_name [, class_name] ) [;] 


where description: 

segjiame is the name of the data segment and may be enclosed in quotes. Also, seg_ name may be 
a macro as in: 

♦ define seg_ name "MY_ DATA_ SEG" 

♦pragma data_ seg ( seg_ name ) ; 

class_name is the optional class name of the data segment and may be enclosed in quotes. Also, 

class_ name may be a macro as in: 

♦define class_ name "MY_ CLASS" 

♦pragma data_ seg ( "MY_ DATA_ SEG", class_ name ) ; 

Consider the following example. 

♦pragma data_ seg ( my_ data ) ; 

static int i; 
static int j; 

The data for i and j will be placed in the segment my_ data . 

To return to the default segment, do not specify any string between the opening and closing parenthesis, 
♦pragma data_ seg (); 

11.9 The DISABLE_MESSAGE Pragma 

The "disable_message" pragma disables the issuance of specified diagnostic messages. The form of the 
"disable_message" pragma is as follows. 


♦pragma disable_ message ( msg_num {, msg_num} ) [;] 


where description: 

msg_num is the number of the diagnostic message. This number corresponds to the number issued by 
the compiler and can be found in the appendix entitled "Open Watcom C Diagnostic 
Messages" on page 305. Make sure to strip all leading zeroes from the message number (to 
avoid interpretation as an octal constant). 
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See also the description of "The ENABLE_MESSAGE Pragma". 


11.10 The DUMP_OBJECT_MODEL Pragma (C++ Only) 

The "dump_object_model" pragma causes the C++ compiler to print information about the object model for 
an indicated class or an enumeration name to the diagnostics file. For class names, this information 
includes the offsets and sizes of fields within the class and within base classes. For enumeration names, 
this information consists of a list of all the enumeration constants with their values. 

The general form of the "dump_object_model" pragma is as follows. 


♦pragma dump_ object_ model class [;] 
♦pragma dump_ object_ model enumeration [;] 
class ::= a defined C++ class free of errors 
enumeration ::= a defined C++ enumeration name 


This pragma is designed to be used for information purposes only. 


11.11 The ENABLE_MESSAGE Pragma 

The "enable_message" pragma re-enables the issuance of specified diagnostic messages that have been 
previously disabled. The form of the "enable_message" pragma is as follows. 


♦pragma enable_ message ( msg_num {, msg_num} ) [;] 


where description: 

msgjium is the number of the diagnostic message. This number corresponds to the number issued by 
the compiler and can be found in the appendix entitled "Open Watcom C Diagnostic 
Messages" on page 305. Make sure to strip all leading zeroes from the message number (to 
avoid interpretation as an octal constant). 

See also the description of "The DISABLE_MESSAGE Pragma" on page 213. 


11.12 The ENUM Pragma 

The "enum" pragma affects the underlying storage-definition for subsequent enum declarations. The forms 
of the "enum" pragma are as follows. 


♦pragma 

♦pragma 

♦pragma 

♦pragma 


enum int [;] 
enum minimum [;] 
enum original [;] 
enum pop [;] 
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where description: 

int Make int the underlying storage definition (same as the "ei" compiler option). 

minimum Minimize the underlying storage definition (same as not specifying the "ei" compiler 
option). 

original Reset back to the original compiler option setting (i.e., what was or was not specified on the 

command line). 

pop Restore the previous setting. 

The first three forms all push the previous setting before establishing the new setting. 


11.13 The ERROR Pragma 

The "error" pragma can be used to issue an error message with the specified text. The following describes 
the form of the "error" pragma. 


♦pragma error "error text" [;] 


where description: 

"error text" is the text of the message that you wish to display. 

You should use the ISO #error directive rather than this pragma. This pragma is provided for compatibility 
with legacy code. The following is an example. 

#if defined(_ 386_) 

♦elseif defined!_86_) 

♦ else 

♦pragma error ( "neither_ 386_or_86_defined" ); 

♦endif 


11.14 The EXTREF Pragma 

The "extref" pragma is used to generate a reference to an external function or data item. The form of the 
"extref" pragma is as follows. 


♦pragma extref name [;] 
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where description: 

name is the name of an external function or data item. It must be declared to be an external 

function or data item before the pragma is encountered. In C++, when name is a function, 
it must not be overloaded. 

This pragma causes an external reference for the function or data item to be emitted into the object file even 
if that function or data item is not referenced in the module. The external reference will cause the linker to 
include the module containing that name in the linked program or DLL. 

This is useful for debugging since you can cause debugging routines (callable from within debugger) to be 
included into a program or DLL to be debugged. 

In C++, you can also force constructors and/or destructors to be called for a data item without necessarily 
referencing the data item anywhere in your code. 

11.15 The FUNCTION Pragma 

Certain functions, such as those listed in the description of the "oi" and "om" options, have intrinsic forms. 
These functions are special functions that are recognized by the compiler and processed in a special way. 
For example, the compiler may choose to generate in-line code for the function. The intrinsic attribute for 
these special functions is set by specifying the "oi" or "om" option or using an "intrinsic" pragma. The 
"function" pragma can be used to remove the intrinsic attribute for a specified list of functions. 

The following describes the form of the "function" pragma. 


♦pragma function ( fn {, fn} ) [;] 


where description: 

fn is the name of a function. 

Suppose the following source code was compiled using the "om" option so that when one of the special 
math functions is referenced, the intrinsic form will be used. In our example, we have referenced the 
function sin which does have an intrinsic form. By specifying sin in a "function" pragma, the intrinsic 
attribute will be removed, causing the function sin to be treated as a regular user-defined function. 

♦include <math.h> 

♦pragma function( sin ) ; 

double test ( double x ) 

{ 

return( sin( x ) ); 

} 


216 The FUNCTION Pragma 







32-bit Pragmas 


11.16 The INCLUDE_ALIAS Pragma 

In certain situations, it can be advantageous to remap the names of include files. Most commonly this 
occurs on systems that do not support long file names when building source code that references header 
files with long names. 

The form of the "include_alias" pragma follows. 


♦pragma 

include_ 

alias 

( "alias_name", "real_name" ) 

' [;] 

♦pragma 

include_ 

alias 

( <alias_name>, <real_name> ) 

' [;] 


where description: 

alias jiame is the name referenced in include directives in source code. 

realjiame is the translated name that the compiler will reference instead. 

The following is an example. 

♦pragma include_ alias( "LongFileName.h", "lfn.h" ) 

♦include "LongFileName.h" 

In the example, the compiler will attempt to read lfn.h when LongFileName.h was included. 

Note that only simple textual substitution is performed. The aliased name must match exactly, including 
double quotes or angle brackets, as well as any directory separators. Also, double quotes and angle 
brackets may not be mixed a single pragma. 

The value of the predefined_ FILE _symbol, as well as the filename reported in error messages, will be 

the true filename after substitution was performed. 

11.17 Setting Priority of Static Data Initialization (C++ Only) 

The "initialize" pragma sets the priority for initialization of static data in the file. This priority only applies 
to initialization of static data that requires the execution of code. For example, the initialization of a class 
that contains a constructor requires the execution of the constructor. Note that if the sequence in which 
initialization of static data in your program takes place has no dependencies, the "initialize" pragma need 
not be used. 

The general form of the "initialize" pragma is as follows. 


♦pragma initialize [before I after] priority [;] 
priority ::= n I library I program 
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where description: 

n is a number representing the priority and must be in the range 0-255. The larger the 

priority, the later the point at which initialization will occur. 

Priorities in the range 0-20 are reserved for the C++ compiler. This is to ensure that proper initialization of 
the C++ run-time system takes place before the execution of your program. The "library" keyword 
represents a priority of 32 and can be used for class libraries that require initialization before the program is 
initialized. The "program" keyword represents a priority of 64 and is the default priority for any compiled 
code. Specifying "before" adjusts the priority by subtracting one. Specifying "after" adjusts the priority by 
adding one. 

A source file containing the following "initialize" pragma specifies that the initialization of static data in the 
file will take place before initialization of all other static data in the program since a priority of 63 will be 
assigned. 

Example: 

♦pragma initialize before program 

If we specify "after" instead of "before", the initialization of the static data in the file will occur after 
initialization of all other static data in the program since a priority of 65 will be assigned. 

Note that the following is equivalent to the "before" example 

Example: 

♦pragma initialize 63 
and the following is equivalent to the "after" example. 

Example: 

♦pragma initialize 65 

The use of the "before", "after", and "program" keywords are more descriptive in the intent of the pragmas. 

It is recommended that a priority of 32 (the priority used when the "library" keyword is specified) be used 
when developing class libraries. This will ensure that initialization of static data defined by the class 
library will take place before initialization of static data defined by the program. The following "initialize" 
pragma can be used to achieve this. 

Example: 

♦pragma initialize library 

11.18 The INLINE_DEPTH Pragma (C++ Only) 

When an in-line function is called, the function call may be replaced by the in-line expansion for that 
function. This in-line expansion may include calls to other in-line functions which can also be expanded. 
The "inline_depth" pragma can be used to set the number of times this expansion of in-line functions will 
occur for a call. 

The form of the "inline_depth" pragma is as follows. 
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♦pragma inline_ depth [(] n [)] [;] 


where description: 

n is the depth of expansion. If n is 0, no expansion will occur. If n is 1, only the original call 

is expanded. If n is 2, the original call and the in-line functions invoked by the original 
function will be expanded. The default value for n is 3. The maximum value for n is 255. 
Note that no expansion of recursive in-line functions occur unless enabled using the 
"inline_recursion" pragma. 

11.19 The INLINE_RECURSION Pragma (C++ Only) 

The "inline_recursion" pragma controls the recursive expansion of inline functions. The form of the 
"inline_recursion" pragma is as follows. 


♦pragma inline_ recursion [(] on I off [)] [;] 


Specifying "on" will enable expansion of recursive inline functions. The depth of expansion is specified by 
the "inline_depth" pragma. The default depth is 3. Specifying "off" suppresses expansion of recursive 
inline functions. This is the default. 


11.20 The INTRINSIC Pragma 

Certain functions, those listed in the description of the "oi" option, have intrinsic forms. These functions 
are special functions that are recognized by the compiler and processed in a special way. For example, the 
compiler may choose to generate in-line code for the function. The intrinsic attribute for these special 
functions is set by specifying the "oi" option or using an "intrinsic" pragma. 

The following describes the form of the "intrinsic" pragma. 


♦pragma intrinsic ( fn {, fn} ) [;] 


where description: 

fn is the name of a function. 

Suppose the following source code was compiled without using the "oi" option so that no function had the 
intrinsic attribute. If we wanted the intrinsic form of the sin function to be used, we could specify the 
function in an "intrinsic" pragma. 
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♦include <math.h> 

♦pragma intrinsic( sin ) ; 

double test ( double x ) 

{ 

return( sin( x ) ); 

} 


11.21 The MESSAGE Pragma 

The "message" pragma can be used to issue a message with the specified text to the standard output without 
terminating compilation. The following describes the form of the "message" pragma. 


♦pragma message ( "message text" ) [;] 


where description: 

"message text" is the text of the message that you wish to display. 

The following is an example. 

♦ if defined!_ 386_) 

♦ else 

♦pragma message ( "assuming 16-bit compile" ); 
♦endif 


11.22 The ONCE Pragma 

The "once" pragma can be used to indicate that the file which contains this pragma should only be opened 
and processed "once". The following describes the form of the "once" pragma. 


♦pragma once [;] 


Assume that the file "foo.h" contains the following text. 


Example: 

♦ ifndef _ F00_ H_ INCLUDED 
♦define _ F00_ H_ INCLUDED 
♦pragma once 


♦endif 

The first time that the compiler processes "foo.h" and encounters the "once" pragma, it records the file’s 
name. Subsequently, whenever the compiler encounters a ♦include statement that refers to "foo.h", it 
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will not open the include file again. This can help speed up processing of #include files and reduce the 
time required to compile an application. 

11.23 The PACK Pragma 

The "pack" pragma can be used to control the way in which structures are stored in memory. There are 4 
forms of the "pack" pragma. 

The following form of the "pack" pragma can be used to change the alignment of structures and their fields 
in memory. 


♦pragma pack ( n ) [;] 


where description: 

n is 1, 2, 4, 8 or 16 and specifies the method of alignment. 


The alignment of structure members is described in the following table. If the size of the member is 1,2, 4, 
8 or 16, the alignment is given for each of the "zp" options. If the member of the structure is an array or 
structure, the alignment is described by the row "x". 


sizeof(member) 
1 
2 
4 
8 

16 

x 


\ 


zpl zp2 zp4 zp8 


0 

0 

0 

0 

0 


0 

2 

2 

2 

2 


aligned to 


0 

2 

4 

4 

4 


0 

2 

4 

8 

8 


largest member 


zpl 6 


0 

2 

4 

8 

16 


An alignment of 0 means no alignment, 2 means word boundary, 4 means doubleword boundary, etc. If the 
largest member of structure "x" is 1 byte then "x" is not aligned. If the largest member of structure "x" is 2 
bytes then "x" is aligned according to row 2. If the largest member of structure "x" is 4 bytes then "x" is 
aligned according to row 4. If the largest member of structure "x" is 8 bytes then "x" is aligned according 
to row 8. If the largest member of structure "x" is 16 bytes then "x" is aligned according to row 16. 

If no value is specified in the "pack" pragma, a default value of 8 is used. Note that the default value can be 
changed with the "zp" Open Watcom C/C++ compiler command line option. 

The following form of the "pack" pragma can be used to save the current alignment amount on an internal 
stack. 


♦pragma pack ( push ) [;] 


The following form of the "pack" pragma can be used to save the current alignment amount on an internal 
stack and set the current alignment. 
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♦pragma pack ( push, number ) [;] 


The following form of the "pack" pragma can be used to restore the previous alignment amount from an 
internal stack. 


♦pragma pack ( pop ) [;] 


11.24 The READ-ONLY._FILE Pragma 

Explicit listing of dependencies in a makefile can often be tedious in the development and maintenance 
phases of a project. The Open Watcom C/C++ compiler will insert dependency information into the object 
file as it processes source files so that a complete snapshot of the files necessary to build the object file are 
recorded. The "read_only_file" pragma can be used to prevent the name of the source file that includes it 
from being included in the dependency information that is written to the object file. 

This pragma is commonly used in system header files since they change infrequently (and, when they do, 
there should be no impact on source files that have included them). 

The form of the "read_only_file" pragma follows. 


♦pragma read_ only_ file [;] 


For more information on make dependencies, see the section entitled "Automatic Dependency Detection 
(.AUTODEPEND)" in the Open Watcom C/C++ Tools User’s Guide. 

11.25 The TEMPLA TE_DEPTH Pragma (C++ Only) 

The "template_depth" pragma provides a hard limit for the amount of nested template expansions allowed 
so that infinite expansion can be detected. 

The form of the "template_depth" pragma is as follows. 


♦pragma template_ depth [(] n [)] [;] 


where description: 

n is the depth of expansion. If the value of n is less than 2, if will default to 2. If n is not 

specified, a warning message will be issued and the default value for n will be 100. 

The following example of recursive template expansion illustrates why this pragma can be useful. 
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Example: 

♦pragma template_ depth(10); 

template <class T> 
struct S { 

S<T*> x; 

} ; 


S<char> v; 


11.26 The WARNING Pragma (C++ Only) 

The "warning" pragma sets the level of warning messages. The form of the "warning" pragma is as 
follows. 


♦pragma warning msg_num level [;] 


where description: 

msg_num is the number of the warning message. This number corresponds to the number issued by 
the compiler and can be found in the appendix entitled "Open Watcom C++ Diagnostic 
Messages" on page 337. If msg_ num is the level of all warning messages is changed 
to the specified level. Make sure to strip all leading zeroes from the message number (to 
avoid interpretation as an octal constant). 

level is a number from 0 to 9 and represents the level of the warning message. When a value of 

zero is specified, the warning becomes an error. 

11.27 Auxiliary Pragmas 

The following sections describe the capabilities provided by auxiliary pragmas. 

11.27.1 Specifying Symbol Attributes 

Auxiliary pragmas are used to describe attributes that affect code generation. Initially, the compiler defines 
a default set of attributes. Each auxiliary pragma refers to one of the following. 

1. a symbol (such as a variable or function) 

2. a type definition that resolves to a function type 

3. the default set of attributes defined by the compiler 

When an auxiliary pragma refers to a particular symbol, a copy of the current set of default attributes is 
made and merged with the attributes specified in the auxiliary pragma. The resulting attributes are assigned 
to the specified symbol and can only be changed by another auxiliary pragma that refers to the same 
symbol. 

An example of a type definition that resolves to a function type is the following. 
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typedef void (*func_type) (); 

When an auxiliary pragma refers to a such a type definition, a copy of the current set of default attributes is 
made and merged with the attributes specified in the auxiliary pragma. The resulting attributes are assigned 
to each function whose type matches the specified type definition. 

When "default" is specified instead of a symbol name, the attributes specified by the auxiliary pragma 
change the default set of attributes. The resulting attributes are used by all symbols that have not been 
specifically referenced by a previous auxiliary pragma. 

Note that all auxiliary pragmas are processed before code generation begins. Consider the following 
example. 

code in which symbol x is referenced 
♦pragma aux y <attrs_ 1>; 
code in which symbol y is referenced 
code in which symbol z is referenced 
♦pragma aux default <attrs_ 2>; 

♦pragma aux x <attrs_ 3>; 

Auxiliary attributes are assigned to x, y and z in the following way. 

1. Symbol x is assigned the initial default attributes merged with the attributes specified by 
<attrs_ 2> and<attrs_ 3> . 

2. Symbol y is assigned the initial default attributes merged with the attributes specified by 
<attrs_ 1>. 

3. Symbol z is assigned the initial default attributes merged with the attributes specified by 
<attrs_ 2>. 


11.27.2 Alias Names 

When a symbol referred to by an auxiliary pragma includes an alias name, the attributes of the alias name 
are also assumed by the specified symbol. 

There are two methods of specifying alias information. In the first method, the symbol assumes only the 
attributes of the alias name; no additional attributes can be specified. The second method is more general 
since it is possible to specify an alias name as well as additional auxiliary information. In this case, the 
symbol assumes the attributes of the alias name as well as the attributes specified by the additional auxiliary 
information. 

The simple form of the auxiliary pragma used to specify an alias is as follows. 


♦pragma aux ( sym, [far 16] alias ) [;] 
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where description: 

sym is any valid C/C++ identifier. 

alias is the alias name and is any valid C/C++ identifier. 

The f ar 16 attribute should only be used on systems that permit the calling of 16-bit code from 32-bit 
code. Currently, the only supported operating system that allows this is 32-bit OS/2. If you have any 
libraries of functions or APIs that are only available as 16-bit code and you wish to access these functions 
and APIs from 32-bit code, you must specify the f ar 16 attribute. If the f ar 16 attribute is specified, the 
compiler will generate special code which allows the 16-bit code to be called from 32-bit code. Note that a 
f ar 16 function must be a function whose attributes are those specified by one of the alias names 
_cdecl or_ _ pascal. These alias names will be described in a later section. 

Consider the following example. 

#pragma aux push_ args parm [ ] ; 

#pragma aux ( rtn, push_ args ) ; 

The routine rtn assumes the attributes of the alias name push_ args which specifies that the arguments 
to rtn are passed on the stack. 

Let us look at an example in which the symbol is a type definition. 

typedef void (func_type) (int) ; 

#pragma aux push_ args parm [ ] ; 

#pragma aux ( func_ type, push_ args ) ; 

extern func_ type rtnl; 
extern func_ type rtn2; 

The first auxiliary pragma defines an alias name called push_ args that specifies the mechanism to be 
used to pass arguments. The mechanism is to pass all arguments on the stack. The second auxiliary 
pragma associates the attributes specified in the first pragma with the type definition f unc_ type . Since 
rtnl and rtn2 are of type func_ type, arguments to either of those functions will be passed on the 
stack. 

The general form of an auxiliary pragma that can be used to specify an alias is as follows. 


♦pragma aux ( alias ) sym aux_attrs [;] 


where description: 

alias is the alias name and is any valid C/C++ identifier. 

sym is any valid C/C++ identifier. 

aux_attrs are attributes that can be specified with the auxiliary pragma. 
Consider the following example. 
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♦pragma aux HIGH_ C "*" \ 

parm caller [] \ 

value no8087 \ 

modify [eax ecx edx fs gs]; 

♦pragma aux (HIGH_ C) rtnl; 

♦pragma aux (HIGH_ C) rtn2; 

♦pragma aux (HIGH_ C) rtn3; 

The routines rtnl, rtn2 and rtn3 assume the same attributes as the alias name HIGH_ C which defines 
the calling convention used by the MetaWare High C compiler. Note that register ES must also be 
specified in the "modify" register set when using a memory model that is not a small data model. 

Whenever calls are made to rtnl, rtn2 and rtn3, the MetaWare High C calling convention will be 
used. 

Note that if the attributes of HIGH_ C change, only one pragma needs to be changed. If we had not used an 
alias name and specified the attributes in each of the three pragmas for rtnl, rtn2 and rtn3, we would 
have to change all three pragmas. This approach also reduces the amount of memory required by the 
compiler to process the source file. 

WARNING! The alias name HIGH_ C is just another symbol. IfHIGH_ C appeared in your source 
code, it would assume the attributes specified in the pragma for HIGH_ C . 


11.27.3 Predefined Aliases 

A number of symbols are predefined by the compiler with a set of attributes that describe a particular 

calling convention. These symbols can be used as aliases. The following is a list of these symbols. 

_ cdecl _cdecl ocdecl defines the calling convention used by Microsoft compilers. 

fastcall _f astcall of astcall defines the calling convention used by Microsoft compilers. 

fortran _fortran ofortran defines the calling convention used by Open Watcom 

FORTRAN compilers. 

_ pascal _pascal opascal defines the calling convention used by OS/2 1.x and Windows 3.x 

API functions. 

_ stdcall _stdcall ostdcall defines a special calling convention used by the Win32 API 

functions. 

_ syscall _syscall osyscall defines the calling convention used by the 32-bit OS/2 API 

functions. 

_ system _system osystem are identical to_syscall. 

_ watcall _watcall owatcall defines the calling convention used by Open Watcom 

compilers. 

The following describes the attributes of the above alias names. 
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11.27.3.1 Predefined "_cdecl" Alias 

♦pragma aux_cdecl *" \ 

parm caller [] \ 

value struct float struct routine [eax] \ 
modify [eax ecx edx] 


Notes: 

1. All symbols are preceded by an underscore character. 

2. Arguments are pushed on the stack from right to left. That is, the last argument is pushed first. 
The calling routine will remove the arguments from the stack. 

3. Floating-point values are returned in the same way as structures. When a structure is returned, 
the called routine allocates space for the return value and returns a pointer to the return value in 
register EAX. 

4. Registers EAX, ECX and EDX are not saved and restored when a call is made. 

11.27.3.2 Predefined "_pascal" Alias 

♦pragma aux_pascal " A " \ 

parm reverse routine [] \ 

value struct float struct caller [] \ 

modify [eax ebx ecx edx] 


Notes: 

1. All symbols are mapped to upper case. 

2. Arguments are pushed on the stack in reverse order. That is, the first argument is pushed first, 
the second argument is pushed next, and so on. The routine being called will remove the 
arguments from the stack. 

3. Floating-point values are returned in the same way as structures. When a structure is returned, 
the caller allocates space on the stack. The address of the allocated space will be pushed on the 
stack immediately before the call instruction. Upon returning from the call, register EAX will 
contain address of the space allocated for the return value. 

4. Registers EAX, EBX, ECX and EDX are not saved and restored when a call is made. 

11.27.3.3 Predefined "_stdcall" Alias 

♦pragma aux_stdcall *@nnn" \ 

parm routine [] \ 

value struct struct caller [] \ 

modify [eax ecx edx] 
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Notes: 

1. All symbols are preceded by an underscore character. 

2. All C symbols (extern "C" symbols in C++) are suffixed by "@nnn" where "nnn" is the sum of 
the argument sizes (each size is rounded up to a multiple of 4 bytes so that char and short are size 
4). When the argument list contains the "@nnn" suffix is omitted. 

3. Arguments are pushed on the stack from right to left. That is, the last argument is pushed first. 
The called routine will remove the arguments from the stack. 

4. When a structure is returned, the caller allocates space on the stack. The address of the allocated 
space will be pushed on the stack immediately before the call instruction. Upon returning from 
the call, register EAX will contain address of the space allocated for the return value. 
Floating-point values are returned in 80x87 register ST(0). 

5. Registers EAX, ECX and EDX are not saved and restored when a call is made. 

11.27.3.4 Predefined "_syscall" Alias 

♦pragma aux_syscall \ 

parm caller [] \ 

value struct struct caller [] \ 

modify [eax ecx edx] 


Notes: 

1. Symbols names are not modified, that is, they are not adorned with leading or trailing 
underscores. 

2. Arguments are pushed on the stack from right to left. That is, the last argument is pushed first. 
The calling routine will remove the arguments from the stack. 

3. When a structure is returned, the caller allocates space on the stack. The address of the allocated 
space will be pushed on the stack immediately before the call instruction. Upon returning from 
the call, register EAX will contain address of the space allocated for the return value. 
Floating-point values are returned in 80x87 register ST(0). 

4. Registers EAX, ECX and EDX are not saved and restored when a call is made. 

11.27.3.5 Predefined "_watcall" Alias (register calling convention) 

♦pragma aux _watcall " \ 

parm routine [eax ebx ecx edx] \ 
value struct caller 


Notes: 

1. Symbol names are followed by an underscore character. 

2. Arguments are processed from left to right. The leftmost arguments are passed in registers and 
the rightmost arguments are passed on the stack (if the registers used for argument passing have 
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been exhausted). Arguments that are passed on the stack are pushed from right to left. The 
calling routine will remove the arguments if any were pushed on the stack. 

3. When a structure is returned, the caller allocates space on the stack. The address of the allocated 
space is put into ESI register. The called routine then places the return value there. Upon 
returning from the call, register EAX will contain address of the space allocated for the return 
value. 

4. Floating-point values are returned using 80x86 registers ("fpc" option) or using 80x87 
floating-point registers ("fpi" or "fpi87" option). 

5. All registers must be preserved by the called routine. 

11.27.3.6 Predefined "_watcall" Alias (stack calling convention) 

♦pragma aux _watcall \ 

parm caller [] \ 

value no8087 struct caller \ 

modify [eax ecx edx 8087] 


Notes: 

1. All symbols appear in object form as they do in source form. 

2. Arguments are pushed on the stack from right to left. That is, the last argument is pushed first. 
The calling routine will remove the arguments from the stack. 

3. When a structure is returned, the caller allocates space on the stack. The address of the allocated 
space will be pushed on the stack immediately before the call instruction. Upon returning from 
the call, register EAX will contain address of the space allocated for the return value. 

4. Floating-point values are returned only using 80x86 registers. 

5. Registers EAX, ECX and EDX are not preserved by the called routine. 

6. Any local variables that are located in the 80x87 cache are not preserved by the called routine. 

11.27.4 Alternate Names for Symbols 

The following form of the auxiliary pragma can be used to describe the mapping of a symbol from its 
source form to its object form. 


♦pragma aux sym obj_name [;] 


where description: 

sym is any valid C/C++ identifier. 

objjiame is any character string enclosed in double quotes. 

When specifying ob j_ name, some characters have a special meaning: 
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where description: 

* is unmodified symbol name 

A is symbol name converted to uppercase 

/ is symbol name converted to lowercase 

# is a placeholder for "@nnn", where nnn is size of all function parameters on the stack; it is 
ignored for functions with variable argument lists, or for symbols that are not functions 

\ next character is treated as literal 

Several examples of source to object form symbol name translation follow: 

In the following example, the name "MyRtn" will be replaced by "MyRtn_" in the object file. 

♦pragma aux MyRtn 
This is the default for all function names. 

In the following example, the name "MyVar" will be replaced by "_MyVar" in the object file. 

♦pragma aux MyVar 
This is the default for all variable names. 

In the following example, the lower case version "myrtn" will be placed in the object file. 

♦pragma aux MyRtn 

In the following example, the upper case version "MYRTN" will be placed in the object file. 

♦pragma aux MyRtn " A "; 

In the following example, the name "MyRtn" will be replaced by "_MyRtn@nnn" in the object file, "nnn" 
represents the size of all function parameters. 

♦pragma aux MyRtn 

In the following example, the name "MyRtn" will be replaced by "_MyRtn#" in the object file. 

♦pragma aux MyRtn 

The default mapping for all symbols can also be changed as illustrated by the following example, 
♦pragma aux default *_ 

The above auxiliary pragma specifies that all names will be prefixed and suffixed by an underscore 
character 
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11.27.5 Describing Calling Information 

The following form of the auxiliary pragma can be used to describe the way a function is to be called. 


♦pragma 

aux sym far 

[;] 

or 



♦pragma 

aux sym near 

[;] 

or 



♦pragma 

aux sym = in_ 

line [;] 

in line ::= 

{ const 1 (seg id) 

1 (offset id) 1 (reloff id) 


1 "asm" } 



where description: 

sym is a function name. 

const is a valid C/C++ integer constant. 

id is any valid C/C++ identifier. 

seg specifies the segment of the symbol id. 

offset specifies the offset of the symbol id. 

reloff specifies the relative offset of the symbol id for near control transfers. 

asm is an assembly language instruction or directive. 

In the following example. Open Watcom C/C++ will generate a far call to the function myrtn. 

♦pragma aux myrtn far; 

Note that this overrides the calling sequence that would normally be generated for a particular memory 
model. In other words, a far call will be generated even if you are compiling for a memory model with a 
small code model. 

In the following example. Open Watcom C/C++ will generate a near call to the function myrtn . 
♦pragma aux myrtn near; 

Note that this overrides the calling sequence that would normally be generated for a particular memory 
model. In other words, a near call will be generated even if you are compiling for a memory model with a 
big code model. 

In the following DOS example. Open Watcom C/C++ will generate the sequence of bytes following the "=" 
character in the auxiliary pragma whenever a call to mode 4 is encountered, mode4 is called an in-line 
function. 
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void mode4(void) ; 


♦pragma aux mode4 = 
0xb4 0x00 
OxbO 0x04 
Oxcd 0x10 
modify [ AH AL 


\ 


/* 

mov 

AH, 0 

*/ 

\ 

/* 

mov 

AL, 4 

*/ 

\ 

/* 

int 

10H 

*/ 

\ 


] ; 


The sequence in the above DOS example represents the following lines of assembly language instructions. 


mov 

AH, 0 

; select function "set mode" 

mov 

AL, 4 

; specify mode (mode 4) 

int 

10H 

; BIOS video call 


The above example demonstrates how to generate BIOS function calls in-line without writing an assembly 
language function and calling it from your C/C++ program. The C prototype for the function mode4 is not 
necessary but is included so that we can take advantage of the argument type checking provided by Open 
Watcom C/C++. 

The following DOS example is equivalent to the above example but mnemonics for the assembly language 
instructions are used instead of the binary encoding of the assembly language instructions. 

void mode4(void); 

♦pragma aux mode4 = \ 

"mov AH,0", \ 

"mov AL,4", \ 

"int 10H" \ 

modify [ AH AL ]; 

A sequence of in-line assembly language instructions may contain symbolic references. In the following 
example, a near call to the function myalias is made whenever myrtn is called. 

extern void myalias(void); 
void myrtn(void) ; 

♦pragma aux myrtn = \ 

0xe8 reloff myalias /* near call */; 

In the following example, a far call to the function myalias is made whenever myrtn is called. 

extern void myalias(void) ; 
void myrtn(void); 

♦pragma aux myrtn = \ 

0x9a offset myalias seg myalias /* far call */; 

11.27.5.1 Loading Data Segment Register 

An application may have been compiled so that the segment register DS does not contain the segment 
address of the default data segment (group "DGROUP"). This is usually the case if you are using a large 
data memory model. Suppose you wish to call a function that assumes that the segment register DS 
contains the segment address of the default data segment. It would be very cumbersome if you were forced 
to compile your application so that the segment register DS contained the default data segment (a small data 
memory model). 

The following form of the auxiliary pragma will cause the segment register DS to be loaded with the 
segment address of the default data segment before calling the specified function. 
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#pragma aux sym parm loadds [;] 

where description: 

sym is a function name. 

Alternatively, the following form of the auxiliary pragma will cause the segment register DS to be loaded 
with the segment address of the default data segment as part of the prologue sequence for the specified 
function. 

♦pragma aux sym loadds [;] 

where description: 

sym is a function name. 

11.27.5.2 Defining Exported Symbols in Dynamic Link Libraries 

An exported symbol in a dynamic link library is a symbol that can be referenced by an application that is 
linked with that dynamic link library. Normally, symbols in dynamic link libraries are exported using the 
Open Watcom Linker "EXPORT" directive. An alternative method is to use the following form of the 
auxiliary pragma. 

♦pragma aux sym export [;] 

where description: 

sym is a function name. 

11.27.5.3 Forcing a Stack Frame 

Normally, a function contains a stack frame if arguments are passed on the stack or an automatic variable is 
allocated on the stack. No stack frame will be generated if the above conditions are not satisfied. The 
following form of the auxiliary pragma will force a stack frame to be generated under any circumstance. 

♦pragma aux sym frame [;] 

where description: 

sym is a function name. 
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11.27.6 Describing Argument Information 

Using auxiliary pragmas, you can describe the calling convention that Open Watcom C/C++ is to use for 
calling functions. This is particularly useful when interfacing to functions that have been compiled by 
other compilers or functions written in other programming languages. 

The general form of an auxiliary pragma that describes argument passing is the following. 


♦pragma aux sym parm { pop_info I reverse I {reg_set} } [;] 
pop_info ::= caller I routine 


where description: 

sym is a function name. 

reg_set is called a register set. The register sets specify the registers that are to be used for 

argument passing. A register set is a list of registers separated by spaces and enclosed in 
square brackets. 

11.27.6.1 Passing Arguments in Registers 

The following form of the auxiliary pragma can be used to specify the registers that are to be used to pass 
arguments to a particular function. 


♦pragma aux sym parm {reg_set} [;] 


where description: 

sym is a function name. 

reg_set is called a register set. The register sets specify the registers that are to be used for 

argument passing. A register set is a list of registers separated by spaces and enclosed in 
square brackets. 

Register sets establish a priority for register allocation during argument list processing. Register sets are 
processed from left to right. However, within a register set, registers are chosen in any order. Once all 
register sets have been processed, any remaining arguments are pushed on the stack. 

Note that regardless of the register sets specified, only certain combinations of registers will be selected for 
arguments of a particular type. 

Note that arguments of type float and double are always pushed on the stack when the "fpi" or "fpi87" 
option is used. 
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double Arguments of type double can only be passed in one of the following register pairs: 

EDX:EAX, ECX:EBX, ECX:EAX, ECX:ESI, EDX:EBX, EDEEAX, ECX:EDI, EDX:ESI, 
EDEEBX, ESEEAX, ECX:EDX, EDX:EDE EDEESI, ESEEBX or EBX:EAX. For 
example, if the following register set was specified for a routine having an argument of 
type double, 

[EBP EBX] 

the argument would be pushed on the stack since a valid register combination for 8-byte 
arguments is not contained in the register set. Note that this method for passing arguments 
of type double is supported only when the "fpc" option is used. Note that this argument 
passing method does not include the passing of 8-byte structures. 

far pointer A far pointer can only be passed in one of the following register pairs: DX:EAX, CX:EBX, 

CX:EAX, CX:ESI, DX:EBX, DEEAX, CX:EDI, DX:ESI, DEEBX, SEEAX, CX:EDX, 
DX:EDI, DEESI, SEEBX, BX:EAX, FS:ECX, FS:EDX, FS:EDI, FS:ESI, FS:EBX, 
FS:EAX, GS:ECX, GS:EDX, GS:EDI, GS:ESI, GS:EBX, GS:EAX, DS:ECX, DS:EDX, 
DS:ED1, DS:ESI, DS:EBX, DS:EAX, ES:ECX, ES:EDX, ES:EDI, ES:ESI, ES:EBX or 
ES:EAX. For example, if a far pointer is passed to a function with the following register 
set. 


[ES EBP] 

the argument would be pushed on the stack since a valid register combination for a far 
pointer is not contained in the register set. 

int The only registers that will be assigned to 4-byte arguments (e.g., arguments of type int) 

are: EAX, EBX, ECX, EDX, ESI and EDI. For example, if the following register set was 
specified for a routine with one argument of type int, 

[EBP] 

the argument would be pushed on the stack since a valid register combination for 4-byte 
arguments is not contained in the register set. Note that this argument passing method 
includes 4-byte structures. Note that this argument passing method also includes arguments 
of type float but only when the "fpc" option is used. 

char, short int Arguments whose size is 1 byte or 2 bytes (e.g., arguments of type char and short int as 
well as 2-byte structures) are promoted to 4 bytes and are then assigned registers as if they 
were 4-byte arguments. 

others Arguments that do not fall into one of the above categories cannot be passed in registers 

and are pushed on the stack. Once an argument has been assigned a position on the stack, 
all remaining arguments will be assigned a position on the stack even if all register sets 
have not yet been exhausted. 

Notes: 

1. The default register set is [EAX EBX ECX EDX]. 

2. Specifying registers AH and AL is equivalent to specifying register AX. Specifying registers 
DH and DL is equivalent to specifying register DX. Specifying registers CH and CL is 
equivalent to specifying register CX. Specifying registers BH and BL is equivalent to specifying 
register BX. Specifying register EAX implies that register AX has been specified. Specifying 
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register EBX implies that register BX has been specified. Specifying register ECX implies that 
register CX has been specified. Specifying register EDX implies that register DX has been 
specified. Specifying register EDI implies that register DI has been specified. Specifying 
register ESI implies that register SI has been specified. Specifying register EBP implies that 
register BP has been specified. Specifying register ESP implies that register SP has been 
specified. 

3. If you are compiling for a memory model with a small data model, or the "zdp" compiler option 
is specified, any register combination containing register DS becomes illegal. In a small data 
model, segment register DS must remain unchanged as it points to the program’s data segment. 
Note that the "zdf" compiler option can be used to specify that register DS does not contain that 
segment address of the program’s data segment. In this case, register combinations containing 
register DS are legal. 

4. If you are compiling for the flat memory model, any register combination containing DS or ES 
becomes illegal. In a flat memory model, code and data reside in the same segment. Segment 
registers DS and ES point to this segment and must remain unchanged. 

Consider the following example. 

♦pragma aux myrtn parm [eax ebx ecx edx] [ebp esi] ; 

Suppose myrtn is a routine with 3 arguments each of type double. 

1. The first argument will be passed in the register pair EDX:EAX. 

2. The second argument will be passed in the register pair ECX:EBX. 

3. The third argument will be pushed on the stack since EBP:ESI is not a valid register pair for 
arguments of type double. 

It is possible for registers from the second register set to be used before registers from the first register set 
are used. Consider the following example. 

♦pragma aux myrtn parm [eax ebx ecx edx] [esi edi]; 

Suppose myrtn is a routine with 3 arguments, the first of type int and the second and third of type double. 

1. The first argument will be passed in the register EAX. 

2. The second argument will be passed in the register pair ECX:EBX. 

3. The third argument will be passed in the register set EDEESI. 

Note that registers are no longer selected from a register set after registers are selected from subsequent 
register sets, even if all registers from the original register set have not been exhausted. 

An empty register set is permitted. All subsequent register sets appearing after an empty register set are 
ignored; all remaining arguments are pushed on the stack. 

Notes: 

1. If a single empty register set is specified, all arguments are passed on the stack. 

2. If no register set is specified, the default register set [EAX EBX ECX EDX] is used. 
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11.27.6.2 Forcing Arguments into Specific Registers 

It is possible to force arguments into specific registers. Suppose you have a function, say "mycopy", that 
copies data. The first argument is the source, the second argument is the destination, and the third 
argument is the length to copy. If we want the first argument to be passed in the register ESI, the second 
argument to be passed in register EDI and the third argument to be passed in register ECX, the following 
auxiliary pragma can be used. 

void mycopy( char near *, char *, int ); 

♦pragma aux mycopy parm [ESI] [EDI] [ECX]; 

Note that you must be aware of the size of the arguments to ensure that the arguments get passed in the 
appropriate registers. 

11.27.6.3 Passing Arguments to In-Line Functions 

For functions whose code is generated by Open Watcom C/C++ and whose argument list is described by an 
auxiliary pragma. Open Watcom C/C++ has some freedom in choosing how arguments are assigned to 
registers. Since the code for in-line functions is specified by the programmer, the description of the 
argument list must be very explicit. To achieve this. Open Watcom C/C++ assumes that each register set 
corresponds to an argument. Consider the following DOS example of an in-line function called 
scrollactivepgup. 

void scrollactivepgup(char,char,char,char, char, char) ; 

♦pragma aux scrollactivepgup = \ 

"mov AH,6" \ 

"int lOh" \ 

parm [ch] [cl] [dh] [dl] [al] [bh] \ 
modify [ah]; 

The BIOS video call to scroll the active page up requires the following arguments. 

1. The row and column of the upper left corner of the scroll window is passed in registers CH and 
CL respectively. 

2. The row and column of the lower right corner of the scroll window is passed in registers DH and 
DL respectively. 

3. The number of lines blanked at the bottom of the window is passed in register AL. 

4. The attribute to be used on the blank lines is passed in register BH. 

When passing arguments. Open Watcom C/C++ will convert the argument so that it fits in the register(s) 
specified in the register set for that argument. For example, in the above example, if the first argument to 
scrollactivepgup was called with an argument whose type was int, it would first be converted to 
char before assigning it to register CH. Similarly, if an in-line function required its argument in register 
EAX and the argument was of type short int, the argument would be converted to long int before 
assigning it to register EAX. 

In general. Open Watcom C/C++ assigns the following types to register sets. 

1. A register set consisting of a single 8-bit register (1 byte) is assigned a type of unsigned char. 
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2. A register set consisting of a single 16-bit register (2 bytes) is assigned a type of unsigned short 
int. 

3. A register set consisting of a single 32-bit register (4 bytes) is assigned a type of unsigned long 
int. 

4. A register set consisting of two 32-bit registers (8 bytes) is assigned a type of double. 

11.27.6.4 Removing Arguments from the Stack 

The following form of the auxiliary pragma specifies who removes from the stack arguments that were 
pushed on the stack. 


♦pragma aux sym parm (caller I routine) [;] 


where description: 

sym is a function name. 

"caller" specifies that the caller will pop the arguments from the stack; "routine" specifies that the called 
routine will pop the arguments from the stack. If "caller" or "routine" is omitted, "routine" is assumed 
unless the default has been changed in a previous auxiliary pragma, in which case the new default is 
assumed. 

11.27.6.5 Passing Arguments in Reverse Order 

The following form of the auxiliary pragma specifies that arguments are passed in the reverse order. 


♦pragma aux sym parm reverse [;] 


where description: 

sym is a function name. 

Normally, arguments are processed from left to right. The leftmost arguments are passed in registers and 
the rightmost arguments are passed on the stack (if the registers used for argument passing have been 
exhausted). Arguments that are passed on the stack are pushed from right to left. 

When arguments are reversed, the rightmost arguments are passed in registers and the leftmost arguments 
are passed on the stack (if the registers used for argument passing have been exhausted). Arguments that 
are passed on the stack are pushed from left to right. 

Reversing arguments is most useful for functions that require arguments to be passed on the stack in an 
order opposite from the default. The following auxiliary pragma demonstrates such a function. 

♦pragma aux rtn parm reverse []; 
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11.27.7 Describing Function Return Information 

Using auxiliary pragmas, you can describe the way functions are to return values. This is particularly 
useful when interfacing to functions that have been compiled by other compilers or functions written in 
other programming languages. 

The general form of an auxiliary pragma that describes the way a function returns its value is the following. 


♦pragma aux sym value {no8087 I reg_set I struct_info} [;] 
struct_info ::= struct {float I struct I (routine I caller) I reg_set} 


where description: 

sym is a function name. 

reg_set is called a register set. The register sets specify the registers that are to be used for 

argument passing. A register set is a list of registers separated by spaces and enclosed in 
square brackets. 

11.27.7.1 Returning Function Values in Registers 

The following form of the auxiliary pragma can be used to specify the registers that are to be used to return 
a function's value. 


♦pragma aux sym value reg_set [;] 


where 

description: 

sym 

is a function name. 

reg_set 

is a register set. 


Note that the method described below for returning values of type float or double is supported only when 
the "fpc" option is used. 

Depending on the type of the return value, only certain registers are allowed in reg_set. 

1- byte For 1-byte return values, only the following registers are allowed: AL, AH, DL, DH, BL, 

BH, CL or CH. If no register set is specified, register AL will be used. 

2- byte For 2-byte return values, only the following registers are allowed: AX, DX, BX, CX, SI or 

DI. If no register set is specified, register AX will be used. 

4-byte For 4-byte return values (including near pointers), only the following register are allowed: 

EAX, EDX, EBX, ECX, ESI or EDI. If no register set is specified, register EAX will be 
used. This form of the auxiliary pragma is legal for functions of type float when using the 
"fpc" option only. 
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far pointer For functions that return far pointers, the following register pairs are allowed: DX:EAX, 
CX:EBX, CX:EAX, CX:ESI, DX:EBX, DLEAX, CX:EDI, DX:ESI, DI:EBX, SFEAX, 
CX:EDX, DX:ED1, DEES I, SFEBX, BX:EAX, FS:ECX, FS:EDX, FS:EDI, FS:ESI, 
FS:EBX, FS:EAX, GS:ECX, GS:EDX, GS:ED1, GS:ESI, GS:EBX, GS:EAX, DS:ECX, 
DS:EDX, DS:EDI, DS:ESI, DS:EBX, DS:EAX, ES:ECX, ES:EDX, ES:EDI, ES:ESI, 
ES:EBX or ES:EAX. If no register set is specified, the registers DX:EAX will be used. 

8-byte For 8-byte return values (including functions of type double), only the following register 

pairs are allowed: EDX:EAX, ECX:EBX, ECX:EAX, ECX:ESI, EDX:EBX, EDFEAX, 
ECX:EDI, EDX:ESI, EDFEBX, ESEEAX, ECX:EDX, EDX:EDI, EDEESI, ESEEBX or 
EBX:EAX. If no register set is specified, the registers EDX:EAX will be used. This form 
of the auxiliary pragma is legal for functions of type double when using the "fpc" option 
only. 

Notes: 

1. An empty register set is not allowed. 

2. If you are compiling for a memory model which has a small data model, any of the above 
register combinations containing register DS becomes illegal. In a small data model, segment 
register DS must remain unchanged as it points to the program’s data segment. 

3. If you are compiling for the flat memory model, any register combination containing DS or ES 
becomes illegal. In a flat memory model, code and data reside in the same segment. Segment 
registers DS and ES point to this segment and must remain unchanged. 

11.27.7.2 Returning Structures 

Typically, structures are not returned in registers. Instead, the caller allocates space on the stack for the 
return value and sets register ESI to point to it. The called routine then places the return value at the 
location pointed to by register ESI. 

The following form of the auxiliary pragma can be used to specify the register that is to be used to point to 
the return value. 


♦pragma aux sym value struct (callerlroutine) reg_set [;] 


where 

description: 

sym 

is a function name. 

reg_set 

is a register set. 


"caller" specifies that the caller will allocate memory for the return value. The address of the memory 
allocated for the return value is placed in the register specified in the register set by the caller before the 
function is called. If an empty register set is specified, the address of the memory allocated for the return 
value will be pushed on the stack immediately before the call and will be returned in register EAX by the 
called routine. 
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"routine" specifies that the called routine will allocate memory for the return value. Upon returning to the 
caller, the register specified in the register set will contain the address of the return value. An empty 
register set is not allowed. 

Only the following registers are allowed in the register set: EAX, EDX, EBX, ECX, ESI or EDI. Note that 
in a big data model, the address in the return register is assumed to be in the segment specified by the value 
in the SS segment register. 

If the size of the structure being returned is 1, 2 or 4 bytes, it will be returned in registers. The return 
register will be selected from the register set in the following way. 

1. A 1-byte structure will be returned in one of the following registers: AL, AH, DL, DH, BL, BH, 
CL or CH. If no register set is specified, register AL will be used. 

2. A 2-byte structure will be returned in one of the following registers: AX, DX, BX, CX, SI or DI. 
If no register set is specified, register AX will be used. 

3. A 4-byte structure will be returned in one of the following registers: EAX, EDX, EBX, ECX, 
ESI or EDI. If no register set is specified, register EAX will be used. 

The following form of the auxiliary pragma can be used to specify that structures whose size is 1, 2 or 4 
bytes are not to be returned in registers. Instead, the caller will allocate space on the stack for the structure 
return value and point register ESI to it. 


♦pragma aux sym value struct struct [;] 


where description: 

sym is a function name. 

11.27.7.3 Returning Floating-Point Data 

There are a few ways available for specifying how the value for a function whose type is float or double is 
to be returned. 

The following form of the auxiliary pragma can be used to specify that function return values whose type is 
float or double are not to be returned in registers. Instead, the caller will allocate space on the stack for the 
return value and point register ESI to it. 


♦pragma aux sym value struct float [;] 


where description: 

sym is a function name. 

In other words, floating-point values are to be returned in the same way structures are returned. 

The following form of the auxiliary pragma can be used to specify that function return values whose type is 
float or double are not to be returned in 80x87 registers when compiling with the "fpi" or "fpi87" option. 
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Instead, the value will be returned in 80x86 registers. This is the default behaviour for the "fpc" option. 
Function return values whose type is float will be returned in register EAX. Function return values whose 
type is double will be returned in registers EDX:EAX. This is the default method for the "fpc" option. 


♦pragma aux sym value no8087 [;] 


where description: 

sym is a function name. 

The following form of the auxiliary pragma can be used to specify that function return values whose type is 
float or double are to be returned in ST(0) when compiling with the "fpi" or "fpi87" option. This form of 
the auxiliary pragma is not legal for the "fpc" option. 


♦pragma aux sym value [8087] [;] 


where description: 

sym is a function name. 

11.27.8 A Function that Never Returns 

The following form of the auxiliary pragma can be used to describe a function that does not return to the 
caller. 

♦pragma aux sym aborts [;] 


where description: 

sym is a function name. 

Consider the following example. 

♦pragma aux exitrtn aborts; 
extern void exitrtn(void); 

void rtn() 

{ 

exitrtn() ; 

} 

exitrtn is defined to be a function that does not return. For example, it may call exit to return to the 
system. In this case. Open Watcom C/C++ generates a "jmp" instruction instead of a "call" instruction to 
invoke exitrtn. 
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11.27.9 Describing How Functions Use Memory 

The following form of the auxiliary pragma can be used to describe a function that does not modify any 
memory (i.e., global or static variables) that is used directly or indirectly by the caller. 


♦pragma aux sym modify nomemory [;] 


where description: 

sym is a function name. 

Consider the following example. 

♦pragma off (check_ stack); 

extern void myrtn(void); 

int i = { 1033 }; 

extern Rtn() { 

while( i < 10000 ) { 

i += 383; 

} 

myrtn(); 
i += 13143; 


To compile the above program, "rtn.c", we issue the following command. 

C>wcc rtn -oai -dl 
C>wpp rtn -oai -dl 
C>wcc386 rtn -oai -dl 
C>wpp386 rtn -oai -dl 

For illustrative purposes, we omit loop optimizations from the list of code optimizations that we want the 
compiler to perform. The "dl" compiler option is specified so that the object file produced by Open 
Watcom C/C++ contains source line information. 

We can generate a file containing a disassembly of rtn. ob j by issuing the following command. 
C>wdis rtn -1 -s -r 

The "s" option is specified so that the listing file produced by the Open Watcom Disassembler contains 
source lines taken from rtn. c . The listing file rtn. 1st appears as follows. 

Module: rtn.c 

Group: 'DGROUP' CONST,_ DATA 

Segment: TEXT' BYTE USE32 00000036 bytes 

#pragma off (check_ stack) ; 

extern void myrtn(void); 

int i = { 1033 }; 
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extern Rtn() { 


0000 

52 






Rtn_ 

push 

EDX 

0001 

8b 

15 

00 

00 

00 

00 


mov 

EDX, _ i 

while( 

’ i 

< 

10000 ) 

{ 




0007 

81 

fa 

10 

27 

00 

00 

LI 

cmp 

EDX,00002710H 

OOOd 

7d 

08 






jge 

L2 


i 

+= 

383; 






} 

OOOf 

81 

c2 

7 f 

01 

00 

00 


add 

EDX,0000017fH 

0015 

eb 

fO 






jmp 

LI 

myrtn (); 








0017 

89 

15 

00 

00 

00 

00 

L2 

mov 

_ i,EDX 

OOld 

e8 

00 

00 

00 

00 



call 

myrtn_ 

0022 

8b 

15 

00 

00 

00 

00 


mov 

EDX, _ i 

i 

+= 13143; 







0028 

81 

c2 

57 

33 

00 

00 


add 

EDX,00003357H 

002e 

89 

15 

00 

00 

00 

00 


mov 

_ i,EDX 


0034 

5a 

pop 

EDX 

0035 

c3 

ret 



No disassembly errors 


Segment: DATA' WORD USE32 00000004 bytes 

0000 09 04 00 00 _ i 


No disassembly errors 


Let us add the following auxiliary pragma to the source file, 
♦pragma aux myrtn modify nomemory; 


If we compile the source file with the above pragma and disassemble the object file using the Open 
Watcom Disassembler, we get the following listing file. 


Module: rtn.c 

Group: 'DGROUP' CONST,_ DATA 

Segment: TEXT' BYTE USE32 00000030 bytes 

#pragma off (check_ stack) ; 

#pragma aux myrtn modify nomemory; 


extern void myrtn(void) ; 


int i = { 1033 }; 


xtern 

Rtn () 

{ 





0000 

52 



Rtn_ 

push 

EDX 

0001 

8b 15 

00 00 00 

00 


mov 

EDX, _ i 

while( i 

< 10000 ) 

{ 




0007 

81 fa 

10 27 00 

00 

LI 

cmp 

EDX,00002710H 

OOOd 

7d 08 




jge 

L2 


i += 

383; 





} 

OOOf 

81 c2 

7f 01 00 

00 


add 

EDX,0000017fH 

0015 

eb f 0 




jmp 

LI 
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myrtn (); 


0017 

89 

15 00 

00 

00 

00 L2 

mov 

_ i,EDX 

OOld 

e8 

00 00 

00 

00 


call 

myrtn_ 

i 

+= 

13143; 






0022 

81 

c2 57 

33 

00 

00 

add 

EDX,00003357H 

0028 

89 

15 00 

00 

00 

00 

mov 

_ i,EDX 


002e 

5a 

pop 

EDX 

002 f 

c3 

ret 



No disassembly errors 


Segment: DATA' WORD USE32 00000004 bytes 

0000 09 04 00 00 _ i 


No disassembly errors 


Notice that the value of i is in register EDX after completion of the "while" loop. After the call to 
myrtn, the value of i is not loaded from memory into a register to perform the final addition. The 
auxiliary pragma informs the compiler that myrtn does not modify any memory (i.e., global or static 
variables) that is used directly or indirectly by Rtn and hence register EDX contains the correct value of 

i . 

The preceding auxiliary pragma deals with routines that modify memory. Let us consider the case where 
routines reference memory. The following form of the auxiliary pragma can be used to describe a function 
that does not reference any memory (i.e., global or static variables) that is used directly or indirectly by the 
caller. 


♦pragma aux sym parm nomemory modify nomemory [;] 


where 

description: 

sym 

is a function name. 

Notes: 



1. You must specify both "parm nomemory" and "modify nomemory". 

Let us replace the auxiliary pragma in the above example with the following auxiliary pragma. 

♦pragma aux myrtn parm nomemory modify nomemory; 

If you now compile our source file and disassemble the object file using WDIS, the result is the following 
listing file. 

Module: rtn.c 

Group: 'DGROUP' CONST,_ DATA 

Segment: TEXT' BYTE USE32 0000002a bytes 

#pragma off (check_ stack) ; 

#pragma aux myrtn parm nomemory modify nomemory; 
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extern void myrtn(void); 
int i = { 1033 }; 
extern Rtn() { 


0000 

52 




Rtn_ 

push 

EDX 

0001 

8b 15 

00 00 

00 

00 


mov 

EDX, _ i 

while( i 

< 10000 ) 

{ 




0007 

81 fa 

10 27 

00 

00 

LI 

cmp 

EDX,00002710H 

OOOd 

7d 08 





jge 

L2 


i += 

383; 






} 

OOOf 

81 c2 

7 f 01 

00 

00 


add 

EDX,0000017fH 

0015 

eb f 0 





jmp 

LI 

myrtn (); 







0017 

e8 00 

00 00 

00 


L2 

call 

myrtn_ 

i 

+= 13143; 






001c 

81 c2 

57 33 

00 

00 


add 

EDX,00003357H 

0022 

89 15 

00 00 

00 

00 


mov 

_ i,EDX 

0028 

5a 





pop 

EDX 

0029 

c3 





ret 



No disassembly errors 


Segment: DATA' WORD USE32 00000004 bytes 

0000 09 04 00 00 _ i 

No disassembly errors 


Notice that after completion of the "while" loop we did not have to update i with the value in register EDX 
before calling myrtn . The auxiliary pragma informs the compiler that myrtn does not reference any 
memory (i.e., global or static variables) that is used directly or indirectly by myrtn so updating i was not 
necessary before calling myrtn. 

11.27.10 Describing the Registers Modified by a Function 

The following form of the auxiliary pragma can be used to describe the registers that a function will use 
without saving. 

#pragma aux sym modify [exact] reg_set [;] 


where 

description: 

sym 

is a function name. 

reg_set 

is a register set. 


Specifying a register set informs Open Watcom C/C++ that the registers belonging to the register set are 
modified by the function. That is, the value in a register before calling the function is different from its 
value after execution of the function. 
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Registers that are used to pass arguments are assumed to be modified and hence do not have to be saved 
and restored by the called function. Also, since the EAX register is frequently used to return a value, it is 
always assumed to be modified. If necessary, the caller will contain code to save and restore the contents 
of registers used to pass arguments. Note that saving and restoring the contents of these registers may not 
be necessary if the called function does not modify them. The following form of the auxiliary pragma can 
be used to describe exactly those registers that will be modified by the called function. 


♦pragma aux sym modify exact reg_set [;] 


where 

description: 

sym 

is a function name. 

reg_set 

is a register set. 


The above form of the auxiliary pragma tells Open Watcom C/C++ not to assume that the registers used to 
pass arguments will be modified by the called function. Instead, only the registers specified in the register 
set will be modified. This will prevent generation of the code which unnecessarily saves and restores the 
contents of the registers used to pass arguments. 

Also, any registers that are specified in the value register set are assumed to be unmodified unless 
explicitly listed in the exact register set. In the following example, the code generator will not generate 
code to save and restore the value of the stack pointer register since we have told it that "GetSP" does not 
modify any register whatsoever. 

Example: 

unsigned GetSP(void); 

#if defined(_ 386_) 

♦pragma aux GetSP = value [esp] modify exact []; 

♦ else 

♦pragma aux GetSP = value [sp] modify exact []; 

♦endif 


11.27.11 An Example 

As mentioned in an earlier section, the following pragma defines the calling convention for functions 
compiled by Meta Ware’s High C compiler. 

♦pragma aux HIGH_ C "*" \ 

parm caller [] \ 

value no8087 \ 

modify [eax ecx edx fs gs]; 

Note that register ES must also be specified in the "modify" register set when using a memory model with a 
non-small data model. Let us discuss this pragma in detail. 

specifies that all function and variable names appear in object form as they do in source 
form. 

parm caller [] specifies that all arguments are to be passed on the stack (an empty register set was 
specified) and the caller will remove the arguments from the stack. 
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value no8087 specifies that floating-point values are to be returned using 80x86 registers and not 80x87 
floating-point registers. 

modify [eax ecx edx fs gs] specifies that registers EAX, ECX, EDX, FS and GS are not preserved by the 
called routine. 

Note that the default method of returning integer values is used; 1-byte characters are returned in register 
AL, 2-byte integers are returned in register AX, and 4-byte integers are returned in register EAX. 

11.27.12 Auxiliary Pragmas and the 80x87 

This section deals with those aspects of auxiliary pragmas that are specific to the 80x87. The discussion in 
this chapter assumes that one of the "fpi" or "fpi87" options is used to compile functions. The following 
areas are affected by the use of these options. 

1. passing floating-point arguments to functions, 

2. returning floating-point values from functions and 

3. which 80x87 floating-point registers are allowed to be modified by the called routine. 

11.27.12.1 Using the 80x87 to Pass Arguments 

By default, floating-point arguments are passed on the 80x86 stack. The 80x86 registers are never used to 
pass floating-point arguments when a function is compiled with the "fpi" or "fpi87" option. However, they 
can be used to pass arguments whose type is not floating-point such as arguments of type "int". 

The following form of the auxiliary pragma can be used to describe the registers that are to be used to pass 
arguments to functions. 


♦pragma aux sym parm {reg_set} [;] 


where description: 

sym is a function name. 

reg_set is a register set. The register set can contain 80x86 registers and/or the string "8087". 

Notes: 

1. If an empty register set is specified, all arguments, including floating-point arguments, will be 
passed on the 80x86 stack. 

When the string "8087" appears in a register set, it simply means that floating-point arguments can be 
passed in 80x87 floating-point registers if the source file is compiled with the "fpi" or "fpi87" option. 

Before discussing argument passing in detail, some general notes on the use of the 80x87 floating-point 
registers are given. 

The 80x87 contains 8 floating-point registers which essentially form a stack. The stack pointer is called ST 
and is a number between 0 and 7 identifying which 80x87 floating-point register is at the top of the stack. 
ST is initially 0. 80x87 instructions reference these registers by specifying a floating-point register number. 
This number is then added to the current value of ST. The sum (taken modulo 8) specifies the 80x87 
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floating-point register to be used. The notation ST(n), where "n" is between 0 and 7, is used to refer to the 
position of an 80x87 floating-point register relative to ST. 

When a floating-point value is loaded onto the 80x87 floating-point register stack, ST is decremented 
(modulo 8), and the value is loaded into ST(0). When a floating-point value is stored and popped from the 
80x87 floating-point register stack, ST is incremented (modulo 8) and ST(1) becomes ST(0). The 
following illustrates the use of the 80x87 floating-point registers as a stack, assuming that the value of ST is 
4 (4 values have been loaded onto the 80x87 floating-point register stack). 


+-+ 

0 | 4th from top | ST(4) 

+-+ 

1 | 5th from top | ST(5) 

+-+ 

2 | 6th from top | ST(6) 

+-+ 

3 | 7th from top | ST(7) 

+-+ 

ST -> 4 | top of stack | ST (0) 

+-+ 

5 | 1st from top | ST(1) 

+-+ 

6 | 2nd from top | ST(2) 

+-+ 

7 | 3rd from top | ST(3) 

+-+ 


Starting with version 9.5, the Open Watcom compilers use all eight of the 80x87 registers as a stack. The 
initial state of the 80x87 register stack is empty before a program begins execution. 

Note: For compatibility with code compiled with version 9.0 and earlier, you can compile with 

the "fpr" option. In this case only four of the eight 80x87 registers are used as a stack. 
These four registers were used to pass arguments. The other four registers form what was 
called the 80x87 cache. The cache was used for local floating-point variables. The state of 
the 80x87 registers before a program began execution was as follows. 

1. The four 80x87 floating-point registers that form the stack are uninitialized. 

2. The four 80x87 floating-point registers that form the 80x87 cache are initialized 
with zero. 

Hence, initially the 80x87 cache was comprised of ST(0), ST(1), ST(2) and ST(3). ST had 
the value 4 as in the above diagram. When a floating-point value was pushed on the stack 
(as is the case when passing floating-point arguments), it became ST(0) and the 80x87 
cache was comprised of ST(1), ST(2), ST(3) and ST(4). When the 80x87 stack was full, 
ST(0), ST(1), ST(2) and ST(3) formed the stack and ST(4), ST(5), ST(6) and ST(7) formed 
the 80x87 cache. Version 9.5 and later no longer use this strategy. 

The rules for passing arguments are as follows. 

1. If the argument is not floating-point, use the procedure described earlier in this chapter. 

2. If the argument is floating-point, and a previous argument has been assigned a position on the 
80x86 stack (instead of the 80x87 stack), the floating-point argument is also assigned a position 
on the 80x86 stack. Otherwise proceed to the next step. 
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3. If the string "8087" appears in a register set in the pragma, and if the 80x87 stack is not full, the 
floating-point argument is assigned floating-point register ST(0) (the top element of the 80x87 
stack). The previous top element (if there was one) is now in ST(1). Since arguments are 
pushed on the stack from right to left, the leftmost floating-point argument will be in ST(0). 
Otherwise the floating-point argument is assigned a position on the 80x86 stack. 

Consider the following example. 

♦pragma aux myrtn parm [8087]; 

void main() 

{ 


float 

x; 

double 

y; 

int 

i; 

long int 

j; 

x = 7.7; 


i = 7; 


y = 77.77 

r 

j = 77; 



myrtn( x, i, y, j ); 

1 

myrtn is an assembly language function that requires four arguments. The first argument of type float (4 
bytes), the second argument is of type int (4 bytes), the third argument is of type double (8 bytes) and the 
fourth argument is of type long int (4 bytes). These arguments will be passed to myrtn in the following 
way. 

1. Since "8087" was specified in the register set, the first argument, being of type float, will be 
passed in an 80x87 floating-point register. 

2. The second argument will be passed on the stack since no 80x86 registers were specified in the 
register set. 

3. The third argument will also be passed on the stack. Remember the following rule: once an 
argument is assigned a position on the stack, all remaining arguments will be assigned a position 
on the stack. Note that the above rule holds even though there are some 80x87 floating-point 
registers available for passing floating-point arguments. 

4. The fourth argument will also be passed on the stack. 

Let us change the auxiliary pragma in the above example as follows. 

♦pragma aux myrtn parm [eax 8087]; 

The arguments will now be passed to myrtn in the following way. 

1. Since "8087" was specified in the register set, the first argument, being of type float will be 
passed in an 80x87 floating-point register. 

2. The second argument will be passed in register EAX, exhausting the set of available 80x86 
registers for argument passing. 

3. The third argument, being of type double, will also be passed in an 80x87 floating-point register. 


250 Auxiliary Pragmas 




32-bit Pragmas 


4. The fourth argument will be passed on the stack since no 80x86 registers remain in the register 
set. 

11.27.12.2 Using the 80x87 to Return Function Values 

The following form of the auxiliary pragma can be used to describe a function that returns a floating-point 
value in ST(0). 


♦pragma aux sym value reg_set [;] 


where description: 

sym is a function name. 

reg_set is a register set containing the string "8087", i.e. [8087], 

11.27.12.3 Preserving 80x87 Floating-Point Registers Across Calls 

The code generator assumes that all eight 80x87 floating-point registers are available for use within a 
function unless the "fpr" option is used to generate backward compatible code (older Open Watcom 
compilers used four registers as a cache). The following form of the auxiliary pragma specifies that the 
floating-point registers in the 80x87 cache may be modified by the specified function. 


♦pragma aux sym modify reg_set [;] 


where description: 

sym is a function name. 

reg_set is a register set containing the string "8087", i.e. [8087]. 

This instructs Open Watcom C/C++ to save any local variables that are located in the 80x87 cache before 
calling the specified routine. 
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12 In-line Assembly Language 


The chapters entitled "16-bit Pragmas" on page 139 and "32-bit Pragmas" on page 207 briefly describe the 
use of the auxiliary pragma to create a sequence of assembly language instructions that can be placed 
anywhere executable C/C++ statements can appear in your source code. This chapter is devoted to an 
in-depth look at in-line assembly language programming. 

The reasons for resorting to in-line assembly code are varied: 

• Speed - You may be interested in optimizing a heavily-used section of code. 

• Size - You may wish to optimize a module for size by replacing a library function call with a direct 
system call. 

• Architecture - You may want to access certain features of the Intel x86 architecture that cannot be 
done so with C/C++ statements. 

There are also some reasons for not resorting to in-line assembly code. 

• Portability - The code is not portable to different architectures. 

• Optimization - Sometimes an optimizing compiler can do a better job of arranging the instruction 
stream so that it is optimal for a particular processor (such as the 486 or Pentium). 

12.1 In-line Assembly Language Default Environment 

In next table is description of the default in-line assembler environment in dependency on C/C++ compilers 
CPU switch for x86 target platform. 


Compiler 

CPU 

directive 

FPU 

directive 

CPU extension 
directives 

-0 

.8086 

.8087 


-1 

.186 

.8087 


-2 

. 286p 

.287 


-3 

. 386p 

.387 


-4 

. 48 6p 

.387 


-5 

. 586p 

.387 

.K3D+.MMX 

-6 

. 68 6p 

.387 

.K3D+.MMX+.XMM+.XMM2+.XMM3 


This environment can be simply changed by appropriate directives. 


Note: 


This change is valid only for the block of assembly source code. After this block, default setting is 
restored. 
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12.2 In-line Assembly Language Tutorial 

Doing in-line assembly is reasonably straight-forward with Open Watcom C/C++ although care must be 
exercised. You can generate a sequence of in-line assembly anywhere in your C/C++ code stream. The 
first step is to define the sequence of instructions that you wish to place in-line. The auxiliary pragma is 
used to do this. Here is a simple example based on a DOS function call that returns a far pointer to the 
Double-Byte Character Set (DBCS) encoding table. 

Example: 

extern unsigned short far *dbcs_ table ( void ) ; 


♦pragma aux dbcs_ table = \ 
"mov ax,6300h" \ 

"int 21h" \ 

value [ds si] \ 
modify [ax]; 


To set up the DOS call, the AH register must contain the hexadecimal value "63" (63h). A DOS function 
call is invoked by interrupt 21h. DOS returns a far pointer in DS:SI to a table of byte pairs in the form 
(start of range, end of range). On a non-DBCS system, the first pair will be (0,0). On a Japanese DBCS 
system, the first pair will be (81h,9Fh). 

With each pragma, we define a corresponding function prototype that explains the behaviour of the 
function in terms of C/C++. Essentially, it is a function that does not take any arguments and that returns a 
far pointer to a unsigned short item. 

The pragma indicates that the result of this "function" is returned in DS:SI (value [ds si]). The pragma also 
indicates that the AX register is modified by the sequence of in-line assembly code (modify [ax]). 

Having defined our in-line assembly code, let us see how it is used in actual C code. 

Example: 

♦include <stdio.h> 

extern unsigned short far *dbcs_ table ( void ) ; 


♦pragma aux dbcs_ table = \ 
"mov ax,6300h" \ 

"int 21h" \ 

value [ds si] \ 
modify [ax]; 


void main() 

{ 

if( *dbcs_ table() != 0 ) { 

/* 

we are running on a DOS system that 
supports double-byte characters 

*/ 

printf( "DBCS supported\n" ) ; 

} 

} 

Before you attempt to compile and run this example, consider this: The program will not work! At least, it 
will not work in most 16-bit memory models. And it doesn't work at all in 32-bit protected mode using a 
DOS extender. What is wrong with it? 
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We can examine the disassembled code for this program in order to see why it does not always work in 
16-bit real-mode applications. 


if( *dbcs_ table() != 0 ) { 



/* 




we are running on a DOS 

system that 



supports double-byte characters 



*/ 



0007 

b8 00 63 

mov 

ax,6300H 

000a 

cd 21 

int 

21H 

000c 

83 3c 00 

cmp 

word ptr [si],0000H 

OOOf 

74 0a 

je 

LI 

i 

printf( "DBCS supported\n" ) 

; 


i 

0011 

be 00 00 

mov 

si,offset L2 

0014 

56 

push 

si 

0015 

e8 00 00 

call 

printf_ 

0018 

83 c4 02 

add 

sp,0002H 


After the DOS interrupt call, the DS register has been altered and the code generator does nothing to 
recover the previous value. In the small memory model, the contents of the DS register never change (and 
any code that causes a change to DS must save and restore its value). It is the programmer’s responsibility 
to be aware of the restrictions imposed by certain memory models especially with regards to the use of 
segmentation registers. So we must make a small change to the pragma. 

extern unsigned short far *dbcs_ table ( void ) ; 


♦pragma aux dbcs_ table = \ 
"push ds" \ 

"mov ax,6300h" \ 

"int 21h" \ 

"mov di,ds" \ 

"pop ds" \ 

value [di si] \ 
modify [ax]; 


If we compile and run this example with a 16-bit compiler, it will work properly. We can examine the 
disassembled code for this revised program. 


if ( *dbcs_ table () != 0 ) { 


0008 

/* 

we are running on a DOS system that 
supports double-byte characters 

*/ 

le push 

ds 

0009 

b8 00 63 


mov 

ax,6300H 

000c 

cd 21 


int 

21H 

OOOe 

8c df 


mov 

di, ds 

0010 

If 


pop 

ds 

0011 

8e c7 


mov 

es, di 

0013 

26 83 3c 

00 

cmp 

word ptr es:[si],0000H 

0017 

74 0a 


je 

LI 

> 

0019 

printf( 

be 00 00 

"DBCS supported\n" ) ; 

mov 

si,offset L2 

001c 

56 


push 

si 

OOld 

e8 00 00 


call 

printf_ 

0020 

83 c4 02 


add 

sp,0002H 


If you examine this code, you can see that the DS register is saved and restored by the in-line assembly 
code. The code generator, having been informed that the far pointer is returned in (DI:SI), loads up the ES 
register from DI in order to reference the far data correctly. 
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That takes care of the 16-bit real-mode case. What about 32-bit protected mode? When using a DOS 
extender, you must examine the accompanying documentation to see if the system call that you wish to 
make is supported by the DOS extender. One of the reasons that this particular DOS call is not so clear-cut 
is that it returns a 16-bit real-mode segment:offset pointer. A real-mode pointer must be converted by the 
DOS extender into a protected-mode pointer in order to make it useful. As it turns out, neither the 
Tenberry Software DOS/4G1W) nor Phar Lap DOS extenders support this particular DOS call (although 
others may). The issues with each DOS extender are complex enough that the relative merits of using 
in-line assembly code are not worth it. We present an excerpt from the final solution to this problem. 


Example: 

#ifndef_ 38 6_ 

extern unsigned short far *dbcs_ table ( void ) ; 


#pragma aux dbcs_ table = \ 
"push ds" \ 

"mov ax,630Oh" \ 
"int 21h" \ 

"mov di,ds" \ 

"pop ds" \ 

value [di si] \ 
modify [ax]; 

#else 


unsigned short far * dbcs_ table ( void ) 

{ 

union REGPACK regs; 

static short dbcs_ dummy = 0; 

memset( &regs, 0, sizeof( regs ) ) ; 
if ( _IsPharLap() ) { 

PHARLAP_ block pblock; 

memset( Spblock, 0, sizeof( pblock ) ); 

pblock.real_ eax = 0x6300; /* get DBCS vector table */ 

pblock. int_ num = 0x21; /* DOS call */ 

regs.x.eax = 0x2511; /* issue real-mode interrupt */ 

regs.x.edx = FP_ OFF ( Spblock ); /* DS:EDX -> parameter block */ 
regs.w.ds = FP_ SEG( &pblock ); 
intr( 0x21, &regs ); 

return( firstmeg( pblock.real_ ds, regs.w.si ) ); 

} else if ( _IsDOS4G() ) { 

DPMI_ block dblock; 


memset( Sdblock, 0, sizeof( dblock ) ); 


dblock.eax = 0x6300; /* 

regs.w.ax = 0x300; /* 

regs.h.bl = 0x21; /* 

regs.h.bh =0; /* 

regs.w.cx = 0; /* 

regs.x.edi = FP_ OFF ( Sdblock ); 
regs.x.es = FP_ SEG ( Sdblock ); 
intr( 0x31, &regs ); 

return( firstmeg( dblock.ds, dblock.esi ) 
else { 

return ( &dbcs_ dummy ) ; 


get DBCS vector table */ 


DPMI Simulate R-M intr 
DOS call */ 
flags */ 

# bytes from stack */ 


) ; 




#endif 


The 16-bit version will use in-line assembly code but the 32-bit version will use a C function that has been 
crafted to work with both Tenberry Software DOS/4G1W) and Phar Lap DOS extenders. The f irstmeg 
function used in the example is shown below. 
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♦define REAL_ SEGMENT 0x34 

void far *firstmeg( unsigned segment, unsigned offset ) 

< 

void far *megl; 
if ( _ IsDOS4G() ) { 

megl = MK_ FP ( FP_ SEG( smegl ), ( segment << 4 ) + offset ); 

} else { 

megl = MK_ FP ( REAL_ SEGMENT, ( segment « 4 ) + offset ) ; 

} 

return( megl ); 

} 


We have taken a brief look at two features of the auxiliary pragma, the "modify" and "value" attributes. 

The "modify" attribute describes those registers that are modified by the execution of the sequence of 
in-line code. You usually have two choices here; you can save/restore registers that are affected by the 
code sequence in which case they need not appear in the modify list or you can let the code generator 
handle the fact that the registers are modified by the code sequence. When you invoke a system function 
(such as a DOS or BIOS call), you should be careful about any side effects that the call has on registers. If 
a register is modified by a call and you have not listed it in the modify list or saved/restored it, this can have 
a disastrous affect on the rest of the code in the function where you are including the in-line code. 

The "value" attribute describes the register or registers in which a value is returned ( we use the term 
"returned", not in the sense that a function returns a value, but in the sense that a result is available after 
execution of the code sequence). 

This leads the discussion into the third feature of the auxiliary pragma, the feature that allows us to place 
the results of C expressions into specific registers as part of the "setup" for the sequence of in-line code. To 
illustrate this, let us look at another example. 

Example: 

extern void BlOSSetCurPos( unsigned short _ rowcol, 

unsigned char _ page ); 


♦pragma aux BlOSSetCurPos = \ 

"push bp" \ 

"mov ah,2" \ 

"int lOh" \ 

"pop bp" \ 

parm [dx] [bh] \ 

modify [ah]; 


The "parm" attribute specifies the list of registers into which values are to be placed as part of the prologue 
to the in-line code sequence. In the above example, the "set cursor position" function requires three pieces 
of information. It requires that the cursor row value be placed in the DH register, that the cursor column 
value be placed in the DL register, and that the screen page number be placed in the BH register. In this 
example, we have decided to combine the row and column information into a single "argument" to the 
function. Note that the function prototype for BlOSSetCurPos is important. It describes the types and 
number of arguments to be set up for the in-line code. It also describes the type of the return value (in this 
case there is none). 

Once again, having defined our in-line assembly code, let us see how it is used in actual C code. 
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Example: 

♦include <stdio.h> 


extern void BlOSSetCurPos ( unsigned short_rowcol, 

unsigned char _ page ); 


♦pragma aux BlOSSetCurPos = \ 

"push bp" \ 

"mov ah,2" \ 

"int lOh" \ 

"pop bp" \ 

parm [dx] [bh] \ 

modify [ah]; 


void main() 

{ 

BlOSSetCurPos ( (5 « 8) | 20, 0 ); 

printf ( "Hello world\n" ); 

} 


To see how the code generator set up the register values for the in-line code, let us take a look at the 
disassembled code. 

BlOSSetCurPos( (5 « 8) | 20, 0 ) ; 


0008 

ba 

14 05 

mov 

dx,0514H 

000b 

30 

ff 

xor 

bh,bh 

OOOd 

55 


push 

bp 

OOOe 

b4 

02 

mov 

ah,02H 

0010 

cd 

10 

int 

10H 

0012 

5d 


pop 

bp 


As we expected, the result of the expression for the row and column is placed in the DX register and the 
page number is placed in the BH register. The remaining instructions are our in-line code sequence. 

Although our examples have been simple, you should be able to generalize them to your situation. 

To review, the "parm", "value" and "modify" attributes are used to: 

1. convey information to the code generator about the way data values are to be placed in registers 
in preparation for the code burst (parm), 

2. convey information to the code generator about the result, if any, from the code burst (value), 
and 

3. convey information to the code generator about any side effects to the registers after the code 
burst has executed (modify). It is important to let the code generator know all of the side effects 
on registers when the in-line code is executed; otherwise it assumes that all registers, other than 
those used for parameters, are preserved. In our examples, we chose to push/pop some of the 
registers that are modified by the code burst. 
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12.3 Labels in In-line Assembly Code 

Labels can be used in in-line assembly code. Here is an example. 
Example: 

extern void _ disable_ video ( unsigned ) ; 
♦pragma aux _ disable_ video = \ 


"again: in al,dx" \ 

"test al,8" \ 

"jz again" \ 

"mov dx,03c0h" \ 

"mov al,llh" \ 

"out dx,al" \ 

"mov al,0" \ 

"out dx,al" \ 

parm [dx] \ 


modify [al dx]; 

12.4 Variables in In-line Assembly Code 

To finish our discussion, we provide examples that illustrate the use of variables in the in-line assembly 
code. The following example illustrates the use of static variable references in the auxiliary pragma. 

Example: 

♦include <stdio.h> 

static short _ rowcol; 


static unsigned char _page; 


extern void BlOSSetCurPos( void ) ; 
♦pragma aux BlOSSetCurPos = \ 

"mov dx,_ rowcol" \ 

"mov bh,_page" \ 

"push bp" \ 

"mov ah,2" \ 

"int lOh" \ 

"pop bp" \ 

modify [ah bx dx]; 


void main() 

{ 

_ rowcol = (5 << 8) | 20; 

_ page = 0; 

BlOSSetCurPos() ; 

printf( "Hello world\n" ); 

} 

The only rule to follow here is that the auxiliary pragma must be defined after the variables are defined. 
The in-line assembler is passed information regarding the sizes of variables so they must be defined first. 

If we look at a fragment of the disassembled code, we can see the result. 
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rowcol = (5 << 8) | 20; 


0008 

c7 06 00 00 14 05 

mov 

word ptr_rowcol, 0514H 


page = 0; 



OOOe 

c6 06 00 00 00 

mov 

byte ptr_page,00H 

BlOSSetCurPos (); 



0013 

8b 16 00 00 

mov 

dx,_rowcol 

0017 

8a 3e 00 00 

mov 

bh,_page 

001b 

55 

push 

bp 

001c 

b4 02 

mov 

ah,02H 

OOle 

cd 10 

int 

10H 

0020 

5d 

pop 

bp 


The following example illustrates the use of automatic variable references in the auxiliary pragma. Again, 
the auxiliary pragma must be defined after the variables are defined so the pragma is placed in-line with the 
function. 


Example: 

♦include <stdio.h> 


void main() 

{ 

short _ rowcol; 

unsigned char _ page; 


extern void BlOSSetCurPos ( void ) ; 
# pragma aux BlOSSetCurPos = \ 


"mov dx,_ rowcol" \ 
"mov bh,_page" \ 
"push bp" \ 
"mov ah,2" \ 
"int lOh" \ 
"pop bp" \ 


modify [ah bx dx] ; 


_ rowcol = (5 << 8) | 20; 

_ page = 0; 

BlOSSetCurPos() ; 

printf( "Hello world\n" ) ; 


If we look at a fragment of the disassembled code, we can see the result. 


_ rowcol = (5 << 8) | 20; 

OOOe c7 46 fc 14 05 

_ page = 0; 

0013 c6 46 fe 00 

BlOSSetCurPos () ; 

0017 8b 96 fc ff 

001b 8a be fe ff 

OOlf 55 

0020 b4 02 

0022 cd 10 

0024 5d 


mov word ptr -4H[bp],0514H 


mov byte ptr -2H[bp],00H 


mov dx,-4H[bp] 

mov bh,-2H[bp] 

push bp 

mov ah,02H 

int 10H 

pop bp 


You should try to avoid references to automatic variables as illustrated by this last example. Referencing 
automatic variables in this manner causes them to be marked as volatile and the optimizer will not be able 
to do a good job of optimizing references to these variables. 
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12.5 In-line Assembly Language using _asm 

There is an alternative to Open Watcom’s auxiliary pragma method for creating in-line assembly code. 

You can use one of the _asm or_ asm keywords to imbed assembly code into the generated code. The 

following is a revised example of the cursor positioning example introduced above. 

Example: 

♦include <stdio.h> 

void main () 

{ 

unsigned short _ rowcol; 
unsigned char _ page; 

_ rowcol = (5 << 8) | 20; 

_ page = 0; 

_ asm { 


mov 

dx, _ 

rowcol 

mov 

bh, _ 

page 

push 

bp 


mov 

ah, 2 


int 

lOh 


pop 

bp 



} ; 

printf( "Hello world\n" ) ; 

} 

The assembly language sequence can reference program variables to retrieve or store results. There are a 
few incompatibilities between Microsoft and Open Watcom implementation of this directive. 

_ LOCAL_SIZE is not supported by Open Watcom C/C++. This is illustrated in the following example. 

Example: 

void main() 

{ 

int i; 
int j; 

_ asm { 

push bp 

mov bp,sp 

sub sp,_LOCAL_ SIZE 

}; 

} 

structure references are not supported by Open Watcom C/C++. This is illustrated in the following 
example. 
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Example: 

♦include <stdio.h> 

struct rowcol { 

unsigned char col; 
unsigned char row; 


void main() 

{ 

struct rowcol _pos; 


unsigned 

char _ page; 

_ pos.row 

= 5; 

_ pos.col 

= 20; 

_ page = 

0; 

_ asm { 


mov 

dl,_ pos. col 

mov 

dh, _ pos . row 

mov 

bh,_ page 

push 

bp 

mov 

ah, 2 

int 

lOh 

pop 

bp 


} ; 

printf ( "Hello world\n" ); 

} 

12.6 In-line Assembly Directives and Opcodes 

It is not the intention of this chapter to describe assembly-language programming in any detail. You should 
consult a book that deals with this topic. However, we present a list of the directives, opcodes and register 
names that are recognized by the assembler built into the compiler’s auxiliary pragma processor. 
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.286 

,286c 

. 28 6p 

.287 

.386 

. 386p 

.387 

.486 

. 48 6p 

.586 

. 586p 

. 686 

. 68 6p 

.8086 

.8087 

byte 

db 

dd 

df 

dp 

dq 

dt 

dup 

dw 

dword 

far 

. k3d 

.mmx 

near 

. no87 

offset 

oword 

ptr 

pword 

qword 

seg 

tbyte 

word 

. xmm 

. xmm2 

. xmm3 



aaa 

aad 

aam 

aas 

adc 

add 

addpd 

addps 

addsd 

addss 

addsubpd 

addsubps 

and 

andnpd 

andnps 

andpd 

andps 

arpl 

bound 

bp 

bsf 

bsr 

bswap 

bt 

btc 

btr 

bts 

call 

calif 

cbw 

cdq 

clc 

cld 

elflush 

cli 

cits 

cmc 

cmova 

cmovae 

cmovb 
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cmovbe 

cmovc 

cmovge 

cmovl 

cmovnae 

cmovnb 

cmovne 

cmovng 

cmovnle 

cmovno 

cmovnz 

cmovo 

cmovpo 

cmovs 

cmpeqpd 

cmpeqps 

cmplepd 

cmpleps 

cmpltpd 

cmpltps 

cmpneqpd 

cmpneqps 

cmpnlepd 

cmpnleps 

cmpnltpd 

cmpnltps 

cmpordpd 

cmpordps 

cmppd 

cmpps 

cmpsd 

cmpss 

cmpunordps 

cmpunordsd 

cmpxchg8b 

comisd 

cvtdq2pd 

cvtdq2ps 

cvtpd2ps 

cvtpi2pd 

cvtps2pd 

cvtps2pi 

cvtsi2sd 

cvtsi2ss 

cvttpd2dq 

cvttpd2pi 

cvttsd2si 

cvttss2si 

daa 

das 

divpd 

divps 

emms 

enter 

f add 

faddp 

f chs 

f clex 

fcmove 

fcmovnb 

fcmovnu 

fcmovu 

fcomip 

f comp 

fdecstp 

f disi 

f divr 

fdivrp 

f f ree 

f iadd 

f idiv 

fidivr 

fincstp 

f init 

fisttp 

f isub 

fid 

fldl 

fldenvd 

fldenvw 

fldlg2 

fldln2 

fmul 

fmulp 

fneni 

fninit 

fnrstord 

fnrstorw 

fnsavew 

fnstcw 

fnstenvw 

fnstsw 

fpreml 

fptan 

frstord 

frstorw 

fsavew 

f scale 

fsincos 

f sqrt 

fstenv 

fstenvd 

f stsw 

f sub 

fsubrp 

ftst 

fucomip 

fucomp 

f xam 

f xch 

fxtract 

f yl2x 

haddps 

hit 

idiv 

imul 

ins 

insb 


cmove 

cmovg 

cmovle 

cmovna 

cmovnbe 

cmovnc 

cmovnge 

cmovnl 

cmovnp 

cmovns 

cmovp 

cmovpe 

cmovz 

cmp 

cmpeqsd 

cmpeqss 

cmplesd 

cmpless 

cmpltsd 

cmpltss 

cmpneqsd 

cmpneqss 

cmpnlesd 

cmpnless 

cmpnltsd 

cmpnltss 

cmpordsd 

cmpordss 

cmps 

cmpsb 

cmpsw 

cmpunordpd 

cmpunordss 

cmpxchg 

comiss 

cpuid 

cvtpd2dq 

cvtpd2pi 

cvtpi2ps 

cvtps2dq 

cvtsd2si 

cvtsd2ss 

cvtss2sd 

cvtss2si 

cvttps2dq 

cvttps2pi 

cwd 

cwde 

dec 

div 

divsd 

divss 

f 2 xml 

fabs 

fbld 

fbstp 

fcmovb 

fcmovbe 

fcmovnbe 

fcmovne 

f com 

f comi 

fcompp 

f cos 

fdiv 

f divp 

f emms 

f eni 

f icom 

ficomp 

fild 

f imul 

fist 

f istp 

fisubr 

flat 

f ldcw 

fldenv 

fldl2e 

fldl2t 

f 1dpi 

f ldz 

fnclex 

fndisi 

fnop 

fnrstor 

fnsave 

fnsaved 

fnstenv 

fnstenvd 

fpatan 

fprem 

frndint 

frstor 

f save 

fsaved 

fsetpm 

f sin 

f St 

f stew 

fstenvw 

f stp 

f subp 

f subr 

fucom 

fucomi 

fucompp 

fwait 

fxrstor 

fxsave 

fyl2xpl 

haddpd 

hsubpd 

hsubps 

in 

inc 

insd 

insw 


In-line Assembly Directives and Opcodes 265 




In-line Assembly Language 


int 

into 

iret 

iretd 

ja 

jae 

jc 

jcxz 

jg 

jge 

jmp 

jmpf 

jnb 

jnbe 

jng 

jnge 

jno 

jnp 

jo 

jP 

js 

jz 

lddqu 

ldmxcsr 

leave 

les 

lgdt 

lgs 

lmsw 

lock 

lodsd 

lodsw 

loope 

looped 

loopned 

loopnew 

loopnzw 

loopw 

loopzw 

lsl 

maskmovdqu 

maskmovq 

maxsd 

maxss 

minps 

minsd 

mov 

movapd 

movddup 

movdq2q 

movhlps 

movhpd 

movlpd 

movlps 

movntdq 

movnti 

movntq 

movq 

movsb 

movsd 

movss 

movsw 

movups 

movzx 

mulps 

mulsd 

near 

neg 

or 

orpd 

outs 

outsb 

packssdw 

packsswb 

paddd 

paddq 

paddusb 

paddusw 

pandn 

pause 

pavgw 

pempeqb 

pcmpgtb 

pcmpgtd 

pf 2id 

pf2iw 

pfcmpeq 

pfempge 

pfmin 

pfmul 

pf rep 

pfrcpitl 

pfrsqrt 

pf sub 

pi2fw 

pinsrw 

pmaxub 

pminsw 

pmulhrw 

pmulhuw 

pmuludq 

pop 

popf 

popf d 

prefetchnta 

prefetchtO 

prefetchw 

psadbw 

pshuflw 

pshufw 

psllq 

psllw 

psrld 

psrldq 

psubb 

psubd 

psubsw 

psubusb 


invd 

invlpg 

iretdf 

iretf 

jb 

jbe 

je 

jeexz 

jl 

jle 

jna 

jnae 

jnc 

jne 

jnl 

jnle 

jns 

jnz 

jpe 

jpo 

lahf 

lar 

Ids 

lea 

Ifence 

lfs 

lidt 

lldt 

lods 

lodsb 

loop 

loopd 

loopew 

loopne 

loopnz 

loopnzd 

loopz 

loopzd 

lss 

ltr 

maxpd 

maxps 

mfence 

minpd 

minss 

monitor 

movaps 

movd 

movdqa 

movdqu 

movhps 

movlhps 

movmskpd 

movmskps 

movntpd 

movntps 

movq2dq 

movs 

movshdup 

movsldup 

movsx 

movupd 

mul 

mulpd 

mulss 

mwait 

nop 

not 

orps 

out 

outsd 

outsw 

packuswb 

paddb 

paddsb 

paddsw 

paddw 

pand 

pavgb 

pavgusb 

pempeqd 

pempeqw 

pcmpgtw 

pextrw 

pfacc 

pf add 

pfempgt 

pfmax 

pfnacc 

pfpnacc 

pfrcpit2 

pfrsqitl 

pfsubr 

pi2fd 

pmaddwd 

pmaxsw 

pminub 

pmovmskb 

pmulhw 

pmullw 

popa 

popad 

por 

prefetch 

prefetchtl 

prefetcht2 

pshufd 

pshufhw 

pslld 

pslldq 

psrad 

psraw 

psrlq 

psrlw 

psubq 

psubsb 

psubusw 

psubw 
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pswapd 

punpckhbw 

punpckhwd 

punpcklbw 

punpcklwd 

push 

pushd 

pushf 

pxor 

rcl 

rcr 

rdmsr 

rep 

repe 

rept 

repz 

retf 

retf d 

ror 

rsm 

sahf 

sal 

seas 

scasb 

seta 

setae 

setc 

sete 

setl 

setle 

setnb 

setnbe 

setng 

setnge 

setno 

setnp 

seto 

setp 

sets 

setz 

shl 

shld 

shrd 

shufpd 

sldt 

smsw 

sqrtps 

sqrtsd 

std 

sti 

stosb 

stosd 

sub 

subpd 

subss 

sysenter 

ucomisd 

ucomiss 

unpcklpd 

unpcklps 

wait 

wbinvd 

xchg 

xlat 

xorpd 

xorps 

ah 

al 

bl 

bx 

crO 

cr2 

cs 

cx 

dl 

drO 

dr3 

dr 6 

dx 

eax 

ecx 

edi 

esi 

esp 

mmO 

mml 

mm 4 

mm 5 

si 

ss 

stl 

st2 

st5 

st6 

tr4 

tr5 

xmmO 

xmml 

xmm4 

xmm5 


punpekhdq 

punpckhqdq 

punpckldq 

punpcklqdq 

pusha 

pushad 

pushfd 

pushw 

repps 

repss 

rdpmc 

rdtsc 

repne 

repnz 

ret 

retd 

retn 

rol 

rsqrtps 

rsqrtss 

sar 

sbb 

scasd 

scasw 

setb 

setbe 

setg 

setge 

setna 

setnae 

setnc 

setne 

setnl 

setnle 

setns 

setnz 

setpe 

setpo 

sfence 

sgdt 

short 

shr 

shufps 

sidt 

sp 

sqrtpd 

sqrtss 

stc 

stmxcsr 

stos 

stosw 

str 

subps 

subsd 

sysexit 

test 

unpekhpd 

unpekhps 

verr 

verw 

wrmsr 

xadd 

xlatb 

xor 


ax 

bh 

eh 

cl 

cr3 

cr4 

dh 

di 

drl 

dr2 

dr7 

ds 

ebp 

ebx 

edx 

es 

f s 

gs 

mm2 

mm3 

mm 6 

mm 7 

St 

stO 

st3 

st4 

st7 

tr3 

tr 6 

tr7 

xmm2 

xmm3 

xmm6 

xmm7 


A separate assembler is also included with this product and is described in the Open Watcom C/C++ Tools 
User’s Guide 
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13 Structured Exception Handling 


Microsoft-style Structured Exception Handling (SEH) is supported by the Open Watcom C compiler only. 
MS SEH is supported under the Win32, Win32s and OS/2 platforms. You should not confuse SEH with 
C++ exception handling. The Open Watcom C++ compiler supports the standard C++ syntax for exception 
handling. 

The following sections introduce some of the aspects of SEH. For a good description of SEH, please refer 
to Advanced Windows NT by Jeffrey Richter (Microsoft Press, 1994). You may also wish to read the 
article "Clearer, More Comprehensive Error Processing with Win32 Structured Exception Handling" by 
Kevin Goodman in the January, 1994 issue of Microsoft Systems Journal. 


13.1 Termination Handlers 


We begin our look at SEH with a simple model. In this model, there are two blocks of code — the 
"guarded" block and the "termination" block. The termination code is guaranteed to be executed regardless 
of how the "guarded" block of code is exited (including execution of any "return" statement). 

_ try { 

/* guarded code */ 


} 

_ finally { 

/* termination handler */ 


} 

The _Jinally block of code is guaranteed to be executed no matter how the guarded block is exited ( break, 
continue, return, goto, or longjmp ). Exceptions to this are calls to abort, exit or _exit which terminate the 
execution of the process. 

There can be no intervening code between try and finally blocks. 

The following is a contrived example of the use of _try and _Jinally. 

Example: 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <excpt.h> 

int docopy( char *in, char *out ) 

{ 

FILE *in_ file = NULL; 

FILE * out_ file = NULL; 

char buffer[256]; 
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_ try { 

in_ file = fopen( in, "r" ); 

if ( in_ file == NULL ) return ( EXIT_ FAILURE ); 
out_ file = fopen( out, "w" ); 

if ( out_ file == NULL ) return ( EXIT_ FAILURE ); 

while( fgets((char *)buffer, 255, in_ file) != NULL ) { 

fputs( (char *)buffer, out_ file ); 

} 

} 

_ finally { 

if ( in_ file != NULL ) { 

printf( "Closing input file\n" ); 
fclose ( in_ file ) ; 

} 

if( out_ file != NULL ) { 

printf( "Closing output file\n" ); 
fclose ( out_ file ) ; 

} 

printf( "End of processing\n" ); 

} 

return ( EXIT_ SUCCESS ); 

} 

void main ( int argc, char **argv ) 

{ 

if( argc < 3 ) { 

printf ( "Usage: mv [in_ filename] [out_ filename]\n" ); 
exit ( EXIT_ FAILURE ) ; 

} 

exit( docopy( argv[l], argv[2] ) ); 

} 

The try block ignores the messy details of what to do when either one of the input or output files cannot be 
opened. It simply tests whether a file can be opened and quits if it cannot. Th e finally block ensures that 
the files are closed if they were opened, releasing the resources associated with open files. This simple 
example could have been written in C without the use of SEH. 

There are two ways to enter the, finally block. One way is to exit the try block using a statement like return 
. The other way is to fall through the end of the try block and into the finally block (the normal execution 
flow for this program). Any code following the finally block is only executed in the second case. You can 
think of the finally block as a special function that is invoked whenever an exit (other than falling out the 
bottom) is attempted from a corresponding try block. 

More formally stated, a local unwind occurs when the system executes the contents of a finally block 
because of the premature exit of code in a try block. 


Note: Kevin Goodman describes "unwinds" in his article. "There are two types of unwinds: global and 
local. A global unwind occurs when there are nested functions and an exception takes place. A local 
unwind takes place when there are multiple handlers within one function. Unwinding means that the 
stack is going to be clean by the time your handler’s code gets executed." 


The try/finally structure is a rejection mechanism which is useful when a set of statements is to be 
conditionally chosen for execution, but not all of the conditions required to make the selection are available 
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beforehand. It is an extension to the C language. You start out with the assumption that a certain task can 
be accomplished. You then introduce statements into the code that test your hypothesis. The try block 
consists of the code that you assume, under normal conditions, will succeed. Statements like if... return 
can be used as tests. Execution begins with the statements in the try block. If a condition is detected which 
indicates that the assumption of a normal state of affairs is wrong, a return statement may be executed to 
cause control to be passed to the statements in the finally block. If the try block completes execution 
without executing a return statement (i.e., all statements are executed up to the final brace), then control is 
passed to the first statement following the try block (i.e., the first statement in the. finally block). 

In the following example, two sets of codes and letters are read in and some simple sequence checking is 
performed. If a sequence error is detected, an error message is printed and processing terminates; otherwise 
the numbers are processed and another pair of numbers is read. 

Example: 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <excpt.h> 

void main( int argc, char **argv ) 

{ 

read_ file ( fopen ( argv[l], "r" ) ); 

} 

void read_ file( FILE *input ) 

{ 

int line = 0; 

char buffer[256]; 

char icode; 

char x, y; 

if( input == NULL ) { 

printf( "Unable to open file\n" ); 
return; 

} 

_ try { 

for (;;) { 

line+t; 

if( fgets( buffer, 255, input ) == NULL ) break; 

icode = buffer[0]; 

if ( icode != ' 1 ' ) return; 

x = buffer[1]; 

line+t; 

if( fgets( buffer, 255, input ) == NULL ) return; 

icode = buffer[0]; 

if ( icode != ' 2 ' ) return; 

y = buffer[1]; 

process( x, y ) ; 

} 

printf( "Processing complete\n" ) ; 
fclose ( input ); 
input = NULL; 

} 
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_ finally { 

if( input != NULL ) { 

printf( "Invalid sequence: line = %d\n", line ); 
fclose ( input ); 

} 

} 

} 

void process( char x, char y ) 

{ 

printf ( "processing pair %c,%c\n", x, y ); 

} 

The above example attempts to read a code and letter. If an end of file occurs then the loop is terminated 
by the break statement. 

If the code is not 1 then we did not get what we expected and an error condition has arisen. Control is 
passed to the first statement in the finally block by the return statement. An error message is printed and 
the open file is closed. 

If the code is 1 then a second code and number are read. If an end of file occurs then we are missing a 
complete set of data and an error condition has arisen. Control is passed to the first statement in the finally 
block by the return statement. An error message is printed and the open file is closed. 

Similarly if the expected code is not 2 an error condition has arisen. The same error handling procedure 
occurs. 

If the second code is 2, the values of variables x and y are processed (printed). The for loop is repeated 
again. 

The above example illustrates the point that all the information required to test an assumption (that the file 
contains valid pairs of data) is not available from the start. We write our code with the assumption that the 
data values are correct (our hypothesis) and then test the assumption at various points in the algorithm. If 
any of the tests fail, we reject the hypothesis. 

Consider the following example. What values are printed by the program? 

Example: 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <excpt.h> 

void main( int argc, char **argv ) 

{ 

int ctr = 0; 

while( ctr < 10 ) { 

printf( "%d\n", ctr ); 

_ try { 

if( ctr == 2 ) continue; 
if( ctr == 3 ) break; 

} 

_ finally { 
ctr++; 

} 
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ctr++; 

} 

printf( "%d\n", ctr ); 

} 

At the top of the loop, the value of ct r is 0. The next time we reach the top of the loop, the value of ct r 
is 2 (having been incremented twice, once by th e finally block and once at the bottom of the loop). When 
ctr has the value 2, the continue statement will cause the finally block to be executed (resulting in ctr 
being incremented to 3), after which execution continues at the top of the while loop. When ctr has the 
value 3, the break statement will cause the, finally block to be executed (resulting in ctr being incremented 
to 4), after which execution continues after the while loop. Thus the output is: 

0 

2 

3 

4 

The point of this exercise was that after the finally block is executed, the normal flow of execution is 
resumed at the break, continue, return , etc. statement and the normal behaviour for that statement occurs. 

It is as if the compiler had inserted a function call just before the statement that exits the try block. 

_ try { 

if ( ctr == 2 ) invoke_ finally_ block () continue; 
if ( ctr == 3 ) invoke_ finally_ block () break; 

} 

There is some overhead associated with local unwinds such as that incurred by the use of break, continue, 
return, etc. To avoid this overhead, a new transfer keyword called _leave can be used. The use of this 
keyword causes a jump to the end of the try block. Consider the following modified version of an earlier 
example. 

Example: 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <excpt.h> 

void main( int argc, char **argv ) 

{ 

read_ file ( fopen ( argv[l], "r" ) ); 

} 

void read_ file( FILE *input ) 

{ 

int line = 0; 

char buffer[256]; 

char icode; 

char x, y; 

if( input == NULL ) { 

printf( "Unable to open file\n" ); 
return; 

} 
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} 


try { 
for(;;) { 

line++; 

if( fgets( buffer, 
icode = buffer[0]; 
if( icode != '1' ) 

x = buffer[1]; 
line++; 

if( fgets( buffer, 
icode = buffer[0]; 
if( icode != '2' ) 

y = buffer[ 1 ] ; 
process( x, y ); 


255, input ) 
_ leave; 


255, input ) 
_ leave; 


printf ( "Processing complete\n" ) 
fclose ( input ); 
input = NULL; 


NULL ) break; 


NULL ) _ leave; 


_ finally { 

if( input != NULL ) { 

printf( "Invalid sequence: line 
fclose( input ); 

} 

} 

} 


%d\n", line ); 


void process( char x, char y ) 

{ 

printf( "processing pair %c,%c\n", x, y ) ; 

} 


There are two ways to enter th e finally block. One way is caused by unwinds — either local (by the use of 
break, continue, return, or goto) or global (more on global unwinds later). The other way is through the 
normal flow of execution (i.e., simply by falling through the bottom of the try block). There is a function 
called AbnormalTermination that can be used to determine which of these two methods was used to enter 
the finally block. If the function returns TRUE (1) then the finally block was entered using the first method; 
if the function returns FALSE (0) then the finally block was entered using the second method. This 
information may be useful in some circumstances. For example, you may wish to avoid executing any code 
in a finally block if the block was entered through the normal flow of execution. 

Example: 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <excpt.h> 

void main( int argc, char **argv ) 

{ 

read_ file ( fopen ( argv[l], "r" ) ); 

} 
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void read_ file( FILE *input ) 

{ 


int 

char 

char 

char 


line = 0; 
buffer[256]; 
icode; 
x, y; 


if( input == NULL ) { 

printf( "Unable to open file\n" ); 
return; 

} 


_ try { 

for (;;) { 


line++; 

if( fgets( buffer. 

255, input ) 

== NULL ) 

break; 

icode = buffer [0]; 
if( icode != ' 1' ) 

return; 



x = buffer[ 1 ] ; 
line++; 

if( fgets( buffer. 

255, input ) 

== NULL ) 

return; 

icode = buffer [0]; 
if( icode != ' 2 ' ) 

y = buffer[1 ] ; 
process ( x, y ); 

return; 




} 

printf ( "Processing complete\n" ); 


_ finally { 

if( AbnormalTermination() ) 

printf( "Invalid sequence: line = %d\n", line ); 
fclose ( input ); 

} 

} 

void process( char x, char y ) 

{ 

printf( "processing pair %c,%c\n", x, y ) ; 

} 

In the above example, we reverted back to the use of the return statement since the execution of a _leave 
statement is considered part of the normal flow of execution and is not considered an "abnormal 
termination" of the try block. Note that since it is not possible to determine whether the finally block is 
executing as the result of a local or global unwind, it may not be appropriate to use the 
AbnormalTermination function as a way to determine what has gone on. However, in our simple example, 
we expect that nothing could go wrong in the "processing" routine. 
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13.2 Exception Filters and Exception Handlers 

We would all like to create flawless software but situations arise for which we did not plan. An event that 
we did not expect which causes the software to cease to function properly is called an exception. The 
computer can generate a hardware exception when the software attempts to execute an illegal instruction. 

We can force this quite easily in C by dereferencing a NULL pointer as shown in the following sample 
fragment of code. 

Example: 

char *nullp = NULL; 

*nullp = ' \1' ; 

We can also generate software exceptions from software by calling a special function for this purpose. We 
will look at software exceptions in more detail later on. 

Given that exceptions are generally very difficult to avoid in large software projects, we can acknowledge 
that they are a fact of life and prepare for them. A mechanism similar to try/finally has been devised that 
makes it possible to gain control when an exception occurs and to execute procedures to handle the 
situation. 

The exception handling mechanism involves the pairing up of a _try block with an jexcept block. This is 
illustrated in the following example. 

Example: 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <excpt.h> 

void main( int argc, char **argv ) 

{ 

char *nullp = NULL; 

printf( "Attempting illegal memory reference.\n" ); 

_ try { 

*nullp = ' \1' ; 

} 

_ except (EXCEPTION_ EXECUTE_ HANDLER) { 

printf( "Oh no! We had an exception!\n" ); 

} 

printf( "We recovered fine...\n" ); 

} 

In this example, any exception that occurs while executing "inside" the try block will cause the except block 
to execute. Unlike the finally block, execution of the except block occurs only when an exception is 
generated and only when the expression after the jexcept keyword evaluates to 

EXCEPTION_ EXECUTE_ HANDLER . The expression can be quite complex and can involve the execution 
of a function that returns one of the permissible values. The expression is called the exception "filter" since 
it determines whether or not the exception is to be handled by the except block. The permissible result 
values for the exception filer are: 
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EXCEPTION_EXECUTE_HANDLER 

meaning "I will handle the exception". 

EXCEPTION_CONTINUE_EXECUTION 

meaning "I want to resume execution at the point where the exception was generated". 

EXCEPTION_CONTINUE_SEARCH 

meaning "I do not want to handle the exception so continue looking down the try/except 
chain until you find an exception handler that does want to handle the exception". 


13.3 Resuming Execution After an Exception 

Why would you want to resume execution of the instruction that caused the exception? Since the exception 
filter can involve a function call, that function can attempt to correct the problem. For example, if it is 
determined that the exception has occurred because of the NULL pointer dereference, the function could 
modify the pointer so that it is no longer NULL. 

Example: 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <excpt.h> 

char *NullP = NULL; 

int filter( void ) 

{ 

if ( NullP == NULL ) { 

NullP = malloc( 20 ); 

return ( EXCEPTION_ CONTINUE_ EXECUTION ) 

} 

return ( EXCEPTION_ EXECUTE_ HANDLER ) 

} 

void main( int argc, char **argv ) 

{ 

printf( "Attempting illegal memory reference.\n" ); 

_ try { 

*NullP = '\1'; 

} 

_ except (filter!)) { 

printf( "Oh no! We had an exception!\n" ); 

} 

printf( "We recovered fine...\n" ); 

} 

Unfortunately, this is does not solve the problem. Understanding why it does not involves looking at the 
sequence of computer instructions that is generated for the expression in question. 

*NullP = '\1'; 

mov eax,dword ptr _ NullP 

mov byte ptr [eax],01H 
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The exception is caused by the second instruction which contains a pointer to the referenced memory 
location (i.e., 0) in register EAX. This is the instruction that will be repeated when the filter returns 
EXCEPTION- CONTINUE- EXECUTION . Since EAX did not get changed by our fix, the exception will 
reoccur. Fortunately, NullP is changed and this prevents our program from looping forever. The moral 
here is that there are very few instances where you can correct "on the fly" a problem that is causing an 
exception to occur. Certainly, any attempt to do so must involve a careful inspection of the computer 
instruction sequence that is generated by the compiler (and this sequence usually varies with the selection 
of compiler optimization options). The best solution is to add some more code to detect the problem before 
the exception occurs. 

13.4 Mixing and Matching _try/_finally and_try/_except 

Where things really get interesting is in the interaction between try/finally blocks and try/except blocks. 
These blocks can be nested within each other. In an earlier part of the discussion, we talked about global 
unwinds and how they can be caused by exceptions being generated in nested function calls. All of this 
should become clear after studying the following example. 

Example: 

♦include <stdio.h> 

#include <stdlib.h> 

#include <excpt.h> 

void func_ level4 ( void ) 

{ 

char *nullp = NULL; 

printf( "Attempting illegal memory reference\n" ); 

_ try { 

*nullp = '\1'; 

} 

_ finally { 

if( AbnormalTermination() ) 

printf ( "Unwind in func_ level4\n" ) ; 

} 

printf ( "Normal return from func_ level4\n" ) ; 

} 

void func_ level3 ( void ) 

{ 

_ try { 

func_ level4 () ; 

} 

_ finally { 

if( AbnormalTermination() ) 

printf ( "Unwind in func_ level3\n" ) ; 

} 

printf ( "Normal return from func_ level3\n" ) ; 

} 

void func_ level2 ( void ) 

{ 

_ try { 

_ try { 

func_ level3 () ; 

} 

_ except (EXCEPTION_ CONTINUE_ SEARCH) { 

printf( "Exception never handled in func_ level2\n" ); 


} 

_ finally { 

if( AbnormalTermination() ) 

printf ( "Unwind in func_ level2\n" ) ; 

} 

printf ( "Normal return from func_ level2\n" ) ; 


280 Mixing and Matching JryIJinally and_tryIjexcept 




Structured Exception Handling 


void func_ levell ( void ) 

{ 

_ try { 

func_ level2 () ; 

} 

_ finally { 

if( AbnormalTermination() ) 

printf ( "Unwind in func_ levell\n" ) ; 

} 

printf ( "Normal return from func_ levell\n" ) ; 

} 

void func_ levelO ( void ) 

{ 

_ try { 

_ try { 

func_ levell (); 

} 

_ except (EXCEPTION_ EXECUTE_ HANDLER) { 

printf ( "Exception handled in func_ levelO\n" ) ; 


} 

_ finally { 

if( AbnormalTermination() ) 

printf ( "Unwind in func_ levelO\n" ) ; 

} 

printf ( "Normal return from func_ levelO\n" ) ; 

} 

void main( int argc, char **argv ) 

{ 

_ try { 

_ try { 

func_ levelO () ; 

} 

_ except (EXCEPTION_ EXECUTE_ HANDLER) { 
printf( "Exception handled in main\n" ); 


} 

_ finally { 

if( AbnormalTermination() ) 
printf( "Unwind in main\n" ) ; 

} 

printf( "Normal return from main\n" ); 


In this example, 

1. main calls func_ levelO 

2. func_ levelO callsfunc_ levell 

3. func_ levell callsfunc_ level2 

4. func_ level2 callsfunc_ level3 

5. func_ level3 callsfunc_ level4 

It is in func_ level4 where the exception occurs. The run-time system traps the exception and performs 
a search of the active try blocks looking for one that is paired up with an except block. 

When it finds one, the filter is executed and, if the result is EXCEPTION_ EXECUTE_ HANDLER, then the 
except block is executed after performing a global unwind. 

If the result is EXCEPTION_ CONTINUE_ EXECUTION, the run-time system resumes execution at the 
instruction that caused the exception. 
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If the result is EXCEPTION_ CONTINUE_ SEARCH, the run-time system continues its search for an except 
block with a filter that returns one of the other possible values. If it does not find any exception handler 
that is prepared to handle the exception, the application will be terminated with the appropriate exception 
notification. 

Let us look at the result of executing the example program. The following messages are printed. 

Attempting illegal memory reference 

Unwind in func_ level4 

Unwind in func_ level3 

Unwind in func_ level2 

Unwind in func_ levell 

Exception handled in func_ levelO 

Normal return from func_ levelO 

Normal return from main 

The run-time system searched down the try/except chain until it got to func_ levelO which had an 
except filter that evaluated to EXCEPTION_ EXECUTE_ HANDLER. It then performed a global unwind in 
which the try/finally blocks of func_ level4,func_ level3,func_ level2, andfunc_ levell 
were executed. After this, the exception handler in func_ levelO did its thing and execution resumed in 
func_ levelO which returned back tomain which returned to the run-time system for normal program 
termination. Note the use of the built-in AbnonnalTennination function in the finally blocks of each 
function. 

This sequence of events permits each function to do any cleaning up that it deems necessary before it is 
wiped off the execution stack. 

13.5 Refining Exception Handling 

The decision to handle an exception must be weighed carefully. It is not necessarily a desirable thing for an 
exception handler to handle all exceptions. In the previous example, the expression in the exception filter 
in func_ levelO always evaluates toEXCEPTION_ EXECUTE_ HANDLER which means it will snag 
every exception that comes its way. There may be other exception handlers further on down the chain that 
are better equipped to handle certain types of exceptions. There is a way to determine the exact type of 
exception using the built-in GetExceptionCode () function. It may be called only from within the 
exception handler filter expression or within the exception handler block. Here is a description of the 
possible return values from the GetExceptionCode () function. 

Value Meaning 

EXCEPTION_ACCESS_VIOLATION 

The thread tried to read from or write to a virtual address for which it does not 
have the appropriate access. 

EXCEPTION_BREAKPOINT 

A breakpoint was encountered. 

EXCEPTION_DATATYPE MISALIGNMENT 

The thread tried to read or write data that is misaligned on hardware that does 
not provide alignment. For example, 16-bit values must be aligned on 2-byte 
boundaries; 32-bit values on 4-byte boundaries, and so on. 
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EXCEPTION_SINGLE_STEP 

A trace trap or other single-instruction mechanism signaled that one instruction 
has been executed. 

EXCEPTION_ARRA Y_BOUNDS_EXCEEDED 

The thread tried to access an array element that is out of bounds and the 
underlying hardware supports bounds checking. 

EXCEPTION_FLT_DENORMAL_OPERAND 

One of the operands in a floating-point operation is denormal. A denormal value 
is one that is too small to represent as a standard floating-point value. 

EXCEPTION_FLT_DIVIDE_BY_ZERO 

The thread tried to divide a floating-point value by a floating-point divisor of 
zero. 

EXCEPTION_FLT_INEXACT_RESULT 

The result of a floating-point operation cannot be represented exactly as a 
decimal fraction. 

EXCEPTION_FLT_INVALID_OPERATION 

This exception represents any floating-point exception not included in this list. 

EXCEPTION_FLTJDVERFLOW 

The exponent of a floating-point operation is greater than the magnitude allowed 
by the corresponding type. 

EXCEPTION_FLT_STACK_CHECK 

The stack overflowed or underflowed as the result of a floating-point operation. 
EXCEPTION_FLT_UNDERFLOW 

The exponent of a floating-point operation is less than the magnitude allowed by 
the corresponding type. 

EXCEPTIONJNT DIVIDE_BY_ZERO 

The thread tried to divide an integer value by an integer divisor of zero. 

EXCEPTIONJNTjOVERFLOW 

The result of an integer operation caused a carry out of the most significant bit of 
the result. 

EXCEPTION_PRIV_INSTRUCTION 

The thread tried to execute an instruction whose operation is not allowed in the 
current machine mode. 

EXCEPTION_NONCONTINUABLE _EXCEPTION 

The thread tried to continue execution after a non-continuable exception 
occurred. 

These constants are defined by including WINDOWS . H in the source code. 

The following example is a refinement of the func_ level 1 () function in our previous example. 
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Example: 

#include <windows.h> 

void func_ levelO ( void ) 

{ 

_ try { 

_ try { 

func_ levell (); 

} 

_ except ( 

(GetExceptionCode () == EXCEPTION_ ACCESS_ VIOLATION) 
? EXCEPT ION_ EXECUTE_ HANDLER 
: EXCEPT ION_ CONTINUE_ SEARCH 
) { 

printf ( "Exception handled in func_ levelO\n" ) ; 


} 

_ finally { 

if( AbnormalTermination() ) 

printf ( "Unwind in func_ levelO\n" ) ; 

} 

printf ( "Normal return from func_ levelO\n" ) ; 


In this version, only an "access violation" will be handled by the exception handler in the 

func_ levelO () function. All other types of exceptions will be passed on to main (which can also be 

modified to be somewhat more selective about the types of exceptions it should handle). 

More information on the exception that has occurred can be obtained by the use of the 
GetExceptionlnf ormation () function. The use of this function is also restricted. It can be called 
only from within the filter expression of an exception handler. However, the return value of 
GetExceptionlnf ormation () can be passed as a parameter to a filter function. This is illustrated in 
the following example. 


Example: 

int GetCode( LPEXCEPTION_ POINTERS exceptptrs ) 

{ 

return (exceptptrs->ExceptionRecord->ExceptionCode ) ; 

} 

void func_ levelO ( void ) 

{ 

_ try { 

_ try { 

func_ levell (); 

} 

_ except ( 

(GetCode( GetExceptionlnformation() ) 

== EXCEPTION_ ACCESS_ VIOLATION) 

? EXCEPT ION_ EXECUTE_ HANDLER 
: EXCEPT ION_ CONTINUE_ SEARCH 
) { 

printf ( "Exception handled in func_ levelO\n" ) ; 


} 

_ finally { 

if( AbnormalTermination() ) 

printf ( "Unwind in func_ levelO\n" ) ; 

} 

printf ( "Normal return from func_ levelO\n" ) ; 


The return value of GetExceptionlnf ormation () is a pointer to an EXCEPTION_ POINTERS 
structure that contains pointers to two other structures: an EXCEPTION_ RECORD structure containing a 
description of the exception, and a CONTEXT structure containing the machine-state information. The filter 
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function can make a copy of the structures if a more permanent copy is desired. Check your Win32 SDK 
documentation for more information on these structures. 


13.6 Throwing Your Own Exceptions 

You can use the same exception handling mechanisms to deal with software exceptions raised by your 
application. The RaiseException () function can be used to throw your own application-defined 
exceptions. The first argument to this function is the exception code. It would be wise to define your 
exception codes so that they do not collide with system defined ones. The following example shows how to 
throw an exception. 

Example: 

♦ define MY_ EXCEPTION ( (DWORD) 123L ) 

RaiseException ( MY_ EXCEPTION, 

EXCEPTION_ NONCONTINUABLE, 

0, NULL ); 

In this example, the GetExceptionCode () function, when used in an exception handler filter 
expression or in the body of an exception handler, would return the value 123. 

See the Win32 SDK documentation for more information on the arguments to the RaiseException () 
function. 
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14 Creating ROM-based Applications 


14.1 Introduction 


This chapter provides information for developers who wish to write applications to be placed in read-only 
memory (ROM). 


14.2 ROMable Functions 


The following functions in the Open Watcom C/C++ library are not dependent on any operating system. 
Therefore they can be used for embedded applications. The math functions are listed here because they are 
ROMable, however you must supply a different _ matherr function if you are not running in the DOS, 
OS/2 or Windows NT environment. 


abs 

asctime 

atan2 

atoi 

cabs 

_ clear87 
cosh 
div 
f abs 

_ fmemchr 
_ fmemicmp 
fmod 

_ fpreset 
_ fstrchr 
_ fstrcspn 
_ fstrlwr 
_ fstrncpy 
_ fstrpbrk 
_ fstrset 
_ fstrtok 
hypot 
int86 (1) 
int386x (2) 
isalpha 
isdigit 
isprint 
isupper 

jO 

labs 

lfind 

loglO 

_ lrotr 

matherr 

mbtowc 

memcmp 


acos 

asin 

atexit 

atol 

ceil 

_ control87 
difftime 
_ enable 
floor 
_ fmemcmp 
_ fmemmove 
FP_ OFF 
f rexp 
_ fstrcmp 
_ fstricmp 
_ fstrncat 
_ fstrnicmp 
_ fstrrchr 
_ fstrspn 
_ fstrupr 
inp 

int86x (1) 

intr 

isascii 

isgraph 

ispunct 

isxdigit 

jl 

ldexp 

localeconv 
longjmp 
lsearch 
mblen 
memccpy 
memcpy 


alloca 
atan 
atof 
bsearch 
_ chain_ intr 
cos 

_ disable 
exp 

_ fmemccpy 
_ fmemcpy 
_ fmemset 
FP_ SEG 
_ fstrcat 
_ fstrcpy 
_ fstrlen 
_ fstrncmp 
_ fstrnset 
_ fstrrev 
_ fstrstr 
gmtime 
inpw 

int386 (2) 

isalnum 

iscntrl 

islower 

isspace 

itoa 

jn 

ldiv 

log 

_lrotl 
ltoa 

mbstowcs 

memchr 

memicmp 
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memmove 

memset 

MK_ FP 

modf 

movedata 

offsetof 

outp 

outpw 

pow 

qsort 

rand 

_ rotl 

_ rotr 

segread 

set jmp 

setlocale 

sin 

sinh 

sprintf 

sqrt 

srand 

sscanf 

stackavail 

_ status? 

strcat 

strchr 

strcmp 

strcmpi 

strcoll 

strcpy 

strcspn 

strdup 

strerror 

stricmp 

strlen 

strlwr 

strncat 

strncmp 

strncpy 

strnicmp 

strnset 

strpbrk 

strrchr 

strrev 

strset 

strspn 

strstr 

strtod 

strtok 

strtol 

strtoul 

strupr 

strxfrm 

swab 

tan 

tanh 

tolower 

toupper 

ultoa 

utoa 

va_ arg 

va_ end 

va_ sta: 

vsprintf 

vsscanf 

wcstombs 

wctomb 

yn 

yo 

y! 


* (1) 16-bit libraries 

* (2) 32-bit libraries 

14.3 System-Dependent Functions 

The following functions in the C/C++ library directly or indirectly make use of operating system functions. 
They cannot be used on systems that are not running on one of the DOS, OS/2 or Windows NT operating 
systems. 


abort 

bdos 

_ bios_ equiplist 

_ bios_ printer 

calloc 

chmod 

clock 

cprintf 

cscanf 

delay 

_ dos_ creat 
_ dos_ findnext 
_ dos_ getdiskfree 
_ dos_ getftime 
_ dos_ keep 
_ dos_ setblock 
_ dos_ setfileattr 
_ dos_ setvect 
dup 
eof 

execlp (1) 
execve (1) 


access 

_ beginthread 
_ bios_ keybrd 
_ bios_ serialcom 
cgets 
chsize 
close 
cputs 
ctime 

_ dos_ allocmem 
_ dos_ creatnew 
_ dos_ freemem 
_ dos_ getdrive 
_ dos_ gettime 
_ dos_ open 
_ dos_ setdate 
_ dos_ setftime 
_ dos_ write 
dup 2 

execl (1) 
execlpe (1) 
execvp (1) 


assert 
_ bios_ disk 

_ bios_ memsize 
_ bios_ timeofday 
chdir 
clearerr 
closedir 
creat 
cwait 

_ dos_ close 
_ dos_ findfirst 
_ dos_ getdate 
_ dos_ getfileattr 
_ dos_ getvect 
_ dos_ read 
_ dos_ setdrive 
_ dos_ settime 
dosexterr 
_ endthread 
execle (1) 
execv (1) 
execvpe (1) 
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exit 

_ exit 

fclose 

fcloseall 

fdopen 

f eof 

ferror 

fflush 

_ ffree 

_ fheapchk 

_ fheapgrow (1) 

_ fheapmin 

_ fheapset 

_ fheapshrink 

_ fheapwalk 

fgetc 

fgetpos 

f gets 

filelength 

fileno 

flushall 

_ fmalloc 

f open 

fprintf 

fputc 

fputs 

tread 

_ frealloc 

free 

freopen 

fscant 

f seek 

fsetpos 

f stat 

ftell 

fwrite 

getc 

getch 

getchar 

getche 

getcmd 

getcwd 

getenv 

getpid 

gets 

halloc 

_ heapchk 

_heapgrow 

_ heapmin 

_ heapset 

_ heapshrink 

_ heapwalk 

hf ree 

intdos 

intdosx 

isatty 

kbhit 

localtime 

lock 

locking 

lseek 

_ makepath 

malloc 

mkdir 

mktime 

_ nfree 

_ nheapchk 

_ nheapgrow 

_ nheapmin 

_ nheapset 

_ nheapshrink 

_ nheapwalk 

_ nmalloc 

_ nrealloc 

nosound 

open 

opendir 

perror 

printf 

putc 

putch 

putchar 

putenv 

puts 

raise 

read 

readdir 

realloc 

remove 

rename 

rewind 

rmdir 

sbrk 

scant 

_ searchenv 

setbuf 

setmode 

setvbuf 

signal 

sleep 

sopen 

sound 

spawnl 

spawnle 

spawnlp 

spawnlpe 

spawnv 

spawnve 

spawnvp 

spawnvpe 

_ splitpath 

stat 

strftime 

system 

tell 

time 

tmpfile 

tmpnam 

tzset 

umask 

ungetc 

ungetch 

unlink 

unlock 

utime 

vfprintf 

vfscant 

vprintf 

vscanf 

wait 

write 



* (1) 16-bit libraries 


14.4 Modifying the Startup Code 

Source files are included in the package for the Open Watcom C/C++ application start-up (or initialization) 
sequence. These files are described in the section entitled "The Open Watcom C/C++ Run-time 
Initialization Routines" on page 112. The startup code will have to be modified if you are creating a 
ROMable application or you are not running in a DOS, OS/2, QNX, or Windows environment. 
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14.5 Choosing the Correct Floating-Point Option 

If there will be a math coprocessor chip in your embedded system, then you should compile your 
application with the "fpi87" option and one of "fp2", "fp3" or "fp5" depending on which math coprocessor 
chip will be in your embedded system. If there will not be a math coprocessor chip in your embedded 
system, then you should compile your application with the "fpc" option. You should not use the "fpi" 
option since that will cause extra code to be linked into your application to decode and emulate the 80x87 
instructions contained in your application. 
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A. Use of Environment Variables 


In the Open Watcom C/C++ software development package, a number of environment variables are used. 
This appendix summarizes their use with a particular component of the package. 


A.1 FORCE 


The FORCE environment variable identifies a file that is to be included as part of the source input stream. 
This variable is used by Open Watcom C/C++. 

SET FORCE=[d:][path]filename[.ext] 

The specified file is included as if a 

♦include "[d:][path]filename[.ext]" 

directive were placed at the start of the source file. 

Example: 

C>set force=\watcom\h\common.cnv 
C>wcc report 

The FORCE environment variable can be overridden by use of the Open Watcom C/C++ "fi" option. 


A.2 INCLUDE 


The INCLUDE environment variable describes the location of the C and C++ header files (files with the 
".h" filename extension). This variable is used by Open Watcom C/C++. 

SET include=[d:][path];[d:][path]... 

The INCLLTDE environment string is like the PATH string in that you can specify one or more directories 
separated by semicolons 


A.3 LFN 


The LFN environment variable is checked by the Open Watcom run-time C libraries and it is used to 
control DOS LFN (DOS Long File Name) support. Normally, these libraries will use DOS LFN support if 
it is available on host OS. If you don’t wish to use DOS LFN support, you can define the LFN 
environment variable and setup it’s value to ’N\ Using the "SET" command, define the environment 
variable as follows: 

SET LFN=N 
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Now, when you run your application, the DOS LFN support will be ignored. To undefine the environment 
variable, enter the command: 

SET LFN= 


A.4 LIB 


The use of the WATCOM environment variable and the Open Watcom Linker "SYSTEM" directive is 
recommended over the use of this environment variable. 

The LIB environment variable is used to select the libraries that will be used when the application is linked. 
This variable is used by the Open Watcom Linker (WLINK.EXE). The LIB environment string is like the 
PATH string in that you can specify one or more directories separated by semicolons 

If you have the 286 development system, 16-bit applications can be linked for DOS, Microsoft Windows, 
OS/2, and QNX depending on which libraries are selected. If you have the 386 development system, 32-bit 
applications can be linked for DOS Extender systems, Microsoft Windows and QNX. 


A.5 LIBDOS 


The use of the WATCOM environment variable and the Open Watcom Linker "SYSTEM" directive is 
recommended over the use of this environment variable. 

If you are developing a DOS application, the LIBDOS environment variable must include the location of 
the 16-bit Open Watcom C/C++ DOS library files (files with the ".lib" filename extension). This variable 
is used by the Open Watcom Linker (WLINK.EXE). The default installation directory for the 16-bit Open 
Watcom C/C++ DOS libraries is \WATCOM\LIB286\DOS . The LIBDOS environment variable must 
also include the location of the 16-bit Open Watcom C/C++ math library files. The default installation 
directory for the 16-bit Open Watcom C/C++ math libraries is \WATCOM\LIB2 8 6 . 

Example: 

C>set libdos=c:\watcom\lib286\dos;c:\watcom\lib286 


A.6 LIBWIN 


The use of the WATCOM environment variable and the Open Watcom Linker "SYSTEM" directive is 
recommended over the use of this environment variable. 

If you are developing a 16-bit Microsoft Windows application, the LIBWIN environment variable must 
include the location of the 16-bit Open Watcom C/C++ Windows library files (files with the ".lib" filename 
extension). This variable is used by the Open Watcom Linker (WLINK.EXE). If you are developing a 
32-bit Microsoft Windows application, see the description of the LIBPHAR environment variable. The 
default installation directory for the 16-bit Open Watcom C/C++ Windows libraries is 
\WATCOM\LIB286\WIN . The LIBWIN environment variable must also include the location of the 
16-bit Open Watcom C/C++ math library files. The default installation directory for the 16-bit Open 
Watcom C/C++ math libraries is \WATCOM\LIB2 8 6 . 


296 LIBWIN 




Use of Environment Variables 


Example: 

C>set libwin=c:\watcom\lib286\win;c:\watcom\lib286 


A.7LIB0S2 


The use of the WATCOM environment variable and the Open Watcom Linker "SYSTEM" directive is 
recommended over the use of this environment variable. 

If you are developing an OS/2 application, the LIBOS2 environment variable must include the location of 
the 16-bit Open Watcom C/C++ OS/2 library files (files with the ".lib" filename extension). This variable 
is used by the Open Watcom Linker (WLINK.EXE). The default installation directory for the 16-bit Open 
Watcom C/C++ OS/2 libraries is \WATCOM\LIB2 8 6\OS2 . The LIBOS2 environment variable must 
also include the directory of the OS/2 DOSCALLS . LIB file which is usually \OS2 . The LIBOS2 
environment variable must also include the location of the 16-bit Open Watcom C/C++ math library files. 
The default installation directory for the 16-bit Open Watcom C/C++ math libraries is 
\WATCOM\LIB286. 

Example: 

C>set libos2=c:\watcom\lib286\os2;c:\watcom\lib286;c:\os2 


A.8 LIBPHAR 


The use of the WATCOM environment variable and the Open Watcom Linker "SYSTEM" directive is 
recommended over the use of this environment variable. 

If you are developing a 32-bit Windows or DOS Extender application, the LIBPHAR environment variable 
must include the location of the 32-bit Open Watcom C/C++ DOS Extender library files or the 32-bit Open 
Watcom C/C++ Windows library files (files with the ".lib" filename extension). This variable is used by 
the Open Watcom Linker (WLINK.EXE). The default installation directory for the 32-bit Open Watcom 
C/C++ DOS Extender libraries is \WATCOM\LIB386\DOS . The default installation directory for the 
32-bit Open Watcom C/C++ Windows libraries is \WATCOM\LIB386\WIN. The LIBPHAR 
environment variable must also include the location of the 32-bit Open Watcom C/C++ math library files. 
The default installation directory for the 32-bit Open Watcom C/C++ math libraries is 
\WATCOM\LIB38 6. 

Example: 

C>set libphar=c:\watcom\lib386\dos;c:\watcom\lib386 
or 

C>set libphar=c:\watcom\lib386\win;c:\watcom\lib386 


A.9 N087 


The N087 environment variable is checked by the Open Watcom run-time math libraries that include 
floating-point emulation support. Normally, these libraries will detect the presence of a numeric data 
processor (80x87) and use it. If you have a numeric data processor in your system but you wish to test a 
version of your application that will use floating-point emulation, you can define the N087 environment 
variable. Using the "SET" command, define the environment variable as follows: 

SET N087=l 
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Now, when you run your application, the 80x87 will be ignored. To undefine the environment variable, 
enter the command: 

SET N087= 


A.10PATH 

The PATH environment variable is used by DOS "COMMAND.COM" or OS/2 "CMD.EXE" to locate 
programs. 

PATH [d:][path];[d:][path]... 

The PATH environment variable should include the disk and directory of the Open Watcom C/C++ binary 
program files when using Open Watcom C/C++ and its related tools. 

If your host system is DOS: 

The default installation directory for 16-bit Open Watcom C/C++ and 32-bit Open Watcom C/C++ DOS 
binaries is called \WATCOM\BINW. 

Example: 

Opath c : \watcom\binw; c : \dos; c : \windows 
If your host system is OS/2: 

The default installation directories for 16-bit Open Watcom C/C++ and 32-bit Open Watcom C/C++ OS/2 
binaries are called \WATCOM\BINP and \WATCOM\BINW. 

Example: 

[C:\]path c:\watcom\binp;c:\watcom\binw 
If your host system is Windows NT: 

The default installation directories for 16-bit Open Watcom C/C++ and 32-bit Open Watcom C/C++ 
Windows NT binaries are called \WATCOM\BINNT and \WATCOM\BINW. 

Example: 

Opath c:\watcom\binnt;c:\watcom\binw 
The PATH environment variable is also used by the following programs in the described manner. 

1. Open Watcom Compile and Link to locate the 16-bit Open Watcom C/C++ and 32-bit Open 
Watcom C/C++ compilers and the Open Watcom Linker. 

2. "WD.EXE" to locate programs and debugger command files. 
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A.11 TMP 

The TMP environment variable describes the location (disk and path) for temporary files created by the 
16-bit Open Watcom C/C++ and 32-bit Open Watcom C/C++ compilers and the Open Watcom Linker. 

SET TMP=[d:][path] 

Normally, Open Watcom C/C++ will create temporary spill files in the current directory. However, by 
defining the TMP environment variable to be a certain disk and directory, you can tell Open Watcom 
C/C++ where to place its temporary files. The same is true of the Open Watcom Linker temporary file. 

Consider the following definition of the TMP environment variable. 

Example: 

C>set tmp=d:\watcom\tmp 

The Open Watcom C/C++ compiler and Open Watcom Linker will create its temporary files in 
d:\watcom\tmp. 


A.12 WATCOM 

In order for the Open Watcom Linker to locate the 16-bit Open Watcom C/C++ and 32-bit Open Watcom 
C/C++ library files, the WATCOM environment variable should be defined. The WATCOM environment 
variable is used to locate the libraries that will be used when the application is linked. The default directory 
for 16-bit Open Watcom C/C++ and 32-bit Open Watcom C/C++ files is "YWATCOM". 

Example: 

C>set watcom=c:\watcom 


A.13 WCC 


The WCC environment variable can be used to specify commonly-used options for the 16-bit C compiler. 
SET WCC=-optionl -option2 ... 

These options are processed before options specified on the command line. The following example defines 
the default options to be "dl" (include line number debug information in the object file) and "ox" (compile 
for maximum number of code optimizations). 

Example: 

C>set wcc=-dl -ox 

Once the WCC environment variable has been defined, those options listed become the default each time 
the WCC command is used. 
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A.14 WCC386 

The WCC386 environment variable can be used to specify commonly-used options for the 32-bit C 
compiler. 

SET WCC386=-optionl -option2 ... 

These options are processed before options specified on the command line. The following example defines 
the default options to be "dl" (include line number debug information in the object file) and "ox" (compile 
for maximum number of code optimizations). 

Example: 

C>set wcc386=-dl -ox 

Once the WCC386 environment variable has been defined, those options listed become the default each 
time the WCC386 command is used. 


A.15WCL 

The WCL environment variable can be used to specify commonly-used WCL options. 

SET WCL=-optionl -option2 ... 

These options are processed before options specified on the command line. The following example defines 
the default options to be "mm" (compile code for medium memory model), "dl" (include line number 
debug information in the object file), and "ox" (compile for maximum number of code optimizations). 

Example: 

C>set wcl=-mm -dl -ox 

Once the WCL environment variable has been defined, those options listed become the default each time 
the WCL command is used. 


A. 16 WCL386 


The WCL386 environment variable can be used to specify commonly-used WCL386 options. 

SET WCL386=-optionl -option2 ... 

These options are processed before options specified on the command line. The following example defines 
the default options to be "3s" (compile code for stack-based argument passing convention), "dl" (include 
line number debug information in the object file), and "ox" (compile for maximum number of code 
optimizations). 
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Example: 

C>set wcl386=-3s -dl -ox 

Once the WCL386 environment variable has been defined, those options listed become the default each 
time the WCL386 command is used. 


A.17 WCGMEMORY 

The WCGMEMORY environment variable may be used to request a report of the amount of memory used 
by the compiler’s code generator for its work area. 

Example: 

C>set WCGMEMORY=? 

When the memory amount is "?" then the code generator will report how much memory was used to 
generate the code. 

It may also be used to instruct the compiler’s code generator to allocate a fixed amount of memory for a 
work area. 

Example: 

C>set WCGMEMORY=128 

When the memory amount is "nnn" then exactly "nnnK" bytes will be used. In the above example, 128K 
bytes is requested. If less than "nnnK" is available then the compiler will quit with a fatal error message. If 
more than "nnnK" is available then only "nnnK" will be used. 

There are two reasons why this second feature may be quite useful. In general, the more memory available 
to the code generator, the more optimal code it will generate. Thus, for two personal computers with 
different amounts of memory, the code generator may produce different (although correct) object code. If 
you have a software quality assurance requirement that the same results (i.e., code) be produced on two 
different machines then you should use this feature. To generate identical code on two personal computers 
with different memory configurations, you must ensure that the WCGMEMORY environment variable is 
set identically on both machines. 

The second reason where this feature is useful is on virtual memory paging systems (e.g., OS/2) where an 
unlimited amount of memory can be used by the code generator. If a very large module is being compiled, 
it may take a very long time to compile it. The code generator will continue to allocate more and more 
memory and cause an excessive amount of paging. By restricting the amount of memory that the code 
generator can use, you can reduce the amount of time required to compile a routine. 

A.18WD 


The WD environment variable can be used to specify commonly-used Open Watcorn Debugger options. 
This environment variable is not used by the Windows version of the debugger, WDW. 

SET WD=-optionl -option2 . . . 

These options are processed before options specified on the command line. The following example defines 
the default options to be "noinvoke" (do not execute the profile . dbg file) and "reg=10" (retain up to 10 
register sets while tracing). 
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Example: 

C>set wd=-noinvoke -reg#10 

Once the WD environment variable has been defined, those options listed become the default each time the 
WD command is used. 


A.19WDW 

The WDW environment variable can be used to specify commonly-used Open Watcorn Debugger options. 
This environment variable is used by the Windows version of the debugger, WDW. 

SET WDW=-optionl -option2 .. . 

These options are processed before options specified in the WDW prompt dialogue box. The following 
example defines the default options to be "noinvoke" (do not execute the profile . dbg file) and 
"reg=10" (retain up to 10 register sets while tracing). 

Example: 

C>set wdw=-noinvoke -reg#10 

Once the WDW environment variable has been defined, those options listed become the default each time 
the WDW command is used. 


A.20 WLANG 

The WLANG environment variable can be used to control which language is used to display diagnostic 
and program usage messages by various Open Watcom software tools. The two currently-supported values 
for this variable are "English" or "Japanese". 

SET WLANG=English 
SET WLANG=Japanese 

Alternatively, a numeric value of 0 (for English) or 1 (for Japanese) can be specified. 

Example: 

C>set wlang=0 

By default, Japanese messages are displayed when the current codepage is 932 and English messages are 
displayed otherwise. Normally, use of the WLANG environment variable should not be required. 


A.21 WPP 


The WPP environment variable can be used to specify commonly-used options for the 16-bit C++ 
compiler. 

SET WPP=-optionl -option2 . . . 

These options are processed before options specified on the command line. The following example defines 
the default options to be "dl" (include line number debug information in the object file) and "ox" (compile 
for maximum number of code optimizations). 
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Example: 

C>set wpp=-dl -ox 

Once the WPP environment variable has been defined, those options listed become the default each time 
the WPP command is used. 


A.22 WPP386 


The WPP386 environment variable can be used to specify commonly-used options for the 32-bit C++ 
compiler. 

SET WPP386=-optionl -option2 ... 

These options are processed before options specified on the command line. The following example defines 
the default options to be "dl" (include line number debug information in the object file) and "ox" (compile 
for maximum number of code optimizations). 

Example: 

C>set wpp386=-dl -ox 

Once the WPP386 environment variable has been defined, those options listed become the default each 
time the WPP386 command is used. 
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B. Open Watcom C Diagnostic Messages 


The following is a list of all warning and error messages produced by the Open Watcom C compilers. 
Diagnostic messages are issued during compilation and execution. 

The messages listed in the following sections contain references to %s, %d and %u . They represent 
strings that are substituted by the Open Watcom C compilers to make the error message more exact. %d 
and %u represent a string of digits; %s a string, usually a symbolic name. 

Consider the following program, named err. c, which contains errors. 

Example: 

♦include <stdio.h> 

void main() 

1 

int i; 
float i; 

i = 383; 
x = 13143.0; 

printf( "Integer value is %d\n", i ); 
printf( "Floating-point value is %f\n", x ); 

} 

If we compile the above program, the following messages will appear on the screen. 

err.c (6) : Error! E1034: Symbol 'i' already defined 

err.c(9) : Error! E1011: Symbol 'x' has not been declared 

err.c: 12 lines, included 191, 0 warnings, 2 errors 

The diagnostic messages consist of the following information: 

1. the name of the file being compiled, 

2. the line number of the line containing the error (in parentheses), 

3. a message number, and 

4. text explaining the nature of the error. 

In the above example, the first error occurred on line 6 of the file err.c. Error number 1034 (with the 
appropriate substitutions) was diagnosed. The second error occurred on line 9 of the file err.c. Error 
number 1011 (with the appropriate substitutions) was diagnosed. 

The following sections contain a complete list of the messages. Run-time messages (messages displayed 
during execution) do not have message numbers associated with them. 


Open Watcom C Diagnostic Messages 305 





Appendices 


B.1 Warning Level 1 Messages 

W100 Parameter %d contains inconsistent levels of indirection 

The function is expecting something like char * * and it is being passed a char * for 

instance. 

W101 Non-portable pointer conversion 

This message is issued whenever you convert a non-zero constant to a pointer. 

W102 Type mismatch (warning) 

This message is issued for a function return value, an assignment or operators where one 
type is pointer and second one is non-pointer type. 

W103 Parameter count does not agree with previous definition (warning) 

You have either not enough parameters or too many parameters in a call to a function. If 
the function is supposed to have a variable number of parameters, then you can ignore this 
warning, or you can change the function declaration and prototypes to use the to 
indicate that the function indeed takes a variable number of parameters. 

W104 Inconsistent levels of indirection 

This occurs in an assignment or return statement when one of the operands has more levels 
of indirection than the other operand. For example, a char * * is being assigned to a 
char *. 

Solution: Correct the levels of indirection or use a void * . 

W105 Assignment found in boolean expression 

An assignment of a constant has been detected in a boolean expression. For example: "if( 
var = 0 )". It is most likely that you want to use "==" for testing for equality. 

W106 Constant out of range - truncated 

This message is issued if a constant cannot be represented in 32 bits or if a constant is 
outside the range of valid values that can be assigned to a variable. 

W107 Missing return value for function ’%s’ 

A function has been declared with a function return type, but no return statement was 
found in the function. Either add a return statement or change the function return type to 
void. 


306 Warning Level 1 Messages 




Open Watcom C Diagnostic Messages 


W108 


W109 


W110 


Will 


W112 


W113 


W114 


W115 


W116 


Duplicate typedef already defined 

A duplicate typedef is not allowed in ISO C. This warning is issued when compiling with 
extensions enabled. You should delete the duplicate typedef definition. 

not used 

unused message 

’fortran ’ pragma not defined 

You have used the fortran keyword in your program, but have not defined a #pragma for 
fortran. 

Meaningless use of an expression 

The line contains an expression that does nothing useful. In the example "i = (1,5);", the 
expression "1," is meaningless. 

Pointer truncated 

A far pointer is being passed to a function that is expecting a near pointer, or a far pointer is 
being assigned to a near pointer. 

Pointer type mismatch 

You have two pointers that either point to different objects, or the pointers are of different 
size, or they have different modifiers. 

Missing semicolon 

You are missing the semicolon on the field definition just before the right curly brace 


&array may not produce intended result 

The type of the expression "&array" is different from the type of the expression "array". 
Suppose we have the declaration char buf f er [ 80 ] Then the expression (&buf fer 
+ 3) will be evaluated as (buffer + 3 * sizeof (buffer) ) which is (buffer 
+ 3 * 80) and not (buffer + 3 * 1) which is what most people expect to happen. 
The address of operator "&" is not required for getting the address of an array. 

Attempt to return address of auto variable 

This warning usually indicates a serious programming error. When a function exits, the 
storage allocated on the stack for auto variables is released. This storage will be 
overwritten by further function calls and/or hardware interrupt service routines. Therefore, 
the data pointed to by the return value may be destroyed before your program has a chance 
to reference it or make a copy of it. 
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W117 


W118 


W119 


W120 


W121 


W122 


W123 


’##’ tokens did not generate a single token (rest discarded) 

When two tokens are pasted together using ##, they must form a string that can be parsed 
as a single token. 

Label ’%s’ has been defined but not referenced 

You have defined a label that is not referenced in a goto statement. It is possible that you 
are missing the case keyword when using an enumerated type name as a case in a switch 
statement. If not, then the label can be deleted. 

Address of static function ’%s’ has been taken 

This warning may indicate a potential problem when the program is overlayed. 
lvalue cast is not standard C 

A cast operation does not yield an lvalue in ISO C. However, to provide compatibility with 
code written prior to the availability of ISO compliant C compilers, if an expression was an 
lvalue prior to the cast operation, and the cast operation does not cause any conversions, the 
compiler treats the result as an lvalue and issues this warning. 

Text following pre-processor directives is not standard C 

Arbitrary text is not allowed following a pre-processor directive. Only comments are 
allowed following a pre-processor directive. 

Literal string too long for array - truncated 

The supplied literal string contains more characters than the specified dimension of the 
array. Either shorten the literal string, or increase the dimension of the array to hold all of 
the characters from the literal string. 

’//’ style comment continues on next line 

The compiler has detected a line continuation during the processing of a C++ style 
comment ("//"). The warning can be removed by switching to a C style comment ("/**/"). 
If you require the comment to be terminated at the end of the line, make sure that the 
backslash character is not the last character in the line. 

Example: 

♦define XX 23 // comment start \ 

comment \ 

end 

int x = XX; // comment start .. 
comment end 
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W124 


W125 


W126 


W127 


W128 


W129 


W130 


W131 


Comparison result always %d 

The line contains a comparison that is always true (1) or false (0). For example comparing 
an unsigned expression to see if it is >= 0 or < 0 is redundant. Check to see if the 
expression should be signed instead of unsigned. 

Nested include depth of%d exceeded 

The number of nested include files has reached a preset limit, check for recursive include 
statements. 

Constant must be zero for pointer compare 

A pointer is being compared using == or != to a non-zero constant. 
trigraph found in string 

Trigraph expansion occurs inside a string literal. This warning can be disabled via the 
command line or #pragma warning directive. 

Example: 

// string expands to "(?]?????"! 
char *e = "(???)???-????"; 

// possible work-arounds 

char *f = "(" "???" ")" "???" "????"; 

char *g = "(\?\?\?)\?\?\?-\?\?\?\?"; 

%d padding byte(s) added 

The compiler has added slack bytes to align a member to the correct offset. 

#endif matches #ifin different source file ’%s’ 

This warning may indicate a #endif nesting problem since the traditional usage of #if 
directives is confined to the same source file. This warning may often come before an error 
and it is hoped will provide information to solve a preprocessing directive problem. 

Possible loss of precision 

This warning indicates that you may be converting a argument of one size to another, 
different size. For instance, you may be losing precision by passing a long argument to a 
function that takes a short. This warning is initially disabled. It must be explicitly enabled 
with #pragma enable_message( 130) or option "-wce=130". It can be disabled later by 
using tfpragma disable_message( 130). 

No prototype found for function ’%s’ 

A reference for a function appears in your program, but you do not have a prototype for 
that function defined. Implicit prototype will be used, but this will cause problems if the 
assumed prototype does not match actual function definition. 
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W132 


W133 


W134 


W135 


No storage class or type specified 

When declaring a data object, either storage class or data type must be given. If no type is 
specified, int is assumed. If no storage class is specified, the default depends on scope (see 
the C Language Reference for details). For instance 

Example: 

auto i; 

is a valid declaration, as is 

Example: 

short i; 

However, 

Example: 

i; 


is not a correctly formed declaration. 

Symbol name truncated for ’%s’ 

Symbol is longer than the object file format allows and has been truncated to fit. Maximum 
length is 255 characters for OMF and 1024 characters for COFF or ELF object files. 

Shift amount negative 

The right operand of a left or right shift operator is a negative value. The result of the shift 
operation is undefined. 

Example: 

int a = 1 << -2 ; 

The value of ’a’ in the above example is undefined. 

Shift amount too large 

The right operand of a left or right shift operator is a value greater than or equal to the 
width in bits of the type of the promoted left operand. The result of the shift operation is 
undefined. 

Example: 

int a = 1 >> 123; 

The value of ’a’ in the above example is undefined. 
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W136 Comparison equivalent to ’unsigned == 0’ 

Comparing an unsigned expression to see whether it is <= 0 is equivalent to testing for == 

0. Check to see if the expression should be signed instead of unsigned. 

W137 Extern function ’%s’ redeclared as static 

The specified function was either explicitly or implicitly declared as extern and later 
redeclared as static. This is not allowed in ISO C and may produce unexpected results with 
ISO compliant compilers. 

Example: 

int bar( void ); 

void foo( void ) 

{ 

bar (); 

} 

static int bar( void ) 

{ 

return ( 0 ) ; 

} 

W138 No newline at end of file 

ISO C requires that a non-empty source file must include a newline character at the end of 
the last line. If no newline was found, it will be automatically inserted. 

W139 Divisor for modulo or division operation is zero 

The right operand of a division or modulo operation is zero. The result of this operation is 
undefined and you should rewrite the offending code to avoid divisions by zero. 

Example: 

int foo( void ) 

{ 

return ( 7 / 0 ) ; 

} 


B.2 Warning Level 2 Messages 

W200 ’%s ’ has been referenced but never assigned a value 

You have used the variable in an expression without previously assigning a value to that 
variable. 
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W201 Unreachable code 

The statement will never be executed, because there is no path through the program that 
causes control to reach this statement. 

W202 Symbol ’%s ’ has been defined, but not referenced 

There are no references to the declared variable. The declaration for the variable can be 
deleted. 

In some cases, there may be a valid reason for retaining the variable. You can prevent the 
message from being issued through use of # pragma ojf(unreferenced). 

W203 Preprocessing symbol ’%s’ has not been declared 

The symbol has been used in a preprocessor expression. The compiler assumes the symbol 
has a value of 0 and continues. A # define may be required for the symbol, or you may 
have forgotten to include the file which contains a #def ine for the symbol. 

B.3 Warning Level 3 Messages 

W300 Nested comment found in comment started on line %u 

While scanning a comment for its end, the compiler detected / * for the start of another 
comment. Nested comments are not allowed in ISO C. You may be missing the */ for the 
previous comment. 

W301 not used 

unused message 

W302 Expression is only useful for its side effects 

You have an expression that would have generated the warning "Meaningless use of an 
expression", except that it also contains a side-effect, such as ++, —, or a function call. 

W303 Parameter ’%s’ has been defined, but not referenced 

There are no references to the declared parameter. The declaration for the parameter can be 
deleted. Since it is a parameter to a function, all calls to the function must also have the 
value for that parameter deleted. 

In some cases, there may be a valid reason for retaining the parameter. You can prevent the 
message from being issued through use of # pragma ojf(unreferenced). 

This warning is initially disabled. It must be specifically enabled with #pragma 
enable_message(303) or option "-wce=303". It can be disabled later by using tfpragma 
disable _message(303). 


312 Warning Level 3 Messages 




Open Watcom C Diagnostic Messages 


W304 


W305 


W306 


W307 


W308 


W309 


Return type ’int’ assumed for function ’%s’ 

If a function is declared without specifying return type, such as 

Example: 

foo( void ); 

then its return type will be assumed to be int 
Type ’int’ assumed in declaration of ’%s’ 

If an object is declared without specifying its type, such as 
Example: 

register count; 
then its type will be assumed to be int 
Assembler warning: ’%s ’ 

A problem has been detected by the in-line assembler. The message indicates the problem 
detected. 

Obsolete non-prototype declarator 

Function parameter declarations containing only empty parentheses, that is, non-prototype 
declarations, are an obsolescent language feature. Their use is dangerous and discouraged. 

Example: 

int func(); 

Unprototyped function ’%s’ called 

A call to an unprototyped function was made, preventing the compiler from checking the 
number of function arguments and their types. Use of unprototyped functions is 
obsolescent, dangerous and discouraged. 

Example: 

int func(); 

void bar( void ) 

{ 

func( 4, "s" ); /* possible argument mismatch */ 

} 

Unprototyped function indirectly called 

An indirect call to an unprototyped function was made, preventing the compiler from 
checking the number of function arguments and their types. Use of unprototyped functions 
is obsolescent, dangerous and discouraged. 
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Example: 

int (*func)(); 

void bar( void ) 

{ 

func( 4, "s" ); /* possible argument mismatch */ 

} 

W310 Pointer truncated during cast 

A far pointer is being cast to a near pointer, losing segment information in the process. 
Example: 

char_near *foo( char_far *fs ) 

{ 

return( (char _near *)fs ); 

} 


B.4 Warning Level 4 Messages 

W400 Array subscript is of type plain char 

Array subscript expression is of plain char type. Such expression may be interpreted as 
either signed or unsigned, depending on compiler settings. A different type should be 
chosen instead of char. A cast may be used in cases when the value of the expression is 
known to never fall outside the 0-127 range. 

Example: 

int foo( int arr[], char c ) 

{ 

return ( arr[c] ); 

} 


B.5 Error Messages 

E1000 BREAK must appear in while, do, for or switch statement 

A break statement has been found in an illegal place in the program. You may be missing 
an opening brace { for a while, do, for or switch statement. 

E1001 CASE must appear in switch statement 

A case label has been found that is not inside a switch statement. 
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E1002 


E1003 


E1004 


E1005 


E1006 


E1007 


E1008 


E1009 


E1010 


E1011 


CONTINUE must appear in while, do or for statement 

The continue statement must be inside a while, do or for statement. You may have too 
many } between the while, do or for statement and the continue statement. 

DEFAULT must appear in switch statement 

A default label has been found that is not inside a switch statement. You may have too 
many } between the start of the switch and the default label. 

Misplaced ’}’ or missing earlier ’{’ 

An extra } has been found which cannot be matched up with an earlier { . 

Misplaced #elif directive 

The #elif directive must be inside an #if preprocessing group and before the #else 
directive if present. 

Misplaced #else directive 

The #else directive must be inside an #if preprocessing group and follow all #elif 
directives if present. 

Misplaced #endif directive 

A preprocessing directive has been found without a matching #if directive. You either 
have an extra or you are missing an #if directive earlier in the file. 

Only 1 DEFAULT per switch allowed 

You cannot have more than one default label in a switch statement. 

Expecting ’%s ’ but found ’%s ’ 

A syntax error has been detected. The tokens displayed in the message should help you to 
determine the problem. 

Type mismatch 

For pointer subtraction, both pointers must point to the same type. For other operators, 
both expressions must be assignment compatible. 

Symbol ’%s ’ has not been declared 

The compiler has found a symbol which has not been previously declared. The symbol 
may be spelled differently than the declaration, or you may need to #include a header 
file that contains the declaration. 
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E1012 


E1013 


E1014 


E1015 


E1016 


E1017 


E1018 


E1019 


E1020 


E1021 


Expression is not a function 

The compiler has found an expression that looks like a function call, but it is not defined as 
a function. 

Constant variable cannot be modified 

An expression or statement has been found which modifies a variable which has been 
declared with the const keyword. 

Left operand must be an ’lvalue ’ 

The operand on the left side of an "=" sign must be a variable or memory location which 
can have a value assigned to it. 

’%s ’ is already defined as a variable 

You are trying to declare a function with the same name as a previously declared variable. 
Expecting identifier 

The token following and "." operators must be the name of an identifier which appears 
in the struct or union identified by the operand preceding the and "." operators. 

Label ’%s’ already defined 

All labels within a function must be unique. 

Label ’%s’ not defined in function 

A goto statement has referenced a label that is not defined in the function. Add the 
necessary label or check the spelling of the label(s) in the function. 

Tag ’%s’ already defined 

All struct, union and enum tag names must be unique. 

Dimension cannot be 0 or negative 

The dimension of an array must be positive and non-zero. 

Dimensions of multi-dimension array must be specified 

All dimensions of a multiple dimension array must be specified. The only exception is the 
first dimension which can declared as "[]". 
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E1022 


E1023 


E1024 


E1025 


E1026 


E1027 


E1028 


E1029 


E1030 


E1031 


E1032 


Missing or misspelled data type near ’%s’ 

The compiler has found an identifier that is not a predefined type or the name of a 
"typedef'. Check the identifier for a spelling mistake. 

Storage class of parameter must be register or unspecified 

The only storage class allowed for a parameter declaration is register. 

Declared symbol ’%s’ is not in parameter list 

Make sure that all the identifiers in the parameter list match those provided in the 
declarations between the start of the function and the opening brace 

Parameter ’%s’ already declared 

A declaration for the specified parameter has already been processed. 

Invalid declarator 

A syntax error has occurred while parsing a declaration. 

Invalid storage class for function 

If a storage class is given for a function, it must be static or extern. 

Variable ’%s’ cannot be void 
You cannot declare a void variable. 

Expression must be ’pointer to ... ’ 

An attempt has been made to de-reference (*) a variable or expression which is not 
declared to be a pointer. 

Cannot take the address of an rx’alue 

You can only take the address of a variable or memory location. 

Name ’%s’ not found in struct/union %s 

The specified identifier is not one of the fields declared in the struct or union. Check that 
the field name is spelled correctly, or that you are pointing to the correct struct or union. 

Expression for ’. ’ must be a ’structure’ or ’union ’ 

The compiler has encountered the pattern "expression" "." "field_name" where the 
expression is not a struct or union type. 
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E1033 


E1034 


E1035 


E1036 


E1037 


E1038 


E1039 


E1040 


E1041 


E1042 


E1043 


Expression for ’-> ’ must be ’pointer to struct or union ’ 

The compiler has encountered the pattern "expression" "field_name" where the 
expression is not a pointer to struct or union type. 

Symbol ’%s ’ already defined 

The specified symbol has already been defined. 

static function ’%s’ has not been defined 

A prototype has been found for a static function, but a definition for the static function has 
not been found in the file. 

Right operand of ’%s’ is a pointer 

The right operand of "+=" and cannot be a pointer. The right operand of" cannot 
be a pointer unless the left operand is also a pointer. 

Type cast must be a scalar type 

You cannot type cast an expression to be a struct, union, array or function. 

Expecting label for goto statement 

The goto statement requires the name of a label. 

Duplicate case value ’%s’ found 

Every case value in a switch statement must be unique. 

Field width too large 

The maximum field width allowed is 16 bits. 

Field width ofO with symbol not allowed 
A bit field must be at least one bit in size. 

Field width must be positive 

You cannot have a negative field width. 

Invalid type specified for bit field 

The types allowed for bit fields are signed or unsigned varieties of char, short and int. 
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E1044 


E1045 


E1046 


E1047 


E1048 


E1049 


E1050 


E1051 


E1052 


E1053 


E1054 


Variable ’%s’ has incomplete type 
A full definition of a struct or union has not been given. 

Subscript on non-array 

One of the operands of "[]" must be an array. 

Incomplete comment started on line %u 

The compiler did not find * / to mark the end of a comment. 

Argument for # must be a macro parm 

The argument for the stringize operator "#" must be a macro parameter. 

Unknown preprocessing directive ’#%s’ 

An unrecognized preprocessing directive has been encountered. Check for correct spelling. 
Invalid #include directive 

A syntax error has been encountered in a #include directive. 

Not enough parameters given for macro ’%s’ 

You have not supplied enough parameters to the specified macro. 

Not expecting a return value for function ’%s’ 

The specified function is declared as a void function. Delete the return statement, or 
change the type of the function. 

Expression has void type 

You tried to use the value of a void expression inside another expression. 

Cannot take the address of a bitfield 

The smallest addressable unit is a byte. You cannot take the address of a bit field. 
Expression must be constant 

The compiler expects a constant expression. This message can occur during static 
initialization if you are trying to initialize a non-pointer type with an address expression. 
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E1055 


E1056 


E1057 


E1058 


E1059 


E1060 


E1061 


E1062 


E1063 


E1064 


Unable to open ’%s’ 

The file specified in an #include directive could not be located. Make sure that the file 
name is spelled correctly, or that the appropriate path for the file is included in the list of 
paths specified in the INCLUDE environment variable or the "-I" option on the command 
line. 

Too many parameters given for macro ’%s’ 

You have supplied too many parameters for the specified macro. 

Modifiers disagree with previous definition of ’%s’ 

You have more than one definition or prototype for the variable or function which have 
different type modifiers. 

Cannot use typedef ’%s’ as a variable 

The name of a typedef has been found when an operand or operator is expected. If you are 
trying to use a type cast, make sure there are parentheses around the type, otherwise check 
for a spelling mistake. 

Invalid storage class for non-local variable 

A variable with module scope cannot be defined with the storage class of auto or register. 
Invalid type 

An invalid combination of the following keywords has been specified in a type declaration: 
const, volatile, signed, unsigned, char, int, short, long, float and double. 

Expecting data or function declaration, but found ’%s’ 

The compiler is expecting the start of a data or function declaration. If you are only part 
way through a function, then you have too many closing braces "}". 

Inconsistent return type for function ’%s’ 

Two prototypes for the same function disagree. 

Missing operand 

An operand is required in the expression being parsed. 

Out of memory 

The compiler has run out of memory to store information about the file being compiled. 

Try reducing the number of data declarations and or the size of the file being compiled. Do 
not #include header files that are not required. 

For the 16-bit C compiler, the "-d2" option causes the compiler to use more memory. Try 
compiling with the "-dl" option instead. 
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E1065 


E1066 


E1067 


E1068 


E1069 


E1070 


E1071 


Invalid character constant 

This message is issued for an improperly formed character constant. 

Cannot perform operation with pointer to void 

You cannot use a "pointer to void" with the operators +, ++, —, += and -=. 

Cannot take address of variable with storage class ’register’ 

If you want to take the address of a local variable, change the storage class from register to 
auto. 

Variable ’%s’ already initialized 

The specified variable has already been statically initialized. 

String literal not terminated before end of line 
A string literal is enclosed by double quote " characters. 

The compiler did not find a closing double quote " or line continuation character \ before 
the end of a line or before the end of the source file. 

Data for aggregate type must be enclosed in curly braces 

When an array, struct or union is statically initialized, the data must be enclosed in curly 
braces {}. 

Type of parameter %d does not agree with previous definition 

The type of the specified parameter is incompatible with the prototype for that function. 
The following example illustrates a problem that can arise when the sequence of 
declarations is in the wrong order. 

Example: 

/* Uncommenting the following line will 
eliminate the error */ 

/* struct foo; */ 

void fnl( struct foo * ); 

struct foo { 

int a,b; 

} ; 


void fnl( struct foo *bar ) 

{ 

fn2( bar ); 

} 

The problem can be corrected by reordering the sequence in which items are declared (by 
moving the description of the structure foo ahead of its first reference or by adding the 
indicated statement). This will assure that the first instance of structure foo is defined at 
the proper outer scope. 
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E1072 


E1073 


E1074 


E1075 


E1076 


E1077 


E1078 


E1079 


E1080 


E1081 


Storage class disagrees with previous definition of ’%s’ 

The previous definition of the specified variable has a storage class of static. The current 
definition must have a storage class of static or extern. 

Alternatively, a variable was previously declared as extern and later defined as static. 
Invalid option ’%s’ 

The specified option is not recognized by the compiler. 

Invalid optimization option ’%s’ 

The specified option is an unrecognized optimization option. 

Invalid memory model ’%s’ 

Memory model option must be one of "ms", "mm", "me", "ml", "rnh" or "mf" which selects 
the Small, Medium, Compact, Large, Huge or Flat memory model. 

Missing semicolon at end of declaration 

You are missing a semicolon on the declaration just before the left curly brace "{". 
Missing ’}’ 

The compiler detected end of file before finding a right curly brace "}" to end the current 
function. 

Invalid type for switch expression 

The type of a switch expression must be integral. 

Expression must be integral 
An integral expression is required. 

Expression must be arithmetic 

Both operands of the "/" and operators must be arithmetic. The operand of the 

unary minus must also be arithmetic. 

Expression must be scalar type 

A scalar expression is required. 
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E1082 


E1083 


E1084 


E1085 


E1086 


E1087 


E1088 


E1089 


E1090 


E1091 


Statement required after label 

The C language definition requires a statement following a label. You can use a null 
statement which consists of just a semicolon 

Statement required after ’do’ 

A statement is required between the do and while keywords. 

Statement required after ’case’ 

The C language definition requires a statement following a case label. You can use a null 
statement which consists of just a semicolon 

Statement required after ’default’ 

The C language definition requires a statement following a default label. You can use a 
null statement which consists of just a semicolon (";")• 

Expression too complicated, split it up and try again 

The expression contains too many levels of nested parentheses. Divide the expression up 
into two or more sub-expressions. 

Missing matching #endif directive 

You are missing a to terminate a #if, #ifdef or #ifndef preprocessing directive. 
Invalid macro definition, missing ) 

The right parenthesis ")" is required for a function-like macro definition. 

Missing ) for expansion of’%s’ macro 

The compiler encountered end-of-file while collecting up the argument for a function-like 
macro. A right parenthesis ")" is required to mark the end of the argument(s) for a 
function-like macro. 

Invalid conversion 

A struct or union cannot be converted to anything. A float or double cannot be converted 
to a pointer and a pointer cannot be converted to a float or double. 

%s 

This is a user message generated with the terror preprocessing directive. 
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E1092 


E1093 


E1094 


E1095 


E1096 


E1097 


E1098 


E1099 


E1100 


E1101 


Cannot define an array of functions 

You can have an array of pointers to functions, but not an array of functions. 

Function cannot return an array 

A function cannot return an array. You can return a pointer to an array. 

Function cannot return a function 

You cannot return a function. You can return a pointer to a function. 

Cannot take address of local variable in static initialization 
You cannot take the address of an auto variable at compile time. 

Inconsistent use of return statements 

The compiler has found a return statement which returns a value and a return statement 
that does not return a value both in the same function. The return statement which does 
not return a value needs to have a value specified to be consistent with the other return 
statement in the function. 

Missing ? or misplaced: 

The compiler has detected a syntax error related to the "?" and operators. You may 
need parenthesis around the expressions involved so that it can be parsed correctly. 

Maximum struct or union size is 64K 

The size of a struct or union is limited to 64K so that the compiler can represent the offset 
of a member in a 16-bit register. 

Statement must be inside function. Probable cause: missing { 

The compiler has detected a statement such as for, while, switch, etc., which must be inside 
a function. You either have too many closing braces "}" or you are missing an opening 
brace " {" earlier in the function. 

Definition of macro ’%s’ not identical to previous definition 

If a macro is defined more than once, the definitions must be identical. If you want to 
redefine a macro to have a different definition, you must #undef it before you can define 
it with a new definition. 

Cannot #undef ’%s ’ 

The special macros_ LINE_,_FILE_,_DATE_,_TIME_, 

_STDC_,_FUNCTION__anflunc_, and the identifier "defined", cannot be 

deleted by the tundef directive. 
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El 102 


E1103 


E1104 


E1105 


E1106 


E1107 


El 108 


E1109 


E1110 


Ellll 


E1112 


Cannot ftdefine the name ’defined’ 

You cannot define a macro called defined. 

## must not be at start or end of replacement tokens 

There must be a token on each side of the "##" (token pasting) operator. 

Type cast not allowed in #if or #elif expression 
A type cast is not allowed in a preprocessor expression. 

’sizeof not allowed in #if or #elif expression 

The sizeof operator is not allowed in a preprocessor expression. 

Cannot compare a struct or union 

A struct or union cannot be compared with "==" or "!=". You must compare each member 
of a struct or union to determine equality or inequality. If the struct or union is packed 
(has no holes in it for alignment purposes) then you can compare two structs using 
memcmp. 

Enumerator list cannot be empty 

You must have at least one identifier in an enum list. 

Invalid floating-point constant 

The exponent part of the floating-point constant is not formed correctly. 

Cannot take sizeof a bit field 

The smallest object that you can ask for the size of is a char. 

Cannot initialize variable with storage class of extern 

A storage class of extern is used to associate the variable with its actual definition 
somewhere else in the program. 

Invalid storage class for parameter 

The only storage class allowed for a parameter is register. 

Initializer list cannot be empty 

An initializer list must have at least one item specified. 
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E1113 


E1114 


E1115 


E1116 


El 117 


E1118 


E1119 


E1120 


E1121 


E1122 


Expression has incomplete type 

An attempt has been made to access a struct or union whose definition is not known, or an 
array whose dimensions are not known. 

Struct or union cannot contain itself 

You cannot have a struct or union contain itself. You can have a pointer in the struct 
which points to an instance of itself. Check for a missing in the declaration. 

Incomplete enum declaration 

The enumeration tag has not been previously defined. 

An id list not allowed except for function definition 

A function prototype must contain type information. 

Must use ’va_start’ macro inside function with variable parameters 

The va_ start macro is used to setup access to the parameters in a function that takes a 
variable number of parameters. A function is defined with a variable number of parameters 
by declaring the last parameter in the function as 

***PATAL*** %s 

A fatal error has been detected during code generation time. The type of error is displayed 
in the message. 

Internal compiler error %d 

A bug has been encountered in the C compiler. Please report the specified internal 
compiler error number and any other helpful details about the program being compiled to 
compiler developers so that we can fix the problem. 

Parameter number %d - invalid register in ttpragma 

The designated registers cannot hold the value for the parameter. 

Procedure ’%s’ has invalid return register in ttpragma 

The size of the return register does not match the size of the result returned by the function. 
Illegal register modified by ’%s’ ttpragma 

For the 16-bit C compiler: The BP, CS, DS, and SS registers cannot be modified in small 
data models. The BP, CS, and SS registers cannot be modified in large data models. 

For the 32-bit C compiler: The EBP, CS, DS, ES, and SS registers cannot be modified in 
flat memory models. The EBP, CS, DS, and SS registers cannot be modified in small data 
models. The EBP, CS, and SS registers cannot be modified in large data models. 
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E1123 File must contain at least one external definition 

Every file must contain at least one global object, (either a data variable or a function). 

This message is only issued in strict ANSI mode (-za). 

E1124 Out of macro space 

The compiler ran out of memory for storing macro definitions. 

E1125 Keyboard interrupt detected 

The compile has been aborted with Ctrl/C or Ctrl/Break. 

E1126 Array, struct or union cannot be placed in a register 

Only scalar objects can be specified with the register class. 

El 127 Type required in parameter list 

If the first parameter in a function definition or prototype is defined with a type, then all of 
the parameters must have a type specified. 

E1128 Enum constant is out of range %s 

All of the constants must fit into appropriate value range. 

E1129 Type does not agree with previous definition of ’%s ’ 

You have more than one definition of a variable or function that do not agree. 

E1130 Duplicate name '%s' not allowed in struct or union 

All the field names in a struct or union must be unique. 

El 131 Duplicate macro parameter ’%s’ 

The parameters specified in a macro definition must be unique. 

E1132 Unable to open work file: error code = %d 

The compiler tries to open a new work file by the name "_wrkN_.tmp" where N is the 

digit 0 to 9. This message will be issued if all of those files already exist. 

E1133 Write error on work file: error code = %d 

An error was encountered trying to write information to the work file. The disk could be 
full. 
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E1134 


E1135 


E1136 


E1137 


E1138 


E1139 


E1140 


E1141 


E1142 


E1143 


Read error on work file: error code = %d 

An error was encountered trying to read information from the work file. 

Seek error on work file: error code = %d 

An error was encountered trying to seek to a position in the work file. 
not used 
unused message 
Out ofenum space 

The compiler has run out of space allocated to store information on all of the enum 
constants defined in your program. 

Filename required on command line 

The name of a file to be compiled must be specified on the command line. 

Command line contains more than one file to compile 

You have more than one file name specified on the command line to be compiled. The 
compiler can only compile one file at a time. You can use the Open Watcom Compile and 
Link utility to compile multiple files with a single command. 

_leave must appear in a _try statement 

The _leave keyword must be inside a _try statement. The _leave keyword causes the 
program to jump to the start of the _Jinally block. 

Expecting end of line but found ’%s’ 

A syntax error has been detected. The token displayed in the message should help you 
determine the problem. 

Too many bytes specified in #pragma 

There is an internal limit on the number of bytes for in-line code that can be specified with 
a pragma. Try splitting the function into two or more smaller functions. 

Cannot resolve linkage conventions for routine ’%s’ #pragma 

The compiler cannot generate correct code for the specified routine because of register 
conflicts. Change the registers used by the parameters of the pragma. 
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E1144 


E1145 


E1146 


E1147 


E1148 


E1149 


E1150 


E1151 


E1152 


Symbol ’%s ’ in pragma must be global 

The in-line code for a pragma can only reference a global variable or function. You can 
only reference a parameter or local variable by passing it as a parameter to the in-line code 
pragma. 

Internal compiler limit exceeded, break module into smaller pieces 

The compiler can handle 65535 quadruples, 65535 leaves, and 65535 symbol table entries 
and literal strings. If you exceed one of these limits, the program must be broken into 
smaller pieces until it is capable of being processed by the compiler. 

Invalid initializer for integer data type 

Integer data types (int and long) can be initialized with numeric expressions or address 
expressions that are the same size as the integer data type being initialized. 

Too many errors: compilation aborted 

The compiler stops compiling when the number of errors generated exceeds the error limit. 
The error limit can be set with the "-e" option. The default error limit is 20. 

Expecting identifier but found ’%s’ 

A syntax error has been detected. The token displayed in the message should help you 
determine the problem. 

Expecting constant but found ’%s ’ 

The #line directive must be followed by a constant indicating the desired line number. 
Expecting \"filename\" but found ’%s’ 

The second argument of the #line directive must be a filename enclosed in quotes. 
Parameter count does not agree with previous definition 

You have either not enough parameters or too many parameters in a call to a function. If 
the function is supposed to have a variable number of parameters, then you are missing the 
", ..." in the function prototype. 

Segment name required 

A segment name must be supplied in the form of a literal string to the_segname() 

directive. 


Error Messages 329 




Appendices 


E1153 


E1154 


E1155 


E1156 


E1157 


E1158 


E1159 


E1160 


E1161 


E1162 


Invalid _ based declaration 

The compiler could not recognize one of the allowable forms of_based declarations. See 

the C Language Reference document for description of all the allowable forms of_based 

declarations. 

Variable for based declaration must be of type segment or pointer 

A based pointer declaration must be based on a simple variable of type_segment or 

pointer. 

Duplicate external symbol %s 

Duplicate external symbols will exist when the specified symbol name is truncated to 8 
characters. 

Assembler error: ’%s ’ 

An error has been detected by the in-line assembler. The message indicates the error 
detected. 

Variable must be ’huge ’ 

A variable or an array that requires more than 64K of storage in the 16-bit compiler must be 
declared as huge. 

Too many parm sets 

Too many parameter register sets have been specified in the pragma. 

I/O error reading ’%s’: %s 

An I/O error has been detected by the compiler while reading the source file. The system 
dependent reason is also displayed in the message. 

Attempt to access far memory with all segment registers disabled in ’%s’ 

The compiler does not have any segment registers available to access the desired far 
memory location. 

No identifier provided for -D ’ option 

The command line option "-D" must be followed by the name of the macro to be defined. 
Invalid register pegged to a segment in ’%s’ 

The register specified in a #pragma data_seg, or a_ segname expression must be a valid 

segment register. 
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E1163 


E1164 


E1165 


E1166 


E1167 


El 168 


E1169 


El 170 


El 171 


El 172 


Invalid octal constant 

An octal constant cannot contain the digits 8 or 9. 

Invalid hexadecimal constant 

The token sequence "Ox" must be followed by a hexadecimal character (0-9, a-f, or A-F). 
Unexpected’)’. Probable cause: missing’)’ 

A closing parenthesis was found in an expression without a corresponding opening 
parenthesis. 

Symbol ’%s’ is unreachable from ttpragma 

The in-line assembler found a jump instruction to a label that is too far away. 

Division or remainder by zero in a constant expression 

The compiler found a constant expression containing a division or remainder by zero. 
Cannot end string literal with backslash 

The argument to a macro that uses the stringize operator ’#’ on that argument must not end 
in a backslash character. 

Example: 

♦define str(x) #x 
str (@#\) 

Invalid _ declspec declaration 

The only valid_declspec declarations are "_declspec(thread)","_declspec(dllexport)", 

and "_declspec(dllimport)". 

Too many storage class specifiers 

You can only specify one storage class specifier in a declaration. 

Expecting ’%s ’ but found end of file 

A syntax error has been detected. The compiler is still expecting more input when it 
reached the end of the source program. 

Expecting struct/union tag but found ’%s’ 

The compiler expected to find an identifier following the struct or union keyword. 
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El 173 


El 174 


El 175 


El 17 6 


El 177 


El 178 


El 179 


E1180 


E1181 


E1182 


El 183 


Operand of _ builtin_isfloat() must be a type 

The_builtin_isfloat() function is used by the va_arg macro to determine if a type is a 

floating-point type. 

Invalid constant 

The token sequence does not represent a valid numeric constant. 

Too many initializers 

There are more initializers than objects to initialize. For example int X[2] = { 0, 1, 2 }; The 
variable "X" requires two initializers not three. 

Parameter %d, pointer type mismatch 

You have two pointers that either point to different objects, or the pointers are of different 
size, or they have different modifiers. 

Modifier repeated in declaration 

You have repeated the use of a modifier like "const" (an error) or "far" (a warning) in a 
declaration. 

Type qualifier mismatch 

You have two pointers that have different "const" or "volatile" qualifiers. 

Parameter %d, type qualifier mismatch 

You have two pointers that have different const or "volatile" qualifiers. 

Sign specifier mismatch 

You have two pointers that point to types that have different sign specifiers. 

Parameter %d, sign specifier mismatch 

You have two pointers that point to types that have different sign specifiers. 

Missing A for string literal 

You need a ’V to continue a string literal across a line. 

Expecting ’%s’ after ’%s’ but found ’%s’ 

A syntax error has been detected. The tokens displayed in the message should help you to 
determine the problem. 
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E1184 


E1185 


E1186 


E1187 


E1188 


E1189 


Expecting ’%s’ after ’%s’ but found end of file 

A syntax error has been detected. The compiler is still expecting more input when it 
reached the end of the source program. 

Invalid register name ’%s’ in #pragma 

The register name is invalid/unknown. 

Storage class of for’ statement declaration not register or auto 

The only storage class allowed for the optional declaration part of a for statement is auto or 
register. 

No type specified in declaration 

A declaration specifier must include a type specifier. 

Example: 

auto i; 

Symbol ’%s’ declared in for’ statement must be object 

Any identifier declared in the optional declaration part of a for statement must denote an 
object. Functions, structures, or enumerations may not be declared in this context. 

Example: 

for( int i = 0, j( void ); i < 5; ++i ) { 

} 

Unexpected declaration 

Within a function body, in C99 mode a declaration is only allowed in a compound 
statement and in the opening clause of a for loop. Declarations are not allowed after if, 
while, or switch statement, etc. 

Example: 

void foo( int a ) 

{ 

if( a > 0 ) 

int j = 3; 

} 

In C89 mode, declarations within a function body are only allowed at the beginning of a 
compound statement. 
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Example: 

void foo( int a ) 

{ 

++a; 

int j = 3; 

} 


B.6 Informational Messages 

12000 Not enough memory to fully optimize procedure ’%s’ 

The compiler did not have enough memory to fully optimize the specified procedure. The 
code generated will still be correct and execute properly. This message is purely 
informational. 

12001 Not enough memory to maintain full peephole 

Certain optimizations benefit from being able to store the entire module in memory during 
optimization. All functions will be individually optimized but the optimizer will not be 
able to share code between functions if this message appears. The code generated will still 
be correct and execute properly. This message is purely informational. It is only printed if 
the warning level is greater than or equal to 4. 

The main reason for this message is for those people who are concerned about reproducing 
the exact same object code when the same source file is compiled on a different machine. 
You may not be able to reproduce the exact same object code from one compile to the next 
unless the available memory is exactly the same. 

12002 ’%s’ defined in: %s(%u) 

This informational message indicates where the symbol in question was defined. The 
message is displayed following an error or warning diagnostic for the symbol in question. 

Example: 

static int a = 9; 
int b = 89; 

The variable ’a’ is not referenced in the preceding example and so will cause a warning to 
be generated. Following the warning, the informational message indicates the line at which 
’a’ was declared. 

12003 source conversion type is ’%s’ 

This informational message indicates the type of the source operand, for the preceding 
conversion diagnostic. 
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12004 target conversion type is ’%s ’ 

This informational message indicates the target type of the conversion, for the preceding 
conversion diagnostic. 

12005 Including file ’%s’ 

This informational message indicates that the specified file was opened as a result of 
♦ include directive processing. 

12006 operator ’%s’ 

This informational message indicates the operator, for the preceding diagnostic. 

12007 first operand type is ’%s’ 

This informational message indicates the type of the first operand, for the preceding 
diagnostic. 

12008 second operand type is '%s' 

This informational message indicates the type of the second operand, for the preceding 
diagnostic. 

B.7 Pre-compiled Header Messages 

H3000 Error reading PCHfile 

The pre-compiled header file does not follow the correct format. 

H3001 PCHfile header is out of date 

The pre-compiled header file is out of date with the compiler. The current version of the 
compiler is expecting a different format. 

H3002 Compile options differ with PCH file 

The command line options are not the same as used when making the pre-compiled header 
file. This can effect the values of the pre-compiled information. 

H3003 Current working directory differs with PCH file 

The pre-compiled header file was compiled in a different directory. 
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H3004 Include file ’%s’ has been modified since PCHfile was made 

The include files have been modified since the pie-compiled header file was made. 

H3005 PCHfile was made from a different include file 

The pre-compiled header file was made using a different include file. 

H3006 Include path differs with PCHfile 

The include paths have changed. 

H3007 Preprocessor macro definition differs with PCHfile 

The definition of a preprocessor macro has changed. 

H3008 PCH cannot have data or code definitions. 

The include files used to build the pre-compiled header contain function or data definitions. 
This is not currently supported. 

B.8 Miscellaneous Messages and Phrases 

M4000 Code size 

String used in message construction. 

M4001 Error! 

String used in message construction. 

M4002 Warning! 

String used in message construction. 

M4003 Note! 

String used in message construction. 

M4004 Parameter %d: 

String used in message construction. 
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C. Open Watcom C++ Diagnostic Messages 


The following is a list of all warning and error messages produced by the Open Watcom C++ compilers. 
Diagnostic messages are issued during compilation and execution. 

The messages listed in the following sections contain references to %N, %S, %T, %s, %dand%u. They 
represent strings that are substituted by the Open Watcom C++ compilers to make the error message more 
exact. %d and %u represent a string of digits; %N, %S, %T and %s a string, usually a symbolic name. 

Consider the following program, named err. cpp, which contains errors. 

Example: 

♦include <stdio.h> 

void main() 

1 

int i; 
float i; 

i = 383; 
x = 13143.0; 

printf( "Integer value is %d\n", i ); 
printf( "Floating-point value is %f\n", x ); 

} 

If we compile the above program, the following messages will appear on the screen. 

File: err.cpp 

(6,12): Error! E042: symbol 'i' already defined 
'i' declared at: (5,9) 

(9,5): Error! E029: symbol 'x' has not been declared 
err.cpp: 12 lines, included 174, no warnings, 2 errors 

The diagnostic messages consist of the following information: 

1. the name of the file being compiled, 

2. the line number and column of the line containing the error (in parentheses), 

3. a message number, and 

4. text explaining the nature of the error. 

In the above example, the first error occurred on line 6 of the file err . cpp . Error number 042 (with the 
appropriate substitutions) was diagnosed. The second error occurred on line 9 of the file err . cpp . Error 
number 029 (with the appropriate substitutions) was diagnosed. 

The following sections contain a complete list of the messages. Run-time messages (messages displayed 
during execution) do not have message numbers associated with them. 
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A number of messages contain a reference to the ARM. This is the "Annotated C++ Reference Manual" 
written by Margaret A. Ellis and Bjarne Stroustrup and published by Addison-Wesley (ISBN 
0-201-51459-1). 

C.1 Diagnostic Messages 

000 internal compiler error 

If this message appears, please report the problem directly to the Open Watcom 
development team. See http://www.openwatcom.org/. 

001 assignment of constant found in boolean expression 

An assignment of a constant has been detected in a boolean expression. For example: "if( 
var = 0 )". It is most likely that you want to use "==" for testing for equality. 

002 constant out of range; truncated 

This message is issued if a constant cannot be represented in 32 bits or if a constant is 
outside the range of valid values that can be assigned to a variable. 

Example: 

int a = 12345678901234567890; 

003 missing return value 

A function has been declared with a non-void return type, but no return statement was 
found in the function. Either add a return statement or change the function return type to 
void. 

Example: 

int foo( int a ) 

{ 

int b = a + a; 

} 

The message will be issued at the end of the function. 

004 base class ’%T’ does not have a virtual destructor 

A virtual destructor has been declared in a class with base classes. However, one of those 
base classes does not have a virtual destructor. A delete of a pointer cast to such a base 
class will not function properly in all circumstances. 

Example: 

struct Base { 

-Base(); 

} ; 

struct Derived : Base { 
virtual -Derived(); 

} ; 
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It is considered good programming practice to declare virtual destructors in all classes used 
as base classes of classes having virtual destructors. 

005 pointer or reference truncated 

The expression contains a transfer of a pointer value to another pointer value of smaller 

size. This can be caused by_ near or far qualifiers (i.e., assigning a far pointer to a 

near pointer). Function pointers can also have a different size than data pointers in certain 
memory models. This message indicates that some information is being lost so check the 
code carefully. 

Example: 

extern int _far *foo(); 

int_far *p_ far = foo(); 

int_near *p_ near = p_ far; // truncated 

006 syntax error; probable cause: missing’;’ 

The compiler has found a complete expression (or declaration) during parsing but could not 
continue. The compiler has detected that it could have continued if a semicolon was 
present so there may be a semicolon missing. 

Example: 

enum S { 

} // missing ';' 

class X { 

} ; 

007 ’&array’ may not produce intended result 

The type of the expression ’&array’ is different from the type of the expression ’array’. 
Suppose we have the declaration char buffer[80]. Then the expression (Sbuffer 
+ 3) will be evaluated as (buffer + 3 * sizeof (buffer) ) which is (buffer 
+ 3 * 80) and not (buffer + 3*1) which is what one may have expected. The 
address-of operator ’&’ is not required for getting the address of an array. 

008 returning address of function argument or of auto or register variable 

This warning usually indicates a serious programming error. When a function exits, the 
storage allocated on the stack for auto variables is released. This storage will be 
overwritten by further function calls and/or hardware interrupt service routines. Therefore, 
the data pointed to by the return value may be destroyed before your program has a chance 
to reference it or make a copy of it. 

Example: 

int *foo() 

{ 

int k = 123; 

return &k; // k is automatic variable 

} 


Diagnostic Messages 339 




Appendices 


009 option requires a file name 

The specified option is not recognized by the compiler since there was no file name after it 
(i.e., "-fo=my.obj"). 

010 asm directive ignored 

The asm directive (e.g., asm( "mov rO,l");) is a non-portable construct. The Open 
Watcom C++ compiler treats all asm directives like comments. 

Oil all members are private 

This message warns the programmer that there will be no way to use the contents of the 
class because all accesses will be flagged as erroneous (i.e., accessing a private member). 

Example: 

class Private { 
int a; 

Private(); 

-Private(); 

Private( const Privates ); 

} ; 

012 template argument cannot be type ’%T’ 

A template argument can be either a generic type (e.g., template < class T > ), a 
pointer, or an integral type. These types are required for expressions that can be checked at 
compile time. 

013 unreachable code 

The indicated statement will never be executed because there is no path through the 
program that causes control to reach that statement. 

Example: 

void foo( int *p ) 

{ 

*P = 4; 
return; 

*P = 6; 

} 

The statement following the return statement cannot be reached. 

014 no reference to symbol ’%S’ 

There are no references to the declared variable. The declaration for the variable can be 
deleted. If the variable is a parameter to a function, all calls to the function must also have 
the value for that parameter deleted. 

In some cases, there may be a valid reason for retaining the variable. You can prevent the 
message from being issued through use of #pragma off(unreferenced), or adding a 
statement that assigns the variable to itself. 
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015 nested comment found in comment started on line %u 

While scanning a comment for its end, the compiler detected /* for the start of another 
comment. Nested comments are not allowed in ISO/ANSI C. You may be missing the * / 
for the previous comment. 

016 template argument list cannot be empty 

An empty template argument list would result in a template that could only define a single 
class or function. 

017 label ’%s’ has not been referenced by a goto 

The indicated label has not been referenced and, as such, is useless. This warning can be 
safely ignored. 

Example: 

int foo( int a, int b ) 

{ 

un_ refed: 

return a + b; 

} 

018 no reference to anonymous union member ’%S’ 

The declaration for the anonymous member can be safely deleted without any effect. 

019 ’break’ may only appear in a for, do, while, or switch statement 

A break statement has been found in an illegal place in the program. You may be missing 
an opening brace { for a while, do, for or switch statement. 

Example: 

int foo ( int a, int b ) 

{ 

break; // illegal 
return a+b; 

} 

020 ’case’ may only appear in a switch statement 

A case label has been found that is not inside a switch statement. 

Example: 

int foo( int a, int b ) 

{ 

case 4: // illegal 

return a+b; 

} 
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021 ’continue’ may only appear in a for, do, or while statement 

The continue statement must be inside a while, do or for statement. You may have too 
many } between the while, do or for statement and the continue statement. 

Example: 

int foo( int a, int b ) 

{ 

continue; // illegal 
return a+b; 

} 

022 ’default’ may only appear in a switch statement 

A default label has been found that is not inside a switch statement. You may have too 
many } between the start of the switch and the default label. 

Example: 

int foo( int a, int b ) 

{ 

default: // illegal 
return a+b; 

} 

023 misplaced ’}’ or missing earlier ’{’ 

An extra } has been found which cannot be matched up with an earlier { . 

024 misplaced #elif directive 

The #elif directive must be inside an #if preprocessing group and before the #else directive 
if present. 

Example: 

int a; 

#else 
int c; 

#elif IN_ IF 
int b; 

#endif 

The #else, #elif, and #endif statements are all illegal because there is no #if that 
corresponds to them. 

025 misplaced #else directive 

The #else directive must be inside an #if preprocessing group and follow all #elif directives 
if present. 
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Example: 

int a; 

#else 
int c; 

#elif IN_ IF 
int b; 

#endif 

The #else, #elif, and tfendif statements are all illegal because there is no #if that 
corresponds to them. 

026 misplaced #endif directive 

A ftendif preprocessing directive has been found without a matching #if directive. You 
either have an extra #endif or you are missing an #if directive earlier in the file. 

Example: 

int a; 

#else 
int c; 

#elif IN_ IF 
int b; 

#endif 

The #else, #elif and #endif statements are all illegal because there is no #if that 
corresponds to them. 

027 only one ’default’ per switch statement is allowed 

You cannot have more than one default label in a switch statement. 

Example: 

int translate( int a ) 

{ 

switch( a ) { 

case 1: 
a = 8 ; 
break; 

default: 
a = 9; 
break; 

default: // illegal 
a = 10; 
break; 

} 

return a; 

} 
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028 expecting ’%s’ but found ’%s’ 

A syntax error has been detected. The tokens displayed in the message should help you to 
determine the problem. 

029 symbol ’%N’ has not been declared 

The compiler has found a symbol which has not been previously declared. The symbol 
may be spelled differently than the declaration, or you may need to #include a header file 
that contains the declaration. 

Example: 

int a = b; // b has not been declared 

030 left expression must be a function or a function pointer 

The compiler has found an expression that looks like a function call, but it is not defined as 
a function. 

Example: 

int a; 

int b = a ( 12 ) ; 

031 operand must be an lvalue 

The operand on the left side of an "=" sign must be a variable or memory location which 
can have a value assigned to it. 

Example: 

void foo( int a ) 

{ 

( a + 1 ) = 7; 

int b = ++ ( a + 6 ); 

} 

Both statements within the function are erroneous, since lvalues are expected where the 
additions are shown. 

032 label ’%s’ already defined 

All labels within a function must be unique. 

Example: 

void bar( int *p ) 

{ 

label: 

*P = 0; 
label: 

return; 

} 

The second label is illegal. 
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033 label ’%s’ is not defined in function 

A goto statement has referenced a label that is not defined in the function. Add the 
necessary label or check the spelling of the label(s) in the function. 

Example: 

void bar( int *p ) 

{ 

labl: 

*p = 0; 
goto label; 

} 

The label referenced in the goto is not defined. 

034 dimension cannot be zero 

The dimension of an array must be non-zero. 

Example: 

int array[0]; // not allowed 

035 dimension cannot be negative 

The dimension of an array must be positive. 

Example: 

int array[-l]; // not allowed 

036 dimensions of multi-dimension array must be specified 

All dimensions of a multiple dimension array must be specified. The only exception is the 
first dimension which can declared as "[]". 

Example: 

int array[][]; // not allowed 

037 invalid storage class for function 

If a storage class is given for a function, it must be static or extern. 

Example: 

auto void foo() 

{ 

} 

038 expression must have pointer type 

An attempt has been made to de-reference a variable or expression which is not declared to 
be a pointer. 
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Example: 

int a; 
int b = *a; 

039 cannot take address of an rvalue 

You can only take the address of a variable or memory location. 

Example: 

char c; 

char *pl = & & c; // not allowed 

char *p2 = & (c+1); // not allowed 

040 expression for ’. ’ must be a class, struct or union 

The compiler has encountered the pattern "expression" "field_name" where the 
expression is not a class, struct or union type. 

Example: 

struct S 

{ 

int a; 

1 ; 

int &fun(); 
int a = fun().a; 

041 expression for ’-> ’ must be pointer to class, struct or union 

The compiler has encountered the pattern "expression" "field_name" where the 
expression is not a pointer to class, struct or union type. 

Example: 

struct S 

{ 

int a; 

1 ; 

int *fun(); 

int a = fun()->a; 

042 symbol ’%S’ already defined 

The specified symbol has already been defined. 

Example: 

char a = 2; 

char a = 2; // not allowed 

043 static function ’%S’ has not been defined 

A prototype has been found for a static function, but a definition for the static function has 
not been found in the file. 
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Example: 

static int fun( void ); 
int k = fun(); 

// fun not defined by end of program 
044 expecting label for goto statement 

The goto statement requires the name of a label. 

Example: 

int fun( void ) 

{ 

goto; 

} 

045 duplicate case value ’%s’found 

Every case value in a switch statement must be unique. 

Example: 

int fun( int a ) 

{ 

switch( a ) { 

case 1: 
return 7; 

case 2 : 
return 9; 

case 1: // duplicate not allowed 
return 7; 

} 

return 79; 

} 

046 bit-field width is too large 

The maximum field width allowed is 16 bits in the 16-bit compiler and 32 bits in the 32-bit 
compiler. 

Example: 

struct S 

{ 

unsigned bitfield :48; // too wide 

} ; 


047 width of a named bit-field must not be zero 

A bit field must be at least one bit in size. 
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Example: 

struct S { 

int bitfield :10; 

int :0; // okay, aligns to int 

int h :0; // error, field is named 


048 bit-field width must be positive 

You cannot have a negative field width. 

Example: 

struct S 

{ 

unsigned bitfield :-10; // cannot be negative 

} ; 

049 bit-field base type must be an integral type 

The types allowed for bit fields are signed or unsigned varieties of char, short and int. 

Example: 

struct S 

{ 

float bitfield : 10; // must be integral 

1 ; 

050 subscript on non-array 

One of the operands of ’[]’ must be an array or a pointer. 

Example: 


int 

array[10]; 



int 

il 

= array[0]; 

// 

ok 

int 

i2 

= 0[array]; 

// 

same as above 

int 

i3 

= 0 [1]; 

// 

illegal 


051 incomplete comment 

The compiler did not find * / to mark the end of a comment. 

052 argument for # must be a macro parm 

The argument for the stringize operator '#' must be a macro parameter. 

053 unknown preprocessing directive ’#%s ’ 

An unrecognized preprocessing directive has been encountered. Check for correct spelling. 
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Example: 

#i_ goofed // not valid 
054 invalid #include directive 

A syntax error has been encountered in a #include directive. 

Example: 

♦include // no header file 
♦include stdio.h 

Both examples are illegal. 

055 not enough parameters given for macro ’%s’ 

You have not supplied enough parameters to the specified macro. 

Example: 

♦define mac(a,b) a+b 

int i = mac (123); // needs 2 parameters 

056 not expecting a return value 

The specified function is declared as a void function. Delete the return value, or change 
the type of the function. 

Example: 

void fun() 

{ 

return 14; // not expecting return value 

} 

057 cannot take address of a bit-field 

The smallest addressable unit is a byte. You cannot take the address of a bit field. 

Example: 

struct S 
{ int bits :6; 

int bitfield :10; 

}; 

S var; 

void* p = Svar.bitfield; // illegal 

058 expression must be a constant 

The compiler expects a constant expression. This message can occur during static 
initialization if you are trying to initialize a non-pointer type with an address expression. 
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059 unable to open ’%s ’ 

The file specified in an Mnclude directive could not be located. Make sure that the file 
name is spelled correctly, or that the appropriate path for the file is included in the list of 
paths specified in the INCLUDE or INCLUDE environment variables or in the "i=" option 
on the command line. 

060 too many parameters given for macro ’%s ’ 

You have supplied too many parameters for the specified macro. The extra parameters are 
ignored. 

Example: 

#define mac(a,b) a+b 

int i = mac(1,2,3); // needs 2 parameters 

061 cannot use _ based or far 16 pointers in this context 

The use of based and far 16 pointers is prohibited in throw expressions and catch 

statements. 

Example: 

extern int_based (_segname ( "myseg" ) ) *pi; 

void bad() 

{ 

try { 
throw pi; 

} catch( int _farl6 *pl6 ) { 

*pl6 = 87; 

} 

} 

Both the throw expression and catch statements cause this error to be diagnosed. 

062 only one type is allowed in declaration specifiers 

Only one type is allowed for the first part of a declaration. A common cause of this 
message is that there may be a missing semi-colon after a class definition. 

Example: 

class C 

{ 

public: 

CO; 

} // needs 

int foo() { return 7; } 
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063 out of memory 

The compiler has run out of memory to store information about the file being compiled. 

Try reducing the number of data declarations and or the size of the file being compiled. Do 
not Mnclude header files that are not required. 

064 invalid character constant 

This message is issued for an improperly formed character constant. 

Example: 

char c = ’ 12345'; 
char d = '''; 

065 taking address of variable with storage class ’register’ 

You can take the address of a register variable in C++ (but not in ISO/ANSI C). If there is 
a chance that the source will be compiled using a C compiler, change the storage class from 
register to auto. 

Example: 

extern int foo( char* ); 
int bar() 

{ 

register char c = ' c'; 
return foo ( &c ); 

} 

066 ’delete ’ expression size is not allowed 

The C++ language has evolved to the point where the delete expression size is no longer 
required for a correct deletion of an array. 

Example: 

void fn( unsigned n, char *p ) { 

delete [n] p; 

} 

067 ending " missing for string literal 

The compiler did not find a second double quote to end the string literal. 

Example: 

char *a = "no_ ending_ quote; 

068 invalid option 

The specified option is not recognized by the compiler. 
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069 invalid optimization option 

The specified option is an unrecognized optimization option. 

070 invalid memory model 

Memory model option must be one of "ms", "mm", "me", "ml", "mh" or "mf" which selects 
the Small, Medium, Compact, Large, Huge or Flat memory model. 

071 expression must be integral 

An integral expression is required. 

Example: 

int foo( int a, float b, int *p ) 

{ 

switch( a ) { 

case 1.3: // must be integral 

return p[b]; // index not integer 

case 2 : 

b <<= 2; // can only shift integers 

default: 
return b; 

} 

} 

072 expression must be arithmetic 

Arithmetic operations, such as "/" and require arithmetic operands unless the operation 
has been overloaded or unless the operands can be converted to arithmetic operands. 

Example: 

class C 

{ 

public: 

int c; 

1 ; 

C cv; 

int i = cv / 2; 

073 statement required after label 

The C language definition requires a statement following a label. You can use a null 
statement which consists of just a semicolon 

Example: 

extern int bar( int ); 
void foo( int a ) 

{ 

if( a ) goto ending; 
bar ( a ); 
ending: 

// needs statement following 

} 
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074 


075 


076 


077 


078 


statement required after ’do’ 

A statement is required between the do and while keywords. 
statement required after ’case’ 

The C language definition requires a statement following a case label. You can use a null 
statement which consists of just a semicolon 


Example: 

int foo( int a ) 

{ 

switch( a ) { 

default: 
return 7; 

case 1: // needs statement following 

} 

return 18; 

} 


statement required after ’default’ 

The C language definition requires a statement following a default label. You can use a 
null statement which consists of just a semicolon (";")• 

Example: 

int foo( int a ) 

{ 

switch( a ) { 

case 7 : 
return 7; 
default: 

// needs statement following 

} 

return 18; 

} 


missing matching #endif directive 

You are missing a #endif to terminate a #if #ifdef or #ifndef preprocessing directive. 

Example: 

#if 1 
int a; 

// needs #endif 


invalid macro definition, missing ’)’ 

The right parenthesis ")" is required for a function-like macro definition. 
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Example: 

♦ define bad_ mac ( a, b 

079 missing ’)’ for expansion of ’%s’ macro 

The compiler encountered end-of-file while collecting up the argument for a function-like 
macro. A right parenthesis ")" is required to mark the end of the argument(s) for a 
function-like macro. 

Example: 

♦define mac( a, b) a+b 
int d = mac( 1, 2 

080 %s 

This is a user message generated with the #error preprocessing directive. 

Example: 

♦error my very own error message 
081 cannot define an array of functions 

You can have an array of pointers to functions, but not an array of functions. 

Example: 

typedef int TD(float); 

TD array[12]; 

082 function cannot return an array 

A function cannot return an array. You can return a pointer to an array. 

Example: 

typedef int ARR[10]; 

ARR fun( float ); 

083 function cannot return a function 

You cannot return a function. You can return a pointer to a function. 

Example: 

typedef int TD(); 

TD fun( float ); 

084 function templates can only have type arguments 

A function template argument can only be a generic type (e.g., template < class T > 
). This is a restriction in the C++ language that allows compilers to automatically 
instantiate functions purely from the argument types of calls. 
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085 maximum class size has been exceeded 

The 16-bit compiler limits the size of a struct or union to 64K so that the compiler can 
represent the offset of a member in a 16-bit register. This error also occurs if the size of a 
structure overflows the size of an unsigned integer. 

Example: 

struct S 

{ 

char arrl[ Oxfffe ]; 
char arr2[ Oxfffe ]; 
char arr3[ Oxfffe ]; 
char arr4[ Oxfffffffe ]; 

} ; 

086 definition of macro ’%s’ not identical to previous definition 

If a macro is defined more than once, the definitions must be identical. If you want to 
redefine a macro to have a different definition, you must #undef it before you can define it 
with a new definition. 

Example: 

♦define CON 123 

♦define CON 124 // not same as previous 

087 initialization of ’%S’ must be in file scope 

A file scope variable must be initialized in file scope. 

Example: 

void fn() 

{ 

extern int v = 1; 

} 

088 default argument for ’%S’ declared outside of class definition 

Problems can occur with member functions that do not declare all of their default 
arguments during the class definition. For instance, a copy constructor is declared if a class 
does not define a copy constructor. If a default argument is added later on to a constructor 
that makes it a copy constructor, an ambiguity results. 

Example: 

struct S { 

S( S const &, int ); 

// S ( S const & ); <— declared by compiler 

} ; 

// ambiguity with compiler 
// generated copy constructor 
// S ( S const & ); 

S::S( S const &, int = 0 ) 

{ 

} 
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089 ## must not be at start or end of replacement tokens 

There must be a token on each side of the "##" (token pasting) operator. 

Example: 

♦define badmac( a, b ) ## a ## b 
090 invalid floating-point constant 

The exponent part of the floating-point constant is not formed correctly. 

Example: 

float f = 123.9E+Q; 

091 ’sizeof is not allowed for a bit-field 

The smallest object that you can ask for the size of is a char. 

Example: 

struct S 
{ int a; 

int b :10; 

} v; 

int k = sizeof( v.b ); 

092 option requires a path 

The specified option is not recognized by the compiler since there was no path after it (i.e., 
"-i=d:\include;d:\path"). 

093 must use ’va_start’ macro inside function with variable arguments 

The va_ start macro is used to setup access to the parameters in a function that takes a 
variable number of parameters. A function is defined with a variable number of parameters 
by declaring the last parameter in the function as 

Example: 

♦include <stdarg.h> 
int foo( int a, int b ) 

{ 

va_ list args; 
va_ start ( args, a ); 
va_ end( args ); 
return b; 

} 

094 ***faTAL*** %s 

A fatal error has been detected during code generation time. The type of error is displayed 
in the message. 
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095 internal compiler error %d 

A bug has been encountered in the compiler. Please report the specified internal compiler 
error number and any other helpful details about the program being compiled to the Open 
Watcom development team so that we can fix the problem. See 
http: //www. open watcom .org/. 

096 argument number %d - invalid register in #pragma 

The designated registers cannot hold the value for the parameter. 

097 procedure ’%s’ has invalid return register in //pragma 

The size of the return register does not match the size of the result returned by the function. 

098 illegal register modified by ’%s’ #pragma 

For the 16-bit Open Watcom C/C++ compiler: The BP, CS, DS, and SS registers cannot 
be modified in small data models. The BP, CS, and SS registers cannot be modified in 
large data models. 

For the 32-bit Open Watcom C/C++ compiler: The EBP, CS, DS, ES, and SS registers 
cannot be modified in flat memory models. The EBP, CS, DS, and SS registers cannot be 
modified in small data models. The EBP, CS, and SS registers cannot be modified in large 
data models. 

099 file must contain at least one external definition 

Every file must contain at least one global object, (either a data variable or a function). 

Note: This message has been disabled starting with Open Watcom vl.4. The ISO 1998 
C++ standard allows empty translation units. 

100 out of macro space 

The compiler ran out of memory for storing macro definitions. 

101 keyboard interrupt detected 

The compilation has been aborted with Ctrl/C or Ctrl/Break. 

102 duplicate macro parameter ’%s’ 

The parameters specified in a macro definition must be unique. 

Example: 

♦define badmac( a, b, a ) a ## b 
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103 unable to open work file: error code = %d 

The compiler tries to open a new work file by the name "_wrkN_.tmp" where N is the 

digit 0 to 9. This message will be issued if all of those files already exist. 

104 write error on work file: error code = %d 

An error was encountered trying to write information to the work file. The disk could be 
full. 

105 read error on work file: error code = %d 

An error was encountered trying to read information from the work file. 

106 token too long; truncated 

The token must be less than 510 bytes in length. 

107 filename required on command line 

The name of a file to be compiled must be specified on the command line. 

108 command line contains more than one file to compile 

You have more than one file name specified on the command line to be compiled. The 
compiler can only compile one file at a time. You can use the Open Watcom Compile and 
Link utility to compile multiple files with a single command. 

109 virtual member functions are not allowed in a union 

A union can only be used to overlay the storage of data. The storage of virtual function 
information (in a safe manner) cannot be done if storage is overlaid. 

Example: 


struct 

Sl{ 

int 

f ( 

int 

); 1 ; 

struct 

S2{ 

int 

f ( 

int 

); 1 ; 

union 

un { 

SI s 

i; 




S2 

s2; 





virtual 

int 

vf ( 

int ) ; 


} ; 

110 union cannot be used as a base class 

This restriction prevents C++ programmers from viewing a union as an encapsulation unit. 
If it is necessary, one can encapsulate the union into a class and achieve the same effect. 
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Example: 

union U { int a; int b; }; 

class S : public U { int s; }; 

111 union cannot have a base class 

This restriction prevents C++ programmers from viewing a union as an encapsulation unit. 
If it is necessary, one can encapsulate the union into a class and inherit the base classes 
normally. 

Example: 

class S { public: int s; }; 

union U : public S { int a; int b; }; 

112 cannot inherit an undefined base class ’%T’ 

The storage requirements for a class type must be known when inheritance is involved 
because the layout of the final class depends on knowing the complete contents of all base 
classes. 

Example: 

class Undefined; 
class C : public Undefined { 
int c; 

} ; 

113 repeated direct base class will cause ambiguities 

Almost all accesses will be ambiguous. This restriction is useful in catching programming 
errors. The repeated base class can be encapsulated in another class if the repetition is 
required. 

Example: 

class Dup 

{ 

int d; 

} ; 

class C : public Dup, public Dup 

{ 

int c; 

} ; 

114 templates may only be declared in namespace scope 

Currently, templates can only be declared in namespace scope. This simple restriction was 
chosen in favour of more freedom with possibly subtle restrictions. 
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115 linkages may only be declared in file scope 

A common source of errors for C and C++ result from the use of prototypes inside of 
functions. This restriction attempts to prevent such errors. 

116 unknown linkage ’%s’ 

Only the linkages "C" and "C++" are supported by Open Watcom C++. 

Example: 

extern "APL" void AplFunc( int* ); 

117 too many storage class specifiers 

This message is a result of duplicating a previous storage class or having a different storage 
class. You can only have one of the following storage classes, extern, static, auto, register, 
or typedef. 

Example: 

extern typedef int (*fn)( void ); 

118 nameless declaration is not allowed 

A type was used in a declaration but no name was given. 

Example: 

static int; 

119 illegal combination of type specifiers 

An incorrect scalar type was found. Either a scalar keyword was repeated or the 
combination is illegal. 

Example: 

short short x; 
short long y; 

120 illegal combination of type qualifiers 

A repetition of a type qualifier has been detected. Some compilers may ignore repetitions 
but strictly speaking it is incorrect code. 

Example: 

const const x; 
struct S { 

int virtual virtual fn(); 

} ; 
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121 syntax error 

The C++ compiler was unable to interpret the text starting at the location of the message. 
The C++ language is sufficiently complicated that it is difficult for a compiler to correct the 
error itself. 

122 parser stack corrupted 

The C++ parser has detected an internal problem that usually indicates a compiler problem. 
Please report this directly to the Open Watcom development team. See 
http://www.openwatcom.org/. 

123 template declarations cannot be nested within each other 

Currently, templates can only be declared in namespace scope. Furthermore, a template 
declaration must be finished before another template can be declared. 

124 expression is too complicated 

The expression contains too many levels of nested parentheses. Divide the expression up 
into two or more sub-expressions. 

125 invalid redefinition of the typedef name ’%S’ 

Redefinition of typedef names is only allowed if you are redefining a typedef name to 
itself. Any other redefinition is illegal. You should delete the duplicate typedef definition. 

Example: 

typedef int TD; 

typedef float TD; // illegal 

126 class ’%T’ has already been defined 

This message usually results from the definition of two classes in the same scope. This is 
illegal regardless of whether the class definitions are identical. 

Example: 

class C { 

} ; 

class C { 

} ; 

127 ’sizeof is not allowed for an undefined type 

If a type has not been defined, the compiler cannot know how large it is. 
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Example: 

class C; 

int x = sizeof( C ); 

128 initializer for variable ’%S’ cannot be bypassed 

The variable may not be initialized when code is executing at the position indicated in the 
message. The C++ language places these restrictions to prevent the use of uninitialized 
variables. 

Example: 

int foo( int a ) 

{ 

switch( a ) { 

case 1: 
int b = 2; 
return b; 

default: // b bypassed 
return b + 5; 

} 

} 

129 division by zero in a constant expression 

Division by zero is not allowed in a constant expression. The value of the expression 
cannot be used with this error. 

Example: 

int foo( int a ) 

{ 

switch( a ) { 

case 4/0: // illegal 

return a; 

} 

return a + 2; 

} 

130 arithmetic overflow in a constant expression 

The multiplication of two integral values cannot be represented. The value of the 
expression cannot be used with this error. 

Example: 

int foo( int a ) 

{ 

switch( a ) { 

case 0x7FFF * 0x7FFF * 0x7FFF: // overflow 
return a; 

} 

return a + 2; 

} 
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131 not enough memory to fully optimize procedure ’%s’ 

The indicated procedure cannot be fully optimized with the amount of memory available. 
The code generated will still be correct and execute properly. This message is purely 
informational (i.e., buy more memory). 

132 not enough memory to maintain full peephole 

Certain optimizations benefit from being able to store the entire module in memory during 
optimization. All functions will be individually optimized but the optimizer will not be 
able to share code between functions if this message appears. The code generated will still 
be correct and execute properly. This message is purely informational (i.e., buy more 
memory). 

133 too many errors: compilation aborted 

The Open Watcom C++ compiler sets a limit to the number of error messages it will issue. 
Once the number of messages reaches the limit the above message is issued. This limit can 
be changed via the "/e" command line option. 

134 too many parm sets 

An extra parameter passing description has been found in the aux pragma text. Only one 
parameter passing description is allowed. 

135 friend’, ’virtual’ or ’inline’ modifiers may only be used on functions 

This message indicates that you are trying to declare a strange entity like an inline variable. 
These qualifiers can only be used on function declarations and definitions. 

136 more than one calling convention has been specified 

A function cannot have more than one #pragma modifier applied to it. Combine the 
pragmas into one pragma and apply it once. 

137 pure member function constant must be ’0’ 

The constant must be changed to ’O’ in order for the Open Watcom C++ compiler to accept 
the pure virtual member function declaration. 

Example: 

struct S { 

virtual int wrong( void ) = 91; 

1 ; 

138 based modifier has been repeated 

A repeated based modifier has been detected. There are no semantics for combining base 
modifiers so this is not allowed. 
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Example: 

char *ptr; 

char_based( void )_based( ptr ) *a; 

139 enumeration variable is not assigned a constant from its enumeration 

In C++ (as opposed to C), enums represent values of distinct types. Thus, the compiler will 
not automatically convert an integer value to an enum type. 

Example: 

enum Days { sun, mod, tues, wed, thur, fri, sat }; 
enum Days day = 2; 

140 bit-field declaration cannot have a storage class specifier 

Bit-fields (along with most members) cannot have storage class specifiers in their 
declaration. Remove the storage class specifier to correct the code. 

Example: 

class C 

{ 

public: 

extern unsigned bitf :10; 

} ; 


141 bit-field declaration must have a base type specified 

A bit-field cannot make use of a default integer type. Specify the type int to correct the 
code. 

Example: 

class C 

{ 

public: 

bitf :10; 

} ; 


142 illegal qualification of a bit-field declaration 

A bit-field can only be declared const or volatile. Qualifications like friend are not 
allowed. 

Example: 

struct S { 

friend int bitl :10; 
inline int bit2 :10; 
virtual int bit3 :10; 

} ; 

All three declarations of bit-fields are illegal. 
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143 duplicate base qualifier 

The compiler has found a repetition of base qualifiers like protected or virtual. 

Example: 

struct Base { int b; }; 

struct Derived : public public Base { int d; }; 

144 only one access specifier is allowed 

The compiler has found more than one access specifier for a base class. Since the compiler 
cannot choose one over the other, remove the unwanted access specifier to correct the code. 

Example: 

struct Base { int b; }; 

struct Derived : public protected Base { int d; }; 

145 unexpected type qualifier found 

Type specifiers cannot have const or volatile qualifiers. This shows up in new expressions 
because one cannot allocate a const object. 

146 unexpected storage class specifier found 

Type specifiers cannot have auto or static storage class specifiers. This shows up in new 
expressions because one cannot allocate a static object. 

147 access to ’%S’ is not allowed because it is ambiguous 

There are two ways that this error can show up in C++ code. The first way a member can 
be ambiguous is that the same name can be used in two different classes. If these classes 
are combined with multiple inheritance, accesses of the name will be ambiguous. 

Example: 

struct SI { int s; }; 
struct S2 { int s; }; 
struct Der : public SI, public S2 
{ 

void foo() { s = 2; }; // s is ambiguous 

} ; 


The second way a member can be ambiguous involves multiple inheritance. If a class is 
inherited non-virtually by two different classes which then get combined with multiple 
inheritance, an access of the member is faced with deciding which copy of the member is 
intended. Use the operator to clarify what member is being accessed or access the 
member with a different class pointer or reference. 
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Example: 

struct Top { int t; In¬ 
struct Mid : public Top { int m; In¬ 
struct Bot : public Top, public Mid 
{ 

void foo() { t = 2; }; // t is ambiguous 

} ; 


148 access to private member ’%S’ is not allowed 

The indicated member is being accessed by an expression that does not have permission to 
access private members of the class. 

Example: 

struct Top { int t; }; 
class Bot : private Top 
{ 

int foo() { return t; }; // t is private 

} ; 

Bot b; 

int k = b.foo(); // foo is private 

149 access to protected member ’%S’ is not allowed 

The indicated member is being accessed by an expression that does not have permission to 
access protected members of the class. The compiler also requires that protected members 
be accessed through a derived class to ensure that an unrelated base class cannot be quietly 
modified. This is a fairly recent change to the C++ language that may cause Open Watcom 
C++ to not accept older C++ code. See Section 11.5 in the ARM for a discussion of 
protected access. 

Example: 

struct Top { int t; }; 
struct Mid : public Top { int m; }; 
class Bot : protected Mid 
{ 

protected: 

// t cannot be accessed 
int foo() { return t; }; 

} ; 

Bot b; 

int k = b.foo(); // foo is protected 

150 operation does not allow both operands to be pointers 

There may be a missing indirection in the code exhibiting this error. An example of this 
error is adding two pointers. 
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Example: 

void fn() 

{ 

char *p, *q; 

p += q; 

} 

151 operand is neither a pointer nor an arithmetic type 

An example of this error is incrementing a class that does not have any overloaded 
operators. 

Example: 

struct S { } x; 
void fn() 

{ 

+ + X } 

} 

152 left operand is neither a pointer nor an arithmetic type 

An example of this error is trying to add 1 to a class that does not have any overloaded 
operators. 

Example: 

struct S { } x; 
void fn() 

{ 

x = x + 1 ; 

} 

153 right operand is neither a pointer nor an arithmetic type 

An example of this error is trying to add 1 to a class that does not have any overloaded 
operators. 

Example: 

struct S { } x; 
void fn() 

{ 

x = 1 + x ; 

} 

154 cannot subtract a pointer from an arithmetic operand 
The subtract operands are probably in the wrong order. 
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Example: 

int fn( char *p ) 

{ 

return ( 10 - p ); 

} 

755 left expression must be arithmetic 

Certain operations like multiplication require both operands to be of arithmetic types. 
Example: 

struct S { } x; 
void fn() 

{ 

x = x * 1; 

} 

156 right expression must be arithmetic 

Certain operations like multiplication require both operands to be of arithmetic types. 
Example: 

struct S { } x; 
void fn() 

{ 

x = 1 * x; 

} 

757 left expression must be integral 

Certain operators like the bit manipulation operators require both operands to be of integral 
types. 

Example: 

struct S { } x; 
void fn() 

{ 

x = x A 1; 

} 

158 right expression must be integral 

Certain operators like the bit manipulation operators require both operands to be of integral 
types. 

Example: 

struct S { } x; 
void fn() 

{ 

x = 1 A x; 

} 
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159 cannot assign a pointer value to an arithmetic item 

The pointer value must be cast to the desired type before the assignment takes place. 
Example: 

void fn( char *p ) 

{ 

int a; 
a = p; 

} 

160 attempt to destroy afar object when the data model is near 

Destructors cannot be applied to objects which are stored in far memory when the default 
memory model for data is near. 

Example: 

struct Obj 
{ char *p; 

~Obj(); 

1 ; 

Obj far obj; 

The last line causes this error to be displayed when the memory model is small (switch 
-ms), since the memory model for data is near. 

161 attempt to call member function for far object when the data model is near 

Member functions cannot be called for objects which are stored in far memory when the 
default memory model for data is near. 

Example: 

struct Obj 
{ char *p; 

int foo (); 

} ; 

Obj far obj; 

int integer = obj.fooO; 

The last line causes this error to be displayed when the memory model is small (switch 
-ms), since the memory model for data is near. 

162 template type argument cannot have a default argument 

This message was produced by earlier versions of the Open Watcom C++ compiler. 
Support for default template arguments was added in version 1.3 and this message was 
removed at that time. 
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163 attempt to delete afar object when the data model is near 

delete cannot be used to deallocate objects which are stored in far memory when the default 
memory model for data is near. 

Example: 

struct Obj 
{ char *p; 

} ; 

void too( Obj far *p ) 

{ 

delete p; 

} 

The second last line causes this error to be displayed when the memory model is small 
(switch -ms), since the memory model for data is near. 

164 first operand is not a class, struct or union 

The offsetof operation can only be performed on a type that can have members. It is 
meaningless for any other type. 

Example: 

♦include <stddef.h> 

int fn( void ) 

{ 

return offsetof ( double, sign ); 

} 

165 syntax error: class template cannot be processed 

The class template contains unbalanced braces. The class definition cannot be processed in 
this form. 

166 cannot convert right pointer to type of left operand 

The C++ language will not allow the implicit conversion of unrelated class pointers. An 
explicit cast is required. 

Example: 

class Cl; 
class C2; 

void fun( Cl* pci, C2* pc2 ) 

{ 

pc2 = pci; 

} 
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167 left operand must be an lvalue 

The left operand must be an expression that is valid on the left side of an assignment. 
Examples of incorrect lvalues include constants and the results of most operators. 

Example: 

int i, j; 
void fn() 

{ 

( i - i ) = j; 
i = j; 


168 static data members are not allowed in an union 

A union should only be used to organize memory in C++. Enclose the union in a class if 
you need a static data member associated with the union. 

Example: 

union U 

{ 

static int a; 
int b; 
int c; 


169 invalid storage class for a member 

A class member cannot be declared with auto, register, or extern storage class. 

Example: 

class C 

{ 

auto int a; // cannot specify auto 

} ; 


170 declaration is too complicated 

The declaration contains too many declarators (i.e., pointer, array, and function types). 
Break up the declaration into a series of typedefs ending in a final declaration. 

Example: 

int ************p; 

Example: 

// transform this to ... 
typedef int ****PD1; 
typedef PD1 ****PD2; 

PD2 ****p; 


Diagnostic Messages 371 




Appendices 


171 exception declaration is too complicated 

The exception declaration contains too many declarators (i.e., pointer, array, and function 
types). Break up the declaration into a series of typedefs ending in a final declaration. 

172 floating-point constant too large to represent 

The Open Watcom C++ compiler cannot represent the floating-point constant because the 
magnitude of the positive exponent is too large. 

Example: 

float f = 1.2e78965; 

173 floating-point constant too small to represent 

The Open Watcom C++ compiler cannot represent the floating-point constant because the 
magnitude of the negative exponent is too large. 

Example: 

float f = 1.2e-78965; 

174 class template ’%M’ cannot be overloaded 

A class template name must be unique across the entire C++ program. Furthermore, a class 
template cannot coexist with another class template of the same name. 

175 range ofenum constants cannot be represented 

If one integral type cannot be chosen to represent all values of an enumeration, the values 
cannot be used reliably in the generated code. Shrink the range of enumerator values used 
in the enum declaration. 

Example: 

enum E 

{ el = OxFFFFFFFF 

, e2 = -1 

} ; 

176 ’%S’ cannot be in the same scope as a class template 

A class template name must be unique across the entire C++ program. Any other use of a 
name cannot be in the same scope as the class template. 

177 invalid storage class in file scope 

A declaration in file scope cannot have a storage class of auto or register. 
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Example: 

auto int a; 

178 const object must be initialized 

Constant objects cannot be modified so they must be initialized before use. 

Example: 

const int a; 

179 declaration cannot be in the same scope as class template ’%S’ 

A class template name must be unique across the entire C++ program. Any other use of a 
name cannot be in the same scope as the class template. 

180 template arguments must be named 

A member function of a template class cannot be defined outside the class declaration 
unless all template arguments have been named. 

181 class template ’%M’ is already defined 

A class template cannot have its definition repeated regardless of whether it is identical to 
the previous definition. 

182 invalid storage class for an argument 

An argument declaration cannot have a storage class of extern, static, or typedef. 
Example: 

int foo( extern int a ) 

{ 

return a; 

} 

183 unions cannot have members with constructors 

A union should only be used to organize memory in C++. Allowing union members to 
have constructors would mean that the same piece of memory could be constructed twice. 

Example: 

class C 

{ 

CO; 

1 ; 

union U 

{ 

int a; 

C c; // has constructor 

} ; 
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184 statement is too complicated 

The statement contains too many nested constructs. Break up the statement into multiple 
statements. 

185 ’%s’ is not the name of a class or namespace 

The right hand operand of a operator turned out not to reference a class type or 
namespace. Because the name is followed by another it must name a class or 
namespace. 

186 attempt to modify a constant value 

Modification of a constant value is not allowed. If you must force this to work, take the 
address and cast away the constant nature of the type. 

Example: 

static int const con = 12; 
void foo() 

{ 

con = 13; // error 

*(int*)&con = 13; // ok 

} 

187 ’offsetof’ is not allowed for a bit-field 

A bit-field cannot have a simple offset so it cannot be referenced in an offsetof expression. 
Example: 

♦include <stddef.h> 
struct S 
{ 


unsigned 

bl 

O 
\— 1 

unsigned 

b2 

LO 
\— 1 

unsigned 

b3 

\—1 
\— 1 


int k = offsetof ( S, b2 ); 

188 base class is inherited with private access 

This warning indicates that the base class was originally declared as a class as opposed to a 
struct. Furthermore, no access was specified so the base class defaults to private 
inheritance. Add the private or public access specifier to prevent this message depending 
on the intended access. 

189 overloaded function cannot be selected for arguments used in call 

Either conversions were not possible for an argument to the function or a function with the 
right number of arguments was not available. 
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Example: 

class Cl; 
class C2; 
int foo( Cl* ); 
int foo( C2* ); 
int k = foo( 5 ); 

190 base operator operands must be " _ segment :> pointer " 

The base operator (:>) requires the left operand to be of type_segment and the right 

operand to be a pointer. 

Example: 

char _ based ( void ) *pcb; 

char _far *pcf = pcb; // needs :> operator 

Examples of typical uses are as follows: 

Example: 

const _segment mySegAbs = 0x4000; 

char_based( void ) *c_ bv = 24; 

char_far *c_ fp_ 1 = mySegAbs :> c_ bv; 

char_far *c_ fp_ 2 =_segname ( DATA" ) :> c_ bv; 

191 expression must be a pointer or a zero constant 

In a conditional expression, if one side of the is a pointer then the other side must also be 
a pointer or a zero constant. 

Example: 

extern int a; 

int *p=(a>7) ? &a : 12; 

192 left expression pointer type cannot be incremented or decremented 

The expression requires that the scaling size of the pointer be known. Pointers to functions, 
arrays of unknown size, or void cannot be incremented because there is no size defined for 
functions, arrays of unknown size, or void. 

Example: 

void *p; 

void *q = p + 2; 

193 right expression pointer type cannot be incremented or decremented 

The expression requires that the scaling size of the pointer be known. Pointers to functions, 
arrays of unknown size, or void cannot be incremented because there is no size defined for 
functions, arrays of unknown size, or void. 
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Example: 

void *p; 

void *q = 2 + p; 

194 expression pointer type cannot be incremented or decremented 

The expression requires that the scaling size of the pointer be known. Pointers to functions, 
arrays of unknown size, or void cannot be incremented because there is no size defined for 
functions, arrays of unknown size, or void. 

Example: 

void *p; 
void *q = ++p; 

195 ’sizeof is not allowed for a function 

A function has no size defined for it by the C++ language specification. 

Example: 

typedef int FT( int ); 
unsigned y = sizeof ( FT ); 

196 ’sizeof is not allowed for type void 

The type void has no size defined for it by the C++ language specification. 

Example: 

void *p; 

unsigned size = sizeof( *p ); 

197 type cannot be defined in this context 

A type cannot be defined in certain contexts. For example, a new type cannot be defined in 
an argument list, a new expression, a conversion function identifier, or a catch handler. 

Example: 

extern int goop (); 
int foo () 

{ 

try { 

return goop (); 

} catch( struct S { int s; } ) { 

return 2; 

} 

} 
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198 expression cannot be used as a class template parameter 

The compiler has to be able to compare expressions during compilation so this limits the 
complexity of expressions that can be used for template parameters. The only types of 
expressions that can be used for template parameters are constant integral expressions and 
addresses. Any symbols must have external linkage or must be static class members. 

199 premature end-of-file encountered during compilation 

The compiler expects more source code at this point. This can be due to missing 
parentheses (’)’) or missing closing braces (’}’). 

200 duplicate case value ’%s’ after conversion to type of switch expression 

A duplicate case value has been found. Keep in mind that all case values must be 
converted to the type of the switch expression. Constants that may be different initially 
may convert to the same value. 

Example: 

enum E { el, e2 }; 
void foo( short a ) 

{ 

switch( a ) { 

case 1: 

case 0x10001: // converts to 1 as short 

break; 

} 

} 

201 declaration statement follows an if statement 

There are implicit scopes created for most control structures. Because of this, no code can 
access any of the names declared in the declaration. Although the code is legal it may not 
be what the programmer intended. 

Example: 

void foo( int a ) 

{ 

if ( a ) 
int b = 14; 

} 

202 declaration statement follows an else statement 

There are implicit scopes created for most control structures. Because of this, no code can 
access any of the names declared in the declaration. Although the code is legal it may not 
be what the programmer intended. 
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Example: 


void too( 

int a 

{ 


if ( a 

) 

int c 

LO 

t—1 

II 

else 


int b 

= 14; 


} 


203 declaration statement follows a switch statement 

There are implicit scopes created for most control structures. Because of this, no code can 
access any of the names declared in the declaration. Although the code is legal it may not 
be what the programmer intended. 

Example: 

void foo( int a ) 

{ 

switch ( a ) 
int b = 14; 

} 

204 ’this ’ pointer is not defined 

The this value can only be used from within non-static member functions. 

Example: 

void *fn() 

{ 

return this; 

} 

205 declaration statement cannot follow a while statement 

There are implicit scopes created for most control structures. Because of this, no code can 
access any of the names declared in the declaration. Although the code is legal it may not 
be what the programmer intended. 

Example: 

void too( int a ) 

{ 

while( a ) 
int b = 14; 

} 

206 declaration statement cannot follow a do statement 

There are implicit scopes created for most control structures. Because of this, no code can 
access any of the names declared in the declaration. Although the code is legal it may not 
be what the programmer intended. 
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Example: 

void foo( int a ) 

{ 

do 

int b = 14; 
while( a ); 

} 

207 declaration statement cannot follow a for statement 

There are implicit scopes created for most control structures. Because of this, no code can 
access any of the names declared in the declaration. Although the code is legal it may not 
be what the programmer intended. A for loop with an initial declaration is allowed to be 
used within another for loop, so this code is legal C++: 

Example: 

void fn( int **a ) 

{ 

for ( int i = 0; i < 10; ++i ) 

for ( int j = 0; j < 10; ++j ) 

a [i] [ j] = i + j; 

} 

The following example, however, illustrates a potentially erroneous situation. 

Example: 

void foo( int a ) 

{ 

for( ; a<10; ) 

int b = 14; 

} 

208 pointer to virtual base class converted to pointer to derived class 

Since the relative position of a virtual base can change through repeated derivations, this 
conversion is very dangerous. All C++ translators must report an error for this type of 
conversion. 

Example: 

struct VBase { int v; } ; 

struct Der : virtual public VBase { int d; }; 
extern VBase *pv; 

Der *pd = (Der *)pv; 

209 cannot use far pointer in this context 

Only near pointers can be thrown when the data memory model is near. 
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Example: 

extern int _ far *p; 

void foo() 

{ 

throw p; 

} 

When the small memory model (-ms switch) is selected, the throw expression is diagnosed 
as erroneous. Similarly, only near pointers can be specified in catch statements when the 
data memory model is near. 

210 returning reference to function argument or to auto or register variable 

The storage for the automatic variable will be destroyed immediately upon function return. 
Returning a reference effectively allows the caller to modify storage which does not exist. 

Example: 

class C 

{ 

char *p; 
public: 

CO; 

~C () ; 

1 ; 

C& foo() 

{ 

C auto_ var; 

return auto_ var; // not allowed 

} 

211 #pragma attributes for ’%S’ may be inconsistent 

A pragma attribute was changed to a value which matches neither the current default not 
the previous value for that attribute. A warning is issued since this usually indicates an 
attribute is being set twice (or more) in an inconsistent way. The warning can also occur 
when the default attribute is changed between two pragmas for the same object. 

212 function arguments cannot be of type void 

Having more than one void argument is not allowed. The special case of one void 
argument indicates that the function accepts no parameters. 


Example: 





void 

{ 

fnl ( 

void ) 

// OK 


} 

void 

fn2 ( 

void, void. 

void ) 

/ / Error 


{ 

} 
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213 class template ’%M’ requires more parameters for instantiation 

The class template instantiation has too few parameters supplied so the class cannot be 
instantiated properly. 

214 class template ’%M’ requires fewer parameters for instantiation 

The class template instantiation has too many parameters supplied so the class cannot be 
instantiated properly. 

215 no declared ’operator new’ has arguments that match 

An operator new could not be found to match the new expression. Supply the correct 
arguments for special operator new functions that are defined with the placement syntax. 

Example: 

♦include <stddef.h> 
struct S { 

void *operator new ( size_ t, char ); 

} ; 

void fn() 

{ 

S *p = new ('a') S; 

} 

216 wide character string concatenated with a simple character string 

There are no semantics defined for combining a wide character string with a simple 
character string. To correct the problem, make the simple character string a wide character 
string by prefixing it with a L. 

Example: 

char *p = "1234" L"5678"; 

217 ’offsetof is not allowed for a static member 

A static member does not have an offset like simple data members. If this is required, use 
the address of the static member. 

Example: 

♦include <stddef.h> 


class C 
{ 

public: 



static int stat; 





} ; 

int memb; 





int 

size_ 1 = offsetof( 

c. 

stat ); 

// 

not allowed 

int 

size_ 2 = offsetof( 

c. 

memb ); 

// 

ok 
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218 cannot define an array of void 

Since the void type has no size and there are no values of void type, one cannot declare an 
array of void. 

Example: 

void array[24]; 

219 cannot define an array of references 

References are not objects, they are simply a way of creating an efficient alias to another 
name. Creating an array of references is currently not allowed in the C++ language. 

Example: 

int& array[24]; 

220 cannot define a reference to void 

One cannot create a reference to a void because there can be no void variables to supply for 
initializing the reference. 

Example: 

voids ref; 

221 cannot define a reference to another reference 

References are not objects, they are simply a way of creating an efficient alias to another 
name. Creating a reference to another reference is currently not allowed in the C++ 
language. 

Example: 

int & & ref; 

222 cannot define a pointer to a reference 

References are not objects, they are simply a way of creating an efficient alias to another 
name. Creating a pointer to a reference is currently not allowed in the C++ language. 

Example: 

chars *ptr; 

223 cannot initialize array with ’operator new’ 

The initialization of arrays created with operator new can only be done with default 
constructors. The capability of using another constructor with arguments is currently not 
allowed in the C++ language. 
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Example: 

struct S 

{ 

S ( int ); 

} ; 

S *p = new S[10] ( 12 ); 

224 ’%N’ is a variable of type void 

A variable cannot be of type void. The void type can only be used in restricted 
circumstances because it has no size. For instance, a function returning void means that it 
does not return any value. A pointer to void is used as a generic pointer but it cannot be 
dereferenced. 

225 cannot define a member pointer to a reference 

References are not objects, they are simply a way of creating an efficient alias to another 
name. Creating a member pointer to a reference is currently not allowed in the C++ 
language. 

Example: 

struct S 

{ 

SO; 

int Sref; 

}; 

int& S : : * p; 

226 function ’%S’ is not distinct 

The function being declared is not distinct enough from the other functions of the same 
name. This means that all function overloads involving the function’s argument types will 
be ambiguous. 

Example: 

struct S { 
int s; 

}; 

extern int foo( S* ); 

extern int foo( S* const ); // not distinct enough 

227 overloaded function is ambiguous for arguments used in call 

The compiler could not find an unambiguous choice for the function being called. 
Example: 

extern int foo( char ); 
extern int foo( short ); 
int k = foo( 4 ); 
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228 declared ’operator new’ is ambiguous for arguments used 

The compiler could not find an unambiguous choice for operator new. 

Example: 

#include <stdlib.h> 
struct Der 
{ 

int s[2]; 

void* operator new( size_t, char ); 
void* operator new ( size_ t, short ); 

} ; 

Der *p = new(10) Der; 

229 function ’%S’ has already been defined 

The function being defined has already been defined elsewhere. Even if the two function 
bodies are identical, there must be only one definition for a particular function. 

Example: 

int foo( int s ) { return s; } 

int foo( int s ) { return s; } // illegal 

230 expression on left is an array 

The array expression is being used in a context where only pointers are allowed. 

Example: 

void fn( void *p ) 

{ 

int a[10]; 

a = 0 ; 
a = p; 
a++; 

} 

231 user-defined conversion has a return type 

A user-defined conversion cannot be declared with a return type. The "return type" of the 
user-defined conversion is implicit in the name of the user-defined conversion. 

Example: 

struct S { 

int operator int(); // cannot have return type 

} ; 

232 user-defined conversion must be a function 

The operator name describing a user-defined conversion can only be used to designate 
functions. 
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Example: 

// operator char can only be a function 
int operator char = 9; 

233 user-defined conversion has an argument list 

A user-defined conversion cannot have an argument list. Since user-defined conversions 
can only be non-static member functions, they have an implicit this argument. 

Example: 

struct S { 

operator int( S& ); // cannot have arguments 

} ; 

234 destructor cannot have a return type 

A destructor cannot have a return type (even void). The destructor is a special member 
function that is not required to be identical in form to all other member functions. This 
allows different implementations to have different uses for any return values. 

Example: 

struct S { 

void* ~S(); 

} ; 

235 destructor must be a function 

The tilde style of name is reserved for declaring destructor functions. Variable names 
cannot make use of the destructor style of names. 

Example: 

struct S { 

int ~S; // illegal 

} ; 

236 destructor has an argument list 

A destructor cannot have an argument list. Since destructors can only be non-static 
member functions, they have an implicit this argument. 

Example: 

struct S { 

~S ( S& ); 

} ; 

237 ’%N’ must be a function 

The operator style of name is reserved for declaring operator functions. Variable names 
cannot make use of the operator style of names. 
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Example: 

struct S { 

int operator+; // illegal 

} ; 


238 ’%N’ is not a function 

The compiler has detected what looks like a function body. The message is a result of not 
finding a function being declared. This can happen in many ways, such as dropping the 
before defining base classes, or dropping the ’=' before initializing a structure via a braced 
initializer. 

Example: 

struct D B { int i; }; 

239 nested type class ’%s’ has not been declared 

A nested class has not been found but is required by the use of repeated operators. The 
construct "A::B::C" requires that 'A' be a class type, and ’B’ be a nested class within the 
scope of ’A'. 

Example: 

struct B { 

static int b; 

} ; 

struct A : public B { 

}; 

int A::B::b=2; // B not nested in A 

The preceding example is illegal; the following is legal 

Example: 

struct A { 

struct B { 
static int b; 

} ; 

} ; 

int A::B::b=2; // B nested in A 

240 enum ’%s’ has not been declared 

An elaborated reference to an enum could not be satisfied. All enclosing scopes have been 
searched for an enum name. Visible variable declarations do not affect the search. 

Example: 

struct D { 
int i; 

enum E { el, e2, e3 }; 

}; 

enum E enum_ var; // E not visible 
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241 class or namespace ’%s’ has not been declared 

The construct "A::B::C" requires that ’A’ be a class type or a namespace, and 'B' be a 
nested class or namespace within the scope of 'A'. The reference to 'A’ could not be 
satisfied. All enclosing scopes have been searched for a class or namespace name. Visible 
variable declarations do not affect the search. 

Example: 

struct A{ int a; }; 
int b; 

int c = B::A::b; 

242 only one initializer argument allowed 

The comma in a function like cast is treated like an argument list comma If a 
comma expression is desired, use parentheses to enclose the comma expression. 

Example: 

void fn() 

{ 

int a; 

a = int( 1, 2 ); // Error! 

a = int ((1,2)); //OK 

} 

243 default arguments are not part of a function’s type 

This message indicates that a declaration has been found that requires default arguments to 
be part of a function's type. Either declaring a function typedef or a pointer to a function 
with default arguments are examples of incorrect declarations. 

Example: 

typedef int TD( int, int a = 14 ); 
int (*p)( int, int a = 14 ) = 0; 

244 missing default arguments 

Gaps in a succession of default arguments are not allowed in the C++ language. 

Example: 

void fn( int = 1, int, int = 3 ); 

245 overloaded operator cannot have default arguments 

Preventing overloaded operators from having default arguments enforces the property that 
binary operators will only be called from a use of a binary operator. Allowing default 
arguments would allow a binary operator + to function as a unary operator +. 
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Example: 

class C 

{ 

public: 

C operator +( int a = 10 ); 

} ; 


246 left expression is not a pointer to a constant object 

One cannot assign a pointer to a constant type to a pointer to a non-constant type. This 
would allow a constant object to be modified via the non-constant pointer. Use a cast if 
this is absolutely necessary. 

Example: 

char* fun( const char* p ) 

{ 

char* q; 

q = p; 

return q; 

} 

247 cannot redefine default argument for ’%S’ 

Default arguments can only be defined once in a program regardless of whether the value 
of the default argument is identical. 

Example: 

static int foo( int a = 10 ); 
static int foo( int a = 10 ) 

{ 

return a+a; 

} 

248 using default arguments would be overload ambiguous with ’%S’ 

The declaration declares enough default arguments that the function is indistinguishable 
from another function of the same name. 

Example: 

void fn( int ); 

void fn( int, int = 1 ); 

Calling the function ’fn’ with one argument is ambiguous because it could match either the 
first ’fn’ without any default arguments or the second ’fn’ with a default argument applied. 

249 using default arguments would be overload ambiguous with ’%S’ using default arguments 

The declaration declares enough default arguments that the function is indistinguishable 
from another function of the same name with default arguments. 
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Example: 

void fn( int, int = 1 ); 
void fn( int, char = 'a' ); 

Calling the function ’fn’ with one argument is ambiguous because it could match either the 
first ’fn’ with a default argument or the second ’fn’ with a default argument applied. 

250 missing default argument for ’%S’ 

In C++, one is allowed to add default arguments to the right hand arguments of a function 
declaration in successive declarations. The message indicates that the declaration is only 
valid if there was a default argument previously declared for the next argument. 

Example: 


void 

fnl ( 

int 

t 

int ) ; 



void 

fnl ( 

int 

t 

int = 3 ); 



void 

fnl ( 

int 

= 2, 

int ) ; 

// 

OK 

void 

fn2 ( 

int 

t 

int ) ; 



void 

fn2 ( 

int 

= 2, 

int ) ; 

// 

Error 


251 enum references must have an identifier 

There is no way to reference an anonymous enum. If all enums are named, the cause of 
this message is most likely a missing identifier. 

Example: 

enum { X, Y, Z }; // anonymous enum 
void fn() 

{ 

enum *p; 

} 

252 class declaration has not been seen for ’~%s’ 

A destructor has been used in a context where its class is not visible. 

Example: 

class C; 

void fun( C* p ) 

{ 

P->~S(); 

} 

253 ’:: ’ qualifier cannot be used in this context 

Qualified identifiers in a class context are allowed for declaring friend member functions. 
The Open Watcom C++ compiler also allows code that is qualified with its own class so 
that declarations can be moved in and out of class definitions easily. 
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Example: 


struct N 

{ 



void 

ba 

r () ; 


} ; 




struct S 

{ 



void 

} 

void 

S : 

:foo () 

{ // OK 

N: 

: bar () 

{ // error 


} 

} ; 


254 ’%S’ has not been declared as a member 

In a definition of a class member, the indicated declaration must already have been declared 
when the class was defined. 

Example: 

class C 

{ 

public: 

int c; 
int goop (); 

} ; 

int C::x = 1; 

C::not_ decled() { } 

255 default argument expression cannot use function argument ’%S’ 

Default arguments must be evaluated at each call. Since the order of evaluation for 
arguments is undefined, a compiler must diagnose all default arguments that depend on 
other arguments. 

Example: 

void goop( int d ) 

{ 

struct S { 

// cannot access "d" 

int foo( int c, int b = d ) 

{ 

return b + c; 

}; 

}; 

} 

256 default argument expression cannot use local variable ’%S’ 

Default arguments must be evaluated at each call. Since a local variable is not always 
available in all contexts (e.g., file scope initializers), a compiler must diagnose all default 
arguments that depend on local variables. 
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Example: 

void goop ( void ) 

{ 

int a; 
struct S { 

// cannot access "a" 

int too( int c, int b = a ) 

{ 

return b + c; 

}; 

}; 

} 

257 access declarations may only be ’public’ or ’protected’ 

Access declarations are used to increase access. A private access declaration is useless 
because there is no access level for which private is an increase in access. 

Example: 

class Base 

{ 

int pri; 
protected: 

int pro; 
public: 

int pub; 

} ; 

class Derived : public Base 

{ 

private: Base::pri; 

} ; 

258 cannot declare both a function and variable of the same name ('%N') 

Functions can be overloaded in C++ but they cannot be overloaded in the presence of a 
variable of the same name. Likewise, one cannot declare a variable in the same scope as a 
set of overloaded functions of the same name. 

Example: 

int foo (); 
int foo; 
struct S { 

int bad(); 
int bad; 

} ; 

259 class in access declaration (’%T’) must be a direct base class 

Access declarations can only be applied to direct (immediate) base classes. 
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Example: 

struct B { 
int f; 

} ; 

struct C : B { 
int g; 

} ; 

struct D : private C { 

B: : f; 

} ; 

In the above example, "C" is a direct base class of "D" and "B" is a direct base class of "C", 
but "B" is not a direct base class of "D". 

260 overloaded functions (’%N’) do not have the same access 

If an access declaration is referencing a set of overloaded functions, then they all must have 
the same access. This is due to the lack of a type in an access declaration. 

Example: 

class C 

{ 

static int foo( int ); 
public: 

static int foo( float ); 

} ; 

class B : private C 

{ 

public: C::foo; 

} ; 

261 cannot grant access to ’%N’ 

A derived class cannot change the access of a base class member with an access 
declaration. The access declaration can only be used to restore access changed by 
inheritance. 

Example: 

class Base 

{ 

public: 

int pub; 
protected: 

int pro; 

} ; 

class Der : private Base 

{ 

public: Base::pub; 
public: Base::pro; 

}; 


// ok 

// changes access 


// private 
// public 
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262 cannot reduce access to ’%N’ 

A derived class cannot change the access of a base class member with an access 
declaration. The access declaration can only be used to restore access changed by 
inheritance. 

Example: 

class Base 

{ 

public: 

int pub; 
protected: 

int pro; 

} ; 

class Der : public Base 

{ 

protected: Base::pub; // changes access 

protected: Base::pro; // ok 

} ; 

263 nested class ’%N’ has not been defined 

The current state of the C++ language supports nested types. Unfortunately, this means 
that some working C code will not work unchanged. 

Example: 

struct S { 

struct T; 

T *link; 

} ; 

In the above example, the class "T" will be reported as not being defined by the end of the 
class declaration. The code can be corrected in the following manner. 

Example: 

struct S { 

struct T; 

T *link; 
struct T { 

} ; 

} ; 

264 user-defined conversion must be a non-static member function 

A user-defined conversion is a special member function that allows the class to be 
converted implicitly (or explicitly) to an arbitrary type. In order to do this, it must have 
access to an instance of the class so it is restricted to being a non-static member function. 
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Example: 

struct S 

{ 

static operator int(); 

} ; 


265 destructor must be a non-static member function 

A destructor is a special member function that will perform cleanup on a class before the 
storage for the class will be released. In order to do this, it must have access to an instance 
of the class so it is restricted to being a non-static member function. 

Example: 

struct S 

{ 

static ~S(); 

} ; 


266 ’%N’ must be a non-static member function 

The operator function in the message is restricted to being a non-static member function. 
This usually means that the operator function is treated in a special manner by the compiler. 

Example: 

class C 

{ 

public: 

static operator =( C&, int ); 

} ; 

267 ’%N’ must have one argument 

The operator function in the message is only allowed to have one argument. An operator 
like operator - is one such example because it represents a unary operator. 

Example: 

class C 

{ 

public: int c; 

} ; 

C& operator-( const C&, int ); 

268 ’%N’ must have two arguments 

The operator function in the message must have two arguments. An operator like operator 
+= is one such example because it represents a binary operator. 
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Example: 

class C 

{ 

public: int c; 

} ; 

C& operator += ( const C& ); 

269 ’%N’ must have either one argument or two arguments 

The operator function in the message must have either one argument or two arguments. An 
operator like operator + is one such example because it represents either a unary or a 
binary operator. 

Example: 

class C 

{ 

public: int c; 

} ; 

C& operator!( const C&, int, float ); 

270 ’%N’ must have at least one argument 

The operator new and operator new [] member functions must have at least one argument 
for the size of the allocation. After that, any arguments are up to the programmer. The 
extra arguments can be supplied in a new expression via the placement syntax. 

Example: 

♦include <stddef.h> 
struct S { 

void * operator new ( size_ t, char ); 

}; 

void fn() 

{ 

S *p = new ('a') S; 

} 

271 ’%N’ must have a return type of void 

The C++ language requires that operator delete and operator delete [] have a return type of 
void. 

Example: 

class C 

{ 

public: 

int c; 

C* operator delete( void* ); 

C* operator delete []( void* ); 

} ; 
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272 ’%N’ must have a return type of pointer to void 

The C++ language requires that both operator new and operator new [] have a return type 
of void * . 

Example: 

♦include <stddef.h> 
class C 
{ 

public: 

int c; 

C* operator new ( size_t size ); 

C* operator new []( size_ t size ); 

} ; 

273 the first argument of ’%N’ must be of type size_t 

The C++ language requires that the first argument for operator new and operator new [] be 
of the type "size_t". The definition for "size_t" can be included by using the standard 
header file <stddef.h>. 

Example: 

void *operator new( int size ); 

void *operator new( double size, char c ); 

void *operator new []( int size ); 

void *operator new []( double size, char c ); 

274 the first argument of ’%N’ must be of type pointer to void 

The C++ language requires that the first argument for operator delete and operator delete 
[] be a void *. 

Example: 

class C; 

void operator delete( C* ) ; 
void operator delete []( C* ); 

275 the second argument of ’%N’ must be of type sizej 

The C++ language requires that the second argument for operator delete and operator 
delete [] be of type "size_t". The two argument form of operator delete and operator delete 
[] is optional and it can only be present inside of a class declaration. The definition for 
"size_t" can be included by using the standard header file <stddef.h>. 

Example: 

struct S { 

void operator delete! void *, char ); 
void operator delete []( void *, char ); 

}; 
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276 the second argument of ’operator ++’ or ’operator — ’ must be hit 

The C++ language requires that the second argument for operator ++ be hit. The two 
argument form of operator ++ is used to overload the postfix operator "++". The postfix 
operator " can be overloaded similarly. 

Example: 

class C { 
public: 

long cv; 

}; 

C& operator ++ ( C&, unsigned ); 

277 return type of ’%S’ must allow the ’->’ operator to be applied 

This restriction is a result of the transformation that the compiler performs when the 
operator -> is overloaded. The transformation involves transforming the expression to 
invoke the operator with applied to the result of operator ->. 

Example: 

struct S { 
int a; 

S *operator ->(); 

1 ; 

void fn( S &q ) 

{ 

q->a = 1; // becomes (q.operator ->())->a = 1; 

} 

278 ’%N’ must take at least one argument of a class/enum or a reference to a class/enum 

Overloaded operators can only be defined for classes and enumerations. At least one 
argument, must be a class or an enum type in order for the C++ compiler to distinguish the 
operator from the built-in operators. 

Example: 

class C { 
public: 

long cv; 

}; 

C& operator ++( unsigned, int ); 

279 too many initializers 

The compiler has detected extra initializers. 

Example: 

int a [3] = { 1, 2, 3, 4 }; 


Diagnostic Messages 397 




Appendices 


280 too many initializers for character string 

A string literal used in an initialization of a character array is viewed as providing the 
terminating null character. If the number of array elements isn't enough to accept the 
terminating character, this message is output. 

Example: 

char ac[3] = "abc"; 

281 expecting ’%s ’ but found expression 

This message is output when some bracing or punctuation is expected but an expression 
was encountered. 

Example: 

int b[3] = 3; 

282 anonymous struct/union member ’%N’ cannot be declared in this class 

An anonymous member cannot be declared with the same name as its containing class. 

Example: 

struct S { 
union { 

int S; // Error! 

char b; 

} ; 

} ; 

283 unexpected ’%s’ during initialization 

This message is output when some unexpected bracing or punctuation is encountered 
during initialization. 

Example: 

int e = { { 1 }; 

284 nested type ’%N’ cannot be declared in this class 

A nested type cannot be declared with the same name as its containing class. 

Example: 

struct S { 

typedef int S; // Error! 

} ; 

285 enumerator ’%N’ cannot be declared in this class 

An enumerator cannot be declared with the same name as its containing class. 
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Example: 

struct S { 

enum E { 

S, // Error! 
T 
} ; 

} ; 


286 static member ’%N’ cannot be declared in this class 

A static member cannot be declared with the same name as its containing class. 

Example: 

struct S { 

static int S; // Error! 

} ; 

287 constructor cannot have a return type 

A constructor cannot have a return type (even void ). The constructor is a special member 
function that is not required to be identical in form to all other member functions. This 
allows different implementations to have different uses for any return values. 

Example: 

class C { 
public: 

C& C ( int ); 

1 ; 

288 constructor cannot be a static member 

A constructor is a special member function that takes raw storage and changes it into an 
instance of a class. In order to do this, it must have access to storage for the instance of the 
class so it is restricted to being a non-static member function. 

Example: 

class C { 
public: 

static C( int ); 

} ; 

289 invalid copy constructor argument list (causes infinite recursion) 

A copy constructor’s first argument must be a reference argument. Furthermore, any 
default arguments must also be reference arguments. Without the reference, a copy 
constructor would require a copy constructor to execute in order to prepare its arguments. 
Unfortunately, this would be calling itself since it is the copy constructor. 
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Example: 

struct S { 

S ( S const & ); // copy constructor 

} ; 


290 constructor cannot be declared const or volatile 

A constructor must be able to operate on all instances of classes regardless of whether they 
are const or volatile. 

Example: 

class C { 
public: 

C( int ) const; 

C ( float ) volatile; 

} ; 

291 constructor cannot be virtual 

Virtual functions cannot be called for an object before it is constructed. For this reason, a 
virtual constructor is not allowed in the C++ language. Techniques for simulating a virtual 
constructor are known, one such technique is described in the ARM p.263. 

Example: 

class C { 
public: 

virtual C( int ); 

1 ; 

292 types do not match in simple type destructor 

A simple type destructor is available for "destructing" simple types. The destructor has no 
effect. Both of the types must be identical, for the destructor to have meaning. 

Example: 

void foo( int *p ) 

{ 

p->int::-double(); 

} 

293 overloaded operator is ambiguous for operands used 

The Open Watcom C++ compiler performs exhaustive analysis using formalized 
techniques in order to decide what implicit conversions should be applied for overloading 
operators. Because of this. Open Watcom C++ detects ambiguities that may escape other 
C++ compilers. The most common ambiguity that Open Watcom C++ detects involves 
classes having constructors with single arguments and a user-defined conversion. 
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Example: 

struct S { 

S(int); 

operator int(); 
int a; 

} ; 

int fn( int b, int i, S s ) 

{ 

// i : s.operator int() 

// OR S(i) : s 
return b ? i : s; 

} 

In the above example, "i" and "s" must be brought to a common type. Unfortunately, there 
are two common types so the compiler cannot decide which one it should choose, hence an 
ambiguity. 

294 feature not implemented 

The compiler does not support the indicated feature. 

295 invalid friend declaration 

This message indicates that the compiler found extra declaration specifiers like auto, float, 
or const in the friend declaration. 

Example: 

class C 

{ 

friend float; 

} ; 

296 friend declarations may only be declared in a class 

This message indicates that a friend declaration was found outside a class scope (i.e., a 
class definition). Friends are only meaningful for class types. 

Example: 

extern void foo(); 
friend void foo(); 

297 class friend declaration needs ’class’ or ’struct’ keyword 

The C++ language has evolved to require that all friend class declarations be of the form 
"class S" or "struct S". The Open Watcom C++ compiler accepts the older syntax with a 
warning but rejects the syntax in pure ISO/ANSI C++ mode. 
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Example: 

struct S; 
struct T { 

friend S; // should be "friend class S;" 

} ; 


298 class friend declarations cannot contain a class definition 

A class friend declaration cannot define a new class. This is a restriction required in the 
C++ language. 

Example: 

struct S { 

friend struct X { 
int f; 

} ; 


299 ’%T’ has already been declared as a friend 

The class in the message has already been declared as a friend. Remove the extra friend 
declaration. 

Example: 

class S; 
class T { 

friend class S; 
int tv; 

friend class S; 

} ; 

300 function ’%S’ has already been declared as a friend 

The function in the message has already been declared as a friend. Remove the extra friend 
declaration. 

Example: 

extern void foo(); 
class T { 

friend void foo(); 
int tv; 

friend void foo(); 

} ; 

301 friend’, ’virtual’ or ’inline’ modifiers are not part of a function’s type 

This message indicates that the modifiers may be incorrectly placed in the declaration. If 
the declaration is intended, it cannot be accepted because the modifiers can only be applied 
to functions that have code associated with them. 
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Example: 

typedef friend (*PF)( void ); 

302 cannot assign right expression to element on left 

This message indicates that the assignment cannot be performed. It usually arises in 
assignments of a class type to an arithmetic type. 

Example: 

struct S 


{ 

int sv; 

} ; 


S s; 


int 

foo () 

{ 



int k; 


k = s; 
return k; 

} 

303 constructor is ambiguous for operands used 

The operands provided for the constructor did not select a unique constructor. 

Example: 

struct S { 

S(int); 

S(char); 

} ; 

S x = S (1.0 ) ; 

304 class ’%s’ has not been defined 

The name before a scope resolution operator must be defined unless a member pointer 
is being declared. 

Example: 

struct S; 

int S : : * p; // OK 

int S::a = 1; // Error! 

305 all bit-fields in a union must be named 

This is a restriction in the C++ language. The same effect can be achieved with a named 
bitfield. 
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Example: 

union u 

{ unsigned bitl :10; 
unsigned :6; 

} ; 


306 cannot convert expression to type of cast 

The cast is trying to convert an expression to a completely unrelated type. There is no way 
the compiler can provide any meaning for the intended cast. 

Example: 

struct T { 

1 ; 

void fn() 

{ 

T y = (T) 0; 

} 

307 conversion ambiguity: [expression] to [cast type] 

The cast caused a constructor overload to occur. The operands provided for the constructor 
did not select a unique constructor. 

Example: 

struct S { 

S(int); 

S(char); 

}; 


void fn() 

{ 

S x = (S) 1.0; 

1 

308 an anonymous class without a declarator is useless 

There is no way to reference the type in this kind of declaration. A name must be provided 
for either the class or a variable using the class as its type. 

Example: 

struct { 
int a; 
int b; 

1 ; 


309 global anonymous union must be declared static 

This is a restriction in the C++ language. Since there is no unique name for the anonymous 
union, it is difficult for C++ translators to provide a correct implementation of external 
linkage anonymous unions. 
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Example: 

static union { 
int a; 
int b; 

} ; 


310 anonymous struct/union cannot have storage class in this context 

Anonymous unions (or structs) declared in class scopes cannot be static. Any other storage 
class is also disallowed. 

Example: 

struct S { 

static union { 
int iv; 
unsigned us; 

} ; 


311 union contains a protected member 

A union cannot have a protected member because a union cannot be a base class. 

Example: 

static union { 
int iv; 

protected: 

unsigned sv; 

} u; 

312 anonymous struct/union contains a private member ’%S’ 

An anonymous union (or struct) cannot have member functions or friends so it cannot have 

private members since no code could access them. 

Example: 

static union { 
int iv; 

private: 

unsigned sv; 

} ; 


313 anonymous struct/union contains a function member ’%S’ 

An anonymous union (or struct) cannot have any function members. This is a restriction in 
the C++ language. 

Example: 

static union { 
int iv; 

void foo(); // error 

unsigned sv; 
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314 anonymous struct/union contains a typedef member ’%S’ 

An anonymous union (or struct) cannot have any nested types. This is a restriction in the 
C++ language. 

Example: 

static union { 
int iv; 
unsigned sv; 
typedef float F; 

F fv; 

} ; 

315 anonymous struct/union contains an enumeration member ’%S’ 

An anonymous union (or struct) cannot have any enumeration members. This is a 
restriction in the C++ language. 

Example: 

static union { 
int iv; 

enum choice { good, bad, indifferent }; 
choice c; 
unsigned sv; 

} ; 

316 anonymous struct/union member ’%s’ is not distinct in enclosing scope 

Since an anonymous union (or struct) provides its member names to the enclosing scope, 
the names must not collide with other names in the enclosing scope. 

Example: 

int iv; 
unsigned sv; 
static union { 
int iv; 
unsigned sv; 

} ; 

317 unions cannot have members with destructors 

A union should only be used to organize memory in C++. Allowing union members to 
have destructors would mean that the same piece of memory could be destructed twice. 

Example: 

struct S { 

int svl, sv2, sv3; 

}; 

struct T { 

~T () ; 

1 ; 

static union 

{ 

S su; 

T tu; 

1 ; 
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318 


319 


unions cannot have members with user-defined assignment operators 

A union should only be used to organize memory in C++. Allowing union members to 
have assignment operators would mean that the same piece of memory could be assigned 
twice. 


Example: 

struct S { 

int svl, sv2, sv3; 

} ; 

struct T { 
int tv; 

operator = ( int ) ; 
operator = ( float 

} ; 

static union 

{ 

S su; 

T tu; 

} u; 


anonymous struct/union cannot have any friends 

An anonymous union (or struct) cannot have any friends. This is a restriction in the C++ 
language. 


Example: 

struct S { 

int svl, sv2, sv3; 

} ; 

static union { 

S sul; 

S su2; 

friend class S; 

} ; 


320 specific versions of template classes can only be defined in file scope 

Currently, specific versions of class templates can only be declared at file scope. This 
simple restriction was chosen in favour of more freedom with possibly subtle restrictions. 

Example: 
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template <class G> class S { 

G x; 

} ; 

struct Q { 

struct S<int> { 
int x; 

}; 

} ; 

void too () 

{ 

struct S<double> { 
double x; 

} ; 

} 

321 anonymous union in a function may only be static or auto 

The current C++ language definition only allows auto anonymous unions. The Open 
Watcom C++ compiler allows static anonymous unions. Any other storage class is not 
allowed. 

322 static data members are not allowed in a local class 

Static data members are not allowed in a local class because there is no way to define the 
static member in file scope. 

Example: 

int foo () 

{ 

struct local { 
static int s; 

} ; 

local lv; 

lv.s = 3; 
return lv.s; 

} 

323 conversion ambiguity: [return value] to [return type of function] 

The cast caused a constructor overload to occur. The operands provided for the constructor 
did not select a unique constructor. 

Example: 

struct S { 

S(int); 

S(char); 

} ; 

S fn() 

{ 

return 1.0; 

} 
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324 conversion of return value is impossible 

The return is trying to convert an expression to a completely unrelated type. There is no 
way the compiler can provide any meaning for the intended return type. 

Example: 

struct T { 

1 ; 

T fn() 

{ 

return 0; 

} 

325 function cannot return a pointer based on _ self 

A function cannot return a pointer that is based on_ self. 

Example: 

void_based(_self) *fn( unsigned ); 

326 defining ’%S’ is not possible because its type has unknown size 

In order to define a variable, the size must be known so that the correct amount of storage 
can be reserved. 

Example: 

class S; 

S sv; 

327 typedef cannot be initialized 

Initializing a typedef is meaningless in the C++ language. 

Example: 

typedef int INT = 15; 

328 storage class of ’%S’ conflicts with previous declaration 

The symbol declaration conflicts with a previous declaration with regard to storage class. 
A symbol cannot be both static and extern. 

329 modifiers of ’%S’ conflict with previous declaration 

The symbol declaration conflicts with a previous declaration with regard to modifiers. 
Correct the program by using the same modifiers for both declarations. 
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330 function cannot be initialized 

A function cannot be initialized with an initializer syntax intended for variables. A 
function body is the only way to provide a definition for a function. 

331 access permission of nested class ’%T’ conflicts with previous declaration 

Example: 

struct S { 

struct N; // public 
private: 

struct N { // private 

}; 

} ; 

332 *** FATAL *** internal error in front end 

If this message appears, please report the problem directly to the Open Watcom 
development team. See http://www.openwatcom.org/. 

333 cannot convert argument to type specified in function prototype 
It is impossible to convert the indicated argument in the function. 

Example: 

extern int too( int& ); 

extern int m; 
extern int n; 

int k = too( m + n ); 

In the example, the value of "m+n" cannot be converted to a reference (it could be 
converted to a constant reference), as shown in the following example. 

Example: 

extern int too( const int& ); 

extern int m; 
extern int n; 

int k = too(m+n ); 

334 conversion ambiguity: [argument] to [argument type in prototype] 

An argument in the function call could not be converted since there is more than one 
constructor or user-defined conversion which could be used to convert the argument. 
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Example: 

struct S; 

struct T 

{ 

T( S& ); 

} ; 

struct S 

{ 

operator T(); 

} ; 

S s; 

extern int foo( T ); 

int k = foo( s ); // ambiguous 

In the example, the argument "s" could be converted by both the constructor in class "T" 
and by the user-conversion in class "S". 

335 cannot be based on based pointer ’%S’ 

A based pointer cannot be based on another based pointer. 

Example: 

_segment s; 

void _based(s) *p; 

void_based(p) *q; 

336 declaration specifiers are required to declare ’%N’ 

The compiler has detected that the name does not represent a function. Only function 
declarations can leave out declaration specifiers. This error also shows up when a typedef 
name declaration is missing. 

Example: 

x; 

typedef int; 

337 static function declared in block scope 

The C++ language does not allow static functions to be declared in block scope. This error 
can be triggered when the intent is to define a static variable. Due to the complexities of 
parsing C++, statements that appear to be variable definitions may actually parse as 
function prototypes. A work-around for this problem is contained in the example. 

Example: 
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struct C { 

} ; 

struct S { 

S ( C ) ; 

} ; 

void foo() 

{ 

static S a( C() ); // function prototype! 
static S b( (C()) );// variable definition 

} 

338 cannot define a _ based reference 

A C++ reference cannot be based on anything. Based modifiers can only be used with 
pointers. 

Example: 

_segment s; 

void fn( int_based(s) & x ); 

339 conversion ambiguity: conversion to common pointer type 

A conversion to a common base class of two different pointers has been attempted. The 
pointer conversion could not be performed because the destination type points to an 
ambiguous base class of one of the source types. 

340 cannot construct object from arguments) 

There is not an appropriate constructor for the set of arguments provided. 

341 number of arguments for function ’%S’ is incorrect 

The number of arguments in the function call does not match the number declared for the 
indicated non-overloaded function. 

Example: 

extern int foo( int, int ); 
int k = foo( 1, 2, 3 ); 

In the example, the function was declared to have two arguments. Three arguments were 
used in the call. 

342 private base class accessed to convert cast expression 

A conversion involving the inheritance hierarchy required access to a private base class. 
The access check did not succeed so the conversion is not allowed. 


412 Diagnostic Messages 




Open Watcom C++ Diagnostic Messages 


Example: 

struct Priv 

{ 

int p; 

} ; 

struct Der : private Priv 

{ 

int d; 

} ; 

extern Der *pd; 

Priv *pp = (Priv*)pd; 

343 private base class accessed to convert return expression 

A conversion involving the inheritance hierarchy required access to a private base class. 
The access check did not succeed so the conversion is not allowed. 

Example: 

struct Priv 

{ 

int p; 

} ; 

struct Der : private Priv 

{ 

int d; 

} ; 

Priv *foo( Der *p ) 

{ 

return p; 

} 

344 cannot subtract pointers to different objects 

Pointer subtraction can be performed only for objects of the same type. 

Example: 

♦include <stddef.h> 

ptrdiff_t diff ( float *fp, int *ip ) 

{ 

return fp - ip; 

} 

In the example, a diagnostic results from the attempt to subtract a pointer to an int object 
from a pointer to a float object. 

345 private base class accessed to convert to common pointer type 

A conversion involving the inheritance hierarchy required access to a private base class. 
The access check did not succeed so the conversion is not allowed. 
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Example: 

struct Priv 

{ 

int p; 

} ; 

struct Der : private Priv 

{ 

int d; 

} ; 

int foo( Der *pd, Priv *pp ) 

{ 

return pd == pp; 

} 

346 protected base class accessed to convert cast expression 

A conversion involving the inheritance hierarchy required access to a protected base class. 
The access check did not succeed so the conversion is not allowed. 

Example: 

struct Prot 

{ 

int p; 

} ; 

struct Der : protected Prot 

{ 

int d; 

}; 

extern Der *pd; 

Prot *pp = (Prot*)pd; 

347 protected base class accessed to convert return expression 

A conversion involving the inheritance hierarchy required access to a protected base class. 
The access check did not succeed so the conversion is not allowed. 

Example: 

struct Prot 

{ 

int p; 

}; 

struct Der : protected Prot 

{ 

int d; 

}; 

Prot *foo( Der *p ) 

{ 

return p; 

} 
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348 cannot define a member pointer with a memory model modifier 

A member pointer describes how to access a field from a class. Because of this a member 
pointer must be independent of any memory model considerations. 

Example: 

struct S; 

int near S::*mp; 

349 protected base class accessed to convert to common pointer type 

A conversion involving the inheritance hierarchy required access to a protected base class. 
The access check did not succeed so the conversion is not allowed. 

Example: 

struct Prot 

{ 

int p; 

}; 

struct Der : protected Prot 

{ 

int d; 

}; 

int too( Der *pd, Prot *pp ) 

{ 

return pd == pp; 

} 

350 non-type parameter supplied for a type argument 

A non-type parameter (e.g., an address or a constant expression) has been supplied for a 
template type argument. A type should be used instead. 

351 type parameter supplied for a non-type argument 

A type parameter (e.g., int ) has been supplied for a template non-type argument. An 
address or a constant expression should be used instead. 

352 cannot access enclosing function’s auto variable ’%S’ 

A local class member function cannot access its enclosing function’s automatic variables. 
Example: 

void goop( void ) 

{ 

int a; 
struct S 
{ 

int too( int c, int b ) 

{ 

return b + c + a; 

}; 

} ; 

} 
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353 cannot initialize pointer to non-constant with a pointer to constant 

A pointer to a non-constant type cannot be initialized with a pointer to a constant type 
because this would allow constant data to be modified via the non-constant pointer to it. 

Example: 

extern const int *pic; 
extern int *pi = pic; 

354 pointer expression is always >= 0 

The indicated pointer expression will always be true because the pointer value is always 
treated as an unsigned quantity, which will be greater or equal to zero. 

Example: 

extern char *p; 

unsigned k = ( 0 <= p ); // always 1 

355 pointer expression is never < 0 

The indicated pointer expression will always be false because the pointer value is always 
treated as an unsigned quantity, which will be greater or equal zero. 

Example: 

extern char *p; 

unsigned k = ( 0 >= p ); // always 0 

356 type cannot be used in this context 

This message is issued when a type name is being used in a context where a non-type name 
should be used. 

Example: 

struct S { 

typedef int T; 

} ; 

void fn( S *p ) 

{ 

p->T = 1; 

} 

357 virtual function may only be declared in a class 

Virtual functions can only be declared inside of a class. This error may be a result of 
forgetting the "C::" qualification of a virtual function’s name. 
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Example: 

virtual void foo(); 
struct S 
{ 

int f; 

virtual void bar(); 

} ; 

virtual void bar() 

{ 

f = 9; 

} 

358 ’%T’ referenced as a union 

A class type defined as a class or struct has been referenced as a union (i.e., union S). 

Example: 

struct S 

{ 

int si, s2; 

} ; 

union S var; 

359 union ’%T’ referenced as a class 

A class type defined as a union has been referenced as a struct or a class (i.e., class S). 

Example: 

union S 

{ 

int si, s2; 

} ; 

struct S var; 

360 typedef ’%N’ defined without an explicit type 

The typedef declaration was found to not have an explicit type in the declaration. If int is 
the desired type, use an explicit int keyword to specify the type. 

Example: 

typedef T; 

361 member function was not defined in its class 

Member functions of local classes must be defined in their class if they will be defined at 
all. This is a result of the C++ language not allowing nested function definitions. 

Example: 

void fn() 

{ 

struct S { 
int bar(); 

} ; 

} 
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362 local class can only have its containing function as a friend 

A local class can only be referenced from within its containing function. It is impossible to 
define an external function that can reference the type of the local class. 

Example: 

extern void ext(); 
void too () 

{ 

class S 

{ 

int s; 
public: 

friend void ext(); 
int q; 

} ; 

} 

363 local class cannot have ’%S’ as a friend 

The only classes that a local class can have as a friend are classes within its own containing 
scope. 

Example: 

struct ext 

{ 

goop (); 

1 ; 

void foo() 

{ 

class S 

{ 

int s; 
public: 

friend class ext; 
int q; 

} ; 

} 

364 adjacent >=, <=, >, < operators 

This message is warning about the possibility that the code may not do what was intended. 
An expression like "a > b > c" evaluates one relational operator to a 1 or a 0 and then 
compares it against the other variable. 

Example: 

extern int a; 
extern int b; 
extern int c; 
int k = a > b > c; 
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365 cannot access enclosing function’s argument ’%S’ 

A local class member function cannot access its enclosing function’s arguments. 

Example: 

void goop( int d ) 

{ 

struct S 

{ 

int too( int c, int b ) 

{ 

return b + c + d; 

}; 

} ; 

} 

366 support for switch ’%s’ is not implemented 

Actions for the indicated switch have not been implemented. The switch is supported for 
compatibility with the Open Watcom C compiler. 

367 conditional expression in if statement is always true 

The compiler has detected that the expression will always be true. If this is not the 
expected behaviour, the code may contain a comparison of an unsigned value against zero 
(e.g., unsigned integers are always greater than or equal to zero). Comparisons against zero 
for addresses can also result in trivially true expressions. 

Example: 

♦define TEST 143 

int foo ( int a, int b ) 

{ 

if ( TEST ) return a; 
return b; 

} 

368 conditional expression in if statement is always false 

The compiler has detected that the expression will always be false. If this is not the 
expected behaviour, the code may contain a comparison of an unsigned value against zero 
(e.g., unsigned integers are always greater than or equal to zero). Comparisons against zero 
for addresses can also result in trivially false expressions. 

Example: 

♦define TEST 14-14 
int foo( int a, int b ) 

{ 

if ( TEST ) return a; 
return b; 

} 
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369 selection expression in switch statement is a constant value 

The expression in the switch statement is a constant. This means that only one case label 
will be executed. If this is not the expected behaviour, check the switch expression. 

Example: 

♦define TEST 0 

int foo( int a, int b ) 

{ 

switch ( TEST ) { 

case 0: 
return a; 

default: 
return b; 

} 

1 

370 constructor is required for a class with a const member 

If a class has a constant member, a constructor is required in order to initialize it. 

Example: 

struct S 

{ 

const int s; 
int i; 


371 constructor is required for a class with a reference member 

If a class has a reference member, a constructor is required in order to initialize it. 

Example: 

struct S 

{ 

int& r; 
int i; 


372 inline member friend function ’%S’ is notallowed 

A friend that is a member function of another class cannot be defined. Inline friend rules 
are currently in flux so it is best to avoid inline friends. 

373 invalid modifier for auto variable 

An automatic variable cannot have a memory model adjustment because they are always 
located on the stack (or in a register). There are also other types of modifiers that are not 
allowed for auto variables such as thread-specific data modifiers. 
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Example: 

int fn( int far x ) 

{ 

int far y = x + 1; 
return y; 

} 

374 object (or object pointer) required to access non-static data member 

A reference to a member in a class has occurred. The member is non-static so in order to 
access it, an object of the class is required. 

Example: 

struct S { 
int m; 

static void fn() 

{ 

m = 1; // Error! 

} 

}; 

375 user-defined conversion has not been declared 

The named user-defined conversion has not been declared in the class of any of its base 
classes. 

Example: 

struct S { 

operator int(); 
int a; 

} ; 

double fn( S *p ) 

{ 

return p->operator double(); 

} 

376 virtual function must be a non-static member function 

A member function cannot be both a static function and a virtual function. A static 
member function does not have a this argument whereas a virtual function must have a this 
argument so that the virtual function table can be accessed in order to call it. 

Example: 

struct S 

{ 

static virtual int foo(); // error 
virtual int bar(); // ok 

static int stat(); // ok 

} ; 
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377 protected base class accessed to convert argument expression 

A conversion involving the inheritance hierarchy required access to a protected base class. 
The access check did not succeed so the conversion is not allowed. 

Example: 

class C 

{ 

protected: 

C ( int ); 
public: 

int c; 

} ; 

int cfun( C ); 
int i = cfun( 14 ); 

The last line is erroneous since the constructor is protected. 

378 private base class accessed to convert argument expression 

A conversion involving the inheritance hierarchy required access to a private base class. 
The access check did not succeed so the conversion is not allowed. 

Example: 

class C 

{ 

C ( int ); 
public: 

int c; 

} ; 

int cfun( C ); 
int i = cfun( 14 ); 

The last line is erroneous since the constructor is private. 

379 delete expression will invoke a non-virtual destructor 

In C++, it is possible to assign a base class pointer the value of a derived class pointer so 
that code that makes use of base class virtual functions can be used. A problem that occurs 
is that a delete has to know the correct size of the type in some instances (i.e., when a two 
argument version of operator delete is defined for a class). This problem is solved by 
requiring that a destructor be defined as virtual if polymorphic deletes must work. The 
delete expression will virtually call the correct destructor, which knows the correct size of 
the complete object. This message informs you that the class you are deleting has virtual 
functions but it has a non-virtual destructor. This means that the delete will not work 
correctly in all circumstances. 
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Example: 

♦include <stddef.h> 

struct B { 
int b; 

void operator delete( void *, size_t ); 
virtual void fn(); 

~B () ; 

} ; 

struct D : B { 
int d; 

void operator delete( void *, size_ t ); 
virtual void fn(); 

~D () ; 

} ; 


void dfn( B *p ) 

{ 

delete p; // could be a pointer to D! 

} 

380 ’offsetof’ is not allowed for a function 

A member function does not have an offset like simple data members. If this is required, 
use a member pointer. 

Example: 

♦include <stddef.h> 

struct S 

{ 

int fun(); 

} ; 


381 


int s = offsetof( S, fun ) ; 

’offsetof’ is not allowed for an enumeration 

An enumeration does not have an offset like simple data members. 
Example: 

♦include <stddef.h> 

struct S 

{ 

enum SE { SI, S2, S3, S4 }; 

SE var; 


int s = offsetof( S, SE ); 
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382 could not initialize for code generation 

The source code has been parsed and fully analysed when this error is emitted. The 
compiler attempted to start generating object code but due to some problem (e.g., out of 
memory, no file handles) could not initialize itself. Try changing the compilation 
environment to eliminate this error. 

383 ’offsetof’ is not allowed for an undefined type 

The class type used in offsetof must be completely defined, otherwise data member offsets 
will not be known. 

Example: 

♦include <stddef.h> 

struct S { 
int a; 
int b; 

int c[ offsetof( S, b ) ]; 

} ; 

384 attempt to override virtual function ’%S’ with a different return type 

A function cannot be overloaded with identical argument types and a different return type. 
This is due to the fact that the C++ language does not consider the function’s return type 
when overloading. The exception to this rule in the C++ language involves restricted 
changes in the return type of virtual functions. The derived virtual function’s return type 
can be derived from the return type of the base virtual function. 

Example: 

struct B { 

virtual B *fn(); 

1 ; 

struct D : B { 

virtual D *fn(); 

} ; 

385 attempt to overload function ’%S’ with a different return type 

A function cannot be overloaded with identical argument types and a different return type. 
This is due to the fact that the C++ language does not consider the function’s return type 
when overloading. 

Example: 

int foo( char ); 
unsigned foo( char ); 
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386 attempt to use pointer to undefined class 

An attempt was made to indirect or increment a pointer to an undefined class. Since the 
class is undefined, the size is not known so the compiler cannot compile the expression 
properly. 

Example: 

class C; 
extern C* pci; 

C* pc2 = ++pcl; // C not defined 

int foo( C*p ) 

{ 

return p->x; // C not defined 

} 

387 expression is useful only for its side effects 

The indicated expression is not meaningful. The expression, however, does contain one or 
more side effects. 

Example: 

extern int* i; 
void func() 

{ 

*(i++); 

} 

In the example, the expression is a reference to an integer which is meaningless in itself. 
The incrementation of the pointer in the expression is a side effect. 

388 integral constant will be truncated during assignment or initialization 

This message indicates that the compiler knows that a constant value will not be preserved 
after the assignment. If this is acceptable, cast the constant value to the appropriate type in 
the assignment. 

Example: 

unsigned char c = 567; 

389 integral value may be truncated during assignment or initialization 

This message indicates that the compiler knows that all values will not be preserved after 
the assignment. If this is acceptable, cast the value to the appropriate type in the 
assignment. 

Example: 

extern unsigned s; 
unsigned char c = s; 
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390 cannot generate default constructor to initialize ’%T’ since constructors were declared 

A default constructor will not be generated by the compiler if there are already constructors 
declared. Try using default arguments to change one of the constructors to a default 
constructor or define a default constructor explicitly. 

Example: 

class C { 

C ( const C& ); 
public : 

int c; 

}; 

C cv; 

391 assignment found in boolean expression 

This is a construct that can lead to errors if it was intended to be an equality (using "==") 
test. 

Example: 

int too ( int a, int b ) 

{ 

if( a = b ) { 

return b; 

} 

return a; // always return 1 ? 

} 

392 definition: ’%F’ 

This informational message indicates where the symbol in question was defined. The 
message is displayed following an error or warning diagnostic for the symbol in question. 

Example: 

static int a = 9; 
int b = 89; 

The variable ’a’ is not referenced in the preceding example and so will cause a warning to 
be generated. Following the warning, the informational message indicates the line at which 
’a’ was declared. 

393 included from %s(%u) 

This informational message indicates the line number of the file including the file in which 
an error or warning was diagnosed. A number of such messages will allow you to trace 
back through the #include directives which are currently being processed. 
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394 reference object must be initialized 

A reference cannot be set except through initialization. Also references cannot be 0 so they 
must always be initialized. 

Example: 

int & ref; 

395 option requires an identifier 

The specified option is not recognized by the compiler since there was no identifier after it 
(i.e., "-nt=module"). 

396 ’main ’ cannot be overloaded 

There can only be one entry point for a C++ program. The "main" function cannot be 
overloaded. 

Example: 

int main (); 
int main( int ); 

397 ’new’ expression cannot allocate a void 

Since the void type has no size and there are no values of void type, one cannot allocate an 
instance of void. 

Example: 

void *p = new void; 

398 ’new’ expression cannot allocate a function 

A function type cannot be allocated since there is no meaningful size that can be used. The 
new expression can allocate a pointer to a function. 

Example: 

typedef int tdfun( int ); 
tdfun *tdv = new tdfun; 

399 ’new’ expression allocates a const or volatile object 

The pool of raw memory cannot be guaranteed to support const or volatile semantics. 
Usually const and volatile are used for statically allocated objects. 

Example: 

typedef const int con_int; 
con_ int* p = new con_ int; 
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400 cannot convert right expression for initialization 

The initialization is trying to convert an argument expression to a completely unrelated 
type. There is no way the compiler can provide any meaning for the intended conversion. 

Example: 

struct T { 

}; 


T x = 0; 

401 conversion ambiguity: [initialization expression] to [type of object] 

The initialization caused a constructor overload to occur. The operands provided for the 
constructor did not select a unique constructor. 

Example: 

struct S { 


} ; 

S (int) ; 

S(char); 

S x 

o 

\—1 

II 


402 class template ’%S’ has already been declared as a friend 

The class template in the message has already been declared as a friend. Remove the extra 
friend declaration. 

Example: 

template <class T> 
class S; 

class X { 

friend class S; 
int f; 

friend class S; 

} ; 


403 private base class accessed to convert initialization expression 

A conversion involving the inheritance hierarchy required access to a private base class. 
The access check did not succeed so the conversion is not allowed. 

404 protected base class accessed to convert initialization expression 

A conversion involving the inheritance hierarchy required access to a protected base class. 
The access check did not succeed so the conversion is not allowed. 
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405 cannot return a pointer or reference to a constant object 

A pointer or reference to a constant object cannot be returned. 

Example: 

int *foo( const int *p ) 

{ 

return p; 

} 

406 cannot pass a pointer or reference to a constant object 

A pointer or reference to a constant object could not be passed as an argument. 
Example: 

int *bar( int * ); 

int *foo( const int *p ) 

{ 

return bar( p ); 

} 

407 class templates must be named 

There is no syntax in the C++ language to reference an unnamed class template. 
Example: 

template <class T> 
class { 

} ; 

408 function templates can only name functions 

Variables cannot be overloaded in C++ so it is not possible to have many different 
instances of a variable with different types. 

Example: 

template <class T> 

T x [ 1 ] ; 

409 template argument ’%S’ is not used in the function argument list 

This restriction ensures that function templates can be bound to types during overload 
resolution. Functions currently can only be overloaded based on argument types. 

Example: 

template <class T> 

int foo( int * ); 
template <class T> 

T bar( int * ); 
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410 destructor cannot be declared const or volatile 

A destructor must be able to operate on all instances of classes regardless of whether they 
are const or volatile. 

411 static member function cannot be declared const or volatile 

A static member function does not have an implicit this argument so the const and volatile 
function qualifiers cannot be used. 

412 only member functions can be declared const or volatile 

A non-member function does not have an implicit this argument so the const and volatile 
function qualifiers cannot be used. 

413 ’const’ or ’volatile’ modifiers are not part of a function’s type 

The const and volatile qualifiers for a function cannot be used in typedefs or pointers to 
functions. The trailing qualifiers are used to change the type of the implicit this argument 
so that member functions that do not modify the object can be declared accurately. 

Example: 

// const is illegal 

typedef void (*baddcl)() const; 

struct S { 

void fun() const; 
int a; 

} ; 

// "this" has type "S const *" 
void S::fun() const 
{ 

this->a =1; // Error! 

} 

414 type cannot be defined in an argument 

A new type cannot be defined in an argument because the type will only be visible within 
the function. This amounts to defining a function that can never be called because C++ 
uses name equivalence for type checking. 

Example: 

extern foo( struct S { int s; } ); 

415 type cannot be defined in return type 

This is a restriction in the current C++ language. A function prototype should only use 
previously declared types in order to guarantee that it can be called from other functions. 
The restriction is required for templates because the compiler would have to wait until the 
end of a class definition before it could decide whether a class template or function 
template is being defined. 
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Example: 

template <class T> 
class C { 

T value; 

} fn( T x ) { 

C y; 

y.x = 0; 
return y; 

} ; 


A common problem that results in this error is to forget to terminate a class or enum 
definition with a semicolon. 

Example: 

struct S { 

int x,y; 

S( int, int ); 

} // missing semicolon 

S::S( int x, int y ) : x(x), y(y) { 

} 

416 data members cannot be initialized inside a class definition 

This message appears when an initialization is attempted inside of a class definition. In the 
case of static data members, initialization must be done outside the class definition. 
Ordinary data members can be initialized in a constructor. 

Example: 

struct S { 

static const int size = 1; 

1 ; 


417 only virtual functions may be declared pure 

The C++ language requires that all pure functions be declared virtual. A pure function 
establishes an interface that must consist of virtual functions because the functions are 
required to be defined in the derived class. 

Example: 

struct S { 

void too() = 0; 

} ; 


418 destructor is not declared in its proper class 

The destructor name is not declared in its own class or qualified by its own class. This is 
required in the C++ language. 
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419 cannot call non-const function for a constant object 

A function that does not promise to not modify an object cannot be called for a constant 
object. A function can declare its intention to not modify an object by using the const 
qualifier. 

Example: 

struct S { 

void fn(); 

} ; 

void cfn( const S *p ) 

{ 

p->fn(); // Error! 

} 

420 memory initializer list may only appear in a constructor definition 

A memory initializer list should be declared along with the body of the constructor 
function. 

421 cannot initialize member ’%N’ twice 

A member cannot be initialized twice in a member initialization list. 

422 cannot initialize base class ’%T’ twice 

A base class cannot be constructed twice in a member initialization list. 

423 ’%T’ is not a direct base class 

A base class initializer in a member initialization list must either be a direct base class or a 
virtual base class. 

424 ’%N’ cannot be initialized because it is not a member 

The name used in the member initialization list does not name a member in the class. 

425 ’%N’ cannot be initialized because it is a member function 

The name used in the member initialization list does not name a non-static data member in 
the class. 

426 ’%N’ cannot be initialized because it is a static member 

The name used in the member initialization list does not name a non-static data member in 
the class. 
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427 ’%N’ has not been declared as a member 

This message indicates that the member does not exist in the qualified class. This usually 
occurs in the context of access declarations. 

428 const/reference member ’%S’ must have an initializer 

The const or reference member does not have an initializer so the constructor is not 
completely defined. The member initialization list is the only way to initialize these types 
of members. 

429 abstract class ’%T’ cannot be used as an argument type 

An abstract class can only exist as a base class of another class. The C++ language does 
not allow an abstract class to be used as an argument type. 

430 abstract class ’%T’ cannot be used as a function return type 

An abstract class can only exist as a base class of another class. The C++ language does 
not allow an abstract class to be used as a return type. 

431 defining ’%S’ is not possible because ’%T’ is an abstract class 

An abstract class can only exist as a base class of another class. The C++ language does 
not allow an abstract class to be used as either a member or a variable. 

432 cannot convert to an abstract class ’%T’ 

An abstract class can only exist as a base class of another class. The C++ language does 
not allow an abstract class to be used as the destination type in a conversion. 

433 mangled name for ’%S’ has been truncated 

The name used in the object file that encodes the name and full type of the symbol is often 
called a mangled name. The warning indicates that the mangled name had to be truncated 
due to limitations in the object file format. 

434 cannot convert to a type of unknown size 

A completely unknown type cannot be used in a conversion because its size is not known. 
The behaviour of the conversion would be undefined also. 

435 cannot convert a type of unknown size 

A completely unknown type cannot be used in a conversion because its size is not known. 
The behaviour of the conversion would be undefined also. 
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436 cannot construct an abstract class 

An instance of an abstract class cannot be created because an abstract class can only be 
used as a base class. 

437 cannot construct an undefined class 

An instance of an undefined class cannot be created because the size is not known. 

438 string literal concatenated during array initialization 

This message indicates that a missing comma could have made a quiet change in the 
program. Otherwise, ignore this message. 

439 maximum size of segment ’%s’ has been exceeded for ’%S’ 

The indicated symbol has grown in size to a point where it has caused the segment it is 
defined inside of to be exhausted. 

440 maximum data item size has been exceeded for ’%S’ 

A non-huge data item is larger than 64k bytes in size. This message only occurs during 
16-bit compilation of C++ code. 

441 function attribute has been repeated 

A function attribute (like the_ export attribute) has been repeated. Remove the extra 

attribute to correct the declaration. 

442 modifier has been repeated 

A modifier (like the far modifier) has been repeated. Remove the extra modifier to correct 
the declaration. 

443 illegal combination of memory model modifiers 

Memory model modifiers must be used individually because they cannot be combined 
meaningfully. 

444 argument name ’%N’ has already been used 

The indicated argument name has already been used in the same argument list. This is not 
allowed in the C++ language. 

445 function definition for ’%S’ must be declared with an explicit argument list 

A function cannot be defined with a typedef. The argument list must be explicit. 
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446 user-defined conversion cannot convert to its own class or base class 

A user-defined conversion cannot be declared as a conversion either to its own class or to a 
base class of itself. 

Example: 

struct B { 

} ; 

struct D : private B { 
operator B(); 

} ; 

447 user-defined conversion cannot convert to void 

A user-defined conversion cannot be declared as a conversion to void. 

Example: 

struct S { 

operator void(); 

} ; 

448 expecting identifier 

An identifier was expected during processing. 

449 symbol ’%S’ does not have a segment associated with it 

A pointer cannot be based on a member because it has no segment associated with it. A 
member describes a layout of storage that can occur in any segment. 

450 symbol ’%S’ must have integral or pointer type 

If a symbol is based on another symbol, it must be integral or a pointer type. An integral 
type indicates the segment value that will be used. A pointer type means that all accesses 
will be added to the pointer value to construct a full pointer. 

451 symbol ’%S’ cannot be accessed in all contexts 

The symbol that the pointer is based on is in another class so it cannot be accessed in all 
contexts that the based pointer can be accessed. 

452 cannot convert class expression to be copied 

A convert class expression could not be copied. 

453 conversion ambiguity: multiple copy constructors 

More than one constructor could be used to copy a class object. 
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454 function template ’%S’ already has a definition 

The function template has already been defined with a function body. A function template 
cannot be defined twice even if the function body is identical. 

Example: 

template <class T> 
void f( T *p ) 

{ 

} 

template <class T> 
void f( T *p ) 

{ 

} 

455 function templates cannot have default arguments 

A function template must not have default arguments because there are certain types of 
default arguments that do not force the function argument to be a specific type. 

Example: 

template <class T> 

void f2( T *p = 0 ) 

{ 

} 

456 ’main ’ cannot be a function template 

This is a restriction in the C++ language because "main" cannot be overloaded. A function 
template provides the possibility of having more than one "main" function. 

457 ’%S’ was previously declared as a typedef 

The C++ language only allows function and variable names to coexist with names of 
classes or enumerations. This is due to the fact that the class and enumeration names can 
still be referenced in their elaborated form after the non-type name has been declared. 

Example: 

typedef int T; 

int T( int ) // error! 

{ 

} 

enum E { A, B, C }; 
void E() 

{ 

enum E x = A; // use "enum E" 

} 

class C { }; 
void C() 

{ 

class C x; // use "class C" 

} 
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458 


459 


460 


461 


462 


’%S’ was previously declared as a variable/function 

The C++ language only allows function and variable names to coexist with names of 
classes or enumerations. This is due to the fact that the class and enumeration names can 
still be referenced in their elaborated form after the non-type name has been declared. 

Example: 

int T( int ) 

{ 

} 

typedef int T; // error! 

void E() 

{ 

} 

enum E {A, B, C }; 

enum E x = A; // use "enum E" 

void C() 

{ 

} 

class C { }; 

class C x; // use "class C" 

private base class accessed to convert assignment expression 

A conversion involving the inheritance hierarchy required access to a private base class. 

The access check did not succeed so the conversion is not allowed. 

protected base class accessed to convert assignment expression 

A conversion involving the inheritance hierarchy required access to a protected base class. 
The access check did not succeed so the conversion is not allowed. 

maximum size of DGROUP has been exceeded for ’%S’ in segment ’%s’ 

The indicated symbol's size has caused the DGROUP contribution of this module to exceed 
64k. Changing memory models or declaring some data as far data are two ways of fixing 
this problem. 

type of return value is not the enumeration type of function 

The return value does not have the proper enumeration type. Keep in mind that integral 
values are not automatically converted to enum types like the C language. 
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463 linkage must be first in a declaration; probable cause: missing ’;’ 

This message usually indicates a missing semicolon The linkage specification must 
be the first part of a declaration if it is used. 

464 ’main ’ cannot be a static function 

This is a restriction in the C++ language because "main" must have external linkage. 

465 ’main ’ cannot be an inline function 

This is a restriction in the C++ language because "main" must have external linkage. 

466 ’mam ’ cannot be referenced 

This is a restriction in the C++ language to prevent implementations from having to work 
around multiple invocations of "main". This can occur if an implementation has to 
generate special code in "main" to construct all of the statically allocated classes. 

467 cannot call a non-volatile function for a volatile object 

A function that does not promise to not modify an object using volatile semantics cannot be 
called for a volatile object. A function can declare its intention to modify an object only 
through volatile semantics by using the volatile qualifier. 

Example: 

struct S { 

void fn(); 

} ; 

void cfn( volatile S *p ) 

{ 

p->fn(); // Error! 

} 

468 cannot convert pointer to constant or volatile objects to pointer to void 
You cannot convert a pointer to constant or volatile objects to ’void*’. 

Example: 

extern const int* pci; 
extern void *vp; 

int k = ( pci == vp ); 

469 cannot convert pointer to constant or non-volatile objects to pointer to volatile void 
You cannot convert a pointer to constant or non-volatile objects to ’volatile void*’. 
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Example: 

extern const int* pci; 
extern volatile void *vp; 

int k = ( pci == vp ); 

470 address of function is too large to be converted to pointer to void 

The address of a function can be converted to ’void*’ only when the size of a ’void*’ 
object is large enough to contain the function pointer. 

Example: 

void_far foo () ; 

void _ near *v = &foo; 

471 address of data object is too large to be converted to pointer to void 

The address of an object can be converted to ’void*’ only when the size of a ’void*’ object 
is large enough to contain the pointer. 

Example: 

int_far *ip; 

void _ near *v = ip; 

472 expression with side effect in sizeof discarded 

The indicated expression will be discarded; consequently, any side effects in that 
expression will not be executed. 

Example: 

int a = 14; 

int b = sizeof ( a++ ); 

In the example, the variable a will still have a value 14 after b has been initialized. 

473 function arguments) do not match those in prototype 

The C++ language requires great precision in specifying arguments for a function. For 
instance, a pointer to char is considered different than a pointer to unsigned char 
regardless of whether char is an unsigned quantity. This message occurs when a 
non-overloaded function is invoked and one or more of the arguments cannot be converted. 
It also occurs when the number of arguments differs from the number specified in the 
prototype. 

474 conversion ambiguity: [expression] to [class object] 

The conversion of the expression to a class object is ambiguous. 
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475 cannot assign right expression to class object 

The expression on the right cannot be assigned to the indicated class object. 

476 argument count is %d since there is an implicit ’this’ argument 

This informational message indicates the number of arguments for the function mentioned 
in the error message. The function is a member function with a this argument so it may 
have one more argument than expected. 

477 argument count is %d since there is no implicit ’this’ argument 

This informational message indicates the number of arguments for the function mentioned 
in the error message. The function is a member function without a this argument so it may 
have one less argument than expected. 

478 argument count is %dfor a non-member function 

This informational message indicates the number of arguments for the function mentioned 
in the error message. The function is not a member function but it could be declared as a 
friend function. 

479 conversion ambiguity: multiple copy constructors to copy array ’%S’ 

More than one constructor to copy the indicated array exists. 

480 variable/function has the same name as the class/enum ’%S’ 

In C++, a class or enum name can coexist with a variable or function of the same name in a 
scope. This warning is indicating that the current declaration is making use of this feature 
but the typedef name was declared in another file. This usually means that there are two 
unrelated uses of the same name. 

481 class/enum has the same name as the function/variable ’%S’ 

In C++, a class or enum name can coexist with a variable or function of the same name in a 
scope. This warning is indicating that the current declaration is making use of this feature 
but the function/variable name was declared in another file. This usually means that there 
are two unrelated uses of the same name. Furthermore, all references to the class or enum 
must be elaborated (i.e., use ’class C’ instead of ’C’) in order for subsequent references to 
compile properly. 

482 cannot create a default constructor 

A default constructor could not be created, because other constructors were declared for the 
class in question. 
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Example: 

struct X { 

X(X&) ; 

} ; 

struct Y { 

X a[10] ; 

} ; 

Y yvar; 

In the example, the variable "yvar" causes a default constructor for the class "Y" to be 
generated. The default constructor for "Y" attempts to call the default constructor for "X" 
in order to initialize the array "a" in class "Y". The default constructor for "X" cannot be 
defined because another constructor has been declared. 

483 attempting to access default constructor for %T 

This informational message indicates that a default constructor was referenced but could 
not be generated. 

484 cannot align symbol ’%S’ to segment boundary 

The indicated symbol requires more than one segment of storage and the symbol's 
components cannot be aligned to the segment boundary. 

485 friend declaration does not specify a class or function 

A class or function must be declared as a friend. 

Example: 

struct T { 

// should be class or function declaration 
friend int; 

} ; 

486 cannot take address of overloaded function 

This message indicates that an overloaded function’s name was used in a context where a 
final type could not be found. Because a final type was not specified, the compiler cannot 
select one function to use in the expression. Initialize a properly-typed temporary with the 
appropriate function and use the temporary in the expression. 

Example: 

int foo( char ); 
int foo( unsigned ); 
extern int (*p) ( char ); 

int k = ( p == &foo ); // fails 

The first foo can be passed as follows: 
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Example: 

int foo( char ); 
int foo( unsigned ); 
extern int (*p)( char ); 

// introduce temporary 

static int (*temp)( char ) = &foo; 

// ok 

int k = ( p == temp ); 

487 cannot use address of overloaded function as a variable argument 

This message indicates that an overloaded function’s name was used as a argument for a 
style function. Because a final function type is not present, the compiler cannot select 
one function to use in the expression. Initialize a properly-typed temporary with the 
appropriate function and use the temporary in the call. 

Example: 

int foo( char ); 

int foo( unsigned ); 

int ellip_ fun( int, ... ); 

int k = ellip_ fun ( 14, &foo ) ; // fails 

The first foo can be passed as follows: 

Example: 

int foo( char ); 

int foo( unsigned ); 

int ellip_ fun( int, ... ); 

static int (*temp)( char ) = &foo; // introduce 
temporary 

int k = ellip_ fun( 14, temp ); //ok 

488 ’%N’ cannot be overloaded 

The indicated function cannot be overloaded. Functions that fall into this category include 
operator delete. 

489 symbol ’%S’ has already been initialized 

The indicated symbol has already been initialized. It cannot be initialized twice even if the 
initialization value is identical. 

490 delete expression is a pointer to a function 

A pointer to a function cannot be allocated so it cannot be deleted. 
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491 delete of a pointer to const data 

Since deleting a pointer may involve modification of data, it is not always safe to delete a 
pointer to const data. 

Example: 

struct S { }; 

void fn( S const *p, S const *q ) { 

delete p; 
delete [] q; 

} 

492 delete expression is not a pointer to data 

A delete expression can only delete pointers. For example, trying to delete an hit is not 
allowed in the C++ language. 

Example: 

void fn( int a ) 

{ 

delete a; // Error! 

} 

493 template argument is not a constant expression 

The compiler has found an incorrect expression provided as the value for a constant value 
template argument. The only expressions allowed for scalar template arguments are 
integral constant expressions. 

494 template argument is not an external linkage symbol 

The compiler has found an incorrect expression provided as the value for a pointer value 
template argument. The only expressions allowed for pointer template arguments are 
addresses of symbols. Any symbols must have external linkage or must be static class 
members. 

495 conversion of const reference to volatile reference 

The constant value can be modified by assigning into the volatile reference. This would 
allow constant data to be modified quietly. 

Example: 

void fn( const int &rci ) 

{ 

int volatile &r = rci; // Error! 

} 
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496 conversion of volatile reference to const reference 

The volatile value can be read incorrectly by accessing the const reference. This would 
allow volatile data to be accessed without correct volatile semantics. 

Example: 

void fn( volatile int &rvi ) 

{ 

int const &r = rvi; // Error! 

} 

497 conversion of const or volatile reference to plain reference 

The constant value can be modified by assigning into the plain reference. This would allow 
constant data to be modified quietly. In the case of volatile data, any access to the plain 
reference will not respect the volatility of the data and thus would be incorrectly accessing 
the data. 

Example: 

void fn ( const int &rci, volatile int &rvi ) 

{ 

int &rl = rci; // Error! 
int &r2 = rvi; // Error! 

} 

498 syntax error before ’%s’; probable cause: incorrectly spelled type name 

The identifier in the error message has not been declared as a type name in any scope at this 
point in the code. This may be the cause of the syntax error. 

499 object (or object pointer) required to access non-static member function 

A reference to a member function in a class has occurred. The member is non-static so in 
order to access it, an object of the class is required. 

Example: 

struct S { 
int m(); 

static void fn() 

{ 

m () ; // Error! 

} 

}; 

500 object (or object pointer) cannot be used to access function 

The indicated object (or object pointer) cannot be used to access function. 
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501 object (or object pointer) cannot be used to access data 

The indicated object (or object pointer) cannot be used to access data. 

502 cannot access member function in enclosing class 

A member function in enclosing class cannot be accessed. 

503 cannot access data member in enclosing class 

A data member in enclosing class cannot be accessed. 

504 syntax error before type name ’%s’ 

The identifier in the error message has been declared as a type name at this point in the 
code. This may be the cause of the syntax error. 

505 implementation restriction: cannot generate thunk from ’%S’ 

This implementation restriction is due to the use of a shared code generator between Open 
Watcom compilers. The virtual this adjustment thunks are generated as functions linked 
into the virtual function table. The functions rely on knowing the correct number of 
arguments to pass on to the overriding virtual function but in the case of ellipsis (...) 
functions, the number of arguments cannot be known when the thunk function is being 
generated by the compiler. The target symbol is listed in a diagnostic message. The work 
around for this problem is to recode the source so that the virtual functions make use of the 
va_list type found in the stdarg header file. 

Example: 
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♦include <iostream.h> 

♦include <stdarg.h> 

struct B { 

virtual void fun( char *, ... ); 

} ; 

struct D : B { 

virtual void fun( char *, ... ) ; 

} ; 

void B::fun( char *f, ... ) 

{ 

va_ list args; 

va_ start( args, f ); 
while( *f ) { 

cout << va_ arg ( args, char ) << endl; 

+ + f ; 

} 

va_ end ( args ) ; 

} 

void D::fun( char *f, ... ) 

{ 

va_ list args; 

va_ start( args, f ); 
while( *f ) { 

cout << va_ arg ( args, int ) << endl; 

+ + f ; 

} 

va_ end ( args ) ; 

} 

The previous example can be changed to the following code with corresponding changes to 
the contents of the virtual functions. 

Example: 

♦include <iostream.h> 

♦include <stdarg.h> 

struct B { 

void fun( char *f, ... ) 

{ 

va_ list args; 

va_ start( args, f ) ; 

_ fun( f, args ); 
va_ end ( args ) ; 

} 

virtual void _ fun ( char *, va_ list ) ; 

} ; 
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~b 

struct D : B { 

// this can be removed since using B::fun 
// will result in the same behaviour 
// since _ fun is a virtual function 
void fun( char *f, ... ) 

{ 

va_ list args; 

va_ start( args, f ); 

_ fun( f, args ); 
va_ end ( args ) ; 

} 

virtual void _ fun( char *, va_ list ); 

} ; 

~b 

void B:fun( char *f, va_ list args ) 

{ 

while ( *f ) { 

cout << va_ arg( args, char ) << endl; 

++f ; 

} 

} 

~b 

void D:fun( char *f, va_ list args ) 

{ 

while ( *f ) { 

cout << va_ arg( args, int ) << endl; 

++f ; 

} 

} 


~b 

// no changes are required for users of the class 
B x; 

D y; 


void dump( B *p ) 

{ 

p->fun( "1234", 'a', 'b', 'c', ' d' ); 
p->fun( "12", 'a', 'b' ); 

} 


~b 

void main() 

{ 

dump( &x ); 
dump( &y ); 

} 
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506 conversion of _ based( void ) pointer to virtual base class 

An_based(void) pointer to a class object cannot be converted to a pointer to virtual base 

class, since this conversion applies only to specific objects. 

Example: 

struct Base In¬ 
struct Derived : virtual Base {}; 

Derived_based ( void ) *p_ derived; 

Base_based ( void ) *p_ base = p_ derived; // error 

The conversion would be allowed if the base class were not virtual. 

507 class for target operand is not derived from class for source operand 

A member pointer conversion can only be performed safely when converting a base class 
member pointer to a derived class member pointer. 

508 conversion ambiguity: [pointer to class member] to [assignment object] 

The base class in the original member pointer is not a unique base class of the derived class. 

509 conversion of pointer to class member involves a private base class 

The member pointer conversion required access to a private base class. The access check 
did not succeed so the conversion is not allowed. 

510 conversion of pointer to class member involves a protected base class 

The member pointer conversion required access to a protected base class. The access check 
did not succeed so the conversion is not allowed. 

511 item is neither a non-static member function nor data member 

A member pointer can only be created for non-static member functions and non-static data 
members. Static members can have their address taken just like their file scope 
counterparts. 

512 function address cannot be converted to pointer to class member 

The indicated function address cannot be converted to pointer to class member. 

513 conversion ambiguity: [address of function ] to [pointer to class member] 

The indicated conversion is ambiguous. 
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514 addressed function is in a private base class 
The addressed function is in a private base class. 

515 addressed function is in a protected base class 
The addressed function is in a protected base class. 

516 class for object is not defined 

The left hand operand for the or operator must be of a class type that is completely 
defined. 

Example: 

class C; 

int fun( C& x ) 

{ 

return x.y; // class C not defined 

} 

51 7 left expression is not a class object 

The left hand operand for the operator must be of a class type since member pointers 
can only be used with classes. 

518 right expression is not a pointer to class member 

The right hand operand for the operator must be a member pointer type. 

519 cannot convert pointer to class of member pointer 

The class of the left hand operand cannot be converted to the class of the member pointer 
because it is not a derived class. 

520 conversion ambiguity: [pointer] to [class of pointer to class member] 

The class of the pointer to member is an ambiguous base class of the left hand operand. 

521 conversion of pointer to class of member pointer involves a private base class 
The class of the pointer to member is a private base class of the left hand operand. 

522 conversion of pointer to class of member pointer involves a protected base class 
The class of the pointer to member is a protected base class of the left hand operand. 
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523 cannot convert object to class of member pointer 

The class of the left hand operand cannot be converted to the class of the member pointer 
because it is not a derived class. 

524 conversion ambiguity: [object] to [class object of pointer to class member] 

The class of the pointer to member is an ambiguous base class of the left hand operand. 

525 conversion of object to class of member pointer involves a private base class 
The class of the pointer to member is a private base class of the left hand operand. 

526 conversion of object to class of member pointer involves a protected base class 
The class of the pointer to member is a protected base class of the left hand operand. 

527 conversion of pointer to class member from a derived to a base class 

A member pointer can only be converted from a base class to a derived class. This is the 
opposite of the conversion rule for pointers. 

528 form is ’#pragma inline_recursion en ’ where ’en ’ is ’on ’ or ’off 

This pragma indicates whether inline expansion will occur for an inline function which is 
called (possibly indirectly) a subsequent time during an inline expansion. Either ’on’ or 
’off’ must be specified. 

529 expression for number of array elements must be integral 

The expression for the number of elements in a new expression must be integral because it 
is used to calculate the size of the allocation (which is an integral quantity). The compiler 
will not automatically convert to an integer because of rounding and truncation issues with 
floating-point values. 

530 function accessed with ’. *’ or ’->*’ can only be called 

The result of the and operators can only be called because it is often specific to 
the instance used for the left hand operand. 

531 left operand must be a pointer, pointer to class member, or arithmetic 
The left operand must be a pointer, pointer to class member, or arithmetic. 

532 right operand must be a pointer, pointer to class member, or arithmetic 
The right operand must be a pointer, pointer to class member, or arithmetic. 
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533 neither pointer to class member can be converted to the other 

The two member pointers being compared are from two unrelated classes. They cannot be 
compared since their members can never be related. 

534 left operand is not a valid pointer to class member 

The specified operator requires a pointer to member as the left operand. 

Example: 

struct S; 

void fn( int S::* mp, int *p ) 

{ 

if( p == mp ) 

P [ 0] = 1; 

} 

535 right operand is not a valid pointer to class member 

The specified operator requires a pointer to member as the right operand. 

Example: 

struct S; 

void fn( int S::* mp, int *p ) 

{ 

if( mp == p ) 

P [ 0] = 1; 

} 

536 cannot use *’ nor with pointer to class member with zero value 

The compiler has detected a NULL pointer use with a member pointer dereference. 

537 operand is not a valid pointer to class member 

The operand cannot be converted to a valid pointer to class member. 

Example: 

struct S; 
int S : : * fn() 

{ 

int a; 
return a; 

} 

538 destructor can be invoked only with ’ or ’-> ’ 

This is a restriction in the C++ language. An explicit invocation of a destructor is not 
recommended for objects that have their destructor called automatically. 
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539 class of destructor must be class of object being destructed 

Destructors can only be called for the exact static type of the object being destroyed. 

540 destructor is not properly qualified 

An explicit destructor invocation can only be qualified with its own class. 

541 pointers to class members reference different object types 

Conversion of member pointers can only occur if the object types are identical. This is 
necessary to ensure type safety. 

542 operand must be pointer to class or struct 

The left hand operand of a operator must be a pointer to a class. This is a restriction 
in the C++ language. 

543 expression must have void type 

If one operand of the ’: ’ operator has void type, then the other operand must also have void 
type. 

544 expression types do not match for ’ operator 

The compiler could not bring both operands to a common type. This is necessary because 
the result of the conditional operator must be a unique type. 

545 cannot create an undefined type with ’operator new ’ 

A new expression cannot allocate an undefined type because it must know how large an 
allocation is required and it must also know whether there are any constructors to execute. 

546 delete of a pointer to an undefined type 

A delete expression cannot safely deallocate an undefined type because it must know 
whether there are any destructors to execute. In spite of this, the ISO/ANSI C++ Working 
Paper requires that an implementation suppoit this usage. 

Example: 

struct U; 

void foo( U *p, U *q ) { 

delete p; 
delete [] q; 

} 
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547 cannot access ’%S’ through a private base class 

The indicated symbol cannot be accessed because it requires access to a private base class. 

548 cannot access ’%S’ through a protected base class 

The indicated symbol cannot be accessed because it requires access to a protected base 
class. 

549 ’sizeof operand contains compiler generated information 

The type used in the ’sizeof operand contains compiler generated information. Clearing a 
struct with a call to memset() would invalidate all of this information. 

550 cannot convert ’: ’ operands to a common reference type 

The two reference types cannot be converted to a common reference type. This can happen 
when the types are not related through base class inheritance. 

551 conversion ambiguity: [reference to object] to [type of opposite ’:’ operand] 

One of the reference types is an ambiguous base class of the other. This prevents the 
compiler from converting the operand to a unique common type. 

552 conversion of reference to ’ object involves a private base class 

The conversion of the reference operands requires a conversion through a private base 
class. 

553 conversion of reference to ’: ’ object involves a protected base class 

The conversion of the reference operands requires a conversion through a protected base 
class. 

554 expression must have type arithmetic, pointer, or pointer to class member 

This message means that the type cannot be converted to any of these types, also. All of 
the mentioned types can be compared against zero (’O’) to produce a true or false value. 

555 expression for ’while’ is always false 

The compiler has detected that the expression will always be false. If this is not the 
expected behaviour, the code may contain a comparison of an unsigned value against zero 
(e.g., unsigned integers are always greater than or equal to zero). Comparisons against zero 
for addresses can also result in trivially false expressions. 
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556 testing expression for for’ is always false 

The compiler has detected that the expression will always be false. If this is not the 
expected behaviour, the code may contain a comparison of an unsigned value against zero 
(e.g., unsigned integers are always greater than or equal to zero). Comparisons against zero 
for addresses can also result in trivially false expressions. 

557 message number ’%d’ is invalid 

The message number used in the #pragma does not match the message number for any 
warning message. This message can also indicate that a number or (meaning all 
warnings) was not found when it was expected. 

558 warning level must be an integer in range 0 to 9 

The new warning level that can be used for the warning can be in the range 0 to 9. The 
level 0 means that the warning will be treated as an error (compilation will not succeed). 
Levels 1 up to 9 are used to classify warnings. The -w option sets an upper limit on the 
level for warnings. By setting the level above the command line limit, you effectively 
ignore all cases where the warning shows up. 

559 function ’%S’ cannot be defined because it is generated by the compiler 

The indicated function cannot be defined because it is generated by the compiler. The 
compiler will automatically generate default constructors, copy constructors, assignment 
operators, and destructors according to the rules of the C++ language. This message 
indicates that you did not declare the function in the class definition. 

560 neither environment variable nor file found for ’ name 

The indirection operator for the command line will first check for an environment variable 
of the name and use the contents for the command line. If an environment variable is not 
found, a check for a file with the same name will occur. 

561 more than 5 indirections during command line processing 

The Open Watcom C++ compiler only allows a fixed number nested indirections using files 
or environment variables, to prevent runaway chains of indirections. 

562 cannot take address of non-static member function 

The only way to create a value that described the non-static member function is to use a 
member pointer. 

563 cannot generate default ’%S’ because class contains either a constant or a reference 
member 

An assignment operator cannot be generated because the class contains members that 
cannot be assigned into. 
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564 cannot convert pointer to non-constant or volatile objects to pointer to const void 
A pointer to non-constant or volatile objects cannot be converted to ’const void*’. 

565 cannot convert pointer to non-constant or non-volatile objects to pointer to const volatile 
void 

A pointer to non-constant or non-volatile objects cannot be converted to ’const volatile 
void*’. 

566 cannot initialize pointer to non-volatile with a pointer to volatile 

A pointer to a non-volatile type cannot be initialized with a pointer to a volatile type 
because this would allow volatile data to be modified without volatile semantics via the 
non-volatile pointer to it. 

567 cannot pass a pointer or reference to a volatile object 

A pointer or reference to a volatile object cannot be passed in this context. 

568 cannot return a pointer or reference to a volatile object 

A pointer or reference to a volatile object cannot be returned. 

569 left expression is not a pointer to a volatile object 

One cannot assign a pointer to a volatile type to a pointer to a non-volatile type. This 
would allow a volatile object to be modified via the non-volatile pointer. Use a cast if this 
is absolutely necessary. 

570 virtual function override for ’%S’ is ambiguous 

This message indicates that there are at least two overrides for the function in the base 
class. The compiler cannot arbitrarily choose one so it is up to the programmer to make 
sure there is an unambiguous choice. Two of the overriding functions are listed as 
informational messages. 

571 initialization priority must be number 0-255, ’library’, or ’program’ 

An incorrect module initialization priority has been provided. Check the User’s Guide for 
the correct format of the priority directive. 

572 previous case label defined %L 

This informational message indicates where a preceding case label is defined. 
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573 previous default label defined %L 

This informational message indicates where a preceding default label is defined. 

574 label defined %L 

This informational message indicates where a label is defined. 

575 label referenced %L 

This informational message indicates where a label is referenced. 

576 object thrown has type: %T 

This informational message indicates the type of the object being thrown. 

577 object thrown has an ambiguous base class %T 

It is illegal to throw an object with a base class to which a conversion would be ambiguous. 
Example: 

struct ambiguous! }; 

struct basel : public ambiguous { }; 
struct base2 : public ambiguous { }; 
struct derived : public basel, public base2 { }; 

too( derived &object ) 

! 

throw object; 

} 

The throw will cause an error to be displayed because an object of type "derived" cannot be 
converted to an object of type "ambiguous". 

578 form is ’#pragma inline_depth level’ where ’level’ is 0 to 255 

This pragma sets the number of times inline expansion will occur for an inline function 
which contains calls to inline functions. The level must be a number from zero to 255. 
When the level is zero, no inline expansion occurs. 

579 pointer or reference truncated by cast 

The cast expression causes a conversion of a pointer value to another pointer value of 

smaller size. This can be caused by_ near or far qualifiers (i.e., casting a far pointer to 

a near pointer). Function pointers can also have a different size than data pointers in 
certain memory models. Because this message indicates that some information is being 
lost, check the code carefully. 
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580 cannot find a constructor for given initializer argument list 

The initializer list provided for the new expression does not uniquely identify a single 
constructor. 

581 variable ’%N’ can only be based on a string in this context 

All of the based modifiers can only be applied to pointer types. The only based modifier 
that can be applied to non-pointer types is the ’_based!_segname("WATCOM"))’ style. 

582 memory model modifiers are not allowed for class members 

Class members describe the arrangement and interpretation of memory and, as such, 
assume the memory model of the address used to access the member. 

583 redefinition of the typedef name ’%S’ ignored 

The compiler has detected that a slightly different type has been assigned to a typedef 
name. The type is functionally equivalent but typedef redefinitions should be precisely 
identical. 

584 constructor for variable ’%S’ cannot be bypassed 

The variable may not be constructed when code is executing at the position the message 
indicated. The C++ language places these restrictions to prevent the use of unconstructed 
variables. 

585 syntax error; missing start of function body after constructor initializer 

Member initializers can only be used in a constructor’s definition. 

Example: 

struct S { 
int a; 

S( int x = 1 ) : a (x) 

{ 

} 

} ; 

586 conversion ambiguity: [expression] to [type of default argument] 

A conversion to an ambiguous base class was detected in the default argument expression. 

587 conversion of expression for default argument is impossible 

A conversion to a unrelated class was detected in the default argument expression. 
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588 syntax error before template name ’%s’ 

The identifier in the error message has been declared as a template name at this point in the 
code. This may be the cause of the syntax error. 

589 private base class accessed to convert default argument 

A conversion to a private base class was detected in the default argument expression. 

590 protected base class accessed to convert default argument 

A conversion to a protected base class was detected in the default argument expression. 

591 operand must be an lvalue (cast produces rvalue) 

The compiler is expecting a value which can be assigned into, 
be assigned into because a brand new value is always created, 
temporary is a meaningless operation. 

592 left operand must be an lvalue (cast produces rx’alue) 

The compiler is expecting a value which can be assigned into, 
be assigned into because a brand new value is always created, 
temporary is a meaningless operation. 

593 right operand must be an lvalue (cast produces rx’alue) 

The compiler is expecting a value which can be assigned into, 
be assigned into because a brand new value is always created, 
temporary is a meaningless operation. 

594 construct resolved as a declaration/type 

The C++ language contains language ambiguities that force compilers to rely on extra 
information in order to understand certain language constructs. The extra information 
required to disambiguate the language can be deduced by looking ahead in the source file. 
Once a single interpretation has been found, the compiler can continue analysing source 
code. See the ARM p.93 for more details. This warning is intended to inform the 
programmer that an ambiguous construct has been resolved in a certain direction. In this 
case, the construct has been determined to be part of a type. The final resolution varies 
between compilers so it is wise to change the source code so that the construct is not 
ambiguous. This is especially important in cases where the resolution is more than three 
tokens away from the start of the ambiguity. 

595 construct resolved as an expression 

The C++ language contains language ambiguities that force compilers to rely on extra 
information in order to understand certain language constructs. The extra information 
required to disambiguate the language can be deduced by looking ahead in the source file. 
Once a single interpretation has been found, the compiler can continue analysing source 
code. See the ARM p.93 for more details. This warning is intended to inform the 
programmer that an ambiguous construct has been resolved in a certain direction. In this 
case, the construct has been determined to be part of an expression (a function-like cast). 
The final resolution varies between compilers so it is wise to change the source code so that 


The result of a cast cannot 
Assigning a new value to a 


The result of a cast cannot 
Assigning a new value to a 


The result of a cast cannot 
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the construct is not ambiguous. This is especially important in cases where the resolution is 
more than three tokens away from the start of the ambiguity. 

596 construct cannot be resolved 

The C++ language contains language ambiguities that force compilers to rely on extra 
information in order to understand certain language constructs. The extra information 
required to disambiguate the language can be deduced by looking ahead in the source file. 
Once a single interpretation has been found, the compiler can continue analysing source 
code. See the ARM p.93 for more details. This warning is intended to inform the 
programmer that an ambiguous construct could not be resolved by the compiler. Please 
report this to the Open Watcom developement team so that the problem can be analysed. 
See http://www.openwatcom.org/. 

597 encountered another ambiguous construct during disambiguation 

The C++ language contains language ambiguities that force compilers to rely on extra 
information in order to understand certain language constructs. The extra information 
required to disambiguate the language can be deduced by looking ahead in the source file. 
Once a single interpretation has been found, the compiler can continue analysing source 
code. See the ARM p.93 for more details. This warning is intended to inform the 
programmer that another ambiguous construct was found inside an ambiguous construct. 
The compiler will correctly disambiguate the construct. The programmer is advised to 
change code that exhibits this warning because this is definitely uncharted territory in the 
C++ language. 

598 ellipsis (...) argument contains compiler generated information 

A class with virtual functions or virtual bases is being passed to a function that will not 
know the type of the argument. Since this information can be encoded in a variety of ways, 
the code may not be portable to another environment. 

Example: 

struct S 

{ virtual int foo(); 

} ; 

static S sv; 

extern int bar( S, ... ); 

static int test = bar( sv, 14, 64 ); 

The call to "bar" causes a warning, since the structure S contains information associated 
with the virtual function for that class. 

599 cannot convert argument for ellipsis (...) argument 

This argument cannot be used as an ellipsis (...) argument to a function. 
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600 conversion ambiguity: [argument] to [ellipsis (...) argument] 

A conversion ambiguity was detected while converting an argument to an ellipsis (...) 
argument. 

601 converted function type has different #pragma from original function type 

Since a #pragma can affect calling conventions, one must be very careful performing casts 
involving different calling conventions. 

602 class value used as return value or argument in converted function type 

The compiler has detected a cast between "C" and "C++" linkage function types. The 
calling conventions are different because of the different language rules for copying 
structures. 

603 class value used as return value or argument in original function type 

The compiler has detected a cast between "C" and "C++" linkage function types. The 
calling conventions are different because of the different language rules for copying 
structures. 

604 must look ahead to determine whether construct is a declaration/type or an expression 

The C++ language contains language ambiguities that force compilers to rely on extra 
information in order to understand certain language constructs. The extra information 
required to disambiguate the language can be deduced by looking ahead in the source file. 
Once a single interpretation has been found, the compiler can continue analysing source 
code. See the ARM p.93 for more details. This warning is intended to inform the 
programmer that an ambiguous construct has been used. The final resolution varies 
between compilers so it is wise to change the source code so that the construct is not 
ambiguous. 

605 assembler: ’%s’ 

An error has been detected by the #pragma inline assembler. 

606 default argument expression cannot reference ’this’ 

The order of evaluation for function arguments is unspecified in the C++ language 
document. Thus, a default argument must be able to be evaluated before the ’this’ 
argument (or any other argument) is evaluated. 

607 tfpragma aux must reference a "C" linkage function ’%S’ 

The method of assigning pragma information via the #pragma syntax is provided for 
compatibility with Open Watcom C. Because C only allows one function per name, this 
was adequate for the C language. Since C++ allows functions to be overloaded, a new 
method of referencing pragmas has been introduced. 
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Example: 

♦pragma aux this_ in_ SI parm caller [si] [ax]; 
struct S { 

void_pragma("this_ in_ SI") foo( int ); 

void_pragma ( "this_ in_ SI " ) foo ( char ); 

} ; 

608 assignment is ambiguous for operands used 

An ambiguity was detected while attempting to convert the right operand to the type of the 
left operand. 

Example: 

struct SI { 
int a; 

} ; 

struct S2 : SI { 
int b; 

} ; 

struct S3 : S2, SI { 
int c; 

} ; 

SI* fn( S3 *p ) 

{ 

return p; 

} 

In the example, class SI occurs ambiguously for an object or pointer to an object of type 
S3 . A pointer to an S3 object cannot be converted to a pointer to an SI object. 

609 pragma name ’%s’ is not defined 

Pragmas are defined with the #pragma aux syntax. See the User’s Guide for the details of 
defining a pragma name. If the pragma has been defined then check the spelling between 
the definition and the reference of the pragma name. 

610 ’%S’ could not be generated by the compiler 

An error occurred while the compiler tried to generate the specified function. The error 
prevented the compiler from generating the function properly so the compilation cannot 
continue. 

611 ’catch’ does not immediately follow a ’try’ or ’catch’ 

The catch handler syntax must be used in conjunction with a try block. 
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Example: 

void f() 

{ 

try { 

// code that may throw an exception 
} catch( int x ) { 

// handle 'int' exceptions 
} catch( ... ) { 

// handle all other exceptions 

} 

} 

612 preceding catch specified ’ 

Since an ellipsis "..." catch handler will handle any type of exception, no further catch 
handlers can exist afterwards because they will never execute. Reorder the catch handlers 
so that the "..." catch handler is the last handler. 

613 argument to extern "C" function contains compiler generated information 

A class with virtual functions or virtual bases is being passed to a function that will not 
know the type of the argument. Since this information can be encoded in a variety of ways, 
the code may not be portable to another environment. 

Example: 

struct S 

{ virtual int foo(); 

} ; 

static S sv; 

extern "C" int bar( S ); 
static int test = bar( sv ) ; 

The call to "bar" causes a warning, since the structure S contains information associated 
with the virtual function for that class. 

614 previous try block defined %L 

This informational message indicates where a preceding try block is defined. 

615 previous catch block defined %L 

This informational message indicates where a preceding catch block is defined. 

616 catch handler can never be invoked 

Because the handlers for a try block are tried in order of appearance, the type specified in a 
preceding catch can ensure that the current handler will never be invoked. This occurs 
when a base class (or reference) precedes a derived class (or reference); when a pointer to a 
base class (or reference to the pointer) precedes a pointer to a derived class (or reference to 
the pointer); or, when "void*" or "void*&" precedes a pointer or a reference to the pointer. 
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Example: 

struct BASE {}; 

struct DERIVED : public BASE {}; 

too () 

{ 


try { 

// code 

for try 





} catch( 
// code 

BASE b ) 

{ 

// 

[1] 


} catch( 
// code 

DERIVED ; 

) { 

// 

warning: 

[i 

} catch( 
// code 

BASE* pb 

) { 

// 

[2] 


} catch( 
// code 

DERIVED* 

pd ) 

{// 

warning: 

[2 

} catch( 
// code 

void* pv 

) { 

// 

[3] 


} catch( 
// code 

int* pi ' 

) { 

// 

warning: 

[3 

} catch( 
// code 

BASES br 

) { 

// 

warning: 

[1 

} catch( 
// code 

float*& pfr ) 

{// 

warning: 

[3 


} 

} 

Each erroneous catch specification indicates the preceding catch block which caused the 
error. 

617 cannot overload extern "C" functions (the other function is ’%S’) 

The C++ language only allows you to overload functions that are strictly C++ functions. 
The compiler will automatically generate the correct code to distinguish each particular 
function based on its argument types. The extern "C" linkage mechanism only allows you 
to define one "C" function of a particular name because the C language does not support 
function overloading. 

618 function will be overload ambiguous with ’%S’ using default arguments 

The declaration declares a function that is indistinguishable from another function of the 
same name with default arguments. 

Example: 

void fn( int, int = 1 ); 
void fn( int ); 

Calling the function ’fn’ with one argument is ambiguous because it could match either the 
first ’fn’ with a default argument applied or the second ’fn’ without any default arguments. 
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619 linkage specification is different than previous declaration ’%S’ 

The linkage specification affects the binding of names throughout a program. It is 
important to maintain consistency because subtle problems could arise when the incorrect 
function is called. Usually this error prevents an unresolved symbol error during linking 
because the name of a declaration is affected by its linkage specification. 

Example: 

extern "C" void fn( void ); 
void fn( void ) 

{ 

} 

620 not enough segment registers available to generate ’%s’ 

Through a combination of options, the number of available segment registers is too small. 
This can occur when too many segment registers are pegged. This can be fixed by 
changing the command line options to only peg the segment registers that must absolutely 
be pegged. 

621 pure virtual destructors must have a definition 

This is an anomaly for pure virtual functions. A destructor is the only special function that 
is inherited and allowed to be virtual. A derived class must be able to call the base class 
destructor so a pure virtual destructor must be defined in a C++ program. 

622 jump into try block 

Jumps cannot enter try blocks. 

Example: 

foo( int a ) 

{ 

if(a) goto tr_ lab; 

try { 
t r_ 1ab: 

throw 1234; 

} catch( int ) { 

if(a) goto tr_ lab; 

} 

if(a) goto tr_ lab; 

} 

All the preceding goto’s are illegal. The error is detected at the label for forward jumps and 
at the goto’s for backward jumps. 
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623 jump into catch handler 

Jumps cannot enter catch handlers. 

Example: 

foo( int a ) 

{ 

if(a)goto ca_ lab; 
try { 

if(a)goto ca_ lab; 

} catch( int ) { 

ca_ lab: 

} 

if(a)goto ca_ lab; 

} 

All the preceding goto’s are illegal. The error is detected at the label for forward jumps and 
at the goto’s for backward jumps. 

624 catch block does not immediately follow try block 

At least one catch handler must immediately follow the "}" of a try block. 

Example: 

extern void goop(); 
void foo() 

{ 

try { 
goop (); 

} // a catch block should follow! 

} 

In the example, there were no catch blocks after the try block. 

625 exceptions must be enabled to use feature (use ’xs’ option) 

Exceptions are enabled by specifying the ’xs’ option when the compiler is invoked. The 
error message indicates that a feature such as try, catch, throw, or function exception 
specification has been used without enabling exceptions. 

626 I/O error reading ’%s’: %s" 

When attempting to read data from a source or header file, the indicated system error 
occurred. Likely there is a hardware problem, or the file system has become corrupt. 

627 text following pre-processor directive 

A #else or #endif directive was found which had tokens following it rather than an end of 
line. Some UNIX style preprocessors allowed this, but it is not legal under standard C or 
C++. Make the tokens into a comment. 
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628 expression is not meaningful 

This message indicates that the indicated expression is not meaningful. An expression is 
meaningful when a function is invoked, when an assignment or initialization is performed, 
or when the expression is casted to void. 

Example: 

void foo( int i, int j ) 

{ 

i + j; // not meaningful 

} 

629 expression has no side effect 

The indicated expression does not cause a side effect. A side effect is caused by invoking a 
function, by an assignment or an initialization, or by reading a volatile variable. 

Example: 

int k; 

void foo( int i, int j ) 

{ 

i + j, // no side effect (note comma) 

k = 3; 

} 

630 source conversion type is ’%T’ 

This informational message indicates the type of the source operand, for the preceding 
conversion diagnostic. 

631 target conversion type is ’%T’ 

This informational message indicates the target type of the conversion, for the preceding 
conversion diagnostic. 

632 redeclaration of ’%S’ has different attributes 

A function cannot be made virtual or pure virtual in a subsequent declaration. All 
properties of a function should be described in the first declaration of a function. This is 
especially important for member functions because the properties of a class are affected by 
its member functions. 

Example: 

struct S { 

void fun (); 

} ; 

virtual void S::fun() 

{ 

} 
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633 template class instantiation for ’%T’ was %L 

This informational message indicates that the error or warning was detected during the 
instantiation of a class template. The final type of the template class is shown as well as the 
location in the source where the instantiation was initiated. 

634 template function instantiation for ’%S’ was %L 

This informational message indicates that the error or warning was detected during the 
instantiation of a function template. The final type of the template function is shown as 
well as the location in the source where the instantiation was initiated. 

635 template class member instantiation was %L 

This informational message indicates that the error or warning was detected during the 
instantiation of a member of a class template. The location in the source where the 
instantiation was initiated is shown. 

636 function template binding for ’%S’ was %L 

This informational message indicates that the error or warning was detected during the 
binding process of a function template. The binding process occurs at the point where 
arguments are analysed in order to infer what types should be used in a function template 
instantiation. The function template in question is shown along with the location in the 
source code that initiated the binding process. 

637 function template binding of ’%S’ was %L 

This informational message indicates that the error or warning was detected during the 
binding process of a function template. The binding process occurs at the point where a 
function prototype is analysed in order to see if the prototype matches any function 
template of the same name. The function template in question is shown along with the 
location in the source code that initiated the binding process. 

638 ’%s’ defined %L 

This informational message indicates where the class in question was defined. The 
message is displayed following an error or warning diagnostic for the class in question. 

Example: 

class S; 

int foo( S*p ) 

{ 

return p->x; 

} 

The variable p is a pointer to an undefined class and so will cause an error to be generated. 
Following the error, the informational message indicates the line at which the class S was 
declared. 
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639 form is ’#pragma template_depth level’ where ’level’ is a non-zero number 

This pragma sets the number of times templates will be instantiated for nested 
instantiations. The depth check prevents infinite compile times for incorrect programs. 

640 possible non-terminating template instantiation (use "#pragma template_depth %d" to 
increase depth) 

This message indicates that a large number of expansions were required to complete a 
template class or template function instantiation. This may indicate that there is an 
erroneous use of a template. If the program will complete given more depth, try using the 
suggested #pragma in the error message to increase the depth. The number provided is 
double the previous value. 

641 cannot inherit a partially defined base class ’%T’ 

This message indicates that the base class was in the midst of being defined when it was 
inherited. The storage requirements for a class type must be known when inheritance is 
involved because the layout of the final class depends on knowing the complete contents of 
all base classes. 

Example: 

struct Partial { 

struct Nested : Partial { 
int n; 

}; 

1 ; 

642 ambiguous function: %F defined %L 

This informational message shows the functions that were detected to be ambiguous. 
Example: 

int amb( char ); // will be ambiguous 

int amb( unsigned char ); // will be ambiguous 

int amb( char, char ); 
int k = amb( 14 ); 

The constant value 14 has an int type and so the attempt to invoke the function amb is 
ambiguous. The first two functions are ambiguous (and will be displayed); the third is not 
considered (nor displayed) since it is declared to have a different number of arguments. 

643 cannot convert argument %d defined %L 

This informational message indicates the first argument which could not be converted to 
the corresponding type for the declared function. It is displayed when there is exactly one 
function declared with the indicated name. 
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644 


645 


646 


647 


’this ’ cannot be converted 

This informational message indicates the this pointer for the function which could not be 
converted to the type of the this pointer for the declared function. It is displayed when 
there is exactly one function declared with the indicated name. 

rejected function: %F defined %L 

This informational message shows the overloaded functions which were rejected from 
consideration during function-overload resolution. These functions are displayed when 
there is more than one function with the indicated name. 

’%T’ operator can be used 

Following a diagnosis of operator ambiguity, this information message indicates that the 
operator can be applied with operands of the type indicated in the message. 

Example: 

struct S { 

S( int ) ; 
operator int(); 

S operator+( int ); 

} ; 

S s(15) ; 

int k = s + 123; // "+" is ambiguous 

In the example, the "+" operation is ambiguous because it can implemented as by the 
addition of two integers (with S : : operator int applied to the second operand) or by a 
call to S : : operator! . This informational message indicates that the first is possible. 

cannot #undef ’%s ’ 

The predefined macros _ cplusplus, _DATE_,_FILE_,_LINE 

_STDC_,_TIME_,_FUNCTION_famb_cannot be undefined using 

the #undef directive. 

Example: 

#undef 
#undef 
#undef 
#undef 
#undef 
#undef 
#undef 
#undef 

All of the preceding directives are not permitted. 


cplusplus 

DATE_ 

FILE_ 

LINE_ 

STDC_ 

TIME_ 

FUNCTION_ 
func_ 
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648 cannot#define ’%s’ 

The predefined macros _cplusplus,_DATE_,_FILE_,_LINE. 

_STDC _, a_nd_ TIME _cannot be defined using the #define directive. 

Example: 


♦define 

_ cplusplus 

1 

♦define 

_DATE_ 

2 

♦define 

_FILE_ 

3 

♦define 

_ LINE_ 

4 

♦define 

_ STDC_ 

5 

♦define 

_ TIME_ 

6 


All of the preceding directives are not permitted. 

649 template function ’%F’ defined %L 

This informational message indicates where the function template in question was defined. 
The message is displayed following an error or warning diagnostic for the function 
template in question. 

Example: 

template <class T> 

void foo( T, T * ) 

{ 

} 

void bar() 

{ 

foo(l); // could not instantiate 

} 

The function template for foo cannot be instantiated for a single argument causing an error 
to be generated. Following the error, the informational message indicates the line at which 
foo was declared. 

650 ambiguous function template: %F defined %L 

This informational message shows the function templates that were detected to be 
ambiguous for the arguments at the call point. 

651 cannot instantiate %S 

This message indicates that the function template could not be instantiated for the 
arguments supplied. It is displayed when there is exactly one function template declared 
with the indicated name. 
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652 rejected function template: %F defined %L 

This informational message shows the overloaded function template which was rejected 
from consideration during function-overload resolution. These functions are displayed 
when there is more than one function or function template with the indicated name. 

653 operand cannot be a function 

The indicated operation cannot be applied to a function. 

Example: 

int Fun (); 

int j = ++Fun; // illegal 

In the example, the attempt to increment a function is illegal. 

654 left operand cannot be a function 

The indicated operation cannot be applied to the left operand which is a function. 
Example: 

extern int Fun (); 
void too() 

{ 

Fun = 0; // illegal 

} 

In the example, the attempt to assign zero to a function is illegal. 

655 right operand cannot be a function 

The indicated operation cannot be applied to the right operand which is a function. 
Example: 

extern int Fun (); 
void too() 

{ 

void* p = 3[Fun]; // illegal 

} 

In the example, the attempt to subscript a function is illegal. 

656 define this function inside its class definition (may improve code quality) 

The Open Watcom C++ compiler has found a constructor or destructor with an empty 
function body. An empty function body can usually provide optimization opportunities so 
the compiler is indicating that by defining the function inside its class definition, the 
compiler may be able to perform some important optimizations. 
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Example: 

struct S { 
~S() ; 

} ; 


S::~S() { 

} 

657 define this function inside its class definition (could have improved code quality) 

The Open Watcom C++ compiler has found a constructor or destructor with an empty 
function body. An empty function body can usually provide optimization opportunities so 
the compiler is indicating that by defining the function inside its class definition, the 
compiler may be able to perform some important optimizations. This particular warning 
indicates that the compiler has already found an opportunity in previous code but it found 
out too late that the constructor or destructor had an empty function body. 

Example: 

struct 
~S 

} ; 

struct 
~T 

} ; 

S::~S() { 

} 

658 cannot convert address of overloaded function ’%S’ 

This information message indicates that an address of an overloaded function cannot be 
converted to the indicated type. 

Example: 

int ovload( char ); 
int ovload( float ); 
int routine! int (*)( int ); 
int k = routine ( ovload ); 

The first argument for the function routine cannot be converted, resulting in the 
informational message. 

659 expression cannot have void type 
The indicated expression cannot have a void type. 

Example: 

main( int argc, char* argv ) 

{ 

if( (void)argc ) { 

return 5; 

} else { 
return 9; 

} 

} 


S { 

0 ; 

T : S { 
0 { } 
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Conditional expressions, such as the one illustrated in the if statement cannot have a void 
type. 

660 cannot reference a bit field 

The smallest addressable unit is a byte. You cannot reference a bit field. 

Example: 

struct S 
{ int bits :6; 

int bitfield :10; 

1 ; 

S var; 

int& ref = var.bitfield; // illegal 

661 cannot assign to object having an undefined class 

An assignment cannot be be made to an object whose class has not been defined. 
Example: 

class X; // declared, but not defined 

extern X& foo(); // returns reference (ok) 
extern X obj; 
void goop() 

{ 

obj = foo(); // error 

} 

662 cannot create member pointer to constructor 

A member pointer value cannot reference a constructor. 

Example: 

class C { 

CO; 

1 ; 

int foo () 

{ 

return 0 == &C::C; 

} 

663 cannot create member pointer to destructor 

A member pointer value cannot reference a destructor. 

Example: 

class C { 

~C () ; 

1 ; 

int foo () 

{ 

return 0 == &C::~C; 

} 
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664 attempt to initialize a non-constant reference with a temporary object 

A temporary value cannot be converted to a non-constant reference type. 
Example: 


struct 

C { 


C( 

C& ) 


C( 

int 

} ; 



c 

& cl 

= 1; 

c 

c2 = 

2; 


The initializations of cl and c2 are erroneous, since temporaries are being bound to 
non-const references. In the case of cl, an implicit constructor call is required to convert 
the integer to the correct object type. This results in a temporary object being created to 
initialize the reference. Subsequent code can modify this temporary’s state. The 
initialization of c2, is erroneous for a similar reason. In this case, the temporary is being 
bound to the non-const reference argument of the copy constructor. 

665 temporary object used to initialize a non-constant reference 

Ordinarily, a temporary value cannot be bound to a non-constant reference. There is 
enough legacy code present that the Open Watcom C++ compiler issues a warning in cases 
that should be errors. This may change in the future so it is advisable to correct the code as 
soon as possible. 

666 assuming unary ’operator & ’ not overloaded for type ’%T’ 

An explicit address operator can be applied to a reference to an undefined class. The Open 
Watcom C++ compiler will assume that the address is required but it does not know 
whether this was the programmer’s intention because the class definition has not been seen. 

Example: 

struct S; 

S * fn( S &y ) { 

// assuming no operator defined 

return &y; 

} 

667 ’va_start’ macro will not work without an argument before ’... ’ 

The warning indicates that it is impossible to access the arguments passed to the function 
without declaring an argument before the "..." argument. The "..." style of argument list 
(without any other arguments) is only useful as a prototype or if the function is designed to 
ignore all of its arguments. 
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Example: 

void fn( ... ) 

{ 

} 

668 ’va_start’ macro will not work with a reference argument before ’... ’ 

The warning indicates that taking the address of the argument before the "..." argument, 
which ’va_start’ does in order to access the variable list of arguments, will not give the 
expected result. The arguments will have to be rearranged so that an acceptable argument 
is declared before the "..." argument or a dummy int argument can be inserted after the 
reference argument with the corresponding adjustments made to the callers of the function. 

Example: 

♦include <stdarg.h> 

void fn( int &r, ... ) 

{ 

va_ list args; 

// address of ' r' is address of 

// object ' r' references so 

// ' va_ start' will not work properly 

va_ start( args, r ); 

va_ end( args ); 

} 

669 ’va_start’ macro will not work with a class argument before ’... ’ 

This warning is specific to C++ compilers that quietly convert class arguments to class 
reference arguments. The warning indicates that taking the address of the argument before 
the "..." argument, which ’va_start’ does in order to access the variable list of arguments, 
will not give the expected result. The arguments will have to be rearranged so that an 
acceptable argument is declared before the "..." argument or a dummy int argument can be 
inserted after the class argument with the corresponding adjustments made to the callers of 
the function. 

Example: 

♦include <stdarg.h> 

struct S { 

SO; 

1 ; 


void fn( S c, ... ) 

{ 

va_ list args; 

// Open Watcom C++ passes a pointer to 

// the temporary created for passing 

// 'c' rather than pushing 'c' on the 

// stack so ' va_ start' will not work 

// properly 

va_ start( args, c ); 

va_ end ( args ) ; 

} 
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670 function modifier conflicts with previous declaration ’%S’ 

The symbol declaration conflicts with a previous declaration with regard to function 
modifiers. Either the previous declaration did not have a function modifier or it had a 
different one. 

Example: 

♦pragma aux never_ returns aborts; 
void fn( int, int ); 

void_pragma ( "never_ returns " ) fn ( int, int ); 

671 function modifier cannot be used on a variable 

The symbol declaration has a function modifier being applied to a variable or non-function. 
The cause of this may be a declaration with a missing function argument list. 

Example: 

int (*_pascal ok) (); 

int (*_pascal not_ ok) ; 

672 ’%T’ contains the following pure virtual functions 

This informational message indicates that the class contains pure virtual function 
declarations. The class is definitely abstract as a result and cannot be used to declare 
variables. The pure virtual functions declared in the class are displayed immediately 
following this message. 

Example: 

struct A { 

void virtual fn( int ) = 0; 

} ; 

A x; 

673 ’%T’ has no implementation for the following pure virtual functions 

This informational message indicates that the class is derived from an abstract class but the 
class did not override enough virtual function declarations. The pure virtual functions 
declared in the class are displayed immediately following this message. 

Example: 

struct A { 

void virtual fn( int ) = 0; 

} ; 

struct D : A { 

} ; 

D x; 
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674 pure virtual function ’%F’ defined %L 

This informational message indicates that the pure virtual function has not been overridden. 
This means that the class is abstract. 

Example: 

struct A { 

void virtual fn( int ) = 0; 

} ; 

struct D : A { 

} ; 

D x; 

675 restriction: standard calling convention required for ’%S’ 

The indicated function may be called by the C++ run-time system using the standard 
calling convention. The calling convention specified for the function is incompatible with 

the standard convention. This message may result when_pascal is specified for a 

default constructor, a copy constructor, or a destructor. It may also result when parm 
reverse is specified in a #pragma for the function. 

676 number of arguments in function call is incorrect 

The number of arguments in the function call does not match the number declared for the 
function type. 

Example: 

extern int (*pfn)( int, int ); 
int k = pfn( 1, 2, 3 ); 

In the example, the function pointer was declared to have two arguments. Three arguments 
were used in the call. 

677 function has type ’%T’ 

This informational message indicates the type of the function being called. 

678 invalid octal constant 

The constant started with a ’0’ digit which makes it look like an octal constant but the 
constant contained the digits ’8’ and ’9’. The problem could be an incorrect octal constant 
or a missing for a floating constant. 

Example: 

int i = 0123456789; // invalid octal constant 
double d = 0123456789; // missing '.'7 
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679 class template definition started %L 

This informational message indicates where the class template definition started so that any 
problems with missing braces can be fixed quickly and easily. 

Example: 

template <class T> 
struct S { 
void f1() { 

// error missing '}' 

} ; 


template <class T> 
struct X { 
void f2() { 

} 

} ; 


680 constructor initializer started %L 

This informational message indicates where the constructor initializer started so that any 
problems with missing parenthesis can be fixed quickly and easily. 

Example: 

struct S { 

S( int x ) : a(x), b(x // missing parenthesis 

{ 

} 


681 zero size array must be the last data member 

The language extension that allows a zero size array to be declared in a class definition 
requires that the array be the last data member in the class. 

Example: 

struct S { 

char a[]; 
int b; 

} ; 


682 cannot inherit a class that contains a zero size array 

The language extension that allows a zero size array to be declared in a class definition 
disallows the use of the class as a base class. This prevents the programmer from 
corrupting storage in derived classes through the use of the zero size array. 

Example: 

struct B { 
int b; 
char a[]; 

In¬ 
struct D : B { 
int d; 

} ; 
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683 zero size array ’%S’ cannot be used in a class with base classes 

The language extension that allows a zero size array to be declared in a class definition 
requires that the class not have any base classes. This is required because the C++ compiler 
must be free to organize base classes in any manner for optimization purposes. 

Example: 

struct B { 
int b; 

} ; 

struct D : B { 
int d; 
char a[]; 

} ; 


684 cannot catch abstract class object 

C++ does not allow abstract classes to be instantiated and so an abstract class object cannot 
be specified in a catch clause. It is permissible to catch a reference to an abstract class. 

Example: 

class Abstract { 
public: 

virtual int foo() = 0; 

} ; 


class Derived : Abstract { 
public: 

int foo(); 

} ; 


int xyz; 

void func( void ) { 

try { 

throw Derived!); 

} catch( Abstract abstract ) { // object 

xyz = 1; 

} 


The catch clause in the preceding example would be diagnosed as improper, since an 
abstract class is specified. The example could be coded as follows. 

Example: 
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class Abstract { 
public: 

virtual int foo() = 0; 

}; 

class Derived : Abstract { 
public: 

int foo(); 

} ; 


int xyz; 

void func( void ) { 

try { 

throw Derived(); 

} catch( Abstract & abstract ) { // reference 

xyz = 1; 

} 

} 

non-static member function ’%S’ cannot be specified 

The indicated non-static member function cannot be used in this context. For example, 
such a function cannot be used as the second or third operand of the conditional operator. 

Example: 

struct S { 

int foo (); 
int bar (); 
int fun (); 

} ; 

int S::fun( int i ) { 

return (i ? foo : bar)(); 

} 

Neither foo nor bar can be specified as shown in the example. The example can be 
properly coded as follows: 

Example: 

struct S { 

int foo (); 
int bar (); 
int fun (); 

} ; 


int S::fun( int i ) { 

return i ? foo() : bar(); 

} 
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687 


688 


689 


690 


attempt to convert pointer or reference from a base to a derived class 

A pointer or reference to a base class cannot be converted to a pointer or reference, 
respectively, of a derived class, unless there is an explicit cast. The return statements in 
the following example will be diagnosed. 


Example: 

struct Base In¬ 
struct Derived : Base {}; 


Base b; 

Derived* ReturnPtr() { return &b; } 

Derived& ReturnRefO { return b; } 


The following program would be acceptable: 

Example: 

struct Base in¬ 
struct Derived : Base {}; 

Base b; 

Derived* ReturnPtr() { return (Derived*)&b; } 

DerivedS ReturnRefO { return (Derived&)b; } 


expression for ’while’ is always true 


The compiler has detected that the expression will always be true. Consequently, the loop 
will execute infinitely unless there is a break statement within the loop or a throw 
statement is executed while executing within the loop. If such an infinite loop is required, 
it can be coded as for ( ;) without causing warnings. 

testing expression for for’ is always true 

The compiler has detected that the expression will always be true. Consequently, the loop 
will execute infinitely unless there is a break statement within the loop or a throw 
statement is executed while executing within the loop. If such an infinite loop is required, 
it can be coded as for ( ;) without causing warnings. 

conditional expression is always true (non-zero) 

The indicated expression is a non-zero constant and so will always be true. 
conditional expression is always false (zero) 

The indicated expression is a zero constant and so will always be false. 
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691 expecting a member of ’%T’ to be defined in this context 

A class template member definition must define a member of the associated class template. 
The complexity of the C++ declaration syntax can make this error hard to identify visually. 

Example: 

template <class T> 
struct S { 
typedef int X; 
static X fn( int ); 
static X qq; 

} ; 

template <class T> 

S<T>::X fn( int ) {// should be 'S<T>::fn' 

return fn( 2 ); 

} 

template <class T> 

S<T>::X qq = 1; // should be 'S<T>::q' 

S<int> x; 

692 cannot throw an abstract class 

An abstract class cannot be thrown since copies of that object may have to be made (which 
is impossible); 

Example: 

struct abstract_ class { 

abstract_ class( int ); 
virtual int foo() = 0; 

}; 

void goop() 

{ 

throw abstract_ class( 17 ) ; 

} 

The throw expression is illegal since it specifies an abstract class. 

693 cannot create pre-compiled header file ’%s’ 

The compiler has detected a problem while trying to open the pre-compiled header file for 
write access. 

694 error occurred while writing pre-compiled header file 

The compiler has detected a problem while trying to write some data to the pre-compiled 
header file. 


482 Diagnostic Messages 




Open Watcom C++ Diagnostic Messages 


695 error occurred while reading pre-compiled header file 

The compiler has detected a problem while trying to read some data from the pre-compiled 
header file. 

696 pre-compiled header file being recreated 

The existing pre-compiled header file may either be corrupted or is a version that the 
compiler cannot use due to updates to the compiler. A new version of the pre-compiled 
header file will be created. 

697 pre-compiled header file being recreated (different compile options) 

The compiler has detected that the command line options have changed enough so the 
contents of the pre-compiled header file cannot be used. A new version of the 
pre-compiled header file will be created. 

698 pre-compiled header file being recreated (different ^include file) 

The compiler has detected that the first #include file name is different so the contents of the 
pre-compiled header file cannot be used. A new version of the pre-compiled header file 
will be created. 

699 pre-compiled header file being recreated (different current directory) 

The compiler has detected that the working directory is different so the contents of the 
pre-compiled header file cannot be used. A new version of the pre-compiled header file 
will be created. 

700 pre-compiled header file being recreated (different INCLUDE path) 

The compiler has detected that the INCLUDE path is different so the contents of the 
pre-compiled header file cannot be used. A new version of the pre-compiled header file 
will be created. 

701 pre-compiled header file being recreated (’%s ’ has been modified) 

The compiler has detected that an include file has changed so the contents of the 
pre-compiled header file cannot be used. A new version of the pre-compiled header file 
will be created. 

702 pre-compiled header file being recreated (macro ’%s’ is different) 

The compiler has detected that a macro definition is different so the contents of the 
pre-compiled header file cannot be used. The macro was referenced during processing of 
the header file that created the pre-compiled header file so the contents of the pre-compiled 
header may be affected. A new version of the pre-compiled header file will be created. 
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703 pre-compiled header file being recreated (macro ’%s’ is not defined) 

The compiler has detected that a macro has not been defined so the contents of the 
pre-compiled header file cannot be used. The macro was referenced during processing of 
the header file that created the pre-compiled header file so the contents of the pre-compiled 
header may be affected. A new version of the pre-compiled header file will be created. 

704 command line specifies smart windows callbacks and DS not equal to SS 

An illegal combination of switches has been detected. The windows smart callbacks option 
cannot be combined with either of the build DLL or DS not equal to SS options. 

705 class ’%N’ cannot be used with #pragma dump_object_model 

The indicated name has not yet been declared or has been declared but not yet been defined 
as a class. Consequently, the object model cannot be dumped. 

706 repeated modifier is ’%s ’ 

This informational message indicates what modifier was repeated in the declaration. 
Example: 

typedef int _far FARINT; 

FARINT _ far *p; // repeated _ far modifier 

707 semicolon may be missing after class/enum definition 

This informational message indicates that a missing semicolon may be the cause of the 
error. 

Example: 

struct S { 
int x,y; 

S( int, int ) ; 

} // missing semicolon 

S::S( int x, int y ) : x(x), y(y) { 

} 

708 cannot return a type of unknown size 

A value of an unknown type cannot be returned. 

Example: 

class S; 

S foo (); 

int goo () 

{ 

foo (); 

} 

In the example, foo cannot be invoked because the class which it returns has not been 
defined. 
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709 cannot initialize array member ’%S’ 

An array class member cannot be specified as a constructor initializer. 

Example: 

class S { 
public: 

int arr[3]; 

SO; 

1 ; 

S: : S () : arr ( 1, 2, 3 ) {} 

In the example, arr cannot be specified as a constructor initializer. Instead, the array may 
be initialized within the body of the constructor. 

Example: 

class S { 
public: 

int arr[3]; 

SO; 

1 ; 

S::S() 

{ 

arr[0] = 1; 
arr [1] = 2; 
arr[2] = 3; 

} 

710 file ’%s’ will #include itself forever 

The compiler has detected that the file in the message has been Mnclude from within itself 
without protecting against infinite inclusion. This can happen if Mfndef and #define header 
file protection has not been used properly. 

Example: 

♦ include_FILE_ 

711 ’mutable ’ may only be used for non-static class members 

A declaration in file scope or block scope cannot have a storage class of mutable. 

Example: 

mutable int a; 

712 ’mutable ’ member cannot also be const 

A mutable member can be modified even if its class object is const. Due to the semantics 
of mutable, the programmer must decide whether a member will be const or mutable 
because it cannot be both at the same time. 
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Example: 

struct S { 

mutable const int * p; // OK 

mutable int * const q; // error 

} ; 

713 left operand cannot be of type bool 

The left hand side of an assignment operator cannot be of type bool except for simple 
assignment. This is a restriction required in the C++ language. 

Example: 

bool q; 

void fn() 

{ 

q += i; 

} 

714 operand cannot be of type bool 

The operand of both postfix and prefix " operators cannot be of type bool. This is a 
restriction required in the C++ language. 

Example: 

bool q; 

void fn() 

{ 

—q; // error 

q—; // error 

} 

715 member ’%N’ has not been declared in ’%T’ 

The compiler has found a member which has not been previously declared. The symbol 
may be spelled differently than the declaration, or the declaration may simply not be 
present. 

Example: 

struct X { int m; }; 

void fn( X *p ) 

{ 

p->x = 1; 

} 

716 integral value may be truncated 

This message indicates that the compiler knows that all values will not be preserved after 
the assignment or initialization. If this is acceptable, cast the value to the appropriate type 
in the assignment or initialization. 
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Example: 

char inc( char c ) 

{ 

return c + 1; 

} 

717 left operand type is ’%T’ 

This informational message indicates the type of the left hand side of the expression. 

718 right operand type is ’%T’ 

This informational message indicates the type of the right hand side of the expression. 

719 operand type is ’%T’ 

This informational message indicates the type of the operand. 

720 expression type is ’%T’ 

This informational message indicates the type of the expression. 

721 virtual function ’%S’ cannot have its return type changed 

This restriction is due to the relatively new feature in the C++ language that allows return 
values to be changed when a virtual function has been overridden. It is not possible to 
support both features because in order to support changing the return value of a function, 
the compiler must construct a "wrapper" function that will call the virtual function first and 
then change the return value and return. It is not possible to do this with "..." style 
functions because the number of parameters is not known. 

Example: 

struct B { 

} ; 

struct D : virtual B { 

} ; 

struct X { 


virtual B 

*fn ( 

int, .. 

■ ) ; 

} ; 




struct Y : X { 




virtual D 

*fn ( 

int, .. 

■ ); 


} ; 


722 _ declspec( ’%N’) is not supported 

The identifier used in the declspec declaration modifier is not supported by Open 
Watcom C++. 
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723 attempt to construct afar object when the data model is near 

Constructors cannot be applied to objects which are stored in far memory when the default 
memory model for data is near. 

Example: 

struct Obj 
{ char *p; 

Obj () ; 

1 ; 

Obj far obj; 

The last line causes this error to be displayed when the memory model is small (switch 
-ms), since the memory model for data is near. 

724 -zo is an obsolete switch (has no effect) 

The -zo option was required in an earlier version of the compiler but is no longer used. 

725 "Vos" 

This is a user message generated with the #pragma message preprocessing directive. 
Example: 

♦pragma message( "my very own warning" ); 

726 no reference to formal parameter ’%S’ 

There are no references to the declared formal parameter. The simplest way to remove this 
warning in C++ is to remove the name from the argument declaration. 

Example: 

int fnl( int a, int b, int c ) 

{ 

// 'b' not referenced 
return a + c; 

} 

int fn2( int a, int /* b */, int c ) 

{ 

return a + c; 

} 

727 cannot dereference a pointer to void 

A pointer to void is used as a generic pointer but it cannot be dereferenced. 
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Example: 

void fn( void *p ) 

{ 

return *p; 

} 

728 class modifiers for ’%T’ conflict with class modifiers for ’%T’ 

A conflict between class modifiers for classes related through inheritance has been 
detected. A conflict will occur if two base classes have class modifiers that are different. 
The conflict can be resolved by ensuring that all classes related through inheritance have 
the same class modifiers. The default resolution is to have no class modifier for the derived 
base. 

Example: 

struct_cdecl B1 { 

void fn( int ); 

} ; 

struct_stdcall B2 { 

void fn( int ); 

} ; 

struct D : Bl, B2 { 

} ; 

729 invalid hexadecimal constant 

The constant started with a ’Ox’ prefix which makes it look like a hexadecimal constant but 
the constant was not followed by any hexadecimal digits. 

Example: 

unsigned i = Ox; // invalid hex constant 

730 return type of ’operator -> ’ will not allow ’-> ’ to be applied 

This restriction is a result of the transformation that the compiler performs when the 
operator -> is overloaded. The transformation involves transforming the expression to 
invoke the operator with applied to the result of operator ->. This warning indicates 
that the operator -> can never be used as an overloaded operator. The only way the 
operator can be used is to explicitly call it by name. 

Example: 

struct S { 
int a; 

void *operator ->(); 

} ; 

void *fn( S &q ) 

{ 

return q.operator ->() ; 

} 
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731 class should have a name since it needs a constructor or a destructor 

The class definition does not have a class name but it includes members that have 
constructors or destructors. Since the class has C++ semantics, it should be have a name in 
case the constructor or destructor needs to be referenced. 

Example: 

struct P { 
int x,y; 

p 0 ; 

1 ; 

typedef struct { 

P c; 
int v; 

} T; 

732 class should have a name since it inherits a class 

The class definition does not have a class name but it inherits a class. Since the class has 
C++ semantics, it should be have a name in case the constructor or destructor needs to be 
referenced. 

Example: 

struct P { 
int x,y; 

P 0 ; 

1 ; 

typedef struct : P { 
int v; 

} T; 

733 cannot open pre-compiled header file ’%s’ 

The compiler has detected a problem while trying to open the pre-compiled header file for 
read/write access. 

734 invalid second argument to va_start 

The second argument to the va_start macro should be the name of the argument just before 
the "..." in the argument list. 

735 ’//’ style comment continues on next line 

The compiler has detected a line continuation during the processing of a C++ style 
comment ("//"). The warning can be removed by switching to a C style comment ("/**/"). 
If you require the comment to be terminated at the end of the line, make sure that the 
backslash character is not the last character in the line. 
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Example: 

♦define XX 23 // comment start \ 

comment \ 

end 

int x = XX; // comment start ... \ 
comment end 

736 cannot open file ’%s’ for write access 

The compiler has detected a problem while trying to open the indicated file for write 
access. 

737 implicit conversion of pointers to integral types of same size 

According to the ISO/ANSI Draft Working Paper, a string literal is an array of char. 
Consequently, it is illegal to initialize or assign the pointer resulting from that literal to a 
pointer of either unsigned char or signed char, since these pointers point at objects of a 
different type. 

738 option requires a number 

The specified option is not recognized by the compiler since there was no number after it 
(i.e., "-w=l"). Numbers must be non-negative decimal numbers. 

739 option -fc specified more than once 

The -fc option can be specified at most once on a command line. 

740 option -fc specified in batch file of commands 

The -fc option cannot be specified on a line in the batch file of command lines specified by 
the -fc option on the command line used to invoke the compiler. 

741 file specified by -fc is empty or cannot be read 

The file specified using the -fc option is either empty or an input/output error was 
diagnosed for the file. 

742 cannot open file specified by -fc option 

The compiler was unable to open the indicated file. Most likely, the file does not exist. An 
input/output error is also possible. 

743 input/output error reading the file specified by -fc option 

The compiler was unable to open the indicated file. Most likely, the file does not exist. An 
input/output error is also possible. 
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744 ’%N’ does not have a return type specified (int assumed) 

In C++, operator functions should have an explicit return type specified. In future revisions 
of the ISO/ANSI C++ standard, the use of default int type specifiers may be prohibited so 
removing any dependencies on default int early will prevent problems in the future. 

Example: 

struct S { 

operator = ( S const & ); 
operator += ( S const & ); 

} ; 

745 cannot initialize reference to non-constant with a constant object 

A reference to a non-constant object cannot be initialized with a reference to a constant 
type because this would allow constant data to be modified via the non-constant pointer to 
it. 

Example: 

extern const int *pic; 

extern int & ref = pic; 

746 processing %s 

This informational message indicates where an error or warning was detected while 
processing the switches specified on the command line, in environment variables, in 
command files (using the ’ @ ’ notation), or in the batch command file (specified using the 
-fc option). 

747 class ’%7” has not been defined 

This informational message indicates a class which was not defined. This is noted 
following an error or warning message because it often helps to a user to determine the 
cause of that diagnostic. 

748 cannot catch undefined class object 

C++ does not allow abstract classes to be copied and so an undefined class object cannot be 
specified in a catch clause. It is permissible to catch a reference to an undefined class. 

749 class ’%T’ cannot be used since its definition has errors 

The analysis of the expression could not continue due to previous errors diagnosed in the 
class definition. 

750 function prototype in block scope missing ’extern ’ 

This warning can be triggered when the intent is to define a variable with a constructor. 

Due to the complexities of parsing C++, statements that appear to be variable definitions 
may actually parse as a function prototype. A work-around for this problem is contained in 
the example. If a prototype is desired, add the extern storage class to remove this warning. 
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751 


752 


753 


Example: 

struct C { 

} ; 

struct S { 

S ( C ) ; 

} ; 

void too() 

{ 

S a ( C() ) 

S b( (C() ) 


// function prototype! 
;// variable definition 


int bar( int );// warning 

extern int sam( int ); // no warning 


function prototype is ’%T’ 

This informational message indicates what the type of the function prototype is for the 
message in question. 

class ’%T’ contains a zero size array 

This warning is triggered when a class with a zero sized array is used in an array or as a 
class member. This is a questionable practice since a zero sized array at the end of a class 
often indicates a class that is dynamically sized when it is constructed. 

Example: 

struct C { 

C *next; 
char name[]; 

1 ; 

struct X { 

C q; 

} ; 

C a[10] ; 
invalid ’new’ modifier 

The Open Watcom C++ compiler does not support new expression modifiers but allows 
them to match the ambient memory model for compatibility. Invalid memory model 
modifiers are also rejected by the compiler. 

Example: 

int *fn( unsigned x ) 

{ 

return new _ interrupt int[x]; 

} 
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754 ’ _ declspec(thread)’ data ’%S’ must be link-time initialized 

This error message indicates that the data item in question either requires a constructor, 
destructor, or run-time initialization. This cannot be supported for thread-specific data at 
this time. 

Example: 

♦include <stdlib.h> 

struct C { 

CO; 

} ; 

struct D { 

~D () ; 

} ; 


C _declspec(thread) c; 

D _ declspec(thread) d; 

int _declspec(thread) e = rand(); 

755 code may not work properly if this module is split across a code segment 

The "zm" option allows the compiler to generate functions into separate segments that have 
different names so that more than 64k of code can be generated in one object file. 
Unfortunately, if an explicit near function is coded in a large code model, the possibility 
exists that the linker can place the near function in a separate code segment than a function 
that calls it. This would cause a linker error followed by an execution error if the 
executable is executed. The "zmf" option can be used if you require explicit near functions 
in your code. 

Example: 

// These functions may not end up in the 
// same code segment if the -zm option 
// is used. If this is the case, the near 
// call will not work since near functions 
// must be in the same code segment to 
// execute properly, 
static int near near_ fn( int x ) 

{ 

return x + 1; 

} 

int far_ fn( int y ) 

{ 

return near_ fn( y * 2 ); 

} 

756 #pragma extref: symbol ’%N’ not declared 

This error message indicates that the symbol referenced by #pragma extref has not been 
declared in the context where the pragma was encountered. 
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757 ttpragma extref: overloaded function ’%S’ cannot be used 

An external reference can be emitted only for external functions which are not overloaded. 

758 #pragma extref: ’%N’ is not a function or data 

This error message indicates that the symbol referenced by #pragma extref cannot have an 
external reference emitted for it because the referenced symbol is neither a function nor a 
data item. An external reference can be emitted only for external functions which are not 
overloaded and for external data items. 

759 ttpragma extref: ’%S’ is not external 

This error message indicates that the symbol referenced by ttpragma extref cannot have an 
external reference emitted for it because the symbol is not external. An external reference 
can be emitted only for external functions which are not overloaded and for external data 
items. 

760 pre-compiled header file being recreated (debugging info may change) 

The compiler has detected that the module being compiled was used to create debugging 
information for use by other modules. In order to maintain correctness, the pre-compiled 
header file must be recreated along with the object file. 

761 octal escape sequence out of range; truncated 

This message indicates that the octal escape sequence produces an integer that cannot fit 
into the required character type. 

Example: 

char *p = "\406"; 

762 binary operator ’%s’ missing right operand 

There is no expression to the right of the indicated binary operator. 

763 binary operator ’%s’ missing left operand 

There is no expression to the left of the indicated binary operator. 

764 expression contains extra operand(s) 

The expression contains operand(s) without an operator 

765 expression contains consecutive operand(s) 

More than one operand found in a row. 
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766 unmatched right parenthesis ’)’ 

The expression contains a right parenthesis ")" without a matching left parenthesis. 

767 unmatched left parenthesis ’(’ 

The expression contains a left parenthesis "(" without a matching right parenthesis. 

768 no expression between parentheses ’( ) ’ 

There is a matching set of parenthesis "()" which do not contain an expression. 

769 expecting ’: ’ operator in conditional expression 

A conditional expression exists without the operator. 

770 expecting ’?’ operator in conditional expression 

A conditional expression exists without the ’?’ operator. 

771 expecting first operand in conditional expression 

A conditional expression exists without the first operand. 

772 expecting second operand in conditional expression 

A conditional expression exists without the second operand. 

773 expecting third operand in conditional expression 

A conditional expression exists without the third operand. 

774 expecting operand after unary operator ’%s’ 

A unary operator without being followed by an operand. 

775 ’%s’ unexpected in constant expression 
’%s’ not allowed in constant expression 

776 assembler: ’%s’ 

A warning has been issued by the #pragma inline assembler. 

777 expecting ’id’ after but found ’%s’ 

The operator has an invalid token following it. 
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Example: 

♦define fn( x ) ((x)+l) 

struct S { 

int inc( int y ) { 

return ::fn( y ); 

} 

} ; 


778 only constructors can be declared explicit 

Currently, only constructors can be declared with the explicit keyword. 

Example: 

int explicit fn( int x ) { 

return x + 1; 

} 

779 const_cast type must be pointer, member pointer, or reference 

The type specified in a const_cast operator must be a pointer, a pointer to a member of a 
class, or a reference. 

Example: 

extern int const *p; 

long lp = const_ cast<long>( p ); 

780 const_cast expression must be pointer to same kind of object 

Ignoring const and volatile qualification, the expression must be a pointer to the same type 
of object as that specified in the const_cast operator. 

Example: 

extern int const * ip; 

long* lp = const_ cast<long*>( ip ); 

781 const_cast expression must be lvalue of the same kind of object 

Ignoring const and volatile qualification, the expression must be an lvalue or reference to 
the same type of object as that specified in the const_cast operator. 

Example: 

extern int const i; 

long& lr = const_ cast<long&>( i ); 

782 expression must be pointer to member from same class in const_cast 

The expression must be a pointer to member from the same class as that specified in the 
const_cast operator. 
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Example: 

struct B { 
int ib; 

} ; 

struct D : public B { 

} ; 

extern int const B::* imb; 

int D::* imd const_ cast<int D::*>( imb ); 

783 expression must be member pointer to same type as specified in const_cast 

Ignoring const and volatile qualification, the expression must be a pointer to member of the 
same type as that specified in the const_cast operator. 

Example: 

struct B { 
int ib; 
long lb; 

} ; 

int D::* imd const_ cast<int D::*>( &B::lb ); 

784 reinterpret_cast expression must be pointer or integral object 

When a pointer type is specified in the reinterpret_cast operator, the expression must be a 
pointer or an integer. 

Example: 

extern float fval; 

long* ip = const_ cast<long*>( fval ); 

The expression has float type and so is illegal. 

785 reinterpret_cast expression cannot be casted to reference type 

When a reference type is specified in the reinterpret_cast operator, the expression must be 
an lvalue (or have reference type). Additionally, constness cannot be casted away. 

Example: 

extern long f; 
extern const long f2; 

longs lrl = const_ cast<long&>( f + 2 ); 
long& lr2 = const_ cast<long&>( f2 ); 

Both initializations are illegal. The first cast expression is not an lvalue. The second cast 
expression attempts to cast away constness. 

786 reinterpret_cast expression cannot be casted to pointer to member 

When a pointer to member type is specified in the reinterpret_cast operator, the expression 
must be a pointer to member. Additionally, constness cannot be casted away. 
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Example: 

extern long in¬ 
struct S { 

const long f2; 

SO; 

} ; 

long S::* mpl = const_ cast<long S:: *> ( f ); 
long S::* mp2 = const_ cast<long S:: *>( &S::f2 ); 

Both initializations are illegal. The first cast expression does not involve a member pointer. 
The second cast expression attempts to cast away constness. 

787 only integral arithmetic types can be used with reinterpret_cast 

Pointers can only be casted to sufficiently large integral types. 

Example: 

void* p; 

float f = reinterpret_ cast<float>( p ); 

The cast is illegal because float type is specified. 

788 only integral arithmetic types can be used with reinterpret_cast 

Only integral arithmetic types can be casted to pointer types. 

Example: 

float fit; 

void* p = reinterpret_ cast<void*>( fit ); 

The cast is illegal because fit has float type which is not integral. 

789 cannot cast away constness 

A cast or implicit conversion is illegal because a conversion to the target type would 
remove constness from a pointer, reference, or pointer to member. 

Example: 

struct S { 
int s; 

} ; 

extern S const * ps; 
extern int const S::* mps; 

S* psl = ps; 

S& rsl = *ps; 

int S::* mpl = mps; 

The three initializations are illegal since they are attempts to remove constness. 
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790 size of integral type in cast less than size of pointer 

An object of the indicated integral type is too small to contain the value of the indicated 
pointer. 

Example: 

int x; 

char p = reinterpret_ cast<char>( &x ); 
char q = (char)( &x ); 

Both casts are illegal since a char is smaller than a pointer. 

791 type cannot be used in reinterpret_cast 

The type specified with reinterpret_cast must be an integral type, a pointer type, a pointer to 
a member of a class, or a reference type. 

Example: 

void* p; 

float f = reinterpret_ cast<float>( p ); 
void* q = ( reinterpret_ cast<void>( p ), p ); 

The casts specify illegal types. 

792 only pointers can be casted to integral types with reinterpret_cast 

The expression must be a pointer type. 

Example: 

void* p; 

float f = reinterpret_ cast<float>( p ); 
void* q = ( reinterpret_ cast<void>( p ), p ); 

The casts specify illegal types. 

793 only integers and pointers can be casted to pointer types with reinterpret_cast 

The expression must be a pointer or integral type. 

Example: 

void* x; 

void* p = reinterpret_ cast<void*>( 16 ); 
void* q = ( reinterpret_ cast<void*>( x ), p ); 

The casts specify illegal types. 

794 static_cast cannot convert the expression 

The indicated expression cannot be converted to the type specified with the static_cast 
operator. Perhaps reinterpret_cast or dynamic_cast should be used instead; 
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795 static_cast cannot be used with the type specified 

A static cast cannot be used with a function type or array type. 

Example: 

typedef int fun( int ); 
extern int poo( long ); 

int i = ( static_ cast<fun)( poo ) )( 22 ); 

Perhaps reinterpret_cast or dynamic_cast should be used instead; 

796 static_cast cannot be used with the reference type specified 

The expression could not be converted to the specified type using static_cast. 

Example: 

long lng; 

int& ref = static_ cast<int&>( lng ); 

Perhaps reinterpret_cast or dynamic_cast should be used instead; 

797 static_cast cannot be used with the pointer type specified 

The expression could not be converted to the specified type using static_cast. 

Example: 

long lng; 

int* ref = static_ cast<int*>( lng ); 

Perhaps reinterpret_cast or dynamic_cast should be used instead; 

798 static_cast cannot be used with the member pointer type specified 

The expression could not be converted to the specified type using static_cast. 

Example: 

struct S { 

long lng; 

} ; 

int S::* mp = static_ cast<int S::*>( &S::lng ); 

Perhaps reinterpret_cast or dynamic_cast should be used instead; 

799 static_cast type is ambiguous 

More than one constructor and/or used-defined conversion function can be used to convert 
the expression to the indicated type. 
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800 cannot cast from ambiguous base class 

When more than one base class of a given type exists, with respect to a derived class, it is 
impossible to cast from the base class to the derived class. 

Example: 

struct Base { int bl; }; 

struct DerA public Base { int da; }; 

struct DerB public Base { int db; }; 

struct Derived public DerA, public DerB { int d; } 

Derived* foo( Base* p ) 

{ 

return static_ cast<Derived*>( p ); 

} 

The cast fails since Base is an ambiguous base class for Derived. 

801 cannot cast to ambiguous base class 

When more than one base class of a given type exists, with respect to a derived class, it is 
impossible to cast from the derived class to the base class. 

Example: 

struct Base { int bl; }; 

struct DerA public Base { int da; }; 

struct DerB public Base { int db; }; 

struct Derived public DerA, public DerB { int d; } 

Base* too( Derived* p ) 

{ 

return (Base*)p; 

} 

The cast fails since Base is an ambiguous base class for Derived. 

802 can only static_cast integers to enumeration type 

When an enumeration type is specified with static_cast, the expression must be an integer. 
Example: 

enum sex { male, female }; 

sex father = static_ cast<sex>( 1.0 ); 

The cast is illegal because the expression is not an integer. 

803 dynamic_cast cannot be used with the type specified 

A dynamic cast can only specify a reference to a class or a pointer to a class or void. When 
a class is referenced, it must have virtual functions defined within that class or a base class 
of that class. 
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804 dynamic_cast cannot convert the expression 

The indicated expression cannot be converted to the type specified with the dynamic_cast 
operator. Only a pointer or reference to a class object can be converted. When a class 
object is referenced, it must have virtual functions defined within that class or a base class 
of that class. 

805 dynamic_cast requires class ’%T’ to have virtual functions 

The indicated class must have virtual functions defined within that class or a base class of 
that class. 

806 base class for type in dynamic_cast is ambiguous (will fail) 

The type in the dynamic_cast is a pointer or reference to an ambiguous base class. 
Example: 

struct A { virtual void f() {}; }; 

struct D1 : A { }; 
struct D2 : A { }; 
struct D : Dl, D2 { }; 

A *foo( D *p ) { 

// will always return NULL 

return ( dynamic_ cast< A* >( p ) ); 

} 

807 base class for type in dynamic_cast is private (may fail) 

The type in the dynamic_cast is a pointer or reference to a private base class. 

Example: 

struct V { virtual void f() {}; }; 
struct A : private virtual V { }; 
struct D : public virtual V, A { }; 

V *foo( A *p ) { 

// returns NULL if 'p' points to an 'A' 

// returns non-NULL if 'p' points to a 'D' 
return ( dynamic_ cast< V* >( p ) ); 

} 

808 base class for type in dynamic_cast is protected (may fail) 

The type in the dynamic_cast is a pointer or reference to a protected base class. 

Example: 

struct V { virtual void f() {}; }; 

struct A : protected virtual V { }; 
struct D : public virtual V, A { }; 

V *foo( A *p ) { 

// returns NULL if 'p' points to an 'A' 

// returns non-NULL if 'p' points to a 'D' 
return ( dynamic_ cast< V* >( p ) ); 

} 
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809 type cannot be used with an explicit cast 

The indicated type cannot be specified as the type of an explicit cast. For example, it is 
illegal to cast to an array or function type. 

810 cannot cast to an array type 

It is not permitted to cast to an array type. 

Example: 

typedef int array_ type[5]; 
int array[5]; 

int* p = (array_ type)array; 

811 cannot cast to a function type 

It is not permitted to cast to a function type. 

Example: 

typedef int fun_ type ( void ) ; 
void* p = (fun_type)0; 

812 implementation restriction: cannot generate RTTI info for ’%T’ (%d classes) 

The information for one class must fit into one segment. If the segment size is restricted to 
64k, the compiler may not be able to emit the correct information properly if it requires 
more than 64k of memory to represent the class hierarchy. 

813 more than one default constructor for ’%T’ 

The compiler found more than one default constructor signature in the class definition. 
There must be only one constructor declared that accepts no arguments. 

Example: 

struct C { 

CO; 

C( int = 0 ); 

1 ; 

C cv; 

814 user-defined conversion is ambiguous 

The compiler found more than one user-defined conversion which could be performed. 

The indicated functions that could be used are shown. 

Example: 

struct T { 

T ( S constS ); 

} ; 

struct S { 

operator T constS (); 

1 ; 

extern S sv; 

T const & tref = sv; 
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Either the constructor or the conversion function could be used; consequently, the 
conversion is ambiguous. 

815 range of possible values for type ’%T’ is %s to %s 

This informational message indicates the range of values possible for the indicated 
unsigned type. 

Example: 

unsigned char uc; 
if( uc >= 0 ) ; 

Being unsigned, the char is always >= 0, so a warning will be issued. Following the 
warning, this informational message indicates the possible range of values for the unsigned 
type involved. 

816 range of possible values for type ’%T’ is %s to %s 

This informational message indicates the range of values possible for the indicated signed 
type. 

Example: 

signed char c; 
if( c <= 127 ) ; 

Because the value of signed char is always <= 127, a warning will be issued. Following the 
warning, this informational message indicates the possible range of values for the signed 
type involved. 

817 constant expression in comparison has value %s 

This informational message indicates the value of the constant expression involved in a 
comparison which caused a warning to be issued. 

Example: 

unsigned char uc; 
if( uc >= 0 ) ; 

Being unsigned, the char is always >= 0, so a warning will be issued. Following the 
warning, this informational message indicates the constant value (0 in this case) involved in 
the comparison. 

818 constant expression in comparison has value %s 

This informational message indicates the value of the constant expression involved in a 
comparison which caused a warning to be issued. 
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Example: 

signed char c; 
if( c <= 127 ) ; 

Because the value of char is always <= 127, a warning will be issued. Following the 
warning, this informational message indicates the constant value (127 in this case) involved 
in the comparison. 

819 conversion of const reference to non-const reference 

A reference to a constant object is being converted to a reference to a non-constant object. 
This can only be accomplished by using an explicit or const_ cast cast. 

Example: 

extern int const & const_ ref; 
int & non_ const_ ref = const_ ref; 

820 conversion of volatile reference to non-volatile reference 

A reference to a volatile object is being converted to a reference to a non-volatile object. 
This can only be accomplished by using an explicit or const_ cast cast. 

Example: 

extern int volatile & volatile_ ref; 
int & non_ volatile_ ref = volatile_ ref; 

821 conversion of const volatile reference to plain reference 

A reference to a constant and volatile object is being converted to a reference to a 
non-volatile and non-constant object. This can only be accomplished by using an explicit 
or const_ cast cast. 

Example: 

extern int const volatile & const_ volatile_ ref; 
int & non_ const_ volatile_ ref = const_ volatile_ ref; 

822 current declaration has type ’%T’ 

This informational message indicates the type of the current declaration that caused the 
message to be issued. 

Example: 

extern int_near foo( int ) ; 

extern int_far foo( int ) ; 

823 only a non-volatile const reference can be bound to temporary 

The expression being bound to a reference will need to be converted to a temporary of the 
type referenced. This means that the reference will be bound to that temporary and so the 
reference must be a non-volatile const reference. 
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Example: 

extern int * pi; 

void * & rl = pi; // error 

void * const & r2 = pi; // ok 

void * volatile & r3 = pi; // error 
void * const volatile & r4 = pi;// error 

824 conversion of pointer to member across a virtual base 

In November 1995, the Draft Working Paper was amended to disallow pointer to member 
conversions when the source class is a virtual base of the target class. This situation is 
treated as a warning (unless -za is specified to require strict conformance), as a temporary 
measure. In the future, an error will be diagnosed for this situation. 

Example: 

struct B { 
int b; 

}; 

struct D : virtual B { 
int d; 

} ; 

int B::* mp_ b = &B::b; 

int D::* mp_ d = mp_b; // conversion across a 

virtual base 

825 declaration cannot be in the same scope as namespace ’%S’ 

A namespace name must be unique across the entire C++ program. Any other use of a 
name cannot be in the same scope as the namespace. 

Example: 

namespace x { 
int q; 

} ; 

int x; 

826 ’%S’ cannot be in the same scope as a namespace 

A namespace name must be unique across the entire C++ program. Any other use of a 
name cannot be in the same scope as the namespace. 

Example: 

int x; 

namespace x { 
int q; 

} ; 
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827 File: %s 

This informative message is written when the -ew switch is specified on a command line. 

It indicates the name of the file in which an error or warning was detected. The message 
precedes a group of one or more messages written for the file in question. Within each 
group, references within the file have the format (line [, column] ) . 

828 %s 

This informative message is written when the -ew switch is specified on a command line. 

It indicates the location of an error when the error was detected either before or after the 
source file was read during the compilation process. 

829 %s: %s 

This informative message is written when the -ew switch is specified on a command line. 

It indicates the location of an error when the error was detected while processing the 
switches specified in a command file or by the contents of an environment variable. The 
switch that was being processed is displayed following the name of the file or the 
environment variable. 

830 %s: %S 

This informative message is written when the -ew switch is specified on a command line. 

It indicates the location of an error when the error was detected while generating a function, 
such as a constructor, destructor, or assignment operator or while generating the machine 
instructions for a function which has been analysed. The name of the function is given 
following text indicating the context from which the message originated. 

831 possible override is ’%S’ 

The indicated function is ambiguous since that name was defined in more than one base 
class and one or more of these functions is virtual. Consequently, it cannot be decided 
which is the virtual function to be used in a class derived from these base classes. 

832 function being overridden is ’%S’ 

This informational message indicates a function which cannot be overridden by a virtual 
function which has ellipsis parameters. 

833 name does not reference a namespace 

A namespace alias definition must reference a namespace definition. 

Example: 

typedef int T; 
namespace a = T; 
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834 namespace alias cannot be changed 

A namespace alias definition cannot change which namespace it is referencing. 

Example: 

namespace nsl { int x; } 

namespace ns2 { int x; } 

namespace a = nsl; 

namespace a = ns2; 

835 cannot throw undefined class object 

C++ does not allow undefined classes to be copied and so an undefined class object cannot 
be specified in a throw expression. 

836 symbol has different type than previous symbol in same declaration 

This warning indicates that two symbols in the same declaration have different types. This 
may be intended but it is often due to a misunderstanding of the C++ declaration syntax. 

Example: 

// change to: 

// char *p; 

// char q; 

// or: 

// char *p, *q; 

char* p, q; 

837 companion definition is ’%S’ 

This informational message indicates the other symbol that shares a common base type in 
the same declaration. 

838 syntax error; default argument cannot be processed 

The default argument contains unbalanced braces or parenthesis. The default argument 
cannot be processed in this form. 

839 default argument started %L 

This informational message indicates where the default argument started so that any 
problems with missing braces or parenthesis can be fixed quickly and easily. 

Example: 

struct S { 

int f( int t= (4+(3-7), // missing parenthesis 

) ; 

} ; 
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840 ’%N’ cannot be declared in a namespace 

A namespace cannot contain declarations or definitions of operator new or operator delete 
since they will never be called implicitly in a new or delete expression. 

Example: 

namespace N { 

void ‘operator new( unsigned ); 
void operator delete( void * ); 


841 namespace cannot be defined in a non-namespace scope 

A namespace can only be defined in either the global namespace scope (file scope) or a 
namespace scope. 

Example: 

struct S { 

namespace N { 
int x; 

} ; 

} 

842 namespace ’:: ’ qualifier cannot be used in this context 

Qualified identifiers in a class context are allowed for declaring friend functions. A 
namespace qualified name can only be declared in a namespace scope that encloses the 
qualified name’s namespace. 

Example: 


namespace 

M { 



namespace 

N 

{ 

void 

f 0 ; 



void 

g 0 ; 



namespace 

0 

{ 


void N::f() { 

// error 

} 

} 

} 

void N::g() { 

// OK 

} 

} 

843 cannot cast away volatility 

A cast or implicit conversion is illegal because a conversion to the target type would 
remove volatility from a pointer, reference, or pointer to member. 
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Example: 

struct S { 
int s; 

} ; 

extern S volatile * ps; 
extern int volatile S::* mps; 

S* psl = ps; 

S& rsl = *ps; 

int S::* mpl = mps; 

The three initializations are illegal since they are attempts to remove volatility. 

844 cannot cast away constness and volatility 

A cast or implicit conversion is illegal because a conversion to the target type would 
remove constness and volatility from a pointer, reference, or pointer to member. 

Example: 

struct S { 
int s; 

} ; 

extern S const volatile * ps; 
extern int const volatile S::* mps; 

S* psl = ps; 

S& rsl = *ps; 

int S::* mpl = mps; 

The three initializations are illegal since they are attempts to remove constness and 
volatility. 

845 cannot cast away unaligned 

A cast or implicit conversion is illegal because a conversion to the target type would add 
alignment to a pointer, reference, or pointer to member. 

Example: 

struct S { 
int s; 

} ; 

extern S _ unaligned * ps; 
extern int _ unaligned S::* mps; 

S* psl = ps; 

S& rsl = *ps; 

int S::* mpl = mps; 

The three initializations are illegal since they are attempts to add alignment. 

846 subscript expression must be integral 

Both of the operands of the indicated index expression are pointers. There may be a 
missing indirection or function call. 
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Example: 

int f(); 
int *p; 
int g() { 

return p[f]; 

} 

847 extension: non-standard user-defined conversion 

An extended conversion was allowed. The latest draft of the C++ working paper does not 
allow a user-defined conversion to be used in this context. As an extension, the WATCOM 
compiler supports the conversion since substantial legacy code would not compile without 
the extension. 

848 useless using directive ignored 

This warning indicates that for most purposes, the using namespace directive can be 
removed. 

Example: 

namespace A { 

using namespace A; // useless 

} ; 

849 base class virtual function has not been overridden 

This warning indicates that a virtual function name has been overridden but in an 
incomplete manner, namely, a virtual function signature has been omitted in the overriding 
class. 

Example: 

struct B { 

virtual void f() const; 

In¬ 
struct D : B { 

virtual void f(); 

} ; 

850 virtual function is ’%S’ 

This message indicates which virtual function has not been overridden. 

851 macro ’%s’ defined %L 

This informational message indicates where the macro in question was defined. The 
message is displayed following an error or warning diagnostic for the macro in question. 
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852 


853 


854 


855 


Example: 

♦define mac(a,b,c) a+b+c 
int i = mac (6, 7,8, 9, 10) ; 

The expansion of macro mac is erroneous because it contains too many arguments. The 
informational message will indicate where the macro was defined. 

expanding macro ’%s’ defined %L 

These informational messages indicate the macros that are currently being expanded, along 
with the location at which they were defined. The message(s) are displayed following a 
diagnostic which is issued during macro expansion. 

conversion to common class type is impossible 

The conversion to a common class is impossible. One or more of the left and right 
operands are class types. The informational messages indicate these types. 

Example: 


class A 

{ AO; 

}; 

class B 

{ BO; 

}; 

extern A 

a; 


extern B 

b; 


int i = 

( a == 

b ); 


The last statement is erroneous since a conversion to a common class type is impossible. 
conversion to common class type is ambiguous 

The conversion to a common class is ambiguous. One or more of the left and right 
operands are class types. The informational messages indicate these types. 


Example: 

class A 
class B 
class C 
class D 
extern A 
extern D d; 
int i = ( a == d 


{ A () ; } ; 

: public A 
: public A 
: public B, 
a; 


) ; 


{ B () ; }; 

{ C(); } ; 

public C 


DO; } ; 


The last statement is erroneous since a conversion to a common class type is ambiguous. 
conversion to common class type requires private access 

The conversion to a common class violates the access permission which was private. One 
or more of the left and right operands are class types. The informational messages indicate 
these types. 
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Example: 

class A { A(); }; 

class B : private A { B(); }; 

extern A a; 

extern B b; 

int i = ( a == b ); 

The last statement is erroneous since a conversion to a common class type violates the 
(private) access permission. 

856 conversion to common class type requires protected access 

The conversion to a common class violates the access permission which was protected. 
One or more of the left and right operands are class types. The informational messages 
indicate these types. 

Example: 

class A { A(); }; 

class B : protected A { B(); }; 

extern A a; 

extern B b; 

int i = ( a == b ); 

The last statement is erroneous since a conversion to a common class type violates the 
(protected) access permission. 

857 namespace lookup is ambiguous 

A lookup for a name resulted in two or more non-function names being found. This is not 
allowed according to the C++ working paper. 

Example: 

namespace M { 
int i; 

} 

namespace N { 
int i; 

using namespace M; 

} 

void f () { 

using namespace N; 
i = 7; // error 

} 

858 ambiguous namespace symbol is ’%S’ 

This informational message shows a symbol that conflicted with another symbol during a 
lookup. 
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859 attempt to static_cast from a private base class 

An attempt was made to static_cast a pointer or reference to a private base class to a 
derived class. 

Example: 

struct PrivateBase { 

} ; 


struct Derived : private PrivateBase { 

} ; 


extern PrivateBase* pb; 
extern PrivateBaseS rb; 

Derived* pd = static_ cast<Derived*>( pb ); 

DerivedS rd = static_ cast<Derived&>( rb ); 

The last two statements are erroneous since they would involve a static_cast from a private 
base class. 

860 attempt to static_cast from a protected base class 

An attempt was made to static_cast a pointer or reference to a protected base class to a 
derived class. 

Example: 

struct ProtectedBase { 

}; 


struct Derived : protected ProtectedBase { 

} ; 


extern ProtectedBase* pb; 
extern ProtectedBase& rb; 

Derived* pd = static_ cast<Derived*>( pb ); 

DerivedS rd = static_ cast<Derived&>( rb ); 

The last two statements are erroneous since they would involve a static_cast from a 
protected base class. 

861 qualified symbol cannot be defined in this scope 

This message indicates that the scope of the symbol is not nested in the current scope. This 
is a restriction in the C++ language. 

Example: 
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namespace A { 
struct S { 
void ok(); 
void bad(); 

}; 

void ok(); 
void bad(); 

} ; 

void A::S::ok() { 

} 

void A::ok() { 

} 

namespace B { 

void A::S::bad() { 

// error! 

} 

void A::bad() { 

// error! 

} 

} ; 

862 using declaration references non-member 

This message indicates that the entity referenced by the using declaration is not a class 

member even though the using declaration is in class scope. 

Example: 

namespace B { 
int x; 

}; 

struct D { 

using B:: x; 

} ; 

863 using declaration references class member 

This message indicates that the entity referenced by the using declaration is a class member 

even though the using declaration is not in class scope. 

Example: 

struct B { 
int m; 

} ; 

using B::m; 

864 invalid suffix for a constant 

An invalid suffix was coded for a constant. 


516 Diagnostic Messages 




Open Watcom C++ Diagnostic Messages 


Example: 


int 64 

a [ ] 

= { 

0i7, 
0i8, 

// 

error 

0il5, 

0il6, 

// 

error 

0i31, 
0i32, 

// 

error 

0i63, 

0i64, 

// 

error 


865 class in using declaration (’%T’) must be a base class 

A using declaration declared in a class scope can only reference entities in a base class. 

Example: 

struct B { 
int f; 

} ; 

struct C { 
int g; 

} ; 

struct D : private C { 

B: if; 

1 ; 


866 name in using declaration is already in scope 

A using declaration can only reference entities in other scopes. It cannot reference entities 
within its own scope. 

Example: 

namespace B { 
int f; 
using B: if; 

} ; 


867 conflict with a previous using-decl ’%S’ 

A using declaration can only reference entities in other scopes. It cannot reference entities 
within its own scope. 

Example: 

namespace B { 
int f; 
using B: if; 

} ; 
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868 conflict with current using-decl ’%S’ 

A using declaration can only reference entities in other scopes. It cannot reference entities 
within its own scope. 

Example: 

namespace B { 
int f; 
using B::f; 

} ; 

869 use of ’%N’ requires build target to be multi-threaded 

The compiler has detected a use of a run-time function that will create a new thread but the 
current build target indicates only single-threaded C++ source code is expected. 

Depending on the user’s environment, enabling multi-threaded applications can involve 
using the "-bm" option or selecting multi-threaded applications through a dialogue. 

870 implementation restriction: cannot use 64-bit value in switch statement 
The use of 64-bit values in switch statements has not been implemented. 

871 implementation restriction: cannot use 64-bit value in case statement 
The use of 64-bit values in case statements has not been implemented. 

872 implementation restriction: cannot use _ int64 as bit-field base type 

The use of_ int64 for the base type of a bit-field has not been implemented. 

873 based function object cannot be placed in non-code segment "%s". 

Use_ segname with the default code segment "_CODE", or a code segment with the 

appropriate suffix (indicated by informational message). 

Example: 

int_based (_segname ("foo") ) f() {return 1;} 

Example: 

int_based (_segname ("_ CODE" ) ) f() {return 1;} 

874 Use a segment name ending in "%s", or the default code segment "_CODE". 

This informational message explains how to use_ segname to name a code segment. 

875 RTTI must be enabled to use feature (use ’xr’ option) 

RTTI must be enabled by specifying the ’xr’ option when the compiler is invoked. The 
error message indicates that a feature such as dynamic _cast, or type id has been used 
without enabling RTTI. 
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876 ’typeid’ class type must be defined 

The compile-time type of the expression or type must be completely defined if it is a class 
type. 

Example: 

struct S; 

void foo( S *p ) { 

typeid( *p ); 
typeid( S ); 

} 

877 cast involves unrelated member pointers 

This warning is issued to indicate that a dangerous cast of a member pointer has been used. 
This occurs when there is an explicit cast between sufficiently unrelated types of member 
pointers that the cast must be implemented using a reinterpret_cast. These casts were 
illegal, but became legal when the new-style casts were added to the draft working paper. 

Example: 

struct Cl { 

int foo (); 

}; 

struct D1 { 

int poo(); 

} ; 

typedef int (Cl::* Clmp )(); 

Clmp fmp = (Clmp)&D1::poo; 

The cast on the last line of the example would be diagnosed. 

878 unexpected type modifier found 

A declspec modifier was found that could not be applied to an object or could not be 
used in this context. 

Example: 

_declspec(thread) struct S { 

} ; 

879 invalid bit-field name ’%N’ 

A bit-field can only have a simple identifier as its name. A qualified name is also not 
allowed for a bit-field. 
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Example: 

struct S { 

int operator + : 1; 

} ; 


880 %u padding byte(s) added 

This warning indicates that some extra bytes have been added to a class in order to align 
member data to its natural alignment. 

Example: 

♦pragma pack(push,8) 
struct S { 
char c; 
double d; 

} ; 

♦pragma pack(pop); 

881 cannot be called with a ’%T *’ 

This message indicates that the virtual function cannot be called with a pointer or reference 
to the current class. 

882 cast involves an undefined member pointer 

This warning is issued to indicate that a dangerous cast of a member pointer has been used. 
This occurs when there is an explicit cast between sufficiently unrelated types of member 
pointers that the cast must be implemented using a reinterpret_cast. In this case, the host 
class of at least one member pointer was not a fully defined class and, as such, it is 
unknown whether the host classes are related through derivation. These casts were illegal, 
but became legal when the new-style casts were added to the draft working paper. 

Example: 

struct Cl { 

int foo(); 

} ; 

struct Dl; 

typedef int (Cl::* Clmp )(); 
typedef int (Dl::* Dlmp )(); 

Clmp fn( Dlmp x ) { 

return (Clmp) x; 

} 

// Dl may derive from Cl 
The cast on the last line of the example would be diagnosed. 
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883 cast changes both member pointer object and class type 

This warning is issued to indicate that a dangerous cast of a member pointer has been used. 
This occurs when there is an explicit cast between sufficiently unrelated types of member 
pointers that the cast must be implemented using a reinterpret_cast. In this case, the host 
classes of the member pointers are related through derivation and the object type is also 
being changed. The cast can be broken up into two casts, one that changes the host class 
without changing the object type, and another that changes the object type without 
changing the host class. 

Example: 

struct Cl { 

int fnl (); 

} ; 

struct D1 : Cl { 
int fn2 () ; 

} ; 

typedef int (Cl::* Clmp )(); 
typedef void (Dl::* Dlmp )(); 

Clmp fn( Dlmp x ) { 

return (Clmp) x; 

} 

The cast on the last line of the example would be diagnosed. 

884 virtual function ’%S’ has a different calling convention 

This error indicates that the calling conventions specified in the virtual function prototypes 
are different. This means that virtual function calls will not function properly since the 
caller and callee may not agree on how parameters should be passed. Correct the problem 
by deciding on one calling convention and change the erroneous declaration. 

Example: 

struct B { 

virtual void _cdecl foo( int, int ); 

}; 

struct D : B { 

void foo( int, int ); 

1 ; 

885 #endif matches #ifin different source file 

This warning may indicate a #endif nesting problem since the traditional usage of #if 
directives is confined to the same source file. This warning may often come before an error 
and it is hoped will provide information to solve a preprocessing directive problem. 


Diagnostic Messages 521 




Appendices 


886 preprocessing directive found %L 

This informational message indicates the location of a preprocessing directive associated 
with the error or warning message. 

887 unary of unsigned operand produces unsigned result 

When a unary minus operator is applied to an unsigned operand, the result has an 
unsigned type rather than a signed type. This warning often occurs because of the 
misconception that is part of a numeric token rather than as a unary operator. The 
work-around for the warning is to cast the unary minus operand to the appropriate signed 
type. 

Example: 

extern void u( int ); 
extern void u( unsigned ); 
void fn( unsigned x ) { 

u ( -x ); 

u ( -2147483648 ); 

} 

888 trigraph expansion produced ’%c’ 

Trigraph expansion occurs at a very low-level so it can affect string literals that contain 
question marks. This warning can be disabled via the command line or #pragma warning 
directive. 

Example: 

// string expands to "(?]?~????"! 
char *e = "(???)???-????"; 

// possible work-arounds 

char *f = "(" " 77 ?" ")" "777" "_" " 7777 "; 
char *g = " (\?\?\?)\?\?\?-\?\?\?\?"; 

889 hexadecimal escape sequence out of range; truncated 

This message indicates that the hexadecimal escape sequence produces an integer that 
cannot fit into the required character type. 

Example: 

char *p = "\xOaCache Timings\xOa"; 

890 undefined macro ’%s’ evaluates to 0 

The ISO C/C++ standard requires that undefined macros evaluate to zero during 
preprocessor expression evaluation. This default behaviour can often mask incorrectly 
spelled macro references. The warning is useful when used in critical environments where 
all macros will be defined. 
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Example: 

#if _ PRODUCTION // should be _PRODUCTION 
#endif 

891 char constant has value %u (more than 8 bits) 

The ISO C/C++ standard requires that multi-char character constants be accepted with an 
implementation defined value. This default behaviour can often mask incorrectly specified 
character constants. 

Example: 

int x = '\0xla'; // warning 
int y = '\xla'; 

892 promotion of unadorned char type to int 

This message is enabled by the hidden -jw option. The warning may be used to locate all 
places where an unadorned char type (i.e., a type that is specified as char and neither 
signed char nor unsigned char ). This may cause portability problems since compilers 
have freedom to specify whether the unadorned char type is to be signed or unsigned. The 
promotion to int will have different values, depending on the choice being made. 

893 switch statement has no case labels 

The switch statement referenced in the warning did not have any case labels. Without case 
labels, a switch statement will always jump to the default case code. 

Example: 

void fn( int x ) 

{ 

switch( x ) { 

default: 

+ + X } 

} 

} 

894 unexpected character (%u) in source file 

The compiler has encountered a character in the source file that is not in the allowable set 
of input characters. The decimal representation of the character byte is output for 
diagnostic purposes. 

Example: 

// invalid char '\0' 

895 ignoring whitespace after line splice 

The compiler is ignoring some whitespace characters that occur after the line splice. This 
warning is useful when the source code must be compiled with other compilers that do not 
allow this extension. 
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Example: 

♦define XXXX int \ 
x; 


XXXX 

896 empty member declaration 

The compiler is warning about an extra semicolon found in a class definition. The extra 
semicolon is valid C++ but some C++ compilers do not accept this as valid syntax. 

Example: 

struct S { ; }; 

897 ’%S’ makes use of a non-portable feature (zero-sized array) 

The compiler is warning about the use of a non-portable feature in a declaration or 
definition. This warning is available for environments where diagnosing the use of 
non-portable features is useful in improving the portability of the code. 

Example: 

struct D { 
int d; 
char a[]; 

} ; 


898 in-class initialization is only allowed for const static integral members 

Example: 

struct A { 

static int i = 0; 

} ; 


899 cannot convert expression to target type 

The implicit cast is trying to convert an expression to a completely unrelated type. There is 
no way the compiler can provide any meaning for the intended cast. 

Example: 

struct T { 

} ; 

void fn() 

{ 

bool b = T; 

} 

900 unknown template specialization of ’%S’ 
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Example: 

template<class T> 
struct A { }; 

template<class T> 
void A<T *>::f() { 

} 

901 wrong number of template arguments for ’%S’ 
Example: 

template<class T> 
struct A { }; 

template<class T, class U> 
struct A<T, U> { }; 

} 

902 cannot explicitly specialize member of ’%S’ 
Example: 

template<class T> 
struct A { }; 

templateo 
struct A<int> { 
void f(); 

} ; 


templateo 

void A<int>::f() { 

} 

903 specialization arguments for ’%S’ match primary template 
Example: 

template<class T> 
struct A { }; 

template<class T> 
struct A<T> { }; 

904 partial template specialization for ’%S’ ambiguous 
Example: 

template<class T, class U> 
struct A { }; 

template<class T, class U> 
struct A<T *, U> { }; 

template<class T, class U> 
struct A<T, U *> { }; 

A<int *, int *> a; 
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905 static assertion failed ’%s’ 

Example: 

static_ assert( false, "false" ); 

906 Exported templates are not supported by Open Watcom C++ 

Example: 

export template< class T > 
struct A { 

} ; 

907 redeclaration of member function ’%S’ not allowed 

Example: 

struct A { 

void f(); 
void f(); 

} ; 

908 candidate defined %L 

909 Invalid register name ’%s’ in #pragma 
The register name is invalid/unknown. 

910 Archaic syntax: class/struct missing in explicit template instantiation 

Archaic syntax has been used. The standard requires a class or struct keyword to be used. 
Example: 

template< class T > 
class MyTemplate { }; 

template MyTemplate< int >; 

Example: 

template class MyTemplate< int >; 

911 destructor for type void cannot be called 

Since the void type has no size and there are no values of void type, one cannot destruct an 
instance of void. 

912 ’typename ’ keyword used outside template 

The typename keyword is only allowed inside templates. 
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913 ’%N’ does not have a return type specified 

In C++, functions must have an explicit return type specified, default int type is no longer 
assumed. 

Example: 

f 0; 

914 ’main ’ must return ’int’ 

The "main" function shall have a return type of type int. 

Example: 

void main() 

{ } 

915 explicit may only be used within class definition 

The explicit specifier shall be used only in the declaration of a constructor within its class 
definition. 

Example: 

struct A { 

explicit A(); 

} ; 

explicit A::A() 

{ } 

916 virtual may only be used within class definition 

The virtual specifier shall be used only in the initial declaration of a class member function. 

Example: 

struct A { 

virtual void f(); 

} ; 

virtual void A::f() 

{ } 

917 cannot redefine default template argument ’%N’ 

A template-parameter shall not be given default arguments by two different declarations in 
the same scope. 

Example: 

template< class T = int > 
class X; 

template< class T = int > 
class X { 

}; 
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918 cannot have default template arguments in partial specializations 

A partial specialization cannot have default template arguments. 
Example: 

template< class T > 
class X { 

}; 

template< class T = int > 
class X< T * > { 

} ; 


919 delete of a pointer to void 

If the dynamic type of the object to be deleted differs from its static type, the behavior is 
undefined. This implies that an object cannot be deleted using a pointer of type void* 
because there are no objects of type void. 

Example: 

void fn( void *p, void *q ) { 

delete p; 
delete [] q; 

} 

920 ’long char’ is deprecated, use wchar_t instead 

The standard C++ ’wchar_t’ type specifier should be used instead of the Open Watcom 
specific Tong char’ type specifier. 

Example: 

void fn( ) { 

long char c; 

} 

921 namespace ’%/’ not allowed in using-declaration 

Specifying a namespace-name is not allowed in a using-declaration, a using-directive must 
be used instead. 

Example: 

namespace ns { } 
using ns; 

922 candidate %C defined %L 

923 qualified name ’%/’ does not name a class 
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Example: 

namespace ns { 

} 

struct ns::A { 

} ; 


924 expected class type, but got ’%T’ 

Example: 

template< class T > 
struct A : public T { 

} ; 

A< int > a; 

925 syntax error near ’%s ’; probable cause: incorrectly spelled type name 

The identifier in the error message has not been declared as a type name in any scope at this 
point in the code. This may be the cause of the syntax error. 

926 syntax error: ’%s’ has not been declared as a member 

The identifier in the error message has not been declared as member. This may be the 
cause of the syntax error. 

Example: 

struct A { }; 

void fn() { 

A::undeclared = 0; 

} 

927 syntax error: ’%s’ has not been declared 

The identifier in the error message has not been declared. This may be the cause of the 
syntax error. 

Example: 

void fn() { 

::undeclared = 0; 

} 

928 syntax error: identifier ’%s\ but expected: ’%s’ 

929 syntax error: token ’%s\ but expected: ’%s’ 

930 member ’%S’ cannot be declared in this class 

A member cannot be declared with the same name as its containing class if the class has a 
user-declared constructor. 
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Example: 

struct S { 

SO { } 

int S; // Error! 

} ; 


931 cv-qualifier in cast to ’%T’ is meaningless 

A top-level cv-qualifier for a non-class rvalue is meaningless. 

Example: 

const int i = (const int) 0; 

932 cv-qualifier in return type ’%T’ is meaningless 

A top-level cv-qualifier for a non-class rvalue is meaningless. 

Example: 

const int f() { 

return 0; 

} 

933 use of C-style cast to ’%T’ is discouraged 

Use of C-style casts "(type) (expr)" is discouraged in favour of explicit C++ casts like 
static_cast, const_cast, dynamic_cast and reinterpret_cast. 

Example: 

const signed int *f( unsigned int *psi ) { 

return ( signed int * ) psi; 

} 

934 unable to match function template definition ’%S’ 

The function template definition cannot be matched to an earlier declaration. 
Example: 

template< class T > 
struct A 
{ 

A ( ) ; 

} ; 

template< class T > 

A< int >::A( ) 

{ 1 

935 form is ’#pragma enable_message( msgnum )’ 

This pragma enables the specified warning message. 
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936 form is ’#pragma disable_message( msgnum )’ 

This pragma disables the specified warning message. 

937 option requires a character 

The specified option is not recognized by the compiler since there was no character after it 
(i.e., ”-p#@"). 

938 ’auto’ is no longer a storage specifier in C++11 mode 

When C++11 is enabled, the auto can no longer appear as a storage specifier. 

939 Implicit conversion from ’decltype(nullptr)’ to ’bool’. 

When C++11 is enabled, an implicit conversion from std::nullptr_t to bool is suspicious. 
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D. Open Watcom C/C++ Run-Time Messages 


The following is a list of error messages produced by the Open Watcom C/C++ run-time library. These 
messages can only appear during the execution of an application built with one of the C run-time libraries. 

D.1 Run-Time Error Messages 

Assertion failed: %s, file %s, line %d 

This message is displayed whenever an assertion that you have made in your program is not 
true. 

Stack Overflow! 

Your program is trying to use more stack space than is available. If you believe that your 
program is correct, you can increase the size of the stack by using the "option stack=nnnn" 
when you link the program. The stack size can also be specified with the "k" option if you 
are using WCL or WCL386. 

Floating-point support not loaded 

You have called one of the printf functions with a format of "%e", "%f", or "%g", but have 
not passed a floating-point value. The compiler generates a reference to the variable 
"_fltused_" whenever you pass a floating-point value to a function. During the linking 
phase, the extra floating-point formatting routines will also be brought into your application 
when "_fltused_" is referenced. Otherwise, you only get the non floating-point formatting 
routines. 

*** NULL assignment detected 

This message is displayed if any of the first 32 bytes of your program’s data segment has 
been modified. The check is performed just before your program exits to the operating 
system. All this message means is that sometime during the execution of your program, 
this memory was modified. 

To find the problem, you must link your application with debugging information and use 
Open Watcom Debugger to monitor its execution. First, run the application with Open 
Watcom Debugger until it completes. Examine the first 16 bytes of the data segment 

("examine_nullarea") and press the space bar to see the next 16 bytes. Any values that 

are not equal to ’OF have been modified. Reload the application, set watch points on the 
modified locations, and start execution. Open Watcom Debugger will stop when the 
specified location(s) change in value. 
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D.2 errno Values and Their Meanings 

The following errors can be generated by the C run-time library. These error codes correspond to the error 
types defined in errno . h . 

ENOENT No such file or directory 

The specified file or directory cannot be found. 

E2BIG Argument list too big 

The argument list passed to the spawn. . ., exec ... or system functions requires 
more than 128 bytes, or the environment information exceeds 32K. 

ENOEXEC Exec format error 

The executable file has an invalid format. 

EBADF Bad file number 

The file handle is not a valid file handle value or it does not correspond to an open file. 
ENOMEM Not enough memory 

There was not enough memory available to perform the specified request. 

EACCES Permission denied 

You do not have the required (or correct) permissions to access a file. 

EEXIST File exists 

An attempt was made to create a file with the 0_EXCL (exclusive) flag when the file 
already exists. 

EXDEV Cross-device link 

An attempt was made to rename a file to a different device. 

EINVAL Invalid argument 

An invalid value was specified for one of the arguments to a function. 

ENFILE File table overflow 

All the FILE structures are in use, so no more files can be opened. 

EMFILE Too many open files 

There are no more file handles available, so no more files can be opened. The maximum 
number of file handles available is controlled by the "FILES=" option in the 
"CONFIG.SYS" file. 
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ENOSPC 


EDOM 


ERANGE 


EDEADLK 


No space left on device 

No more space is left for writing on the device, which usually means that the disk is full. 
Argument too large 

An argument to a math function is not in the domain of the function. 

Result too large 

The result of a math function could not be represented (too small, or too large). 

Resource deadlock would occur 

A resource deadlock would occur with regards to locked files. 


D.3 Math Run-Time Error Messages 

The following errors can be generated by the math functions in the C run-time library. These error codes 
correspond to the exception types defined in math. h and returned by the matherr function when a math 
error occurs. 

DOMAIN Domain error 

An argument to the function is outside the domain of the function. 
OVERFLOW Overflow range error 

The function result is too large. 

PLOSS Partial loss of significance 

A partial loss of significance occurred. 

SING Argument singularity 

An argument to the function has a bad value (e.g., log(O.O)). 

TLOSS Total loss of significance 

A total loss of significance occurred. An argument to a function 
was too large to produce a meaningful result. 

UNDERFLOW Underflow range error 

The result is too small to be represented. 
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1 C Library Overview 


The C library provides much of the power usually associated with the C language. This chapter introduces 
the individual functions (and macros) that comprise the Open Watcom C library. The chapter Library 
Functions and Macros describes each function and macro in complete detail. 

Library functions are called as if they had been defined within the program. When the program is linked, 
the code for these routines is incorporated into the program by the linker. 

Strictly speaking, it is not necessary to declare most library functions since they return int values for the 
most part. It is preferred, however, to declare all functions by including the header files found in the 
synopsis section with each function. Not only does this declare the return value, but also the type expected 
for each of the arguments as well as the number of arguments. This enables the Open Watcom C and C++ 
compilers to check the arguments coded with each function call. 


1.1 Classes of Functions 


The functions in the Open Watcom C library can be organized into a number of classes: 

Character Manipulation Functions 

These functions deal with single characters. 

Wide Character Manipulation Functions 

These functions deal with wide characters. 

Multibyte Character Manipulation Functions 

These functions deal with multibyte characters. 

Memory Manipulation Functions 

These functions manipulate blocks of memory. 

String Manipulation Functions 

These functions manipulate strings of characters. A character string is an array of zero or 
more adjacent characters followed by a null character (' \ 0' ) which marks the end of the 
string. 

Wide String Manipulation Functions 

These functions manipulate strings of wide characters. A wide character string is an array 
of zero or more adjacent wide characters followed by a null wide character (L' \ 0' ) 
which marks the end of the wide string. 

Multibyte String Manipulation Functions 

These functions manipulate strings of multibyte characters. A multibyte character is either 
a single-byte or double-byte character. The Chinese, Japanese and Korean character sets 
are examples of character sets containing both single-byte and double-byte characters. 
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What determines whether a character is a single-byte or double-byte character is the value 
of the lead byte in the sequence. For example, in the Japanese DBCS (double-byte 
character set), double-byte characters are those in which the first byte falls in the range 
0x81 - 0x9F or OxEO - OxFC and the second byte falls in the range 0x40 - 0x7E or 0x80 - 
OxFC. A string of multibyte characters must be scanned from the first byte (index 0) to the 
last byte (index n) in sequence in order to determine if a particular byte is part of a 
double-byte character. For example, suppose that a multibyte character string contains the 
following byte values. 

0x31 0x40 0x41 0x81 0x41 // "1@A.." where .. is a DB char 

Among other characters, it contains the letter "A" (the first 0x41) and a double-byte 
character (0x81 0x41). The second 0x41 is not the letter "A" and that could only be 
determined by scanning from left to right starting with the first byte (0x31). 

Conversion Functions 

These functions convert values from one representation to another. Numeric values, for 
example, can be converted to strings. 

Memory Allocation Functions 

These functions are concerned with allocating and deallocating memory. 

Heap Functions 

These functions provide the ability to shrink and grow the heap, as well as, find heap 
related problems. 

Math Functions 

The mathematical functions perform mathematical computations such as the common 
trigonometric calculations. These functions operate on double values, also known as 
floating-point values. 

Searching Functions 

These functions provide searching and sorting capabilities. 

Time Functions 

These functions provide facilities to obtain and manipulate times and dates. 

Variable-length Argument Lists 

These functions provide the capability to process a variable number of arguments to a 
function. 

Stream I/O Functions 

These functions provide the "standard" functions to read and write files. Data can be 
transmitted as characters, strings, blocks of memory or under format control. 

Wide Character Stream I/O Functions 

These functions provide the "standard" functions to read and write files of wide characters. 
Data can be transmitted as wide characters, wide character strings, blocks of memory or 
under format control. 

Process Primitive Functions 

These functions deal with process creation, execution and termination, signal handling, and 
timer operations. 
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Process Environment 

These functions deal with process identification, user identification, process groups, system 
identification, system time and process time, environment variables, terminal identification, 
and configurable system variables. 

Directory Functions 

These functions provide directory services. 

Operating System I/O Functions 

These "non-standard" file operations are more primitive than the "standard" functions in 
that they are directly interfaced to the operating system. They are included to provide 
compatibility with other C implementations and to provide the capability to directly use 
operating-system file operations. 

File Manipulation Functions 

These functions operate directly on files, providing facilities such as deletion of files. 
Console I/O Functions 

These functions provide the capability to directly read and write characters from the 
console. 

Default Windowing Functions 

These functions provide the capability to manipulate various dialog boxes in Open 
Watcom’s default windowing system. 

BIOS Functions 

This set of functions allows access to services provided by the BIOS. 

DOS-Specific Functions 

This set of functions allows access to DOS-specific functions. 

Intel 80x86 Architecture-Specific Functions 

This set of functions allows access to Intel 80x86 processor-related functions. 

Intel Pentium Multimedia Extension Functions 

This set of functions allows access to Intel Architecture Multimedia Extensions (MMX). 

Miscellaneous Functions 

This collection consists of the remaining functions. 

DOS LFN aware Functions 

These functions are DOS LFN capable. 

The following subsections describe these function classes in more detail. Each function in the class is 
noted with a brief description of its purpose. The chapter Library Functions and Macros provides a 
complete description of each function and macro. 

1.1.1 Character Manipulation Functions 

These functions operate upon single characters of type char. The functions test characters in various 
ways and convert them between upper and lowercase. The following functions are defined: 

isalnum test for letter or digit 
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isalpha 

test for letter 

isascii 

test for ASCII character 

isblank 

test for blank character 

iscntrl 

test for control character 

_ iscsym 

test for letter, underscore or digit 

_ iscsymf 

test for letter or underscore 

isdigit 

test for digit 

isgraph 

test for printable character, except space 

islower 

test for letter in lowercase 

isprint 

test for printable character, including space 

ispunct 

test for punctuation characters 

isspace 

test for "white space" characters 

isupper 

test for letter in uppercase 

isxdigit 

test for hexadecimal digit 

tolower 

convert character to lowercase 

toupper 

convert character to uppercase 


1.1.2 Wide Character Manipulation Functions 

These functions operate upon wide characters of type wchar_ t. The functions test wide characters in 
various ways and convert them between upper and lowercase. The following functions are defined: 


iswalnum 

test for letter or digit 

iswalpha 

test for letter 

iswascii 

test for ASCII character 

iswblank 

test for blank character 

iswcntrl 

test for control character 

_ iswcsym 

test for letter, underscore or digit 

_ iswcsymf 

test for letter or underscore 

isw digit 

test for digit 

iswgraph 

test for printable character, except space 

iswlower 

test for letter in lowercase 

iswprint 

test for printable character, including space 

iswpunct 

test for punctuation characters 

iswspace 

test for "white space" characters 

iswupper 

test for letter in uppercase 

iswxdigit 

test for hexadecimal digit 

wctype 

construct a property value for a given "property 

iswctype 

test a character for a specific property 

towlower 

convert character to lowercase 

towupper 

convert character to uppercase 

wctrans 

construct mapping value for a given "property" 

towctrans 

convert a character based on a specific property 


it 


1.1.3 Multibyte Character Manipulation Functions 

These functions operate upon multibyte characters. The functions test wide characters in various ways and 
convert them between upper and lowercase. The following functions are defined: 

Jmbccmp compare one multibyte character with another 

Jmbccpy copy one multibyte character from one string to another 

Jmbcicmp compare one multibyte character with another (case insensitive) 
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_fmbclen 

_fmblen 

_fmbgetcode 

_fmbputchar 

_fmbrlen 

_fmbrtowc 

_Jmbsbtype 

_Jmbtowc 

_ismbbalnum 

_ismbbalpha 

_ismbbgraph 

Jismbbkalnum 

_ismbbkana 

_ismbbkalpha 

_ismbbkprint 

_ismbbkpu.nct 

_ismbblead 

_ismbbprint 

_ismbbpunct 

_ismbbtrail 

_ismbcalnum 

_ismbcalpha 

_ismbccntrl 

_ismbcdigit 

_ismbcgraph 

_ismbchira 

_ismbckata 

_ismbcIO 

_ismbcll 

_ismbcl2 

_ismbclegal 

_ismbclower 

_ismbcprint 

_ismbcpunct 

_ismbcspace 

_ismbcsymbol 

_ismbcupper 

_ismbcxdigit 

_mbbtombc 

_mbbtype 

_mbccmp 

_mbccpy 

_mbcicmp 

_mbcjistojms 

_mbcjmstojis 

_mbclen 

_mbctolower 

_mbctoupper 

_mbctohira 

_mbctokata 

_mbctombb 

_mbgetcode 

mblen 

_mbputchar 


return number of bytes comprising multibyte character 

determine length of next multibyte character 

get next single-byte or double-byte character from far suing 

store single-byte or double-byte character into far string 

determine length of next multibyte character 

convert far multibyte character to wide character 

return type of byte in multibyte character string 

convert far multibyte character to wide character 

test for isalnum or _ismbbkalnum 

test for isalpha or _ismbbkalpha 

test for isgraph or _ismbbkprint 

test for non-ASCII text symbol other than punctuation 

test for single-byte Katakana character 

test for non-ASCII text symbol other than digits or punctuation 

test for non-ASCII text or non-ASCII punctuation symbol 

test for non-ASCII punctuation character 

test for valid first byte of multibyte character 

test for isprint or _ismbbkprint 

test for ispunct or _ismbbkpunct 

test for valid second byte of multibyte character 

test for _ismbcalpha or _ismbcdigit 

test for a multibyte alphabetic character 

test for a multibyte control character 

test for a multibyte decimal-digit character ’0’ through ’9’ 

test for a printable multibyte character except space 

test for a double-byte Hiragana character 

test for a double-byte Katakana character 

test for a double-byte non-Kanji character 

test for a JIS level 1 double-byte character 

test for a JIS level 2 double-byte character 

test for a valid multibyte character 

test for a valid lowercase multibyte character 

test for a printable multibyte character including space 

test for any multibyte punctuation character 

test for any multibyte space character 

test for valid multibyte symbol (punctuation and other special graphics) 

test for valid uppercase multibyte character 

test for any multibyte hexadecimal-digit character 

return double-byte equivalent to single-byte character 

determine type of byte in multibyte character 

compare one multibyte character with another 

copy one multibyte character from one string to another 

compare one multibyte character with another (case insensitive) 

convert JIS code to shift-JIS code 

convert shift-JIS code to JIS code 

return number of bytes comprising multibyte character 

convert double-byte uppercase character to double-byte lowercase character 

convert double-byte lowercase character to double-byte uppercase character 

convert double-byte Katakana character to Hiragana character 

convert double-byte Hiragana character to Katakana character 

return single-byte equivalent to double-byte character 

get next single-byte or double-byte character from string 

determine length of next multibyte character 

store single-byte or double-byte character into string 
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mbrlen 

mbrtowc 

_mbsbtype 

mbsinit 

mbtowc 


determine length of next multibyte character 

convert multibyte character to wide character 

return type of byte in multibyte character string 

determine if mbstate_t object describes an initial conversion state 

convert multibyte character to wide character 


1.1.4 Memory Manipulation Functions 

These functions manipulate blocks of memory. In each case, the address of the memory block and its size 
is passed to the function. The functions that begin with "_f" accept far pointers as their arguments 
allowing manipulation of any memory location regardless of which memory model your program has been 
compiled for. The following functions are defined: 


Jmemccpy 

_fmemchr 

_fmemcmp 

J'memcpy 

_fmemicmp 

_Jmemmove 

_fmemset 

memccpy 

memchr 

memcmp 

memcpy 

memicmp 

memmove 

memset 

movedata 

swab 

wmemchr 

wmemcmp 

wmemcpy 

wmemmove 

wmemset 


copy far memory block up to a certain character 

search far memory block for a character value 

compare any two memory blocks (near or far) 

copy far memory block, overlap not allowed 

compare far memory, case insensitive 

copy far memory block, overlap allowed 

set any memory block (near of far) to a character 

copy memory block up to a certain character 

search memory block for a character value 

compare memory blocks 

copy memory block, overlap not allowed 

compare memory, case insensitive 

copy memory block, overlap allowed 

set memory block to a character 

copy memory block, with segment information 

swap bytes of a memory block 

search memory block for a wide character value 

compare memory blocks 

copy memory block, overlap not allowed 

copy memory block, overlap allowed 

set memory block to a wide character 


See the section "String Manipulation Functions" for descriptions of functions that manipulate strings of 
data. See the section "Wide String Manipulation Functions" for descriptions of functions that manipulate 
wide strings of data. 


1.1.5 String Manipulation Functions 

A string is an array of characters (with type char) that is terminated with an extra null character 
(' \ 0' ) . Functions are passed only the address of the string since the size can be determined by 
searching for the terminating null character. The functions that begin with "_f accept far pointers as their 
arguments allowing manipulation of any memory location regardless of which memory model your 
program has been compiled for. The following functions are defined: 

bcmp compare two byte strings 

bcopy copy a byte string 

_bprintf formatted transmission to fixed-length string 

bzero zero a byte string 

Jstrcat concatenate two far strings 
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Jstrchr 

_fstrcmp 

Jstrcpy 

_Jstrcspn 

J'stricmp 

_jstrlen 

_fstrlwr 

_fstmcat 

_Jstrncmp 

_fstrncpy 

_Jstrnicmp 

_Jstrnset 

Jstrpbrk 

_Jstrrchr 

_fstrrev 

Jstrset 

_fstrspn 

_fstrstr 

_Jstrtok 

Jstrupr 

sprintf 

sscanf 

s treat 

strehr 

stremp 

strempi 

strcoll 

strepy 

strespn 

_strdec 

_strdup 

strerror 

_stricmp 

_strinc 

strlcat 

strlcpy 

strlen 

_strlwr 

st meat 

strnemp 

_strncnt 

strnepy 

_strnextc 

_strnicmp 

_strninc 

_strnset 

strpbrk 

strrehr 

_strrev 

_strset 

strspn 

_strspnp 

strstr 

strtok 


locate character in far string 
compare two far strings 
copy far string 

get number of string characters not from a set of characters 

compare two far strings with case insensitivity 

length of a far string 

convert far string to lowercase 

concatenate two far strings, up to a maximum length 

compare two far strings up to maximum length 

copy a far string, up to a maximum length 

compare two far strings with case insensitivity up to a maximum length 

fill far string with character to a maximum length 

locate occurrence of a string within a second string 

locate last occurrence of character from a character set 

reverse a far string in place 

fill far string with a character 

find number of characters at start of string which are also in a second string 

find first occurrence of string in second string 

get next token from a far string 

convert far string to uppercase 

formatted transmission to string 

scan from string under format control 

concatenate string 

locate character in string 

compare two strings 

compare two strings with case insensitivity 
compare two strings using "locale" collating sequence 
copy a string 

get number of string characters not from a set of characters 

returns pointer to the previous character in string 

allocate and duplicate a string 

get error message as string 

compare two strings with case insensitivity 

return pointer to next character in string 

concatenate string into a bounded buffer 

copy string into a bounded buffer 

string length 

convert string to lowercase 

concatenate two strings, up to a maximum length 

compare two strings up to maximum length 

count the number of characters in the first "n" bytes 

copy a string, up to a maximum length 

return integer value of the next character in string 

compare two strings with case insensitivity up to a maximum length 

increment character pointer by "n" characters 

fill string with character to a maximum length 

locate occurrence of a string within a second string 

locate last occurrence of character from a character set 

reverse a string in place 

fill string with a character 

find number of characters at start of string which are also in a second string 
return pointer to first character of string not in set 
find first occurrence of string in second string 
get next token from string 
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_strupr 

strxfrm 

_vbprintf 

vsscanf 


convert string to uppercase 
transform string to locale’s collating sequence 
same as "_bprintf" but with variable arguments 
same as "sscanf" but with variable arguments 


For related functions see the sections Conversion Functions (conversions to and from strings), Time 
Functions (formatting of dates and times), and Memory Manipulation Functions (operate on arrays without 
terminating null character). 


1.1.6 Wide String Manipulation Functions 

A wide string is an array of wide characters (with type wchar_ t) that is terminated with an extra null wide 
character (L' \ 0' ) . Functions are passed only the address of the string since the size can be determined 
by searching for the terminating null character. The functions that begin with "_f" accept far pointers as 
their arguments allowing manipulation of any memory location regardless of which memory model your 
program has been compiled for. The following functions are defined: 


Jbwprintf 

swprintf 

swscanf 

_vbwprintf 

vswscanf 

wcscat 

wcschr 

wcscmp 

wcscmpi 

wcscoll 

wcscpy 

wcscspn 

_wcsdec 

_wcsdup 

wcs error 

_wcsicmp 

_wcsinc 

wcslcat 

wcslcpy 

wcslen 

_wcslwr 

wcsncat 

wcsncmp 

_yvcsncnt 

wcsncpy 

_wcsnextc 

_wcsnicmp 

_wcsninc 

jwcsnset 

wcspbrk 

wcsrchr 

_wcsrev 

_wcsset 

wcsspn 

_wcsspnp 

wcsstr 


formatted wide character transmission to fixed-length wcsing 
formatted wide character transmission to string 
scan from wide character string under format control 
same as "_bwprintf" but with variable arguments 
same as "swscanf" but with variable arguments 
concatenate string 
locate character in string 
compare two strings 

compare two strings with case insensitivity 
compare two strings using "locale" collating sequence 
copy a string 

get number of string characters not from a set of characters 

returns pointer to the previous character in string 

allocate and duplicate a string 

get error message as string 

compare two strings with case insensitivity 

return pointer to next character in string 

concatenate string into a bounded buffer 

copy string into a bounded buffer 

string length 

convert string to lowercase 

concatenate two strings, up to a maximum length 

compare two strings up to maximum length 

count the number of characters in the first "n" bytes 

copy a string, up to a maximum length 

return integer value of the next multibyte-character in string 

compare two strings with case insensitivity up to a maximum length 

increment wide character pointer by "n" characters 

fill string with character to a maximum length 

locate occurrence of a string within a second string 

locate last occurrence of character from a character set 

reverse a string in place 

fill string with a character 

find number of characters at start of string which are also in a second string 
return pointer to first character of string not in set 
find first occurrence of string in second string 
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wcstok get next token from string 

_wcsupr convert string to uppercase 

wcsxfrm transform string to locale’s collating sequence 

For related functions see the sections Conversion Functions (conversions to and from strings). Time 
Functions (formatting of dates and times), and Memory Manipulation Functions (operate on arrays without 
terminating null character). 


1.1.7 Multibyte String Manipulation Functions 

A wide string is an array of wide characters (with type wchar_ t) that is terminated with an extra null wide 
character (L' \ 0' ) . Functions are passed only the address of the wide string since the size can be 
determined by searching for the terminating null character. The functions that begin with "_F accept far 
pointers as their arguments allowing manipulation of any memory location regardless of which memory 
model your program has been compiled for. The following functions are defined: 


btowc 

Jmbscat 

Jmbschr 

_fmbscmp 

_Jmbscpy 

_fmbscspn 

Jmbsdec 

Jmbsdup 

Jmbsicmp 

Jmbsinc 

Jmbslen 

_fmbslwr 

_fmbsnbcat 

Jmbsnbcmp 

Jmbsnbcnt 

Jmbsnbcpy 

Jmbsnbicmp 

Jmbsnbset 

_Jmbsncat 

_fmbsnccnt 

_fmbsncmp 

_Jmbsncpy 

_Jmbsnextc 

_fmbsnicmp 

_fmbsninc 

Jmbsnset 

Jmbspbrk 

Jmbsrchr 

Jmbsrev 

_Jmbsrtowcs 

Jmbsset 

_Jmbsspn 

_Jmbsspnp 

_Jmbsstr 

_fmbstok 

_Jmbstowcs 

_fmbsupr 


return wide-character version of single-byte character 

concatenate two far strings 

locate character in far string 

compare two far strings 

copy far string 

get number of string characters not from a set of characters 

returns far pointer to the previous character in far string 

allocate and duplicate a far string 

compare two far strings with case insensitivity 

return far pointer to next character in far string 

length of a far string 

convert far string to lowercase 

append up to "n" bytes of string to another string 

compare up to "n" bytes in two strings 

count the number of characters in the first "n" bytes 

copy up to "n" bytes of a string 

compare up to "n" bytes in two strings with case insensitivity 
fill string with up to "n" bytes 

concatenate two far strings, up to a maximum length 

count the number of characters in the first "n" bytes 

compare two far strings up to maximum length 

copy a far string, up to a maximum length 

return integer value of the next multibyte-character in far string 

compare two far strings with case insensitivity up to a maximum length 

increment wide character far pointer by "n" characters 

fill far string with character to a maximum length 

locate occurrence of a string within a second string 

locate last occurrence of character from a character set 

reverse a far string in place 

convert multibyte character string to wide character string 
fill far string with a character 

find number of characters at start of string which are also in a second string 
return far pointer to first character of far string not in set 
find first occurrence of string in second string 
get next token from a far string 

convert multibyte character string to wide character string 
convert far string to uppercase 
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_fmbterm 

_fmbvtop 

_fwcrtomb 

_fwcsrtombs 

_fwcstombs 

_fwctomb 

_mbscat 

_mbschr 

_mbscmp 

_mbscoll 

jnbscpy 

_mbscspn 

_mbsdec 

_mbsdup 

_mbsicmp 

_mbsinc 

mbsinit 

_mbslen 

_mbslwr 

_mbsnbcat 

_mbsnbcmp 

_mbsnbcnt 

_mbsnbcpy 

jnbsnbicmp 

_mbsnbset 

_mbsncat 

_mbsnccnt 

_mbsncmp 

_mbsncpy 

_mbsnextc 

_mbsnicmp 

_mbsninc 

_mbsnset 

_mbspbrk 

_mbsrchr 

_mbsrev 

mbsrtowcs 

_mbsset 

_mbsspn 

_mbsspnp 

_mbsstr 

_mbstok 

mbstowcs 

_mbsupr 

_mbterm 

_mbvtop 

wcrtomb 

wcsrtombs 

wcstombs 

wctob 

wctomb 


determine if next multibyte character in string is null 

store multibyte character into far string 

convert wide character to multibyte character and store 

convert far wide character string to far multibyte character string 

convert far wide character string to far multibyte character string 

convert wide character to multibyte character 

concatenate string 

locate character in string 

compare two strings 

compare two strings using "locale" collating sequence 
copy a string 

get number of string characters not from a set of characters 
returns pointer to the previous character in string 
allocate and duplicate a string 
compare two strings with case insensitivity 
return pointer to next character in string 

determine if mbstate_t object describes an initial conversion state 
string length 

convert string to lowercase 

append up to "n" bytes of string to another string 

compare up to "n" bytes in two strings 

count the number of characters in the first "n" bytes 

copy up to "n" bytes of a string 

compare up to "n" bytes in two strings with case insensitivity 

fill string with up to "n" bytes 

concatenate two strings, up to a maximum length 

count the number of characters in the first "n" bytes 

compare two strings up to maximum length 

copy a string, up to a maximum length 

return integer value of the next multibyte-character in string 

compare two strings with case insensitivity up to a maximum length 

increment wide character pointer by "n" characters 

fill string with up to "n" multibyte characters 

locate occurrence of a string within a second string 

locate last occurrence of character from a character set 

reverse a string in place 

convert multibyte character string to wide character string 
fill string with a character 

find number of characters at start of string which are also in a second string 
return pointer to first character of string not in set 
find first occurrence of string in second string 
get next token from string 

convert multibyte character string to wide character string 
convert string to uppercase 

determine if next multibyte character in string is null 
store multibyte character into string 
convert wide character to multibyte character and store 
convert wide character string to multibyte character string 
convert wide character string to multibyte character string 
return single-byte character version of wide character 
convert wide character to multibyte character 
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For related functions see the sections Conversion Functions (conversions to and from strings), Time 
Functions (formatting of dates and times), and Memory Manipulation Functions (operate on arrays without 
terminating null character). 


1.1.8 Conversion Functions 

These functions perform conversions between objects of various types and strings. The following functions 
are defined: 


at of 

atoi 

atol 

atoll 

ecvt 

fcvt 

gcvt 

itoa 

lltoa 

Itoa 

strtod 

strtol 

strtoll 

strtoul 

strtoull 

ulltoa 

ultoa 

utoa 


string to "double" 
string to "int" 
string to "long int" 
string to "long long int" 

"double" to E-format string 

"double" to F-format string 

"double" to string 

"int" to string 

"long long int" to string 

"long int" to string 

string to "double" 

string to "long int" 

string to "long long int" 

string to "unsigned long int" 

string to "unsigned long long int" 

"unsigned long long int" to string 

"unsigned long int" to string 

"unsigned int" to string 


These functions perform conversions between objects of various types and wide character strings. The 
following functions are defined: 


_itow 

_lltow 

_ltow 

_ulltow 

_ultow 

_utow 

wcstod 

wcstol 

west oil 

westoul 

wcstoull 

_wtof 

_wtoi 

_wtol 

_wtoll 


"int" to wide character string 

"long long int" to wide character string 

"long int" to wide character string 

"unsigned long long int" to wide character string 

"unsigned long int" to wide character string 

"unsigned int" to wide character string 

wide character string to "double" 

wide character string to "long int" 

wide character string to "long long int" 

wide character string to "unsigned long int" 

wide character string to "unsigned long long int" 

wide character string to "double" 

wide character string to "int" 

wide character string to "long int" 

wide character string to "long long int" 


See also tolower, towlower, _ mbctolower,toupper, towupper, _ mbctoupper,strlwr, 
_ wcslwr^ mbslwr,strupr, _ wesupr and_ mbsupr which convert the cases of characters and 
strings. 
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1.1.9 Memory Allocation Functions 

These functions allocate and de-allocate blocks of memory. 

Unless you are running your program in 32-bit protect mode, where segments have a limit of 4 gigabytes, 
the default data segment has a maximum size of 64K bytes. It may be less in a machine with insufficient 
memory or when other programs in the computer already occupy some of the memory. The _ nmal loc 
function allocates space within this area while the _ fmalloc function allocates space outside the area (if 
it is available). 

In a small data model, the malloc, calloc and realloc functions use the _ nmalloc function to 
acquire memory; in a large data model, the _ fmalloc function is used. 

It is also possible to allocate memory from a based heap using _ bmalloc. Based heaps are similar to far 
heaps in that they are located outside the normal data segment. Based pointers only store the offset portion 
of the full address, so they behave much like near pointers. The selector portion of the full address 
specifies which based heap a based pointer belongs to, and must be passed to the various based heap 
functions. 


It is important to use the appropriate memory-deallocation function to free memory blocks. The _ nf ree 
function should be used to free space acquired by the _ ncalloc^ nmalloc, or_ nrealloc functions 
The _ f f ree function should be used to free space acquired by the_ f calloc^_ fmalloc, or 
_ f realloc functions. The_ bf ree function should be used to free space acquired by the_ bcalloc, 
_ bmalloc, or_ brealloc functions. 


The free function will use the _ nfree function when the small data memory model is used; it will use 
the _ f f ree function when the large data memory model is being used. 

It should be noted that the _ fmalloc and_ nmalloc functions can both be used in either data memory 
model. The following functions are defined: 


alloca 

_b calloc 

_bexpand 

_bfree 

_bfreeseg 

_bheapseg 

_bmalloc 

Jbmsize 

_brealloc 

calloc 

_expand 

_fcalloc 

_Jexpand 

Jfree 

_fmalloc 

_fmsize 

_frealloc 

free 

_freect 

halloc 

hfree 

malloc 


allocate auto storage from stack 
allocate and zero memory from a based heap 
expand a block of memory in a based heap 
free a block of memory in a based heap 
free a based heap 
allocate a based heap 

allocate a memory block from a based heap 
return the size of a memory block 
re-allocate a memory block in a based heap 
allocate and zero memory 
expand a block of memory 

allocate and zero a memory block (outside default data segment) 
expand a block of memory (outside default data segment) 
free a block allocated using "_fmalloc" 
allocate a memory block (outside default data segment) 
return the size of a memory block 

re-allocate a memory block (outside default data segment) 
free a block allocated using "malloc", "calloc" or "realloc" 
return number of objects that can be allocated 
allocate huge array 
free huge array 

allocate a memory block (using current memory model) 
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_memavl 

return amount of available memory 

_memmax 

return largest block of memory available 

_msize 

return the size of a memory block 

_ncalloc 

allocate and zero a memory block (inside default data segment) 

_nexpand 

expand a block of memory (inside default data segment) 

_nfree 

free a block allocated using "_nmalloc" 

_nmalloc 

allocate a memory block (inside default data segment) 

_nmsize 

return the size of a memory block 

_nrealloc 

re-allocate a memory block (inside default data segment) 

realloc 

re-allocate a block of memory 

sbrk 

set allocation "break" position 

stackavail 

determine available amount of stack space 


1.1.10 Heap Functions 

These functions provide the ability to shrink and grow the heap, as well as, find heap related problems. The 
following functions are defined: 


Jieapchk 

Jbheapchk 

_fheapchk 

_nheapchk 

_heapgrow 

_fheapgrow 

_nheapgrow 

Jieapmin 

Jbheapmin 

_fheapmin 

_nheapmin 

Jieapset 

Jbheapset 

_Jheapset 

_nheapset 

Jieapshrink 

_Jheapshrink 

Jbheapshrink 

_nheapshrink 

_heapwalk 

Jbheapwalk 

_fheapwalk 

_nheapwalk 


perform consistency check on the heap 
perform consistency check on a based heap 
perform consistency check on the far heap 
perform consistency check on the near heap 
grow the heap 
grow the far heap 

grow the near heap up to its limit of 64K 

shrink the heap as small as possible 

shrink a based heap as small as possible 

shrink the far heap as small as possible 

shrink the near heap as small as possible 

fill unallocated sections of heap with pattern 

fill unallocated sections of based heap with pattern 

fill unallocated sections of far heap with pattern 

fill unallocated sections of near heap with pattern 

shrink the heap as small as possible 

shrink the far heap as small as possible 

shrink a based heap as small as possible 

shrink the near heap as small as possible 

walk through each entry in the heap 

walk through each entry in a based heap 

walk through each entry in the far heap 

walk through each entry in the near heap 


1.1.11 Math Functions 

These functions operate with objects of type double, also known as floating-point numbers. The Intel 
8087 processor (and its successor chips) is commonly used to implement floating-point operations on 
personal computers. Functions ending in "87" pertain to this specific hardware and should be isolated in 
programs when portability is a consideration. The following functions are defined: 

abs absolute value of an object of type "int" 

acos arccosine 

acosh inverse hyperbolic cosine 
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asin 

asinh 

atan 

atan2 

atanh 

bessel 

cabs 

cbrt 

ceil 

__clear87 

_control87 

copysign 

cos 

cosh 

div 

erf 

erfc 

exp 

exp2 

expml 

fabs 

fdim 

_Jinite 

floor 

fma 

fmax 

fmin 

fmod 

_fpreset 

frexp 

hypot 

ilogb 

imaxabs 

imaxdiv 

JO 

Jl 

jn 

labs 

Idexp 

Idiv 

Igamma 

lgamma_r 

log 

loglO 

loglp 

log2 

logb 

matherr 

max 

min 

modf 

nearbyint 

nextafter 

pow 


arcsine 

inverse hyperbolic sine 

arctangent of one argument 

arctangent of two arguments 

inverse hyperbolic tangent 

bessel functions jO, jl, jn, yO, yl, and yn 

absolute value of complex number 

cubed root of a number 

ceiling function 

clears floating-point status 

sets new floating-point control word 

copies the sign of one number to another 

cosine 

hyperbolic cosine 

compute quotient, remainder from division of an "int" object 

computes the error function 

computes the complementary error function 

exponential function 

two raised to a value 

exponential of a number minus one 

absolute value of "double" 

positive difference of two numbers 

determines whether floating-point value is valid 

floor function 

fused multiply-add 

returns larger of two numbers 

returns smaller of two numbers 

modulus function 

initializes for floating-point operations 

fractional exponent 

compute hypotenuse 

retrieve the exponent of a "double" 

get quotient, remainder from division of object of maximum-size integer type 

absolute value of an object of maximum-size integer type 

return Bessel functions of the first kind (described under "bessel Functions") 

return Bessel functions of the first kind (described under "bessel Functions") 

return Bessel functions of the first kind (described under "bessel Functions") 

absolute value of an object of type "long int" 

multiply by a power of two 

get quotient, remainder from division of object of type "long int" 
natural logarithm of the absolute value of the Gamma function 
natural logarithm of the absolute value of the Gamma function (thread-safe) 
natural logarithm 
logarithm, base 10 

natural logarithm of one plus the argument 
logarithm, base 2 

retrieve the exponent of a "double" 

handles error from math functions 

return maximum of two arguments 

return minimum of two arguments 

get integral, fractional parts of "double" 

returns nearest integer based on rounding mode 

returns next machine-representable floating point value 

raise to power 
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rand 

remainder 

rint 

round 

scalbn 

_set_matherr 

sin 

sink 

sqrt 

srand 

_status87 

tan 

tank 

tgamma 

trunc 

yO 

yi 

yn 


random integer 

retrieves the remainder of a division operation 

returns nearest integer based on rounding mode 

rounds to the nearest integer 

compute a "double" times two raised to a power 

specify a math error handler 

sine 

hyperbolic sine 
square root 

set starting point for generation of random numbers using "rand" function 

gets floating-point status 

tangent 

hyperbolic tangent 
compute the Gamma function 
truncate a floating point value 

return Bessel functions of the second kind (described under "bessel") 
return Bessel functions of the second kind (described under "bessel") 
return Bessel functions of the second kind (described under "bessel") 


1.1.12 Searching Functions 

These functions provide searching and sorting capabilities. The following functions are defined: 

bsearch find a data item in an array using binary search 

Ifind find a data item in an array using linear search 

Isearch linear search array, add item if not found 

qsort sort an array 


1.1.13 Time Functions 


These functions are concerned with dates and times. The following functions are defined: 


asctime 

_asctime 

_wasctime 

_ wasctime 

clock 

dime 

_ctime 

_wctime 

_ wctime 

dijftime 

ftime 

gmtime 

_gmtime 

localtime 

_localtime 

mktime 

_strdate 

strftime 

wcsftime 

_wstrftime_ms 


makes time string from time structure 

makes time string from time structure 

makes time string from time structure 

makes time string from time structure 

gets time since program start 

gets calendar time string 

gets calendar time string 

gets calendar time string 

gets calendar time string 

calculate difference between two times 

returns the current time in a "timeb" structure 

convert calendar time to Coordinated Universal Time (UTC) 

convert calendar time to Coordinated Universal Time (UTC) 

convert calendar time to local time 

convert calendar time to local time 

make calendar time from local time 

return date in buffer 

format date and time 

format date and time 

format date and time 
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_strtime 

jwstrtime 

time 

tzset 

_wstrdate 


return time in buffer 
return time in buffer 
get current calendar time 

set global variables to reflect the local time zone 
return date in buffer 


1.1.14 Variable-length Argument Lists 

Variable-length argument lists are used when a function does not have a fixed number of arguments. These 
macros provide the capability to access these arguments. The following functions are defined: 

va_arg get next variable argument 

va_end complete access of variable arguments 

va_start start access of variable arguments 


1.1.15 Stream I/O Functions 

A stream is the name given to a file or device which has been opened for data transmission. When a stteam 
is opened, a pointer to a FILE sttucture is returned. This pointer is used to reference the stream when other 
functions are subsequently invoked. 

There are two modes by which data can be Uansmitted: 

binary Data is transmitted unchanged. 

text On input, carriage-return characters are removed before following linefeed characters. On 

output, carriage-return characters are inserted before linefeed characters. 

These modes are required since text files are stored with the two characters delimiting a line of text, while 
the C convention is for only the linefeed character to delimit a text line. 

When a program begins execution, there are a number of streams already open for use: 

stdin Standard Input: input from the console 

stdout Standard Output: output to the console 

stderr Standard Error: output to the console (used for error messages) 

stdaux Standard Auxiliary: auxiliary port, available for use by a program (not available in some 

Windows platforms) 

stdprn Standard Printer: available for use by a program (not available in some Windows 

platforms) 

These standard streams may be re-directed by use of the f reopen function. 

See also the section File Manipulation Functions for other functions which operate upon files. 

The functions referenced in the section Operating System I/O Functions may also be invoked (use the 
f ileno function to obtain the file handle). Since the stream functions may buffer input and output, these 
functions should be used with caution to avoid unexpected results. 
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The following functions are defined: 


clearerr 

fclose 

fcloseall 

fdopen 

feof 

fterror 

Jflush 

fgetc 

_Jgetchar 

fgetpos 

ft'gets 

flushall 

fopen 

fprintf 

fputc 

_Jputchar 

fputs 

fread 

freopen 

fscanf 

fseek 

fsetpos 

_fsopen 

ft ell 

fwrite 

getc 

getchar 

gets 

_getw 

perror 

printf 

putc 

putchar 

puts 

_J)UtW 

rewind 

scanf 

setbuf 

setvbuf 

tmpfile 

ungetc 

vfprintf 

vfscanf 

vprintf 

vscanf 


clear end-of-file and error indicators for stream 

close stream 

close all open streams 

open stream, given handle 

test for end of file 

test for file error 

flush output buffer 

get next character from file 

equivalent to "fgetc" with the argument "stdin" 

get current file position 

get a string 

flush output buffers for all streams 
open a stream 
format output 
write a character 

write a character to the "stdout" stream 

write a string 

read a number of objects 

re-opens a stream 

scan input according to format 

set current file position, relative 

set current file position, absolute 

open a shared stream 

get current file position 

write a number of objects 

read character 

get next character from "stdin" 

get string from "stdin" 

read int from stream file 

write error message to "stderr" stream 

format output to "stdout" 

write character to file 

write character to "stdout" 

write string to "stdout" 

write int to stream file 

position to start of file 

scan input from "stdin" under format control 

set buffer 

set buffering 

create temporary file 

push character back on input stream 

same as "fprintf" but with variable arguments 

same as "fscanf' but with variable arguments 

same as "printf" but with variable arguments 

same as "scanf" but with variable arguments 


See the section Directory Functions for functions which are related to directories. 
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1.1.16 Wide Character Stream I/O Functions 

The previous section describes some general aspects of stream input/output. The following describes 
functions dealing with streams containing multibyte character sequences. 

After a stream is associated with an external file, but before any operations are performed on it, the stream 
is without orientation. Once a wide character input/output function has been applied to a stream without 
orientation, the stream becomes wide-oriented. Similarly, once a byte input/output function has been 
applied to a stream without orientation, the stream becomes byte-oriented. Only a successful call to 
f reopen can otherwise alter the orientation of a stream (it removes any orientation). You cannot mix 
byte input/output functions and wide character input/output functions on the same stream. 

A file positioning function can cause the next wide character output function to overwrite a partial 
multibyte character. This can lead to the subsequent reading of a stream of multibyte characters containing 
an invalid character. 


When multibyte characters are read from a stream, they are converted to wide characters. Similarly, when 
wide characters are written to a stream, they are converted to multibyte characters. 

The following functions are defined: 


fgetwc 

_fgetwchar 

fgetws 

fprintf 

fputwc 

Jputwchar 

fputws 

fscanf 

fwprintf 

fwscanf 

getwc 

getwchar 

_getws 

putwc 

putwchar 

_putws 

ungetwc 

vfwprintf 

vfwscanf 

vswprintf 

vwprintf 

vwscanf 

_wfdopen 

_wfopen 

_wfreopen 

_wfsopen 

_wperror 

wprintf 

wscanf 


get next wide character from file 

equivalent to "fgetwc" with the argument "stdin" 

get a wide character string 

"C" and "S" extensions to the format specifier 

write a wide character 

write a character to the "stdout" stream 

write a wide character string 

"C" and "S" extensions to the format specifier 

formatted wide character output 

scan wide character input according to format 

read wide character 

get next wide character from "stdin" 

get wide character string from "stdin" 

write wide character to file 

write wide character to "stdout" 

write wide character string to "stdout" 

push wide character back on input stream 

same as "fwprintf" but with variable arguments 

same as "fwscanf" but with variable arguments 

same as "swprintf" but with variable arguments 

same as "wprintf" but with variable arguments 

same as "wscanf" but with variable arguments 

open stream, given handle using a wide character "mode" 

open a stream using wide character arguments 

re-opens a stream using wide character arguments 

open a shared stream using wide character arguments 

write error message to "stderr" stream 

format wide character output to "stdout" 

scan wide character input from "stdin" under format control 


See the section Directory Functions for functions which are related to directories. 
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1.1.17 Process Primitive Functions 

These functions deal with process creation, execution and termination, signal handling, and timer 
operations. 

When a new process is started, it may replace the existing process 

• P_ OVERLAY is specified with thespawn . . . functions 

• the exec . . . routines are invoked 

or the existing process may be suspended while the new process executes (control continues at the point 
following the place where the new process was started) 

• P_ WAIT is specified with thespawn. . . functions 

• system is used 

The following functions are defined: 


abort 

immediate termination of process, return code 3 

atexit 

register exit routine 

_beginthread 

start a new thread of execution 

cwait 

wait for a child process to terminate 

_cwait 

wait for a child process to terminate 

delay 

delay for number of milliseconds 

_endthread 

end the current thread 

execl 

chain to program 

_execl 

chain to program 

execle 

chain to program, pass environment 

_execle 

chain to program, pass environment 

execlp 

chain to program 

_execlp 

chain to program 

execlpe 

chain to program, pass environment 

_execlpe 

chain to program, pass environment 

execv 

chain to program 

_execv 

chain to program 

execve 

chain to program, pass environment 

_execve 

chain to program, pass environment 

execvp 

chain to program 

_execvp 

chain to program 

execvpe 

chain to program, pass environment 

_execvpe 

chain to program, pass environment 

exit 

exit process, set return code 

_Exit 

exit process, set return code 

_exit 

exit process, set return code 

onexit 

register exit routine 

raise 

signal an exceptional condition 

signal 

set handling for exceptional condition 

sleep 

delay for number of seconds 

spawnl 

create process 

_spawnl 

create process 

spawnle 

create process, set environment 
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_spawnle 

create process, set environment 

spawnlp 

create process 

_spaw nip 

create process 

spawnlpe 

create process, set environment 

_spawnlpe 

create process, set environment 

spawnv 

create process 

_spawnv 

create process 

spawnve 

create process, set environment 

_spawnve 

create process, set environment 

spawnvp 

create process 

_spawnvp 

create process 

spawnvpe 

create process, set environment 

_spawnvpe 

create process, set environment 

system 

execute system command 

wait 

wait for any child process to terminate 

_wexecl 

chain to program 

_wexecle 

chain to program, pass environment 

_wexeclp 

chain to program 

_wexeclpe 

chain to program, pass environment 

_wexecv 

chain to program 

_wexecve 

chain to program, pass environment 

_wexecvp 

chain to program 

_wexecvpe 

chain to program, pass environment 

_wspawnl 

create process 

_wspawnle 

create process, set environment 

_w spawnlp 

create process 

_wspawnlpe 

create process, set environment 

_w spawnv 

create process 

_w spawnve 

create process, set environment 

_w spawnvp 

create process 

__w spawnvpe 

create process, set environment 

_wsystem 

execute system command 

There are eight spawn , 

. . . and exec. . . functions each. The " is one to three letters: 

• "1" or "v" (one is required) to indicate the way the process parameters are passed 

• "p" (optional) to indicate whether the PATH environment variable is searched to locate the program 

for the process 


• "e" (optional) to indicate that the environment variables are being passed 

18 Process Environment 

These functions deal with process identification, process groups, system identification, system time, 
environment variables, and terminal identification. The following functions are defined: 

_bgetcmd 

get command line 

clearenv 

delete environment variables 

getcmd 

get command line 

getegid 

get effective group ID of calling process 

getenv 

get environment variable value 

geteuid 

get effective user ID 
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getgid 

getpgrp 

getpid 

_getpid 

getppid 

gettid 

getuid 

isatty 

putenv 

_searchenv 

setenv 

sysconf 

ttyname 

_wgetenv 

_wputenv 

_wsearchenv 

_wsetenv 


get real group ID of calling process 
get process group ID of calling process 
get process ID of calling process 
get process ID of calling process 
get parent process ID of calling process 
get thread ID of current thread 
get real user ID 

determine if file descriptor associated with a terminal 

add, change or delete environment variable 

search for a file in list of directories 

add, change or delete environment variable 

determine value of configurable system limit or option 

return pointer to string containing pathname of terminal associated with file 

descriptor argument 

get environment variable value 

add, change or delete environment variable 

search for a file in list of directories 

add, change or delete environment variable 


1.1.19 Directory Functions 

These functions pertain to directory manipulation. The following functions are defined: 


chdir 

closedir 

getcwd 

_getdcwd 

mkdir 

opendir 

readdir 

rewinddir 

rmdir 

_w chdir 

_wclosedir 

_wgetcwd 

_wgetdcwd 

_wmkdir 

_wopendir 

_wreaddir 

_wrewinddir 

_wnndir 


change current working directory 

close opened directory file 

get current working directory 

get current directory on drive 

make a new directory 

open directory file 

read file name from directory 

reset position of directory stream 

remove a directory 

change current working directory 

close opened directory file 

get current working directory 

get current directory on drive 

make a new directory 

open directory file 

read file name from directory 

reset position of directory stream 

remove a directory 


1.1.20 Operating System I/O Functions 

These functions operate at the operating-system level and are included for compatibility with other C 
implementations. It is recommended that the functions used in the section File Manipulation Functions be 
used for new programs, as these functions are defined portably and are part of the ISO/ANSI standard for 
the C language. 

The functions in this section reference opened files and devices using a file handle which is returned when 
the file is opened. The file handle is passed to the other functions. 
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The following functions are defined: 


chsize 

close 

_commit 

creat 

dup 

dup2 

eof 

filelength 

fileno 

fstat 

fsync 

Jidopen 

lock 

locking 

Iseek 

open 

_os_handle 

_pclose 

pclose 

_popen 

popen 

read 

setmode 

sopen 

tell 

umask 

unlink 

unlock 

write 

_wcreat 

_wopen 

_wpopen 

_wsopen 

_wunlink 


change the size of a file 
close file 

commit changes to disk 
create a file 

duplicate file handle, get unused handle number 
duplicate file handle, supply new handle number 
test for end of file 
get file size 

get file handle for stream file 
get file status 

write queued file and filesystem data to disk 

get POSIX handle from OS handle 

lock a section of a file 

lock/unlock a section of a file 

set current file position 

open a file 

get OS handle from POSIX handle 

close a pipe 

close a pipe 

open a pipe 

open a pipe 

read a record 

set file mode 

open a file for shared access 
get current file position 
set file permission mask 
delete a file 

unlock a section of a file 

write a record 

create a file 

open a file 

open a pipe 

open a file for shared access 
delete a file 


1.1.21 File Manipulation Functions 

These functions operate directly with files. The following functions are defined: 


access 

chmod 

Istat 

remove 

rename 

stat 

tmpnam 

utime 

_waccess 

_wchmod 

_wremove 

_wrename 


test file or directory for mode of access 

change permissions for a file 

get file status 

delete a file 

rename a file 

get file status 

create name for temporary file 

set modification time for a file 

test file or directory for mode of access 

change permissions for a file 

delete a file 

rename a file 
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_wstat get file status 

_wtmpnam create name for temporary file 

_wutime set modification time for a file 

1.1.22 Console I/O Functions 

These functions provide the capability to read and write data from the console. Data is read or written 
without any special initialization (devices are not opened or closed), since the functions operate at the 
hardware level. 

The following functions are defined: 


cgets 

get a string from the console 

cprintf 

print formatted string to the console 

cputs 

write a string to the console 

cscanf 

scan formatted data from the console 

getch 

get character from console, no echo 

getche 

get character from console, echo it 

kb hit 

test if keystroke available 

putch 

write a character to the console 

ungetch 

push back next character from console 


1.1.23 Default Windowing Functions 

These functions provide the capability to manipulate attributes of various windows created by Open 
Watcom’s default windowing system for Microsoft Windows and IBM OS/2. 

The following functions are defined: 


dwDeleteOnClose 

dwSetAboutDlg 

dwSetAppTitle 

dwSetConTitle 

dwShutDown 

dwYield 


delete console window upon close 
set about dialogue box title and contents 
set main window’s application title 
set console window’s title 
shut down default windowing system 
yield control to other processes 


1.1.24 BIOS Functions 


This set of functions allows access to services provided by the BIOS. The following functions are defined: 


_bios_disk 

bios_equiplist 

bios_keybrd 

bios_memsize 

bios _printer 

_bios_serialcom 

biosJtimeofday 


provide disk access functions 
determine equipment list 
provide low-level keyboard access 
determine amount of system board memory 
provide access to printer services 
provide access to serial services 
get and set system clock 
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1.1.25 DOS-Specific Functions 

These functions provide the capability to invoke DOS functions directly from a program. The following 
functions are defined: 


bdos 

dosexterr 

_dos_allocmem 

_dos_close 

_dos_commit 

_dos_creat 

_dos_creatnew 

_dos_findclose 

_dos_findfirst 

_dos_findnext 

_dos_freemem 

_dos_getdate 

_dos_getdiskfree 

_dos_getdrive 

_dos_getfileattr 

_dos_getftime 

_dos_gettime 

_dos_getvect 

_dos_keep 

_dos_open 

_dos_read 

_dos_setblock 

_dos_setdate 

_dos_setdrive 

_dos_setfileattr 

_dos_setftime 

_dos_settime 

_dos_set\’ect 

_dos_write 

intdos 

intdosx 

_wdos_fmdclose 

_wdos_findfirst 

_wdos_findnext 


DOS call (short form) 

extract DOS error information 

allocate a block of memory 

close a file 

flush buffers to disk 

create a file 

create a new file 

close find file matching 

find first file matching a specified pattern 

find the next file matching a specified pattern 

free a block of memory 

get current system date 

get information about disk 

get the current drive 

get file attributes 

get file’s last modification time 

get the current system time 

get contents of interrupt vector 

install a terminate-and-stay-resident program 

open a file 

read data from a file 

change the size of allocated block 

change current system date 

change the current default drive 

set the attributes of a file 

set a file's last modification time 

set the current system time 

set an interrupt vector 

write data to a file 

cause DOS interrupt 

cause DOS interrupt, with segment registers 
close find file matching 
find first file matching a specified pattern 
find the next file matching a specified pattern 


1.1.26 Intel 80x86 Architecture-Specific Functions 

These functions provide the capability to invoke Intel 80x86 processor-related functions directly from a 
program. Functions that apply to the Intel 8086 CPU apply to that family including the 80286, 80386, 
80486 and Pentium processors. The following functions are defined: 


_chain_in.tr 

_disable 

_enable 

FP_OFF 

FP_SEG 

hip 


chain to the previous interrupt handler 

disable interrupts 

enable interrupts 

get offset part of far pointer 

get segment part of far pointer 

get one byte from hardware port 
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inpw 

get two bytes (one word) from hardware port 

int386 

cause 386/486/Pentium CPU interrupt 

int386x 

cause 386/486/Pentium CPU interrupt, with segment registers 

int86 

cause 8086 CPU interrupt 

int86x 

cause 8086 CPU interrupt, with segment registers 

intr 

cause 8086 CPU interrupt, with segment registers 

MK_FP 

make a far pointer from the segment and offset values 

nosound 

turn off the speaker 

outp 

write one byte to hardware port 

outpw 

write two bytes (one word) to hardware port 

segread 

read segment registers 

sound 

turn on the speaker at specified frequency 


1.1.27 Intel Pentium Multimedia Extension Functions 


This set of functions allows access to Intel Architecture Multimedia Extensions (MMX). These functions 
are implemented as in-line intrinsic functions. The general format for most functions is: 

mm_ result = mm_ function ( mm_ operandl, mm_ operand2 ) ; 


These functions provide a simple model for use of Intel Multimedia Extension (MMX). More advanced 
use of MMX can be implemented in much the same way that these functions are implemented. See the 
<mmintrin . h> header file for examples. The following functions are defined: 


m_empty 
m_from_int 
m _packssdw 

m _packsswb 

m_packuswb 

m jpaddb 

m_paddd 

m_paddsb 

m_paddsw 

m_paddusb 

m_paddusw 

m_paddw 

m_pand 

m_pandn 

m_pcmpeqb 

pijpcmpeqd 

m_pcmpeqw 

pijpcmpgtb 

m_pcmpgtd 

m_pcmpgtw 

pi _pmaddwd 

pi_pmulhw 

m_pmullw 

m _por 
m _pslld 
pijpslldi 


empty multimedia state 

form 64-bit MM value from unsigned 32-bit integer value 

pack and saturate 32-bit double-words from two MM elements into signed 16-bit 
words 

pack and saturate 16-bit words from two MM elements into signed bytes 

pack and saturate signed 16-bit words from two MM elements into unsigned bytes 

add packed bytes 

add packed 32-bit double-words 

add packed signed bytes with saturation 

add packed signed 16-bit words with saturation 

add packed unsigned bytes with saturation 

add packed unsigned 16-bit words with saturation 

add packed 16-bit words 

AND 64 bits of two MM elements 

invert the 64 bits in MM element, then AND 64 bits from second MM element 

compare packed bytes for equality 

compare packed 32-bit double-words for equality 

compare packed 16-bit words for equality 

compare packed bytes for greater than relationship 

compare packed 32-bit double-words for greater than relationship 

compare packed 16-bit words for greater than relationship 

multiply packed 16-bit words, then add 32-bit results pair-wise 

multiply the packed 16-bit words of two MM elements, then store high-order 16 

bits of results 

multiply the packed 16-bit words of two MM elements, then store low-order 16 
bits of results 

OR 64 bits of two MM elements 

shift left each 32-bit double-word by amount specified in second MM element 
shift left each 32-bit double-word by amount specified in constant value 
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_m_psllq shift left each 64-bit quad-word by amount specified in second MM element 

_m_psllqi shift left each 64-bit quad-word by amount specified in constant value 

_m_psllw shift left each 16-bit word by amount specified in second MM element 

_m_psllwi shift left each 16-bit word by amount specified in constant value 

_m_psrad shift right (with sign propagation) each 32-bit double-word by amount specified in 

second MM element 

_m_psradi shift right (with sign propagation) each 32-bit double-word by amount specified in 

constant value 

_m_psraw shift right (with sign propagation) each 16-bit word by amount specified in second 

MM element 

_m_psrawi shift right (with sign propagation) each 16-bit word by amount specified in 

constant value 

_m_psrld shift right (with zero fill) each 32-bit double-word by an amount specified in 

second MM element 

_m_psrldi shift right (with zero fill) each 32-bit double-word by an amount specified in 

constant value 

_m_psrlq shift right (with zero fill) each 64-bit quad-word by an amount specified in second 

MM element 

_m_psrlqi shift right (with zero fill) each 64-bit quad-word by an amount specified in 

constant value 

_m_psrlw shift right (with zero fill) each 16-bit word by an amount specified in second MM 

element 

_m_psrlwi shift right (with zero fill) each 16-bit word by an amount specified in constant 

value 

_m_psubb subtract packed bytes in MM element from second MM element 

_m_psubd subtract packed 32-bit dwords in MM element from second MM element 

_m_psubsb subtract packed signed bytes in MM element from second MM element with 

saturation 

_m_psubsw subtract packed signed 16-bit words in MM element from second MM element 

with saturation 

_m_psubusb subtract packed unsigned bytes in MM element from second MM element with 

saturation 

_m_psubusxv subtract packed unsigned 16-bit words in MM element from second MM element 

with saturation 

_m_psubw subtract packed 16-bit words in MM element from second MM element 

_m_punpckhbw interleave bytes from the high halves of two MM elements 

_m_punpckhdq interleave 32-bit double-words from the high halves of two MM elements 

_m_punpckhwd interleave 16-bit words from the high halves of two MM elements 

jn_punpcklbw interleave bytes from the low halves of two MM elements 

_m_punpckldq interleave 32-bit double-words from the low halves of two MM elements 

_m_punpcklwd interleave 16-bit words from the low halves of two MM elements 

_m_pxor XOR 64 bits from two MM elements 

_m_to_int retrieve low-order 32 bits from MM value 

1.1.28 Miscellaneous Functions 

The following functions are defined: 

assert test an assertion and output a string upon failure 

_fullpath return full path specification for file 

_getmbcp get current multibyte code page 

getopt a command-line parser that can be used by applications that follow guidelines 

outlined in the Single UNIX Specification 
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_harderr 

_hardresume 

localeconv 

longjmp 

_lrotl 

_lrotr 

main 

offsetof 

_rotl 

_rotr 

setjmp 

_makepath 

setlocale 

_setmbcp 

_splitpath 

_splitpath2 

_wfullpath 

_wmakepath 

_wsetlocale 

_wsplitpath 

_wsplitpath2 


critical error handler 

critical error handler resume 

obtain locale specific conversion information 

return and restore environment saved by "setjmp" 

rotate an "unsigned long" left 

rotate an "unsigned long" right 

the main program (user written) 

get offset of field in structure 

rotate an "unsigned int" left 

rotate an "unsigned int" right 

save environment for use with "longjmp" function 

make a full filename from specified components 

set locale category 

set current multibyte code page 

split a filename into its components 

split a filename into its components 

return full path specification for file 

make a full filename from specified components 

set locale category 

split a filename into its components 

split a filename into its components 


1.1.29 DOS LFN aware Functions 

These functions deal with DOS Long File Name if an application is compiled with 

-D_WATCOM_LFN_option and DOS LFN support is available on host system. The following 

functions are defined: 


access 

chdir 

chmod 

creat 

_dos_creat 

_dos_creatnew 

_dos_findfirst 

_dos_getfi leattr 

_dos_open 

_dos_setfileattr 

_findfirst 

_fullpath 

getcwd 

_getdcwd 

Istat 

mkdir 

open 

opendir 

remove 

rename 

rmdir 

sopen 

stat 

tmpnam 

unlink 


test file or directory for mode of access 
change current working directory 
change permissions for a file 
create a file 
create a file 
create a new file 

find first file matching a specified pattern 
get file attributes 
open a file 

set the atttibutes of a file 

find first file matching a specified pattern 

return full path specification for file 

get current working directory 

get current directory on drive 

get file status 

make a new directory 

open a file 

open directory file 

delete a file 

rename a file 

remove a directory 

open a file for shared access 

get file status 

create name for temporary file 
delete a file 
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utime 

_waccess 

_wchdir 

_wchmod 

_wcreat 

_wdos^fmdfirst 

_wfindfirst 

_wfullpath 

_wgetcwd 

_wgetdcwd 

_wmkdir 

_wopen 

_wopendir 

_wremove 

_wrename 

_wrmdir 

_wsopen 

_wstat 

_wtmpnam 

_wunlink 

_wutime 


set modification time for a file 
test file or directory for mode of access 
change current working directory 
change permissions for a file 
create a file 

find first file matching a specified pattern 

find first file matching a specified pattern 

return full path specification for file 

get current working directory 

get current directory on drive 

make a new directory 

open a file 

open directory file 

delete a file 

rename a file 

remove a directory 

open a file for shared access 

get file status 

create name for temporary file 
delete a file 

set modification time for a file 


1.2 Header Files 


The following header files are supplied with the C library. As has been previously noted, when a library 
function is referenced in a source file, the related header files (shown in the synopsis for that function) 
should be included into that source file. The header files provide the proper declarations for the functions 
and for the number and types of arguments used with them. Constant values used in conjunction with the 
functions are also declared. The files can be included multiple times and in any order. 

1.2.1 Header Files in /watcom/h 

The following header files are provided with the software. The header files that are located in the 
\WATCOM\H directory are described first. 

assert.h This ISO C90 header file is required when an assert macro is used. These assertions 

will be ignored when the identifier NDEBUG is defined. 

bios.li This header file declares all BIOS related functions. 

conio.h This header file declares console and Intel 80x86 port input/output functions. 

ctype.h This ISO C90 header file declares functions that perform character classification and case 

conversion operations. Similar functions for wide characters are declared in <wctype.h>. 

direct.h This header file declares functions related to directories and the type DIR which describes 

an entry in a directory. 

dos.h This header file declares functions that interact with DOS. It includes the definitions of the 

FP_ OFF,FP_ SEG andMK_ FP macros, and for the following structures and unions: 
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env.h 

errno.h 

fcntl.h 

fenv.h 

float.h 

fnmatch.h 
graph, h 

inttypes.li 


io.h 

limits.h 

locale, h 

malloc.h 

math.h 


DOSERROR describes the DOS error information. 

REGS describes the CPU registers for Intel 8086 family. 

SREGS describes the segment registers for the Intel 8086 family. 

REGPACK describes the CPU registers and segment registers for Intel 8086 family. 

INTPACK describes the input parameter to an "interrupt" function. 

This POSIX header file declares environment string functions. 

This ISO C90 header file provides the extern declaration for error variable errno and 
provides the symbolic names for error codes that can be placed in the error variable. 

This POSIX header file defines the flags used by the open and sopen functions. The 
function declarations for these functions are found in the <io. h> header file. 


This ISO C99 header file defines several types and declares several functions that give 
access to the floating point environment. These functions can be used to control status 
flags and control modes in the floating point processor. 

This ISO C90 header file declares constants related to floating-point numbers, declarations 
for low-level floating-point functions, and the declaration of the floating-point exception 
codes. 


This header file declares the pattern matching function f nmatch 

This header file contains structure definitions and function declarations for the Open 
Watcom C Graphics library functions. 

This ISO C99 header file includes <stdint.h> and expands on it by definition macros for 
printing and scanning specific sized integer types. This header also declares several 
functions for manipulating maximum sized integers. 

Note that the format macros are not visible in C++ programs unless the macro 
_STDC_ FORMAT_ MACROS is defined. 

This header file declares functions that perform input/output operations at the operating 
system level. These functions use file handles to reference files or devices. The function 
f stat is declared in the <sys/stat. h> header file. 

This ISO C90 header file contains constant declarations for limits or boundary values for 
ranges of integers and characters. 

This ISO C90 header file contains declarations for the categories (LC. . .) of locales 
which can be selected using the setlocale function which is also declared. 

This header file declares the memory allocation and deallocation functions. 

This ISO/ANSI header file declares the mathematical functions (which operate with 
floating-point numbers) and the structures: 
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mmintrin.h 


process.h 

search.h 
setjmp.h 
share.h 
signal.li 
stdarg.h 
stdbool.h 


stddef.h 


stdint.h 


stdio.h 


exception describes the exception structure passed to the matherr function; 
symbolic constants for the types of exceptions are included 

complex declares a complex number 

This header file declares functions that interact with the Intel Architecture Multimedia 
Extensions. It defines the datatype used to store multimedia values: 

_ m64 describes the 64-bit multimedia data element. Note; the underlying 

implementation details of this datatype are subject to change. Other 
compilers may implement a similar datatype in a different manner. 

It also contains prototypes for multimedia functions and pragmas for the in-line generation 
of code that operates on multimedia registers. 

This header file declares the spawn . . . functions, the exec. . . functions, and the 
system function. The file also contains declarations for the constants P_ WAIT, 

P_ NOWAIT,P_ NOWAITO, andP_ OVERLAY. 

This header file declares the functions If ind and 1 search 

This ISO C90 header file declares the set jmp and long jmp functions. 

This header file defines constants for shared access to files using the sopen function. 

This ISO C90 header file declares the signal and raise functions. 

This ISO C90 header file defines the macros which handle variable argument lists. 

This ISO C99 header file defines the macro bool and the macros true and false for 
use in C programs. If this header is included in a C++ program there is no effect. The C++ 
reserved words will not be redefined. However the definition of bool , true , and 
false used in a C program will be compatible with their C++ counterparts. In particular, 
a C function declared as taking a bool parameter and a structure containing a bool 
member can both be shared between C and C++ without error. 

This ISO C90 header file defines a few popular constants and types including NULL (null 
pointer), size_ t (unsigned size of an object), andptrdif f_ t (difference between two 
pointers). It also contains a declaration for the of f setof macro. 

This ISO C99 header file defines numerous type names for integers of various sizes. Such 
type names provide a reasonably portable way to refer to integers with a specific number of 
bits. This header file also defines macros that describe the minimum and maximum values 
for these types (similar to the macros in limits.h), and macros for writing integer constants 
with specific sized types. 

Note that in C++ programs the limit macros are not visible unless the macro 

_STDC_ LIMIT_ MACROS is defined. Similarly the constant writing macros are not 

visible unless the macro_ STDC_ CONSTANT_ MACROS is defined. 

This ISO C90 header file declares the standard input/output functions. Files, devices and 
directories are referenced using pointers to objects of the type FILE. 
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stdlib.h This ISO C90 header file declares many standard functions excluding those declared in 

other header files discussed in this section. 

string.li This ISO C90 header file declares functions that manipulate strings or blocks of memory. 

time.h This ISO/ANSI header file declares functions related to times and dates and defines the 

structure struct tm. 

varargs.h This UNIX System V header file provides an alternate way of handling variable argument 
lists. The equivalent ISO/ANSI header file is <stdarg.h>. 

wcliar.h This ISO C99 header file defines several data types including wchar_ t,size_ t, 

mbstate_ t (an object that can hold conversion state information necessary to convert 
between multibyte characters and wide characters), wctype_ t (a scalar type that can hold 
values which represent locale-specific character classification), and wint_ t which is an 
integral type that can hold any wchar_ t value as well asWEOF (a character that is not in 
the set of "wchar_t" characters and that is used to indicate end-of-file on an input stream). 
The functions that are declared in this header file are grouped as follows: 

• Wide character classification and case conversion. 

• Input and output of wide characters, or multibyte characters, or both. 

• Wide string numeric conversion. 

• Wide string manipulation. 

• Wide string data and time conversion. 

• Conversion between multibyte and wide character sequences. 

wctype.h This ISO C99 header file declares functions that perform characater classification and case 
conversion operations on wide characters. Similar functions for ordinary characters are 
declared in <ctype.h>. 

1.2.2 Header Files in Awatcom/h/sys 

The following header files are present in the sys subdirectory. Their presence in this directory indicates 

that they are system-dependent header files. 

sys/locking.h This header file contains the manifest constants used by the locking function. 

sys/stat.h This POSIX header file contains the declarations pertaining to file status, including 
definitions for the f stat and stat functions and for the structure: 

stilt describes the information obtained for a directory, file or device 

sys/timeb.h This header file describes the timeb structure used in conjunction with the ftime 
function. 

sys/types.h This POSIX header file contains declarations for the types used by system-level calls to 
obtain file status or time information. 
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sys/utime.h This POSIX header file contains a declaration for the utime function and for the 
structured type utimbuf used by it. 

1.3 Global Data 

Certain data items are used by the Open Watcom C/C++ run-time library and may be inspected (or changed 
in some cases) by a program. The defined items are: 

jnnblksiz Prototype in <stdlib.h>. 

This unsigned int data item contains the increment by which the "break" pointer for 
memory allocation will be advanced when there is no freed block large enough to satisfy a 
request to allocate a block of memory. This value may be changed by a program at any 
time. 

_ argc Prototype in <stdlib.h>. 

This int item contains the number of arguments passed to main. 

_ argv Prototype in <stdlib.h>. 

This char * * item contains a pointer to a vector containing the actual arguments passed 
to main. 

daylight Prototype in <time . h> . 

This unsigned int has a value of one when daylight saving time is supported in this 
locale and zero otherwise. Whenever a time function is called, the tzset function is 
called to set the value of the variable. The value will be determined from the value of the 
TZ environment variable. 

_doserrno Prototype in <stdlib.h>. 

This int item contains the actual error code returned when a DOS, Windows or OS/2 
function fails. 

environ Prototype in <stdlib. h> . 

This char * *_near data item is a pointer to an array of character pointers to the 

environment strings. 

errno Prototype in <errno . h> . 

This int item contains the number of the last error that was detected. The run-time library 
never resets errno to 0. Symbolic names for these errors are found in the <errno . h> 
header file. See the descriptions for the perror and strerror functions for 
information about the text which describes these errors. 

fltused_ The C compiler places a reference to the fltused_ symbol into any module that uses a 

floating-point library routine or library routine that requires floating-point support (e.g., the 
use of a float or double as an argument to the printf function). 

Jmode Prototype in <stdlib. h> . 

This data item contains the default type of file (text or binary) translation for a file. It will 
contain a value of either 
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MaxThreads 


minreal 


optarg 


opterr 


optind 


optopt 


O_BINARY indicates that data is transmitted to and from streams unchanged. 

0_TEXT indicates that carriage return characters are added before linefeed 

characters on output operations and are removed on input operations when 
they precede linefeed characters. 

These values are defined in the <f cntl. h> header file. The value of _ fmode may be 
changed by a program to change the default behavior of the open, f open, creat and 
sopen functions. The default setting of _ fmode isO_ TEXT, for text-mode translation. 
0_ BINARY is the setting for binary mode. You can change the value of_ fmode in either 
of two ways: 

• You can include the object file BINMODE . OBJ when linking your application. This 
object file contains code to change the initial setting of _ fmode toO_ BINARY, 
causing all files except stdin, stdout, and stderr to be opened in binary mode. 

• You can change the value of _ fmode directly by setting it in your program. 


There is a limit to the number of threads an application can create under 16-bit OS/2 and 
32-bit NetWare. The default limit is 32. This limit can be adjusted by statically initializing 
the unsigned global variable_ MaxThreads . 

Under 32-bit OS/2, there is no limit to the number of threads an application can create. 
However, due to the way in which multiple threads are supported in the Open Watcom 
libraries, there is a small performance penalty once the number of threads exceeds the 
default limit of 32 (this number includes the initial thread ). If you are creating more than 
32 threads and wish to avoid this performance penalty, you can redefine the threshold value 
of 32. You can statically initialize the global variable_ MaxThreads . 

By adding the following line to your multi-threaded application, the new threshold value 
will be set to 48. 

unsigned _MaxThreads = { 48 }; 

Prototype in <stdlib. h> . 

This data item contains the minimum amount of real memory (below 640K) to reserve 
when running a 32-bit DOS extended application. 

Prototype in <unistd. h> . 

This char * variable contains a pointer to an option-argument parsed by the getopt 
function. 

Prototype in <unistd. h> . 

This int variable controls whether the getopt function will print error messages. The 
default value is non-zero and will cause the getopt function to print error messages on 
the console. 

Prototype in <unistd. h> . 

This int variable holds the index of the argument array element currently processed by the 
getopt function. 

Prototype in <unistd. h> . 
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osmajor 


osminor 


osbuild 


osver 


os mode 


jsp 


stacksize 


stdaux 


This int variable contains the unrecognized option character in case the getopt function 
returns an error. 

Prototype in <stdlib. h> . 

This unsigned char variable contains the major number for the version of DOS 
executing on the computer. If the current version is 3.20, then the value will be 3. 

Prototype in <stdlib. h> . 

This unsigned char variable contains the minor number for the version of DOS 
executing on the computer. If the current version is 3.20, then the value will be 20. 

(Win32 only) Prototype in <stdlib. h> . 

This unsigned short variable contains the operating system build number for the 
version of Windows executing on the computer. 

(Win32 only) Prototype in <stdlib. h> . 

This unsigned int variable contains the operating system build number for the version 
of Windows executing on the computer. 

On Win32s or Windows 95/98 platforms, the high bit of the low-order 16-bit word is 
turned on. Windows 95/98 do not have build numbers. 

unsigned short dwBuild; 

// Get build numbers for Win32 or Win32s 

if ( _ osver < 0x8000 ) // Windows NT/2000 

dwBuild = _ osver; 

else if (_ winmajor < 4) // Win32s 

dwBuild = _ osver & 0x8000; 
else // Windows 95 or 98 

dwBuild =0; // No build numbers provided 

Note that the Win32 GetVersionEx function is the preferred method for obtaining 
operating system version number information. 

(16-bit only) Prototype in <stdlib . h> . 

This unsigned char variable contains either the value DOS_MODE which indicates 
the program is running in real address mode, or it contains the value OS2_MODE which 
indicates the program is running in protected address mode. 

Prototype in <stdlib. h> . 

This data item contains the segment value for the DOS Program Segment Prefix. Consult 
the technical documentation for your DOS system for the process information contained in 
the Program Segment Prefix. 

On 16-bit 80x86 systems, this unsigned int value contains the size of the stack for a 
TINY memory model program. Changing the value of this item during the execution of a 
program will have no effect upon the program, since the value is used when the program 
starts execution. To change the size of the stack to be 8K bytes, a statement such as follows 
can be included with the program. 

unsigned int _ stacksize = { 8 * 1024 }; 

Prototype in <stdio.h>. 

This variable (with type FILE *) indicates the standard auxiliary port (not available in 
some Windows platforms). 
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stderr 


stdin 


stdout 


stdprn 


sys_errlist 


sys_nerr 


threadid 


timezone 


tzname 


wargc 


wargv 


Prototype in <stdio . h> . 

This variable (with type FILE *) indicates the standard error stream (set to the console by 
default). 


Prototype in <stdio . h> . 

This variable (with type FILE *) indicates the standard input stream (set to the console 
by default). 

Prototype in <stdio . h> . 

This variable (with type FILE *) indicates the standard output stream (set to the console 
by default). 

Prototype in <stdio . h> . 

This variable (with type FILE *) indicates the standard printer, (not available in some 
Windows platforms). 

Prototype in <stdlib. h> . 

This variable is an array of pointers to character strings for each error code defined in the 
<errno . h> header file. 


Prototype in <stdlib. h> . 

This int variable contains the number of messages declared in sys_ err list. 
Prototype in <stddef. h> . 

This variable/function may be used to obtain the id of the current thread which is an int. 
In the 32-bit libraries, _ threadid is a function that returns a pointer to an int. In the 
16-bit libraries, _ threadid is a far pointer to an int. Note that the value stored where 
_ threadid points does not necessarily change when a thread context switch occurs (so 
do not make a copy of the pointer ... it may change). To obtain the current thread 
identifier, simply code: 

int tid = *_ threadid; 

Prototype in <time . h> . 

This long int contains the number of seconds of time that the local time zone is earlier 
than Coordinated Universal Time (UTC) (formerly known as Greenwich Mean Time 
(GMT)). Whenever a time function is called, the tzset function is called to set the value 
of the variable. The value will be determined from the value of the TZ environment 
variable. 

Prototype in <time . h> . 

This array of two pointers to character strings indicates the name of the standard 
abbreviation for the time zone and the name of the abbreviation for the time zone when 
daylight saving time is in effect. Whenever a time function is called, the tzset function 
is called to set the values in the array. These values will be determined from the value of 
the TZ environment variable. 

Prototype in <stdlib. h> . 

This int item contains the number of arguments passed to wmain. 

Prototype in <stdlib. h> . 

This wchar_ t * * item contains a pointer to a vector containing the actual arguments 
passed to wmain. 
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wenviron Prototype in <stdlib. h> . 

This wchar_ t * *_near data item is a pointer to an array of wide-character pointers 

to the wide-character equivalents of the environment strings. 

_win_alloc _Jlags 

Prototype in <stdlib. h> . 

This unsigned long int variable contains the flags to be used when allocating 
memory in Windows. 

_win_realloc _Jlags 

Prototype in <stdlib. h> . 

This unsigned long int variable contains the flags to be used when reallocating 
memory in Windows. 

winmajor (Win32 only) Prototype in <stdlib. h> . 

This unsigned int variable contains the operating system major version number for the 
version of Windows executing on the computer. For example, the major version number of 
the Daytona release of Windows NT is 3. 

Note that the Win32 GetVersionEx function is the preferred method for obtaining 
operating system version number information. 

winminor (Win32 only) Prototype in <stdlib. h> . 

This unsigned int variable contains the operating system minor version number for 
the version of Windows executing on the computer. For example, the minor version 
number of the Daytona release of Windows NT is 5. 

Note that the Win32 GetVersionEx function is the preferred method for obtaining 
operating system version number information. 

wirtver (Win32 only) Prototype in <stdlib. h> . 

This unsigned int variable contains the operating system version number for the 
version of Windows executing on the computer. The low-order byte contains the minor 
version number (see also _ winminor). The next byte contains the major version number 
(see also _ winmajor). The high-order word contains no useful information. 

Note that the Win32 GetVersionEx function is the preferred method for obtaining 
operating system version number information. 


1.4 The TZ Environment Variable 


The TZ environment variable is used to establish the local time zone. The value of the variable is used by 
various time functions to compute times relative to Coordinated Universal Time (UTC) (formerly known as 
Greenwich Mean Time (GMT)). 

The time on the computer should be set to the local time. Use the DOS time command and the DOS 
date command if the time is not automatically maintained by the computer hardware. 

The TZ environment variable can be set (before the program is executed) by using the DOS set command 
as follows: 


SET TZ=PST8PDT 
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or (during the program execution) by using the setenv or putenv library functions: 

setenv( "TZ", "PST8PDT", 1 ); 

putenv( "TZ=PST8PDT" ); 

The value of the variable can be obtained by using the getenv function: 
char *tzvalue; 
tzvalue = getenv( "TZ" ); 

The tzset function processes the TZ environment variable and sets the global variables daylight 
(indicates if daylight saving time is supported in the locale), time zone (contains the number of seconds 
of time difference between the local time zone and Coordinated Universal Time (UTC)), and tzname (a 
vector of two pointers to character strings containing the standard and daylight time-zone names). 

The value of the TZ environment variable should be set as follows (spaces are for clarity only): 

std offset dst offset, rule 

On the OS/2 platform, an alternate format is also supported. Please refer to the following section for 
details. 

The expanded format is as follows: 
stdoffset[dstfoffset][,start[/time], end[/time ]]] 

std, dst three or more letters that are the designation for the standard (std) or summer (dst) time 

zone. Only std is required. If dst is omitted, then summer time does not apply in this 
locale. Upper- and lowercase letters are allowed. Any characters except for a leading 
colon (:), digits, comma (,), minus (-), plus (+), and ASCII NUL (\0) are allowed. 

offset indicates the value one must add to the local time to arrive at Coordinated Universal Time 

(UTC). The offset has the form: 

hh[:mm[:ss]] 

The minutes (mm) and seconds (ss) are optional. The hour (hh) is required and may be a 
single digit. The offset following std is required. If no offset follows dst, summer time is 
assumed to be one hour ahead of standard time. One or more digits may be used; the value 
is always interpreted as a decimal number. The hour may be between 0 and 24, and the 
minutes (and seconds) - if present - between 0 and 59. If preceded by a the time zone 
will be east of the Prime Meridian ; otherwise it will be west (which may be indicated by an 
optional preceding "+"). 

rule indicates when to change to and back from summer time. The rule has the form: 

date/time, date/time 

where the first date describes when the change from standard to summer time occurs and 
the second date describes when the change back happens. Each time field describes when, 
in current local time, the change to the other time is made. 

The format of date may be one of the following: 
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Jn The Julian day n (1 <= n <= 365). Leap days are not counted. That is, in 

all years - including leap years - February 28 is day 59 and March 1 is day 
60. It is impossible to explicitly refer to the occasional February 29. 

n The zero-based Julian day (0 <= n <= 365). Leap years are counted, and it 

is possible to refer to February 29. 

Mm.n.d The d’th day (0 <= d <= 6) of week n of month m of the year (1 <= n <= 5, 

1 <= m <= 12, where week 5 means "the last d day in month m" which may 
occur in the fourth or fifth week). Week 1 is the first week in which the 
d’th day occurs. Day zero is Sunday. 

The time has the same format as offset except that no leading sign ("+" or "-") is allowed. 
The default, if time is omitted, is 02:00:00. 

Whenever ctime, _ ctime,localtime, _ localtime ormktime is called, the time zone names 
contained in the external variable tzname will be set as if the tzset function had been called. The same 
is true if the %Z directive of strftime is used. 

Some examples are: 

TZ=EST5EDT Eastern Standard Time is 5 hours earlier than Coordinated Universal Time (UTC). 

Standard time and daylight saving time both apply to this locale. By default. Eastern 
Daylight Time (EDT) is one hour ahead of standard time (i.e., EDT4). Since it is not 
specified, daylight saving time starts on the first Sunday of April at 2:00 A.M. and ends on 
the last Sunday of October at 2:00 A.M. This is the default when the TZ variable is not set. 

TZ=EST5EDT4,M4.1.0/02:00:00,M10.5.0/02:00:00 

This is the full specification for the default when the TZ variable is not set. Eastern 
Standard Time is 5 hours earlier than Coordinated Universal Time (UTC). Standard time 
and daylight saving time both apply to this locale. Eastern Daylight Time (EDT) is one 
hour ahead of standard time. Daylight saving time starts on the first (1) Sunday (0) of April 
(4) at 2:00 A.M. and ends on the last (5) Sunday (0) of October (10) at 2:00 A.M. 

TZ=PST8PDT Pacific Standard Time is 8 hours earlier than Coordinated Universal Time (UTC). Standard 
time and daylight saving time both apply to this locale. By default. Pacific Daylight Time 
is one hour ahead of standard time (i.e., PDT7). Since it is not specified, daylight saving 
time starts on the first Sunday of April at 2:00 A.M. and ends on the last Sunday of 
October at 2:00 A.M. 

TZ=NST3:30NDT1:30 

Newfoundland Standard Time is 3 and 1/2 hours earlier than Coordinated Universal Time 
(UTC). Standard time and daylight saving time both apply to this locale. Newfoundland 
Daylight Time is 1 and 1/2 hours earlier than Coordinated Universal Time (UTC). 

TZ=Central Europe Time-2:00 

Central European Time is 2 hours later than Coordinated Universal Time (UTC). Daylight 
saving time does not apply in this locale. 
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1.5 The OS/2 TZ Environment Variable 


On the OS/2 platform, an alternate format of the TZ environment variable is supported, in addition to the 
standard format described in the preceding section. The value of the OS/2 TZ environment variable should 
be set as follows (spaces are for clarity only): 

std offset dst, rule 

This format will be used if after scanning the standard format there are additional fields or the format has 
not been identified as standard. 

The standard format is identified if an offset follows dst; characters J, M, /, or : are found in rule; or some 
fields are empty. 

The alternate expanded format is as follows (fields may not be empty): 
stdoffsetdst,sm,sw,sd,st,em,ew,ed,et, shift 

std, dst three or more letters that are the designation for the standard (std) and summer (dst) time 

zone. Upper- and lowercase letters are allowed. Any characters except for a leading colon 
(:), digits, comma (,), minus (-), plus (+), and ASCII NUL (\0) are allowed. 

offset indicates the value one must add to the local time to arrive at Coordinated Universal Time 

(UTC). The offset has the form: 

hh[:mm[:ss]] 

The minutes (mm) and seconds (ss) are optional. The hour (hh) is required and may be a 
single digit. The value is always interpreted as a decimal number. The hour may be 
between 0 and 24, and the minutes (and seconds) - if present - between 0 and 59. If 
preceded by a the time zone will be east of the Prime Meridian ; otherwise it will be 
west (which may be indicated by an optional preceding "+"). 

rule indicates when to change to and back from summer time and the time shift for summer 

time. The rule has the form: 

sm,sw,sd,st,em,ew,ed,et, shift 

where sm,sw,sd,st describe when the change from standard to summer time occurs and 
em,ew,ed,et describe when the change back happens. 

sm and em specify the starting and ending month (1 - 12) of the summer time. 

sw and ew specify the starting and ending week of the summer time. You can specify the 
last week of the month (-1 ), or week 1 to 4. Week 0 has a special meaning for the day 
field ( sd or ed ). 

sd/ed Starting/ending day of dst, 

0 - 6 ( weekday Sun to Sat) if sw/ew is not zero, 

1 - 31 ( day of the month ) if sw/ew is zero 
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st/et Starting/ending time (in seconds after midnight) of the summer time. 
shift Amount of time change (in seconds). 

An example of the default setting is: 

TZ=ES T5EDT,4,1,0,7200,10,-1,0,7200,3600 

This is the full specification for the default when the TZ variable is not set. Eastern 
Standard Time is 5 hours earlier than Coordinated Universal Time (UTC). Standard time 
and daylight saving time both apply to this locale. Eastern Daylight Time (EDT) is one 
hour ahead of standard time. Daylight saving time starts on the first (1) Sunday (0) of April 
(4) at 2:00 A.M. and ends on the last (-1) Sunday (0) of October (10) at 2:00 A.M. 
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The Open Watcom C Graphics Library consists of a large number of functions that provide graphical image 
support under DOS and QNX. This chapter provides an overview of this support. The following topics are 
discussed. 

• Graphics Functions 

• Graphics Adapters 

• Classes of Graphics Functions 

1. Environment Functions 

2. Coordinate System Functions 

3. Attribute Functions 

4. Drawing Functions 

5. Text Functions 

6. Graphics Text Functions 

7. Image Manipulation Functions 

8. Font Manipulation Functions 

9. Presentation Graphics Functions 

Display Functions 
Analyze Functions 
Utility Functions 

• Graphics Header Files 

2.1 Graphics Functions 

Graphics functions are used to display graphical images such as lines and circles upon the computer screen. 
Functions are also provided for displaying text along with the graphics output. 

2.2 Graphics Adapters 

Support is provided for both color and monochrome screens which are connected to the computer using any 
of the following graphics adapters: 

• IBM Monochrome Display/Printer Adapter (MDPA) 

• IBM Color Graphics Adapter (CGA) 

• IBM Enhanced Graphics Adapter (EGA) 

• IBM Multi-Color Graphics Array (MCGA) 


Graphics Adapters 


43 




Open Watcom C Library Reference 


• IBM Video Graphics Array (VGA) 

• Hercules Monochrome Adapter 

• SuperVGA adapters (SVGA) supplied by various manufacturers 

2.3 Classes of Graphics Functions 

The functions in the Open Watcom C Graphics Library can be organized into a number of classes: 
Environment Functions 

These functions deal with the hardware environment. 

Coordinate System Functions 

These functions deal with coordinate systems and mapping coordinates from one system to 
another. 

Attribute Functions 

These functions control the display of graphical images. 

Drawing Functions 

These functions display graphical images such as lines and ellipses. 

Text Functions 

These functions deal with displaying text in both graphics and text modes. 

Graphics Text Functions 

These functions deal with displaying graphics text. 

Image Manipulation Functions 

These functions store and retrieve screen images. 

Font Manipulation Functions 

These functions deal with displaying font based text. 

Presentation Graphics Functions 

These functions deal with displaying presentation graphics elements such as bar charts and 
pie charts. 

The following subsections describe these function classes in more detail. Each function in the class is 
noted with a brief description of its purpose. 

2.3.1 Environment Functions 

These functions deal with the hardware environment. The _ getvideoconf ig function returns 
information about the current video mode and the hardware configuration. The _ setvideomode 
function selects a new video mode. 

Some video modes support multiple pages of screen memory. The visual page (the one displayed on the 
screen) may be different than the active page (the one to which objects are being written). 
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The following functions are defined: 


_getactivepcige 

_get\’ideoconfig 

_get\’isualpage 

_grstatus 

_setactivepage 

_settextrows 

_setvideomode 

_setvideomoderows 

_setvisualpage 


get the number of the current active graphics page 

get information about the graphics configuration 

get the number of the current visual graphics page 

get the status of the most recently called graphics library function 

set the active graphics page (the page to which graphics objects are 

drawn) 

set the number of rows of text displayed on the screen 
select the video mode to be used 

select the video mode and the number of text rows to be used 
set the visual graphics page (the page displayed on the screen) 


2.3.2 Coordinate System Functions 

These functions deal with coordinate systems and mapping coordinates from one system to another. The 
Open Watcom C Graphics Library supports three coordinate systems: 

1. Physical coordinates 

2. View coordinates 

3. Window coordinates 

Physical coordinates match the physical dimensions of the screen. The physical origin, denoted (0,0), is 
located at the top left corner of the screen. A pixel to the right of the origin has a positive x-coordinate and 
a pixel below the origin will have a positive y-coordinate. The x- and y-coordinates will never be negative 
values. 


The view coordinate system can be defined upon the physical coordinate system by moving the origin from 
the top left corner of the screen to any physical coordinate (see the _ setvieworg function). In the view 
coordinate system, negative x- and y-coordinates are allowed. The scale of the view and physical 
coordinate systems is identical (both are in terms of pixels). 

The window coordinate system is defined in terms of a range of user-specified values (see the 
_ setwindow function). These values are scaled to map onto the physical coordinates of the screen. This 
allows for consistent pictures regardless of the resolution (number of pixels) of the screen. 

The following functions are defined: 


_getcliprgn 

_getphyscoord 

_get\’iewcoord 

_get\’iewcoord_w 

_get\’iewcoord_wxy 

_getwindowcoord 

jsetcliprgn 

_setvieworg 

jsetviewport 

jsetwindow 


get the boundary of the current clipping region 
get the physical coordinates of a point in view coordinates 
get the view coordinates of a point in physical coordinates 
get the view coordinates of a point in window coordinates 
get the view coordinates of a point in window coordinates 
get the window coordinates of a point in view coordinates 
set the boundary of the clipping region 

set the position to be used as the origin of the view coordinate system 
set the boundary of the clipping region and the origin of the view 
coordinate system 

define the boundary of the window coordinate system 
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2.3.3 Attribute Functions 


These functions control the display of graphical images such as lines and circles. Lines and figures are 
drawn using the current color (see the _ setcolor function), the current line style (see the 
_ setlinestyle function), the current fill mask (see the_ setf illmask function), and the current 
plotting action (see the _ setplotaction function). 

The following functions are defined: 


_getarcinfo 

_getbkcolor 

_getcolor 

_getfillmask 

_getlinestyle 

_getplotaction 

_remapa Up alette 

_remappalette 

_selectpalette 

_setbkcolor 

_setcolor 

_setfillmask 

_setlinestyle 

_setplotaction 


get the endpoints of the most recently drawn arc 

get the background color 

get the current color 

get the current fill mask 

get the current line style 

get the current plotting action 

assign colors for all pixel values 

assign color for one pixel value 

select a palette 

set the background color 

set the current color 

set the current fill mask 

set the current line style 

set the current plotting action 


2.3.4 Drawing Functions 

These functions display graphical images such as lines and ellipses. Functions exist to draw straight lines 
(see the _ lineto functions), rectangles (see the_ rectangle functions), polygons (see the_ polygon 
functions), ellipses (see the _ ellipse functions), elliptical arcs (see the_ arc functions) and pie-shaped 
wedges from ellipses (see the _ pie functions). 

These figures are drawn using the attributes described in the previous section. The functions ending with 
_ w or_ wxy use the window coordinate system; the others use the view coordinate system. 

The following functions are defined: 


_arc 

_arc_w 

_arc_wxy 

_clearscreen 

_ellipse 

_ellipse_w 

_ellipse_wxy 

Jloodfill 

_Jloodfill_w 

_getcurrentposition 

_getcurrentposition_w 

_getpixel 

_getpixel_w 

_lineto 


draw an arc 

draw an arc using window coordinates 

draw an arc using window coordinates 

clear the screen and fill with the background color 

draw an ellipse 

draw an ellipse using window coordinates 
draw an ellipse using window coordinates 
fill an area of the screen with the current color 

fill an area of the screen in window coordinates with the current color 

get the coordinates of the current output position 

get the window coordinates of the current output position 

get the color of the pixel at the specified position 

get the color of the pixel at the specified position in window 

coordinates 

draw a line from the current position to a specified position 
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_lineto_w 

_moveto 

_moveto_w 

_pie 

_pie_w 

_pie_wxy 

_polygon 

_polygon_w 

_polygon_wxy 

_rectangle 

_rectangle_w 

_rectangle_wxy 

_setpixel 

_setpixel_w 


draw a line from the current position to a specified position in window 
coordinates 

set the current output position 

set the current output position using window coordinates 
draw a wedge of a "pie" 

draw a wedge of a "pie" using window coordinates 
draw a wedge of a "pie" using window coordinates 
draw a polygon 

draw a polygon using window coordinates 
draw a polygon using window coordinates 
draw a rectangle 

draw a rectangle using window coordinates 
draw a rectangle using window coordinates 
set the color of the pixel at the specified position 

set the color of the pixel at the specified position in window coordinates 


2.3.5 Text Functions 


These functions deal with displaying text in both graphics and text modes. This type of text output can be 
displayed in only one size. 

This text is displayed using the _ outtext and_ outmem functions. The output position for text follows 
the last text that was displayed or can be reset (see the _ settextposition function). Text windows 
can be created (see the _ settextwindow function) in which the text will scroll. Text is displayed with 
the current text color (see the _ settextcolor function). 


The following functions are defined: 


_clearscreen 

_displaycursor 

_getbkcolor 

_gettextcolor 

_gettextcursor 

_gettextposition 

_gettextwindow 

_outmem 

_outtext 

jscrolltextwindow 

_setbkcolor 

_settextcolor 

_settextcursor 

_settextposition 

_settextwindow 

_wrapon 


clear the screen and fill with the background color 

determine whether the cursor is to be displayed after a graphics function 

completes execution 

get the background color 

get the color used to display text 

get the shape of the text cursor 

get the current output position for text 

get the boundary of the current text window 

display a text string of a specified length 

display a text string 

scroll the contents of the text window 

set the background color 

set the color used to display text 

set the shape of the text cursor 

set the output position for text 

set the boundary of the region used to display text 

permit or disallow wrap-around of text in a text window 


2.3.6 Graphics Text Functions 

These functions deal with displaying graphics text. Graphics text is displayed as a sequence of line 
segments, and can be drawn in different sizes (see the _ setcharsize function), with different 
orientations (see the _ settextorient function) and alignments (see the_ settextalign function). 
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The functions ending with _ w use the window coordinate system; the others use the view coordinate 
system. 

The following functions are defined: 


_gettextextent 

_gettextsettings 

_grtext 

_grtext_w 

_setcharsize 

_setcharsize_w 

_setcharspacing 

_setcharspacing_w 

_settextalign 

_settextorient 

_settextpath 


get the bounding rectangle for a graphics text string 

get information about the current settings used to display graphics text 

display graphics text 

display graphics text using window coordinates 

set the character size used to display graphics text 

set the character size in window coordinates used to display graphics 

text 

set the character spacing used to display graphics text 

set the character spacing in window coordinates used to display 

graphics text 

set the alignment used to display graphics text 
set the orientation used to display graphics text 
set the path used to display graphics text 


2.3.7 Image Manipulation Functions 

These functions are used to transfer screen images. The _ get image function transfers a rectangular 
image from the screen into memory. The _ put image function transfers an image from memory back 
onto the screen. The functions ending with _ w or_ wxy use the window coordinate system; the others use 
the view coordinate system. 

The following functions are defined: 


_getimcige 

_getimage_w 

_getimage_wxy 

_imagesize 

_imagesize_w 

_imagesize_wxy 

_putimage 

_putimage_w 


store an image of an area of the screen into memory 

store an image of an area of the screen in window coordinates into 

memory 

store an image of an area of the screen in window coordinates into 
memory 

get the size of a screen area 

get the size of a screen area in window coordinates 
get the size of a screen area in window coordinates 
display an image from memory on the screen 

display an image from memory on the screen using window coordinates 


2.3.8 Font Manipulation Functions 

These functions are for the display of fonts compatible with Microsoft Windows. Fonts are contained in 
files with an extension of . FON . Before font based text can be displayed, the fonts must be registered with 
the _ registerf onts function, and a font must be selected with the_ setfont function. 
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The following functions are defined: 


_getfontinfo 

_getgtextextent 

_getgtextvector 

_outgtext 

_registerfonts 

_setfont 

_setgtextvector 

_unregisterfonts 


get information about the currently selected font 

get the length in pixels of a text string 

get the current value of the font text orientation vector 

display a string of text in the current font 

initialize the font graphics system 

select a font from among the registered fonts 

set the font text orientation vector 

frees memory allocated by the font graphics system 


2.3.9 Presentation Graphics Functions 

These functions provide a system for displaying and manipulating presentation graphics elements such as 
bar charts and pie charts. The presentation graphics functions can be further divided into three classes: 

Display Functions 

These functions are for the initialization of the presentation graphics system and the 
displaying of charts. 

Analyze Functions 

These functions calculate default values for chart elements without actually displaying the 
chart. 

Utility Functions 

These functions provide additional support to control the appearance of presentation 
graphics elements. 

The following subsections describe these function classes in more detail. Each function in the class is 
noted with a brief description of its purpose. 


2.3.9.1 Display Functions 

These functions are for the initialization of the presentation graphics system and the displaying of charts. 
The _ pg_ initchart function initializes the system and should be the first presentation graphics 
function called. The single-series functions display a single set of data on a chart; the multi-series functions 
(those ending with ms) display several sets of data on the same chart. 

The following functions are defined: 


_pg_chart 

display a 

_pg_chartms 

display a 

_pg_chartpie 

display a 

_pg_chartscatter 

display a 

_pg_chartscatterms 

display a 

_j)g_defaultchart 

initialize 

_pg_initchart 

initialize 


bar, column or line chart 
multi-series bar, column or line chart 
pie chart 
scatter chart 

multi-series scatter chart 

the chart environment for a specific chart type 

the presentation graphics system 
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2.3.9.2 Analyze Functions 

These functions calculate default values for chart elements without actually displaying the chart. The 
functions ending with ms analyze multi-series charts; the others analyze single-series charts. 

The following functions are defined: 


_pg_analyzechart 

analyze 

_pg_analyzechartms 

analyze 

_pg_analyzepie 

analyze 

_pg_analyzescatter 

analyze 

_pg_analyzescatterms 

analyze 


2.3.9.3 Utility Functions 

These functions provide additional support 


bar, column or line chart 
multi-series bar, column or line chart 
pie chart 
scatter chart 

multi-series scatter chart 


control the appearance of presentation graphics elements. 


The following functions are defined: 


_jyg_getchardef 

_pg_getpalette 

_pg_getstyleset 

Jpgjilabelchart 
_pg_resetpalette 
_pg_resetstyl eset 
_pg_setchardef 
_j)g_setpalette 

_pg_setstyleset 

_pg_vlabelchart 


get bit-map definition for a specific character 

get presentation graphics palette (colors, line styles, fill patterns and 

plot characters) 

get presentation graphics style-set (line styles for window borders and 
grid lines) 

display text horizontally on a chart 
reset presentation graphics palette to default values 
reset presentation graphics style-set to default values 
set bit-map definition for a specific character 

set presentation graphics palette (colors, line styles, fill patterns and plot 
characters) 

set presentation graphics style-set (line styles for window borders and 
grid lines) 

display text vertically on a chart 


2.4 Graphics Header Files 

All program modules which use the Graphics Library should include the header file graph. h. This file 
contains prototypes for all the functions in the library as well as the structures and constants used by them. 

Modules using the presentation graphics functions should also include the header file pgchart. h. 
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3 DOS Considerations 


For the most part, DOS (Disk Operating System) for your personal computer can be ignored, unless an 
application is highly dependent upon the hardware or uses specialized functions from the operating system. 
In this section, some of these aspects will be addressed. For a more detailed explanation, the technical 
documentation for the DOS that you are using should be consulted. 


3.1 DOS Devices 


Most of the hardware devices attached to your computer have names which are recognized by DOS. 
names cannot be used as the names of files. Some examples are: 

These 

CON 

the console (screen) 


AUX 

the serial (auxiliary) port 


COM1 

serial port 1 


COM2 

serial port 2 


PRN 

the printer on the parallel port 


LPT1 

the printer on the first parallel port 


LPT2 

the printer on the second parallel port 


LPT3 

the printer on the third parallel port 


NUL 

a non-existent device, which accepts (and discards) output 


Disks (such 

as diskette drives and hard disks) are specified as single letters, starting with the letter A. 

A 

colon character (:) follows the letter for the drive. Either uppercase or lowercase letters can be used, 
examples are; 

Some 

A: 

the first disk drive 


a: 

the first disk drive 


e: 

the fifth disk drive 



3.2 DOS Directories 


Each disk drive is conceptually divided into directories. Each directory is capable of containing files and/or 
other directories. The initial directory, called the root directory, is not named; all other directories are 
named and can be accessed with a path specification. A path is either absolute or relative to the current 
working directory. Some examples are; 

b:\ the root directory of the second disk drive 

\ the root directory of the current disk drive 

\outer\middle\inner 

directory inner which is contained within directory middle which is contained within 
directory outer which is contained within the root directory of the current disk drive. 
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Directory names are separated by backslash characters (\). The initial backslash character informs DOS 
that the path starts with the root directory. When the first character is not a backslash, the path starts with 
the current working directory on the indicated device. 

The DOS CHDIR (CD) command can be used to change the current working directory for a device. 
Suppose that the following DOS commands were issued: 

chdir a:\apps\payroll 
chdir c:\mydir 

Then, the following path specifications are: 

Relative Path Absolute Path 

a:xxx\y a:\apps\payroll\xxx\y 

ctzzzzz c:\mydir\zzzzz 

When no drive is specified, DOS uses the current disk drive. 


3.3 DOS File Names 


The name of a file within a directory has the format filename . ext where the required filename 
portion is up to eight characters in length and the optional ext portion is up to three characters in length. 
A period character (.) separates the two names when the ext portion is present. 

More than eight characters can be given in the filename . DOS truncates the name to eight characters 
when a longer filename is given. This may lead to erroneous results in some cases, since the files 
MYBIGDATAFILE and MYBIGDATES both refer to the file MYBIGDAT . 

The characters used in file names may be letters, digits as well as some other characters documented in 
your DOS technical documentation. Most people restrict their file names to contain only letters and digits. 
Uppercase and lowercase letters are treated as being equivalent (file names are case insensitive). Thus, the 
files 


MYDATA.NEW 
mydata.new 
MyData.New 

all refer to the same file. 

You cannot use a DOS device name (such as CON or PRN, for example) for a file name. See the section 
DOS Devices for a list of these reserved names. 

A complete file designation has the following format: 

drive:\path\filename.ext 

where: 
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drive: is an optional disk drive specification. If omitted, the default drive is used. Some 

examples are: 

A: (first disk drive) 
c: (third disk drive) 

\path\ is the path specification for the directory containing the desired file. Some examples 

are: 


\mylib\ 

\apps\payroll\ 

filename.ext is the name of the file. 

Suppose that the current working directories are as follows: 

Drive Directory 

A: \payroll 

B: \ (root directory) 

C: \source\c 


and that the default disk drive is C: . Then, the following file designations will result in the indicated file 
references: 


Designation 


Actual File 


pgm.c 

\basic.dat 

paypgm\outsep.c 

b:data 

a:employee 

a:\deduct\yrl988 


C:\SOURCE\C\PGM.C 

C:\BASIC.DAT 

C:\SOURCE\C\PAYPGM\OUTSEP.C 

B:\DATA 

A :\P A YROLLVEMPLO YEE 
A:\DEDUCT\YR1988 


3.4 DOS Files 


DOS files are stored within directories on disk drives. Most software, including Open Watcom C/C++, 
treats files in two representations: 

BINARY These files can contain arbitrary data. It is the responsibility of the software to recognize 

records within the file if they exist. 

TEXT These files contain lines of "printable" characters. Each line is delimited by a carriage 

return character followed by a linefeed character. 

Since the conceptual view of text files in the C and C++ languages is that lines are terminated by only 
linefeed characters, the Open Watcom C library will remove carriage returns on input and add them on 
output, provided the mode is set to be text. This mode is set upon opening the file or with the setmode 
function. 
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3.5 DOS Commands 


DOS commands are documented in the technical documentation for your DOS system. These may be 
invoked from a C or C++ program with the system function. 

3.6 DOS Interrupts 

DOS interrupts and 8086 interrupts are documented in the technical documentation for your DOS system. 
These may be generated from a C or C++ program by calling the bdos, intdos, intdosx, intr, 
int386, int386x, int8 6 and int 8 6x functions. 


3.7 DOS Processes 


Currently, DOS has the capability to execute only one process at a time. Thus, when a process is initiated 
with the spawn . . . parameter P_ WAIT, the new process will execute to completion before control 
returns to the initiating program. Otherwise, the new task replaces the initial task. Tasks can be started by 
using the system, exec. . . and spawn. . . functions. 
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4 Library Functions and Macros 


Each of the functions or macros in the C Library is described in this chapter. Each description consists of a 
number of subsections: 

Synopsis: This subsection gives the header files that should be included within a source file that references the 

function or macro. It also shows an appropriate declaration for the function or for a function that could be 
substituted for a macro. This declaration is not included in your program; only the header file(s) should be 
included. 

When a pointer argument is passed to a function and that function does not modify the item indicated by 

that pointer, the argument is shown with const before the argument. For example, 

const char *string 

indicates that the array pointed at by string is not changed. 

Constraints: This subsection describes Runtime-constraints for Safer C Library functions. 

Safer C: This subsection points to the Safer C version of the described "unsafe" function. 

Description: This subsection is a description of the function or macro. 

Returns: This subsection describes the return value (if any) for the function or macro. 

Errors: This subsection describes the possible errno values. 

See Also: This optional subsection provides a list of related functions or macros. 

Example: This optional subsection consists of one or more examples of the use of the function. The examples are 
often just fragments of code (not complete programs) for illustration purposes. 

Classification: This subsection provides an indication of where the function or macro is commonly found. The 
following notation is used: 

ISO C These functions or macros are defined by the ISO/ANSI C standard ISO/IEC 

9899:1989. 

ISO C90 These functions or macros are defined by the ISO/ANSI C standard ISO/IEC 

9899:1990. 

ISO C95 These functions or macros are defined by the ISO/ANSI C standard ISO/IEC 

9899:1990/AMD 1:1995. 

ISO C99 These functions or macros are defined by the ISO/ANSI C standard ISO/IEC 

9899:1999. 
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POSIX 1003.1 


POSIX 1003.2 


POSIX 1003.4 


Intel 


BIOS 

DOS 


OS/2 

PC Graphics 

Windows 

WATCOM 


TR 24731 


The functions or macros are not defined by the ISO C standard. These functions are 
specified in the document IEEE Standard Portable Operating System Interface for 
Computer Environments (IEEE Draft Standard 1003.1-1990). 

These functions or macros are not defined by the ISO C standard. These functions are 
specified in the document Shell and Utility Application Interface for Computer 
Operating System Environments (IEEE Computer Society Working Group 1003.2). 

These functions or macros are not defined by the ISO C standard. These functions are 
specified in the document Realtime Extensions for Computer Operating System 
Environments (IEEE Computer Society Working Group 1003.4). 

These functions or macros are neither ISO C nor POSIX. It performs a function 
related to the Intel x86 architecture. It may be found in other implementations of C 
for personal computers using Intel chips. Use these functions with caution, if 
portability is a consideration. 

These functions access a service of the BIOS found in IBM Personal Computers and 
compatibles. These functions should not be used if portability is a consideration. 

These functions or macros are neither ISO C nor POSIX. They perform a function 
related to DOS. They may be found in other implementations of C for personal 
computers with DOS. Use these functions with caution, if portability is a 
consideration. 

These functions are specific to OS/2. 

These functions are part of the PC graphics library. 

These functions are specific to Microsoft Windows. 

These functions or macros are neither ISO C nor POSIX. They may be found in other 
implementations of the C language, but caution should be used if portability is a 
consideration. 

These functions are "safer" versions of normal C library functions. They perform 
more checks on parameters and should be used in preference over their "unsafe" 
version. 


Systems: This subsection provides an indication of where the function or macro is supported. The following notation 

is used: 


All 

DOS 

DOS/16 

DOS/32 

DOS/PM 


This function is available on all systems (we do not include RDOS, Linux, Netware or 
DOS/PM in this category). 

This function is available on both 16-bit DOS and 32-bit extended DOS. 

This function is available on 16-bit, real-mode DOS. 

This function is available on 32-bit, protected-mode extended DOS. 

This 16-bit DOS protected-mode function is supported under Phar Lap’s 
286IDOS-Extender "RUN286". The function is found in one of Open Watcom’s 
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Linux 

MACRO 
Math 
Netware 
OS/2 1.x 


OS/2-32 

RDOS 

QNX 

QNX/16 

QNX/32 

Windows 

Win386 

Win32 


16-bit protected-mode DOS libraries (DOSPM*.LIB under the 16-bit OS2 
subdirectory). 

This function is available on the Linux operating system for Intel 80386 and upwards 
compatible systems. 

This function is implemented as a macro (#define) on all systems. 

This function is a math function. Math functions are available on all systems. 

This function is available on the 32-bit Novell Netware operating system. 

This function is available on IBM OS/2 1.x, a 16-bit protected-mode system for Intel 
80286 and upwards compatible systems. 

When "(MT)" appears after OS/2, it refers to the CLIBMTL library which supports 
multi-threaded applications. 

When "(DL)" appears after OS/2, it refers to the CLIBDLL library which supports 
creation of Dynamic Link Libraries. 

When "( all)" appears after "OS/2 1", it means all versions of the OS/2 1.x libraries. 

If a function is missing from the OS/2 library, it may be found in Open Watcom’s 
16-bit protected-mode DOS libraries (DOSPM*.LIB) for Phar Lap’s 
286IDOS-Extender (RUN286). 

This function is available on 32-bit IBM OS/2, a protected-mode system for Intel 
80386 and upwards compatible systems. 

This function is available on RDOS operating system. 

This function is available on QNX Software Systems’ 16 or 32-bit operating systems. 

This function is available on QNX Software Systems’ 16-bit operating system. 

This function is available on QNX Software Systems’ 32-bit operating system. 

This function is available on 16-bit, protected-mode Windows 3.x. 

This function is available on Microsoft Windows 3.x, using Open Watcom’s 
Windows Extender for 32-bit protected-mode applications running on Intel 386 or 
upward compatible systems. 

This function is available on 32-bit Microsoft Windows platforms (Windows 95, 
Windows 98, Windows NT, Windows 2000, etc.). It may also be available for 
Windows 3.x using Win32s support. 
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Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


#include <stdlib.h> 
void abort( void ) ; 

The abort function raises the signal SIGABRT. The default action for SIGABRT is to terminate 
program execution, returning control to the process that started the calling program (usually the 
operating system). The status unsuccessful termination is returned to the invoking process by means of 
the function call raise (SIGABRT) . The exit code returned to the invoking process is 
EXIT_ FAILURE which is defined in the<stdlib. h> header file. 

The abort function does not return to its caller. 

atexit, _ bgetcmd.exec. . exit, _ Exit,_ exit.getcmd, getenv, main, onexit, 
putenv, spawn. . system 

♦include <stdlib.h> 

void main() 

{ 

int major_ error = 1; 

if( major_ error ) 
abort (); 

} 

ISOC 

All, Linux, RDOS, Netware 
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Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


abort_handler_s 


♦ define_STDC_ WANT_ LIB_ EXT1 1 

♦include <stdlib.h> 

void abort_ handler_ s( 

const char * restrict msg, 
void * restrict ptr, 
errno_ t error ); 

The abort_ handler_ s function may be passed as an argument to the 

set_ constraint handler_ s function. It writes a message on the standard error stream in the 
following format: 

Runtime-constraint violation: <msg> 

The abort_ handler_ s function then calls thabort function. 

The abort_ handler_ s function does not return to its caller. 
ignore_ handler_ s$et_ constraint handler_ s 

♦ define_STDC_ WANT_ LIB_ EXT1 1 

♦include <stdlib.h> 

♦include <stdio.h> 

void main( void ) 

{ 

constraint handler_ t old_ handler; 

old_ handler = set_ constraint handler_ s ( abort_ handler_ s ) ; 
if( getenv_ s ( NULL, NULL, 0, NULL ) ) { 

printf ( "getenv_ s failed\n" ); 

} 

set_ constraint handler_ s ( old_ handler ) ; 

} 

produces the following: 

Runtime-constraint violation: getenv_s, name == NULL. 

ABNORMAL TERMINATION 

TR 24731 

All, Linux, RDOS, Netware 
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abs 

Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <stdlib.h> 
int abs( int j ); 

The abs function returns the absolute value of its integer argument j. 

The abs function returns the absolute value of its argument. 

labs, llabs, imaxabs, fabs 

♦include <stdio.h> 

♦include <stdlib.h> 

void main( void ) 

{ 

printf( "%d %d %d\n", abs( -5 ), abs( 0 ), 

} 

produces the following: 

5 0 5 
ISO C90 

All, Linux, RDOS, Netware 


abs( 5 ) ) ; 
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access, _access, _waccess 


Synopsis: 

Description: 


Returns: 

Errors: 


See Also: 
Example: 


♦include <io.h> 

int access ( const char *path, int mode ); 

int _ access( const char *path, int mode ); 

int _ waccess( const wchar_ t *path, int mode ); 

The access function determines if the file or directory specified by path exists and if it can be 
accessed with the file permission given by mode. 

When the value of mode is zero, only the existence of the file is verified. The read and/or write 
permission for the file can be determined when mode is a combination of the bits: 


Bit 

Meaning 

R_OK 

test for read permission 

W_OK 

test for write permission 

X_OK 

test for execute permission 

F_OK 

test for existence of file 


With DOS, all files have read permission; it is a good idea to test for read permission anyway, since a 
later version of DOS may support write-only files. 

The _ access function is identical toaccess. Use _ access for ANSI naming conventions. 

The _ waccess function is a wide-character version ofaccess that operates with wide-character 
strings. 

The access function returns zero if the file or directory exists and can be accessed with the specified 
mode. Otherwise, -1 is returned and errno is set to indicate the error. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EACCES Access denied because the file’s permission does not allow the specified access. 

ENOENT Path or file not found. 

chmod, fstat, open, sopen, stat 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <io.h> 

void main( int argc, char *argv[] ) 

{ 

if ( argc != 2 ) { 

fprintf( stderr, "Use: check <filename>\n" ); 
exit ( 1 ); 

} 
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access, _access, _waccess 


if( access ( argv[l], F_ OK ) == 0 ) { 

printf( "%s existsin", argv[1] ); 

} else { 

printf ( "%s does not existin'', argv[l] ); 
exit ( EXIT_ FAILURE ) ; 

} 

if( access ( argv[l], R_ OK ) == 0 ) { 

printf( "%s is readablein", argv[1] ); 

} 

if( access ( argv[l], W_ OK ) == 0 ) { 

printf( "%s is writeablein", argv[1] ); 

} 

if( access ( argv[l], X_ OK ) == 0 ) { 

printf( "%s is executablein", argv[l] ); 

} 

exit ( EXIT_ SUCCESS ) ; 


Classification: POSIX 1003.1 

_access conforms to ANSI naming conventions 
_waccess is WATCOM 

Systems: access - All, Linux, RDOS, Netware 

_ access - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
_ waccess - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 


RDOS 
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acos 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double acos ( double x ); 

The acos function computes the principal value of the arccosine of x. A domain error occurs for 
arguments not in the range [-1,1]. 

The acos function returns the arccosine in the range [0,7t]. When the argument is outside the 
permissible range, the matherr function is called. Unless the default matherr function is replaced, 
it will set the global variable errno to EDOM, and print a "DOMAIN error" diagnostic message using 
the stderr stream. 

asin, atan, atan2, matherr 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", acos (.5) ); 

} 

produces the following: 

1.047197 

ISOC 

Math 
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acosh 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double acosh( double x ) ; 

The acosh function computes the inverse hyperbolic cosine of x. A domain error occurs if the value of 
x is less than 1.0. 

The acosh function returns the inverse hyperbolic cosine value. When the argument is outside the 
permissible range, the matherr function is called. Unless the default matherr function is replaced, 
it will set the global variable errno to EDOM, and print a "DOMAIN error" diagnostic message using 
the stderr stream. 

asinh, atanh, cosh, matherr 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", acosh( 1.5 ) ); 

} 

produces the following: 

0.962424 
WATCOM 
Math 
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alloca 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <malloc.h> 

void *alloca ( size_ t size ) ; 

The alloca function allocates space for an object of .size bytes from the stack. The allocated space is 
automatically discarded when the current function exits. The alloca function should not be used in 
an expression that is an argument to a function. 

The alloca function returns a pointer to the start of the allocated memory. The return value is NULL 
if there is insufficient stack space available. 

calloc, malloc, stackavail 

#include <stdio.h> 

♦include <string.h> 

♦include <malloc.h> 

FILE *open_ err_ file ( char * ) ; 

void main() 

{ 

FILE *fp; 

fp = open_ err_ file ( "alloca" ) ; 
if( fp == NULL ) { 

printf( "Unable to open error file\n" ); 

} else { 

fclose( fp ); 

} 

} 

FILE *open_ err_ file ( char *name ) 

{ 

char *buffer; 

/* allocate temp buffer for file name */ 
buffer = (char *) alloca( strlen(name) + 5 ); 
if( buffer ) { 

sprintf( buffer, "%s.err", name ); 
return( fopen( buffer, "w" ) ); 

} 

return( (FILE *) NULL ); 

} 

WATCOM 

MACRO 
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arc Functions 


Synopsis: #include <graph.h> 

short _ FAR _ arc( short xl, short yl, 
short x2, short y2, 

short x3, short y3, 

short x4, short y4 ); 

short _ FAR _ arc_ w ( double xl, double yl, 

double x2, double y2, 

double x3, double y3, 

double x4, double y4 ) ; 

short _ FAR _ arc_ wxy ( struct _ wxycoord _ FAR *pl, 

struct _ wxycoord _ FAR *p2, 
struct _ wxycoord _ FAR *p3, 
struct _ wxycoord _ FAR *p4 ) ; 

Description: The _ arc functions draw elliptical arcs. The_ arc function uses the view coordinate system. The 
_ arc_ w and. arc_ wxy functions use the window coordinate system. 

The center of the arc is the center of the rectangle established by the points (xl,yl) and (x2,y2). 
The arc is a segment of the ellipse drawn within this bounding rectangle. The arc starts at the point on 
this ellipse that intersects the vector from the centre of the ellipse to the point (x3, y 3) . The arc ends 
at the point on this ellipse that intersects the vector from the centre of the ellipse to the point 
(x4, y4) . The arc is drawn in a counter-clockwise direction with the current plot action using the 
current color and the current line style. 

The following picture illustrates the way in which the bounding rectangle and the vectors specifying the 
start and end points are defined. 



When the coordinates (xl,yl) and (x2,y2) establish a line or a point (this happens when one or 
more of the x-coordinates or y-coordinates are equal), nothing is drawn. 
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arc Functions 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


The current output position for graphics output is set to be the point at the end of the arc that was drawn. 

The _ arc functions return a non-zero value when the arc was successfully drawn; otherwise, zero is 
returned. 

_ ellipse^ pie,_ rectangle^ getarcinfo,_ setcolor,_ setlinestyle, 

_ setplotaction 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

_ setvideomode( _ VRES16C0L0R ); 

_ arc( 120, 90, 520, 390, 500, 20, 450, 460 ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ) ; 

} 

produces the following: 



PC Graphics 

_ arc - DOS 
_ arc_ w - DOS 
_ arc_ wxy - DOS 
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asctime Functions 


Synopsis: #include <time.h> 

char * asctime( const struct tm *timeptr ); 

char *_ asctime( const struct tm *timeptr, char *buf ); 

wchar_ t *_ wasctime( const struct tm *timeptr ); 

wchar_ t *_wasctime ( const struct tm *timeptr, wchar_ t *buf ) ; 

struct tm { 

int tm_ sec; /* seconds after the minute — [0,61] */ 

int tm_ min; /* minutes after the hour — [0,59] */ 

int tm_ hour; /* hours after midnight — [0,23] */ 

int tm_ mday; /* day of the month — [1,31] */ 

int tm_mon; /* months since January — [0,11] */ 

int tm_ year; /* years since 1900 */ 

int tm_ wday; /* days since Sunday — [0,6] */ 

int tm_ yday; /* days since January 1 — [0,365]*/ 

int tm_isdst; /* Daylight Savings Time flag */ 

} ; 

Safer C: The Safer C Library extension provides the asctime_ s function which is a safer alternative to 

asctime This newer asctime_ s function is recommended to be used instead of the traditional 
"unsafe" asctime function. 

Description: The asctime functions convert the time information in the structure pointed to by timeptr into a string 
containing exactly 26 characters. This string has the form shown in the following example: 

Sat Mar 21 15:58:27 1987\n\0 

All fields have a constant width. The new-line character ' \n' and the null character ' \0' occupy the 
last two positions of the string. 

The ISO C function asctime places the result string in a static buffer that is re-used each time asctime 
or ctime is called. The non-ISO C function _ asctime places the result string in the buffer pointed 
to by buf. 

The _ wasctime and_wasctime functions are identical to theiasctime and _ asctime 

counterparts except that they deal with wide-character strings. 

Returns: The asctime functions return a pointer to the character string result. 

See Also: asctime_ s,clock, ctime Functions, ctime_ s,difftime, gmtime, gmtime_ s, 

localtime, localtime_ sjnktime, strftime, time, tzset 

Example: #include <stdio.h> 

♦include <time.h> 

void main() 

{ 

struct tm time_ of_ day; 
time_ t Itime; 

auto char buf[26]; 
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asctime Functions 


Classification: 


Systems: 


} 


time( sltime ); 

_ localtime ( Sltime, &time_ of_ day ) ; 
printf( "Date and time is: %s\n", 

_ asctime( &time_ of_ day, buf ) 


) ; 


produces the following: 

Date and time is: Sat Mar 21 15:58:27 1987 

ISOC 

_asctime is WATCOM 
_wasctime is WATCOM 
_wasctime is WATCOM 

asctime - All, Linux, RDOS, Netware 
_ asctime - All, RDOS, Netware 
_ wasctime - All, Linux 
_ wasctime - All, Linux 
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asctime_s, _wasctime_s 


Synopsis: #def ine STDC_ WANT_ LIB_ EXT1 1 

♦include <time.h> 

errno_ t asctime_ s( char * s, 

rsize_ t maxsize, 
const struct tm * timeptr); 
errno_ t _ wasctime_ s ( wchar_ t * s, 

rsize_ t maxsize, 

const struct tm * timeptr); 

struct tm { 


int 

tm_ 

sec; 

/* 

seconds after the minute — 

[0,61] 

*/ 

int 

tm_ 

min; 

/* 

minutes after the hour — 

[0,59] 

*/ 

int 

tm_ 

hour; 

/* 

hours after midnight — 

[0,23] 

*/ 

int 

tm_ 

mday; 

/* 

day of the month — 

[1,31] 

*/ 

int 

tm_ 

mon; 

/* 

months since January — 

[0,11] 

*/ 

int 

tm_ 

year; 

/* 

years since 1900 


*/ 

int 

tm_ 

wday; 

/* 

days since Sunday — 

[0, 6] 

*/ 

int 

tm_ 

yday; 

/* 

days since January 1 

[0,365' 

1 */ 

int 

tm_ 

isdst; 

/* 

Daylight Savings Time flag * 

/ 



} ; 


Constraints: If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and asctime_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither ,v nor timeptr shall be a null pointer, maxsize shall not be less than 26 and shall not be greater 
than RSIZE_MAX. The broken-down time pointed to by timeptr shall be normalized. The calendar year 
represented by the broken-down time pointed to by timeptr shall not be less than calendar year 0 and 
shall not be greater than calendar year 9999. If there is a runtime-constraint violation, there is no 
attempt to convert the time, and s[0] is set to a null character if ,v is not a null pointer and maxsize is not 
zero and is not greater than RSIZE_MAX. 

Description: The asctime_ s function converts the normalized broken-down time in the structure pointed to by 
timeptr into a 26 character (including the null character) string in the form 

Sun Sep 16 01:03:52 1973\n\0 
The fields making up this string are (in order): 

1. The name of the day of the week represented by timeptr->tm_wday using the following three 
character weekday names: 

Sun, Mon, Tue, Wed, Thu, Fri, and Sat. 

2. The character space. 

3. The name of the month represented by timeptr->tm_mon using the following three character 
month names: 

Jan, Feb, Mar.Apr.MayJun, Jul, Aug, Sep, Oct, Nov, and Dec. 

4. The character space. 

5. The value of timeptr->tm_mday as if printed using the fprintf format "%2d". 
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asctime_s, _wasctime_s 


Returns: 


See Also: 


Example: 


Classification: 


Systems: 


6. The character space. 

7. The value of timeptr->tm_hour as if printed using the fprintf format "%.2d". 

8. The character colon. 

9. The value of timeptr->tm_min as if printed using the fprintf format "%.2d". 

10. The character colon. 

11. The value of timeptr->tm_sec as if printed using the fprintf format "%.2d". 

12. The character space. 

13. The value of timeptr->tm_year + 1900 as if printed using the fprintf format "%4d". 

14. The character new line. 

15. The null character. 

The _ wasctime_ s function is a wide-character version ofksctime_ s that operates with 
wide-character strings. 

The asctime_ s function returns zero if there was no runtime-constraint violation. Otherwise, a 
non-zero value is returned. 

asctime Functions, clock, ctime Functions, ctime_ s,difftime, gmtime, gmtime_ s, 
localtime, localtime_ sjnktime, strftime, time, tzset 

#def ine_STDC_ WANT_ LIB_ EXT1 _ 1 

♦include <stdio.h> 

♦include <time.h> 

void main() 

{ 

struct tm time_ of_ day; 
time_ t ltime; 

auto char buf[26]; 

time( &ltime ); 

_ localtime( &ltime, &time_ of_ day ); 

asctime_ s ( buf, sizeof ( buf ) , &time_ of_ day ) ; 

printf( "Date and time is: %s\n", buf ); 

} 

produces the following: 

Date and time is: Mon Jan 30 11:32:45 2006 
TR 24731 

_wasctime_s is WATCOM 

asctime_ s - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
Linux, RDOS, Netware 
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asctime_s, _wasctime_s 


_ wasctime. 
Linux 


s - DOS, Windows, Win386, Win32, OS/2 1.x (all), OS/2-32, 
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asm 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double asin ( double x ); 

The asin function computes the principal value of the arcsine of x. A domain error occurs for 
arguments not in the range [-1,1]. 

The asin function returns the arcsine in the range [-7t/2,7t/2]. When the argument is outside the 
permissible range, the matherr function is called. Unless the default matherr function is replaced, 
it will set the global variable errno to EDOM, and print a "DOMAIN error" diagnostic message using 
the stderr stream. 

acos, atan, atan2, matherr 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", asin (.5) ); 

} 

produces the following: 

0.523599 

ISOC 

Math 
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asinh 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double asinh( double x ); 

The asinh function computes the inverse hyperbolic sine of x. 

The asinh function returns the inverse hyperbolic sine value. 

acosh, atanh, sinh, matherr 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", asinh( 0.5 ) ); 

} 

produces the following: 

0.481212 
WATCOM 
Math 
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assert 


Synopsis: 

Description: 


Returns: 

Example: 


Classification: 

Systems: 


#include <assert.h> 

void assert( int expression ) ; 

The assert macro prints a diagnostic message upon the stderr stream and terminates the program 
if expression is false (0). The diagnostic message has the form 

Assertion failed: expression , file filename, line linenumber 

where, filename is the name of the source file and linenumber is the line number of the assertion that 
failed in the source file. Filename and linenumber are the values of the preprocessing macros 
_FILE _and_ LINE _respectively. No action is taken if expression is true (non-zero). 

The assert macro is typically used during program development to identify program logic errors. 

The given expression should be chosen so that it is true when the program is functioning as intended. 
After the program has been debugged, the special "no debug" identifier NDEBUG can be used to remove 
assert calls from the program when it is re-compiled. If NDEBUG is defined (with any value) with a 
-d command line option or with a #def ine directive, the C preprocessor ignores all assert calls in 
the program source. 

The assert macro does not return a value. 

♦include <stdio.h> 

♦include <assert.h> 

void process_ string( char *string ) 

{ 

/* use assert to check argument */ 
assert ( string != NULL ); 
assert( *string != '\0' ); 

/* rest of code follows here */ 

} 

void main() 

{ 

process_ string( "hello" ); 
process_ string( "" ); 

} 

ISOC 

MACRO 
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atari 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double atan( double x ) ; 

The atan function computes the principal value of the arctangent of x. 

The atan function returns the arctangent in the range (-n/2,n/2). 

acos, asin, atan2 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", atan (.5) ); 

} 

produces the following: 

0.463648 

ISOC 

Math 
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atan2 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 

double atan2 ( double y, double x ); 

The atan2 function computes the principal value of the arctangent of y/x, using the signs of both 
arguments to determine the quadrant of the return value. A domain error occurs if both arguments are 
zero. 

The atan2 function returns the arctangent of y/x, in the range (-n,n). When the argument is outside the 
permissible range, the matherr function is called. Unless the default matherr function is replaced, 
it will set the global variable errno to EDOM, and print a "DOMAIN error" diagnostic message using 
the stderr stream. 

acos, asin, atan, matherr 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", atan2 ( .5, 1. ) ); 

} 

produces the following: 

0.463648 

ISOC 

Math 
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atanh 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double atanh( double x ) ; 

The atanh function computes the inverse hyperbolic tangent of x. A domain error occurs if the value 
of x is outside the range (-1,1). 

The atanh function returns the inverse hyperbolic tangent value. When the argument is outside the 
permissible range, the matherr function is called. Unless the default matherr function is replaced, 
it will set the global variable errno to EDOM, and print a "DOMAIN error" diagnostic message using 
the stderr stream. 

acosh, asinh, matherr, tanh 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", atanh( 0.5 ) ); 

} 

produces the following: 

0.549306 

WATCOM 

Math 
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atexit 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdlib.h> 

int atexit( void (*func)(void) ); 

The atexit function is passed the address of function June to be called when the program terminates 
normally. Successive calls to atexit create a list of functions that will be executed on a "last-in, 
first-out" basis. No more than 32 functions can be registered with the atexit function. 

The functions have no parameters and do not return values. 

The atexit function returns zero if the registration succeeds, non-zero if it fails. 

abort, _ Exit,_ exit.exit 

♦include <stdio.h> 

♦include <stdlib.h> 

void main() 

{ 

extern void fund (void) , func2 (void) , func3 (void) ; 

atexit ( fund ) ; 
atexit( func2 ); 
atexit ( func3 ); 
printf ( "Do this first. \n" ); 

} 


void 

fund (void) 

{ 

printf( 

"last.\n 

void 

func2(void) 

{ 

printf( 

"this " 

void 

func3(void) 

{ 

printf( 

"Do " ); 


produces the following: 

Do this first. 

Do this last. 

ISOC 

All, Linux, RDOS, Netware 
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atof, _wtof 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <stdlib.h> 

double atof( const char *ptr ) ; 

double _ wtof ( const wchar_ t *ptr ) ; 

The atof function converts the string pointed to by ptr to double representation. It is equivalent to 
strtod( ptr, (char **)NULL ) 

The _ wtof function is a wide-character version of at of that operates with wide-character strings. It 
is equivalent to 

wcstod( ptr, (wchar_t **)NULL ) 

The atof function returns the converted value. Zero is returned when the input string cannot be 
converted. In this case, errno is not set. When an error has occurred, errno contains a value 
indicating the type of error that has been detected. 

sscanf, strtod 

♦include <stdlib.h> 

void main() 

{ 

double x; 

x = atof( "3.1415926" ) ; 

} 

ISOC 

_wtof is WATCOM 

atof - Math 
_ wtof - Math 
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atoi, _wtoi 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <stdlib.h> 

int atoi( const char *ptr ) ; 

int _ wtoi ( const wchar_ t *ptr ) ; 

The atoi function converts the string pointed to by ptr to int representation. 

The _ wtoi function is a wide-character version ofatoi that operates with wide-character strings. 
The atoi function returns the converted value. 

atoi, atoll, itoa, ltoa, lltoa, sscanf, strtol, strtoll, strtoul, strtoull, 
strtoimax, strtoumax, ultoa, ulltoa, utoa 

♦include <stdlib.h> 

void main() 

{ 

int x; 

x = atoi ( "-289" ); 

} 

ISOC 

_wtoi is WATCOM 

atoi - All, Linux, RDOS, Netware 
_ wtoi - All, Linux, RDOS 
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atol,_wtol 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <stdlib.h> 

long int atol( const char *ptr ) ; 

long int _ wtol ( const wchar_ t *ptr ) ; 

The atol function converts the string pointed to by ptr to long int representation. 

The _ wtol function is a wide-character version ofatol that operates with wide-character strings. 
The atol function returns the converted value. 

atoi, atoll, itoa, ltoa, lltoa, sscanf, strtol, strtoll, strtoul, strtoull, 
strtoimax, strtoumax, ultoa, ulltoa, utoa 

♦include <stdlib.h> 

void main() 

{ 

long int x; 
x = atol( "-289" ) ; 

} 

ISOC 

_wtol is WATCOM 

atol - All, Linux, RDOS, Netware 
_ wtol - All, Linux, RDOS 
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atoll, _wtoll 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <stdlib.h> 

long long int atoll ( const char *ptr ); 
long long int _ wtoll ( const wchar_ t *ptr ) ; 

The atoll function converts the string pointed to by ptr to long long int representation. 

The _ wtoll function is a wide-character version ofatoll that operates with wide-character strings. 
The atoll function returns the converted value. 

atoi, atol, itoa, ltoa, lltoa, sscanf, strtol, strtoll, strtoul, strtoull, 
strtoimax, strtoumax, ultoa, ulltoa, utoa 

♦include <stdlib.h> 

void main() 

{ 

long int x; 

x = atoll( "-289356768201" ); 

} 

ISOC 

_wtoll is WATCOM 

atoll - All, Linux, RDOS, Netware 
_ wtoll - All, Linux, RDOS 
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atouni 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdlib.h> 

wchar_ t *_ atouni ( wchar_ t *wcs, const char *sbcs ); 

The _ atouni function converts the string pointed to by sbcs to a wide-character string and places it in 
the buffer pointed to by wcs. 

The conversion ends at the first null character. 

The _ atouni function returns the first argument as a result. 

atoi, atol, itoa, ltoa, strtod, strtol, strtoul, ultoa, utoa 

♦include <stdlib.h> 

void main() 

{ 

wchar_ t wcs[12]; 

_ atouni( wcs, "Hello world" ) ; 

} 

WATCOM 

All, Linux, RDOS, Netware 
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basename 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


♦include <libgen.h> 

char *basename( char *path ) ; 

The basename function returns a pointer to the final component of a pathname pointed to by the path 
argument, deleting trailing path separators. 

If the string pointed to by path consists entirely of path separators, a string consisting of single path 
separator is returned. 

If path is a null pointer or points to an empty string, a pointer to the string is returned. 

The basename function may modify the string pointed to by path and may return a pointer to static 
storage that may be overwritten by a subsequent call to basename 

The basename function is not re-entrant or thread-safe. 

The basename function returns a pointer to the final component of path. 

dirname 

♦include <stdio.h> 

♦include <libgen.h> 

int main( void ) 

{ 

puts ( basename( "/usr/lib" ) ); 

puts( basename! "//usr//lib//" ) ); 

puts! basename! "///" ) ); 

puts! basename! "foo" ) ); 

puts( basename( NULL ) ) ; 

return( 0 ) ; 

} 

produces the following: 

lib 

lib 

/ 

foo 


POSIX 

All, Linux, RDOS, Netware 
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bdos 


Synopsis: #include <dos.h> 

int bdos( int dos_ func, unsigned dx, unsigned char al ); 

Description: The bdos function causes the computer’s central processor (CPU) to be interrupted with an interrupt 
number hexadecimal 21 (0x21), which is a request to invoke a specific DOS function. Before the 
interrupt, the DX register is loaded from dx, the AH register is loaded with the DOS function number 
from dos_func and the AL register is loaded from al. The remaining registers are passed unchanged to 
DOS. 

You should consult the technical documentation for the DOS operating system you are using to 
determine the expected register contents before and after the interrupt in question. 

Returns: The bdos function returns the value of the AX register after the interrupt has completed. 

See Also: int386, int386x, int86, int86x, intdos, intdosx, intr, segread 

Example: ((include <dos.h> 

♦ define DISPLAY_ OUTPUT 2 

void main() 

{ 

int rc; 

rc = bdos ( DISPLAY_ OUTPUT, ' B', 0 ); 

rc = bdos( DISPLAY_ OUTPUT, 'D', 0 ); 

rc = bdos ( DISPLAY_ OUTPUT, 'O', 0 ); 

rc = bdos( DISPLAY_ OUTPUT, 'S', 0 ); 

} 

Classification: DOS 

Systems: DOS, Windows, Win386, DOS/PM 
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beginthread, _beginthreadex 


Synopsis: #include <process.h> 

#if defined(_ 386_ ) 

# define FAR 
#else 

# define FAR_far 

#endif 

#if defined (_ NT_ ) 

unsigned long _ beginthread( 

void (*start_ address)(void *), 
unsigned stack_ size, 
void *arglist); 

unsigned long _ beginthreadex( 
void *security, 
unsigned stack_ size, 

unsigned (_stdcall *start_ address) (void *), 

void *arglist, 
unsigned initflag, 
unsigned *thrdid ) ; 

#else 

int FAR _ beginthread ( 

void (FAR *start_ address)(void FAR *), 
void FAR *stack_ bottom, 
unsigned stack_ size, 
void FAR *arglist ); 

#endif 

Description: The _ beginthread function is used to start a new thread of execution at the function identified by 
start_address with a single parameter identified by arglist. 

For each operating environment under which _ beginthread is supported, the_ beginthread 
function uses the appropriate system call to begin a new thread of execution. 

The new thread will use the memory identified by stack_bottom and stack_size for its stack. 

Note for 16-bit applications: If the stack is not in DGROUP (i.e., the stack pointer does not point to an 
area in DGROUP) then you must compile your application with the "zu" option. For example, the 
pointer returned by mal loc in a large data model may not be in DGROUP. The "zu" option relaxes 
the restriction that the SS register contains the base address of the default data segment, "DGROUP". 
Normally, all data items are placed into the group DGROUP and the SS register contains the base 
address of this group. In a thread, the SS register will likely not contain the base address of this group. 
When the "zu" option is selected, the SS register is volatile (assumed to point to another segment) and 
any global data references require loading a segment register such as DS with the base address of 
DGROUP. 

Note for OS/2 32-bit applications: Memory for a stack need not be provided by the application. The 
stack_bottom may be NULL in which case the run-time system will provide a stack. You must specify 
a non-zero stack_size for this stack. 

Note for Win32 applications: Memory for a stack is provided by the run-time system. The size of the 
stack is determined by stack_size and must not be zero. 

The _ beginthreadex function can be used to create a new thread, in a running or suspended state 
specified by initflag, with security attributes specified by security. 


Library Functions and Macros 87 




beginthread, _beginthreadex 


The initial state of the new thread (running or suspended ) is specified by the initflag argument. If the 
CREATE_ SUSPENDED flag (WINBASE.H) is specified, the thread is created in a suspended state, and 
will not run until the Win32 ResumeThread function is called with the thread handle as an argument. 
If this value is zero, the thread runs immediately after creation. 

The security descriptor for the new thread is specified by the security argument. This is a pointer to a 
Win32 SECURITY_ ATTRIBUTES structure (see Microsoft’s Win32 Programmer’s Reference for 
more information). For default behaviour, the security structure pointer can be NULL. 

The thread identifier is returned in the location identified by the thrdid argument. 

The thread ends when it exits from its main function or calls exit, _ Exit,_ exit*_ endthread or 
_ endthreadex. 

The variable/function _ threadid which is defined in<stddef . h> may be used by the executing 
thread to obtain its thread ID. In the 16-bit libraries, _ threadid is a far pointer to an int. In the 
32-bit libraries, it is a function that returns an int. 

There is no limit to the number of threads an application can create under Win32 platforms. 

There is a limit to the number of threads an application can create under 16-bit OS/2 and 32-bit 
NetWare. The default limit is 32. This limit can be adjusted by statically initializing the unsigned 
global variable_ MaxThreads . 

Under 32-bit OS/2, there is no limit to the number of threads an application can create. However, due 
to the way in which multiple threads are supported in the Open Watcom libraries, there is a small 
performance penalty once the number of threads exceeds the default limit of 32 (this number includes 
the initial thread). If you are creating more than 32 threads and wish to avoid this performance penalty, 
you can redefine the threshold value of 32. You can statically initialize the global variable 
_ MaxThreads. 

By adding the following line to your multi-threaded application, the new threshold value will be set to 
48. 


unsigned _MaxThreads = { 48 }; 

Returns: Under Win32, the _ beginthread function returns the thread handle for the new thread if successful; 

otherwise it returns -1 to indicate that the thread could not be started. 

Under all other systems that support the _ beginthread function (OS/2, Netware and QNX), it 
returns the thread ID for the new thread if successful; otherwise it returns -1 to indicate that the thread 
could not be started. 

The _ beginthreadex function returns the thread handle for the new thread if successful; otherwise 
it returns 0 to indicate that the thread could not be started. 

When the thread could not be started, the value of errno could be set to EAGAIN if there are too many 
threads, or to EINVAL if the argument is invalid or the stack size is incorrect, or to ENOMEM if there is 
not enough available memory. 

See Also: _ endthread 
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beginthread, _beginthreadex 


Example: #include <stdio.h> 

♦include <stdlib.h> 
♦include <stddef.h> 
♦include <malloc.h> 
♦include <process.h> 
♦include <dos.h> 


8192 

_far 

4096 


♦ if defined(_ 386_) 

♦define FAR 
♦define STACK_ SIZE 

♦ else 

♦define FAR 
♦define STACK_ SIZE 
♦endif 


static volatile int WaitForThread; 

void FAR child( void FAR *parm ) 

{ 

char * FAR *argv = (char * FAR *) parm; 
int i; 


printf ( "Child thread ID = %x\n", *_ threadid ); 
for( i = 0; argv[i]; i++ ) { 

printf( "argv[%d] = %s\n", i, argv[i] ); 

} 

WaitForThread = 0; 

_ endthread(); 
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beginthread, _beginthreadex 


Classification: 

Systems: 


void main() 

{ 

char 

#if defined (_NT 

unsigned long 
#else 

char 

int 

#endif 


*args[3]; 
_ ) 
tid; 

*stack; 

tid; 


args[0] = "child"; 
args[l] = "parm"; 
args[2] = NULL; 

WaitForThread = 1; 

#if defined (_NT_) 

tid = _ beginthread ( child, STACK_ SIZE, args ); 
printf( "Thread handle = %lx\n", tid ); 

#else 

#if defined(_ 386_ ) 

stack = (char *) malloc ( STACK_ SIZE ); 

#else 

stack = (char *) _ nmalloc ( STACK_ SIZE ); 

#endif 

tid = _ beginthread ( child, stack, STACK_ SIZE, args ); 
printf( "Thread ID = %x\n", tid ); 

#endif 

while( WaitForThread ) { 

sleep ( 0 ); 

} 

} 


WATCOM 


_beginthread - Win32, OS/2 l.x(MT), OS/2 l.x(DL), OS/2-32, Linux, 
RDOS, Netware 
_ beginthreadex - Win32 
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bessel Functions 


Synopsis: #include <math.h> 

double jO( double x ); 
double jl( double x ); 
double jn( int n, double x ); 
double yO( double x ); 
double yl( double x ); 
double yn( int n, double x ); 

Description: Functions j 0, j 1, and jn return Bessel functions of the first kind. 

Functions yO, y 1, and yn return Bessel functions of the second kind. The argument x must be positive. 

If x is negative, _ matherr will be called to print a DOMAIN error message tostderr, set errno to 
EDOM, and return the value -HUGE_ VAL. This error handling can be modified by using thematherr 
routine. 

Returns: These functions return the result of the desired Bessel function of x. 

See Also: matherr 

Example: #include <stdio.h> 

♦include <math.h> 

void main() 

1 

double x, y, z; 

x = j 0 ( 2.4 ) ; 
y = yl( 1.58 ) ; 
z = jn( 3, 2.4 ) ; 

printf( "j0(2.4) = %f, yl(1.58) = %f\n", x, y ); 
printf( "jn(3,2.4) = %f\n", z ); 

} 

Classification: WATCOM 

Systems: jO - Math 

jl - Math 
jn - Math 
yO - Math 
yl - Math 
yn - Math 
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bcmp 


Synopsis: #include <string.h> 

int bcmp(const void *sl, const void *s2, size_ t n) ; 

Description: The bcmp function compares the byte string pointed to by si to the string pointed to by s2. The number 
of bytes to compare is specified by n. Null characters may be included in the comparision. 

Note that this function is similar to the ISO C memcmp function but just tests for equality (new code 
should use the ISO C function). 

Returns: The bcmp function returns zero if the byte strings are identical; otherwise it returns 1. 

See Also: bcopy, bzero, memcmp, strcmp 

Example: ((include <stdio.h> 

♦include <string.h> 

void main() 

{ 

if( bcmp( "Hello there", "Hello world", 6 ) ) { 

printf( "Not equal\n" ); 

} else { 

printf ( "Equal\n" ); 

} 

} 

produces the following: 

Equal 

Classification: WATCOM 

Systems: All, Linux, RDOS, Netware 
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bcopy 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <string.h> 

void bcopy( const void *src, void *dst, size_ t n ); 

The bcopy function copies the byte string pointed to by src (including any null characters) into the 
array pointed to by dst. The number of bytes to copy is specified by n. Copying of overlapping objects 
is guaranteed to work properly. 

Note that this function is similar to the ISO C memmove function but the order of arguments is different 
(new code should use the ISO C function). 

The bcopy function has no return value. 

bcmp, bzero, memmove, strcpy 

♦include <stdio.h> 

♦include <string.h> 

void main() 

{ 

auto char buffer [80]; 

bcopy( "Hello ", buffer, 6 ); 

bcopy ( "world", &buffer[6], 6 ); 
printf ( "%s\n", buffer ); 

} 

produces the following: 

Hello world 
WATCOM 

All, Linux, RDOS, Netware 
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bfreeseg 


Synopsis: #include <malloc.h> 

int _ bfreeseg (_segment seg ); 

Description: The _ bfreeseg function frees a based-heap segment. 

The argument seg indicates the segment returned by an earlier call to _ bheapseg. 

Returns: The _ bfreeseg function returns 0 if successful and -1 if an error occurred. 

See Also: _ bcalloc^_ bexpancL bf ree^_ bheapseg^ bmalloc^_ brealloc 

Example: #include <stdio.h> 

♦include <stdlib.h> 

♦include <malloc.h> 

struct list { 

struct list 
int 

} ; 

void main() 

{ 

int i; 

_ segment seg; 

struct list _based(seg) *head; 

struct list _based(seg) *p; 

/* allocate based heap */ 
seg = _ bheapseg( 1024 ); 
if( seg == _ NULLSEG ) { 

printf ( "Unable to allocate based heap\n" ); 
exit ( 1 ) ; 

} 

/* create a linked list in the based heap */ 
head = 0; 

for( i = 1; i < 10; i++ ) { 

p = _bmalloc( seg, sizeof ( struct list ) ); 

if( P == _ NULLOFF ) { 

printf ( bmalloc failed\n" ); 
break; 

} 

p->next = head; 
p->value = i; 
head = p; 

} 

/* traverse the linked list, printing out values */ 
for( p = head; p != 0; p = p->next ) { 

printf( "Value = %d\n", p->value ); 

} 


_based(_self) *next; 

value; 
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bfreeseg 


/* free all the elements of the linked list */ 
for( ; p = head; ) { 

head = p->next; 

_ bfree( seg, p ); 

} 

/* free the based heap */ 

_bfreeseg( seg ); 


Classification: WATCOM 

Systems: DOS/16, Windows, OS/2 l.x(all) 
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bgetcmd 


Synopsis: 

Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


#include <process.h> 

int _ bgetcmd( char *cmd_ line, int len ); 

The _ bgetcmd function causes the command line information, with the program name removed, to be 
copied to cmdjine. The argument len specifies the size of cmd_line. The information is terminated 
with a null character. This provides a method of obtaining the original parameters to a program 
unchanged (with the white space intact). 

This information can also be obtained by examining the vector of program parameters passed to the 
main function in the program. 

The number of bytes required to store the entire command line, excluding the terminating null character, 
is returned. 

abort, atexit, exec. . ., exit, _ Exit,_ exit.getcmd, getenv, main, onexit, putenv, 
spawn. . system 

Suppose a program were invoked with the command line 

myprog arg-1 ( my stuff ) here 

where that program contains 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <process.h> 

void main( void ) 

{ 

char *cmdline; 
int cmdlen; 


cmdlen = _ bgetcmd ( NULL, 0 ) + 1; 
cmdline = malloc( cmdlen ); 


if ( 

cmdline 

!= NULL ) { 


cmdlen = 

_ bgetcmd( cmdline, cmdlen ); 

} 

printf( 

"%s\n", cmdline ); 


} 

produces the following: 

arg-1 ( my stuff ) here 
WATCOM 

All, Linux, RDOS, Netware 
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bheapseg 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


♦include <malloc.h> 

_segment _ bheapseg ( size_ t size ); 

The _ bheapseg function allocates a based-heap segment of at least size bytes. 

The argument size indicates the initial size for the heap. The heap will automatically be enlarged as 
needed if there is not enough space available within the heap to satisfy an allocation request by 
_ bcalloc,_ bexpand^ bmalloc, or_ brealloc. 

The value returned by _ bheapseg is the segment value or selector for the based heap. This value 
must be saved and used as an argument to other based heap functions to indicate which based heap to 
operate upon. 

Each call to _ bheapseg allocates a new based heap. 

The value returned by _ bheapseg is the segment value or selector for the based heap. This value 
must be saved and used as an argument to other based heap functions to indicate which based heap to 
operate upon. A special value of _ NULLSEG is returned if the segment could not be allocated. 

_ bfreeseg,_ bcalloc,_ bexpand^ bmalloc,_ brealloc 


♦include <stdio.h> 
♦include <stdlib.h> 
♦include <malloc.h> 


struct list { 

struct list_based(_self) 

int value; 

} ; 


*next; 


void main() 

{ 

int 

_segment 

struct list 
struct list 


i; 

seg; 

_based(seg) 

_based(seg) 


*head; 

*p; 


/* allocate based heap */ 
seg = _ bheapseg ( 1024 ); 
if ( seg == _ NULLSEG ) { 

printf( "Unable to allocate based heap\n" ) ; 
exit( 1 ); 

} 
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bheapseg 


Classification: 

Systems: 


/* create a linked list in the based heap */ 
head = 0; 

for( i = 1; i < 10; i++ ) { 

p = _bmalloc( seg, sizeof ( struct list ) ); 

if( P == _ NULLOFF ) { 

printf ( bmalloc failed\n" ); 
break; 

} 

p->next = head; 
p->value = i; 
head = p; 


/* traverse the linked list, printing out values */ 
for( p = head; p != 0; p = p->next ) { 

printf( "Value = %d\n", p->value ); 

} 

/* free all the elements of the linked list */ 
for( ; p = head; ) { 

head = p->next; 

_ bfree( seg, p ); 

} 

/* free the based heap */ 

_bfreeseg( seg ); 


WATCOM 

DOS/16, Windows, OS/2 l.x(all) 
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Synopsis: 


Description: 


Returns: 


bios_disk 


♦include <bios.h> 

unsigned short _bios_ disk ( unsigned service, 

struct diskinfo_ t *diskinfo ) ; 


struct diskinfo_ t { /* disk parameters */ 

unsigned drive; /* drive number */ 

unsigned head; /* head number */ 

unsigned track; /* track number */ 

unsigned sector; /* sector number */ 

unsigned nsectors; /* number of sectors */ 

void _ far *buffer; /* buffer address */ 

} ; 


The _ bios_ disk function uses INT 0x13 to provide access to the BIOS disk functions. Information 
for the desired sendee is passed the diskinf o_ t structure pointed to by diskinfo. The value for 
sendee can be one of the following values: 


Value 

Meaning 

_DISK_RESET 

Forces the disk controller to do a reset on the disk. This request does not use the 
diskinfo argument. 

_DISK_S TA TUS 

Obtains the status of the last disk operation. 

_DISK_READ 

Reads the specified number of sectors from the disk. This request uses all of the 
information passed in the diskinfo structure. 

_DISK_WRITE 

Writes the specified amount of data to the disk. This request uses all of the 
information passed in the diskinfo structure. 

_DISK_VERIF Y 

Checks the disk to be sure the specified sectors exist and can be read. A CRC 
(cyclic redundancy check) test is performed. This request uses all of the 
information passed in the diskinfo structure except for the buffer field. 


_DISK_FORMAT Formats the specified track on the disk. The head and track fields indicate the 
track to be formatted. Only one track can be formatted per call. The buffer field 
points to a set of sector markers, whose format depends on the type of disk drive. 
This service has no return value. 

This function is not supported by DOS/4GW (you must use the Simulate Real-Mode Interrupt DPMI 
call). 

The _ bios_ disk function returns status information in the high-order byte when sendee is 
_DISK_STATUS, _DISK_READ, _DISK_WRITE, or _DISK_VERIFY. The possible values are: 


Value 

Meaning 

0x00 

Operation successful 

0x01 

Bad command 

0x02 

Address mark not found 

0x03 

Attempt to write to write-protected disk 

0x04 

Sector not found 

0x05 

Reset failed 
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bios_disk 


Example: 


Classification: 

Systems: 


0x06 

Disk changed since last operation 

0x07 

Drive parameter activity failed 

0x08 

DMA overrun 

0x09 

Attempt to DMA across 64K boundary 

OxOA 

Bad sector detected 

OxOB 

Bad track detected 

OxOC 

Unsupported track 

0x10 

Data read (CRC/ECC) error 

Oxll 

CRC/ECC corrected data error 

0x20 

Controller failure 

0x40 

Seek operation failed 

0x80 

Disk timed out or failed to respond 

OxAA 

Drive not ready 

OxBB 

Undefined error occurred 

OxCC 

Write fault occurred 

OxEO 

Status error 

OxFF 

Sense operation failed 

♦include 

<stdio.h> 

♦include 

<bios.h> 

void main() 


{ 

struct diskinfo_ t di; 
unsigned short status; 


di.drive = di.head = di.track = di.sector = 0; 
di.nsectors = 1; 
di.buffer = NULL; 

status = _ bios_ disk ( _ DISK_ VERIFY, &di ); 
printf ( "Status = 0x%4.4X\n", status ); 

} 

BIOS 

DOS. Windows, Win386 
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bios_equiplist 


Synopsis: 

Description: 

Returns: 


Example: 


Classification: 

Systems: 


#include <bios.h> 

unsigned short _ bios_ equiplist( void ) ; 

The _ bios_ equiplist function uses INT Oxll to determine what hardware and peripherals are 
installed on the machine. 

The _ bios_ equiplist function returns a set of bits indicating what is currently installed on the 
machine. Those bits are defined as follows: 


Bit Meaning 


bit 0 
bit 1 
bits 2-3 
bits 4-5 
bits 6-7 
bit 8 
bits 9-11 
bit 12 
bit 13 
bits 14-15 


Set to 1 if system boots from disk 

Set to 1 if a math coprocessor is installed 

Indicates motherboard RAM size 

Initial video mode 

Number of diskette drives 

Set to 1 if machine does not have DMA 

Number of serial ports 

Set to 1 if a game port is attached 

Set to 1 if a serial printer is attached 

Number of parallel printers installed 


♦include <stdio.h> 

♦include <bios.h> 

void main() 

{ 

unsigned short equipment; 
equipment = _ bios_ equiplist () ; 

printf ( "Equipment flags = 0x%4.4X\n", equipment ); 

} 


BIOS 


DOS, Windows, Win386 
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bios_keybrd 


Synopsis: #include <bios.h> 

unsigned short _ bios_ keybrd( unsigned service ); 

Description: The _ bios_ keybrd function uses INT 0x16 to access the BIOS keyboard services. The possible 
values for service are the following constants: 

Constant Meaning 

_KEYBRD_READ Reads the next character from the keyboard. The function will wait until 

a character has been typed. 

KE YBRD READ Y Checks to see if a character has been typed. If there is one, then its value 

will be returned, but it is not removed from the input buffer. 

_KEYBRD_SHIFTSTATUS Returns the current state of special keys. 

JVKEYBRD_READ Reads the next character from an enhanced keyboard. The function will 

wait until a character has been typed. 

JVKEYBRD_READY Checks to see if a character has been typed on an enhanced keyboard. If 

there is one, then its value will be returned, but it is not removed from the 
input buffer. 

NKE YB RDJS11 IF TSTA T US Returns the current state of special keys on an enhanced keyboard. 

Returns: The return value depends on the service requested. 

The _ KEYBRD_ READ and_ NKEYBRD_ READ services return the character’s ASCII value in the 
low-order byte and the character’s keyboard scan code in the high-order byte. 

The _ KEYBRD_ READY and_ NKEYBRD_ READY services return zero if there was no character 
available, otherwise it returns the same value returned by _ KEYBRD_ READ and. NKEYBRD_ READ. 

The shift status is returned in the low-order byte with one bit for each special key defined as follows: 

Bit Meaning 

bit 0 (0x01) Right SHIFT key is pressed 

bit 1 (0x02) Left SHIFT key is pressed 
bit 2 (0x04) CTRL key is pressed 
bit 3 (0x08) ALT key is pressed 

bit 4 (0x10) SCROLL LOCK is on 

bit 5 (0x20) NUM LOCK is on 

bit 6 (0x40) CAPS LOCK is on 

bit 7 (0x80) Insert mode is set 

Example: #include <stdio.h> 

♦include <bios.h> 

void main() 

{ 

unsigned short key_ state; 
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bios_keybrd 


Classification: 

Systems: 


key_ state = _ bios_ keybrd ( _ KEYBRD_ SHIFTSTATUS ); 
if( key_ state & 0x10 ) 

printf ( "SCROLL LOCK is on\n" ); 
if( key_ state & 0x20 ) 

printf ( "NUM LOCK is on\n" ); 
if( key_ state & 0x40 ) 

printf ( "CAPS LOCK is on\n" ); 


produces the following: 
NUM LOCK is on 

BIOS 

DOS, Windows, Win386 
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bios memsize 


Synopsis: 

Description: 

Returns: 


#include <bios.h> 

unsigned short _ bios_ memsize ( void ) ; 

The _ bios_ memsize function uses INT 0x12 to determine the total amount of memory available. 

The _ bios_ memsize function returns the total amount of IK blocks of memory installed (maximum 
640). 


Example: ((include <stdio.h> 

((include <bios.h> 


void main() 

{ 

unsigned short memsize; 


} 


memsize = _ bios_ memsize (); 
printf ( "The total amount of memory is: 
memsize ); 


%dK\n", 


produces the following: 

The total amount of memory is: 640K 

Classification: BIOS 

Systems: DOS, Windows, Win386 
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bios_printer 


Synopsis: #include <bios.h> 

unsigned short _ bios_ printer( unsigned service, 

unsigned port, 
unsigned data ); 

Description: The _ bios_ printer function uses INT 0x17 to perform printer output services to the printer 
specified by port. The values for service are: 

Value Meaning 

_PRINTER_WRITE Sends the low-order byte of data to the printer specified by port. 

_PRINTER_INIT Initializes the printer specified by port. 

_PRINTER_STATUS Get the status of the printer specified by port. 

Returns: The _ bios_ printer function returns a printer status byte defined as follows: 

Bit Meaning 

bit 0 (0x01 ) Printer timed out 

bits 1-2 Unused 

bit 3 (0x08) I/O error 

bit 4 ( 0x10) Printer selected 

bit 5 (0x20) Out of paper 

bit 6 ( 0x40) Printer acknowledge 

bit 7 (0x80) Printer not busy 

Example: #include <stdio.h> 

♦include <bios.h> 

void main() 

{ 

unsigned short status; 

status = _ bios_ printer ( _ PRINTER_ STATUS, 1, 0 ); 
printf( "Printer status: 0x%2.2X\n", status ); 

} 

Classification: BIOS 

Systems: DOS, Windows, Win386 
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bios serialcom 


Synopsis: 


Description: 


Returns: 


#include <bios.h> 

unsigned short _ bios_ serialcom( unsigned service, 

unsigned serial_port, 
unsigned data ) ; 

The _ bios_ serialcom function uses INT 0x14 to provide serial communications services to the 
serial port specified by serial_port. 0 represents COM1, 1 represents COM2, etc. The values for 
service are: 


Value 

jCOMJNIT 

_COM_SEND 

_COM_RECEIVE 

_COM_STATUS 


Meaning 

Initializes the serial port to the parameters specified in data. 
Transmits the low-order byte of data to the serial port. 
Reads an input character from the serial port. 

Returns the current status of the serial port. 


The value passed in data for the _ COM_ INIT service can be built using the appropriate combination of 
the following values: 


Value 

Meaning 

JCOMJIO 

110 baud 

_COM_150 

150 baud 

_COM_300 

300 baud 

_COM_600 

600 baud 

JCOMJ200 

1200 baud 

_COM_2400 

2400 baud 

_COM_4800 

4800 baud 

_COM_9600 

9600 baud 

_COM_NOPARITY 

No parity 

_COM_EVENPARITY 

Even parity 

_COM_ODDPARITY 

Odd parity 

_COM_CHR7 

7 data bits 

_COM_CHR8 

8 data bits 

_COM_STOPl 

1 stop bit 

_COM_STOP2 

2 stop bits 


The _ bios_ serialcom function returns a 16-bit value with the high-order byte containing status 
information defined as follows: 


Bit 


Meaning 


bit 15 (0x8000) 
bit14 (0x4000) 
bit 13 (0x2000) 


Timed out 

Transmit shift register empty 
Transmit holding register empty 
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bios serialcom 


bit 12 (0x1000) Break detected 

bit 11 (0x0800) Framing error 

bit 10 (0x0400) Parity error 

bit 9 (0x0200) Overrun error 

bit 8 (0x0100) Data ready 

The low-order byte of the return value depends on the value of the service argument. 

When service is _COM_SEND, bit 15 will be set if the data could not be sent. If bit 15 is clear, the 
return value equals the byte sent. 

When sendee is _COM_RECEIVE, the byte read will be returned in the low-order byte if there was no 
error. If there was an error, at least one of the high-order status bits will be set. 

When sendee is _COM_INIT or _COM_STATUS the low-order bits are defined as follows: 

Bit Meaning 

bit 0 (0x01) Clear to send (CTS) changed 

bit 1 (0x02) Data set ready changed 

bit 2 (0x04) Trailing-edge ring detector 

bit 3 (0x08) Receive line signal detector changed 

bit 4 (0x10) Clear to send 

bit 5 (0x20) Data-set ready 

bit 6 (0x40) Ring indicator 

bit 7 (0x80) Receive-line signal detected 

Example: #include <stdio.h> 

♦include <bios.h> 

void main() 

{ 

unsigned short status; 

status = _ bios_ serialcom ( _ COM_ STATUS, 1, 0 ); 
printf( "Serial status: 0x%2.2X\n", status ); 

} 

Classification: BIOS 

Systems: DOS, Windows, Win386 
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biosjimeofday 


Synopsis: 

Description: 


Returns: 

Example: 


Classification: 

Systems: 


♦include <bios.h> 

int _ bios_ timeofday ( int service, long *timeval ); 

The _ bios_ timeof day function uses INT OxlA to get or set the current system clock value. The 
values for service are: 

Value Meaning 

_TIME_GETCLOCK Places the current system clock value in the location pointed to by timeval. The 
function returns zero if midnight has not passed since the last time the system 
clock was read or set; otherwise, it returns 1. 

_TIME_SETCLOCK Sets the system clock to the value in the location pointed to by timeval. 

A value of -1 is returned if neither _TIME_GETCLOCK nor _TIME_SETCLOCK were specified; 
otherwise 0 is returned. 

♦include <stdio.h> 

♦include <bios.h> 

void main() 

{ 

long time_ of_ day; 

_ bios_ timeofday ( _ TIME_ GETCLOCK, &time_ of_ day ) ; 
printf( "Ticks since midnight: %lu\n", time_ of_ day ); 

} 

produces the following: 

Ticks since midnight: 762717 

BIOS 

DOS, Windows, Win386 


108 Library Functions and Macros 




Synopsis: 

Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


bprintf, _bwprintf 


♦include <stdio.h> 

int _ bprintf( char *buf, size_ t bufsize, 
const char *format, ... ); 
int _ bwprintf( wchar_ t *buf, size_ t bufsize, 
const wchar_ t *format, ... ); 

The _ bprintf function is equivalent to thesprintf function, except that the argument bufsize 
specifies the size of the character array buf'mio which the generated output is placed. A null character 
is placed at the end of the generated character string. The format string is described under the 
description of the print f function. 

The _ bwprintf function is a wide-character version of_ bprintf. It accepts a wide-character 
string argument for format and produces wide character output. The argument buf specifies an array of 
wide characters into which the generated output is to be written, rather than converted to multibyte 
characters and written to a stream. 

The _ bprintf function returns the number of characters written into the array, not counting the 
terminating null character. The _ bwprintf function returns the number of wide characters written 
into the array, not counting the terminating null character. An error can occur while converting a value 
for output. When an error has occurred, errno contains a value indicating the type of error that has 
been detected. 

cprintf, fprintf, printf, sprintf, _ vbprintf.vcprintf, vfprintf, vprintf, 
vsprintf 

♦include <stdio.h> 

void main( int argc, char *argv[] ) 

{ 

char f ile_ name [ 9 ] ; 
char file_ext[4]; 

_ bprintf( file_ name, 9, "%s", argv[l] ); 

_ bprintf ( file_ext, 4, "%s", argv[2] ); 

printf ( "%s.%s\n", file_ name, file_ ext ); 

} 

WATCOM 

_ bprintf - All, Linux, RDOS, Netware 
_ bwprintf - All, Linux 
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break... Functions 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <stdlib.h> 
void break_ off( void ); 
void break_ on( void ); 

The break_ off function can be used with DOS to restrict break checking (Ctrl+C, Ctrl+Break) to 
screen output and keyboard input. The break_ on function can be used with DOS to add break 
checking (Ctrl+C, Ctrl+Break) to other activities such as disk file input/output. 

The break_ off andbreak_ on functions to not return anything. 

signal 

♦include <stdio.h> 

♦include <stdlib.h> 

void main() 

{ 

long i; 

FILE *tmpf; 

tmpf = tmpfileO; 
if( tmpf != NULL ) { 

printf ( "Start\n" ); 
break_ of f () ; 

for( i = 1; i < 100000; i++ ) 
fprintf ( tmpf, "%ld\n", i ); 
break_ on () ; 
printf ( "Finish\n" ); 

} 

} 

DOS 

break_ off - DOS, Windows, Win386 
break_ on - DOS, Windows, Win386 
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bsearch 


Synopsis: 


Safer C: 

Description: 


Returns: 

See Also: 
Example: 


#include <stdlib.h> 
void *bsearch( const void *key, 
const void *base, 
size_ t num, 
size_ t width, 

int (*compar)( const void *pkey, 

const void *pbase) ); 

The Safer C Library extension provides the bsearch_ s function which is a safer alternative to 
bsearch This newer bsearch_ s function is recommended to be used instead of the traditional 
"unsafe" bsearch function. 

The bsearch function performs a binary search of a sorted array of num elements, which is pointed to 
by base, for an item which matches the object pointed to by key. Each element in the array is width 
bytes in size. The comparison function pointed to by compar is called with two arguments that point to 
elements in the array. The first argument pkey points to the same object pointed to by key. The second 
argument phase points to a element in the array. The comparison function shall return an integer less 
than, equal to, or greater than zero if the key object is less than, equal to, or greater than the element in 
the array. 

The bsearch function returns a pointer to the matching member of the array, or NULL if a matching 
object could not be found. If there are multiple values in the array which are equal to the key, the return 
value is not necessarily the first occurrence of a matching value when the array is searched linearly. 

bsearch_ s,lfind, lsearch, qsort, qsort_ s 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <string.h> 

static const char *keywords[] = { 

"auto", 

"break", 

"case", 

"char", 

/* . */ 

/* . */ 

/* . */ 

"while" 

}; 

♦ define NUM_ KW sizeof(keywords) / sizeof(char *) 

int kw_ compare( const void *pl, const void *p2 ) 

{ 

const char *plc = (const char *) pi; 
const char **p2c = (const char **) p2; 
return ( strcmp( pic, *p2c ) ); 

} 
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bsearch 


Classification: 

Systems: 


int keyword_ lookup( const char *name ) 

{ 

const char **key; 

key = (char const **) bsearch( name, keywords, NUM_ 
sizeof( char * ), kw_ compare ); 
if( key == NULL ) return ( -1 ); 
return key - keywords; 

} 


void main() 

{ 

printf ( "%d\n", keyword_ lookup( 
printf ( "%d\n", keyword_ lookup( 
printf ( "%d\n", keyword_ lookup( 

} 

//************ sample program output 

111 

II -1 

I/O 


"case" ) ); 

"crigger" ) ); 

"auto" ) ) ; 


produces the following: 
2 

-1 

0 


ISOC 

All, Linux, RDOS, Netware 


KW, 
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bsearch s 


Synopsis: 


Constraints: 


Description: 


Returns: 

See Also: 
Example: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdlib.h> 

void *bsearch_ s ( const void *key, 
const void *base, 
rsize_ t nmemb, 
rsize_ t size, 

int (*compar)( const void *k, const void *y, void *context ), 
void *context ); 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and bsearch_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither nmemb nor size shall be greater than RSIZE_ MAX. If nmemb is not equal to zero, then none of 
key, base , or compar shall be a null pointer. If there is a runtime-constraint violation, the bsearch_ s 
function does not search the array. 

The bsearch_ s function searches an array of nmemb objects, the initial element of which is pointed 
to by base, for an element that matches the object pointed to by key. The size of each element of the 
array is specified by size. The comparison function pointed to by compar is called with three 
arguments. The first two point to the key object and to an array element, in that order. The function 
shall return an integer less than, equal to, or greater than zero if the key object is considered, 
respectively, to be less than, to match, or to be greater than the array element. The array shall consist 
of: all the elements that compare less than, all the elements that compare equal to, and all the elements 
that compare greater than the key object, in that order. The third argument to the comparison function 
is the context argument passed to bsearch_ s The sole use of context bybsearch_ s is to pass it to 
the comparison function. 

The bsearch_ s function returns a pointer to a matching element of the array,or a null pointer if no 
match is found or there is a runtime-constraint violation. If two elements compare as equal, which 
element is matched is unspecified. 

bsearch, lfind, lsearch, qsort, qsort_ s 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <string.h> 

static const char *keywords[] = { 

"auto", 

"break", 

"case", 

"char", 

/* . */ 

/* . */ 

/* . */ 

"while" 

} ; 

static void * context = NULL; 

♦define NUM_ KW sizeof(keywords) / sizeof(char *) 
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bsearch s 


int kw_ compare( const void *pl, const void *p2, void *context ) 

{ 

const char *plc = (const char *) pi; 
const char **p2c = (const char **) p2; 
return( strcmp( pic, *p2c ) ); 

} 

int keyword_ lookup ( const char *name ) 

{ 

const char **key; 

key = (char const **) bsearch_ s ( name, keywords, NUM_ KW, 
sizeof ( char * ), kw_ compare, context ); 
if( key == NULL ) return ( -1 ) ; 
return key - keywords; 

} 

int main() 

{ 

printf( "%d\n", keyword_ lookup ( "case" ) ); 

printf ( "%d\n", keyword_ lookup( "crigger" ) ); 

printf ( "%d\n", keyword_ lookup( "auto" ) ); 

return 0; 

} 

//************ sample program output ************ 

in 

//-i 

//o 

produces the following: 

2 

-1 

0 

Classification: TR 24731 

Systems: All, Linux, RDOS, Netware 
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btowc 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <wchar.h> 
wint_ t btowc ( int c ) ; 

The btowc function determines whether c is a valid single-byte character in the initial shift state. 

The btowc function returns WEOF if c has the value EOF or if (unsigned char)c does not constitute a 
valid single-byte character in the initial shift state. Otherwise, btowc returns the wide character 
representation of that character. 

_ mbccmp,_ mbccpy,_ mbcicmp,_ mbcjistojms,_ mbc jmsto jis,_ mbclen^_ mbctohira, 
_ mbctokata,_ mbctolower^. mbctombb,_ mbctoupperjnblen, mbrlen, mbrtowc, 
mbsrtowcs, mbsrtowcs_ sjnbstowcs, mbstowcs_ s,mbtowc, wcrtomb, wcrtomb_ s, 
wcsrtombs, wcsrtombs_ s,wcstombs, wcstombs_ s,wctob, wctomb, wctomb_ s 

♦include <stdio.h> 

♦include <wchar.h> 

void main( void ) 

{ 

printf ( "EOF is %sa valid single-byte characterin' 1 , 
btowc( EOF ) == WEOF ? "not " : "" ); 

} 

produces the following: 

EOF is not a valid single-byte character 
ISOC 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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bzero 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <string.h> 

void bzero( void *dst, size_ t n ); 

The bzero function fills the first n bytes of the object pointed to by dst with zero (null) bytes. 

Note that this function is similar to the ISO C memset function (new code should use the ISO C 
function). 

The bzero function has no return value, 
bcmp, bcopy, memset, strset 
♦include <string.h> 

void main() 

{ 

char buffer[80]; 
bzero ( buffer, 80 ); 

} 

WATCOM 

All, Linux, RDOS, Netware 
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cabs 


Synopsis: 


Description: 

Returns: 

Example: 


Classification: 

Systems: 


♦include <math.h> 

double cabs( struct complex value ) ; 

struct _ complex { 

double x; /* real part */ 
double y; /* imaginary part */ 

} ; 


The cabs function computes the absolute value of the complex number value by a calculation which is 
equivalent to 

sqrt( (value.x*value.x) + (value.y*value.y) ) 

In certain cases, overflow errors may occur which will cause the matherr routine to be invoked. 

The absolute value is returned. 

♦include <stdio.h> 

♦include <math.h> 

struct _ complex c = { -3.0, 4.0 }; 

void main() 

{ 

printf( "%f\n", cabs( c ) ); 

} 

produces the following: 

5.000000 

WATCOM 

Math 
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calloc Functions 


Synopsis: #include <stdlib.h> For ISO C compatibility (calloc only) 

♦include <malloc.h> Required for other function prototypes 
void *calloc( size_ t n, size_ t size ); 

void_based (void) *_ bcalloc(_segment seg, 

size_ t n, 
size_ t size ) ; 

void_far *_ fcalloc ( size_ t n, size_ t size ); 

void_near *_ ncalloc ( size_ t n, size_ t size ); 

Description: The calloc functions allocate space for an array of n objects, each of length size bytes. Each element is 
initialized to 0. 

Each function allocates memory from a particular heap, as listed below: 

Function Heap 

calloc Depends on data model of the program 

_bcalloc Based heap specified by seg value 

_fcalloc Far heap (outside the default data segment) 

jicalloc Near heap (inside the default data segment) 

In a small data memory model, the calloc function is equivalent to the _ ncalloc function; in a large 
data memory model, the calloc function is equivalent to the _ fcalloc function. 

A block of memory allocated should be freed using the appropriate free function. 

Returns: The calloc functions return a pointer to the start of the allocated memory. The return value is NULL 

(_ NULLOFF for_ bcalloc) if there is insufficient memory available or if the value of the size 
argument is zero. 

See Also: _ expand Functions,f ree Functions, halloc, hf ree, malloc Functions, _ msize Functions, 

realloc Functions, sbrk 

Example: ((include <stdlib.h> 

void main() 

{ 

char *buffer; 

buffer = (char *)calloc( 80, sizeof(char) ); 

} 

Classification: ISO C 

_bcalloc is WATCOM 
_fcalloc is WATCOM 
_ncalloc is WATCOM 

Systems: calloc - All, Linux, RDOS, Netware 

_bcalloc - DOS/16, Windows, OS/2 l.x(all) 

_ fcalloc - DOS/16, Windows, OS/2 l.x(all) 
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calloc Functions 


_ ncalloc 
OS/2-32, 


- DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 l.x(MT), 
Linux, RDOS 
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cbrt 

Synopsis: 

Description: 

Returns: 

Example: 


Classification: 

Systems: 


#include <math.h> 
double cbrt( double x ) ; 

The cbrt function computes the cubed root of the argument x. 

The cubed root of the value. 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", cbrt ( 8.0 ) ); 

} 

produces the following: 

2.000000 
ISO C99 
Math 
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ceil 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double ceil ( double x ); 

The ceil function (ceiling function) computes the smallest integer not less than x. 

The ceil function returns the smallest integer not less than x, expressed as a double . 
floor 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f %f %f %f %f\n", ceil ( -2.1 ), ceil ( -2. ), 
ceil( 0.0 ), ceil ( 2. ), ceil ( 2.1 ) ); 

} 

produces the following: 

-2.000000 -2.000000 0.000000 2.000000 3.000000 

ISOC 

Math 
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cgets 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <conio.h> 

char *cgets( char *buf ) ; 

The cgets function gets a string of characters directly from the console and stores the string and its 
length in the array pointed to by buf. The first element of the array buf[0] must contain the maximum 
length in characters of the string to be read. The array must be big enough to hold the string, a 
terminating null character, and two additional bytes. 

The cgets function reads characters until a carriage-return line-feed combination is read, or until the 
specified number of characters is read. The string is stored in the array starting at buf,[2], The 
carriage-return line-feed combination, if read, is replaced by a null character. The actual length of the 
string read is placed in buf[ 1 ]. 

The cget s function returns a pointer to the start of the string which is at buf[2], 

fgets, getch, getche, gets 

♦include <conio.h> 

void main() 

{ 

char buffer[82]; 

buffer[0] = 80; 
cgets ( buffer ); 

cprintf ( "%s\r\n", &buffer[2] ); 

} 

WATCOM 

All, Linux, RDOS, Netware 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


chainjntr 


#include <dos.h> 

void _ chain_ intr ( void (_interrupt_far *func) () ); 

The _ chain_ intr function is used at the end of an interrupt routine to start executing another 
interrupt handler (usually the previous handler for that interrupt). When the interrupt handler 
designated by func receives control, the stack and registers appear as though the interrupt just occurred. 

The _ chain_ intr function does not return. 

_ dos_ getvect^ dos_ keep^ dos_ setvect 

♦include <stdio.h> 

♦include <dos.h> 

volatile int clock_ ticks; 

void (_interrupt_far *prev_ int_ lc) () ; 

♦define BLIP_ COUNT (5*18) /* 5 seconds */ 

void_interrupt_far timer_ rtn () 

{ 

++clock_ ticks; 

_ chain_ intr ( prev_ int_ lc ) ; 

} 

int delays = 0; 

int compile_ a_ line () 

{ 

if( delays > 15 ) return( 0 ); 

delay( 1000 ); /* delay for 1 second */ 

printf( "Delayed for 1 second\n" ); 

delays++; 

return( 1 ); 

} 

void main() 

{ 

prev_ int_ lc = _ dos_ getvect ( Oxlc ) ; 

_ dos_ setvect ( Oxlc, timer_ rtn ); 
while! compile_ a_ line() ) { 

if( clock_ ticks >= BLIP_ COUNT ) { 

putchar( ' ) ; 

clock_ ticks -= BLIP_ COUNT; 

} 

} 

_ dos_ setvect ( Oxlc, prev_ int_ lc ); 

} 

WATCOM 
DOS, Windows 
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chdir, _chdir, _wchdir 


Synopsis: 

Description: 


Returns: 

Errors: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <sys/types.h> 

♦include <direct.h> 

int chdir( const char *path ); 

int _ chdir( const char *path ); 

int _ wchdir ( const wchar_ t *path ) ; 

The chdir function changes the current directory on the specified drive to the specified path. If no 
drive is specified in path then the current drive is assumed. The path can be either relative to the 
current directory on the specified drive or it can be an absolute path name. 

Each drive under DOS, OS/2 or Windows has a current directory. The current working directory is the 
current directory of the current drive. If you wish to change the current drive, you must use the 
_ dos_ setdrive function. 

The _ chdir function is identical tochdir. Use _ chdir for ANSI naming conventions. 

The _ wchdir function is a wide-character version of chdir that operates with wide-character strings. 

The chdir function returns zero if successful. Otherwise, -1 is returned, errno is set to indicate the 
error, and the current working directory remains unchanged. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

ENOENT The specified path does not exist or path is an empty string. 

chmod, _ dos_ setdrivegetcwd, mkdir, rmdir, stat, umask 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <direct.h> 

void main( int argc, char *argv[] ) 

{ 

if( argc != 2 ) { 

fprintf( stderr, "Use: cd <directory>\n" ); 
exit ( 1 ); 

} 

if( chdir( argv[l] ) == 0 ) { 

printf ( "Directory changed to %s\n", argv[l] ); 
exit ( 0 ); 

} else { 

perror ( argv[l] ); 
exit ( 1 ); 

} 

} 

POSIX 1003.1 

_chdir conforms to ANSI naming conventions 
_wchdir is WATCOM 

chdir - All, Linux, RDOS, Netware 
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chdir, _chdir, _wchdir 


chdir - All, RDOS, Netware 

wchdir - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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chdrive 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <direct.h> 

void _ chdrive ( int drive ) ; 

The _ chdrive function changes the current working drive to the one specified by drive. A value of 1 
is drive A, 2 is drive B, 3 is drive C, etc. 

The _ chdrive function returns zero if drive is successfully changed. Otherwise, -1 is returned. 

_ dos_ getdrive^. dos_ setdrive^, getdrive 

#include <stdio.h> 

♦include <direct.h> 


void main( void ) 

{ 

int drive = 3; 


} 


if ( _ chdrive( drive ) == 0 ) 

printf ( "Changed the current drive to %c\n", 
'A' + drive - 1 ); 


produces the following: 

Changed the current drive to C 


DOS 


DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS, DOS/PM 
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chmod, _chmod, _wchmod 


Synopsis: #include <sys/types,h> 

♦include <sys/stat.h> 

♦include <io.h> 

int chmod( const char *path, int permission ); 

int _ chmod( const char *path, int permission ); 

int _ wchmod( const wchar_t *path, int permission ); 

Description: The chmod function changes the permissions for a file specified by path to be the settings in the mode 
given by permission. The access permissions for the file or directory are specified as a combination of 
bits (defined in the <sys/stat. h> header file). 

The following bits define permissions for the owner. 

Permission Meaning 

S_IRWXU Read, write, execute/search 

S_IRUSR Read permission 

S_IWUSR Write permission 

S_IXUSR Execute/search permission 

The following bits define permissions for the group. 

Permission Meaning 

S_IRWXG Read, write, execute/search 

S_IRGRP Read permission 

S_IWGRP Write permission 

S_IXGRP Execute/search permission 

The following bits define permissions for others. 

Permission Meaning 

S_IRWXO Read, write, execute/search 

S_IROTH Read permission 

S_IWOTH Write permission 

S_IXOTH Execute/search permission 

The following bits define miscellaneous permissions used by other implementations. 

Permission Meaning 

SJREAD is equivalent to S_IRUSR (read permission) 

SJWRITE is equivalent to S_IWUSR (write permission) 

S_IEXEC is equivalent to S_IXUSR (execute/search permission) 

Upon successful completion, the chmod function will mark for update the st_ctime field of the file. 

The _ chmod function is identical tochmod. Use _ chmod for ANSI naming conventions. 

The _ wchmod function is a wide-character version of chmod that operates with wide-character strings. 
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chmod, _chmod, _wchmod 


Returns: The chmod returns zero if the new settings are successfully made; otherwise, -1 is returned and errno 

is set to indicate the error. 

Errors: When an error has occurred, errno contains a value indicating the type of error that has been detected. 

Constant Meaning 

EACCES Search permission is denied for a component of path. 

ENOENT The specified path does not exist or path is an empty string. 

See Also: fstat, open, sopen, stat 

Example: /* 

* change the permissions of a list of files 

* to be read/write by the owner only 
*/ 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <sys/types.h> 

♦include <sys/stat.h> 

♦include <io.h> 

void main( int argc, char *argv[] ) 

{ 

int i; 

int ecode = 0; 

for( i = 1; i < argc; i++ ) { 

if ( chmod ( argv[i], S_ IRUSR | S_ IWUSR ) == -1 ) { 

perror( argv[i] ); 
ecode++; 

} 

} 

exit( ecode ); 

} 

Classification: POSIX 1003.1 

_chmod conforms to ANSI naming conventions 
_wchmod is WATCOM 

Systems: chmod - All, Linux, RDOS, Netware 

_ chmod - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS 
_ wchmod - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 


128 Library Functions and Macros 




chsize, _chsize 


Synopsis: #include <io.h> 

int chsize( int handle, long size ) ; 
int _ chsize( int handle, long size ); 

Description: The chsize function changes the size of the file associated with handle by extending or truncating the 
file to the length specified by size. If the file needs to be extended, the file is padded with NULL (’\0’) 
characters. 

The _ chsize function is identical tochsize. Use _ chsize for ANSI naming conventions. 

Returns: The chsize function returns zero if successful. A return value of -1 indicates an error, and errno is 

set to indicate the error. 

Errors: When an error has occurred, errno contains a value indicating the type of error that has been detected. 

Constant Meaning 

EACCES The specified file is locked against access. 

EBADF Invalid file handle. 

ENOSPC Not enough space left on the device to extend the file. 

See Also: close, creat, open 

Example: #include <stdio.h> 

♦include <io.h> 

♦include <fcntl.h> 

♦include <sys/stat.h> 

void main() 

{ 

int handle; 

handle = open ( "file", 0_ RDWR | 0_ CREAT, 

S_ IRUSR | S_ IWUSR | S_ IRGRP | S_ IWGRP ); 
if( handle != -1 ) { 

if( chsize( handle, 32 * 1024L ) != 0 ) { 

printf( "Error extending file\n" ) ; 

} 

close ( handle ); 

} 

} 

Classification: WATCOM 

_chsize conforms to ANSI naming conventions 

Systems: chsize - All, Linux, RDOS, Netware 

_ chsize - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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clear87 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <float.h> 

unsigned int _ clear87 ( void ); 

The _ clear 8 7 function clears the floating-point status word which is used to record the status of 
8087/80287/80387/80486 floating-point operations. 

The _ clear 8 7 function returns the old floating-point status. The description of this status is found in 
the <f loat. h> header file. 

_ control87 1 _ controlfp,_ finite^ fpreset^ status87 

♦include <stdio.h> 

♦include <float.h> 

void main() 

{ 

unsigned int fp_ status; 

fp_ status = _ clear87 () ; 

printf ( "80x87 status =" ); 
if( fp_ status & SW_ INVALID ) 
printf ( " invalid" ); 
if ( fp_ status & SW_ DENORMAL ) 
printf ( " denormal" ); 
if ( fp_ status & SW_ ZERODIVIDE ) 
printf ( " zero_ divide" ); 
if ( fp_ status & SW_ OVERFLOW ) 
printf ( " overflow" ); 
if ( fp_ status & SW_ UNDERFLOW ) 
printf ( " underflow" ); 
if ( fp_ status & SW_ INEXACT ) 

printf ( " inexact_ result" ); 
printf ( "\n" ); 

} 

Intel 

Math 
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clearenv 


Synopsis: 

Description: 

Returns: 

Errors: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <env.h> 
int clearenv( void ); 

The clearenv function clears the process environment area. No environment variables are defined 
immediately after a call to the clearenv function. Note that this clears the PATH, COMSPEC, and TZ 
environment variables which may then affect the operation of other library functions. 

The clearenv function may manipulate the value of the pointer environ. 

The clearenv function returns zero upon successful completion. Otherwise, it will return a non-zero 
value and set errno to indicate the error. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

ENOMEM Not enough memory to allocate a control structure. 

exec. . ., getenv, getenv_ s,putenv, _ searchenv,setenv, spawn. . ., system 

The following example clears the entire environment area and sets up a new TZ environment variable. 

♦include <env.h> 

void main() 

{ 

clearenv(); 

setenv( "TZ", "EST5EDT", 0 ); 

} 

WATCOM 

All, Linux, RDOS, Netware 
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clearerr 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <stdio.h> 

void clearerr( FILE *fp ); 

The clearerr function clears the end-of-file and error indicators for the stream pointed to by fp. 
These indicators are cleared only when the file is opened or by an explicit call to the clearerr or 
rewind functions. 

The clearerr function returns no value, 
feof, ferror, perror, strerror 
♦include <stdio.h> 

void main() 

{ 

FILE *fp; 
int c; 

c = ' J' ; 

fp = fopen( "file", "w" ); 
if ( fp != NULL ) { 

fputc ( c, fp ); 

if( ferror( fp ) ) { /* if error */ 

clearerr( fp ); /* clear the error */ 

fputc ( c, fp ); /* and retry it */ 

1 

} 

1 

ISOC 

All, Linux, RDOS, Netware 
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clearscreen 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <graph.h> 

void _ FAR _ clearscreen( short area ); 

The _ clearscreen function clears the indicated area and fills it with the background color. The 
area argument must be one of the following values: 

JGCLEARSCREEN area is entire screen 

_G VIE WPOR T area is current viewport or clip region 

_GWINDOW area is current text window 

The _ clearscreen function does not return a value. 

_ setbkcolor^ setviewport,_ setcliprgn,_ settextwindow 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

_ setvideomode( _ VRES16C0L0R ); 

_ rectangle! _ GFILLINTERIOR, 100, 100, 540, 380 ); 
getch(); 

_ setviewport( 200, 200, 440, 280 ) ; 

_ clearscreen ( _ GVIEWPORT ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ); 

} 

PC Graphics 
DOS 
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clock 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


#include <time.h> 
clock_ t clock(void); 

The clock function returns the number of clock ticks of processor time used by program since the 
program started executing. This can be converted to seconds by dividing by the value of the macro 
CLOCKS_ PER_ SEC. 

Note that under DOS and OS/2, the clock tick counter will reset to 0 for each subsequent 24 hour 
interval that elapses. 

The clock function returns the number of clock ticks that have occurred since the program started 
executing. 

asctime Functions, asctime_ s,ctime Functions, ctime_ s,difftime, gmtime, gmtime_ s, 
localtime, localtime_ s^nktime, strftime, time, tzset 

♦include <stdio.h> 

♦include <math.h> 

♦include <time.h> 

void compute( void ) 

{ 

int i, j; 
double x; 

x = 0.0; 

for( i = 1; i <= 100; i++ ) 
for( j = 1; j <= 100; j++ ) 

x += sqrt( (double) i * j ) ; 
printf ( "%16.7f\n", x ); 

} 

void main() 

{ 

clock_ t start_ time, end_ time; 

start_ time = clock(); 
compute (); 

end_ time = clock(); 

printf ( "Execution time was %lu seconds\n", 

(end_ time - start_time) / CLOCKS_ PER_ SEC ); 

} 

ISOC 

All, Linux, RDOS, Netware 
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clock_getres 


Synopsis: 


Description: 

Returns: 

Errors: 

See Also: 

Classification: 

Systems: 


♦include <time.h> 

int clock_ getres (clockid_ t clockid, struct timespec *ts); 

struct timespec { 
time_ t tv_ sec; 
long tv_ nsec; 


The clock_ getres function retrieves the minimum resolution of the clock specified by clockid in 
the ts pointer. 

If successful, the function will return zero. If the call fails, the return value is the negation of the 
appropriate errno value as specified below. This implementation will also set errno appropriately 
on failures. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINVAL The value of clockid is invalid. 

clock_ settime,clock_ gettime,clock_ nanosleep 

POSIX 

Linux 
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clock_gettime 


Synopsis: 


Description: 

Returns: 

Errors: 

See Also: 

Classification: 

Systems: 


♦include <time.h> 

int clock_ gettime (clockid_ t clockid, struct timespec *ts); 

struct timespec { 
time_ t tv_ sec; 
long tv_ nsec; 


The clock_ gettime function retrieves the time for the clock specified by clockid in the ts pointer. 

If successful, the function will return zero. If the call fails, the return value is the negation of the 
appropriate errno value as specified below. This implementation will also set errno appropriately 
on failures. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINVAL The value of clockid is invalid. 

clock_ settime,clock_ getres,clock_ nanosleep 

POSIX 

Linux 
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clock_nanosleep 


Synopsis: 


Description: 


Returns: 

Errors: 


See Also: 

Classification: 

Systems: 


♦include <time.h> 

int clock_ nanosleep (clockid_ t clockid, int flags, 

const struct timespec *request, 
struct timespec *remains); 

struct timespec { 
time_ t tv_ sec; 
long tv_ nsec; 

} ; 


The clock_ nanosleep function causes the current thread to be suspended until the time period 
specified by request has elapsed according to the clock specified by clockid if the flags do not contain 
the value TIMER_ABSTIME. 

If flags does contain TIMER_ABSTIME, the clock_ nanosleep function causes the current thread 
to be suspended until the absolute time specified by request has been reached according to the clock 
specified by clockid if the flags. 

If remains is not NULL, the structure will contain the amount of time remaining to be slept if 
clock_ nanosleep is interrupted by a signal. 

If successful and uninterrupted, the function will return zero. If the call fails or is interrupted, the return 
value is the negation of the appropriate errno value as specified below. This implementation will also 
set errno appropriately on failures. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINTR The sleep was interrupted by a signal. 

EINVAL The value of clockid , request , or flags is invalid. 

ENOTSUP The specified clock does not support this function. 
clock_ gettime,clock_ getres,clock_ settime 
POSIX 
Linux 
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clock settime 


Synopsis: 


Description: 

Returns: 

Errors: 


See Also: 

Classification: 

Systems: 


♦include <time.h> 

int clock_ settime (clockid_ t clockid, const struct timespec *ts); 

struct timespec { 
time_ t tv_ sec; 
long tv_ nsec; 


The clock_ settime function sets the time for the clock specified by clockid to the time contained in 
the ts pointer. Depending on the value of clockid , the function may fail if the user has insufficient 
privileges. 

Values of ts that specify significance beyond the clock’s resolution will be truncated. 

If successful, the function will return zero. If the call fails, the return value is the negation of the 
appropriate errno value as specified below. This implementation will also set errno appropriately 
on failures. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINVAL The value of clockid is invalid, or the value of ts exceeds the range of this clock. 

EPERM The user does not have sufficient privileges to modify the specified clock. 

clock_ gettime,clock_ getres,clock_ nanosleep 

POSIX 

Linux 
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clone 


Synopsis: #include <sched.h> 


pid_ t 


clone( int (*fn)(void *), void *child_ 
int flags, void *args, ... ); 

/* pid_ t *ppid, void *tls, pid_ t 


stack, 
*ctid */ 


Description: The clone function creates a "clone" of the currently running process that shares the address space of 
the original, parent process, and starts execution within the clone process at the fit function. The child 
function is called with args as its argument, and, once complete, with will terminate with the return 
value of fin as its exit code. This function provides a wrapper around the Linux kernel’s SYS_ clone 
system call. 

The child_stack argument points to a user-allocated memory block within the process’s heap for use as 
the cloned process’s new stack space. Because the stack will grow in the direction of descending 
address, the child_stack argument should refer to the highest address in the allocated memory. 

The flags argument may be one of the following values: 


Constant 

CLONEVM 

CLONE_FS 

CLONE_FILES 

CLONE_SIGHAND 

CLONE_PTRACE 

CLONE_VFORK 

CLONE_PARENT 

CLONE_THREAD 

CLONE_NEWNS 
CLONE _SYSVSEM 
CLONE _SE TTLS 

CLONE _PARENT_SETTID 

CLONE _CHILD_CLEARTID 


Meaning 

Virtual memory should be shared across processes 

File system information should be shared across processes 

File handles should be shared across processes 

Signal handlers and blocked signals should be shared across 
processes 

Allow tracing within the child process (if enabled in the parent) 

The child can wake the parent via mm_ release 

The new child should share the same parent as the cloning process 

The new process is to be considered a thread, and should be 
grouped in the same thread group as the parent 

The child process is provided a new mount namespace 

The child process shares all System V semaphores 

The thread-local storage, an optional argument, should be passed 
and set appropriately. The user must specify the tls argument if 
this flag is set. 

Store the thread ID of the parent in the ptid argument. The user 
must specify the optional ptid argument if this flag is set. 

Clear the thread ID stored in clid argument. The user must specify 
the optional did argument if this flag is set. 
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clone 


CLONE JUNTRACED The parent process cannot force tracing on the child process 

CLONE_CHILD_SETTID Store the thread ID of the child process in the ctid argument. The 

user must specify the optional ctid argument if this flag is set. 

CLONE_NEWUTS The child process has a new UTS namespace 

CLONE_NEWIPC The child process has a new IPC namespace 

CLONE_NEWUSER The child process has a new user namespace 

CLONE_NEWPID The child process has a new PID namespace 

CLONE_NEWNET The child process has a new network namespace 

CLONE_IO The parent and child share io contexts 

This function provides a low-level threading interface that is normally meant for designing higher level 
thread libraries. 

Returns: If successful, the function will return the process ID of the child process. If the system call fails, the 

return value will be -1, and errno will be set appropriately. 

Classification: WATCOM 

Systems: Linux 
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close, _close 


Synopsis: 

Description: 

Returns: 

Errors: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <io.h> 

int close( int handle ) ; 

int _ close( int handle ) ; 

The close function closes a file at the operating system level. The handle value is the file handle 
returned by a successful execution of one of the creat, dup, dup2, open or sopen functions. 

The _ close function is identical toclose. Use _ close for ANSI naming conventions. 

The close function returns zero if successful. Otherwise, it returns -1 and errno is set to indicate the 
error. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EBADF The handle argument is not a valid file handle. 

creat, dup, dup2, open, sopen 

♦include <fcntl.h> 

♦include <io.h> 

void main() 

{ 

int handle; 

handle = open ( "file", 0_ RDONLY ); 
if( handle != -1 ) { 

/* process file */ 
close ( handle ); 

} 

} 

POSIX 1003.1 

_close conforms to ANSI naming conventions 
close - All, Linux, RDOS, Netware 

_ close - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 


Library Functions and Macros 141 




closedir, _wclosedir 


Synopsis: 

Description: 

Returns: 

Errors: 

See Also: 
Example: 


♦include <direct.h> 

int closedir( DIR *dirp ) ; 

int _ wclosedir( WDIR *dirp ); 

The closedir function closes the directory specified by dirp and frees the memory allocated by 
opendir. 

The _ wclosedir function is identical toclosedir except that it closes a directory of 
wide-character filenames opened by _ wopendir. 

The closedir function returns zero if successful, non-zero otherwise. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EBADF The argument dirp does not refer to an open directory stream. 

_ dos_ find. . .Qpendir, readdir, rewinddir 

To get a list of files contained in the directory \watcom\h on your default disk: 

♦include <stdio.h> 

♦include <direct.h> 

typedef struct { 


unsigned short 

twosecs 

5; 

/* seconds / 2 */ 

unsigned short 

minutes 

6; 


unsigned short 
} ftime_ t; 

hours 

5; 


typedef struct { 

unsigned short 

day 

5; 


unsigned short 

month 

4; 


unsigned short 

year 

7; 



} fdate_ t; 


void main() 

{ 

DIR *dirp; 

struct dirent *direntp; 
ftime_ t *f_time; 
fdate_ t *f_ date; 


142 Library Functions and Macros 






closedir, _wclosedir 


dirp = opendir( "\\watcom\\h" ); 
if( dirp != NULL ) { 

for(;;) { 

direntp = readdir( dirp ) ; 
if( direntp == NULL ) break; 
f_ time = (ftime_t *)&direntp->d_ time; 
f_ date = (fdate_ t *)&direntp->d_ date; 
printf ( "%-12s %d/%2.2d/%2.2d " 

"%2.2d:%2.2d:%2.2d \n", 
direntp->d_ name, 
f_ date->year + 1980, 
f_ date->month, 
f_ date->day, 
f_ time->hours, 
f_ time->minutes, 
f_ time->twosecs * 2 ) ; 

} 

closedir( dirp ); 

} 

} 

Note the use of two adjacent backslash characters (\) within character-string constants to signify a single 
backslash. 

Classification: POSIX 1003.1 

_wclosedir is WATCOM 

Systems: closedir - All, Linux, RDOS, Netware 

_ wclosedir - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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cmdname 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <process.h> 

char *_ cmdname( char ^buffer ); 

The _ cmdname function obtains a copy of the executing program’s pathname and places it in buffer. 

If the pathname of the executing program cannot be determined then NULL is returned; otherwise the 
address of buffer is returned. 

getcmd 

♦include <stdio.h> 

♦include <process.h> 

void main() 

{ 

char buf fer [PATH_ MAX] ; 

printf ( "%s\n", _ cmdname( buffer ) ); 

} 

WATCOM 

All, Linux, RDOS, Netware 
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commit 


Synopsis: 

Description: 

Returns: 

Classification: 

Systems: 


♦include <io.h> 

int _ commit ( int handle ) ; 

The _ commit function commits changes to the file specified by handle to disk immediately. 

The _ commit function returns -1 if the changes have been successfully committed. Otherwise, 0 is 
returned and errno is set to indicate the error. 

WATCOM 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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control87 


Synopsis: #include <float.h> 

unsigned int _ control87( unsigned int newcw, 

unsigned int mask ); 

Description: The _ control 8 7 function updates the control word of the 8087/80287/80387/80486. If mask is zero, 
then the control word is not updated. If mask is non-zero, then the control word is updated with bits 
from newcw corresponding to every bit that is on in mask. 

Returns: The _ control 8 7 function returns the new control word. The description of bits defined for the 

control word is found in the <f loat. h> header file. 

See Also: _ clear87^_ controlfp,_ finite^ fpreset^_ status87 

Example: #include <stdio.h> 

#include <float.h> 

char *status[2] = { "disabled", "enabled" }; 

void main () 

{ 

unsigned int fp_ cw = 0; 
unsigned int fp_ mask = 0; 
unsigned int bits; 

fp_ cw = _ control87 ( fp_ cw, 

fp_ mask ) ; 

printf( "Interrupt Exception Masks\n" ); 
bits = fp_ cw & MCW_ EM; 

printf( " Invalid Operation exception %s\n", 
status [ (bits & EM_ INVALID) == 0 ] ); 

printf ( " Denormalized exception %s\n", 

status [ (bits & EM_ DENORMAL) == 0 ] ); 

printf ( " Divide-By-Zero exception %s\n", 

status [ (bits & EM_ ZERODIVIDE) == 0 ] ); 

printf ( " Overflow exception %s\n", 

status [ (bits & EM_ OVERFLOW) == 0 ] ); 

printf ( " Underflow exception %s\n", 

status[ (bits & EM_ UNDERFLOW) == 0 ] ); 

printf ( " Precision exception %s\n", 

status [ (bits & EM_ PRECISION) == 0 ] ); 

printf ( "Infinity Control = " ); 
bits = fp_ cw & MCW_ IC; 

if ( bits == IC_ AFFINE ) printf ( "affine\n" ); 

if ( bits == IC_ PROJECTIVE ) printf ( "pro jective\n" ) ; 


printf( "Rounding Control = " ) ; 
bits = fp_ cw & MCW_ RC; 


if ( 

bits 

== RC_ 

NEAR ) 

printf( 

"near\n" ); 

if ( 

bits 

== RC_ 

DOWN ) 

printf( 

"down\n" ); 

if ( 

bits 

== RC_ 

UP ) 

printf( 

"up\n" ); 

if ( 

bits 

== RC_ 

CHOP ) 

printf( 

"chop\n" ); 
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control87 


Classification: 

Systems: 


printf ( " 

Precis. 

ion 

Control : 

= " ) ; 



bits 

; = fp 

_ cw & 

MCW. 

_ PC; 




if ( 

bits 

== PC_ 

24 

) 

printf( 

"24 

bits\n" ); 

if ( 

bits 

== PC_ 

53 

) 

printf( 

"53 

bits\n" ); 

if ( 

bits 

== PC_ 

64 

) 

printf( 

"64 

bits\n" ); 


} 

Intel 

All, Linux, RDOS, Netware 
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controlfp 


Synopsis: #include <float.h> 

unsigned int _ controlfp( unsigned int newcw, 

unsigned int mask ); 

Description: The _ controlfp function updates the control word of the 8087/80287/80387/80486. If mask is zero, 
then the control word is not updated. If mask is non-zero, then the control word is updated with bits 
from newcw corresponding to every bit that is on in mask. 

Returns: The _ controlfp function returns the new control word. The description of bits defined for the 

control word is found in the <f loat. h> header file. 

See Also: _ clear87^_ control87,_ finite^ fpreset^_ status87 

Example: #include <stdio.h> 

#include <float.h> 

char *status[2] = { "disabled", "enabled" }; 

void main () 

{ 

unsigned int fp_ cw = 0; 
unsigned int fp_ mask = 0; 
unsigned int bits; 

fp_ cw = _ controlfp ( fp_ cw, 

fp_ mask ) ; 

printf( "Interrupt Exception Masks\n" ); 
bits = fp_ cw & MCW_ EM; 

printf( " Invalid Operation exception %s\n", 
status [ (bits & EM_ INVALID) == 0 ] ); 

printf ( " Denormalized exception %s\n", 

status [ (bits & EM_ DENORMAL) == 0 ] ); 

printf ( " Divide-By-Zero exception %s\n", 

status [ (bits & EM_ ZERODIVIDE) == 0 ] ); 

printf ( " Overflow exception %s\n", 

status [ (bits & EM_ OVERFLOW) == 0 ] ); 

printf ( " Underflow exception %s\n", 

status[ (bits & EM_ UNDERFLOW) == 0 ] ); 

printf ( " Precision exception %s\n", 

status [ (bits & EM_ PRECISION) == 0 ] ); 

printf ( "Infinity Control = " ); 
bits = fp_ cw & MCW_ IC; 

if ( bits == IC_ AFFINE ) printf ( "affine\n" ); 

if ( bits == IC_ PROJECTIVE ) printf ( "pro jective\n" ) ; 


printf( "Rounding Control = " ) ; 
bits = fp_ cw & MCW_ RC; 


if ( 

bits 

== RC_ 

NEAR ) 

printf( 

"near\n" ); 

if ( 

bits 

== RC_ 

DOWN ) 

printf( 

"down\n" ); 

if ( 

bits 

== RC_ 

UP ) 

printf( 

"up\n" ); 

if ( 

bits 

== RC_ 

CHOP ) 

printf( 

"chop\n" ); 
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controlfp 


Classification: 

Systems: 


printf ( " 

Precis. 

ion 

Control : 

= " ) ; 



bits 

; = fp 

_ cw & 

MCW. 

_ PC; 




if ( 

bits 

== PC_ 

24 

) 

printf( 

"24 

bits\n" ); 

if ( 

bits 

== PC_ 

53 

) 

printf( 

"53 

bits\n" ); 

if ( 

bits 

== PC_ 

64 

) 

printf( 

"64 

bits\n" ); 


} 

Intel 

All, Linux, RDOS, Netware 
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copysign 


Synopsis: 

Description: 

Returns: 

Example: 


Classification: 

Systems: 


#include <math.h> 

double copysign( double x, double y ); 

The copysign function returns a value whose absolute value is equal to the absolute value of the 
argument x and whose sign matches argument y. 

A value of the same magnitude as x and the same sign as y. 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", copysign( -2.0, 3.0 ) ); 

} 

produces the following: 

2.000000 
ISO C99 
Math 


150 Library Functions and Macros 




cos 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <math.h> 
double cos( double x ) ; 

The cos function computes the cosine of x (measured in radians). A large magnitude argument may 
yield a result with little or no significance. 

The cos function returns the cosine value. 

acos, sin, tan 

♦include <math.h> 

void main() 

{ 

double value; 

value = cos ( 3.1415278 ); 

} 

ISOC 

Math 


Library Functions and Macros 151 




cosh 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double cosh ( double x ); 

The cosh function computes the hyperbolic cosine of x. A range error occurs if the magnitude of x is 
too large. 

The cosh function returns the hyperbolic cosine value. When the argument is outside the permissible 
range, the matherr function is called. Unless the default matherr function is replaced, it will set the 
global variable errno to ERANGE, and print a "RANGE error" diagnostic message using the stderr 
stream. 

sinh, tanh, matherr 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", cosh(.5) ); 

} 

produces the following: 

1.127626 

ISOC 

Math 
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cprintf 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


#include <conio.h> 

int cprintf( const char *format, ... ); 

The cprintf function writes output directly to the console under control of the argument format. The 
putch function is used to output characters to the console. The format string is described under the 
description of the print f function. 

The cprintf function returns the number of characters written. 

_ bprintf.fprintf, printf, sprintf, _ vbprintf.vcprintf, vfprintf, vprintf, 
vsprintf 

♦include <conio.h> 

void main() 

{ 

char *weekday, *month; 
int day, year; 

weekday = "Saturday"; 
month = "April"; 
day = 18; 
year = 1987; 

cprintf( "%s, %s %d, %d\n", 

weekday, month, day, year ); 

} 

produces the following: 

Saturday, April 18, 1987 
WATCOM 

All, Linux, RDOS, Netware 
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cputs 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <conio.h> 

int cputs( const char *buf ) ; 

The cputs function writes the character string pointed to by buf directly to the console using the 
putch function. Unlike the puts function, the carriage-return and line-feed characters are not 
appended to the string. The terminating null character is not written. 

The cputs function returns a non-zero value if an error occurs; otherwise, it returns zero. When an error 
has occurred, errno contains a value indicating the type of error that has been detected. 

fputs, putch, puts 

♦include <conio.h> 

void main() 

1 

char buffer [82]; 

buffer[0] = 80; 
cgets ( buffer ); 
cputs ( &buffer[2] ); 
putch ( '\r' ); 

putch( '\n' ); 

} 

WATCOM 

All, Linux, RDOS, Netware 
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creat, _creat, _wcreat 


Synopsis: #include <sys/types .h> 

♦include <sys/stat.h> 

♦include <io.h> 

int creat( const char *path, int mode ); 

int _ creat( const char *path, int mode ); 

int _ wcreat ( const wchar_ t *path, int mode ) ; 

Description: The creat function creates (and opens) a file at the operating system level. It is equivalent to: 

open ( path, 0_ WRONLY | 0_ CREAT | 0_ TRUNC, mode ); 

The _ creat function is identical tocreat. Use _ creat for ANSI naming conventions. 

The _ wcreat function is identical tocreat except that it accepts a wide character string argument. 

The name of the file to be created is given by path. When the file exists (it must be writeable), it is 
truncated to contain no data and the preceding mode setting is unchanged. 

When the file does not exist, it is created with access permissions given by the mode argument. The 
access permissions for the file or directory are specified as a combination of bits (defined in the 
<sys/stat .h> header file). 

The following bits define permissions for the owner. 

Permission Meaning 

S_IRWXU Read, write, execute/search 

S_IRUSR Read permission 

S_IWUSR Write permission 

S_IXUSR Execute/search permission 

The following bits define permissions for the group. 

Permission Meaning 

S_IRWXG Read, write, execute/search 

S_IRGRP Read permission 

S_IWGRP Write permission 

S_IXGRP Execute/search permission 

The following bits define permissions for others. 

Permission Meaning 

S_IRWXO Read, write, execute/search 

S_IROTH Read permission 

S_IWOTH Write permission 

S_IXOTH Execute/search permission 

The following bits define miscellaneous permissions used by other implementations. 
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creat, _creat, _wcreat 


Returns: 


Errors: 


See Also: 


Example: 


Classification: 


Systems: 


Permission 


Meaning 


SJREAD is equivalent to S_IRUSR (read permission) 

SJWRITE is equivalent to S_IWUSR (write permission) 

S_IEXEC is equivalent to S_IXUSR (execute/search permission) 


All files are readable with DOS; however, it is a good idea to set S_ I READ when read permission is 
intended for the file. 


If successful, creat returns a handle for the file. When an error occurs while opening the file, -1 is 
returned, and errno is set to indicate the error. 


When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 


EACCES 

EMFILE 

ENOENT 


Access denied because path specifies a directory or a volume ID, or a read-only 
file. 

No more handles available (too many open files). 

The specified path does not exist ox path is an empty string. 


chsize, close, dup, dup2, eof, exec. . fdopen, filelength, fileno, fstat, 

_ grow_ handlesisatty, lseek, open, read, setmode, sopen, stat, tell, write, 
umask 


♦include <sys/types.h> 

♦include <sys/stat.h> 

♦include <io.h> 

void main() 

{ 

int handle; 

handle = creat ( "file", S_ IWRITE | S_ IREAD ); 
if( handle != -1 ) { 

/* process file */ 

close ( handle ); 

} 

} 


POSIX 1003.1 

_creat conforms to ANSI naming conventions 
_wcreat is WATCOM 

creat - All, Linux, RDOS, Netware 
_ creat - All, Linux, RDOS, Netware 

_ wcreat - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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cscanf 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <conio.h> 

int cscanf( const char *format, ... ); 

The cscanf function scans input from the console under control of the argument format. Following 
the format string is a list of addresses to receive values. The cscanf function uses the function 
getche to read characters from the console. The format string is described under the description of 
the scanf function. 


The cscanf function returns EOF when the scanning is terminated by reaching the end of the input 
stream. Otherwise, the number of input arguments for which values were successfully scanned and 
stored is returned. When a file input error occurs, the errno global variable may be set. 


f scanf, scanf, sscanf, vcscanf, vfscanf, vscanf, vsscanf 

To scan a date in the form "Saturday April 18 1987": 

♦include <conio.h> 

void main() 

{ 


int day, year; 

char weekday[10], month[10]; 


} 


cscanf( "%s %s %d %d", 

weekday, month, &day, Syear 
cprintf( "\n%s, %s %d, %d\n", 

weekday, month, day, year ) ; 


WATCOM 


All, Linux, RDOS, Netware 


Library Functions and Macros 157 




ctime Functions 


Synopsis: 

Safer C: 

Description: 


Returns: 
See Also: 

Example: 


#include <time.h> 

char *ctime( const time_ t *timer ); 

char *_ ctime ( const time_ t *timer, char *buf ) ; 

wchar_ t *_ wctime ( const time_ t *timer ) ; 

wchar_ t *_wctime ( const time_ t *timer, wchar_ t *buf ) ; 

The Safer C Library extension provides the ctime_ s function which is a safer alternative toctime 
This newer ctime_ s function is recommended to be used instead of the traditional "unsafe" ctime 
function. 

The ctime functions convert the calendar time pointed to by timer to local time in the form of a string. 
The ctime function is equivalent to 

asctime( localtime( timer ) ) 

The ctime functions convert the time into a string containing exactly 26 characters. This string has the 
form shown in the following example: 

Sat Mar 21 15:58:27 1987\n\0 

All fields have a constant width. The new-line character ' \n' and the null character ' \ 0' occupy the 
last two positions of the string. 

The ISO C function ctime places the result string in a static buffer that is re-used each time ctime or 
asctime is called. The non-ISO C function _ ctime places the result string in the buffer pointed to 
by buf. 

The wide-character function _ wctime is identical to ctime except that it produces a wide-character 

string. The wide-character function_wctime is identical to_ ctime except that it produces a 

wide-character string. 

Whenever the ctime functions are called, the tzset function is also called. 

The calendar time is usually obtained by using the t ime function. That time is Coordinated Universal 
Time (UTC) (formerly known as Greenwich Mean Time (GMT)). 

The time set on the computer with the DOS time command and the DOS date command reflects the 
local time. The environment variable TZ is used to establish the time zone to which this local time 
applies. See the section The TZ Environment Variable for a discussion of how to set the time zone. 

The ctime functions return the pointer to the string containing the local time. 

asctime Functions, asctime_ s,clock, ctime_ s,difftime, gmtime, gmtime_ s, 
localtime, localtime_ sjnktime, strftime, time, tzset, ctime_ s 

♦include <stdio.h> 

♦include <time.h> 

void main() 

{ 

time_ t time_ of_ day; 
auto char buf[26]; 
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ctime Functions 


Classification: 


Systems: 


time_ of_ day = time ( NULL ) ; 

printf ( "It is now: %s", _ ctime ( &time_ of_ day, buf ) ); 


produces the following: 

It is now: Fri Dec 25 15:58:42 1987 

ISOC 

_ctime is WATCOM 
_wctime is WATCOM 
_wctime is WATCOM 

ctime - All, Linux, RDOS, Netware 
_ ctime - All, Linux, RDOS 
_ wctime - All, Linux 
_wctime - All, Linux 
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ctime_s, _wctime_s 


Synopsis: #def ine _STDC_ WANT_ LIB_ EXT1_1 

♦include <time.h> 

errno_ t ctime_ s( char * s, 

rsize_ t maxsize, 
const time_ t * timer); 

♦include <wchar.h> 

errno_ t _ wctime_ s ( wchar_ t * s, 

rsize_ t maxsize, 
const time_ t * timer); 

Constraints: If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and ct ime_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither ,v nor timer shall be a null pointer, maxsize shall not be less than 26 and shall not be greater than 
RSIZE_MAX. If there is a runtime-constraint violation, s[0] is set to a null character if s is not a null 
pointer and maxsize is not equal zero and is not greater than RSIZE_MAX. 

Description: The ctime_ s function converts the calendar time pointed to by timer to local time in the form of a 
string. It is equivalent to 

asctime_ s ( s, maxsize, localtime_ s ( timer ) ) 

Recommended practice: 

The strftime function allows more flexible formatting and supports locale-specific behavior. If you do 
not require the exact form of the result string produced by the ctime_ s function, consider using the 
strftime function instead. 

Returns: The ct ime_ s function returns zero if there was no runtime-constraint violation. Otherwise, a 

non-zero value is returned. 

See Also: asctime Functions, asctime_ s.clock, ctime Functions, difftime, gmtime, gmtime_ s, 

localtime, localtime_ sjnktime, strftime, time, tzset 

Example: ♦define _STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <time.h> 

void main() 

{ 

time_ t time_ of_ day; 
auto char buf[26]; 

time_ of_ day = time ( NULL ) ; 

ctime_ s ( buf, sizeof ( buf ) , &time_ of_ day ) ; 
printf ( "It is now: %s", buf ); 

} 

produces the following: 

It is now: Mon Jan 30 14:29:55 2006 

Classification: TR 24731 
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ctime_s, _wctime_s 


Systems: 


_wctime_s is WATCOM 

ctime_ s - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, Linux, 
RDOS, Netware 

_ wctime_ s - DOS, Windows, Win386, Win32, OS/2 1.x (all), OS/2-32, 
Linux 
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cwait, _cwait 


Synopsis: #include <process.h> 

int cwait( int *status, int process_ id, int action ); 
int _ cwait ( int *status, int process, id, int action ); 

Description: The cwait function suspends the calling process until the specified process terminates. 

If status is not NULL, it points to a word that will be filled in with the termination status word and 
return code of the terminated child process. 

If the child process terminated normally, then the low order byte of the status word will be set to 0, and 
the high order byte will contain the low order byte of the return code that the child process passed to the 
DOSEXIT function. The DOSEXIT function is called whenever main returns, or exit , or _ Exit or 
_ exit are explicity called. 

If the child process did not terminate normally, then the high order byte of the status word will be set to 
0, and the low order byte will contain one of the following values: 

Value Meaning 

1 Hard-error abort 

2 Trap operation 

3 SIGTERM signal not intercepted 

Note: This implementation of the status value follows the OS/2 model and differs from the 

Microsoft implementation. Under Microsoft, the return code is returned in the low 
order byte and it is not possible to determine whether a return code of 1, 2, or 3 imply 
that the process terminated normally. For portability to Microsoft compilers, you 
should ensure that the application that is waited on does not return one of these values. 
The following shows how to handle the status value in a portable manner. 
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cwait, _cwait 


Returns: 


cwait ( Sstatus, process, id, WAIT_ CHILD ); 


#if defined (_WATCOMC_) 

switch( status & Oxff ) { 

case 0: 

printf( "Normal termination exit code = %d\n ", 
break; 
case 1: 

printf( "Hard-error abort\n" ); 
break; 
case 2: 

printf( "Trap operation\n" ); 
break; 
case 3: 


printf( "SIGTERM signal not intercepted\n" ); 
break; 
default: 

printf( "Bogus return status\n" ) ; 

} 


status » 8 ) ; 


#else if defined (_ MSC_ VER) 
switch( status & Oxff ) { 

case 1: 

printf ( "Possible Hard-error abort\n" ); 
break; 
case 2: 

printf ( "Possible Trap operation\n" ); 
break; 
case 3: 

printf( "Possible SIGTERM signal not intercepted\n" ); 
break; 
default: 

printf( "Normal termination exit code = %d\n", status ); 

} 

#endif 


The processed argument specifies which process to wait for. Under Win32, any process can wait for 
any other process for which the process ID is known. Under OS/2, a process can wait for any of its 
child processes. For example, a process ID is returned by certain forms of the spawn . . . functions 
that is used to start a child process. 

The action argument specifies when the parent process resumes execution. This argument is ignored in 
Win32, but is accepted for compatibility with OS/2 (although Microsoft handles the status value 
differently from OS/2!). The possible values are: 

Value Meaning 

WAITjCHILD Wait until the specified child process has ended. 

WAIT_GRANDCHILD Wait until the specified child process and all of the child processes of that 

child process have ended. 

Under Win32, there is no parent-child relationship. 

The cwait function returns the (child's) process ID if the (child) process terminated normally. 
Otherwise, cwait returns -1 and sets errno to one of the following values: 
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cwait, _cwait 


Constant Meaning 

EINVAL Invalid action code 

ECHILD Invalid process ID, or the child does not exist. 

EINTR The child process terminated abnormally. 

See Also: exit, _ Exit*_ exit.spawn . . ., wait 

Example: #include <stdio.h> 

♦include <process.h> 

void main() 

{ 

int process^ id; 
int status; 

process_ id = spawnl ( P_ NOWAIT, "child.exe", 
"child", "parra", NULL ); 
cwait ( Sstatus, process, id, WAIT_ CHILD ); 

} 

Classification: WATCOM 

Systems: cwait - Win32, OS/2 1.x (all), OS/2-32 

_ cwait - Win32, OS/2 l.x(all), OS/2-32 
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delay 


Synopsis: #include <i8 6.h> 

void delay( unsigned milliseconds ); 

Description: The delay function suspends execution by the specified number of milliseconds. 

Returns: The delay function has no return value. 

See Also: sleep 

Example: #include <i8 6.h> 

void main () 

{ 

sound( 200 ); 

delay( 500 ); /* delay for 1/2 second */ 

nosound(); 

} 

Classification: WATCOM 
Systems: All, RDOS, Netware 
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dieeetomsbin 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 

extern int _ dieeetomsbin( double *src, double *dest ); 

The _ dieeetomsbin function loads the double pointed to by src in IEEE format and converts it to 
Microsoft binary format, storing the result into the double pointed to by dest. 

For _ dieeetomsbin IEEE Nan’s and Infinities will cause overflow. IEEE denormals will be 
converted if within range. Otherwise, they will be converted to 0 in the Microsoft binary format. 

The range of Microsoft binary format floats is 2.938736e-39 to 1.701412e+38. The range of Microsoft 
binary format doubles is 2.938735877056e-39 to 1.701411834605e+38. 

Microsoft Binary Format was used by early versions of Microsoft QuickBASIC before coprocessors 
became standard. 

The _ dieeetomsbin function returns 0 if the conversion was successful. Otherwise, it returns 1 if 
conversion would cause an overflow. 

_ dmsbintoieee,_ fieeetomsbin,_ fmsbintoieee 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

float fieee, fmsb; 
double dieee, dmsb; 

fieee = 0.5; 
dieee = -2.0; 

/* Convert IEEE format to Microsoft binary format */ 

_ fieeetomsbin( &fieee, &fmsb ); 

_ dieeetomsbin( &dieee, &dmsb ); 

/* Convert Microsoft binary format back to IEEE format */ 

_ fmsbintoieee( &fmsb, Sfieee ); 

_ dmsbintoieee( &dmsb, Sdieee ) ; 

/* Display results */ 

printf( "fieee = %f, dieee = %f\n", fieee, dieee ); 

} 

produces the following: 

fieee = 0.500000, dieee = -2.000000 
WATCOM 

All, Linux, RDOS, Netware 
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difftime 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


#include <time.h> 

double difftime( time_ t timel, time_t timeO ); 

The difftime function calculates the difference between the two calendar times: 
timel - timeO 

The difftime function returns the difference between the two times in seconds as a double . 

asctime Functions, asctime_ s,clock, ctime Functions, ctime_ s,gmtime, gmtime_ s, 
localtime, localtime_ sjnktime, strftime, time, tzset 

♦include <stdio.h> 

♦include <time.h> 

void compute( void ); 

void main() 

{ 

time_ t start_ time, end_ time; 

start_ time = time ( NULL ) ; 
compute (); 

end_ time = time ( NULL ) ; 

printf ( "Elapsed time: %f seconds\n", 

difftime ( end_ time, start_ time ) ) ; 

} 

void compute( void ) 

{ 

int i, j; 

for( i = 1; i <= 20; i++ ) { 
for( j = 1; j <= 20; j++ ) 
printf ( "%3d ", i * j ); 
printf ( "\n" ); 

} 

} 

ISOC 

Math 
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dirname 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <libgen.h> 

char *dirname( char *path ) ; 

The dirname function takes a pointer to a character string that contains a pathname, and returns a 
pointer to a string that is a pathname of the parent directory of that file. Trailing path separators are not 
considered as part of the path. 

The dirname function may modify the string pointed to by path and may return a pointer to static 
storage that may be overwritten by a subsequent call to dirname 

The dirname function is not re-entrant or thread-safe. 

The dirname function returns a pointer to a string that is the parent directory of path. If path is a null 
pointer or points to an empty string, a pointer to the string "." is returned. 

basename 

♦include <stdio.h> 

♦include <libgen.h> 

int main( void ) 

{ 

puts( dirname( "/usr/lib" ) ); 

puts( dirname( "/usr/" ) ); 

puts( dirname( "usr" ) ); 

puts( dirname( "/" ) ); 

puts( dirname( " . . " ) ) ; 

return( 0 ) ; 

} 

produces the following: 

/usr 

/ 

/ 


POSIX 

All, Linux, RDOS, Netware 
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disable 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <i86.h> 
void _ disable ( void ) ; 

The _ disable function causes interrupts to become disabled. 

The _ disable function would be used in conjunction with the_ enable function to make sure that a 
sequence of instructions are executed without any intervening interrupts occurring. 

The _ disable function returns no value. 

_ enable 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <i86.h> 

struct list_ entry { 

struct list_ entry *next; 
int data; 

} ; 

volatile struct list_ entry *ListHead = NULL; 
volatile struct list_ entry *ListTail = NULL; 

void insert ( struct list_ entry *new_ entry ) 

{ 

/* insert new_ entry at end of linked list */ 
new_ entry->next = NULL; 

_ disable!); /* disable interrupts */ 

if( ListTail == NULL ) { 

ListHead = new_ entry; 

} else { 

ListTail->next = new_ entry; 

} 

ListTail = new_ entry; 

_ enable!); /* enable interrupts now */ 

} 

void main() 

{ 

struct list_entry *p; 
int i; 

for( i = 1; i <= 10; i++ ) { 

p = (struct list_ entry *) 

malloc ( sizeof( struct list_ entry ) ); 

if( p == NULL ) break; 
p->data = i; 
insert( p ); 

} 

} 

Intel 

All, Linux, RDOS, Netware 
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displaycursor 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


♦include <graph.h> 

short _ FAR _ displaycursor( short mode ); 

The _ displaycursor function is used to establish whether the text cursor is to be displayed when 
graphics functions complete. On entry to a graphics function, the text cursor is turned off. When the 
function completes, the mode setting determines whether the cursor is turned back on. The mode 
argument can have one of the following values: 

_GCURSORON the cursor will be displayed 

_GCURSOROFF the cursor will not be displayed 

The _ displaycursor function returns the previous setting for mode. 

_ gettextcursor,_ settextcursor 

♦include <stdio.h> 

♦include <graph.h> 

main () 

{ 

char buf[ 80 ]; 

_ setvideomode( _ TEXTC80 ); 

_ settextposition( 2, 1 ); 

_ displaycursor( _ GCURSORON ); 

_ outtext( "Cursor ON\n\nEnter your name >" ) ; 
gets( buf ); 

_ displaycursor( _ GCURSOROFF ); 

_ settextposition( 6, 1 ); 

_ outtext( "Cursor OFF\n\nEnter your name >" ); 
gets ( buf ); 

_ setvideomode( _ DEFAULTMODE ) ; 

} 

PC Graphics 
DOS 
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Synopsis: 


Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


div 


#include <stdlib.h> 

div_ t div( int numer, int denom ); 

typedef struct { 

int quot; /* quotient */ 

int rem; /* remainder */ 

} div_ t; 

The div function calculates the quotient and remainder of the division of the numerator numer by the 
denominator denom. 


The div function returns a structure of type div_ t which contains the fieldsquot and rem. 
ldiv, lldiv, imaxdiv 


♦include <stdio.h> 
♦include <stdlib.h> 


void print_ time( int seconds ) 

{ 

div_ t min_ sec; 


} 


min_ sec = div ( seconds, 60 ); 

printf( "It took %d minutes and %d seconds\n", 
min_ sec . quot, min_ sec.rem ); 


void main( void ) 

{ 

print_ time( 130 ) ; 

} 


produces the following: 

It took 2 minutes and 10 seconds 


ISO C90 


All, Linux, RDOS, Netware 
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dmsbintoieee 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <math.h> 

extern int _ dmsbintoieee( double *src, double *dest ); 

The _ dmsbintoieee function loads the double pointed to by src in Microsoft binary format and 
converts it to IEEE format, storing the result into the double pointed to by dest. 

The range of Microsoft binary format floats is 2.938736e-39 to 1.701412e+38. The range of Microsoft 
binary format doubles is 2.938735877056e-39 to 1.701411834605e+38. 

Microsoft Binary Format was used by early versions of Microsoft QuickBASIC before coprocessors 
became standard. 

The _ dmsbintoieee function returns 0 if the conversion was successful. Otherwise, it returns 1 if 
conversion would cause an overflow. 

_ dieeetomsbin,_ fieeetomsbin,_ fmsbintoieee 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

float fieee, fmsb; 
double dieee, dmsb; 

fieee = 0.5; 
dieee = -2.0; 

/* Convert IEEE format to Microsoft binary format */ 

_ fieeetomsbin( Sfieee, &fmsb ); 

_ dieeetomsbin( &dieee, &dmsb ); 

/* Convert Microsoft binary format back to IEEE format */ 

_ fmsbintoieee( &fmsb, &fieee ); 

_ dmsbintoieee( &dmsb, Sdieee ) ; 

/* Display results */ 

printf ( "fieee = %f, dieee = %f\n", fieee, dieee ); 

} 

produces the following: 

fieee = 0.500000, dieee = -2.000000 
WATCOM 

All, Linux, RDOS, Netware 
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Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


dos_allocmem 


♦include <dos.h> 

#if defined (_NT_) | | \ 

( defined(_ 0S2_) && \ 

(defined (_ 386 _) || defined (_PPC_)) ) 

unsigned _ dos_ allocmem( unsigned size, 

void * *segment); 

♦ else 

unsigned _ dos_ allocmem( unsigned size, 

unsigned ^segment); 


♦endif 


The _ dos_ allocmem function uses system call 0x48 to allocate size paragraphs directly from DOS. 
The size of a paragraph is 16 bytes. The allocated memory is always paragraph aligned. The segment 
descriptor for the allocated memory is returned in the word pointed to by segment. If the allocation 
request fails, the maximum number of paragraphs that can be allocated is returned in this word instead. 

For 32-bit DOS applications, it is recommended that the corresponding DPMI services be used. 

The _ dos_ allocmem function returns zero if successful. Otherwise, it returns an OS error code and 
sets errno accordingly. 

alloca, calloc, _ dos_ freemen^. dos_ setblockhalloc, malloc 

♦include <stdio.h> 

♦include <dos.h> 

void main( void ) 

{ 

♦ if defined (_NT_) | | \ 

( defined (_OS2_) && \ 

(defined (_ 386_) || defined (_ PPC_ )) ) 

void *segment; 

♦ else 

unsigned segment; 

♦endif 

/* Try to allocate 100 paragraphs, then free them */ 
if( _ dos_ allocmem( 100, ^segment ) != 0 ) { 

printf( dos_ allocmem failed\n" ) ; 
printf( "Only %u paragraphs available\n", 
segment ); 

} else { 

printf( dos_ allocmem succeeded\n" ) ; 
if ( _ dos_ freemem( segment ) != 0 ) { 

printf( dos_ freemem failedXn" ) ; 

} else { 

printf( dos_ freemem succeeded\n" ) ; 


} 

} 

DOS 

DOS, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 
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_dos_close 

Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <dos.h> 

unsigned _ dos_ close( int handle ) ; 

The _ dos_ close function uses system call 0x3E to close the file indicated by handle. The value for 
handle is the one returned by a function call that created or last opened the file. 

The _ dos_ close function returns zero if successful. Otherwise, it returns an OS error code and sets 
errno accordingly. 

creat,_ dos_ create dos_ creatnew*. dos_ opendup, fclose, open 

♦include <stdio.h> 

♦include <dos.h> 

♦include <fcntl.h> 

void main() 

{ 

int handle; 

/* Try to open "stdio.h" and then close it */ 
if ( _ dos_ open ( "stdio.h", 0_ RDONLY, Shandle ) != 0 ){ 

printf( "Unable to open file\n" ) ; 

} else { 

printf( "Open succeeded\n" ); 
if ( _ dos_ close ( handle ) != 0 ) { 

printf ( "Close failed\n" ); 

} else { 

printf ( "Close succeeded\n" ); 

} 

} 

} 

DOS 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


dos_commit 


#include <dos.h> 

unsigned _ dos_ commit( int handle ) ; 

The _ dos_ commit function uses system call 0x68 to flush to disk the DOS buffers associated with the 
file indicated by handle. It also forces an update on the corresponding disk directory and the file 
allocation table. 

The _ dos_ commit function returns zero if successful. Otherwise, it returns an OS error code and sets 
errno accordingly. 

_ dos_ close*. dos_ creat* dos_ open* dos_ write 

♦include <stdio.h> 

♦include <dos.h> 

♦include <fcntl.h> 

void main() 

{ 

int handle; 

if ( _ dos_ open ( "file", 0_ RDONLY, handle ) != 0 ) { 

printf ( "Unable to open file\n" ); 

} else { 

if ( _ dos_ commit ( handle ) == 0 ) { 

printf ( "Commit succeeded.\n" ); 

} 

_ dos_ close( handle ); 

} 

} 

produces the following: 

Commit succeeded. 

DOS 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 
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dos creat 


Synopsis: #include <dos.h> 

unsigned _ dos_ creat( const char *path, 

unsigned attribute, 
int *handle ); 

Description: The _ dos_ creat function uses system call 0x3C to create a new file named path, with the access 
attributes specified by attribute. The handle for the new file is returned in the word pointed to by 
handle. If the file already exists, the contents will be erased, and the attributes of the file will remain 
unchanged. The possible values for attribute are: 

Attribute Meaning 

_A_NORMAL Indicates a normal file. File can be read or written without any restrictions. 

_A_RDONLY Indicates a read-only file. File cannot be opened for "write". 

_A_HIDDEN Indicates a hidden file. This file will not show up in a normal directory search. 

_A_SYSTEM Indicates a system file. This file will not show up in a normal directory search. 

Returns: The _ dos_ creat function returns zero if successful. Otherwise, it returns an OS error code and sets 

errno accordingly. 

See Also: creat, _ dos_ creatnew*. dos_ open^. dos_ openopen, fdopen, fopen, f reopen, 

_ fsopen^ grow_ handles^ hdopen,open, _ open_ osfhandlej, popen.sopen 

Example: #include <stdio.h> 

♦include <dos.h> 

void main() 

{ 

int handle; 

if ( _ dos_ creat ( "file", _ A_ NORMAL, Shandle ) != 0 ){ 

printf( "Unable to create file\n" ); 

} else { 

printf( "Create succeeded\n" ) ; 

_ dos_ close( handle ); 

} 

} 

Classification: DOS 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 
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Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


dos_creatnew 


♦include <dos.h> 

unsigned _ dos_ creatnew( const char *path, 

unsigned attribute, 
int *handle ); 


The _ dos_ creatnew function uses system call 0x5B to create a new file named path, with the access 
attributes specified by attribute. The handle for the new file is returned in the word pointed to by 
handle. If the file already exists, the create will fail. The possible values for attribute are: 


Attribute 

_A_NORMAL 

_A_RDONLY 

_A_HIDDEN 

_A_SYSTEM 


Meaning 

Indicates a normal file. File can be read or written without any restrictions. 
Indicates a read-only file. File cannot be opened for "write". 

Indicates a hidden file. This file will not show up in a normal directory search. 
Indicates a system file. This file will not show up in a normal directory search. 


The _ dos_ creatnew function returns zero if successful. Otherwise, it returns an OS error code and 
sets errno. Possible values and their interpretations: 


Constant 

EACCES 

EEXIST 

EMFILE 

ENOENT 


Meaning 

Access denied because the directory is full, or the file exists and cannot be 
overwritten. 

File already exists 

No more handles available (i.e., too many open files) 

Path or file not found 


creat,_ dos_ create dos_ open^ dos_ openopen, fdopen, fopen, f reopen, _ fsopen, 
_ grow_ handles^ hdopen,open, _ open_ osfhandlej. popen,sopen 

♦include <stdio.h> 

♦include <dos.h> 

void main() 

{ 

int handlel, handle2; 

if ( _ dos_ creat ( "file", _ A_ NORMAL, Shandlel ) ){ 

printf( "Unable to create file\n" ); 

} else { 

printf ( "Create succeeded\n" ); 

if ( _ dos_ creatnew ( "file", _A_ NORMAL, &handle2 ) ){ 

printf ( "Unable to create new file\n" ); 

} 

_ dos_ close( handlel ); 

} 


DOS 
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_dos_creatnew 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 
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dosexterr 


Synopsis: #include <dos.h> 

int dosexterr( struct DOSERROR *err_ info ) ; 

struct _ DOSERROR { 

int exterror; 
char errclass; 
char action; 
char locus; 

} ; 

Description: The dosexterr function extracts extended error information following a failed DOS function. This 
information is placed in the structure located by err_info. This function is only useful with DOS 
version 3.0 or later. 

You should consult the technical documentation for the DOS system on your computer for an 
interpretation of the error information. 

Returns: The dosexterr function returns an unpredictable result when the preceding DOS call did not result in 

an error. Otherwise, dosexterr returns the number of the extended error. 

See Also: perror 

Example: #include <stdio.h> 

♦include <dos.h> 

♦include <fcntl.h> 

struct _ DOSERROR dos_ err; 

void main () 

{ 

int handle; 

/* Try to open "stdio.h" and then close it */ 
if ( _ dos_ open ( "stdio.h", 0_ RDONLY, Shandle ) != 0 ){ 

dosexterr( &dos_ err ); 
printf ( "Unable to open file\n" ); 

printf( "exterror (AX) = %d\n", dos_ err.exterror ); 

printf( "errclass (BH) = %d\n", dos_ err. errclass ); 

printf( "action (BL) = %d\n", dos_ err.action ); 

printf( "locus (CH) = %d\n", dos_ err.locus ); 

} else { 

printf( "Open succeeded\n" ); 
if( _ dos_ close( handle ) != 0 ) { 

printf( "Close failed\n" ) ; 

} else { 

printf( "Close succeeded\n" ) ; 

} 

} 

} 

produces the following: 


/* contents of AX register */ 
/* contents of BH register */ 
/* contents of BL register */ 
/* contents of CH register */ 
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dosexterr 


Classification: 

Systems: 


Unable to open file 
exterror (AX) = 2 
errclass (BH) = 8 
action (BL) = 3 
locus (CH) = 2 

DOS 

DOS, Windows, Win386, DOS/PM 
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dos find... Functions 


Synopsis: #include <dos.h> 

unsigned _ dos_ findfirst( const char *path, 

unsigned attributes, 
struct find_ t *buffer ); 

unsigned _ dos_ findnext( struct find_ t *buffer ); 

unsigned _ dos_ findclose( struct find_ t *buffer ); 

struct find_ t { 

char reserved[21] ; /* reserved for use by DOS */ 

char attrib; /* attribute byte for file */ 

unsigned short wr_ time; /* time of last write to file*/ 
unsigned short wr_ date; /* date of last write to file*/ 
unsigned long size; /* length of file in bytes */ 

#if defined (_0S2_) || defined (_NT_) 

char name[256]; /* null-terminated filename */ 

#else 

char name[13]; /* null-terminated filename */ 

#endif 

} ; 

unsigned _wdos_ findfirst( const wchar_ t *path, 

unsigned attributes, 
struct _ wfind_ t *buffer ); 
unsigned _ wdos_ findnext ( struct _ wfind_ t *buffer ); 
unsigned _ wdos_ findclose ( struct _ wfind_ t *buffer ); 

struct _ wfind_ t { 

char reserved[21]; /* reserved for use by DOS */ 

char attrib; /* attribute byte for file */ 

unsigned short wr_ time; /* time of last write to file */ 
unsigned short wr_ date; /* date of last write to file */ 
unsigned long size; /* length of file in bytes */ 

#if defined (_0S2_) || defined (_NT_) 

wchar_ t name[256]; /* null-terminated filename */ 

#else 

wchar_ t name[13]; /* null-terminated filename */ 

#endif 

} ; 

Description: The _ dos_ findfirst function uses system call 0x4E to return information on the first file whose 

name and attributes match the path and attributes arguments. The information is returned in a f ind_ t 
structure pointed to by buffer. The path argument may contain wildcard characters (’?’ and The 
attributes argument may be any combination of the following constants: 

Attribute Meaning 

_A_NORMAL Indicates a normal file. File can be read or written without any restrictions. 
_A_RDONLY Indicates a read-only file. File cannot be opened for "write". 

_A_HIDDEN Indicates a hidden file. This file will not show up in a normal directory search. 

_A_SYSTEM Indicates a system file. This file will not show up in a normal directory search. 

_A_VOLID Indicates a volume-ID. 
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dosjind.. 


Returns: 

See Also: 
Example: 


. Functions 


_A_SUBDIR Indicates a sub-directory. 

_A_ARCH This is the archive flag. It is set whenever the file is modified, and is cleared by the 
MS-DOS BACKUP command and other backup utility programs. 

The attributes argument is interpreted by DOS as follows: 

1. If _ A_ NORMAL is specified, then normal files are included in the search. 

2. If any of _ A_ HIDDEN^ A_ SYSTEM^ A_ SUBDIR are specified, then normal files and the 
specified type of files are included in the search. 

3. If _ A_ VOLID is specified, then volume-ID's are also included in the search. Note: The 
_ A_ VOLID attribute is not supported on systems other than DOS (e.g. Win32, OS/2). 

4. _ A_ RDONLY and_ A_ ARCH are ignored by this function. 

The format of the wr_ time field is described by the following structure (this structure is not defined in 
any Open Watcom header file). 

typedef struct { 


unsigned 

short 

twosecs 

5; 

/* 

seconds 

/ 2 */ 

unsigned 

short 

minutes 

6; 

/* 

minutes 

(0,59) 

unsigned 

short 

hours 

5; 

/* 

hours (0,23) * 


} ftime_ t; 

The format of the wr_ date field is described by the following structure (this structure is not defined in 
any Open Watcom header file). 

typedef struct { 


unsigned 

short 

day 

: 5; 

/* 

day (1,31) */ 

unsigned 

short 

month 

: 4; 

/* 

month (1,12) */ 

unsigned 

short 

year 

: 7; 

/* 

0 is 1980 */ 


} fdate_ t; 

The _ dos_ f indnext function uses system call 0x4F to return information on the next file whose 
name and attributes match the pattern supplied to the _ dos_ f indf irst function. 

On some systems (e.g. Win32, OS/2), you must call _ dos_ f indclose to indicate that you are done 
matching files. This function deallocates any resources that were allocated by the _ dos_ f indf irst 
function. 

The _ wdos_ find. . . functions are similar to their counterparts but operate on wide-character 
strings. 

The _ dos_ find. . . functions return zero if successful. Otherwise, the_ dos_ f indf irst and 
_ dos_ f indnext functions return an OS error code and seferrno accordingly. 

opendir, readdir, closedir 

♦include <stdio.h> 

♦include <dos.h> 

void main() 

{ 

struct find_ t fileinfo; 

unsigned rc; /* return code */ 
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dosjind... Functions 


/* Display name and size of "*.c" files */ 

rc = _ dos_ findfirst( "*.c", _ A_ NORMAL, &fileinfo ); 

while ( rc == 0 ) { 

printf ( "%14s %101d\n", fileinfo.name, 

fileinfo.size ); 

rc = _ dos_ findnext( sfileinfo ) ; 

} 

#if defined (_ 0S2_ ) 

_ dos_ findclose( sfileinfo ); 

#endif 

} 

Classification: DOS 


Systems: 

_ dos_ findclose 

- DOS, 

Windows, 

Win386, 

Win32, 

OS/2 

1.x(all), 

OS/2-32, 


DOS/PM 









_ dos_ findfirst 

- DOS, 

Windows, 

Win386, 

Win32, 

OS/2 

1.x(all), 

OS/2-32, 


DOS/PM 









_ dos_ findnext - 

DOS, 

Windows, 

Win386, 

Win32, 

OS/2 1 

.x(all), 

OS/2-32, 


DOS/PM 









_ wdos_ findclose 

- DOS 

, Windows 

, Win386 

, Win32 

, OS/2 

1.x(all) 

, OS/2-32 


_ wdos_ findfirst 

- DOS 

, Windows 

, Win386 

, Win32 

, OS/2 

1.x(all) 

, OS/2-32 


_ wdos_ findnext 

- DOS, 

Windows, 

Win386, 

Win32, 

OS/2 

1.x(all), 

OS/2-32 
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dos freemem 


Synopsis: 


Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <dos.h> 

#if defined (_NT_) | | \ 

( defined(_0S2_) && \ 

(defined (_ 386_) || defined (_PPC_)) ) 

unsigned _ dos_ freemem ( void * segment ); 

♦ else 

unsigned _ dos_ freemem( unsigned segment ); 

♦endif 

The _ dos_ freemem function uses system call 0x49 to release memory that was previously allocated 
by _ dos_ allocmem. The value contained in segment is the one returned by a previous call to 
_ dos_ allocmem. 

For 32-bit DOS applications, it is recommended that the corresponding DPMI services be used. 

The _ dos_ freemem function returns zero if successful. Otherwise, it returns an OS error code and 
sets errno accordingly. 

_ dos_ allocmem^ dos_ setblockfree, hfree 

♦include <stdio.h> 

♦include <dos.h> 

void main( void ) 

{ 

♦ if defined (_NT_) | | \ 

( defined!_OS2_) && \ 

(defined (_ 386_) || defined!_PPC_)) ) 

void *segment; 

♦ else 

unsigned segment; 

♦endif 

/* Try to allocate 100 paragraphs, then free them */ 
if( _ dos_ allocmem( 100, ^segment ) != 0 ) { 

printf( dos_ allocmem failed\n" ) ; 
printf( "Only %u paragraphs available\n", 
segment ); 

} else { 

printf( dos_ allocmem succeeded\n" ) ; 
if ( _ dos_ freemem( segment ) != 0 ) { 

printf( dos_ freemem failed\n" ); 

} else { 

printf ( dos_ freemem succeeded\n" ) ; 


} 

} 

DOS 

DOS, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 
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dos_getdate 


Synopsis: 


Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <dos.h> 

void _ dos_ getdate ( struct dosdate_ t *date ); 

struct dosdate_ t { 

unsigned char day; /* 1-31 */ 

unsigned char month; /* 1-12 */ 

unsigned short year; /* 1980-2099 */ 
unsigned char dayofweek;/* 0-6 (0=Sunday) */ 

} ; 

The _ dos_ getdate function uses system call 0x2A to get the current system date. The date 

information is returned in a dosdate_ t structure pointed to by date. 

The _ dos_ getdate function has no return value. 

_ dos_ gettimej. dos_ setdate^, dos_ settimegmtime, localtime, mktime, time 

♦include <stdio.h> 

♦include <dos.h> 


void main() 

1 

struct dosdate_ t date; 
struct dostime_ t time; 


} 


/* Get and display the current date and time */ 

_ dos_ getdate( &date ); 

_ dos_ gettime( &time ); 

printf ( "The date (MM-DD-YYYY) is: %d-%d-%d\n", 
date.month, date.day, date.year ); 
printf ( "The time (HH:MM:SS) is: %.2d:%.2d:%.2d\n", 
time.hour, time.minute, time.second ); 


produces the following: 

The date (MM-DD-YYYY) is: 12-25-1989 
The time (HH:MM:SS) is: 14:23:57 


DOS 


DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 


Library Functions and Macros 185 




dos_getdiskfree 


Synopsis: 


Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <dos.h> 

unsigned _ dos_ getdiskfree( unsigned drive, 

struct diskfree_ t *diskspace ); 

struct diskfree_ t { 

unsigned short total_ clusters; 
unsigned short avail_ clusters; 
unsigned short sectors_ per_ cluster; 
unsigned short bytes_ per_ sector; 

} ; 

The _ dos_ getdiskfree function uses system call 0x36 to obtain useful information on the disk 
drive specified by drive. Specify 0 for the default drive, 1 for drive A, 2 for drive B, etc. The 
information about the drive is returned in the structure diskf ree_ t pointed to by diskspace. 

The _ dos_ getdiskfree function returns zero if successful. Otherwise, it returns a non-zero value 
and sets errno to EINVAL indicating an invalid drive was specified. 

_ dos_ getdrive^. dos_ setdrive^, getdiskfree,_ getdrive 

♦include <stdio.h> 

♦include <dos.h> 

void main() 

{ 

struct diskfree_ t disk_ data; 

/* get information about drive 3 (the C drive) */ 
if ( _ dos_ getdiskfree ( 3, &disk_ data ) == 0 ) { 

printf( "total clusters: %u\n", 

disk_ data.total_ clusters ); 
printf( "available clusters: %u\n", 

disk_ data.avail_ clusters ); 
printf( "sectors/cluster: %u\n", 

disk_ data. sectors_ per_ cluster ) ; 
printf( "bytes per sector: %u\n", 

disk_ data.bytes_ per_ sector ); 

} else { 

printf( "Invalid drive specified\n" ); 

} 

} 

produces the following: 

total clusters: 16335 
available clusters: 510 
sectors/cluster: 4 
bytes per sector: 512 

DOS 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 
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dos_getdrive 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <dos.h> 

void _ dos_ getdrive ( unsigned *drive ) ; 

The _ dos_ getdrive function uses system call 0x19 to get the current disk drive number. The 
current disk drive number is returned in the word pointed to by drive. A value of 1 is drive A, 2 is drive 
B, 3 is drive C, etc. 

The _ dos_ getdrive function has no return value. 

_ dos_ getdiskfreej_ dos_ setdrive^. getdiskfree^ getdrive 

♦include <stdio.h> 

♦include <dos.h> 


void main() 

{ 

unsigned drive; 


} 


_ dos_ getdrive( Sdrive ); 
printf ( "The current drive is %c\n", 
'A' + drive - 1 ); 


produces the following: 

The current drive is C 


DOS 

DOS. Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 
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dos_getfileattr 


Synopsis: #include <dos.h> 

unsigned _ dos_ getfileattr( const char *path, 

unsigned *attributes ); 

Description: The _ dos_ getf ileattr function uses system call 0x43 to get the current attributes of the file or 
directory that path points to. The possible attributes are: 

Attribute Meaning 

_A_NORMAL Indicates a normal file. File can be read or written without any restrictions. 
_A_RDONLY Indicates a read-only file. File cannot be opened for "write". 

_A_HIDDEN Indicates a hidden file. This file will not show up in a normal directory search. 

_A_SYSTEM Indicates a system file. This file will not show up in a normal directory search. 

Indicates a volume-ID. 

Indicates a sub-directory. 


Returns: 


_A_VOLID 
_A_SUBDIR 
A ARCH 


This is the archive flag. It is set whenever the file is modified, and is cleared by the 
MS-DOS BACKUP command and other backup utility programs. 


The _ dos_ getf ileattr function returns zero if successful. Otherwise, it returns an OS error code 
and sets errno accordingly. 


See Also: 


dos_ setfileattr 


Example: #include <stdio.h> 

♦include <dos.h> 

print_ attribute() 

{ 

unsigned attribute; 

_ dos_ getfileattr( "file", Sattribute ); 
printf( "File attribute is %d\n", attribute ); 
if( attribute & _ A_ RDONLY ) { 

printf( "This is a read-only file.Xn" ); 

} else { 

printf ( "This is not a read-only file.Xn" ); 

} 

} 

void main() 

{ 

int handle; 
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dos_getfileattr 


Classification: 

Systems: 


if ( _ dos_ creat ( "file", _ A_ RDONLY, Shandle ) != 0 ) { 

printf( "Error creating file\n" ); 

} 

print_ attribute (); 

_ dos_ setfileattr ( "file", _ A_ NORMAL ); 
print_ attribute (); 

_ dos_ close( handle ); 

} 

DOS 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 
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dos_getftime 


Synopsis: #include <dos.h> 

unsigned _ dos_ getftime( int handle, 

unsigned *date, 
unsigned *time ); 

Description: The _ dos_ getftime function uses system call 0x57 to get the date and time that the file associated 
with handle was last modified. The date consists of the year, month and day packed into 16 bits as 
follows: 

Bits Meaning 

bits 0-4 Day (1-31) 

bits 5-8 Month (1-12) 

bits 9-15 Year (0-119 representing 1980-2099) 

The time consists of the hour, minute and seconds/2 packed into 16 bits as follows: 

Bits Meaning 

bits 0-4 Seconds/2 (0-29) 

bits 5-10 Minutes (0-59) 

bits 11-15 Hours (0-23) 

Returns: The _ dos_ getftime function returns zero if successful. Otherwise, it returns an OS error code and 

sets errno accordingly. 

See Also: _ dos_ setftime 

Example: ((include <stdio.h> 

((include <dos.h> 

((include <fcntl.h> 

((define YEAR (t) ( ( (t & OxFEOO) » 9) + 1980) 

((define MONTH (t) ( (t & OxOlEO) » 5) 

((define DAY(t) (t & OxOOlF) 

((define HOUR(t) ( (t & 0xF800) » 11) 

((define MINUTE (t) ( (t & 0x07E0) » 5) 

((define SECOND (t) ( (t & OxOOlF) « 1) 

void main( void ) 

{ 

int handle; 

unsigned date, time; 
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dos_getftime 


Classification: 

Systems: 


if ( _ dos_ open ( "file", 0_ RDONLY, Shandle ) != 0 ) { 

printf ( "Unable to open file\n" ); 

} else { 

printf ( "Open succeeded\n" ); 

_ dos_ getftime( handle, &date, &time ); 
printf ( "The file was last modified on %d/%d/%d", 
MONTH(date), DAY(date), YEAR(date) ); 
printf ( " at %.2d:%.2d:%.2d\n", 

HOUR(time), MINUTE(time), SECOND(time) ); 
_ dos_ close( handle ); 

} 

} 

produces the following: 

Open succeeded 

The file was last modified on 12/29/1989 at 14:32:46 

DOS 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 
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dos_gettime 


Synopsis: #include <dos.h> 

void _ dos_ gettime ( struct dostime_ t *time ) ; 

struct dostime_ t { 

unsigned char hour; /* 0-23 */ 

unsigned char minute; /* 0-59 */ 

unsigned char second; /* 0-59 */ 

unsigned char hsecond; /* 1/100 second; 0-99 */ 

} ; 

Description: The _ dos_ gettime function uses system call 0x2C to get the current system time. The time 
information is returned in a dostime_ t structure pointed to by time. 

Returns: The _ dos_ gettime function has no return value. 

See Also: _ dos_ getdate^. dos_ setdate^ dos_ settimegmtime, localtime, mktime, time 

Example: #include <stdio.h> 

♦include <dos.h> 

void main() 

{ 

struct dosdate_ t date; 
struct dostime_ t time; 

/* Get and display the current date and time */ 

_ dos_ getdate( &date ); 

_ dos_ gettime( &time ); 

printf ( "The date (MM-DD-YYYY) is: %d-%d-%d\n", 
date.month, date.day, date.year ); 
printf ( "The time (HH:MM:SS) is: %.2d:%.2d:%.2d\n", 
time.hour, time.minute, time.second ); 

} 

produces the following: 

The date (MM-DD-YYYY) is: 12-25-1989 
The time (HH:MM:SS) is: 14:23:57 

Classification: DOS 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 
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dos_getvect 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <dos.h> 

void (_interrupt_far *_ dos_ getvect (unsigned intnum) ) () ; 

The _ dos_ getvect function gets the current value of interrupt vector number intnum. 

The _ dos_ getvect function returns a far pointer to the current interrupt handler for interrupt number 
intnum. 

_ chain_ intr*. dos_ keep^ dos_ setvect 

#include <stdio.h> 

♦include <dos.h> 

volatile int clock_ ticks; 

void (_interrupt_far *prev_ int_ lc) () ; 

♦define BLIP_ COUNT (5*18) /* 5 seconds */ 

void_interrupt_far timer_rtn() 

{ 

++clock_ ticks; 

_ chain_ intr ( prev_ int_ lc ) ; 

} 

int delays = 0; 

int compile_ a_ line() 

{ 

if( delays > 15 ) return( 0 ); 

delay( 1000 ); /* delay for 1 second */ 

printf ( "Delayed for 1 second\n" ); 

delays++; 

return( 1 ); 

} 

void main() 

{ 

prev_ int_ lc = _ dos_ getvect ( Oxlc ) ; 

_ dos_ setvect ( Oxlc, timer_ rtn ); 
while ( compile_ a_ line () ) { 

if( clock_ ticks >= BLIP_ COUNT ) { 

putchar( '.' ); 

clock_ ticks -= BLIP_ COUNT; 

} 

} 

_ dos_ setvect ( Oxlc, prev_ int_ lc ); 

} 

WATCOM 

DOS, Windows, DOS/PM 
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dos_keep 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <dos.h> 

void _ dos_ keep ( unsigned retcode, unsigned memsize ); 

The _ dos_ keep function is used to install terminate-and-stay-resident programs ("TSR’s") in 
memory. The amount of memory kept for the program is memsize paragraphs (a paragraph is 16 bytes) 
from the Program Segment Prefix which is stored in the variable _ psp. The value of retcode is 
returned to the parent process. 

The _ dos_ keep function does not return. 

_ chain_ intr^ dos_ getvect*. dos_ setvect 

♦include <dos.h> 

void permanent!) 

{ 

/* . */ 

/* . */ 

/* . */ 

} 

void transient!) 

{ 

/* . */ 

/* . */ 

/* . */ 

} 

void main() 

{ 

/* initialize our TSR */ 
transient(); 

/* 

now terminate and keep resident 
the non-transient portion 

*/ 

_ dos_ keep ( 0, (FP_ OFF ( transient ) + 15) >> 4 ); 

} 

DOS 

DOS 


194 Library Functions and Macros 




dos_open 


Synopsis: 


Description: 


Returns: 


See Also: 


♦include 

♦include 

♦include 

unsigned 


<dos.h> 

<fcntl.h> 

<share.h> 

_ dos_ open ( const char *path, 
unsigned mode, 
int *handle ); 


The _ dos_ open function uses system call 0x3D to open the file specified by path, which must be an 
existing file. The mode argument specifies the file’s access, sharing and inheritance permissions. The 
access mode must be one of: 


Mode 


Meaning 


OJtDONLY 

OJWRONLY 

0_RDWR 


Read only 
Write only 
Both read and write 


The sharing permissions, if specified, must be one of: 


Permission Meaning 


SHJCOMPAT 

SH_DENYRW 

SH_DENYWR 

SH_DENYRD 

SH_DENYNO 


Set compatibility mode. 

Prevent read or write access to the file. 
Prevent write access of the file. 

Prevent read access to the file. 

Permit both read and write access to the file. 


The inheritance permission, if specified, is: 


Permission Meaning 

ON OINMERIT File is not inherited by a child process 

The _ dos_ open function returns zero if successful. Otherwise, it returns an MS-DOS error code and 
sets errno to one of the following values: 


Constant 

EACCES 

EINVAL 

EMFILE 

ENOENT 


Meaning 

Access denied because path specifies a directory or a volume ID, or opening a 
read-only file for write access 

A sharing mode was specified when file sharing is not installed, or access-mode 
value is invalid 

No more handles available, (too many open files) 

Path or file not found 


_ dos_ close*. dos_ creat* dos_ creatnew*. dos_ read* dos_ writefdopen, fopen, 
freopen, _ fsopen,_ grow_ handles** hdopen.open, _ open_ osfhandle*. popen, 
sopen 
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dos_open 


Example: 


Classification: 

Systems: 


♦include <stdio.h> 

♦include <dos.h> 

♦include <fcntl.h> 

♦include <share.h> 

void main() 

{ 

int handle; 

if ( _ dos_ open ( "file", 0_ RDONLY, Shandle ) != 0 ) { 

printf ( "Unable to open file\n" ); 

} else { 

printf ( "Open succeeded\n" ); 

_ dos_ close( handle ); 

} 

} 

DOS 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


dos_read 


♦include <dos.h> 

unsigned _ dos_ read ( int handle, void_far *buffer, 

unsigned count, unsigned *bytes ); 

The _ dos_ read function uses system call 0x3F to read count bytes of data from the file specified by 
handle into the buffer pointed to by buffer. The number of bytes successfully read will be stored in the 
unsigned integer pointed to by bytes. 

The _ dos_ read function returns zero if successful. Otherwise, it returns an OS error code and sets 
errno accordingly. 

_ dos_ closer dos_ open^ dos_ write 

♦include <stdio.h> 

♦include <dos.h> 

♦include <fcntl.h> 

void main() 

{ 

unsigned len_ read; 
int handle; 

auto char buffer[80]; 

if ( _ dos_ open ( "file", 0_ RDONLY, Shandle ) != 0 ) { 

printf( "Unable to open file\n" ); 

} else { 

printf( "Open succeeded\n" ); 

_ dos_ read ( handle, buffer, 80, &len_ read ); 

_ dos_ close( handle ); 

} 

} 

DOS 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 
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dos setblock 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


#include <dos.h> 

unsigned _ dos_ setblock( unsigned size, 

unsigned segment, 
unsigned *maxsize ); 

The _ dos_ setblock function uses system call 0x4A to change the size of segment, which was 
previously allocated by _ dos_ allocmem, to size paragraphs. If the request fails, the maximum 
number of paragraphs that this memory block can be changed to is returned in the word pointed to by 
maxsize. 

For 32-bit DOS applications, it is recommended that the corresponding DPMI services be used. 

The _ dos_ setblock function returns zero if successful. Otherwise, it returns an OS error code and 
sets errno to ENOMEM indicating a bad segment value, insufficient memory or corrupted memory. 

_ dos_ allocmem^ dos_ freememrealloc 

♦include <stdio.h> 

♦include <dos.h> 

void main( void ) 

{ 

♦ if defined!_NT_) | | \ 

( defined!_0S2_) && \ 

(defined!_ 386_) || defined!_PPC_)) ) 

void *segment; 

♦ else 

unsigned segment; 

♦endif 

/* Try to allocate 100 paragraphs, then free them */ 
if( _ dos_ allocmem( 100, ^segment ) != 0 ) { 

printf( dos_ allocmem failed\n" ) ; 
printf ( "Only %u paragraphs available\n", segment); 

} else { 

printf( dos_ allocmem succeeded\n" ) ; 

♦ if defined!_DOS_) 

{ unsigned maxsize = 0; 

/* Try to increase it to 200 paragraphs */ 
if( _ dos_ setblock( 200, segment, Smaxsize ) != 0 ) { 

printf! dos_ setblock failed: max=%u, err=%s\n", 
maxsize, strerror( errno) ); 

} else { 

printf( dos_ setblock succeeded\n" ); 


♦endif 
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dos_setblock 


if ( _ dos_ freememf segment ) != 0 ) { 

printf( dos_ freemem failed\n" ) ; 

} else { 

printf ( dos_ freemem succeeded\n" ) ; 


} 

} 

Classification: DOS 
Systems: DOS, DOS/PM 
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dos setdate 


Synopsis: 


Description: 

Returns: 

See Also: 
Example: 


#include <dos.h> 

unsigned _ dos_ setdate( struct dosdate_ t *date ); 


struct dosdate_ t { 

unsigned char day; /* 
unsigned char month; /* 
unsigned short year; /* 
unsigned char dayofweek;/* 


1-31 */ 

1-12 */ 
1980-2099 */ 
0-6 (0=Sunday) 


*/ 


The _ dos_ setdate function uses system call 0x2B to set the current system date. The date 
information is passed in a dosdate_ t structure pointed to by date. 


The _ dos_ setdate function returns zero if successful. Otherwise, it returns an OS error code and 
sets errno accordingly. 


_ dos_ getdate^. dos_ gettimej, dos_ settimegmtime, localtime, mktime, time 

♦include <stdio.h> 

♦include <dos.h> 


void main() 

{ 

struct dosdate_ t date; 
struct dostime_ t time; 

/* Get and display the current date and time */ 

_ dos_ getdate( &date ); 

_ dos_ gettime ( &time ); 

printf ( "The date (MM-DD-YYYY) is: %d-%d-%d\n", 
date.month, date.day, date.year ); 
printf ( "The time (HH:MM:SS) is: %.2d:%.2d:%.2d\n", 
time.hour, time.minute, time.second ); 

/* Change it to the turn of the century */ 

date.year = 1999; 

date.month = 12; 

date.day = 31; 

time.hour = 23; 

time.minute = 59; 

_ dos_ setdate( &date ); 

_ dos_ settime( &time ); 

printf( "New date (MM-DD-YYYY) is: %d-%d-%d\n", 
date.month, date.day, date.year ); 
printf( "New time (HH:MM:SS) is: %.2d:%.2d:%.2d\n", 
time.hour, time.minute, time.second ); 


produces the following: 


The date 
The time 
New date 
New time 


(MM-DD-YYYY) is: 12-25-1989 
(HH:MM:SS) is: 14:23:15 
(MM-DD-YYYY) is: 12-31-1999 
(HH:MM:SS) is: 23:59:16 
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dos_setdate 


Classification: DOS 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 
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dos setdrive 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <dos.h> 

void _ dos_ setdrive( unsigned drive, unsigned *total ); 

The _ dos_ setdrive function uses system call OxOE to set the current default disk drive to be the 
drive specified by drive, where 1 = drive A, 2 = drive B, etc. The total number of disk drives is returned 
in the word pointed to by total. For DOS versions 3.0 or later, the minimum number of drives returned 
is 5. 

The _ dos_ setdrive function has no return value. If an invalid drive number is specified, the 
function fails with no error indication. You must use the _ dos_ getdrive function to check that the 
desired drive has been set. 

_ dos_ getdiskfreej_ dos_ getdrive^. getdiskfree^ getdrive 

♦include <stdio.h> 

♦include <dos.h> 

void main() 

{ 

unsigned drivel, drive2, total; 

_ dos_ getdrive ( Sdrivel ) ; 

printf ( "Current drive is %c\n", 'A' + drivel - 1 ); 

/* try to change to drive C */ 

_ dos_ setdrive( 3, stotal ); 

_ dos_ getdrive ( &drive2 ); 

printf( "Current drive is %c\n", 'A' + drive2 - 1 ); 

/* go back to original drive */ 

_ dos_ setdrive( drivel, Stotal ); 

_ dos_ getdrive ( Sdrivel ) ; 

printf( "Current drive is %c\n", 'A' + drivel - 1 ); 
printf ( "Total number of drives is %u\n", total ); 

} 

produces the following: 

Current drive is D 
Current drive is C 
Total number of drives is 6 

DOS 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 
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Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


dos_setfileattr 


♦include <dos.h> 

unsigned _ dos_ setfileattr( const char *path, 

unsigned attributes ) ; 

The _ dos_ setf ileattr function uses system call 0x43 to set the attributes of the file or directory 
that path points to. The possible attributes are: 

Attribute Meaning 

_A_NORMAL Indicates a normal file. File can be read or written without any restrictions. 
_A_RDONLY Indicates a read-only file. File cannot be opened for "write". 

A IIIDDEN Indicates a hidden file. This file will not show up in a normal directory search. 

A SYSTEM Indicates a system file. This file will not show up in a normal directory search. 

A VOEII) Indicates a volume-ID. 

_A_SUBDIR Indicates a sub-directory. 

_A_ARCH This is the archive flag. It is set whenever the file is modified, and is cleared by the 
MS-DOS BACKUP command and other backup utility programs. 

The _ dos_ setf ileattr function returns zero if successful. Otherwise, it returns an OS error code 
and sets errno accordingly. 

_ dos_ getfileattr 


♦include <stdio.h> 
♦include <dos.h> 


print_ attribute() 

{ 

unsigned attribute; 

_ dos_ getfileattr( "file", Sattribute ); 
printf ( "File attribute is %x\n", attribute ); 
if ( attribute & _ A_ RDONLY ) { 

printf( "This is a read-only file\n" ) ; 

} else { 

printf ( "This is not a read-only file\n" ); 

} 

} 

void main() 

1 

int handle; 
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dos setfileattr 


Classification: 

Systems: 


if ( _ dos_ creat ( "file", _ A_ RDONLY, Shandle ) != 0 ){ 

printf( "Error creating file\n" ); 

} 

print_ attribute (); 

_ dos_ setfileattr ( "file", _ A_ NORMAL ); 
print_ attribute (); 

_ dos_ close( handle ); 

} 

DOS 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 
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dos setftime 


Synopsis: #include <dos.h> 

unsigned _ dos_ setftime( int handle, 

unsigned date, 
unsigned time ); 

Description: The _ dos_ setftime function uses system call 0x57 to set the date and time that the file associated 
with handle was last modified. The date consists of the year, month and day packed into 16 bits as 
follows: 

Bits Meaning 

bits 0-4 Day (1-31) 

bits 5-8 Month (1-12) 

bits 9-15 Year (0-119 representing 1980-2099) 

The time consists of the hour, minute and seconds/2 packed into 16 bits as follows: 

Bits Meaning 

bits 0-4 Seconds/2 (0-29) 

bits 5-10 Minutes (0-59) 

bits 11-15 Hours (0-23) 

Returns: The _ dos_ setftime function returns zero if successful. Otherwise, it returns an OS error code and 

sets errno accordingly. 

See Also: _ dos_ getftime 

Example: ((include <stdio.h> 

((include <dos.h> 

((include <fcntl.h> 

((define YEAR (t) ( ( (t & OxFEOO) » 9) + 1980) 

((define MONTH (t) ( (t & OxOlEO) » 5) 

((define DAY(t) (t & OxOOlF) 

((define HOUR(t) ( (t & 0xF800) » 11) 

((define MINUTE (t) ( (t & 0x07E0) » 5) 

((define SECOND (t) ( (t & OxOOlF) « 1) 

void main( void ) 

{ 

int handle; 

unsigned short date, time; 
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dos setftime 


Classification: 

Systems: 


if ( _ dos_ open ( "file", 0_ RDWR, Shandle ) != 0 ) { 

printf ( "Unable to open file\n" ); 

} else { 

printf( "Open succeeded\n" ); 

_ dos_ getftime( handle, &date, &time ); 
printf ( "The file was last modified on %d/%d/%d", 
MONTH(date), DAY(date), YEAR(date) ); 
printf ( " at %.2d:%.2d:%.2d\n", 

HOUR(time), MINUTE(time), SECOND(time) ); 
/* set the time to 12 noon */ 
time = (12 << 11) + (0 << 5) + 0; 

_ dos_ setftime( handle, date, time ); 

_ dos_ getftime( handle, &date, &time ); 
printf ( "The file was last modified on %d/%d/%d", 
MONTH(date), DAY(date), YEAR(date) ); 
printf ( " at %.2d:%.2d:%.2d\n", 

HOUR(time), MINUTE(time), SECOND(time) ); 
_ dos_ close( handle ); 

} 

} 

produces the following: 

Open succeeded 

The file was last modified on 12/29/1989 at 14:32:46 

The file was last modified on 12/29/1989 at 12:00:00 

DOS 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 
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dos_settime 


Synopsis: 


#include <dos.h> 

unsigned _ dos_ settime ( struct 

struct dostime_ t { 

unsigned char hour; 
unsigned char minute; 
unsigned char second; 
unsigned char hsecond; 

} ; 


dostime_ t *time ) ; 

/* 0-23 */ 

/* 0-59 */ 

/* 0-59 */ 

/* 1/100 second; 0-99 */ 


Description: 


The _ dos_ settime function uses system call 0x2D to set the current system time. The time 
information is passed in a dostime_ t structure pointed to by time. 


Returns: The _ dos_ settime function returns zero if successful. Otherwise, it returns a non-zero value and 

sets errno to EINVAL indicating that an invalid time was given. 


See Also: 


dos_ getdate^. dos_ setdate^ dos_ gettimegmtime, localtime, mktime, time 


Example: #include <stdio.h> 

♦include <dos.h> 


void main() 

{ 

struct dosdate_ t date; 
struct dostime_ t time; 

/* Get and display the current date and time */ 

_ dos_ getdate( &date ); 

_ dos_ gettime ( &time ); 

printf( "The date (MM-DD-YYYY) is: %d-%d-%d\n", 
date.month, date.day, date.year ); 
printf ( "The time (HH:MM:SS) is: %.2d:%.2d:%.2d\n", 
time.hour, time.minute, time.second ); 


} 


/* Change it to the turn of the century */ 

date.year = 1999; 

date.month = 12; 

date.day = 31; 

time.hour = 23; 

time.minute = 59; 

_ dos_ setdate( &date ); 

_ dos_ settime( &time ); 

printf ( "New date (MM-DD-YYYY) is: %d-%d-%d\n", 
date.month, date.day, date.year ); 
printf ( "New time (HH:MM:SS) is: %.2d:%.2d:%.2d\n", 
time.hour, time.minute, time.second ); 


produces the following: 


The 

date 

(MM-DD-YYYY) is 

: 12-25-1989 

The 

time 

(HH:MM:SS) is: 

14:23:15 

New 

date 

(MM-DD-YYYY) is 

: 12-31-1999 

New 

Classification: DOS 

time 

(HH:MM:SS) is: 

23:59:16 
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_dos_settime 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


dos^setvect 


#include <dos.h> 

void _ dos_ setvect( unsigned intnum, 

void (_interrupt_far *handler) () ) ; 

The _ dos_ setvect function sets interrupt vector number intnum to point to the interrupt handling 
function pointed to by handler. 

The _ dos_ setvect function does not return a value. 

_ chain_ intr^ dos_ getvect*. dos_ keep 

♦include <stdio.h> 

♦include <dos.h> 

volatile int clock_ ticks; 

void (_interrupt_far *prev_ int_ lc) () ; 

♦define BLIP_ COUNT (5*18) /* 5 seconds */ 

void_interrupt_far timer_rtn() 

{ 

++clock_ ticks; 

_ chain_ intr ( prev_ int_ lc ) ; 

} 


int compile_ a_ line () 

1 

static int delays = 0; 

if( delays > 15 ) return ( 0 ); 

delay! 1000 ); /* delay for 1 second */ 

printf ( "Delayed for 1 second\n" ); 

delays++; 

return( 1 ); 

} 

void main() 

1 

prev_ int_ lc = _ dos_ getvect ( Oxlc ) ; 

_ dos_ setvect ( Oxlc, timer_ rtn ); 
while! compile_ a_ line() ) { 

if( clock_ ticks >= BLIP_ COUNT ) { 

putchar( ' . ' ) ; 

clock_ ticks -= BLIP_ COUNT; 

} 

} 

_ dos_ setvect ( Oxlc, prev_ int_ lc ); 

} 

WATCOM 

DOS. Windows, DOS/PM 
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_dos_write 

Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <dos.h> 

unsigned _ dos_ write( int handle, void const _ far *buffer, 

unsigned count, unsigned *bytes ); 

The _ dos_ write function uses system call 0x40 to write count bytes of data from the buffer pointed 
to by buffer to the file specified by handle. The number of bytes successfully written will be stored in 
the unsigned integer pointed to by bytes. 

The _ dos_ write function returns zero if successful. Otherwise, it returns an OS error code and sets 
errno accordingly. 

_ dos_ close^ dos_ open^ dos_ read 

♦include <stdio.h> 

♦include <dos.h> 

♦include <fcntl.h> 

char buffer[] = "This is a test for _ dos_ write ; 

void main() 

{ 

unsigned len_ written; 
int handle; 

if ( _ dos_ creat ( "file", _ A_ NORMAL, Shandle ) != 0 ) { 

printf( "Unable to create file\n" ); 

} else { 

printf ( "Create succeeded\n" ); 

_ dos_ write( handle, buffer, sizeof(buffer), 

&len_ written ) ; 

_ dos_ close( handle ); 

} 

} 

DOS 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, DOS/PM 
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dup, _dup 


Synopsis: 


Description: 


Returns: 


Errors: 


See Also: 


Example: 


Classification: 


Systems: 


♦include <io.h> 

int dup( int handle ) ; 

int _ dup ( int handle ) ; 

The dup function duplicates the file handle given by the argument handle. The new file handle refers 
to the same open file handle as the original file handle, and shares any locks. The new file handle is 
identical to the original in that it references the same file or device, it has the same open mode (read 
and/or write) and it will have file position identical to the original. Changing the position with one 
handle will result in a changed position in the other. 

The _ dup function is identical todup. Use _ dup for ANSI naming conventions. 

If successful, the new file handle is returned to be used with the other functions which operate on the 
file. Otherwise, -1 is returned and errno is set to indicate the error. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EBADF The argument handle is not a valid open file handle. 

EMFILE The number of file handles would exceed {OPEN_MAX}. 

chsize, close, creat, dup2, eof, exec. . ., fdopen, filelength, fileno, fstat, 

_ grow_ handlesisatty, Iseek, open, read, setmode, sopen, stat, tell, write, 
umask 

♦include <fcntl.h> 

♦include <io.h> 

void main( void ) 

{ 

int handle, dup_ handle; 


handle = open ( "file". 




0_ WRONLY 

0_ CREAT 

0_ TRUNC 

| 0_ TEXT, 

S_ IRUSR 

S_ IWUSR 

S_ IRGRP | 

S_ IWGRP ); 

if( handle != -1 ) { 




dup_ handle = dup ( 

handle ); 



if( dup_ handle != 

-1 ) { 




/* process file */ 


close ( dup_ handle ); 

} 

close ( handle ); 

} 

} 

POSIX 1003.1 

_dup conforms to ANSI naming conventions 
dup - All, Linux, RDOS, Netware 

_ dup - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS 
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dup2, jdup2 


Synopsis: 


Description: 


Returns: 


Errors: 


See Also: 


Example: 


Classification: 


♦include <io.h> 

int dup2( int handle, int handle2 ); 
int _ dup2( int handle, int handle2 ); 

The dup2 function duplicates the file handle given by the argument handle. The new file handle is 
identical to the original in that it references the same file or device, it has the same open mode (read 
and/or write) and it will have identical file position to the original (changing the position with one 
handle will result in a changed position in the other). 

The number of the new handle is handle2. If a file already is opened with this handle, the file is closed 
before the duplication is attempted. 

The _ dup2 function is identical todup2. Use _ dup2 for ANSI naming conventions. 

The dup2 function returns zero if successful. Otherwise, -1 is returned and errno is set to indicate 
the error. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EBADF The argument handle is not a valid open file handle or handle2 is out of range. 

EMFILE The number of file handles would exceed {OPEN_MAX}, or no file handles 

above handle2 are available. 

chsize, close, creat, dup, eof, exec. . ., fdopen, filelength, fileno, fstat, 

_ grow_ handlesisatty, lseek, open, read, setmode, sopen, stat, tell, write, 
umask 


♦include <fcntl.h> 
♦include <io.h> 


void main() 

{ 

int handle, dup_ handle; 


handle = open ( "file", 

0_ WRONLY | 0_ CREAT 
S_ IRUSR | S_ IWUSR 
if( handle != -1 ) { 

dup_ handle = 4; 
if( dup2 ( handle, dup_ handle 


0_ TRUNC | 0_ TEXT, 

S_ IRGRP | S_ IWGRP ) ; 

!= -1 ) { 


/* process file */ 


close ( dup_ handle ); 

} 

close( handle ); 

} 

} 


POSIX 1003.1 

_dup2 conforms to ANSI naming conventions 
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dup2, jdup2 


Systems: 


dup2 - 
_ dup2 


All, Linux, RDOS, Netware 
- DOS, Windows, Win386, Win32, 


OS/2 1.x(all), 


OS/2-32, RDOS 
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dwDeleteOnClose 


Synopsis: #include <wdefwin.h> 

int _ dwDeleteOnClose( int handle ); 

Description: The _ dwDeleteOnClose function tells the console window that it should close itself when the 
corresponding file is closed. The argument handle is the handle associated with the opened console. 

The _ dwDeleteOnClose function is one of the support functions that can be called from an 
application using Open Watcom’s default windowing support. 

Returns: The _ dwDeleteOnClose function returns 1 if it was successful and 0 if not. 

See Also: _ dwSetAboutDlg,_ dwSetAppTitle,_ dwSetConTitle,_ dwShutDown,_ dwYield 

Example: #include <wdefwin.h> 

♦include <stdio.h> 

void main() 

{ 

FILE *sec; 

_ dwSetAboutDlg( "Hello World About Dialog", 

"About Hello World\n" 

"Copyright 1994 by WATCOM\n" ); 

_ dwSetAppTitle( "Hello World Application Title" ); 

_ dwSetConTitle( 0, "Hello World Console Title" ); 
printf( "Hello World\n" ) ; 
sec = fopen( "CON", "r+" ); 

_ dwSetConTitle( fileno( sec ) , 

"Hello World Second Console Title" ); 

_ dwDeleteOnClose ( fileno( sec ) ); 

fprintf( sec, "Hello to second console\n" ); 

fprintf( sec, "Press Enter to close this console\n" ); 

fflush( sec ); 

fgetc( sec ) ; 

fclose ( sec ); 

} 

Classification: WATCOM 

Systems: Windows, Win386, Win32, OS/2-32 
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dwSetAboutDIg 


Synopsis: #include <wdefwin.h> 

int _ dwSetAboutDIg( const char *title, const char *text ); 

Description: The _ dwSetAboutDIg function sets the "About" dialog box of the default windowing system. The 
argument title points to the string that will replace the current title. If title is NULL then the title will 
not be replaced. The argument text points to a string which will be placed in the "About" box. To get 
multiple lines, embed a new line after each logical line in the string. If text is NULL, then the current 
text in the "About" box will not be replaced. 

The _ dwSetAboutDIg function is one of the support functions that can be called from an application 
using Open Watcom’s default windowing support. 

Returns: The _ dwSetAboutDIg function returns 1 if it was successful and 0 if not. 

See Also: _ dwDeleteOnClose,_ dwSetAppTitle,_ dwSetConTitle,_ dwShutDown,_ dwYield 

Example: #include <wdefwin.h> 

♦include <stdio.h> 

void main() 

{ 

FILE *sec; 

_ dwSetAboutDIg( "Hello World About Dialog", 

"About Hello World\n" 

"Copyright 1994 by WATCOM\n" ); 

_ dwSetAppTitle( "Hello World Application Title" ); 

_ dwSetConTitle( 0, "Hello World Console Title" ); 
printf( "Hello World\n" ); 
sec = fopen( "CON", "r+" ); 

_ dwSetConTitle( fileno( sec ), 

"Hello World Second Console Title" ); 

_ dwDeleteOnClose ( fileno( sec ) ); 

fprintf( sec, "Hello to second console\n" ); 

fprintf( sec, "Press Enter to close this console\n" ); 

fflush( sec ); 

fgetc( sec ) ; 

fclose ( sec ); 

} 

Classification: WATCOM 

Systems: Windows, Win386, Win32, OS/2-32 
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dwSetAppTitle 


Synopsis: #include <wdefwin.h> 

int _ dwSetAppTitle( const char *title ); 

Description: The _ dwSetAppTitle function sets the main window’s title. The argument title points to the string 
that will replace the current title. 

The _ dwSetAppTitle function is one of the support functions that can be called from an application 
using Open Watcom’s default windowing support. 

Returns: The _ dwSetAppTitle function returns 1 if it was successful and 0 if not. 

See Also: _ dwDeleteOnClose,_ dwSetAboutDlg,_ dwSetConTitle,_ dwShutDown,_ dwYield 

Example: #include <wdefwin.h> 

♦include <stdio.h> 

void main() 

{ 

FILE *sec; 

_ dwSetAboutDlg( "Hello World About Dialog", 

"About Hello World\n" 

"Copyright 1994 by WATCOM\n" ); 

_ dwSetAppTitle( "Hello World Application Title" ); 

_ dwSetConTitle( 0, "Hello World Console Title" ); 
printf( "Hello WorldXn" ); 
sec = fopen( "CON", "r+" ); 

_ dwSetConTitle( fileno( sec ), 

"Hello World Second Console Title" ); 

_ dwDeleteOnClose( fileno( sec ) ); 

fprintf( sec, "Hello to second console\n" ); 

fprintf( sec, "Press Enter to close this console\n" ) ; 

fflush( sec ); 

fgetc( sec ) ; 

fclose ( sec ); 

} 

Classification: WATCOM 

Systems: Windows, Win386, Win32, OS/2-32 


216 Library Functions and Macros 




dwSetConTitle 


Synopsis: #include <wdefwin.h> 

int _ dwSetConTitle( int handle, const char *title ); 

Description: The _ dwSetConTitle function sets the console window’s title which corresponds to the handle 

passed to it. The argument handle is the handle associated with the opened console. The argument title 
points to the string that will replace the current title. 

The _ dwSetConTitle function is one of the support functions that can be called from an application 
using Open Watcom’s default windowing support. 

Returns: The _ dwSetConTitle function returns 1 if it was successful and 0 if not. 

See Also: _ dwDeleteOnClose,_ dwSetAboutDlg,_ dwSetAppTitle,_ dwShutDown^ dwYield 

Example: #include <wdefwin.h> 

#include <stdio.h> 

void main() 

{ 

FILE *sec; 

_ dwSetAboutDlg( "Hello World About Dialog", 

"About Hello WorldXn" 

"Copyright 1994 by WATCOM\n" ); 

_ dwSetAppTitle( "Hello World Application Title" ); 

_ dwSetConTitle( 0, "Hello World Console Title" ); 
printf( "Hello World\n" ) ; 
sec = fopen( "CON", "r+" ); 

_ dwSetConTitle( fileno( sec ), 

"Hello World Second Console Title" ); 

_ dwDeleteOnClose ( fileno( sec ) ); 

fprintf( sec, "Hello to second console\n" ); 

fprintf( sec, "Press Enter to close this console\n" ); 

fflush( sec ); 

fgetc( sec ) ; 

fclose ( sec ); 

} 

Classification: WATCOM 

Systems: Windows, Win386, Win32, OS/2-32 
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dwShutDown 


Synopsis: #include <wdefwin.h> 

int _ dwShutDown ( void ) ; 

Description: The _ dwShutDown function shuts down the default windowing I/O system. The application will 

continue to execute but no windows will be available for output. Care should be exercised when using 
this function since any subsequent output may cause unpredictable results. 

When the application terminates, it will not be necessary to manually close the main window. 

The _ dwShutDown function is one of the support functions that can be called from an application 
using Open Watcom’s default windowing support. 

Returns: The _ dwShutDown function returns 1 if it was successful and 0 if not. 

See Also: _ dwDeleteOnClose,_ dwSetAboutDlg,_ dwSetAppTitle,_ dwSetConTitle,_ dwYield 

Example: #include <wdefwin.h> 

♦include <stdio.h> 

void main() 

{ 

FILE *sec; 

_ dwSetAboutDlg( "Hello World About Dialog", 

"About Hello World\n" 

"Copyright 1994 by WATCOM\n" ); 

_ dwSetAppTitle( "Hello World Application Title" ); 

_ dwSetConTitle( 0, "Hello World Console Title" ); 
printf( "Hello World\n" ); 

sec = fopen( "CON", "r+" ); 

_ dwSetConTitle( fileno( sec ), 

"Hello World Second Console Title" ); 

_ dwDeleteOnClose ( fileno( sec ) ); 

fprintf( sec, "Hello to second console\n" ); 

fprintf( sec, "Press Enter to close this console\n" ); 

fflush( sec ); 

fgetc( sec ) ; 

fclose ( sec ); 

_ dwShutDown(); 

/* 

do more computing that does not involve 
console input/output 

*/ 

} 

Classification: WATCOM 

Systems: Windows, Win386, Win32, OS/2-32 
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dwYield 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <wdefwin.h> 
int _ dwYield ( void ) ; 

The _ dwYield function yields control back to the operating system, thereby giving other processes a 
chance to run. 

The _ dwYield function is one of the support functions that can be called from an application using 
Open Watcom’s default windowing support. 

The _ dwYield function returns 1 if it was successful and 0 if not. 

_ dwDeleteOnClose,_ dwSetAboutDlg,_ dwSetAppTitle,_ dwSetConTitle, 

_ dwShutDown 

♦include <wdefwin.h> 

♦include <stdio.h> 

void main() 

1 

int i; 

for( i = 0; i < 1000; i++ ) { 

/* give other processes a chance to run */ 

_ dwYield(); 

/* do CPU-intensive calculation */ 

/* . */ 

/* . */ 

/* . */ 

} 

} 

WATCOM 

Windows, Win386, Win32, OS/2-32 
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ecvt, _ecvt, _wecvt 


Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <stdlib.h> 
char *ecvt( double value, 
int ndigits, 
int *dec, 
int *sign ) ; 

char *_ ecvt( double value, 
int ndigits, 
int *dec, 
int *sign ); 

wchar_ t *_ wecvt( double value, 
int ndigits, 
int *dec, 
int *sign ); 

The ecvt function converts the floating-point number value into a character string. The parameter 
ndigits specifies the number of significant digits desired. The converted number will be rounded to 
ndigits of precision. 

The character string will contain only digits and is terminated by a null character. The integer pointed 
to by dec will be filled in with a value indicating the position of the decimal point relative to the start of 
the string of digits. A zero or negative value indicates that the decimal point lies to the left of the first 
digit. The integer pointed to by sign will contain 0 if the number is positive, and non-zero if the number 
is negative. 

The _ ecvt function is identical toecvt. Use _ ecvt for ANSI naming conventions. 

The _ wecvt function is a wide-character version ofecvt. It produces a wide-character string. 

The ecvt function returns a pointer to a static buffer containing the converted string of digits. Note: 
ecvt and f cvt both use the same static buffer. 

fcvt, gcvt, printf 

♦include <stdio.h> 

♦include <stdlib.h> 

void main() 

{ 

char *str; 
int dec, sign; 

str = ecvt( 123.456789, 6, &dec, &sign ); 

printf ( "str=%s, dec=%d, sign=%d\n", str,dec,sign ); 

} 

produces the following: 
str=123457, dec=3, sign=0 
WATCOM 

_ecvt conforms to ANSI naming conventions 

ecvt - Math 
_ ecvt - Math 
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ecvt, _ecvt, _wecvt 


wecvt - Math 
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ellipse Functions 


Synopsis: #include <graph.h> 

short _ FAR _ ellipse( short fill, short xl, short yl, 

short x2, short y2 ); 

short _ FAR _ellipse_w( short fill, double xl, double yl, 

double x2, double y2 ) ; 

short _ FAR _ ellipse_ wxy ( short fill, 

struct _ wxycoord _ FAR *pl, 
struct _ wxycoord _ FAR *p2 ); 

Description: The _ ellipse functions draw ellipses. The_ ellipse function uses the view coordinate system. 
The _ ellipse_ w and_ ellipse_ wxy functions use the window coordinate system. 

The center of the ellipse is the center of the rectangle established by the points (xl, yl) and 
(x2,y2). 

The argument/;// determines whether the ellipse is filled in or has only its outline drawn. The argument 
can have one of two values: 

JGFILLINTERIOR fill the interior by writing pixels with the current plot action using the current 

color and the current fill mask 

JGBORDER leave the interior unchanged; draw the outline of the figure with the current 

plot action using the current color and line style 

When the coordinates (xl,yl) and (x2,y2) establish a line or a point (this happens when one or 
more of the x-coordinates or y-coordinates are equal), nothing is drawn. 

Returns: The _ ellipse functions return a non-zero value when the ellipse was successfully drawn; otherwise, 

zero is returned. 

See Also: _ arc,_ rectangle^ setcolor^ setf illmask,_ setlinestyle,_ setplotaction 

Example: (/include <conio.h> 

♦include <graph.h> 

main () 

{ 

_ setvideomode ( _VRES16C0L0R ); 

_ellipse( _ GBORDER, 120, 90, 520, 390 ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ); 

} 

produces the following: 
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ellipse Functions 



Classification: PC Graphics 

Systems: _ ellipse - DOS 

_ ellipse_ w - DOS 
_ ellipse_ wxy - DOS 
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enable 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <i86.h> 
void _ enable ( void ) ; 

The _ enable function causes interrupts to become enabled. 

The _ enable function would be used in conjunction with the_ disable function to make sure that a 
sequence of instructions are executed without any intervening interrupts occurring. 

The _ enable function returns no value. 

_ disable 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <i86.h> 

struct list_ entry { 

struct list_ entry *next; 
int data; 

In¬ 
struct list_ entry *ListHead = NULL; 
struct list_ entry *ListTail = NULL; 

void insert ( struct list_ entry *new_ entry ) 

{ 

/* insert new_ entry at end of linked list */ 
new_ entry->next = NULL; 

_ disable!); /* disable interrupts */ 

if( ListTail == NULL ) { 

ListHead = new_ entry; 

} else { 

ListTail->next = new_ entry; 

} 

ListTail = new_ entry; 

_ enable!); /* enable interrupts now */ 

} 

void main() 

{ 

struct list_entry *p; 
int i; 

for( i = 1; i <= 10; i++ ) { 

p = (struct list_ entry *) 

malloc ( sizeof( struct list_ entry ) ); 

if( p == NULL ) break; 
p->data = i; 
insert( p ); 

} 

} 

Intel 

All, Linux, RDOS, Netware 
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endhostent 


Synopsis: 

Description: 

See Also: 

Classification: 

Systems: 


#include <netdb.h> 
void endhostent( void ) ; 

The endhostent function closes the network host database at /etc/hosts, 
is not open, this call results in no actions. 

gethostent, sethostent 

POSIX 

Linux 


If the network host database 
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endnetent 


Synopsis: 

Description: 

See Also: 

Classification: 

Systems: 


#include <netdb.h> 
void endnetent( void ) ; 

The endnetent function closes the network database. 

This function is not thread-safe. Other calls to this function or to other functions accessing the 
hostname database may affect the return value from this function. 

getnetent, setnetent, getnetbyname, getnetbyaddr 

POSIX 

Linux 
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endprotoent 


Synopsis: 

Description: 

See Also: 

Classification: 

Systems: 


#include <netdb.h> 
void endprotoent( void ) ; 

The endprotoent function explicitly closes the protocol database. 

This function is not thread-safe. Other calls to this function or to other functions accessing the protocol 
database may affect the return value from this function. 

getprotoent, setprotoent, getprotobyname, getprotobynumber 

POSIX 

Linux 
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endpwent 


Synopsis: 

Description: 
See Also: 
Example: 


Classification: 

Systems: 


#include <pwd.h> 
void endpwent( void ) ; 

The endpwent function closes the system’s password database after calls to getpwent are complete, 
setpwent, getpwent, getpwnam, getpwuid 

The following program will print out each user and their user ID in the system’s password database 

♦include <stdio.h> 

♦include <pwd.h> 

void main() 

{ 

struct passwd *pw; 
setpwent(); 

while((pw = getpwent()) != NULL) { 

printf("User id %d is %s\n", (int) pw->pw_ uid, pw->pw_ name) ; 

} 

endpwent(); 

} 

POSIX 

Linux 
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endservent 


Synopsis: 

Description: 

See Also: 

Classification: 

Systems: 


#include <netdb.h> 
void endservent( void ) ; 

The endservent function closes the service database. 

This function is not thread-safe. Other calls to this function or to other functions accessing the 
hostname database may affect the return value from this function. 

getservent, setservent, getservbyname, getservbyport 

POSIX 

Linux 
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endthread, _endthreadex 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


#include <process.h> 

void _ endthread (void) ; 

void _ endthreadex( unsigned retval ); 

The _ endthread function is used to terminate a thread created by_ beginthread. For each 
operating environment under which _ endthread is supported, the_ endthread function uses the 
appropriate system call to end the current thread of execution. 

The _ endthreadex function is used to terminate a thread created by_ beginthreadex. The 
thread exit code retx’al must be specified. 

The _ endthread function does not return any value. 

_ beginthread 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <stddef.h> 

♦include <malloc.h> 

♦include <process.h> 

♦include <dos.h> 

♦ if defined(_ 386_ ) 

♦define FAR 
♦define STACK_ SIZE 

♦ else 

♦define FAR 
♦define STACK_ SIZE 
♦endif 

static volatile int WaitForThread; 

void FAR child( void FAR *parm ) 

{ 

char * FAR *argv = (char * FAR *) parm; 
int i; 

printf ( "Child thread ID = %x\n", *_ threadid ); 
for( i = 0; argv[i]; i++ ) { 

printf( "argv[%d] = %s\n", i, argv[i] ); 

} 

WaitForThread = 0; 

_endthread(); 

} 


8192 

_far 

4096 
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Classification: 

Systems: 


endthread, _endthreadex 


void main() 

{ 

char 

#if defined (_NT 

unsigned long 
#else 

char 

int 

#endif 


*args[3]; 
_ ) 
tid; 

*stack; 

tid; 


args[0] = "child"; 
args[l] = "parm"; 
args[2] = NULL; 

WaitForThread = 1; 

#if defined (_NT_) 

tid = _ beginthread ( child, STACK_ SIZE, args ); 
printf( "Thread handle = %lx\n", tid ); 

#else 

#if defined(_ 386_ ) 

stack = (char *) malloc ( STACK_ SIZE ); 

#else 

stack = (char *) _ nmalloc ( STACK_ SIZE ); 

#endif 

tid = _ beginthread ( child, stack, STACK_ SIZE, args ); 
printf( "Thread ID = %x\n", tid ); 

#endif 

while( WaitForThread ) { 

sleep ( 0 ); 

} 

} 


WATCOM 

_ endthread - Win32, OS/2 l.x(MT), OS/2 l.x(DL), OS/2-32, Linux, RDOS, 
Netware 

_ endthreadex - Win32 
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eof, _eof 


Synopsis: #include <io.h> 

int eof( int handle ) ; 
int _ eof( int handle ); 

Description: The eof function determines, at the operating system level, if the end of the file has been reached for 
the file whose file handle is given by handle. Because the current file position is set following an input 
operation, the eof function may be called to detect the end of the file before an input operation beyond 
the end of the file is attempted. 

The _ eof function is identical toeof. Use _ eof for ANSI naming conventions. 

Returns: The eof function returns 1 if the current file position is at the end of the file, 0 if the current file 

position is not at the end. A return value of -1 indicates an error, and in this case errno is set to 
indicate the error. 

Errors: When an error has occurred, errno contains a value indicating the type of error that has been detected. 

EBADF The handle argument is not a valid file handle. 

See Also: read 

Example: #include <stdio.h> 

♦include <fcntl.h> 

♦include <io.h> 

void main( void ) 

{ 

int handle, len; 
char buffer [100]; 

handle = open ( "file", 0_ RDONLY ) ; 
if( handle != -1 ) { 

while ( ! eof ( handle ) ) { 

len = read( handle, buffer, sizeof(buffer) - 1 ); 
bufferf len ] = '\0'; 
printf( "%s", buffer ); 

} 

close ( handle ); 

} 

} 

Classification: WATCOM 

_eof conforms to ANSI naming conventions 

Systems: eof - All, Linux, RDOS, Netware 

_ eof - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 


232 Library Functions and Macros 




Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


erf 


#include <math.h> 
double erf( double x ); 

The erf function computes the value of the error function, also known as the Gauss error function, for 
the argument x. 

For non-infinite values of x the function returns the value of the error function. For positive infinity or 
negative infinity the function returns positive or negative one respectively. For not-a-number the 
function returns NAN. 

erf c 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", erf ( 0.0 ) ); 

} 

produces the following: 

0.000000 
ISO C99 
Math 
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erfc 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double erfc ( double x ); 

The erfc function computes the value of the complementary error function, also known as the Gauss 
error function, for the argument x. 

For non-infinite values of x the function returns the value of the error function. For positive infinity or 
negative infinity the function returns negative or positive one respectively. For not-a-number the 
function returns NAN. 

erf 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", erfc ( 0.0 ) ); 

} 

produces the following: 

0.000000 

WATCOM 

Math 
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exec... Functions 


Synopsis: #include <process.h> 


int 

execl( 

path, argO, argl.. 

., argn, NULL ) 

r 

int 

execle( 

path, argO, argl.. 

., argn, NULL, 

envp ) ; 

int 

execlp( 

file, argO, argl.. 

., argn, NULL ) 

r 

int 

execlpe( 

file, argO, argl.. 

., argn, NULL, 

envp ) ; 

int 

execv( 

path, argv ); 



int 

execve( 

path, argv, envp ) 

r 


int 

execvp( 

file, argv ); 



int 

execvpe( 

file, argv, envp ) 

r 


int 

_ execl( 

path, argO, argl 

. .., argn, NULL 

) ; 

int 

_ execle( 

path, argO, argl 

. .., argn, NULL 

, envp ); 

int 

_ execlp( 

file, argO, argl 

. . ., argn, NULL 

) ; 

int 

_ execlpe( file, argO, argl 

. . . , argn, NULL 

, envp ); 

int 

_execv( 

path, argv ) ; 



int 

_ execve( 

path, argv, envp 

) ; 


int 

_ execvp( 

file, argv ); 



int 

_ execvpe( file, argv, envp 

); 



const 

char 

*path; 


/* 

file name incl. path 

*/ 

const 

char 

*file; 


/* 

file name 

*/ 

const 

char 

*argO, 

..., *argn; 

/* 

arguments 

*/ 

const 

char 

*const 

argv[]; 

/* 

array of arguments 

*/ 

const 

char 

*const 

envp[]; 

/* 

environment strings 

*/ 


int 

_ wexecl( 

path, 

argO, argl. 

.., argn. 

NULL ); 

int 

_ wexecle( 

path. 

argO, argl. 

.., argn. 

NULL, envp ) ; 

int 

_ wexeclp( 

file, 

argO, argl. 

.., argn. 

NULL ); 

int 

_ wexeclpe( 

file, 

argO, argl. 

.., argn. 

NULL, envp ); 

int 

_ wexecv( 

path, 

argv ); 



int 

_ wexecve( 

path. 

argv, envp 

); 


int 

_ wexecvp( 

file, 

argv ); 



int 

_ wexecvpe( 

file, 

argv, envp 

); 



const 

wchar_ 

t 

*path; 

/* 

file name incl. path 

*/ 

const 

wchar_ 

t 

*file; 

/* 

file name 

*/ 

const 

wchar_ 

t 

*argO, 

. . ., *argn;/* 

arguments 

*/ 

const 

wchar_ 

t 

*const 

argv[]; /* 

array of arguments 

*/ 

const 

wchar_ 

t 

*const 

envp[]; /* 

environment strings 

*/ 


Description: The exec... functions load and execute a new child process, named by path or file. If the child process 
is successfully loaded, it replaces the current process in memory. No return is made to the original 
program. 

The program is located by using the following logic in sequence: 

1. An attempt is made to locate the program in the current working directory if no directory 
specification precedes the program name; otherwise, an attempt is made in the specified 
directory. 

2. If no file extension is given, an attempt is made to find the program name, in the directory 
indicated in the first point, with . COM concatenated to the end of the program name. 

3. If no file extension is given, an attempt is made to find the program name, in the directory 
indicated in the first point, with . EXE concatenated to the end of the program name. 

4. When no directory specification is given as part of the program name, the execlp, 
execlpe, execvp, and execvpe functions will repeat the preceding three steps for each 
of the directories specified by the PATH environment variable. The command 
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exec... Functions 


Returns: 


Errors: 


path c:\myapps;d:\lib\applns 

indicates that the two directories 

c:\myapps 
d:\lib\applns 

are to be searched. The DOS PATH command (without any directory specification) will 
cause the current path definition to be displayed. 

An error is detected when the program cannot be found. 

Arguments are passed to the child process by supplying one or more pointers to character strings as 
arguments in the exec... call. These character strings are concatenated with spaces inserted to separate 
the arguments to form one argument string for the child process. The length of this concatenated string 
must not exceed 128 bytes for DOS systems. 

The arguments may be passed as a list of arguments (execl, execle, execlp, and execlpe) or as 
a vector of pointers (execv, execve, execvp, and execvpe). At least one argument, argO or 
argv[0], must be passed to the child process. By convention, this first argument is a pointer to the name 
of the program. 

If the arguments are passed as a list, there must be a NULL pointer to mark the end of the argument list. 
Similarly, if a pointer to an argument vector is passed, the argument vector must be terminated by a 
NULL pointer. 

The environment for the invoked program is inherited from the parent process when you use the 
execl, execlp, execv, and execvp functions. The execle, execlpe, execve, and execvpe 
functions allow a different environment to be passed to the child process through the envp argument. 

The argument envp is a pointer to an array of character pointers, each of which points to a string 
defining an environment variable. The array is terminated with a NULL pointer. Each pointer locates a 
character string of the form 

variable=value 

that is used to define an environment variable. If the value of envp is NULL, then the child process 
inherits the environment of the parent process. 

The environment is the collection of environment variables whose values have been defined with the 
DOS SET command or by the successful execution of the putenv function. A program may read 
these values with the getenv function. 

The execvpe and execlpe functions are extensions to POSIX 1003.1. 

The _ wexec . . . functions are similar to their counterparts but operate on wide-character strings. 

When the invoked program is successfully initiated, no return occurs. When an error is detected while 
invoking the indicated program, exec... returns -1 and errno is set to indicate the error. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
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exec... Functions 


See Also: 
Example: 


Constant Meaning 

E2BIG The argument list exceeds 128 bytes, or the space required for the environment 

information exceeds 32K. 

EACCES The specified file has a locking or sharing violation. 

EMFILE Too many files open 

ENOENT Path or file not found 

ENOMEM Not enough memory is available to execute the child process. 


abort, atexit, exit, _ Exit,_ exit,getcmd, getenv, main, putenv, spawn. . ., system 


♦include <stddef.h> 

♦include <process.h> 

execl( "myprog", 

"myprog", "ARG1", "ARG2", NULL ); 

The preceding invokes "myprog" as if 
myprog ARG1 ARG2 

had been entered as a command to DOS. The program will be found if one of 

myprog. 
myprog.com 
myprog.exe 

is found in the current working directory. 

♦include <stddef.h> 

♦include <process.h> 

char *env_ list[] = { "SOURCE=MYDATA" , 

"TARGET=OUTPUT", 

"lines=65", 

NULL 

} ; 


execle ( "myprog", 

"myprog", "ARG1", "ARG2", NULL, 
env_ list ) ; 

The preceding invokes "myprog" as if 
myprog ARG1 ARG2 

had been entered as a command to DOS. The program will be found if one of 

myprog. 
myprog.com 
myprog.exe 
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exec... Functions 


is found in the current working directory. The DOS environment for the invoked program will consist 
of the three environment variables SOURCE, TARGET and lines . 

♦include <stddef.h> 

♦include <process.h> 

char *arg_list[] = { "myprog", "ARG1", "ARG2", NULL }; 

execv( "myprog", arg_ list ); 

The preceding invokes "myprog" as if 
myprog ARG1 ARG2 

had been entered as a command to DOS. The program will be found if one of 

myprog. 
myprog.com 
myprog.exe 

is found in the current working directory. 

Classification: POSIX 1003.1 with extensions 

_exec... conforms to ANSI naming conventions 
_wexec... is WATCOM 

Systems: execl - DOS/16, Win32, OS/2 1.x (all), OS/2-32, Linux, RDOS 

execle - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS 

execlp - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS 

execlpe - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS 
execv - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS 
execve - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS 

execvp - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS 

execvpe - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS 
_ execl - DOS/16, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS 
_execle - DOS/16, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS 

_execlp - DOS/16, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS 

_execlpe - DOS/16, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS 
_execv - DOS/16, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS 
_ execve - DOS/16, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS 

_execvp - DOS/16, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS 

_execvpe - DOS/16, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS 
_ wexecl - DOS/16, Win32, OS/2 l.x(all), OS/2-32 

_ wexecle - DOS/16, Win32, OS/2 l.x(all), OS/2-32 

_ wexeclp - DOS/16, Win32, OS/2 l.x(all), OS/2-32 

_ wexeclpe - DOS/16, Win32, OS/2 l.x(all), OS/2-32 
_ wexecv - DOS/16, Win32, OS/2 l.x(all), OS/2-32 

_ wexecve - DOS/16, Win32, OS/2 l.x(all), OS/2-32 

_ wexecvp - DOS/16, Win32, OS/2 l.x(all), OS/2-32 

_ wexecvpe - DOS/16, Win32, OS/2 l.x(all), OS/2-32 
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Synopsis: 

Description: 


Returns: 
See Also: 

Example: 


Classification: 

Systems: 


Exit, _exit 


#include <stdlib.h> 
void _ Exit ( int status ) ; 
void _ exit ( int status ) ; 

The _ Exit function causes normal program termination to occur. 

1. The functions registered by the atexit or onexit functions are not called. 

2. Any unopened files are not closed and any buffered output is not flushed to the associated 
files or devices. 

3. Any files created by tmpf ile are not removed. 

4. The return status is made available to the parent process. Only the low order byte of status is 
available on DOS systems. The status value is typically set to 0 to indicate successful 
termination and set to some other value to indicate an error. 

The _ exit is functionaly equivalent to_ Exit. 

The _ Exit function does not return to its caller. 

abort, atexit, _ bgetcmd,exec. . ., exit, _ exit,getcmd, getenv, main, onexit, 
putenv, spawn. . ., system 

♦include <stdio.h> 

♦include <stdlib.h> 

void main( int argc, char *argv[] ) 

{ 

FILE *fp; 

if( argc <= 1 ) { 

fprintf( stderr, "Missing argument\n" ) ; 
exit( EXIT_ FAILURE ); 

} 

fp = fopen ( argv[l], "r" ); 
if( fp == NULL ) { 

fprintf ( stderr, "Unable to open '%s'\n", argv[l] ); 

_ Exit ( EXIT_ FAILURE ) ; 

} 

fclose ( fp ); 

_ Exit( EXIT_ SUCCESS ); 

} 

ISO C99 

_exit is POSIX 1003.1 

_ Exit - All, Linux, RDOS, Netware 
_ exit - All, Linux, RDOS, Netware 
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exit 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <stdlib.h> 
void exit( int status ) ; 

The exit function causes normal program termination to occur. 

First, all functions registered by the atexit function are called in the reverse order of their 
registration. Next, all open files are flushed and closed, and all files created by the tmpf ile function 
are removed. Finally, the return status is made available to the parent process. Only the low order byte 
of status is available on DOS systems. The status value is typically set to 0 to indicate successful 
termination and set to some other value to indicate an error. 

The exit function does not return to its caller. 

abort, atexit, _ Exit,_ exit,onexit 

♦include <stdio.h> 

♦include <stdlib.h> 

void main( int argc, char *argv[] ) 

{ 

FILE *fp; 

if ( argc <= 1 ) { 

fprintf( stderr, "Missing argument\n" ) ; 
exit( EXIT_ FAILURE ); 

} 

fp = fopen ( argv[l], "r" ); 
if( fp == NULL ) { 

fprintf( stderr, "Unable to open '%s'\n", argv[1] ); 

exit( EXIT_ FAILURE ); 

} 

fclose ( fp ); 

exit( EXIT_ SUCCESS ); 

} 

ISOC 

All, Linux, RDOS, Netware 
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exp 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double exp( double x ); 

The exp function computes the exponential function of x. A range error occurs if the magnitude of x is 
too large. 

The exp function returns the exponential value. When the argument is outside the permissible range, 
the matherr function is called. Unless the default matherr function is replaced, it will set the 
global variable errno to ERANGE, and print a "RANGE error" diagnostic message using the stderr 
stream. 

log, matherr 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", exp (.5) ); 

} 

produces the following: 

1.648721 

ISOC 

Math 
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exp2 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <math.h> 
double exp2( double x ); 

The exp2 function computes 2.0 raised to the value x. The current implementation uses a simple 
power calculation. 

The function returns two to the power x. 
exp, pow 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", exp2 ( 2.0 ) ); 

} 

produces the following: 

4.000000 
ISO C99 
Math 
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expml 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double expml( double x ) ; 

The expml function computes the value of the exponential of x minus 1. This routine provides far 
better accuracy for cases where the exponential of the argument x is significantly less than 1.0. 

The function returns a the exponential of ,arg x minus 1 without loss of accuracy due to subtractive 
cancelation. 

exp 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", expml( -1.0E-3 ) ); 

} 

produces the following: 

-0.000995 
ISO C99 
Math 
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expand Functions 


Synopsis: #include <malloc.h> 

void *_ expand( void *mem_ blk, size_ t size ); 

void_based (void) *_ bexpand (_segment seg, 

void_based (void) *mem_ blk, 

size_ t size ) ; 

void_far *_ fexpand(void_far *mem_ blk, size_ t size); 

void_near *_ nexpand (void_near *mem_ blk, size_ t size); 

Description: The _ expand functions change the size of the previously allocated block pointed to by memjblk by 
attempting to expand or contract the memory block without moving its location in the heap. The 
argument size specifies the new desired size for the memory block. The contents of the memory block 
are unchanged up to the shorter of the new and old sizes. 

Each function expands the memory from a particular heap, as listed below: 

Function Heap Expanded 

_expand Depends on data model of the program 

_bexpand Based heap specified by seg value 

_fexpand Far heap (outside the default data segment) 

jiexpand Near heap (inside the default data segment) 

In a small data memory model, the _ expand function is equivalent to the_ nexpand function; in a 
large data memory model, the _ expand function is equivalent to the_ fexpand function. 

Returns: The _ expand functions return the value memjblk if it was successful in changing the size of the block. 

The return value is NULL (_ NULLOFF for_ bexpand) if the memory block could not be expanded to 
the desired size. It will be expanded as much as possible in this case. 

The appropriate _ msize function can be used to determine the new size of the expanded block. 

See Also: calloc Functions, free Functions, halloc, hfree, malloc Functions, _ msize Functions, 

realloc Functions, sbrk 

Example: ((include <stdio.h> 

((include <malloc.h> 

void main() 

{ 

char *buf; 

char _far *buf2; 
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expand Functions 


Classification: 

Systems: 


} 


buf = (char *) malloc( 80 ); 

printf ( "Size of buffer is %u\n", _msize(buf) ); 
if ( _ expand( buf, 100 ) == NULL ) { 

printf ( "Unable to expand bufferin'' ) ; 

} 

printf ( "New size of buffer is %u\n", _msize(buf) ) 

buf2 = (char_far *) _ fmalloc ( 2000 ); 

printf ( "Size of far buffer is %u\n", _ fmsize(buf2) 
if ( _ fexpand( buf2, 8000 ) == NULL ) { 

printf ( "Unable to expand far bufferin'' ) ; 

} 

printf ( "New size of far buffer is %uin", 

_ fmsize(buf2) ); 


produces the following: 

Size of buffer is 80 
Unable to expand buffer 
New size of buffer is 80 
Size of far buffer is 2000 
New size of far buffer is 8000 


WATCOM 


_ expand - All, Linux, RDOS 
_ bexpand - DOS/16, Windows, OS/2 l.x(all) 

_ fexpand - DOS/16, Windows, OS/2 l.x(all) 

_ nexpand - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 l.x(MT), 
OS/2-32, Linux, RDOS 
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fabs 


Synopsis: #include <math.h> 

double fabs( double x ); 

Description: The fabs function computes the absolute value of the argument x. 

Returns: The fabs function returns the absolute value of x. 

See Also: abs, labs, imaxabs 

Example: #include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f %f\n", fabs(.5), fabs (-.5) ); 

} 

produces the following: 

0.500000 0.500000 

Classification: ISO C 
Systems: Math 


246 Library Functions and Macros 




fclose 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdio.h> 
int fclose( FILE *fp ); 

The fclose function closes the file//?. If there was any unwritten buffered data for the file, it is 
written out before the file is closed. Any unread buffered data is discarded. If the associated buffer was 
automatically allocated, it is deallocated. 

The fclose function returns zero if the file was successfully closed, or non-zero if any errors were 
detected. When an error has occurred, errno contains a value indicating the type of error that has 
been detected. 

fcloseall, fdopen, fopen, f reopen, _ fsopen 

♦include <stdio.h> 

void main() 

{ 

FILE *fp; 

fp = fopen( "stdio.h", "r" ); 
if( fp != NULL ) { 

fclose ( fp ); 

} 

} 

ISOC 

All, Linux, RDOS, Netware 
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fcloseall 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdio.h> 
int fcloseall ( void ); 

The fcloseall function closes all open stream files, except stdin, stdout, stderr, stdaux, 
and stdprn. This includes streams created (and not yet closed) by fdopen, fopen and f reopen. 
The stdaux and stdprn files are not available for some Windows platforms. 

The fcloseall function returns the number of streams that were closed if no errors were 
encountered. When an error occurs, EOF is returned. 

fclose, fdopen, fopen, freopen, _ fsopen 

♦include <stdio.h> 

void main() 

{ 

printf ( "The number of files closed is %d\n". 


WATCOM 

All, Linux, RDOS, Netware 
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Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


fcvt, _fcvt, _wfcvt 


#include <stdlib.h> 
char *fcvt( double value, 
int ndigits, 
int *dec, 
int *sign ) ; 

char *_ fcvt( double value, 
int ndigits, 
int *dec, 
int *sign ); 

wchar_ t *_ wfcvt( double value, 
int ndigits, 
int *dec, 
int *sign ) ; 

The fcvt function converts the floating-point number value into a character string. The parameter 
ndigits specifies the number of digits desired after the decimal point. The converted number will be 
rounded to this position. 

The character string will contain only digits and is terminated by a null character. The integer pointed 
to by dec will be filled in with a value indicating the position of the decimal point relative to the start of 
the string of digits. A zero or negative value indicates that the decimal point lies to the left of the first 
digit. The integer pointed to by sign will contain 0 if the number is positive, and non-zero if the number 
is negative. 

The _ fcvt function is identical tofcvt. Use _ fcvt for ANSI naming conventions. 

The _ wfcvt function is a wide-character version off cvt. It produces a wide-character string. 

The f cvt function returns a pointer to a static buffer containing the converted string of digits. Note: 
ecvt and fcvt both use the same static buffer. 

ecvt, gcvt, printf 

♦include <stdio.h> 

♦include <stdlib.h> 

void main() 

{ 

char *str; 
int dec, sign; 

str = fcvt( -123.456789, 5, &dec, &sign ); 

printf ( "str=%s, dec=%d, sign=%d\n", str,dec,sign ); 

} 

produces the following: 
str=12345679, dec=3, sign=-l 
WATCOM 

_fcvt conforms to ANSI naming conventions 

fcvt - Math 
_ fcvt - Math 
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fcvt, _fcvt, _wfcvt 


wfcvt - Math 
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fdim 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 

double fdim( double x, double y ); 

The fdim function computes the positive difference of x and y. The function is equivalent to: 
fmax( x - y, 0.0 ); 

The routine will either return x-y or 0.0, whichever is greater, 
fmax, fmin 

♦include <stdio.h> 

♦include <math.h> 

void main() 

1 

printf ( "%f\n", fdim( 3.0, 2.0 ) ); 

} 

produces the following: 

1.000000 
ISO C99 
Math 
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fdopen, Jdopen, _wfdopen 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


Systems: 


♦include <stdio.h> 

FILE *fdopen( int handle, const char *mode ); 

FILE *_ fdopen( int handle, const char *mode ); 

FILE *_ wfdopen ( int handle, const wchar_ t *mode ); 

The fdopen function associates a stream with the file handle handle which represents an opened file or 
device. The handle was returned by one of creat, dup, dup2, open, or sopen. The open mode 
mode must match the mode with which the file or device was originally opened. 

The argument mode is described in the description of the f open function. 

The _ fdopen function is identical tofdopen. Use _ fdopen for ANSI naming conventions. 

The _ wfdopen function is identical tof dopen except that it accepts a wide character string for the 
second argument. 

The fdopen function returns a pointer to the object controlling the stream. This pointer must be 
passed as a parameter to subsequent functions for performing operations on the file. If the open 
operation fails, fdopen returns a NULL pointer. When an error has occurred, errno contains a value 
indicating the type of error that has been detected. 

creat, _ dos_ opendup, dup2, fopen, freopen, _ f sopen,_ grow_ handles^ hdopen, 
open, _ open_ osfhandlej. popen,sopen 

♦include <stdio.h> 

♦include <fcntl.h> 

♦include <io.h> 

void main() 

{ 

int handle; 

FILE *fp; 

handle = open ( "file", 0_ RDONLY | 0_ TEXT ); 
if( handle != -1 ) { 

fp = fdopen( handle, "r" ); 
if( fp != NULL ) { 

/* 

process the stream 

*/ 

fclose ( fp ); 

} else { 

close ( handle ); 

} 

} 

} 

POSIX 1003.1 

_fdopen conforms to ANSI naming conventions 
_wfdopen is WATCOM 

fdopen - All, Linux, RDOS, Netware 
_ fdopen - All, Linux, RDOS, Netware 
_ wfdopen - All, Linux 
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feclearexcept 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 

Classification: 

Systems: 


♦include <fenv.h> 

int feclearexcept( int excepts ); 

The feclearexcept function attempts to clear the floating-point exceptions specified by the excepts 
argument. 

For valid exception values see fegetexceptf lag. 

The feclearexcept function returns zero if the excepts argument is zero or if all the specified 
exceptions were successfully cleared. Otherwise, it returns a nonzero value. 

fegetexceptflag, feraiseexcept, fesetexceptflag, fetestexcept 

♦include <fenv.h> 

void main( void ) 

{ 

feclearexcept ( FE_ OVERFLOW | FE_ UNDERFLOW ); 

} 

ISO C99 

All, Linux, RDOS, Netware 
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fedisableexcept, _fedisableexcept 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 

Classification: 

Systems: 


#include <fenv.h> 

void fedisableexcept( int excepts ); 
void_fedisableexcept( int excepts ) ; 

The fedisableexcept function disables the floating point exceptions specified by the excepts 
argument. 

For valid exception values see fegetexceptf lag. 

No value is returned. 

feenableexcept 

♦include <fenv.h> 

void main( void ) 

{ 

fedisableexcept( FE_ DIVBYZERO ); 

} 

WATCOM 

fedisableexcept - All, Linux, RDOS, Netware 
_ fedisableexcept - All, Linux, RDOS, Netware 
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feenableexcept, _feenableexcept 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 

Classification: 

Systems: 


#include <fenv.h> 

void feenableexcept( int excepts ); 
void_feenableexcept( int excepts ) ; 

The feenableexcept function enables the floating point exceptions specified by the excepts 
argument. 

For valid exception values see fegetexceptf lag. 

No value is returned. 

fedisableexcept 

♦include <fenv.h> 

void main( void ) 

{ 

feenableexcept ( FE_ DIVBYZERO ); 

} 

WATCOM 

feenableexcept - All, Linux, RDOS, Netware 
_ feenableexcept - All, Linux, RDOS, Netware 
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fegetenv 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <fenv.h> 

int fegetenv( fenv_ t *envp ); 

The fegetenv function attempts to store the current floating-point environment in the object pointed 
to by envp argument. 

The fegetenv function returns zero if the environment was successfully stored. Otherwise, it returns 
a nonzero value. 

feholdexcept, fesetenv, feupdateenv 

♦include <stdio.h> 

♦include <fenv.h> 

void main( void ) 

{ 

fenv_ t env; 
fegetenv( &env ); 

} 

ISO C99 

All, Linux, RDOS, Netware 
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fegetexceptflag 


Synopsis: #include <fenv.h> 

int fegetexceptflag( fexcept_ t *flagp, int excepts ); 

Description: The fegetexceptflag function attempts to store a representation of the floating-point exceptions 
specified by the excepts argument into the fexcept_t object pointed by th cflcigp argument. 

Valid exception bit values are 

FE_INVALID At least one of the arguments is a value for which the function is not defined. 

FE_DENORMAL The result is not normalized. 

FE_DIVBYZERO Division by zero. 

FE_OVERFLOW The result is too large in magnitude to be represented as the return type. 

FE_UNDERFLOW The result is too small in magnitude to be represented as the return type. 

FE_INEXACT The result is not exact. 

FE_ALL_EXCEPT Is the logical OR of all exceptions. 

Returns: The fegetexceptflag function returns zero if the representation was successfully stored. 

Otherwise, it returns a nonzero value. 

See Also: feclearexcept, feraiseexcept, fesetexceptf lag, fetestexcept 

Example: #include <fenv.h> 

void main( void ) 

{ 

fexcept_ t flags; 

fegetexceptflag! Sflags, FE_ DIVBYZERO ); 

} 

Classification: ISO C99 

Systems: All, Linux, RDOS, Netware 


Library Functions and Macros 257 




fegetround 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <fenv.h> 
int fegetround( void ); 

The fegetround function returns a value that indicates the rounding direction mode, as specified in 
the current floating point environment. 

The fegetround function returns the value of the rounding direction macro representing the current 
rounding direction or a negative value if there is no such rounding direction macro or the current 
rounding direction is not determinable. 

For valid rounding modes see feset round. 

fesetround 

♦include <stdio.h> 

♦include <fenv.h> 

void main( void ) 

{ 

int mode; 

mode = fegetround(); 

if ( mode == FE_ TONEAREST ) 

printf( "Nearest\n" ); 
else if ( mode == FE_ DOWNWARD ) 
printf ( "Down\n" ); 
else if ( mode == FE_ TOWARDZERO ) 
printf ( "To Zero\n" ); 
else if ( mode == FE_ UPWARD ) 
printf ( "Up\n" ); 

} 

ISO C99 

All, Linux, RDOS, Netware 
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feholdexcept 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <fenv.h> 

int feholdexcept ( fenv_ t *envp ); 

The feholdexcept function saves the current floating-point environment in the object pointed to by 
envp argument, clears the floating-point status flags, and then installs a non-stop (continue on 
floating-point exceptions) mode, if available, for all floating-point exceptions. 

The feholdexcept function returns zero if and only if non-stop floating-point exception handling 
was successfully installed. 

fegetenv, fesetenv, feupdateenv 

♦include <fenv.h> 

void main( void ) 

{ 

fenv_ t env; 
feholdexcept( &env ) ; 

} 

ISO C99 

All, Linux, RDOS, Netware 
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feof 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdio.h> 
int feof( FILE *fp ) ; 

The feof function tests the end-of-file indicator for the stream pointed to by fp. Because this indicator 
is set when an input operation attempts to read past the end of the file the feof function will detect the 
end of the file only after an attempt is made to read beyond the end of the file. Thus, if a file contains 
10 lines, the feof will not detect end of file after the tenth line is read; it will detect end of file once the 
program attempts to read more data. 

The feof function returns non-zero if the end-of-file indicator is set for fp. 

clearerr, ferror, fopen, freopen, perror, read, strerror 

♦include <stdio.h> 

void process_ record( char *buf ) 

{ 

printf ( "%s\n", buf ); 

} 

void main() 

{ 

FILE *fp; 

char buffer[100]; 

fp = fopen( "file", "r" ); 

fgets( buffer, sizeof( buffer ), fp ); 

while( ! feof( fp ) ) { 

process_ record( buffer ); 

fgets ( buffer, sizeof ( buffer ), fp ); 

} 

fclose ( fp ); 

} 

ISOC 

All, Linux, RDOS, Netware 


260 Library Functions and Macros 




feraiseexcept 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 

Classification: 

Systems: 


♦include <fenv.h> 

int feraiseexcept( int excepts ); 

The feraiseexcept function attempts to raise the floating-point exceptions specified by the excepts 
argument. 

For valid exception values see fegetexceptf lag. 

The feraiseexcept function returns zero if the excepts argument is zero or if all the specified 
exceptions were successfully raised. Otherwise, it returns a nonzero value. 

feclearexcept, fegetexceptflag, fetestexcept 

♦include <fenv.h> 

void main( void ) 

{ 

feraiseexcept ( FE_ DIVBYZERO ); 

} 

ISO C99 

All, Linux, RDOS, Netware 
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terror 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdio.h> 
int ferror( FILE *fp ); 

The ferror function tests the error indicator for the stream pointed to by fp. 

The ferror function returns non-zero if the error indicator is set for fp. 

clearerr, feof, perror, strerror 

♦include <stdio.h> 

void main() 

{ 

FILE *fp; 
int c; 

fp = fopen( "file", "r" ); 
if( fp != NULL ) { 

c = fgetc ( fp ); 
if( ferror( fp ) ) { 

printf ( "Error reading file\n" ); 

} 

} 

fclose ( fp ); 

} 

ISOC 

All, Linux, RDOS, Netware 
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fesetenv 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <fenv.h> 

int fesetenv( const fenv_t *envp ); 

The fesetenv function attempts to establish the floating-point environment to environment 
represented by the object pointed by envp argument. The envp argument shall point to an object set by 
a call to f egetenv or feholdexcept , or equal the FE_ DFL_ ENV macro. Note that fesetenv 
merely installs the state of the floating-point status flags represented through its argument, and does not 
raise these floating-point exceptions. 

The fesetenv function returns zero if the environment was successfully established. Otherwise, it 
returns a nonzero value. 

fegetenv, feholdexcept, feupdateenv 

♦include <fenv.h> 

void main( void ) 

{ 

fenv_ t env; 
fegetenv( &env ); 
fesetenv ( FE_ DFL_ ENV ) ; 
fesetenv( &env ); 

} 

ISO C99 

All, Linux, RDOS, Netware 
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fesetexceptflag 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <fenv.h> 

int fesetexceptflag( const fexcept_ t *flagp, int excepts ); 

The fesetexceptflag function attempts to set the exceptions indicated by excepts argument with 
the states stored in the object pointed by flcigp argument. The value pointed by th eflagp argument shall 
have been set by a previous call to fegetexceptf lag whose second argument represented at least 
those floating-point exceptions represented by the excepts argument. This function does not raise 
floating-point exceptions, but only sets the state of the flags. 

For valid exception values see fegetexceptf lag. 

The fesetexceptflag function returns zero if the excepts argument is zero or if all the specified 
flags were successfully set to the appropriate state. Otherwise, it returns a nonzero value. 

feclearexcept, fegetexceptflag, fetestexcept 

♦include <fenv.h> 

void main( void ) 

{ 

fexcept_t flags; 

fgetexceptflag( Sflags, FE_ DENORMAL|FE_ INVALID ); 
fsetexceptflag( &flags, FE_ INVALID ); 

} 

ISO C99 

All, Linux, RDOS, Netware 
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fesetround 


Synopsis: #include <fenv.h> 

int fesetround( int mode ); 

Description: The fesetround function sets the rounding direction mode, specified by mode , for the current 
floating point environment. 

The rounding direction mode can be one of the following values: 

FE_TONEAREST Round to nearest integer, halfway rounding away from zero 

FE_DOWNWARD Round downward to the next lowest integer 

FE _TOWARDZERO Round to the nearest integer in the direction of zero 

FEJUPWARD Round upward to the next highest integer 

Returns: The fesetround function returns a zero value if and only if the requested rounding direction was 

established. 

See Also: fegetround, nearbyint, rint 

Example: #include <stdio.h> 

♦include <math.h> 

void main() 

1 

fesetround (FE_ DOWNWARD) 
printf ( "%f\n", rint ( 1.5 ) ); 
fesetround (FE_ UPWARD) 
printf ( "%f\n", rint ( 1.5 ) ); 

} 

produces the following: 

1.00000 

2.00000 

Classification: ISO C99 

Systems: All, Linux, RDOS, Netware 
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fetestexcept 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <fenv.h> 

int fetestexcept( int excepts ) ; 

The fetestexcept function tests which of the specified floating-point exceptions flags are currently 
set. The excepts argument specifies the floating-point exceptions to be queried. 

For valid exception values see fegetexceptf lag. 

The fetestexcept function returns the value of the bitwise OR of the floating-point exception 
macros corresponding to the currently set floating-point exceptions included in the excepts argument. 

feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag 

♦include <stdio.h> 

♦include <fenv.h> 

void main( void ) 

{ 

int excepts; 

feclearexcept ( FE_ DIVBYZERO ); 

...code that may cause a divide by zero exception 

excepts = fetestexcept ( FE_ DIVBYZERO ); 
if ( excepts & FE_ DIVBYZERO) 

printf ( "Divide by zero occurred\n" ); 

} 

ISO C99 

All, Linux, RDOS, Netware 
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feupdateenv 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <fenv.h> 

int feupdateenv( const fenv_ t *envp ); 

The feupdateenv function attempts to save the currently raised floating-point exceptions in its 
automatic storage, installs the floating-point environment represented by the object pointed to by envp 
argument, and then raises the saved floating-point exceptions. The argument envp shall point to an 
object set by a call to feholdexcept or fegetenv, or equal a floating-point environment macro. 

The feupdateenv function returns zero if all the actions were successfully carried out. Otherwise, it 
returns a nonzero value. 

fegetenv, feholdexcept, fesetenv 

♦include <fenv.h> 

void main( void ) 

{ 

fenv_ t env; 
fegetenv( Senv ); 
fesetenv( FE_ DFL_ ENV ); 
feupdateenv! Senv ); 

} 

ISO C99 

All, Linux, RDOS, Netware 
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fflush 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <stdio.h> 
int fflush( FILE *fp ); 

If the file //? is open for output or update, the fflush function causes any unwritten data to be written to 
the file. If the file//? is open for input or update, the fflush function undoes the effect of any 
preceding unget c operation on the stream. If the value of//? is NULL, then all files that are open will 
be flushed. 

The fflush function returns EOF if a write error occurs and zero otherwise. When an error has 
occurred, errno contains a value indicating the type of error that has been detected. 

fgetc, fgets, flushall, fopen, getc, gets, setbuf, setvbuf, ungetc 

♦include <stdio.h> 

♦include <conio.h> 

void main() 

{ 

printf ( "Press any key to continue..." ); 
fflush( stdout ); 
getch(); 

} 

ISOC 

All, Linux, RDOS, Netware 
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ffs 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <strings.h> 
int ffs( int i ); 

The ffs finds the first bit set, beginning with the least significant bit, in i. Bits are numbered starting 
at one (the least significant bit). 

The ffs function returns the index of the first bit set. If i is 0, ffs returns zero. 

_ lrotl,_ lrotr,_ rotl,_ rotr 

♦include <stdio.h> 

♦include <strings.h> 

int main( void ) 

{ 


printf( 

"%d\n", 

ffs ( 

0 ) ); 

printf( 

"%d\n", 

ffs ( 

16 ) ) ; 

printf( 

"%d\n", 

ffs ( 

127 ) ) ; 

printf( 

"%d\n", 

ffs ( 

-16 ) ); 


return( 0 ) ; 

} 

produces the following: 

0 

5 

1 

5 


POSIX 

All, Linux, RDOS, Netware 
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fgetc, fgetwc 


Synopsis: 

Description: 

Returns: 


See Also: 
Example: 


Classification: 

Systems: 


♦include <stdio.h> 
int fgetc( FILE *fp ); 

♦include <stdio.h> 

♦include <wchar.h> 

wint_ t fgetwc( FILE *fp ); 

The fgetc function gets the next character from the file designated by fp. The character is signed. 

The fgetwc function is identical to fgetc except that it gets the next multibyte character (if present) 
from the input stream pointed to by fp and converts it to a wide character. 

The fgetc function returns the next character from the input stream pointed to by fp. If the stream is 
at end-of-file, the end-of-file indicator is set and fgetc returns EOF. If a read error occurs, the error 
indicator is set and fgetc returns EOF. 

The fgetwc function returns the next wide character from the input stream pointed to by fp. If the 
stream is at end-of-file, the end-of-file indicator is set and fgetwc returns WEOF. If a read error 
occurs, the error indicator is set and fgetwc returns WEOF. If an encoding error occurs, errno is set 
to EILSEQ and fgetwc returns WEOF. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 

fgetchar, fgets, fopen, getc, getchar, gets, ungetc 

♦include <stdio.h> 

void main() 

{ 

FILE *fp; 
int c; 

fp = fopen( "file", "r" ); 
if( fp != NULL ) { 

while( (c = fgetc( fp )) != EOF ) 

fputc( c, stdout ); 
fclose ( fp ); 

} 

} 

ISOC 

fgetc - All, Linux, RDOS, Netware 
fgetwc - All, Linux 
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Synopsis: 

Description: 


Returns: 


See Also: 
Example: 


Classification: 

Systems: 


fgetchar, Jgetchar, Jgetwchar 


♦include <stdio.h> 
int fgetchar( void ) ; 
int _ fgetchar( void ); 
wint_ t _ fgetwchar( void ) ; 

The fgetchar function is equivalent to fgetc with the argument stdin. 

The _ fgetchar function is identical tofgetchar. Use _ fgetchar for ANSI naming 
conventions. 

The _ fgetwchar function is identical tofgetchar except that it gets the next multibyte character 
(if present) from the input stream pointed to by stdin and converts it to a wide character. 

The fgetchar function returns the next character from the input stream pointed to by stdin. If the 
stream is at end-of-file, the end-of-file indicator is set and fgetchar returns EOF. If a read error 
occurs, the error indicator is set and fgetchar returns EOF. 

The _ fgetwchar function returns the next wide character from the input stream pointed to by 
stdin. If the stream is at end-of-file, the end-of-file indicator is set and _ fgetwchar returnsWEOF. 
If a read error occurs, the error indicator is set and _ fgetwchar returnsWEOF. If an encoding error 
occurs, errno is set to EILSEQ and _ fgetwchar returnsWEOF. 

When an error has occurred, errno contains a value indicating the type of error that has been detected, 
fgetc, fgets, fopen, getc, getchar, gets, ungetc 
♦include <stdio.h> 

void main() 

{ 

FILE *fp; 
int c; 

fp = freopen( "file", "r", stdin ); 
if( fp != NULL ) { 

while( (c = fgetchar()) != EOF ) 

fputchar(c) ; 
fclose ( fp ); 

} 

} 

WATCOM 

_fgetchar conforms to ANSI naming conventions 

fgetchar - All, Linux, RDOS, Netware 
_ fgetchar - All, Linux, RDOS, Netware 
_ fgetwchar - All, Linux 
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fgetpos 


Synopsis: #include <stdio.h> 

int fgetpos ( FILE *fp, fpos_ t *pos ) ; 

Description: The fgetpos function stores the current position of the file^p in the object pointed to by pos. The 
value stored is usable by the f setpos function for repositioning the file to its position at the time of 
the call to the fgetpos function. 

Returns: The fgetpos function returns zero if successful, otherwise, the fgetpos function returns a non-zero 

value. When an error has occurred, err no contains a value indicating the type of error that has been 
detected. 

See Also: fopen, fseek, f setpos, ftell 

Example: #include <stdio.h> 

void main() 

{ 

FILE *fp; 

fpos_t position; 

auto char buffer[80]; 

fp = fopen( "file", "r" ); 
if( fp != NULL ) { 

fgetpos( fp, Sposition ); /* get position */ 

fgets( buffer, 80, fp ); /* read record */ 

fsetpos( fp, Sposition ); /* set position */ 

fgets( buffer, 80, fp ); /* read same record */ 

fclose ( fp ); 

} 

} 

Classification: ISO C 

Systems: All, Linux, RDOS, Netware 
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fgets, fgetws 


Synopsis: #include <stdio.h> 

char *fgets( char *buf, int n, FILE *fp ); 

♦include <stdio.h> 

♦include <wchar.h> 

wchar_ t *fgetws ( wchar_ t *buf, int n, FILE *fp ) ; 

Description: The f get s function gets a string of characters from the file designated by fp and stores them in the 
array pointed to by buf. The fgets function stops reading characters when end-of-file is reached, or 
when a newline character is read, or when n-1 characters have been read, whichever comes first. The 
new-line character is not discarded. A null character is placed immediately after the last character read 
into the array. 

The fgetws function is identical to fgets except that it gets a string of multibyte characters (if 
present) from the input stream pointed to by fp, converts them to wide characters, and stores them in the 
wide-character array pointed to by buf. In this case, n specifies the number of wide characters, less one, 
to be read. 

A common programming error is to assume the presence of a new-line character in every string that is 
read into the array. A new-line character will not be present when more than n-1 characters occur 
before the new-line. Also, a new-line character may not appear as the last character in a file, just before 
end-of-file. 

The gets function is similar to fgets except that it operates with stdin, it has no size argument, 
and it replaces a newline character with the null character. 

Returns: The fgets function returns buf if successful. NULL is returned if end-of-file is encountered, or a read 

error occurs. When an error has occurred, errno contains a value indicating the type of error that has 
been detected. 

See Also: fgetc, fgetchar, fopen, getc, getchar, gets, ungetc 

Example: ♦include <stdio.h> 

void main() 

{ 

FILE *fp; 

char buffer [80]; 

fp = fopen ( "file", "r" ); 
if( fp != NULL ) { 

while( fgets( buffer, 80, fp ) != NULL ) 

fputs( buffer, stdout ) ; 
fclose( fp ); 

} 

} 

Classification: ISO C 

Systems: fgets - All, Linux, RDOS, Netware 

fgetws - All, Linux 
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fieeetomsbin 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 

extern int _ fieeetomsbin( float *src, float *dest ); 

The _ fieeetomsbin function loads the float pointed to by src in IEEE format and converts it to 
Microsoft binary format, storing the result into the float pointed to by dest. 

For _ fieeetomsbin IEEE Nan’s and Infinities will cause overflow. IEEE denormals will be 
converted if within range. Otherwise, they will be converted to 0 in the Microsoft binary format. 

The range of Microsoft binary format floats is 2.938736e-39 to 1.701412e+38. The range of Microsoft 
binary format doubles is 2.938735877056e-39 to 1.701411834605e+38. 

Microsoft Binary Format was used by early versions of Microsoft QuickBASIC before coprocessors 
became standard. 

The _ fieeetomsbin function returns 0 if the conversion was successful. Otherwise, it returns 1 if 
conversion would cause an overflow. 

_ dieeetomsbin,_ dmsbintoieee,_ fmsbintoieee 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

float fieee, fmsb; 
double dieee, dmsb; 

fieee = 0.5; 
dieee = -2.0; 

/* Convert IEEE format to Microsoft binary format */ 

_ fieeetomsbin( &fieee, &fmsb ); 

_ dieeetomsbin( &dieee, &dmsb ); 

/* Convert Microsoft binary format back to IEEE format */ 

_ fmsbintoieee( &fmsb, Sfieee ); 

_ dmsbintoieee( &dmsb, Sdieee ) ; 

/* Display results */ 

printf( "fieee = %f, dieee = %f\n", fieee, dieee ); 

} 

produces the following: 

fieee = 0.500000, dieee = -2.000000 

WATCOM 

All, Linux, Netware 
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Synopsis: 

Description: 


Returns: 


See Also: 
Example: 


Classification: 

Systems: 


filelength, Jilelength, _filelengthi64 


♦include <io.h> 

long filelength( int handle ); 
long _ filelength( int handle ); 

_int64 _ filelengthi64 ( int handle ); 

The filelength function returns, as a 32-bit long integer, the number of bytes in the opened file 
indicated by the file handle handle. 

The _filelengthi64 function returns, as a 64-bit integer, the number of bytes in the opened file indicated 
by the file handle handle. 

The _ filelength function is identical tof ilelength. Use _ filelength for ANSI naming 
conventions. 

If an error occurs in filelength (-1L) is returned. 

If an error occurs in _filelengthi64, (-1164) is returned. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 

Otherwise, the number of bytes written to the file is returned. 

fstat, lseek, tell 

♦include <sys/types.h> 

♦include <fcntl.h> 

♦include <stdio.h> 

♦include <io.h> 

void main( void ) 

{ 

int handle; 

/* open a file for input */ 

handle = open ( "file", 0_ RDONLY | 0_ TEXT ); 
if( handle != -1 ) { 

printf ( "Size of file is %ld bytes\n", 
filelength! handle ) ); 

close ( handle ); 

} 

} 

produces the following: 

Size of file is 461 bytes 
WATCOM 

_filelength conforms to ANSI naming conventions 
filelength - All, Linux, RDOS, Netware 

_ filelength - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
_ filelengthi64 - All, Linux 
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FILENAME MAX 


Synopsis: #include <stdio.h> 

♦ define FILENAME_ MAX 123 

Description: The FILENAME_ MAX macro is the size of an array of char big enough to hold a string naming any file 
that the implementation expects to open; If there is no practical file name length limit, 

FILENAME_ MAX is the recommended size of such an array. As file name string contents must meet 
other system-specific constraints, some strings of length FILENAME_ MAX may not work. 

FILENAME_ MAX typically sizes an array to hold a file name. 

Returns: The FILENAME_ MAX macro returns a positive integer value. 

Example: #include <stdio.h> 

♦include <string.h> 


int main( int argc, char *argv[] ) 

{ 

if( argc ) { 

char fname [FILENAME_ MAX] ; 

strcpy( fname, argv[0] ); 
puts( fname ); 

} 

return( 0 ) ; 

} 

Classification: ISO C 
Systems: MACRO 
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fileno 


Synopsis: #include <stdio.h> 

int fileno( FILE *stream ); 

Description: The fileno function returns the number of the file handle for the file designated by stream. This 
number can be used in POSIX input/output calls anywhere the value returned by open can be used. 
The following symbolic values in <io. h> define the file handles that are associated with the C 
language stdin, stdout, stderr, stdaux, and stdprn files when the application is started. The stdaux and 
stdprn files are not available for Win32. 

Value Meaning 

STDIN_FILENO Standard input file number, stdin (0) 

STDOUT_FILENO Standard output file number, stdout (1) 

STDERR_FILENO Standard error file number, stderr (2) 

STDAUX_FILENO Standard auxiliary file number, stdaux (3) 

STDPRN_FILENO Standard printer file number, stdprn (4) 

Returns: The fileno function returns the number of the file handle for the file designated by stream. If an 

error occurs, a value of -1 is returned and errno is set to indicate the error. 

See Also: open 

Example: #include <stdio.h> 

void main() 

{ 

FILE ‘stream; 

stream = fopen( "file", "r" ); 

printf( "File number is %d\n", fileno( stream ) ); 

fclose( stream ); 

} 

produces the following: 

File number is 7 

Classification: POSIX 1003.1 
Systems: All, Linux, RDOS, Netware 
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findclose 


Synopsis: 

Description: 

Returns: 


See Also: 
Example: 


Classification: 

Systems: 


#include <io.h> 

int _ findclose( long handle ); 

The _ findclose function closes the directory of filenames established by a call to the_ f indf irst 
function. The handle argument was returned by the _ f indf irst function. 

If successful, _ findclose returns 0; otherwise,_ findclose and returns -1 and setserrno to one 
of the following values: 

Constant Meaning 

ENOENT No matching files 

_ dos_ find. . findfirst,_ f indnext.closedir, opendir, readdir 

♦include <stdio.h> 

♦include <io.h> 

void main() 

{ 

struct _ finddata_ t fileinfo; 
long handle; 

int rc; 

/* Display name and size of "*.c" files */ 

handle = _ findfirst ( "*.c", Sfileinfo ); 

rc = handle; 
while ( rc != -1 ) { 

printf( "%14s %101d\n", fileinfo.name, 

fileinfo.size ); 

rc = _ findnext( handle, sfileinfo ); 

} 

_ findclose( handle ); 

} 

DOS 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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find first, _findfirsti64, _wfindfirst, _wfindfirsti64 


Synopsis: #include <io.h> 

long _ findfirst( const char *filespec, 

struct _ finddata_ t *fileinfo ); 
long _ findfirsti64( const char *filespec, 

struct _ finddatai64_ t *fileinfo ); 
long _ wfindfirst( const wchar_ t *filespec, 

struct _ wfinddata_ t *fileinfo ); 
long _ wfindfirsti64( const wchar_ t *filespec, 

struct _ wfinddatai64_ t *fileinfo ); 

Description: The _ findfirst function returns information on the first file whose name matches th efilespec 
argument. Th efilespec argument may contain wildcard characters (’?’ and The information is 
returned in a _ f inddata_ t structure pointed to by fileinfo. 

struct _ finddata_ t { 
unsigned attrib; 

time_ t time_ create; /* -1 for FAT file systems */ 

time_t time_ access; /* -1 for FAT file systems */ 

time_ t time_ write; 

_ fsize_ t size; 

char name [_ MAX_ PATH] ; 

} ; 

The _fmdfirsti64 function returns information on the first file whose name matches th efilespec 
argument. It differs from the _ findfirst function in that it returns a 64-bit file size. Th efilespec 
argument may contain wildcard characters (’?’ and The information is returned in a 
_ finddatai64_ t structure pointed to by fileinfo. 

struct _ finddatai64_ t { 
unsigned attrib; 

time_ t time_ create; /* -1 for FAT file systems */ 

time_t time_ access; /* -1 for FAT file systems */ 

time_ t time_ write; 

_ int64 size; /* 64-bit size info */ 

char name [_ MAX_ PATH] ; 

} ; 

The _ wf indf irsti64 function is a wide-character version of_ findfirst that operates with 
wide-character strings. 

struct _ wfinddata_ t { 
unsigned attrib; 

time_ t time_ create; /* -1 for FAT file systems */ 

time_t time_ access; /* -1 for FAT file systems */ 

time_ t time_ write; 

_ fsize_ t size; 

wchar_ t name [_ MAX_ PATH] ; 

} ; 

The wide-character _wfindfirsti64 function is similar to the _findfirsti64 function but operates on 
wide-character strings. It differs from the _ wf indf irsti64 function in that it returns a 64-bit file 
size. 
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struct _ wfinddatai64_ t { 
unsigned attrib; 

time_ t time_ create; /* -1 for FAT file systems */ 

time_t time_ access; /* -1 for FAT file systems */ 

time_ t time_ write; 

_ int64 size; /* 64-bit size info */ 

wchar_ t name [_ MAX_ PATH] ; 

} ; 

Returns: If successful, _ f indf irst returns a unique search handle identifying the file or group of files 

matching the filespec specification, which can be used in a subsequent call to _ f indnext or to 
_ f indclose. Otherwise,_ f indf irst and returns -1 and setserrno to one of the following 
values: 

Constant Meaning 

ENOENT No matching files 

EINVAL Invalid filename specification 

See Also: _ dos_ find. . ,j_ findclose,_ findnext.closedir, opendir, readdir 

Example: #include <stdio.h> 

♦include <io.h> 

void main () 

{ 

struct _ finddata_ t fileinfo; 
long handle; 

int rc; 

/* Display name and size of "*.c" files */ 

handle = _ findfirst( "*.c", Sfileinfo ); 

rc = handle; 
while ( rc != -1 ) { 

printf ( "%14s %101d\n", fileinfo.name, 

fileinfo.size ); 

rc = _ findnext( handle, Sfileinfo ); 

} 

_ findclose( handle ); 

} 

Classification: DOS 

Systems: _ findfirst - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 

_ findfirsti64 - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
_ wfindfirst - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
_ wfindfirsti64 - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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Synopsis: #include <io.h> 

int _ findnext( long handle, 

struct _ finddata_ t *fileinfo ); 
int _ findnexti64 ( long handle, 

struct _ finddatai64_ t *fileinfo ); 
int _ wfindnext ( long handle, 

struct _ wfinddata_ t *fileinfo ); 
int _ wfindnexti64 ( long handle, 

struct _ wfinddatai64_ t *fileinfo ); 

Description: The _ findnext function returns information on the next file whose name matches th efilespec 

argument that was specified in a call to the _ f indf irst function. The handle argument was returned 
by the _ f indf irst function. The information is returned in a_ f inddata_ t structure pointed to 
by file info. 

struct _ finddata_ t { 
unsigned attrib; 

time_ t time_ create; /* -1 for FAT file systems */ 

time_t time_ access; /* -1 for FAT file systems */ 

time_ t time_ write; 

_ fsize_ t size; 

char name [_ MAX_ PATH] ; 

}; 

The _ f indnexti64 function returns information on the next file whose name matches th efilespec 
argument that was specified in a call to the _ f indf irsti64 function. It differs from the 
_ findnext function in that it returns a 64-bit file size. The handle argument was returned by the 
_ f indf irsti64 function. The information is returned in a_ f inddatai64_ t structure pointed to 
by file info. 

struct _ finddatai64_ t { 
unsigned attrib; 

time_ t time_ create; /* -1 for FAT file systems */ 

time_t time_ access; /* -1 for FAT file systems */ 

time_ t time_ write; 

_ int64 size; /* 64-bit size info */ 

char name [_ MAX_ PATH] ; 

}; 

The _ wf indnexti64 function is a wide-character version of_ findnext that operates with 
wide-character strings. 

struct _ wfinddata_ t { 
unsigned attrib; 

time_ t time_ create; /* -1 for FAT file systems */ 

time_t time_ access; /* -1 for FAT file systems */ 

time_ t time_ write; 

_ fsize_ t size; 

wchar_ t name [_ MAX_ PATH] ; 

} ; 

The wide-character _ wf indnexti64 function is similar to the_ f indnexti64 function but 
operates on wide-character strings. It differs from the _ wf indnexti64 function in that it returns a 
64-bit file size. 
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findnext, 


Returns: 


See Also: 
Example: 


Classification: 

Systems: 


findnexti64, _wfindnext, _wfindnexti64 


struct _ wfinddatai64_ t { 


unsigned 

attrib; 





time_ t 

time_ create; 

/* -1 for FAT 

file 

systems 

*/ 

time_ t 

time_ access; 

/* -1 for FAT 

file 

systems 

*/ 

time_ t 

time_ write; 





_ int64 

size; 

/* 64-bit size 

info 

*/ 



wchar_ t name [_ MAX_ PATH] ; 


If successful, _ findnext returns 0; otherwise,_ findnext and returns -1 and setserrno to one of 
the following values: 

Constant Meaning 

ENOENT No matching files 

_ dos_ find. . findclose,_ findfirst.closedir, opendir, readdir 

♦include <stdio.h> 

♦include <io.h> 

void main() 

{ 

struct _ finddata_ t fileinfo; 
long handle; 

int rc; 

/* Display name and size of "*.c" files */ 

handle = _ findfirst ( "*.c", sfileinfo ); 

rc = handle; 
while ( rc != -1 ) { 

printf( "%14s %101d\n", fileinfo.name, 

fileinfo.size ); 

rc = _ findnext( handle, Sfileinfo ); 

} 

_ findclose( handle ); 

} 

DOS 

_ findnext - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
_ findnexti64 - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
_ wfindnext - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
_ wfindnexti64 - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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Synopsis: #include <float.h> 

int _ finite( double x ); 

Description: The _ finite function determines whether the double precision floating-point argument is a valid 
number (i.e., not infinite and not a NAN). 

Returns: The _ finite function returns 0 if the number is not valid and non-zero otherwise. 

See Also: _ clear87,_ control87,_ controlfp,_ fpreset,printf, _ status87,isf inite, 

fpclassify 

Example: #include <stdio.h> 

♦include <float.h> 

void main() 

{ 

printf ( "%s\n", (_ finite ( 1.797693134862315e+308 ) ) 

? "Valid" : "Invalid" ); 

printf ( "%s\n", (_ finite( 1.797693134862320e+308 ) ) 

? "Valid" : "Invalid" ); 

} 

produces the following: 

Valid 

Invalid 

Classification: WATCOM 

Systems: Math 
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Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <graph.h> 

short _ FAR _ floodfill( short x, short y, 

short stop_ color ); 

short _ FAR _ f loodf ill_ w ( double x, double y, 

short stop_ color ) ; 

The _ floodfill functions fill an area of the screen. The_ floodfill function uses the view 
coordinate system. The _ f loodf ill_ w function uses the window coordinate system. 

The filling starts at the point (x,y) and continues in all directions: when a pixel is filled, the 
neighbouring pixels (horizontally and vertically) are then considered for filling. Filling is done using 
the current color and fill mask. No filling will occur if the point (x, y) lies outside the clipping region. 

If the argument stop_color is a valid pixel value, filling will occur in each direction until a pixel is 
encountered with a pixel value of stop_color. The filled area will be the area around (x, y) , bordered 
by stop_color. No filling will occur if the point (x, y) has the pixel value stop_color. 

If stop_color has the value (-1), filling occurs until a pixel is encountered with a pixel value different 
from the pixel value of the starting point (x, y) . No filling will occur if the pixel value of the point 
(x,y) is the current color. 

The _ floodfill functions return zero when no filling takes place; a non-zero value is returned to 
indicate that filling has occurred. 

_ setcliprgn^ setcolor w setfillmask,_ setplotaction 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

_ setvideomode( _ VRES16C0L0R ); 

_ setcolor( 1 ) ; 

_ ellipse( _ GBORDER, 120, 90, 520, 390 ); 

_ setcolor( 2 ) ; 

_ floodfill( 320, 240, 1 ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ) ; 

} 

PC Graphics 

_ floodfill - DOS 
_ floodfill_ w - DOS 
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floor 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double floor( double x ) ; 

The floor function computes the largest integer not greater than x. 

The floor function computes the largest integer not greater than x, expressed as a double . 
ceil, fmod 

♦include <stdio.h> 

♦include <math.h> 

void main() 


printf( 

" % f \ n " , 

floor( 

-3.14 

printf( 

" % f \ n " , 

floor( 

-3. ) 

printf( 

" % f \ n " , 

floor( 

0. ) 

printf( 

" % f \ n " , 

floor( 

3.14 

printf( 

" % f \ n " , 

floor( 

3. ) 


produces the following: 

-4.000000 

-3.000000 

0.000000 

3.000000 

3.000000 

ISOC 

Math 
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flushall 


Synopsis: #include <stdio.h> 

int flushall( void ) ; 

Description: The flushall function clears all buffers associated with input streams and writes any buffers 

associated with output streams. A subsequent read operation on an input file causes new data to be read 
from the associated file or device. 

Calling the flushall function is equivalent to calling the f flush for all open stream files. 

Returns: The flushall function returns the number of open streams. When an output error occurs while 

writing to a file, the errno global variable will be set. 


See Also: 
Example: 


fopen, fflush 
♦include <stdio.h> 

void main() 

{ 

printf ( "The number of open files is %d\n", 
flushall () ); 

} 


produces the following: 

The number of open files is 4 

Classification: WATCOM 

Systems: All, Linux, RDOS, Netware 
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fma 


Synopsis: 

Description: 

Returns: 

Example: 


Classification: 

Systems: 


#include <math.h> 

double fma( double x, double y, double z ); 

The fma function performs a fused multiply-add operation. The resultant value is the product of x and 
y summed with z. 

The x*y+z 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", fma( 2.0, 3.0, 1.0 ) ); 

} 

produces the following: 

7.00000 
ISO C99 
Math 
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Synopsis: #include <math.h> 

double fmax( double x, double y ); 

Description: The fmax function returns the larger of x and y. 

Returns: The routine will return the larger of x or y. 

See Also: f dim, fmin 

Example: #include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", fmax( 3.0, 2.0 ) ); 

} 

produces the following: 

3.000000 

Classification: ISO C99 
Systems: Math 


288 Library Functions and Macros 




fmin 


Synopsis: #include <math.h> 

double fmin( double x, double y ); 

Description: The fmin function returns the smaller of x and y. 

Returns: The routine will return the smaller of x or y. 

See Also: f dim, fmax 

Example: #include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", fmin( 3.0, 2.0 ) ); 

} 

produces the following: 

2.000000 

Classification: ISO C99 
Systems: Math 
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fmod 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 

double fmod( double x, double y ); 

The fmod function computes the floating-point remainder of x/y, even if the quotient x/y is not 
representable. 

The fmod function returns the value x - (i *y), for some integer i such that, if y is non-zero, the result 
has the same sign as x and magnitude less than the magnitude of y. If the value of y is zero, then the 
value returned is zero. 

ceil, fabs, floor 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 


printf( 

"%f\n", fmod( 

4.5, 

2.0 ) 

) ; 

printf( 

"%f\n", fmod( 

-4.5, 

2.0 ) 

) ; 

printf( 

"%f\n", fmod( 

4.5, 

-2.0 ) 

) ; 

printf( 

"%f\n", fmod( 

-4.5, 

-2.0 ) 

); 


} 

produces the following: 

0.500000 

-0.500000 

0.500000 

-0.500000 

ISOC 

Math 
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fmsbintoieee 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 

extern int _ fmsbintoieee( float *src, float *dest ); 

The _ fmsbintoieee function loads the float pointed to by src in Microsoft binary format and 
converts it to IEEE format, storing the result &into the float pointed to by dest. 

The range of Microsoft binary format floats is 2.938736e-39 to 1.701412e+38. The range of Microsoft 
binary format doubles is 2.938735877056e-39 to 1.701411834605e+38. 

Microsoft Binary Format was used by early versions of Microsoft QuickBASIC before coprocessors 
became standard. 

The _ fmsbintoieee function returns 0 if the conversion was successful. Otherwise, it returns 1 if 
conversion would cause an overflow. 

_ dieeetomsbin,_ dmsbintoieee,_ fieeetomsbin 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

float fieee, fmsb; 
double dieee, dmsb; 

fieee = 0.5; 
dieee = -2.0; 

/* Convert IEEE format to Microsoft binary format */ 

_ fieeetomsbin( Sfieee, &fmsb ); 

_ dieeetomsbin( &dieee, &dmsb ); 

/* Convert Microsoft binary format back to IEEE format */ 

_ fmsbintoieee( &fmsb, &fieee ); 

_ dmsbintoieee( &dmsb, Sdieee ) ; 

/* Display results */ 

printf( "fieee = %f, dieee = %f\n", fieee, dieee ); 

} 

produces the following: 

fieee = 0.500000, dieee = -2.000000 
WATCOM 

All, Linux, RDOS, Netware 
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fnmatch 


Synopsis: #include <fnmatch.h> 

int fnmatch( const char *pattern, 

const char *string, int flags ); 

Description: The fnmatch function checks the string specified by the string argument to see if it matches the 
pattern specified by the pattern argument. 

The flag argument is a bitwise inclusive OR of the bits described below. It modifies the interpretation 
of pattern and string. 

Flag Meaning 

FNM_PATHNAME If set, a path separator in string is explicitly matched by a slash in pattern. It isn’t 
matched by either the asterisk or question mark special characters, or by a bracket 
expression. 

FNM_PERIOD If set, a leading period in string matches a period in pattern, where the definition of 
"leading" depends on FNM_PATHNAME: 

• If FNM_PATHNAME is set, a period is leading if it’s the first character in string, or if 
it immediately follows a path separator. 

• If FNM_PATHNAME isn’t set, a period is leading only if it’s the first character in 
string. 

FNM_NOESCAPE If set, disables backslash escaping: 

• If FNM_NOESCAPE isn't set in flags, a backslash character (\) in pattern followed by 
any other character matches that second character in string. In particular, \\ matches a 
backslash in string. 

• If FNM_NOESCAPE is set, a backslash character is treated as an ordinary character. 
FNM_IGNORECASE If set, the matching is case-insensitive. 

FNM CA SEFOLD A synonym for FNMJGNORECASE. 

FNM_LEADING_DIR If set, the final path separator and any following characters in string are ignored 
during matching. 

A pattern-matching special character that is quoted is a pattern that matches the special character itself. 
When not quoted, such special characters have special meaning in the specification of patterns. The 
pattern-matching special characters and the contexts in which they have their special meaning are as 
follows: 

? a ? is a pattern that matches any printable or nonprintable character except <newline>. 

* the * matches any string, including the null string. 

[br_exp] a pattern that matches a single character as per Regular Expression Bracket Expressions 

(1003.2 2.9.1.2) except that 


292 Library Functions and Macros 




fnmatch 


• The exclamation point character (!) replaces the circumflex character ( A ) in its 
role as a nonmatching list in the regular expression notation. 

• The backslash is used as an escape character within bracket expressions. 

The ?, * and [ characters aren't special when used inside a bracket expression. 

The concatenation of patterns matching a single character is a valid pattern that matches the 
concatenation of the single characters matched by each of the concatenated patterns. For example, the 
pattern a [be] matches the strings ab and ac. 

The concatenation of one or more patterns matching a single character with one or more asterisks (*) is 
a valid pattern. In such patterns, each asterisk matches a string of zero or more characters, up to the first 
character that matches the character following the asterisk in the pattern. For example, the pattern a*d 
matches the strings ad, abd, and abed, but not the string abc . 

When asterisk is the first or last character in a pattern, it matches zero or more characters that precede or 
follow the characters matched by the remainded of the pattern. For example, the pattern a*d* matches 
the strings ad, abed, abedef, aaaad and adddd. The pattern *a*d matches the strings ad, 
abed, efabed, aaaadandadddd. 

Returns: The fnmatch function returns zero when string matches the pattern specified by pattern. If there is no 

match, FNM_NOMATCH is returned. If an error occurs, fnmatch returns another non-zero value. 

Example: #include <stdio.h> 

♦include <fnmatch.h> 

♦include <stdlib.h> 

♦include <limits.h> 

int main( int arge, char **argv ) 

{ 

int i; 

char buf fer [PATH_ MAX+1 ] ; 

while( gets( buffer ) ) { 

for( i = 1; i < arge; i++ ) { 

if( fnmatch( argv[i], buffer, 0 ) == 0 ) { 

printf( %s' matches pattern '%s'\n", 

buffer, argv[i] ); 

break; 

} 

} 

} 

return ( EXIT_ SUCCESS ); 

} 

Classification: POSIX 1003.2 
Systems: All, Linux, RDOS, Netware 
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fopen, _wfopen 


Synopsis: #include <stdio.h> 

FILE *fopen( const char *filename, const char *mode ); 

FILE *_ wfopen( const wchar_t ^filename, 
const wchar_ t *mode ); 

Safer C: The Safer C Library extension provides the f open_ s function which is a safer alternative tof open 

This newer f open_ s function is recommended to be used instead of the traditional "unsafe" fopen 
function. 

Description: The fopen function opens the file whose name is the string pointed to by filename, and associates a 
stream with it. The argument mode points to a string beginning with one of the following sequences: 

Mode Meaning 

"r" open file for reading 

"w" create file for writing, or truncate to zero length 

"a" append: open file or create for writing at end-of-file 

"r+" open file for update (reading and/or writing) 

"w+" create file for update, or truncate to zero length 

"a+" append: open file or create for update, writing at end-of-file 

In addition to the above characters, you can also include one of the following characters in mode to 
specify the translation mode for newline characters: 

t The letter "t" may be added to any of the above sequences in the second or later position 

to indicate that the file is (or must be) a text file. It also overrides the global translation 
mode flag if you link your program with BINMODE . OBJ . The global translation 
mode flag default is "text" unless you explicitly link your program with 
BINMODE.OBJ. 

When neither "t" nor "b" is specified, the value of the global variable _ fmode 
establishes whether the file is to treated as a binary or a text file. Unless this value is 
changed by the program or you have linked your program with BINMODE . OBJ, the 
default will be text mode. 

b The letter "b" may be added to any of the above sequences in the second or later 

position to indicate that the file is (or must be) a binary file (an ISO C requirement for 
portability to systems that make a distinction between text and binary files). 

You can also include one of the following characters to enable or disable the "commit" flag for the 
associated file. 

c The letter "c" may be added to any of the above sequences in the second or later 

position to indicate that any output is committed by the operating system whenever a 
flush ( fflush or flushall) is done. 

This option is not supported under Netware. 
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n The letter "n" may be added to any of the above sequences in the second or later 

position to indicate that the operating system need not commit any output whenever a 
flush is done. It also overrides the global commit flag if you link your program with 
COMMODE . OBJ. The global commit flag default is "no-commit" unless you explicitly 
link your program with COMMODE . OBJ. 

This option is not supported under Netware. 

The "t", "c", and "n" mode options are extensions for fopen and _ fdopen and should not be used 
where ISO C portability is desired. 

Opening a file with read mode (r as the first character in the mode argument) fails if the file does not 
exist or it cannot be read. Opening a file with append mode (a as the first character in the mode 
argument) causes all subsequent writes to the file to be forced to the current end-of-file, regardless of 
previous calls to the f seek function. When a file is opened with update mode (+ as the second or later 
character of the mode argument), both input and output may be performed on the associated stream. 

When a stream is opened in update mode, both reading and writing may be performed. However, 
writing may not be followed by reading without an intervening call to the f f lush function or to a file 
positioning function (f seek, f setpos, rewind). Similarly, reading may not be followed by writing 
without an intervening call to a file positioning function, unless the read resulted in end-of-file. 

The _ wf open function is a wide-character version off open that operates with wide-character strings. 

Returns: The fopen function returns a pointer to the object controlling the stream. This pointer must be passed 

as a parameter to subsequent functions for performing operations on the file. If the open operation fails, 
fopen returns NULL . When an error has occurred, errno contains a value indicating the type of 
error that has been detected. 

See Also: _ dos_ openf close, fcloseall, fdopen, fopen_ s,f reopen, freopen_ s,_ fsopen, 

_ grow_ handles^ hdopen,open, _ open_ osfhandlej. popen,sopen 

Example: #include <stdio.h> 

void main() 

{ 

FILE *fp; 

fp = fopen( "file", "r" ); 
if ( fp != NULL ) { 

/* rest of code goes here */ 
fclose( fp ); 

} 

} 

Classification: ISO C ft’, V, ’n’ are Open Watcom extensions) 

_wfopen is WATCOM 

Systems: fopen - All, Linux, RDOS, Netware 

_ wfopen - All, Linux 


Library Functions and Macros 295 




fopen_s, _wfopen_s 


Synopsis: #def ine_ STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

errno_ t fopen_ s ( FILE * restrict * restrict streamptr, 
const char * restrict filename, 
const char * restrict mode); 

errno_ t _ wfopen_ s ( FILE * restrict * restrict streamptr, 

const wchar_ t * restrict filename, 
const wchar_ t * restrict mode); 

Constraints: If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and f open_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

None of streamptr, filename, or mode shall be a null pointer. If there is a runtime-constraint violation, 
f open_ s does not attempt to open a file. Furthermore, if streamptr is not a null pointer, f open_ s 
sets *streamptr to the null pointer. 

Description: The f open_ s function opens the file whose name is the string pointed to by filename, and associates a 
stream with it. The mode string shall be as described for fopen, with the addition that modes starting 
with the character ’w’ or ’a’ may be preceded by the character ’u\ see below: 

Mode Meaning 

"uw " truncate to zero length or create text file for writing, default permissions 

"ua" append; open or create text file for writing at end-of-file, default permissions 

"uwb" truncate to zero length or create binary file for writing, default permissions 

"uab" append; open or create binary file for writing at end-of-file, default permissions 

"uw+" truncate to zero length or create text file for update, default permissions 

"ua+" append; open or create text file for update, writing at end-of-file, default permissions 

"uw+b or uwb+" truncate to zero length or create binary file for update, default permissions 

"ua+b or uab+" append; open or create binary file for update, writing at end-of-file, default 
permissions 

To the extent that the underlying system supports the concepts, files opened for writing shall be opened 
with exclusive (also known as non-shared) access. If the file is being created, and the first character of 
the mode string is not ’u\ to the extent that the underlying system supports it, the file shall have a file 
permission that prevents other users on the system from accessing the file. If the file is being created 
and first character of the mode string is ’u\ then by the time the file has been closed, it shall have the 
system default file access permissions. If the file was opened successfully, then the pointer to FILE 
pointed to by streamptr will be set to the pointer to the object controlling the opened file. Otherwise, 
the pointer to FILE pointed to by streamptr will be set to a null pointer. 

In addition to the above characters, you can also include one of the following characters in mode to 
specify the translation mode for newline characters: 
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Returns: 


See Also: 


fopen_s, _wfopen_s 


t The letter "t" may be added to any of the above sequences in the second or later position 

to indicate that the file is (or must be) a text file. It also overrides the global translation 
mode flag if you link your program with BINMODE . OBJ . The global translation 
mode flag default is "text" unless you explicitly link your program with 
BINMODE.OBJ. 

When neither "t" nor "b" is specified, the value of the global variable _ fmode 
establishes whether the file is to treated as a binary or a text file. Unless this value is 
changed by the program or you have linked your program with BINMODE . OBJ, the 
default will be text mode. 

b The letter "b" may be added to any of the above sequences in the second or later 

position to indicate that the file is (or must be) a binary file (an ISO C requirement for 
portability to systems that make a distinction between text and binary files). 

You can also include one of the following characters to enable or disable the "commit" flag for the 
associated file. 

c The letter "c" may be added to any of the above sequences in the second or later 

position to indicate that any output is committed by the operating system whenever a 
flush ( fflush or flushall) is done. 

This option is not supported under Netware. 

n The letter "n" may be added to any of the above sequences in the second or later 

position to indicate that the operating system need not commit any output whenever a 
flush is done. It also overrides the global commit flag if you link your program with 
COMMODE . OBJ . The global commit flag default is "no-commit" unless you explicitly 
link your program with COMMODE . OBJ. 

This option is not supported under Netware. 

The "t", "c", and "n" mode options are extensions for fopen_s and should not be used where ISO C 
portability is desired. 

Opening a file with read mode (r as the first character in the mode argument) fails if the file does not 
exist or it cannot be read. Opening a file with append mode (a as the first character in the mode 
argument) causes all subsequent writes to the file to be forced to the current end-of-file, regardless of 
previous calls to the f seek function. When a file is opened with update mode (+ as the second or later 
character of the mode argument), both input and output may be performed on the associated stream. 

When a stream is opened in update mode, both reading and writing may be performed. However, 
writing may not be followed by reading without an intervening call to the f f lush function or to a file 
positioning function (f seek, f setpos, rewind). Similarly, reading may not be followed by writing 
without an intervening call to a file positioning function, unless the read resulted in end-of-file. 

The _ wf open_ s function is a wide-character version of open_ s that operates with wide-character 
strings. 

The f open_ s function returns zero if it opened the file. If it did not open the file or if there was a 
runtime-constraint violation, f open_ s returns a non-zero value. 

_ dos_ openfclose, fcloseall, fdopen, fopen, freopen, freopen_ s,_ fsopen, 

_ grow_ handles^, hdopen.open, _ open_ osfhandle^, popen.sopen 
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fopen_s, _wfopen_s 


Example: 


Classification: 


Systems: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

void main() 

{ 

errno_ t rc; 

FILE *fp; 

rc = fopen_ s( &fp, "file", "r" ); 
if( fp != NULL ) { 

/* rest of code goes here */ 
fclose ( fp ); 

} 

} 

TR 24731 

_wfopen_s is WATCOM 

fopen_ s - All, Linux, RDOS, Netware 
_ wfopen_ s - All, Linux 
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FP OFF 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <i86.h> 

unsigned FP_ OFF ( void_far *far_ptr ); 

The FP_ OFF macro can be used to obtain the offset portion of the far pointer value given in far_ptr. 

The macro returns an unsigned integer value which is the offset portion of the pointer value. 

FP_ SEGjyiK_ FP,segread 

♦include <stdio.h> 

♦include <i86.h> 

char ColourTable[256] [3]; 

void main() 

{ 

union REGPACK r; 
int i; 

/* read block of colour registers */ 
r.h.ah = 0x10; 
r.h.al = 0x17; 

♦ if defined(_ 386_) 

r.x.ebx = 0; 
r.x.ecx = 256; 

r.x.edx = FP_ OFF ( ColourTable ); 
r.w.ds = r.w.fs = r.w.gs = FP_ SEG( &r ); 

♦ else 

r.w.bx = 0; 
r.w.cx = 256; 

r.w.dx = FP_ OFF ( ColourTable ); 

♦endif 

r.w.es = FP_ SEG( ColourTable ); 
intr( 0x10, &r ); 

for( i = 0; i < 256; i++ ) { 

printf( "Colour index = %d " 

"{ Red=%d, Green=%d, Blue=%d }\n", 

i, 

ColourTable[i][0], 

ColourTable[i][1], 

ColourTable[i][2] ); 

} 

} 

Intel 

MACRO 
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FP SEG 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <i86.h> 

unsigned FP_ SEG ( void_far *far_ptr ); 

The FP_ SEG macro can be used to obtain the segment portion of the far pointer value given in far_ptr. 

The macro returns an unsigned integer value which is the segment portion of the pointer value. 

FP_ OFFjyiK_ FP,segread 

♦include <stdio.h> 

♦include <i86.h> 

char ColourTable[256] [3]; 

void main() 

{ 

union REGPACK r; 
int i; 

/* read block of colour registers */ 
r.h.ah = 0x10; 
r.h.al = 0x17; 

♦ if defined(_ 386_) 

r.x.ebx = 0; 
r.x.ecx = 256; 

r.x.edx = FP_ OFF ( ColourTable ); 
r.w.ds = r.w.fs = r.w.gs = FP_ SEG( &r ); 

♦ else 

r.w.bx = 0; 
r.w.cx = 256; 

r.w.dx = FP_ OFF ( ColourTable ); 

♦endif 

r.w.es = FP_ SEG( ColourTable ); 
intr( 0x10, &r ); 

for( i = 0; i < 256; i++ ) { 

printf( "Colour index = %d " 

"{ Red=%d, Green=%d, Blue=%d }\n", 

i, 

ColourTable[i][0], 

ColourTable[i][1], 

ColourTable[i][2] ); 

} 

} 

Intel 

MACRO 
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fpclassify 


Synopsis: #include <math.h> 

int fpclassify( x ); 

Description: The fpclassify macro classifies its argument x as NaN, infinite, normal, subnormal, or zero. First, 
an argument represented in a format wider than its semantic type is converted to its semantic type. 

Then classification is based on the type of the argument. 

The argument x must be an expression of real floating type. 

The possible return values of fpclassify and their meanings are listed below. 

Constant Meaning 

FP_INFINITE positive or negative infinity 

FP_NAN NaN (not-a-number) 

FP NORMA L normal number (neither zero, subnormal, NaN, nor infinity) 

FP_SUBNORMAL subnormal number 

FP ZERO positive or negative zero 

Returns: The fpclassify macro returns the value of the number classification macro appropriate to the value 

of its argument x. 

See Also: isfinite, isinf, isnan, isnormal, signbit 

Example: ((include <math.h> 

♦include <stdio.h> 

void main( void ) 

{ 

printf( "infinity %s a normal number\n", 

fpclassify ( INFINITY ) == FP_ NORMAL ? 

"is" : "is not" ) ; 

} 

produces the following: 

infinity is not a normal number 

Classification: ISO C 
Systems: MACRO 


Library Functions and Macros 301 




fpreset 


Synopsis: #include <float.h> 

void _ fpreset ( void ); 

Description: The _ fpreset function resets the floating-point unit to the default state that the math library requires 
for correct function. After a floating-point exception, it may be necessary to call the _ fpreset 
function before any further floating-point operations are attempted. 

In multi-threaded environments, _ fpreset only affects the current thread. 

Returns: No value is returned. 

See Also: _ clear87^_ control87,_ controlfp,_ finite^ status87 

Example: #include <stdio.h> 

♦include <float.h> 

char *status[2] = { "No", " " }; 

void main( void ) 

{ 

unsigned int fp_ status; 

fp_ status = _ status87 (); 

printf ( "80x87 status\n" ); 
printf( "%s invalid operation\n", 

status! (fp_ status & SW_ INVALID) == 0 ] ); 

printf ( "%s denormalized operand\n", 

status! (fp_ status & SW_ DENORMAL) == 0 ] ); 

printf ( "%s divide by zero\n", 

status! (fp_ status & SW_ ZERODIVIDE) == 0 ] ); 

printf ( "%s overflow\n", 

status! (fp_ status & SW_ OVERFLOW) == 0 ] ); 

printf ( "%s underflow\n", 

status! (fp_ status & SW_ UNDERFLOW) == 0 ] ); 

printf ( "%s inexact result\n", 

status! (fp_ status & SW_ INEXACT) == 0 ] ); 

_ fpreset(); 

} 

Classification: Intel 

Systems: All, Linux, RDOS, Netware 
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fprintf, fwprintf 


Synopsis: 


Safer C: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


Systems: 


♦include <stdio.h> 

int fprintf( FILE *fp, const char *format, ... ); 

♦include <stdio.h> 

♦include <wchar.h> 

int fwprintf ( FILE *fp, const wchar_ t *format, ... ); 

The Safer C Library extension provides the fprintf_ s function which is a safer alternative to 
fprintf This newer fprintf_ s function is recommended to be used instead of the traditional 
"unsafe" fprintf function. 

The fprintf function writes output to the file pointed to by fp under control of the argument format. 
The format string is described under the description of the print f function. 

The fwprintf function is a wide-character version of fprintf. It accepts a wide-character string 
argument for format and produces wide character output. 

The fprintf function returns the number of characters written, or a negative value if an output error 
occurred. The fwprintf function returns the number of wide characters written, or a negative value 
if an output error occurred. When an error has occurred, errno contains a value indicating the type of 
error that has been detected. 


_ bprintf.cprintf, printf, sprintf, _ vbprintf.vcprintf, vfprintf, vprintf, 
vsprintf 

♦include <stdio.h> 


char *weekday = { "Saturday" }; 
char *month = { "April" }; 


void main( void ) 

{ 


} 


fprintf( stdout, "%s, 
weekday, month. 


%s %d, %d\n", 
18, 1987 ); 


produces the following: 
Saturday, April 18, 1987 


ISOC 

fwprintf is ISO C95 

fprintf - All, Linux, RDOS, Netware 
fwprintf - All, Linux 
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fprintf_s, fwprintf_s 


Synopsis: 


Constraints: 


Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

int fprintf_ s ( FILE * restrict stream, 

const char * restrict format, ... ); 

♦include <wchar.h> 

int fwprintf_ s ( FILE * restrict stream. 

const wchar_ t * restrict format, ... ); 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and fprintf_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither stream nor format shall be a null pointer. The %n specifier (modified or not by flags, field 
width, or precision) shall not appear in the string pointed to by format. Any argument to fprintf_ s 
corresponding to a % s specifier shall not be a null pointer. 

If there is a runtime-constraint violation, the fprintf_ s function does not attempt to produce further 
output, and it is unspecified to what extent fprintf_ s produced output before discovering the 
runtime-constraint violation. 

The fprintf_ s function is equivalent to thefprintf function except for the explicit 
runtime-constraints listed above. 

The fwprintf_ s function is a wide-character version offprintf_ s. It accepts a wide-character 
string argument for format and produces wide character output. 

The fprintf_ s function returns the number of characters written, or a negative value if an output 
error or runtime-constraint violation occurred. 


The fwprintf_ s function returns the number of wide characters written, or a negative value if an 
output error or runtime-constraint violation occurred. 


_ bprintf.cprintf, fprintf, printf, sprintf, _ vbprintf.vcprintf, vfprintf, 
vprintf, vsprintf 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 


char *weekday = { "Friday" }; 
char *month = { "August" }; 


void main( void ) 

{ 


} 


fprintf_ s ( stdout, 
weekday. 


"%s, %s %d, %d\n", 
month, 13, 2004 ); 


produces the following: 

Friday, August 13, 2004 


TR 24731 


fprintf_ s - All, Linux, RDOS, Netware 
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fprintf_s, fwprintf_s 


fwprintf_ s - All, Linux 
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fputc, fputwc 


Synopsis: 

Description: 

Returns: 


See Also: 
Example: 


Classification: 

Systems: 


♦include <stdio.h> 

int fputc( int c, FILE *fp ); 

♦include <stdio.h> 

♦include <wchar.h> 

wint_ t fputwc( wint_ t c, FILE *fp ); 

The fputc function writes the character specified by the argument c to the output stream designated by 
fP- 


The fputwc function is identical to fputc except that it converts the wide character specified by c to 
a multibyte character and writes it to the output stream. 

The fputc function returns the character written or, if a write error occurs, the error indicator is set 
and fputc returns EOF. 

The fputwc function returns the wide character written or, if a write error occurs, the error indicator is 
set and fputwc returns WEOF. If an encoding error occurs, errno is set to EILSEQ and fputwc 
returns WEOF. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 

fopen, fputchar, fputs, putc, putchar, puts, ferror 

♦include <stdio.h> 

void main() 

{ 

FILE *fp; 
int c; 

fp = fopen( "file", "r" ); 
if( fp != NULL ) { 

while( (c = fgetc( fp )) != EOF ) 

fputc ( c, stdout ); 
fclose ( fp ); 

} 

} 

ISOC 

fputc - All, Linux, RDOS, Netware 
fputwc - All, Linux 
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Synopsis: 

Description: 


Returns: 


See Also: 
Example: 


Classification: 

Systems: 


fputchar, Jputchar, Jputwchar 


♦include <stdio.h> 

int fputchar( int c ) ; 

int _ fputchar ( int c ); 

wint_ t _ fputwchar ( wint_ t c ) ; 

The fputchar function writes the character specified by the argument c to the output stream 
stdout. This function is identical to the put char function. 

The function is equivalent to: 

fputc( c, stdout ); 

The _ fputchar function is identical tofputchar. Use _ fputchar for ANSI naming 
conventions. 

The _ fputwchar function is identical tofputchar except that it converts the wide character 
specified by c to a multibyte character and writes it to the output stream. 

The fputchar function returns the character written or, if a write error occurs, the error indicator is 
set and fputchar returns EOF. 

The _ fputwchar function returns the wide character written or, if a write error occurs, the error 
indicator is set and _ fputwchar returnsWEOF. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 

fopen, fputc, fputs, putc, putchar, puts, ferror 

♦include <stdio.h> 

void main() 

{ 

FILE *fp; 
int c; 

fp = fopen( "file", "r" ); 
if( fp != NULL ) { 

c = fgetc( fp ); 
while ( c != EOF ) { 

_ fputchar( c ); 
c = fgetc( fp ); 

} 

fclose ( fp ); 

} 

} 

WATCOM 

_fputchar conforms to ANSI naming conventions 

fputchar - All, Linux, RDOS, Netware 
_ fputchar - All, Linux, RDOS, Netware 
_ fputwchar - All, Linux 
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fputs, fputws 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdio.h> 

int fputs( const char *buf, FILE *fp ); 

♦include <stdio.h> 

♦include <wchar.h> 

int fputws ( const wchar_ t *buf, FILE *fp ) ; 

The fputs function writes the character string pointed to by buf to the output stream designated by fp. 
The terminating null character is not written. 

The fputws function is identical to fputs except that it converts the wide character string specified 
by buf to a multibyte character string and writes it to the output stream. 

The fputs function returns EOF if an error occurs; otherwise, it returns a non-negative value (the 
number of characters written). The fputws function returns EOF if a write or encoding error occurs; 
otherwise, it returns a non-negative value (the number of characters written). When an error has 
occurred, errno contains a value indicating the type of error that has been detected. 

fopen, fputc, fputchar, putc, putchar, puts, ferror 

♦include <stdio.h> 

void main() 

{ 

FILE *fp; 

char buffer[80]; 

fp = fopen( "file", "r" ); 
if( fp != NULL ) { 

while( fgets( buffer, 80, fp ) != NULL ) 

fputs ( buffer, stdout ); 
fclose ( fp ); 

} 

} 

ISOC 

fputs - All, Linux, RDOS, Netware 
fputws - All, Linux 
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fread 


Synopsis: 

Description: 

Returns: 


See Also: 
Example: 


Classification: 

Systems: 


#include <stdio.h> 
size_ t fread( void *buf, 

size_ t elsize, 
size_ t nelem, 

FILE *fp ); 

The fread function reads nelem elements of elsize bytes each from the file specified by fp into the 
buffer specified by buf. 

The fread function returns the number of complete elements successfully read. This value may be 
less than the requested number of elements. 

The f eof and f error functions can be used to determine whether the end of the file was encountered 
or if an input/output error has occurred. When an error has occurred, errno contains a value 
indicating the type of error that has been detected. 

fopen, feof, ferror 

The following example reads a simple student record containing binary data. The student record is 
described by the struct student_ data declaration. 

♦include <stdio.h> 

struct student_ data { 
int student_ id; 
unsigned char marks[10]; 

} ; 


size_ t read_ data ( FILE *fp, struct student_ data *p ) 

{ 

return! fread( p, sizeof(*p), 1, fp ) ); 

} 

void main() 

{ 

FILE *fp; 

struct student_ data std; 
int i; 

fp = fopen( "file", "r" ); 
if( fp != NULL ) { 

while! read_ data ( fp, &std ) != 0 ) { 

printf( "id=%d ", std.student_ id ); 
for( i = 0; i < 10; i++ ) 

printf! "%3d ", std.marks[ i ] ); 

printf ( "\n" ); 

} 

fclose ( fp ); 

} 

} 

ISOC 

All, Linux, RDOS, Netware 
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free Functions 


Synopsis: 

Description: 


Returns: 
See Also: 

Example: 


Classification: 


♦include <stdlib.h> For ISO C compatibility (free only) 

♦include <malloc.h> Required for other function prototypes 
void free( void *ptr ) ; 

void _ bfree (_segment seg, void_based (void) *ptr ); 

void _ ffree ( void_far *ptr ) ; 

void _ nfree ( void_near *ptr ) ; 

When the value of the argument ptr is NULL, the free function does nothing; otherwise, the free 
function deallocates the memory block located by the argument ptr which points to a memory block 
previously allocated through a call to the appropriate version of calloc, malloc or realloc. After 
the call, the freed block is available for allocation. 


Each function deallocates memory from a particular heap, as listed below: 

Function Heap 

free Depends on data model of the program 

_bfree Based heap specified by seg value 

Jfree Far heap (outside the default data segment) 

jifree Near heap (inside the default data segment) 

In a large data memory model, the free function is equivalent to the _ ffree function; in a small data 
memory model, the free function is equivalent to the _ nfree function. 


The free functions return no value. 


calloc Functions, _ expand Functions.halloc, hfree, malloc Functions, _ msize Functions, 
realloc Functions, sbrk 

♦include <stdio.h> 

♦include <stdlib.h> 

void main() 

{ 

char ^buffer; 

buffer = (char *)malloc( 80 ); 
if( buffer == NULL ) { 

printf( "Unable to allocate memory\n" ); 

} else { 

/* rest of code goes here */ 

free( buffer ); /* deallocate buffer */ 

} 

} 


ISOC 

_bfree is WATCOM 
_ffree is WATCOM 
_nfree is WATCOM 
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free Functions 


Systems: 


free - All, Linux, RDOS, Netware 
_bfree - DOS/16, Windows, OS/2 l.x(all) 

_ ffree - DOS/16, Windows, OS/2 l.x(all) 

_ nfree - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 l.x(MT), 
OS/2-32, Linux, RDOS 
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freed 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <malloc.h> 

unsigned int _ freect ( size_ t size ) ; 

The _ freect function returns the number of times that_ nmalloc (ormalloc in small data models) 
can be called to allocate a item of size bytes. In the tiny, small and medium memory models, the default 
data segment is only extended as needed to satisfy requests for memory allocation. Therefore, you will 
need to call _ nheapgrow in these memory models before calling _freect in order to get a meaningful 
result. 


The _ freect function returns the number of calls as an unsigned integer. 

calloc, _ heapgrow Functions,malloc Functions, _ memavl,_ memmax 

♦include <stdio.h> 

♦include <malloc.h> 


void main() 

1 

int i; 


} 


printf ( "Can allocate %u longs 
_ freect( sizeof(long) 
_ nheapgrow(); 

printf( "Can allocate %u longs 
_ freect( sizeof(long) 
for( i = 1; i < 1000; i++ ) { 

_ nmalloc( sizeof(long) ); 

} 

printf ( "After allocating 1000 
printf ( "Can still allocate %u 
_ freect( sizeof(long) 


before _ nheapgrow\n", 

) ); 

after _ nheapgrow\n", 

) ); 


longs:\n" ); 
longs\n", 

) ); 


produces the following: 

Can allocate 0 longs before _ nheapgrow 
Can allocate 10447 longs after _ nheapgrow 
After allocating 1000 longs: 

Can still allocate 9447 longs 


WATCOM 


All, Linux, RDOS 
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freopen, _wfreopen 


Synopsis: 


Safer C: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


Systems: 


♦include <stdio.h> 

FILE *freopen( const char *filename, 
const char *mode, 

FILE *fp ); 

FILE *_ wfreopen( const wchar_t ^filename, 
const wchar_ t *mode, 

FILE *fp ); 

The Safer C Library extension provides the f reopen_ s function which is a safer alternative to 
f reopen This newer f reopen_ s function is recommended to be used instead of the traditional 
"unsafe" f reopen function. 

The stream located by the fp pointer is closed. The f reopen function opens the file whose name is 
the string pointed to by filename, and associates a stream with it. The stream information is placed in 
the structure located by the //; pointer. 

The argument mode is described in the description of the f open function. 

The _ wfreopen function is a wide-character version off reopen that operates with wide-character 
strings. 

The f reopen function returns a pointer to the object controlling the stream. This pointer must be 
passed as a parameter to subsequent functions for performing operations on the file. If the open 
operation fails, f reopen returns NULL . When an error has occurred, errno contains a value 
indicating the type of error that has been detected. 

_ dos_ openfclose, fcloseall, fdopen, fopen, fopen_ s,freopen_ s,_ fsopen, 

_ grow_ handles^ hdopen,open, _ open_ osfhandlej. popen,sopen 

♦include <stdio.h> 

void main() 

{ 

FILE *fp; 
int c; 

fp = freopen( "file", "r", stdin ); 
if( fp != NULL ) { 

while( (c = fgetcharO) != EOF ) 
fputchar (c); 
fclose ( fp ); 

} 

} 

ISOC 

_wfreopen is WATCOM 

freopen - All, Linux, RDOS, Netware 
_ wfreopen - All, Linux 
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freopen_s, _wfreopen_s 


Synopsis: 


Constraints: 


Description: 


Returns: 


See Also: 


Example: 


♦include <stdio.h> 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

errno_ t freopen_ s ( FILE * restrict * restrict newstreamptr, 

const char * filename, 
const char * restrict mode, 

FILE * restrict stream ); 

errno_ t _ wfreopen_ s ( FILE * restrict * restrict newstreamptr, 

const wchar_ t * restrict filename, 
const wchar_ t * restrict mode, 

FILE * restrict stream ); 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and f reopen_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

None of newstreamptr, mode, and stream shall be a null pointer. If there is a runtime-constraint 
violation, f reopen_ s neither attempts to close any file associated with stream nor attempts to open a 
file. Furthermore, if newstreamptr is not a null pointer, f reopen_ s sets *newstreamptr to the null 
pointer. 

The f reopen_ s function opens the file whose name is the string pointed to by filename and associates 
the stream pointed to by stream with it. The mode argument has the same meaning as in the fopen_s 
function (including the mode’s effect on exclusive access and file permissions). If filename is a null 
pointer.the f reopen_ s function attempts to change the mode of the stream to that specified by mode 
,as if the name of the file currently associated with the stream had been used. It is 
implementation-defined which changes of mode are permitted (if any), and under what circumstances. 
The f reopen_ s function first attempts to close any file that is associated with stream. Failure to 
close the file is ignored. The error and end-of-file indicators for the stream are cleared. If the file was 
opened successfully, then the pointer to FILE pointed to by newstreamptr will be set to the value of 
stream. Otherwise, the pointer to FILE pointed to by newstreamptr will be set to a null pointer. 

The _ wf reopen_ s function is a wide-character version of reopen_ s that operates with 
wide-character strings. 

The f reopen_ s function returns zero if it opened the file. If it did not open the file or there was a 
runtime-constraint violation, f reopen_ s returns a non-zero value. 

_ dos_ openfclose, fcloseall, fdopen, fopen, fopen_ s.freopen, _ fsopen, 

_ grow_ handles^ hdopen.open, _ open_ osfhandle^ popen.sopen 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

void main() 

{ 

errno_ t rc; 

FILE *fp; 

int c; 
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freopen_s, _wfreopen_s 


Classification: 


Systems: 


rc = freopen_ s ( &fp, "file", "r", 
if( rc == 0 ) { 

while ( (c = fgetc( fp )) != EOF 

fputchar(c); 
fclose( fp ) ; 

} 


TR 24731 

_wfreopen_s is WATCOM 

freopen_ s - All, Linux, RDOS, Netware 
_ wfreopen_ s - All, Linux 


stdin ); 

) 
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frexp 

Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 

double frexp( double value, int *exp ); 

The frexp function breaks a floating-point number into a normalized fraction and an integral power of 
2. It stores the integral power of 2 in the int object pointed to by exp. 

The frexp function returns the value of x, such that x is a double with magnitude in the interval 
[0.5,1) or zero, and value equals x times 2 raised to the power *exp. If value is zero, then both parts of 
the result are zero. 

ldexp, modf 

#include <stdio.h> 

♦include <math.h> 

void main() 

{ 

int expon; 
double value; 

value = frexp( 4.25, Sexpon ); 

printf ( "%f %d\n", value, expon ); 
value = frexp( -4.25, Sexpon ); 
printf( "%f %d\n", value, expon ); 

} 

produces the following: 

0.531250 3 
-0.531250 3 

ISOC 

Math 
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fscant, fwscanf 


Synopsis: 

Safer C: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdio.h> 

int fscanf ( FILE *fp, const char *format, ... ); 

♦include <stdio.h> 

♦include <wchar.h> 

int fwscanf( FILE *fp, const wchar_ t *format, ... ); 

The Safer C Library extension provides the f scanf_ s function which is a safer alternative to 
fscanf This newer f scanf_ s function is recommended to be used instead of the traditional "unsafe" 
fscanf function. 

The fscanf function scans input from the file designated by fp under control of the argument format. 
Following the format string is a list of addresses to receive values. The format string is described under 
the description of the scanf function. 

The fwscanf function is identical to fscanf except that it accepts a wide-character string argument 
for format. 

The fscanf function returns EOF if an input failure occurred before any conversion. Otherwise, the 
number of input arguments for which values were successfully scanned and stored is returned. When a 
file input error occurs, the errno global variable may be set. 

cscanf, scanf, sscanf, vcscanf, vfscanf, vscanf, vsscanf 

To scan a date in the form "Saturday April 18 1987": 

♦include <stdio.h> 

void main( void ) 

{ 

int day, year; 

char weekday[10], month[10]; 

FILE *in_ data; 

in_ data = fopen( "file", "r" ); 
if( in_ data != NULL ) { 

fscanf ( in_ data, "%s %s %d %d", 

weekday, month, &day, Syear ); 
printf ( "Weekday=%s Month=%s Day=%d Year=%d\n", 
weekday, month, day, year ); 
fclose ( in_ data ); 

} 

} 

ISO C90 

fwscanf is ISO C95 

fscanf - All, Linux, RDOS, Netware 
fwscanf - All, Linux 
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fscanf_s, fwscanf_s 


Synopsis: 


Constraints: 


Description: 


Returns: 

See Also: 
Example: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

int fscanf_ s ( FILE * restrict stream, 

const char * restrict format, ... ) ; 

♦include <stdio.h> 

♦include <wchar.h> 

int fwscanf_ s ( FILE * restrict stream, 

const wchar_ t * restrict format, ... ) ; 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and f scanf_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither stream nor format shall be a null pointer. Any argument indirected through in order to store 
converted input shall not be a null pointer. 

If there is a runtime-constraint violation, the f scanf_ s function does not attempt to perform further 
input, and it is unspecified to what extent f scanf_ s performed input before discovering the 
runtime-constraint violation. 

The fscanf_ s function is equivalent tofscanf except that the c, s, and [ conversion specifiers 
apply to a pair of arguments (unless assignment suppression is indicated by a *). The first of these 
arguments is the same as for f scanf. That argument is immediately followed in the argument list by 
the second argument, which has type size_ t and gives the number of elements in the array pointed to 
by the first argument of the pair. If the first argument points to a scalar object, it is considered to be an 
array of one element. 

A matching failure occurs if the number of elements in a receiving object is insufficient to hold the 
converted input (including any trailing null character). 

The fwscanf_ s function is identical tof scanf_ s except that it accepts a wide-character string 
argument for format. 

The f scanf_ s function returnsEOF if an input failure occurred before any conversion or if there was 
a runtime-constraint violation. Otherwise, the f scanf_ s function returns the number of input items 
successfully assigned, which can be fewer than provided for, or even zero. 

When a file input error occurs, the errno global variable may be set. 

cscanf, fscanf, scanf, sscanf, vcscanf, vfscanf, vscanf, vsscanf 

To scan a date in the form "Friday August 13 2004": 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

void main( void ) 

{ 

int day, year; 

char weekday[10], month[10]; 

FILE *in_ data; 
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fscanf_s, fwscanf_s 


Classification: 

Systems: 


in_ data = fopen( "file", "r" ); 
if( in_ data != NULL ) { 

fscanf_ s ( in_ data, "%s %s %d %d", 
weekday, sizeof( weekday ), 
month, sizeof( month ), 

&day, Syear ); 

printf_ s ( "Weekday=%s Month=%s Day=%d Year=%d\n", 
weekday, month, day, year ); 
fclose ( in_ data ); 

} 

} 

TR 24731 

fscanf_ s - All, Linux, RDOS, Netware 

fwscanf_ s - All, Linux 
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fseek 


Synopsis: #include <stdio.h> 

int fseek( FILE *fp, long int offset, int where ); 

Description: The fseek function changes the read/write position of the file specified by fp. This position defines 
the character that will be read or written on the next I/O operation on the file. The argument^/? is a file 
pointer returned by f open or f reopen. The argument offset is the position to seek to relative to one 
of three positions specified by the argument where. Allowable values for where are: 

Value Meaning 

SEEK_SET The new file position is computed relative to the start of the file. The value of offset must 
not be negative. 

SEEK_CUR The new file position is computed relative to the current file position. The value of offset 
may be positive, negative or zero. 

SEEK_END The new file position is computed relative to the end of the file. 

The fseek function clears the end-of-file indicator and undoes any effects of the ungetc function on 
the same file. 

The ft ell function can be used to obtain the current position in the file before changing it. The 
position can be restored by using the value returned by ftell in a subsequent call to fseek with the 
where parameter set to SEEK_ SET. 

Returns: The fseek function returns zero if successful, non-zero otherwise. When an error has occurred, 

errno contains a value indicating the type of error that has been detected. 

See Also: fgetpos, fopen, fsetpos, ftell 

Example: The size of a file can be determined by the following example which saves and restores the current 

position of the file. 

♦include <stdio.h> 

long int filesize( FILE *fp ) 

{ 

long int save_pos, size_ of_ file; 

save_ pos = ftell ( fp ) ; 
fseek ( fp, OL, SEEK_ END ) ; 
size_ of_ file = ftell( fp ) ; 
fseek ( fp, save_ pos, SEEK_ SET ); 
return( size_ of_ file ); 

} 
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fseek 


Classification: 

Systems: 


void main() 

{ 

FILE *fp; 

fp = fopen( "file", "r" ); 
if ( fp != NULL ) { 

printf( "File size=%ld\n", filesize( fp ) ); 

fclose( fp ); 

} 

} 

ISOC 

All, Linux, RDOS, Netware 
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fsetpos 


Synopsis: #include <stdio.h> 

int fsetpos ( FILE *fp, fpos_ t *pos ) ; 

Description: The fsetpos function positions the file^p according to the value of the object pointed to by pos, 
which shall be a value returned by an earlier call to the f getpos function on the same file. 

Returns: The fsetpos function returns zero if successful, otherwise, the fsetpos function returns a non-zero 

value. When an error has occurred, errno contains a value indicating the type of error that has been 
detected. 

See Also: fgetpos, fopen, fseek, ftell 

Example: #include <stdio.h> 

void main () 

{ 

FILE *fp; 

fpos_t position; 

auto char buffer[ 80 ]; 

fp = fopen( "file", "r" ); 
if( fp != NULL ) { 

fgetpos( fp, Sposition ); /* get position */ 

fgets( buffer, 80 , fp ); /* read record */ 

fsetpos( fp, Sposition ); /* set position */ 

fgets( buffer, 80 , fp ); /* read same record */ 

fclose ( fp ); 

} 

} 

Classification: ISO C 

Systems: All, Linux, RDOS, Netware 
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fso pen, _wfsopen 


Synopsis: #include <stdio.h> 

FILE *_fsopen( const char *filename, 

const char *mode, int share ); 

FILE *_ wfsopen( const wchar_t ^filename, 

const wchar_ t *mode, int share ); 

Description: The _ f sopen function opens the file whose name is the string pointed to by filename, and associates a 
stream with it. The arguments mode and share control shared reading or writing. The argument mode 
points to a string beginning with one of the following sequences: 

Mode Meaning 

"r" open file for reading; use default file translation 

"w" create file for writing, or truncate to zero length; use default file translation 

"a" append: open text file or create for writing at end-of-file; use default file translation 

"rh" open binary file for reading 

"rt" open text file for reading 

"wb " create binary file for writing, or truncate to zero length 

"wt" create text file for writing, or truncate to zero length 

"ab " append; open binary file or create for writing at end-of-file 

"at" append; open text file or create for writing at end-of-file 

"r+" open file for update (reading and/or writing); use default file translation 

"w+" create file for update, or truncate to zero length; use default file translation 

"a+" append; open file or create for update, writing at end-of-file; use default file translation 

"r+b", "rb+" open binary file for update (reading and/or writing) 

"r+t", "rt+" open text file for update (reading and/or writing) 

"w+b", "wb+" create binary file for update, or truncate to zero length 

"w+t", "wt+" create text file for update, or truncate to zero length 

"a+b", "ab+ " append; open binary file or create for update, writing at end-of-file 

"a+t", "at+" append; open text file or create for update, writing at end-of-file 

When default file translation is specified, the value of the global variable _ fmode establishes whether 
the file is to treated as a binary or a text file. Unless this value is changed by the program, the default 
will be text mode. 
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fsopen, _wfsopen 


Returns: 


See Also: 


Example: 


Opening a file with read mode (' r' as the first character in the mode argument) fails if the file does not 
exist or it cannot be read. Opening a file with append mode ('a' as the first character in the mode 
argument) causes all subsequent writes to the file to be forced to the current end-of-file, regardless of 
previous calls to the f seek function. When a file is opened with update mode (' +' as the second or 
third character of the mode argument), both input and output may be performed on the associated 
stream. 


When a stream is opened in update mode, both reading and writing may be performed. However, 
writing may not be followed by reading without an intervening call to the f f lush function or to a file 
positioning function (f seek , f setpos , rewind). Similarly, reading may not be followed by 
writing without an intervening call to a file positioning function, unless the read resulted in end-of-file. 

The shared access for the file, share , is established by a combination of bits defined in the <share . h> 
header file. The following values may be set: 


Value 


Meaning 


SHJCOMPAT 

SH_DENYRW 

SH_DENYWR 

SH_DENYRD 

SH_DENYNO 


Set compatibility mode. 

Prevent read or write access to the file. 
Prevent write access of the file. 

Prevent read access to the file. 

Permit both read and write access to the file. 


You should consult the technical documentation for the DOS system that you are using for more 
detailed information about these sharing modes. 

The _ wf sopen function is a wide-character version of_ fsopen that operates with wide-character 
strings. 

The _ fsopen function returns a pointer to the object controlling the stream. This pointer must be 
passed as a parameter to subsequent functions for performing operations on the file. If the open 
operation fails, _ fsopen retumsNULL . When an error has occurred, errno contains a value 
indicating the type of error that has been detected. 

_ dos_ openfclose, fcloseall, fdopen, fopen, freopen, _ grow_ handles^ hdopen, 
open, _ open_ osfhandlej. popen,sopen 

♦include <stdio.h> 

♦include <share.h> 

void main() 

{ 

FILE *fp; 

/* 

open a file and prevent others from writing to it 

*/ 

fp = _fsopen( "report.dat", "w", SH_ DENYWR ); 
if( fp != NULL ) { 

/* rest of code goes here */ 
fclose ( fp ); 

} 

} 
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fso pen, _wfsopen 


Classification: WATCOM 

Systems: _ fsopen - All, Linux, RDOS, Netware 

_ wfsopen - All, Linux 
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fstat, _fstat, _fstati64, _wfstat, _wfstati64 

Synopsis: #include <sys/types .h> 

♦include <sys/stat.h> 

int fstat( int handle, struct stat *buf ); 

int _ fstat( int handle, struct stat *buf ); 

int _ fstati64( int handle, struct _ stati64 *buf ); 

int _ wfstat ( int handle, struct _ stat *buf ); 

int _wfstati64( int handle, struct _ stati64 *buf ); 

Description: The fstat functions obtain information about an open file whose file handle is handle. This 
information is placed in the structure located at the address indicated by huf. 

The file <sys/stat. h> contains definitions for the structure stat. 

Field Type/Meaning 

st_dev (dev_t) the disk drive the file resides on 

st_ino (ino_t) this inode’s number (not used for DOS) 

st_mode (unsigned short ) file mode 

st_nlink (short ) number of hard links 

st_uid (unsigned long) user-id (always ’root’ for DOS) 

st_gid (short) group-id (always ’root’ for DOS) 

st_rdev (dev_t) this should be the device type but it is the same as st_dev for the time being 

st_size (off_t) total file size 

st_atime (time_t) this should be the file "last accessed" time if the file system supports it 

stjntime (time_t) the file "last modified" time 

st_ctime (time_t) this should be the file "last status change" time if the file system supports it 

The following fields are Netware only: 
st_btime (time_t) the file "last archived" time 

st_attr (unsigned long) the file’s attributes 

st_archivedID (unsigned long) the user/object ID that last archived file 

st_updatedID (unsigned long) the user/object ID that last updated file 

st_inheritedRightsMask (unsigned short) the inherited rights mask 
st_originatingNameSpace (unsigned char) the originating name space 
The structure _ stati64 differs fronts tat in the following way: 
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fstat, _fstat, _fstati64, _wfstat, _wfstati64 


st_size (_int64) total file size (as a 64-bit value) 

At least the following macros are defined in the <sys/stat. h> header file. 

Macro Meaning 

SJSFIFO(m) Test for FIFO. 

S_ISCHR(m) Test for character special file. 

S_ISDIR(m) Test for directory file. 

S_ISBLK(m) Test for block special file. 

S_ISREG(m) Test for regular file. 

The value m supplied to the macros is the value of the st_ mode field of astat structure. The macro 
evaluates to a non-zero value if the test is true and zero if the test is false. 

The following bits are encoded within the st_ mode field of astat structure. 

Mask Owner Permissions 

S_IRWXU Read, write, search (if a directory), or execute (otherwise) 

S_IRUSR Read permission bit 

S_IWUSR Write permission bit 

S_IXUSR Search/execute permission bit 

S_IREAD == S_ IRUSR (for Microsoft compatibility) 

S_IWRITE == S_ IWUSR (for Microsoft compatibility) 

S_IEXEC == S_ IXUSR (for Microsoft compatibility) 

S_ IRWXU is the bitwise inclusive OR ofS_ IRUSR,S_ IWUSR, andS_ IXUSR. 

Mask Group Permissions (same as owner’s on DOS, OS/2 or Windows) 

S_IRWXG Read, write, search (if a directory), or execute (otherwise) 

S_IRGRP Read permission bit 

S_IWGRP Write permission bit 

S_IXGRP Search/execute permission bit 

S_ IRWXG is the bitwise inclusive OR ofS_ IRGRP,S_ IWGRP, andS_ IXGRP. 

Mask Other Permissions (same as owner’s on DOS, OS/2 or Windows) 

S_IRWXO Read, write, search (if a directory), or execute (otherwise) 

S_IROTH Read permission bit 

S_IWOTH Write permission bit 

S_IXOTH Search/execute permission bit 

S_ IRWXO is the bitwise inclusive OR ofS_ IROTH,S_ IWOTH, andS_ IXOTH. 
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fstat, _fstat, _fstati64, _wfstat, _wfstati64 


Mask Meaning 

S_ISUID (Not supported by DOS, OS/2 or Windows) Set user ID on execution. The 

process’s effective user ID shall be set to that of the owner of the file when the file 
is run as a program. On a regular file, this bit should be cleared on any write. 
S_ISGID (Not supported by DOS, OS/2 or Windows) Set group ID on execution. Set 

effective group ID on the process to the file’s group when the file is run as a 
program. On a regular file, this bit should be cleared on any write. 

The _ fstat function is identical tof stat. Use _ fstat for ANSI naming conventions. 

The _ f stati64,_ wf stat, and_ wf stati64 functions differ fromf stat in the type of structure 
that they are asked to fill in. The _ wf stat and_ wf stati64 functions deal with wide character 
strings. The differences in the structures are described above. 

Returns: All forms of the fstat function return zero when the information is successfully obtained. Otherwise, 

-1 is returned. 

Errors: When an error has occurred, errno contains a value indicating the type of error that has been detected. 

Constant Meaning 

EBADF The handle argument is not a valid file handle. 

See Also: creat, dup, dup2, open, sopen, stat 

Example: ((include <stdio.h> 

♦include <sys/types.h> 

♦include <sys/stat.h> 

♦include <fcntl.h> 

♦include <io.h> 

void main() 

{ 

int handle, rc; 
struct stat buf; 

handle = open ( "file", 0_ RDONLY ); 
if( handle != -1 ) { 

rc = fstat ( handle, &buf ); 
if ( rc != -1 ) 

printf ( "File size = %d\n", buf.st_ size ); 
close ( handle ); 

} 

} 

Classification: POSIX 

_fstat conforms to ANSI naming conventions 
_fstati64 is WATCOM 
_wfstat is WATCOM 
_wfstati64 is WATCOM 

Systems: fstat - All, Linux, RDOS, Netware 

_ fstat - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ fstati64 - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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wfstat - 
wfstati64 


fstat, _fstat, Jstati64, _wfstat, _wfstati64 


DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
- DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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fsync 


Synopsis: 

Description: 


Returns: 

Errors: 


See Also: 
Example: 


♦include <io.h> 
int fsync( int fd ); 


The fsync function writes to disk all the currently queued data for the open file specified by fd. All 
necessary file system information required to retrieve the data is also written to disk. The file access 
times are also updated. 

The fsync function is used when you wish to ensure that both the file data and file system information 
required to recover the complete file have been written to the disk. 

The fsync function does not return until the transfer is completed. 

The fsync function returns zero if successful. Otherwise, it returns -1 and errno is set to indicate the 
error. If the fsync function fails, outstanding i/o operations are not guaranteed to have been 
completed. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 


Constant 

EBADF 

EINVAL 

EIO 

ENOSYS 


Meaning 

Thcfd argument is not a valid file handle. 

Synchronized i/o is not supported for this file. 

A physical I/O error occurred (e.g., a bad block). The precise meaning is device 
dependent. 

The fsync function is not supported. 


fstat, open, stat, write 


/* 

★ 

*/ 


Write a file 


♦include 

♦include 

♦include 

♦include 

♦include 


<fcntl.h> 
<stdio.h> 
<stdlib.h> 
<string.h> 
<io.h> 


and make sure it 


is on disk. 


char buf[512]; 


void main() 

{ 

int handle; 
int i; 


handle = creat ( "file", S_ IWRITE | S_ IREAD ); 
if( handle == -1 ) { 

perror ( "Error creating file" ); 
exit ( EXIT_ FAILURE ) ; 


330 Library Functions and Macros 




fsync 


for( i = 0; i < 255; ++i ) { 

memset( buf, i, sizeof( buf ) ); 

if( write( handle, buf, sizeof(buf) ) 

perror( "Error writing file" ); 
exit( EXIT_ FAILURE ); 

} 

} 

if( fsync ( handle ) == -1 ) { 

perror( "Error sync'ing file" ); 
exit( EXIT_ FAILURE ); 

} 

close ( handle ); 
exit( EXIT_ SUCCESS ); 

} 

Classification: POSIX 1003.4 
Systems: All, Linux, RDOS, Netware 


! = sizeof(buf) ) { 


Library Functions and Macros 331 




ftell 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdio.h> 

long int ftell( FILE *fp ); 

The ftell function returns the current read/write position of the file specified by fp. This position 
defines the character that will be read or written by the next I/O operation on the file. The value 
returned by ftell can be used in a subsequent call to f seek to set the file to the same position. 

The ftell function returns the current read/write position of the file specified by fp. When an error is 
detected, -1L is returned. When an error has occurred, errno contains a value indicating the type of 
error that has been detected. 

fgetpos, fopen, fsetpos, fseek 

♦include <stdio.h> 

long int filesize( FILE *fp ) 

{ 

long int save_ pos, size_ of_ file; 

save_ pos = ftell ( fp ) ; 
fseek ( fp, OL, SEEK_ END ) ; 
size_ of_ file = ftell( fp ) ; 
f seek ( fp, save_ pos, SEEK_ SET ); 
return ( size_ of_ file ) ; 

} 

void main() 

{ 

FILE *fp; 

fp = fopen( "file", "r" ); 
if( fp != NULL ) { 

printf( "File size=%ld\n", filesize( fp ) ); 

fclose( fp ); 

} 

} 

ISOC 

All, Linux, RDOS, Netware 
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ftime 


Synopsis: 


Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <sys/timeb.h> 

int ftime( struct timeb *timeptr ); 

struct timeb { 

time_t time; /* time in seconds since Jan 1, 1970 UTC */ 
unsigned short millitm; /* milliseconds */ 
short timezone; /* difference in minutes from UTC */ 
short dstflag; /* nonzero if in daylight savings time */ 

} ; 


The ftime function gets the current time and stores it in the structure pointed to by timeptr. 

The ftime function fills in the fields of the structure pointed to by timeptr. The ftime function 
returns -1 if not successful, and no useful value otherwise. 

asctime Functions, asctime_ s.clock, ctime Functions, ctime_ s,dif ftime, gmtime, 
gmtime_ s.localtime, localtime_ s,mktime, strftime, time, tzset 

♦include <stdio.h> 

♦include <time.h> 

♦include <sys/timeb.h> 

void main() 

1 

struct timeb timebuf; 
char *tod; 

ftime( Stimebuf ) ; 

tod = ctime( Stimebuf.time ); 

printf ( "The time is %.19s.%hu %s", 

tod, timebuf.millitm, &tod[20] ); 

} 

produces the following: 

The time is Tue Dec 25 15:58:42.870 1990 

WATCOM 

All, Linux, RDOS 
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fullpath, _wfullpath 


Synopsis: #include <stdlib.h> 

char *_ fullpath( char *buffer, 

const char *path, 
size_ t size ); 

wchar_ t *_wfullpath( wchar_ t *buffer , 

const wchar_ t *path, 
size_ t size ) ; 

Description: The _ fullpath function returns the full pathname of the file specification in path in the specified 
buffer buffer of length size. 

The maximum size that might be required for buffer is _ MAX_ PATH. If the buffer provided is too 
small, NULL is returned and errno is set. 

If buffer is NULL then a buffer of size _ MAX_ PATH is allocated usingialloc. This buffer may be 
freed using the free function. 

If path is NULL or points to a null string ("") then the current working directory is returned in buffer. 

The _ wfullpath function is a wide-character version of_ fullpath that operates with 
wide-character strings. 

Returns: The _ fullpath function returns a pointer to the full path specification if no error occurred. 

Otherwise, NULL is returned. 

Errors: When an error has occurred, errno contains a value indicating the type of error that has been detected. 

Constant Meaning 

ENOENT The current working directory could not be obtained. 

ENOMEM The buffer could not be allocated. 

ERANGE The buffer passed was too small. 

See Also: _ makepath^ splitpath 

Example: #include <stdio.h> 

#include <stdlib.h> 

void main( int argc, char *argv[] ) 

1 

int i; 

char buf f [ PATH_ MAX ]; 

for( i = 1; i < argc; ++i ) { 

puts( argv[i] ) ; 

if ( _ fullpath( buff, argv[i], PATH_ MAX ) ) { 

puts( buff ) ; 

} else { 

puts( "FAIL!" ); 

} 

} 

} 
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full path, _wfullpath 


Classification: WATCOM 

Systems: _ fullpath - All, Linux, RDOS, Netware 

_ wfullpath - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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fwide 


Synopsis: #include <stdio.h> 

♦include <wchar.h> 

int fwide( FILE *fp, int mode ); 

Description: The fwide function determines the orientation of the stream pointed to by fp. If mode is greater than 
zero, the function first attempts to make the stream wide oriented. If mode is less than zero, the 
function first attempts to make the stream byte oriented. Otherwise, mode is zero and the fwide 
function does not alter the orientation of the stream. 

Returns: The fwide function returns a value greater than zero if, after the call, the stream has wide orientation, a 

value less than zero if the stream has byte orientation, or zero if the stream has no orientation. 

See Also: f open, f reopen 

Example: #include <stdio.h> 

♦include <wchar.h> 

void main( void ) 

{ 

FILE *fp; 

int mode; 

fp = fopen( "file", "r" ); 
if( fp != NULL ) { 

mode = fwide( fp, -33 ) ; 
printf( "orientation: %s\n", 
mode > 0 ? "wide" : 
mode < 0 ? "byte" : "none" ); 

} 

} 

produces the following: 
orientation: byte 

Classification: ISO C95 
Systems: All, Linux, RDOS 
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fwrite 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <stdio.h> 
size_ t fwrite( const void *buf, 
size_ t elsize, 
size_ t nelem, 

FILE *fp ); 

The fwrite function writes nelem elements of elsize bytes each to the file specified by //;. 

The fwrite function returns the number of complete elements successfully written. This value will be 
less than the requested number of elements only if a write error occurs. When an error has occurred, 
errno contains a value indicating the type of error that has been detected. 

ferror, fopen 

♦include <stdio.h> 

struct student_ data { 
int student_ id; 
unsigned char marks[10]; 

} ; 


void main() 

{ 

FILE *fp; 

struct student_ data std; 
int i; 

fp = fopen( "file", "w" ); 
if( fp != NULL ) { 

std.student_ id = 1001; 
for( i = 0; i < 10; i++ ) 

std.marks[ i ] = (unsigned char) (85 + i); 

/* write student record with marks */ 
i = fwrite( &std, sizeof(std), 1, fp ); 
printf( "%d record written\n", i ); 
fclose ( fp ); 

} 

} 

ISOC 

All, Linux, RDOS, Netware 
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gcvt, _gcvt, _wgcvt 


Synopsis: 


Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <stdlib.h> 
char *gcvt( double value, 
int ndigits, 
char *buffer ); 
char *_ gcvt( double value, 
int ndigits, 
char *buffer ); 

wchar_ t *_ wgcvt( double value, 
int ndigits, 
wchar_ t ^buffer ); 

The gcvt function converts the floating-point number value into a character string and stores the result 
in buffer. The parameter ndigits specifies the number of significant digits desired. The converted 
number will be rounded to this position. 

If the exponent of the number is less than -4 or is greater than or equal to the number of significant 
digits wanted, then the number is converted into E-format, otherwise the number is formatted using 
F-format. 

The _ gcvt function is identical togcvt. Use _ gcvt for ANSI naming conventions. 

The _ wgcvt function is a wide-character version ofgcvt. It produces a wide-character string. 

The gcvt function returns a pointer to the string of digits. 

ecvt, fcvt, printf 

♦include <stdio.h> 

♦include <stdlib.h> 

void main() 

{ 

char buffer [80]; 

printf ( "%s\n", gcvt( -123.456789, 5, buffer ) ); 
printf ( "%s\n", gcvt( 123.456789E+12, 5, buffer ) ); 

} 

produces the following: 

-123.46 
1.2346E+014 

WATCOM 

_gcvt conforms to ANSI naming conventions 

gcvt - Math 
_ gcvt - Math 
_ wgcvt - Math 
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getactivepage 


Synopsis: #include <graph.h> 

short _ FAR _ getactivepage( void ) ; 

Description: The _ getactivepage function returns the number of the currently selected active graphics page. 

Only some combinations of video modes and hardware allow multiple pages of graphics to exist. When 
multiple pages are supported, the active page may differ from the visual page. The graphics 
information in the visual page determines what is displayed upon the screen. Animation may be 
accomplished by alternating the visual page. A graphics page can be constructed without affecting the 
screen by setting the active page to be different than the visual page. 

The number of available video pages can be determined by using the _ getvideoconf ig function. 
The default video page is 0. 

Returns: The _ getactivepage function returns the number of the currently selected active graphics page. 

See Also: _ setactivepage,_ setvisualpage,_ getvisualpage,_ getvideoconf ig 

Example: #include <conio.h> 

♦include <graph.h> 

main() 

{ 

int old_ apage; 
int old_ vpage; 

_ setvideomode( _ HRES16COLOR ); 
old_ apage = _ getactivepage () ; 
old_ vpage = _ getvisualpage () ; 

/* draw an ellipse on page 0 */ 

_ setactivepage( 0 ); 

_ setvisualpage( 0 ); 

_ellipse! _ GFILLINTERIOR, 100, 50, 540, 150 ); 

/* draw a rectangle on page 1 */ 

_ setactivepage( 1 ); 

_ rectangle! _ GFILLINTERIOR, 100, 50, 540, 150 ); 
getch(); 

/* display page 1 */ 

_ setvisualpage( 1 ); 
getch() ; 

_ setactivepage ( old_ apage ); 

_ setvisualpage ( old_ vpage ) ; 

_ setvideomode( _ DEFAULTMODE ); 

} 

Classification: PC Graphics 
Systems: DOS 
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getarcinfo 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


#include <graph.h> 

short _ FAR _ getarcinfo ( struct xycoord _ FAR *start_pt, 

struct xycoord _ FAR *end_pt, 
struct xycoord _ FAR *inside_pt ); 

The _ getarcinfo function returns information about the arc most recently drawn by the_ arc or 
_ pie functions. The arguments start_pt and end_pt are set to contain the endpoints of the arc. The 
argument inside_pt will contain the coordinates of a point within the pie. The points are all specified in 
the view coordinate system. 

The endpoints of the arc can be used to connect other lines to the arc. The interior point can be used to 
fill the pie. 

The _ getarcinfo function returns a non-zero value when successful. If the previous arc or pie was 
not successfully drawn, zero is returned. 

_ arc,_ pie 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

struct xycoord start_pt, end_pt, inside_pt; 

_ setvideomode( _ VRES16C0L0R ); 

_ arc( 120, 90, 520, 390, 520, 90, 120, 390 ); 

_ getarcinfo ( &start_pt, &end_pt, &inside_pt ); 

_ moveto ( start_ pt. xcoord, start_ pt. ycoord ); 

_ lineto ( end_ pt. xcoord, end_ pt. ycoord ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ); 

} 

produces the following: 
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getarcinfo 



Classification: PC Graphics 
Systems: DOS 
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getbkcolor 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <graph.h> 

long _ FAR _ getbkcolor ( void ) ; 

The _ getbkcolor function returns the current background color. In text modes, the background 
color controls the area behind each individual character. In graphics modes, the background refers to 
the entire screen. The default background color is 0. 

The _ getbkcolor function returns the current background color. 

_ setbkcolor,^ remappalette 


♦include <conio.h> 

♦include <graph.h> 

long colors! 16 ] = { 

_ BLACK, _ BLUE, _ GREEN, _ CYAN, 

_ RED, _ MAGENTA, _ BROWN, _ WHITE, 

_ GRAY, _ LIGHTBLUE, _ LIGHTGREEN, _ LIGHTCYAN, 

_ LIGHTRED, _ LIGHTMAGENTA, _ YELLOW, _ BRIGHTWHITE 

} ; 

main () 

{ 

long old_ bk; 
int bk; 

_ setvideomode ( _VRES16COLOR ); 

old_ bk = _ getbkcolor () ; 

for( bk = 0; bk < 16; ++bk ) { 

_ setbkcolor( colors[ bk ] ); 

getch (); 

} 

_ setbkcolor( old_ bk ) ; 

_setvideomode( _DEFAULTMODE ) ; 

} 

PC Graphics 
DOS 
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getc, getwc 


Synopsis: 

Description: 


Returns: 


See Also: 
Example: 


Classification: 

Systems: 


♦include <stdio.h> 
int getc( FILE *fp ); 

♦include <stdio.h> 

♦include <wchar.h> 
wint_ t getwc( FILE *fp ); 

The getc function gets the next character from the file designated by fp. The character is returned as 
an int value. The getc function is equivalent to fgetc, except that it may be implemented as a 
macro. 

The getwc function is identical to getc except that it gets the next multibyte character (if present) 
from the input stream pointed to by fp and converts it to a wide character. 

The getc function returns the next character from the input stream pointed to by fp. If the stream is at 
end-of-file, the end-of-file indicator is set and getc returns EOF. If a read error occurs, the error 
indicator is set and getc returns EOF. 

The getwc function returns the next wide character from the input stream pointed to by fp. If the 
stream is at end-of-file, the end-of-file indicator is set and getwc returns WEOF. If a read error occurs, 
the error indicator is set and getwc returns WEOF. If an encoding error occurs, errno is set to 
EILSEQ and getwc returns WEOF. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 

fgetc, fgetchar, fgets, fopen, getchar, gets, ungetc 

♦include <stdio.h> 

void main() 

{ 

FILE *fp; 
int c; 

fp = fopen( "file", "r" ); 
if( fp != NULL ) { 

while( (c = getc( fp )) != EOF ) 

putchar(c); 
fclose( fp ) ; 

} 

} 

ISOC 

getc - All, Linux, RDOS, Netware 
getwc - All, Linux 
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getch 


Synopsis: #include <conio.h> 

int getch( void ) ; 

Description: The getch function obtains the next available keystroke from the console. Nothing is echoed on the 
screen (the function getche will echo the keystroke, if possible). When no keystroke is available, the 
function waits until a key is depressed. 

The kbhit function can be used to determine if a keystroke is available. 

Returns: A value of EOF is returned when an error is detected; otherwise the getch function returns the value 

of the keystroke (or character). 

When the keystroke represents an extended function key (for example, a function key, a 
cursor-movement key or the ALT key with a letter or a digit), zero is returned and the next call to 
getch returns a value for the extended function. 

See Also: getche, kbhit, putch, ungetch 

Example: ((include <stdio.h> 

((include <conio.h> 

void main() 

{ 

int c; 

printf( "Press any key\n" ) ; 
c = getch(); 

printf( "You pressed %c(%d)\n", c, c ) ; 

} 

Classification: WATCOM 

Systems: All, Linux, RDOS, Netware 
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getchar, getwchar 


Synopsis: 

Description: 

Returns: 


See Also: 
Example: 


Classification: 

Systems: 


♦include <stdio.h> 
int getchar( void ) ; 

♦include <wchar.h> 
wint_ t getwchar ( void ) ; 

The getchar function is equivalent to getc with the argument stdin. 

The getwchar function is similar to getchar except that it is equivalent to getwc with the 
argument stdin. 

The getchar function returns the next character from the input stream pointed to by stdin. If the 
stream is at end-of-file, the end-of-file indicator is set and getchar returns EOF. If a read error 
occurs, the error indicator is set and getchar returns EOF. 

The getwchar function returns the next wide character from the input stream pointed to by stdin. 

If the stream is at end-of-file, the end-of-file indicator is set and getwchar returns WEOF. If a read 
error occurs, the error indicator is set and getwchar returns WEOF. If an encoding error occurs, 
errno is set to EILSEQ and getwchar returns WEOF. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 

fgetc, fgetchar, fgets, fopen, getc, gets, ungetc 

♦include <stdio.h> 

void main() 

{ 

FILE *fp; 
int c; 

fp = freopen( "file", "r", stdin ); 
while( (c = getchar()) != EOF ) 

putchar(c); 
fclose ( fp ); 

} 

ISOC 

getchar - All, Linux, RDOS, Netware 
getwchar - All, Linux 
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getche 


Synopsis: #include <conio.h> 

int getche( void ) ; 

Description: The getche function obtains the next available keystroke from the console. The function will wait 
until a keystroke is available. That character is echoed on the screen at the position of the cursor (use 
getch when it is not desired to echo the keystroke). 

The kbhit function can be used to determine if a keystroke is available. 

Returns: A value of EOF is returned when an error is detected; otherwise, the getche function returns the value 

of the keystroke (or character). 

When the keystroke represents an extended function key (for example, a function key, a 
cursor-movement key or the ALT key with a letter or a digit), zero is returned and the next call to 
getche returns a value for the extended function. 

See Also: getch, kbhit, putch, ungetch 

Example: ((include <stdio.h> 

((include <conio.h> 

void main() 

{ 

int c; 

printf( "Press any key\n" ) ; 
c = getche(); 

printf( "You pressed %c(%d)\n", c, c ) ; 

} 

Classification: WATCOM 

Systems: All, Linux, RDOS, Netware 
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getcliprgn 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <graph.h> 

void _ FAR _ getcliprgn ( short _ FAR *xl, short _ FAR *yl, 

short _ FAR *x2, short _ FAR *y2 ); 

The _ getcliprgn function returns the location of the current clipping region. A clipping region is 
defined with the _ setcliprgn or_ setviewport functions. By default, the clipping region is the 
entire screen. 

The current clipping region is a rectangular area of the screen to which graphics output is restricted. 

The top left corner of the clipping region is placed in the arguments (xl,yl) . The bottom right 
corner of the clipping region is placed in (x2, y 2) . 

The _ getcliprgn function returns the location of the current clipping region. 

_ setcliprgn^ setviewport 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

short xl, yl, x2, y2; 

_ setvideomode( _ VRES16C0L0R ); 

_ getcliprgn! &xl, &yl, &x2, &y2 ); 

_ setcliprgn! 130, 100, 510, 380 ); 

_ ellipse! _ GBORDER, 120, 90, 520, 390 ); 
getch(); 

_ setcliprgn! xl, yl, x2, y2 ); 

_ setvideomode( _DEFAULTMODE ) ; 

} 

PC Graphics 
DOS 
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getcmd 


Synopsis: 

Description: 


Returns: 
See Also: 

Example: 


Classification: 

Systems: 


#include <process.h> 

char *getcmd( char *cmd_ line ) ; 

The getcmd function causes the command line information, with the program name removed, to be 
copied to cmd_line. The information is terminated with a null character. This provides a method of 
obtaining the original parameters to a program unchanged (with the white space intact). 

This information can also be obtained by examining the vector of program parameters passed to the 
main function in the program. 

The address of the target cmd_line is returned. 

abort, atexit, _ bgetcmd,exec. . ., exit, _ Exit,_ exit,getenv, main, onexit, 
putenv, spawn. . system 

Suppose a program were invoked with the command line 

myprog arg-1 ( my stuff ) here 

where that program contains 

♦include <stdio.h> 

♦include <process.h> 

void main() 

{ 

char cmds[128]; 

printf ( "%s\n", getcmd( cmds ) ); 

} 

produces the following: 

arg-1 ( my stuff ) here 
WATCOM 

All, Linux, RDOS, Netware 
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getcolor 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <graph.h> 

short _ FAR _ getcolor ( void ) ; 

The _ getcolor function returns the pixel value for the current color. This is the color used for 
displaying graphics output. The default color value is one less than the maximum number of colors in 
the current video mode. 

The _ getcolor function returns the pixel value for the current color. 

_ setcolor 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

int col, old_ col; 

_ setvideomode( _ VRES16C0L0R ); 
old_ col = _ getcolor (); 
for( col = 0; col < 16; ++col ) { 

_ setcolor( col ) ; 

_ rectangle( _ GFILLINTERIOR, 100, 100, 540, 380 ); 
getch (); 

} 

_ setcolor ( old_ col ); 

_ setvideomode( _ DEFAULTMODE ); 

} 

PC Graphics 

DOS 


Library Functions and Macros 349 




getcurrentposition Functions 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <graph.h> 

struct xycoord _ FAR _ getcurrentposition( void ) ; 

struct _ wxycoord _ FAR _ getcurrentposition_ w ( void ); 

The _ getcurrentposition functions return the current output position for graphics. The 
_ getcurrentposition function returns the point in view coordinates. The 
_ getcurrentposition_ w function returns the point in window coordinates. 

The current position defaults to the origin, (0,0) , when a new video mode is selected. It is changed 
by successful calls to the _ arc^_ moveto and_ lineto functions as well as the_ setviewport 
function. 

Note that the output position for graphics output differs from that for text output. The output position 
for text output can be set by use of the _ settextposition function. 

The _ getcurrentposition functions return the current output position for graphics. 

_ moveto^ settextposition 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

struct xycoord old_pos; 

_ setvideomode( _ VRES16COLOR ); 
old_ pos = _ getcurrentposition () ; 

_ moveto( 100, 100 ) ; 

_ lineto( 540, 100 ); 

_ lineto( 320, 380 ) ; 

_ lineto( 100, 100 ) ; 

_ moveto ( old_ pos . xcoord, old_ pos . ycoord ); 
getch (); 

_ setvideomode( _ DEFAULTMODE ); 

} 

PC Graphics 

_ getcurrentposition - DOS 
_ getcurrentposition_ w - DOS 
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getcwd, _wgetcwd 


Synopsis: 

Description: 


Returns: 

Errors: 


See Also: 
Example: 


#include <direct.h> 

char *getcwd( char *buffer, size_ t maxlen ); 

wchar_ t *_wgetcwd( wchar_ t *buffer, size_ t maxlen ); 


The getcwd function returns the name of the current working directory. The buffer address is either 
NULL or is the location at which a string containing the name of the current working directory is placed. 
In the latter case, the value of maxlen is the length in characters (including the terminating null 
character) which can be be used to store this name. An error occurs if the length of the path (including 
the terminating null character) exceeds maxlen. 

The maximum size that might be required for buffer is PATH_ MAX + 1 bytes. 

Extension: When buffer has a value of NULL, a string is allocated using malloc to contain the name 
of the current working directory. This string may be freed using the free function. 

The _ wgetcwd function is a wide-character version ofgetcwd that operates with wide-character 
strings. The maxlen is the length in wide-characters (wchar_t). 

The getcwd function returns the address of the string containing the name of the current working 
directory, unless an error occurs, in which case NULL is returned. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 


Constant 

EINVAL 

ENOMEM 

ERANGE 


Meaning 

The argument maxlen is negative. 

Not enough memory to allocate a buffer. 

The buffer is too small (specified by maxlen) to contain the name of the current 
working directory. 


chdir, chmod, _ getdcwdjnkdir, rmdir 


♦include <stdio.h> 

♦include <stdlib.h> 

♦include <direct.h> 

void main() 

{ 

char *cwd; 

cwd = getcwd( NULL, 0 ); 
if( cwd != NULL ) { 

printf( "My working directory is %s\n", cwd ); 
free( cwd ); 

} 

} 

produces the following: 

My working directory is C:\PROJECT\C 
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getcwd, _wgetcwd 


Classification: POSIX 1003.1 with extensions 
_wgetcwd is WATCOM 

Systems: getcwd - All, Linux, RDOS, Netware 

_ wgetcwd - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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getdcwd, _wgetdcwd 


Synopsis: 

Description: 


Returns: 

Errors: 


See Also: 
Example: 


#include <direct.h> 

char *_ getdcwd( int drive, char *buffer, size_ t maxlen ); 
wchar_ t *_wgetdcwd( int drive, wchar_ t *buffer, size_ t maxlen ); 


The _ getdcwd function gets the full path of the current working directory on the specified drive. The 
drive argument specifies the drive (0 = default drive, 1 = A, 2 = B, etc.). The buffer address is either 
NULL or is the location at which a string containing the name of the current working directory is placed. 
In the latter case, the value of maxlen is the length in characters (including the terminating null 
character) which can be be used to store this name. An error occurs if the length of the path (including 
the terminating null character) exceeds maxlen. 

The maximum size that might be required for buffer is PATH_ MAX + 1 bytes. 

When buffer has a value of NULL, a string is allocated using malloc to contain the name of the 
current working directory. This string may be freed using the free function. 

The _ wgetdcwd function is a wide-character version of_ getdcwd that operates with wide-character 
strings. The maxlen is the length in wide-characters (wchar_t). 

The _ getdcwd function returns the address of the string containing the name of the current working 
directory on the specified drive, unless an error occurs, in which case NULL is returned. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 


Constant 

ENODEV 

ENOMEM 

ERANGE 


Meaning 

The drive cannot be accessed. 

Not enough memory to allocate a buffer. 

The buffer is too small (specified by size) to contain the name of the current 
working directory. 


chdir, chmod, getcwd, mkdir, rmdir 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <direct.h> 

void main() 

{ 

char *cwd; 

cwd = _ getdcwd ( 3, NULL, 0 ); 
if( cwd != NULL ) { 

printf( "The current directory on drive C is %s\n", 
cwd ) ; 

free( cwd ); 

} 

} 

produces the following: 
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getdcwd, _wgetdcwd 


Classification: 

Systems: 


The current directory on drive C is C:\PROJECT\C 
WATCOM 

_ getdcwd - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
_ wgetdcwd - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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getdelim 


Synopsis: 

Description: 


Returns: 

Example: 


Classification: 

Systems: 


♦include <stdio.h> 

ssize_ t getdelim( char **line, size_t *n, int delim, FILE *fp ); 

The getdelim function reads in text from a stream^? up to and including a delimiter delim and 
returns the resulting text in a buffer pointed to by line when complete. The buffer pointed to by line 
should be of the size pointed to by n initially. 

The buffer pointed to by line can initially be null and n should reflect the size of line and be set to null. 
When getdelim is invoked, it will check if the buffer pointed to by line is allocated and large enough. 
If not, it will first call realloc to resize the buffer appropriately and adjust the value pointed to by n 
to reflect the new size of line after reallocation. If allocation fails, errno will be set to ENOMEM. 

The function returns the number of characters read into the buffer or -1 on either error or if no further 
data is available. 

The following program would print out each line in a text file "test.txt" . 

♦include <stdio.h> 

void main() 

{ 

char *line; 
size_ t n; 

FILE *fp; 

fp = fopen("test.txt", "r"); 
while(getdelim(&line, &n, '\n', fp) >= 0) { 

printf("> %s", line); 

} 

fclose(fp); 

} 

POSIX 

All, Linux, RDOS, Netware 
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getdiskfree 


Synopsis: 


Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <direct.h> 

unsigned _ getdiskfree( unsigned drive, 

struct diskfree_ t *diskspace ); 

struct diskfree_ t { 

unsigned short total_ clusters; 
unsigned short avail_ clusters; 
unsigned short sectors_ per_ cluster; 
unsigned short bytes_ per_ sector; 

} ; 

The _ getdiskfree function uses system call 0x36 to obtain useful information on the disk drive 
specified by drive. Specify 0 for the default drive, 1 for drive A, 2 for drive B, etc. The information 
about the drive is returned in the structure diskf ree_ t pointed to by diskspace. 

The _ getdiskfree function returns zero if successful. Otherwise, it returns a non-zero value and 
sets errno to EINVAL indicating an invalid drive was specified. 

_ dos_ getdiskfree^ dos_ getdrive^. dos_ setdrive^. getdrive 

♦include <stdio.h> 

♦include <direct.h> 

void main() 

{ 

struct diskfree_ t disk_ data; 

/* get information about drive 3 (the C drive) */ 
if ( _ getdiskfree ( 3, &disk_ data ) == 0 ) { 

printf( "total clusters: %u\n", 

disk_ data.total_ clusters ); 
printf ( "available clusters: %u\n", 

disk_ data.avail_ clusters ); 
printf ( "sectors/cluster: %u\n", 

disk_ data. sectors_ per_ cluster ) ; 
printf( "bytes per sector: %u\n", 

disk_ data.bytes_ per_ sector ); 

} else { 

printf( "Invalid drive specified\n" ); 

} 

} 

produces the following: 

total clusters: 16335 
available clusters: 510 
sectors/cluster: 4 
bytes per sector: 512 

DOS 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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getdrive 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <direct.h> 
int _ getdrive( void ); 

The _ getdrive function returns the current (default) drive number. 
A value of 1 is drive A, 2 is drive B, 3 is drive C, etc. 


_ dos_ getdiskfreej_ dos_ getdrive^. dos_ setdrive^. getdiskfree 

♦include <stdio.h> 

♦include <direct.h> 


void main( void ) 

{ 


} 


printf ( "The current drive is 
'A' + _ getdrive () 


% c \ n " , 

- 1 ); 


produces the following: 

The current drive is C 


DOS 


DOS. Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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getegid 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <unistd.h> 
gid_ t getegid ( void ); 

The getegid function returns the efective group ID for the current process. 

The efective group ID for the current process, 
getgid, getuid, geteuid 
/* 

* Print the effective group ID of the process. 

*/ 

♦include <stdio.h> 

♦include <unistd.h> 

int main( void ) 

{ 

printf ( "My effective group ID is %d\n", getegid() ); 

return( 0 ) ; 


POSIX 1003.1 
Linux 
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getenv, _wgetenv 


Synopsis: 

Safer C: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <stdlib.h> 

char *getenv( const char *name ); 

wchar_ t *_wgetenv( const wchar_ t *name ); 

The Safer C Library extension provides the getenv_ s function which is a safer alternative to 
getenv This newer getenv_ s function is recommended to be used instead of the traditional "unsafe" 
getenv function. 

The getenv function searches the environment list for an entry matching the string pointed to by 
name. The matching is case-insensitive; all lowercase letters are treated as if they were in upper case. 

Entries can be added to the environment list with the DOS set command or with the putenv or 
setenv functions. All entries in the environment list can be displayed by using the DOS set 
command with no arguments. 

To assign a string to a variable and place it in the environment list: 

C>SET INCLUDE=C:\WATCOM\H 

To see what variables are in the environment list, and their current assignments: 

C>SET 

COMSPEC=C:\COMMAND.COM 
PATH=C:\;C:\WATCOM 
INCLUDE=C:\WATCOM\H 

The _ wgetenv function is a wide-character version ofgetenv that operates with wide-character 
strings. 

The getenv function returns a pointer to the string assigned to the environment variable if found, and 
NULL if no match was found. Note: the value returned should be duplicated if you intend to modify 
the contents of the string. 

clearenv, exec. . ., getenv_ s,putenv, _ searchenv,setenv, spawn. . ., system 

♦include <stdio.h> 

♦include <stdlib.h> 

void main( void ) 

{ 

char *path; 

path = getenv( "INCLUDE" ); 
if( path != NULL ) 

printf( "INCLUDE=%s\n", path ); 

} 

ISOC 

_wgetenv is WATCOM 

getenv - All, Linux, RDOS, Netware 
_ wgetenv - All, Linux 
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getenv_s 


Synopsis: 


Constraints: 


Description: 


Returns: 


See Also: 


♦ define_ STDC_ WANT_ LIB_ EXT1_1 

♦include <stdlib.h> 

errno_ t getenv_ s ( size_ t * restrict len, 

char * restrict value, 

rsize_ t maxsize, 

const char * restrict name ); 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and getenv_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

name shall not be a null pointer, maxsize shall neither be equal to zero nor be greater than 
RS I ZE_ MAX. If maxsize is not equal to zero, then value shall not be a null pointer. 

If there is a runtime-constraint violation, the integer pointed to by len (if len is not null ) is set to zero, 
and the environment list is not searched. 

The getenv_ s function searches the environment list for an entry matching the string pointed to by 
name. 

If that entry is found, getenv_ s performs the following actions. If len is not a null pointer, the length 
of the string associated with the matched entry is stored in the integer pointed to by len. If the length of 
the associated string is less than maxsize , then the associated string is copied to the array pointed to by 
value. 

If that entry is not found, getenv_ s performs the following actions. If len is not a null pointer, zero is 
stored in the integer pointed to by len. If maxsize is greater than zero, then value[0] is set to the null 
character. 

The matching is case-insensitive; all lowercase letters are treated as if they were in upper case. 

Entries can be added to the environment list with the DOS set command or with the putenv or 
setenv functions. All entries in the environment list can be displayed by using the DOS set 
command with no arguments. 

To assign a string to a variable and place it in the environment list: 

C>SET INCLUDE=C:\WATCOM\H 

To see what variables are in the environment list, and their current assignments: 

C>SET 

COMSPEC=C:\COMMAND.COM 
PATH=C:\;C:\WATCOM 
INCLUDE=C:\WATCOM\H 

The getenv_ s function returns zero if the environment string specified by name was found and 
successfully stored in the buffer pointed to by value. Otherwise, a non-zero value is returned. 

clearenv, exec. . getenv, putenv, _ searchenv.setenv, spawn. . system 
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getenv_s 


Example: 


Classification: 

Systems: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdlib.h> 

♦include <stdio.h> 

void main( void ) 

{ 

char buffer[12 8] ; 

size_ t len; 

if( getenv_ s ( &len, buffer, sizeof( buffer ), "INCLUDE" ) == 0 ) 
printf ( "INCLUDE=%s\n", buffer ); 

} 

TR 24731 

All, Linux, RDOS, Netware 
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geteuid 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <unistd.h> 
uid_ t geteuid ( void ); 

The geteuid function returns the efective user ID for the calling process. 

The efective user ID for the calling process 
getuid, getgid, getegid 
/* 

* Print the effective user ID of the process. 

*/ 

♦include <stdio.h> 

♦include <unistd.h> 

int main( void ) 

{ 

printf ( "My effective user ID is %d\n", geteuid() ); 

return( 0 ) ; 


POSIX 1003.1 
Linux 
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getfillmask 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


♦include <graph.h> 
unsigned char _ FAR * _ FAR 

_ getfillmask( unsigned char _ FAR *mask ); 

The _ getfillmask function copies the current fill mask into the area located by the argument mask. 
The fill mask is used by the _ ellipse^ f loodfill,_ pie^_ polygon and_ rectangle 
functions that fill an area of the screen. 

The fill mask is an eight-byte array which is interpreted as a square pattern (8 by 8) of 64 bits. Each bit 
in the mask corresponds to a pixel. When a region is filled, each point in the region is mapped onto the 
fill mask. When a bit from the mask is one, the pixel value of the corresponding point is set using the 
current plotting action with the current color; when the bit is zero, the pixel value of that point is not 
affected. 

When the fill mask is not set, a fill operation will set all points in the fill region to have a pixel value of 
the current color. 

If no fill mask has been set, NULL is returned; otherwise, the _ getfillmask function returns mask. 

_ floodfill,_ setfillmask,_ setplotaction 

♦include <conio.h> 

♦include <graph.h> 

char old_ mask [ 8 ] ; 

char new_ mask [ 8 ] = { 0x81, 0x42, 0x24, 0x18, 

0x18, 0x24, 0x42, 0x81 }; 


main () 

{ 

_ setvideomode( _ VRES16COLOR ); 

_ getfillmask ( old_ mask ); 

_setfillmask( new_ mask ); 

_ rectangle! _ GFILLINTERIOR, 100, 100, 540, 380 ); 
_ setf illmask ( old_ mask ); 
getch(); 

_ setvideomode ( _ DEFAULTMODE ); 

} 

PC Graphics 
DOS 
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getfontinfo 


Synopsis: 

Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <graph.h> 

short _ FAR _ getfontinfo ( struct _ fontinfo _ FAR *info ); 


The _ getfontinfo function returns information about the currently selected font. Fonts are selected 
with the _ setfont function. The font information is returned in the_ fontinfo structure indicated 
by the argument info. The structure contains the following fields: 


type 

ascent 

pixwidth 

pixheight 

avgwidth 

filename 

facename 


1 for a vector font, 0 for a bit-mapped font 

distance from top of character to baseline in pixels 

character width in pixels (0 for a proportional font) 

character height in pixels 

average character width in pixels 

name of the file containing the current font 

name of the current font 


The _ getfontinfo function returns zero if the font information is returned successfully; otherwise a 
negative value is returned. 


registerfonts,_ unregisterfonts,_ setfont^_ outgtext,_ getgtextextent, 
setgtextvector,_ getgtextvector 


♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

int width; 

struct _ fontinfo info; 

_ setvideomode( _ VRES16COLOR ); 

_ getfontinfo( &info ); 

_ moveto( 100, 100 ); 

_ outgtext( "WATCOM Graphics" ); 

width = _ getgtextextent( "WATCOM Graphics" ); 

_ rectangle! _ GBORDER, 100, 100, 

100 + width, 100 + info.pixheight ); 

getch(); 

_ setvideomode( _ DEFAULTMODE ); 

} 


PC Graphics 
DOS 
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getgid 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <unistd.h> 
gid_ t getgid ( void ); 

The getgid function returns the group ID for the current process. 

The group ID for the current process, 
getuid, geteuid, getegid 
/* 

* Print the group ID of the process. 

*/ 

♦include <stdio.h> 

♦include <unistd.h> 

int main( void ) 

{ 

printf ( "I belong to group ID %d\n", getgidO ); 
return( 0 ) ; 


POSIX 1003.1 
Linux 
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getgtextextent 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <graph.h> 

short _ FAR _ getgtextextent ( char _ FAR *text ) ; 

The _ getgtextextent function returns the length in pixels of the argument text as it would be 
displayed in the current font by the function _ outgtext. Note that the text is not displayed on the 
screen, only its length is determined. 

The _ getgtextextent function returns the length in pixels of a string. 

_ registerfonts,_ unregisterfonts,_ setfont,_ getfontinfo,_ outgtext, 

_ setgtextvector,_ getgtextvector 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

int width; 

struct _ fontinfo info; 

_ setvideomode( _ VRES16COLOR ); 

_ getfontinfo( &info ); 

_ moveto( 100, 100 ); 

_ outgtext( "WATCOM Graphics" ); 

width = _ getgtextextent( "WATCOM Graphics" ); 

_ rectangle! _ GBORDER, 100, 100, 

100 + width, 100 + info.pixheight ); 

getch(); 

_ setvideomode( _ DEFAULTMODE ); 

} 

PC Graphics 
DOS 
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getgtextvector 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


#include <graph.h> 

struct xycoord _ FAR _ getgtextvector( void ) ; 

The _ getgtextvector function returns the current value of the text orientation vector. This is the 
direction used when text is displayed by the _ out gt ext function. 

The _ getgtextvector function returns, as anxycoord structure, the current value of the text 
orientation vector. 

_ registerfonts,_ unregisterfonts,_ setfont,_ getfontinfo,_ outgtext, 

_ getgtextextent,_ setgtextvector 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

struct xycoord old_ vec; 

_ setvideomode( _ VRES16C0L0R ); 
old_ vec = _ getgtextvector () ; 

_ setgtextvector( 0, -1 ); 

_ moveto( 100, 100 ); 

_ outgtext( "WATCOM Graphics" ); 

_ setgtextvector ( old_ vec. xcoord, old_ vec . ycoord ); 
getch(); 

_ setvideomode ( _ DEFAULTMODE ); 

} 

PC Graphics 
DOS 
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gethostbyname 


Synopsis: 

Description: 


Returns: 


See Also: 
Example: 


#include <netdb.h> 

struct hostent *gethostbyname( const char *name ); 

The gethostbyname function determines the address or addresses of a host specified by the name 
argument. The routine will query the local database initially. If not found, the routine will perform a 
DNS query, returning all "A" records for the given host name. 

The structure returned is defined as: 

struct hostent { 


char 

*h_ name; 

/* host official name */ 

char 

**h_ aliases; 

/* host alternate names, up to 16 , 
* terminated by a NULL pointer 
*/ 

/* address type */ 

int 

h_ addrtype; 

int 

h_ length; 

/* address length in bytes */ 

char ** 

**h_ addr_ list; 

/* array of pointers to network 
* addresses in network byte 


* order, terminated by a NULL 

* pointer 
*/ 

} ; 


In the current Open Watcom implementation, this routine will only ever return IPv4 addresses, and all 
addresses will be of AF_ INET address type. 

The pointer returned by gethostbyname points to a private location, and the user should free neither 
the pointer itself nor any of its constituent structure members. Subsequent calls to this function may 
result in the values changing. 

This function is not thread-safe. Other calls to this function or to other functions accessing the 
hostname database may affect the return value from this function. 

If a matching host is found, the return value will be non-NULL. The returned pointer should not be 
freed by the calling routine. 

If the host is found, the h_ name member will be a copy of the name argument. The addresses are 
contained in the h_ addr_ list member as a NULL-terminated list, and this structure entry will never 
be NULL. 

If no matching host is found or an error occurs, the return value will be NULL, 
gethostent 

The following program will attempt to determine the address of a hostname passed as an argument. 
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gethostbyname 


♦include <stdio.h> 

♦include <netdb.h> 

♦include <arpa/inet.h> 

int main(int argc, char *argv[]) 

{ 

int i; 

struct hostent *he; 

struct in_ addr **addr_list; 

if (argc != 2) { 

fprintf(stderr,"usage : %s <hostname>\n", argv[0]); 
return 1; 

} 

if ((he = gethostbyname(argv[1])) == NULL) { // get the host inf 

o 

printf("Failed to find %s\n", argv[l]); 
return 2; 

} 

printf ("IP addresses for %s:\n", argv[l]); 
addr_ list = (struct in_ addr **) he->h_ addr_ list; 
for(i = 0; addr_list[i] != NULL; i++) { 

printf (" %s\n", inet_ ntoa(*addr_ list[i])); 

} 

return 0; 

} 


Classification: POSIX 
Systems: Linux 
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gethostent 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


#include <netdb.h> 

struct hostent *gethostent( void ); 

The gethostent function reads, parses, and returns entries from the network host database at 
/etc/hosts. The first call will return the first entry, and subsequent calls return subsequent entries. A 
null pointer is returned if either an error is encountered or no further entries exist. 

If a call to sethostent was not first made, the gethostent function will open the database if 
necessary initially. By default, this will always return the first entry in the database. 


The structure returned 

is defined as: 


struct hostent 

{ 


char 

*h_ name; 

/* host official name */ 

char 

**h_ aliases; 

/* host alternate names, up to 16, 
* terminated by a NULL pointer 
*/ 

/* address type */ 

int 

h_ addrtype; 

int 

h_ length; 

/* address length in bytes */ 

char ** 

**h_ addr_ list; 

/* array of pointers to network 
* addresses in network byte 


* order, terminated by a NULL 

* pointer 
*/ 

} ; 


In the current Open Watcom implementation, this routine will only ever return IPv4 addresses, and all 
addresses will be of AF_ INET address type. 

The pointer returned by gethostent points to a static location, and the user should free neither the 
pointer itself nor any of its consituent structure members. 

This function is not thread-safe. Other calls to functions accessing the hostname database may affect 
the return value from this function. 

A parsed host database entry, or NULL if no further entries exist or an error occurred, 
sethostent, endhostent 

The following program will print out each user and their user ID in the system’s password database 
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gethostent 


♦include <stdio.h> 

♦include <netdb.h> 

♦include <arpa/inet.h> 

int main(int argc, char *argv[]) 

{ 

struct hostent *e; 

sethostent(1); 
e = gethostent() ; 
while(e != NULL) { 

char *ia = e->h_ addr_ list [0] ; 
printf("%s - %d.%d.%d.%d\n", 
e->h_ name, 

ia[0],ia[1],ia[2],ia[3] 


); 

e = gethostent (); 

} 

endhostent (); 
return 0; 


Classification: POSIX 
Systems: Linux 
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getimage Functions 


Synopsis: 


Description: 


Returns: 
See Also: 
Example: 


Classification: 


#include <graph.h> 

void _ FAR _ getimage( short xl, short yl, 

short x2, short y2, 
char _ HUGE *image ) ; 

void _ FAR _getimage_w( double xl, double yl, 

double x2, double y2, 
char _ HUGE * image ) ; 

void _ FAR _ getimage_ wxy ( struct _ wxycoord _ FAR *pl, 

struct _ wxycoord _ FAR *p2, 
char _ HUGE *image ); 

The _ getimage functions store a copy of an area of the screen into the buffer indicated by the image 
argument. The _ getimage function uses the view coordinate system. The_ getimage_ w and 
_ getimage_ wxy functions use the window coordinate system. 

The screen image is the rectangular area defined by the points (xl,yl) and (x2,y2). The buffer 
image must be large enough to contain the image (the size of the image can be determined by using the 
_ imagesize function). The image may be displayed upon the screen at some later time by using the 
_ put image functions. 

The _ getimage functions do not return a value. 

_ imagesize,_ putimage 

♦include <conio.h> 

♦include <graph.h> 

♦include <malloc.h> 

main () 

{ 

char *buf; 
int y; 

_ setvideomode( _ VRES16C0L0R ); 

_ ellipse( _ GFILLINTERIOR, 100, 100, 200, 200 ); 
buf = (char*) malloc( 



imagesize( 

100, 

. 100, 201, 

buf != NULL 

) { 




_ getimage( 

100, 

100, 

201, 

201, buf ); 

_ putimage( 

260, 

200, 

buf. 

_ GPSET ); 

_ putimage( 

420, 

100, 

buf. 

_ GPSET ); 


for( y = 100; y < 300; ) { 


_ putimage( 
y += 20; 

420, 

Y r 

buf, _ GXOR ); 

_ putimage( 

420, 

Yr 

buf, _ GXOR ); 


} 

free( buf ); 

} 

getch(); 

_ setvideomode( _DEFAULTMODE ) ; 

} 

PC Graphics 
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getimage Functions 


Systems: 


getimage - DOS 
getimage_ w - DOS 
getimage_ wxy - DOS 
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getline 


Synopsis: 

Description: 


Returns: 

Example: 


Classification: 

Systems: 


#include <stdio.h> 

ssize_ t getline( char **line, size_t *n, FILE *fp ); 

The getline function reads a single line of text from a stream and returns the resulting text, 
including any new line characters, in a buffer pointed to by line when complete. The buffer pointed to 
by line should be of the size pointed to by n initially. 

The buffer pointed to by line can initially be null and n should reflect the size of line and be set to 0. 
When getline is invoked, it will check if the buffer pointed to by line is allocated and large enough. 
If not, it will first call realloc to resize the buffer appropriately and adjust the value pointed to by n 
to reflect the new size of line after reallocation. If allocation fails, errno will be set to ENOMEM. 

The function returns the number of characters read into the buffer or -1 on either error or if no further 
data is available. 

The following program would print out each line in a text file "test.txt" 

♦include <stdio.h> 

void main() 

{ 

char *line; 
size_ t n; 

FILE *fp; 

fp = fopen("test.txt", "r"); 
while(getline(&line, &n, fp) >= 0) { 

printf("> %s", line); 

} 

fclose(fp); 

} 

POSIX 

All, Linux, RDOS, Netware 
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getlinestyle 


Synopsis: #include <graph.h> 

unsigned short _ FAR _ getlinestyle( void ) ; 

Description: The _ getlinestyle function returns the current line-style mask. 

The line-style mask determines the style by which lines and arcs are drawn. The mask is treated as an 
array of 16 bits. As a line is drawn, a pixel at a time, the bits in this array are cyclically tested. When a 
bit in the array is 1, the pixel value for the current point is set using the current color according to the 
current plotting action; otherwise, the pixel value for the point is left unchanged. A solid line would 
result from a value of OxFFFF and a dashed line would result from a value of OxFOFO 

The default line style mask is OxFFFF 

Returns: The _ getlinestyle function returns the current line-style mask. 

See Also: _ lineto^_ pie^ rectangle^ polygon^ setlinestyle 

Example: #include <conio.h> 

♦include <graph.h> 

♦define DASHED OxfOfO 

main() 

{ 

unsigned old_ style; 

_ setvideomode ( _VRES16COLOR ); 
old_ style = _ getlinestyle (); 

_ setlinestyle ( DASHED ); 

_ rectangle! _ GBORDER, 100, 100, 540, 380 ); 

_ setlinestyle ( old_ style ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ); 

} 

Classification: PC Graphics 
Systems: DOS 
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getmbcp 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <mbctype.h> 
int _ getmbcp( void ); 

The _ getmbcp function returns the current multibyte code page number. 

The _ getmbcp function returns the current multibyte code page. A return value of zero indicates that 
a single byte code page is in use. 

_ mbbtombc^ mbc jisto jms,_ mbc jmsto jis,_ mbctombb,_ ismbbalnum,_ ismbbalpha, 
_ ismbbgraph^ ismbbkalnum,_ ismbbkalpha,_ ismbbkana,_ ismbbkprint, 

_ ismbbkpunct,_ ismbblead,_ ismbbprint,_ ismbbpunct,_ ismbbtrail^_ mbbtombc, 
_ mbc jisto jms,_ mbc jmsto jis,_ mbctombb,_ mbbtype,_ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

void main() 

{ 

printf ( "%d\n", _ setmbcp( 932 ) ); 

printf ( "%d\n", _ getmbcp() ); 

} 

produces the following: 

0 

932 

WATCOM 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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getnetbyaddr 


Synopsis: 

Description: 


Returns: 


See Also: 

Classification: 

Systems: 


#include <netdb.h> 

struct netent *getnetbyaddr( in_ addr_t net, int type ); 

The getnetbyaddr function searches the network database for a network with a matching address 
type, specified by type as AF_ INET ,AF_ INET6 , etc., and address matching the net argument. The 
function returns information about said network if a match is found. The routine will query the local 
database only. 

The structure returned is defined as: 
struct netent { 


char 

*n_ name; 

/* 

official network name */ 

char 

**n_ aliases; 

/* 

alias list */ 

int 

n_ addrtype; 

/* 

address type */ 

uint32_ 

t n_ net; 

/* 

network number */ 


} ; 

The pointer returned by getnetbyaddr points to a private location, and the user should free neither 
the pointer itself nor any of its constituent structure members. Subsequent calls to this function may 
result in the values changing. 

This function is not thread-safe. Other calls to this function or to other functions accessing the 
hostname database may affect the return value from this function. 

If a matching host is found, the return value will be non-NULL. The returned pointer should not be 
freed by the calling routine. 

The alias names of said network are contained in the n_ aliases member as a NULL-terminated list, 
and this structure entry will never be NULL. 

If no matching host is found or an error occurs, the return value will be NULL. 

getnetent, getnetbyname 

POSIX 

Linux 
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getnetbyname 


Synopsis: 

Description: 


Returns: 


See Also: 

Classification: 

Systems: 


#include <netdb.h> 

struct netent *getnetbyname( const char *name ); 

The getnetbyname function searches the network database for a network name and returns 
information about said network if a match is found. The routine will query the local database only. 

The structure returned is defined as: 

struct netent { 


char 

*n_ name; 

/* 

official network name */ 

char 

**n_ aliases; 

/* 

alias list */ 

int 

n_ addrtype; 

/* 

address type */ 

uint32_ 

t n_ net; 

/* 

network number */ 


} ; 

The pointer returned by getnetbyname points to a private location, and the user should free neither 
the pointer itself nor any of its constituent structure members. Subsequent calls to this function may 
result in the values changing. 

This function is not thread-safe. Other calls to this function or to other functions accessing the 
hostname database may affect the return value from this function. 

If a matching host is found, the return value will be non-NULL. The returned pointer should not be 
freed by the calling routine. 

The addresses are contained in the n_ aliases member as a NULL-terminated list, and this structure 
entry will never be NULL. 

If no matching host is found or an error occurs, the return value will be NULL. 

getnetent, getnetbyaddr 

POSIX 

Linux 
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getnetent 


Synopsis: 

Description: 


Returns: 


See Also: 

Classification: 

Systems: 


#include <netdb.h> 

struct netent *getnetent( void ); 

The getnetent function retrieves the next entry in the network database. If not proceeded by an 
appropriate call to setnetent , the function will always return the first network in the database. The 
routine will query the local database only. 

The structure returned is defined as: 

struct netent { 


char 

*n_ name; 

/* 

official network name */ 

char 

**n_ aliases; 

/* 

alias list */ 

int 

n_ addrtype; 

/* 

address type */ 

uint32_ 

t n_ net; 

/* 

network number */ 


} ; 


The pointer returned by getnetent points to a private location, and the user should free neither the 
pointer itself nor any of its constituent structure members. Subsequent calls to this function may result 
in the values changing. 

This function is not thread-safe. Other calls to this function or to other functions accessing the 
hostname database may affect the return value from this function. 

If the database contains more entries, the return value will be non-NULL. The returned pointer should 
not be freed by the calling routine. 

The alias names of said network are contained in the n_ aliases member as a NULL-terminated list, 
and this structure entry will never be NULL. 

If no additional network is found or an error occurs, the return value will be NULL. 

setnetent, endnetent, getnetbyname, getnetbyaddr 

POSIX 

Linux 
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getopt 


Synopsis: #include <unistd.h> 

int getopt( int argc, char * const argv[], 
const char *optstring ) ; 

char *optarg; 

int optind, opterr, optopt; 

Description: The getopt function is a command-line parser that can be used by applications that follow Utility 
Syntax Guidelines 3, 4, 5, 6, 7, 9 and 10 in the Base Definitions volume of IEEE Std 1003.1-2001, 
Section 12.2, Utility Syntax Guidelines. 

The parameters argc and argv are the argument count and argument array as passed to main. The 
argument optstring is a string of recognised option characters; if a character is followed by a colon, the 
option takes an argument. All option characters allowed by Utility Syntax Guideline 3 are allowed in 
optstring. 

The global variable optind is the index of the next element of the argv[] vector to be processed. It is 
initialised to 1 by the system, and getopt updates it when it finishes with each element of argv[]. When 
an element of argv[] contains multiple option characters, getopt uses a static variable to determine 
which options have already been processed. 

The getopt function returns the next option character (if one is found) from argv that matches a 
character in optstring, if there is one that matches. If the option takes an argument, getopt sets the 
variable optarg to point to the option-argument as follows: 

If the option was the last character in the string pointed to by an element of argv, then optarg contains 
the next element of argv, and optind is incremented by 2. If the resulting value of optind is not 
less than argc, this indicates a missing option-argument, and getopt returns an error indication. 

Otherwise, optarg points to the string following the option character in that element of argv, and 
optind is incremented by 1. 

If, when getopt is called: 

• argv [optind] is a null pointer 

• *argv[optind] is not the character 

• argv [optind] points to the string "-" 

getopt returns -1 without changing optind. If cirgv[optind] points to the string getopt 
returns-1 after incrementing optind. 

If getopt encounters an option character that is not contained in optstring, it returns the 
question-mark (?) character. If it detects a missing option-argument, it returns the colon character (:) if 
the first character of optstring was a colon, or a question-mark character (?) otherwise. In either case, 
getopt will set the global variable optopt to the option character that caused the error. If the 
application has not set the global variable opterr to 0 and the first character of optstring is not a 
colon, getopt also prints a diagnostic message to stderr. 

The getopt function is not re-entrant and hence not thread-safe. 
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getopt 


Returns: 


See Also: 


Example: 


The getopt function returns the next option character specified on the command line. 

A colon (:) is returned if getopt detects a missing argument and the first character of optstring was a 
colon (:). 

A question mark (?) is returned if getopt encounters an option character not in optstring or detects a 
missing argument and the first character of optstring was not a colon (:). 

Otherwise, getopt returns -1 when all command line options are parsed. 

abort, atexit, _ bgetcmcfexec. . ., exit, _ Exit,_ exit,getcmd, getenv, main, 
onexit, putenv, spawn. . ., system 


♦include <stdio.h> 
♦include <unistd.h> 


int main( 

{ 

int 

char 

char 


int argc. 


c; 

*ifile; 
*ofile; 


char **argv ) 


while( (c = getopt( argc, argv, ":abf:o:" )) != -1 ) { 

switch( c ) { 

case 'a': 

printf( "option a is set\n" ); 
break; 
case 'b': 

printf( "option b is set\n" ) ; 
break; 
case 'f' : 


gv[0] 


ifile = 
printf( 
break; 
case 'o' : 

ofile = 
printf( 
break; 
case ' : 

printf( 
break; 
case '?' : 


) ; 


printf( 


break; 


optarg; 

"input filename is '%s'\n", ifile ); 


optarg; 

"output filename is '%s'\n", ofile ); 


"-%c without filename\n", optopt ); 


"usage: %s -ab -f <filename> -o <filename>\n", 


ar 


} 

return ( 0 ) ; 


produces the following: 

option a is set 

input filename is 'in' 

output filename is 'out' 1 
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getopt 


when the program is executed with the command 
<program name> -afin -o out 

Classification: POSIX 
Systems: All, Linux 
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get_osfhandle 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


♦include <io.h> 

long _ get_ osfhandle( int posixhandle ) ; 

The _ get_ osfhandle function returns the operating system’s internal file handle that corresponds to 
the POSIX-level file handle specified by posixhandle. 

The value returned by _ get_ osfhandle can be used as an argument to the. open_ osfhandle 
function which can be used to connect a second POSIX-level handle to an open file. 

The example below demonstrates the use of these two functions. Note that the example shows how the 
dup2 function can be used to obtain almost identical functionality. 

When the POSIX-level file handles associated with one OS file handle are closed, the first one closes 
successfully but the others return an error (since the first call close the file and released the OS file 
handle). So it is important to call close at the right time, i.e., after all I/O operations are completed to 
the file. 


If successful, _ get_ osfhandle returns an operating system file handle corresponding to 
posixhandle. Otherwise, it returns -1 and sets errno to EBADF, indicating an invalid file handle. 

close, dup2, fdopen, _ hdopen,open, _ open_ osfhandlej_ os_ handle 


♦include 

♦include 

♦include 

♦include 


<stdio.h> 
<stdlib.h> 
<io.h> 

<fcntl.h> 


void main() 

{ 

long os_ handle; 
int fhl, fh2, rc; 


fhl 


if ( 


= open( 


fhl == 
printf( 


"file", 

0_ WRONLY 
S IRUSR 


0_ CREAT 
S IWUSR 


0_ TRUNC 
S_ IRGRP 


1 ) { 

"Could not open 


output file\n" 


exit ( EXIT_ FAILURE ) ; 


} 

printf( "First POSIX handle %d\n", fhl ); 


0_ BINARY, 
S_ IWGRP ) ; 
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get_osfhandle 


Classification: 

Systems: 


#if defined (USE_ DUP2) 
fh2 = 6; 

if( dup2( fhl, fh2 )==-!) fh2 = -1; 
#else 

os_ handle = _ get_ osfhandle ( fhl ) ; 
printf ( "OS Handle %ld\n", os_ handle ); 


fh2 = _ open_ osfhandle ( os_ handle, 0_ WRONLY 

0_ BINARY ); 


#endif 

if( fh2 == -1 ) { 

printf ( "Could not open with second handle\n" 
exit ( EXIT_ FAILURE ) ; 


} 

printf( "Second POSIX handle %d\n", fh2 ); 


); 


rc = write( fh2, "trash\xOd\xOa", 7 ); 

printf( "Write file using second handle %d\n", rc ); 

rc = close( fh2 ); 

printf( "Closing second handle %d\n", rc ); 
rc = close( fhl ) ; 

printf( "Closing first handle %d\n", rc ); 


WATCOM 


DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, Linux, Netware 
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getpgrp 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <unistd.h> 
gid_ t getpgrp ( void ) ; 

The getpgrp function returns the process group ID for the current process. 

The process group ID for the current process, 
getuid, geteuid, getegid 
/* 

* Print the process group ID of the process. 

*/ 

♦include <stdio.h> 

♦include <unistd.h> 

int main( void ) 

{ 

printf ( "I belong to group ID %d\n", getpgrp() ); 

return( 0 ) ; 


POSIX 1003.1 
Linux 
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getphyscoord 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <graph.h> 

struct xycoord _ FAR _ getphyscoord( short x, short y ); 

The _ getphyscoord function returns the physical coordinates of the position with view coordinates 
(x, y) . View coordinates are defined by the _ setvieworg and_ setviewport functions. 

The _ getphyscoord function returns the physical coordinates, as an xycoord structure, of the 
given point. 

_ getviewcoord,_ setvieworg,_ setviewport 

♦include <conio.h> 

♦include <graph.h> 

♦include <stdlib.h> 

main () 

{ 

struct xycoord pos; 

_ setvideomode( _ VRES16C0L0R ); 

_ setvieworg( rand() % 640, rand() % 480 ); 
pos = _ getphyscoord( 0, 0 ); 

_ rectangle( _ GBORDER, - pos.xcoord, - pos.ycoord, 

639 - pos.xcoord, 479 - pos.ycoord ); 

getch(); 

_ setvideomode( _DEFAULTMODE ); 

} 

PC Graphics 
DOS 
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getpid, _getpid 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <unistd.h> 
pid_ t getpid ( void ); 
pid_ t _ getpid( void ) ; 

The getpid function returns the process ID for the current process. 
The process ID for the current process, 
getppid, gettid 
/* 

* print out the ID of this process 
*/ 

♦include <stdio.h> 

♦include <unistd.h> 

int main( void ) 

{ 

printf ( "I'm process %d\n", getpidO ); 
return ( 0 ) ; 

} 

POSIX 1003.1 
_getpid is WATCOM 

getpid - All, Linux, RDOS 
_ getpid - All, Linux, RDOS 
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getpixel Functions 


Synopsis: #include <graph.h> 

short _ FAR _ getpixel( short x, short y ); 

short _ FAR _getpixel_w( double x, double y ); 

Description: The _ getpixel functions return the pixel value for the point with coordinates (x, y) . The 

_ getpixel function uses the view coordinate system. The_ getpixel_ w function uses the window 
coordinate system. 

Returns: The _ getpixel functions return the pixel value for the given point when the point lies within the 

clipping region; otherwise, (-1) is returned. 

See Also: _ setpixel 

Example: #include <conio.h> 

♦include <graph.h> 

♦include <stdlib.h> 

main() 

{ 

int x, y; 
unsigned i; 

_ setvideomode ( _VRES16C0L0R ); 

_ rectangle! _ GBORDER, 100, 100, 540, 380 ); 
for( i = 0; i <= 60000; ++i ) { 

x = 101 + rand() % 439; 
y = 101 + rand() % 279; 

_ setcolor ( _ getpixel ( x, y ) + 1 ); 

_ setpixel ( x, y ); 

} 

getch(); 

_ setvideomode( _ DEFAULTMODE ); 

} 

Classification: PC Graphics 

Systems: _ getpixel - DOS 

_ getpixel_ w - DOS 
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getplotaction 


Synopsis: #include <graph.h> 

short _ FAR _ getplotaction( void ) ; 

Description: The _ getplotaction function returns the current plotting action. 

The drawing functions cause pixels to be set with a pixel value. By default, the value to be set is 
obtained by replacing the original pixel value with the supplied pixel value. Alternatively, the replaced 
value may be computed as a function of the original and the supplied pixel values. 

The plotting action can have one of the following values: 



_GPSET 

replace the original screen pixel value with the supplied pixel value 


jGAND 

replace the original screen pixel value with the bitwise and of the original 
pixel value and the supplied pixel value 


JiOR 

replace the original screen pixel value with the bitwise or of the original pixel 
value and the supplied pixel value 


_GXOR 

replace the original screen pixel value with the bitwise exclusive-or of the 
original pixel value and the supplied pixel value. Performing this operation 
twice will restore the original screen contents, providing an efficient method 
to produce animated effects. 

Returns: 

The_ getplotaction 

function returns the current plotting action. 

See Also: 

_ setplotaction 



Example: #include <conio.h> 

♦include <graph.h> 

main () 

{ 

int old_ act; 


_ setvideomode( _ VRES16C0L0R 
old_ act = _ getplotaction () ; 
_ setplotaction( _ GPSET ); 

_ rectangle! _ GFILLINTERIOR, 

); 

100, 

100, 

540, 

380 ) ; 

getch (); 

_ setplotaction ( _ GXOR ); 

_ rectangle! _ GFILLINTERIOR, 

100, 

100, 

540, 

380 ) ; 

getch(); 

_ setplotaction ( old_ act ); 

_ setvideomode( _ DEFAULTMODE 

); 





} 

Classification: PC Graphics 
Systems: DOS 
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getppid 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <unistd.h> 
pid_ t getppid(void); 

The getppid function allows the calling process to find out its parent ID. 
The process parent’s process ID. 
getpid 
/* 

* Print the parent's process ID. 

*/ 

♦include <stdio.h> 

♦include <unistd.h> 

int main( void ) 

{ 

printf ( "My parent is %d\n", getppid() ); 

return( 0 ) ; 


POSIX 1003.1 
Linux 
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getprotobyname 


Synopsis: 

Description: 


Returns: 


See Also: 

Classification: 

Systems: 


#include <netdb.h> 

struct netent *getprotobyname( const char *name ); 

The getprotobyname function searches the protocol database for a protocol matching the specified 
name , considering both the official name and aliases. The routine will query the local database only. 

The structure returned is defined as: 

struct protoent { 

char *p_ name; /* official protocol name */ 

char **p_ aliases; /* alias list */ 

int p_ proto; /* protocol number */ 

} ; 


The pointer returned by getprotobyname points to a private location, and the user should free 
neither the pointer itself nor any of its constituent structure members. Subsequent calls to this function 
may result in the values changing. 

This function is not thread-safe. Other calls to this function or to other functions accessing the protocol 
database may affect the return value from this function. 

If a matching protocol database entry is found, the return value will point to a struct protoent as 
defined above. 

The alias names of said protocol are contained in the p_ aliases member as a NULL-terminated list, 
and this stmcture entry will never be NULL. 

If no protocol is found or an error occurs, the return value will be NULL, 
getprotoent, setprotoent, endprotoent, getprotobynumber 
POSIX 
Linux 


Library Functions and Macros 391 




getprotobynumber 


Synopsis: 

Description: 


Returns: 


See Also: 

Classification: 

Systems: 


#include <netdb.h> 

struct netent *getprotobynumber( int protocol ); 

The getprotobynumber function searches the protocol database for a protocol matching the 
specified by the protocol argument. The routine will query the local database only. 

The structure returned is defined as: 

struct protoent { 

char *p_ name; /* official protocol name */ 

char **p_ aliases; /* alias list */ 

int p_ proto; /* protocol number */ 

} ; 


The pointer returned by getprotobynumber points to a private location, and the user should free 
neither the pointer itself nor any of its constituent structure members. Subsequent calls to this function 
may result in the values changing. 

This function is not thread-safe. Other calls to this function or to other functions accessing the protocol 
database may affect the return value from this function. 

If a matching protocol database entry is found, the return value will point to a struct protoent as 
defined above. 

The alias names of said protocol are contained in the p_ aliases member as a NULL-terminated list, 
and this structure entry will never be NULL. 

If no protocol is found or an error occurs, the return value will be NULL, 
getprotoent, setprotoent, endprotoent, getprotobyname 
POSIX 
Linux 
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getprotoent 


Synopsis: 

Description: 


Returns: 


See Also: 

Classification: 

Systems: 


#include <netdb.h> 

struct netent *getprotoent( void ) ; 

The getprotoent function retrieves the next entry in the protocol database. If not proceeded by an 
appropriate call to setprotoent , the function will always return the first protocol in the database. 
The routine will query the local database only. 

The structure returned is defined as: 

struct protoent { 


char 

*p_ name; 

/* 

official protocol name */ 

char 

**p_ aliases; 

/* 

alias list */ 

int 

P_ proto; 

/* 

protocol number */ 


} ; 


The pointer returned by getprotoent points to a private location, and the user should free neither the 
pointer itself nor any of its constituent structure members. Subsequent calls to this function may result 
in the values changing. 

This function is not thread-safe. Other calls to this function or to other functions accessing the protocol 
database may affect the return value from this function. 

If the database contains more entries, the return value will be non-NULL. The returned pointer should 
not be freed by the calling routine. 

The alias names of said protocol are contained in the p_ aliases member as a NULL-terminated list, 
and this structure entry will never be NULL. 

If no protocol is found or an error occurs, the return value will be NULL, 
setprotoent, endprotoent, getprotobyname, getprotobynumber 
POSIX 
Linux 
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getpwent 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <pwd.h> 

struct passwd *getpwent( void ) ; 

The getpwent function reads, parses, and returns entries from the password database at /etc/passwd. 
The first call will return the first entry, and subsequent calls return subsequent entries. A null pointer is 
returned if either an error is encountered or no further entries exist. 

The structure returned is defined as: 

struct passwd { 


char 

*pw_ name; 

/* user's login name 

*/ 

char 

*pw_ passwd; 

/* user's password 

*/ 

uid_ t 

pw_ uid; 

/* user ID number 

*/ 

gid_ t 

pw_ gid; 

/* group ID number 

*/ 

char 

*pw_ gecos; 

/* real name 

*/ 

char 

*pw_ dir; 

/* home directory 

*/ 

char 

*pw_ shell; 

/* initial program 

*/ 


} ; 


On most modern Linux implementations, the resulting password will simply be ’x’ as passwords are not 
normally stored in the password database itself. 

The pointer returned by getpwent points to a static location, and the user should free neither the 
pointer itself nor any of its consituent structure members. 

This function is not thread-safe. Other calls to functions accessing the password database may affect 
the return value from this function. 

A parsed password database entry, or NULL if no further entries exist or an error occurred, 
setpwent, endpwent, getpwnam, getpwuid 

The following program will print out each user and their user ID in the system’s password database 

♦include <stdio.h> 

♦include <pwd.h> 

void main() 

{ 

struct passwd *pw; 
setpwent(); 

while((pw = getpwent()) != NULL) { 

printf("User id %d is %s\n", (int) pw->pw_ uid, pw->pw_ name) ; 

} 

endpwent(); 


} 

POSIX 

Linux 
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getpwnam 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <pwd.h> 

struct passwd *getpwnam( const char *name ); 

The getpwnam function locates and returns a parsed password database entry for the user with the 
specified username. If a matching entry is not found or an error occurs, a null pointer will be returned. 

The structure returned is defined as: 

struct passwd { 


char 

*pw_ name; 

/* user's login name 

*/ 

char 

*pw_ passwd; 

/* user's password 

*/ 

uid_ t 

pw_ uid; 

/* user ID number 

*/ 

gid_ t 

pw_ gid; 

/* group ID number 

*/ 

char 

*pw_ gecos; 

/* real name 

*/ 

char 

*pw_ dir; 

/* home directory 

*/ 

char 

*pw_ shell; 

/* initial program 

*/ 


} ; 


On most modern Linux implementations, the resulting password will simply be ’x’ as passwords are not 
normally stored in the password database itself. 

The pointer returned by getpwnam points to a static location, and the user should free neither the 
pointer itself nor any of its consituent structure members. 

This function is not thread-safe. Other calls to functions accessing the password database may affect 
the return value from this function. 

A matching parsed password database entry, or NULL if no match is found, 
setpwent, endpwent, getpwuid, getpwent 

The following program will locate and print out the user ID corresponding to a user name 'root.’ 

♦include <stdio.h> 

♦include <pwd.h> 

void main() 

{ 

struct passwd *pw; 

pw = getpwnam( "root" ); 
if(pw) { 

printf("The user id for root is %d\n", (int) pw->pw_ uid) ; 

} else { 

printf("User 'root' was not found.\n"); 

} 

} 

POSIX 

Linux 
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getpwuid 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <pwd.h> 

struct passwd *getpwuid( uit_t uid ); 

The getpwuid function locates and returns a parsed password database entry for the user with the 
specified user ID. If a matching entry is not found or an error occurs, a null pointer will be returned. 

The structure returned is defined as: 

struct passwd { 


char 

*pw_ name; 

/* user's login name 

*/ 

char 

*pw_ passwd; 

/* user's password 

*/ 

uid_ t 

pw_ uid; 

/* user ID number 

*/ 

gid_ t 

pw_ gid; 

/* group ID number 

*/ 

char 

*pw_ gecos; 

/* real name 

*/ 

char 

*pw_ dir; 

/* home directory 

*/ 

char 

*pw_ shell; 

/* initial program 

*/ 


} ; 


On most modern Linux implementations, the resulting password will simply be ’x’ as passwords are not 
normally stored in the password database itself. 

The pointer returned by getpwuid points to a static location, and the user should free neither the 
pointer itself nor any of its consituent structure members. 

This function is not thread-safe. Other calls to functions accessing the password database may affect 
the return value from this function. 

A matching parsed password database entry, or NULL if no match is found, 
setpwent, endpwent, getpwnam, getpwent 

The following program will locate and print out the user name corresponding to a user ID of 1000. 

♦include <stdio.h> 

♦include <pwd.h> 

void main() 

{ 

struct passwd *pw; 

pw = getpwuid( (uid_ t) 1000 ); 
if(pw) 

printf("The corresponding username is '%s'\n", pw->pw_ name) ; 

else 

printf("User id 1000 was not found.\n"); 

} 

POSIX 

Linux 
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gets, _getws 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <stdio.h> 
char *gets( char *buf ) ; 

♦include <stdio.h> 

wchar_ t *_ getws ( wchar_ t *buf ) ; 

The gets function gets a string of characters from the file designated by stdin and stores them in the 
array pointed to by buf until end-of-file is encountered or a new-line character is read. Any new-line 
character is discarded, and a null character is placed immediately after the last character read into the 
array. 

The _ getws function is a wide-character version of gets that operates with wide-character strings. 
The _ getws function gets a string of multibyte characters (if present) from the input stream pointed to 
by stdin, converts them to wide characters, and stores them in the wide-character array pointed to by 
buf until end-of-file is encountered or a wide-character new-line character is read. 

It is recommended that f gets be used instead of gets because data beyond the array buf will be 
destroyed if a new-line character is not read from the input stream stdin before the end of the array 
buf is reached. 

A common programming error is to assume the presence of a new-line character in every string that is 
read into the array. A new-line character may not appear as the last character in a file, just before 
end-of-file. 

The gets function returns buf if successful. NULL is returned if end-of-file is encountered, or if a read 
error occurs. When an error has occurred, errno contains a value indicating the type of error that has 
been detected. 

fgetc, fgetchar, fgets, fopen, getc, getchar, ungetc 

♦include <stdio.h> 

void main() 

{ 

char buffer [80]; 

while] gets( buffer ) != NULL ) 

puts( buffer ); 

} 

ISOC 

_getws is WATCOM 

gets - All, Linux, RDOS, Netware 
_ getws - All, Linux 
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gets_s 


Synopsis: 

Constraints: 


Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦ define_ STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

char *gets_ s ( char *s, rsize_t n ); 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and gets_ s will set s[0] to be the null character, and characters are read and discarded 
from stdin until a new-line character is read, or end-of-file or a read error occurs. 

s shall not be a null pointer, n shall neither be equal to zero nor be greater than RSI ZE_ MAX . A 
new-line character, end-of-file, or read error shall occur within reading n-1 characters from stdin . 

The gets_ s function gets a string of characters from the file designated by stdin and stores them in 
the array pointed to by s until end-of-file is encountered or a new-line character is read. Size of the 
array s is specified by the argument n , this information is used to protect buffer from overflow. If 
buffer ,v is about to be overflown, runtime-constraint is activated. Any new-line character is discarded, 
and a null character is placed immediately after the last character read into the array. 

The gets_ s function returns ,v if successful. NULL is returned if there was a runtime-constraint 
violation, or if end-of-file is encountered and no caracters have been read into the array, or if a read 
error occurs. 

fgetc, fgetchar, fgets, fopen, getc, getchar, gets, ungetc 

♦ define_ STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

int main() 

{ 

char buffer[80]; 

while( gets_ s( buffer, sizeof( buffer ) ) != NULL ) 

puts( buffer ); 

} 

TR 24731 

All, Linux, RDOS, Netware 
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getservbyname 


Synopsis: 

Description: 


Returns: 


See Also: 

Classification: 

Systems: 


#include <netdb.h> 

struct servent *getservbyname( const char *name, const char *protocol 

) ; 

The getservbyname function searches the service database for a service with matching name and 
protocol , returning a pointer the a struct servent if found. The function will search for matching 
aliases as well. If protocol is NULL, the first encountered service matching the specified name will be 
returned regardless of protocol. The routine will query the local database only. 

The structure returned is defined as: 

struct servent { 


char 

*s_ name; 

/* 

official service name */ 

char 

**s_ aliases; 

/* 

alias list */ 

int 

s_ port; 

/* 

port number */ 

char 

*s_ proto; 

/* 

protocol to use */ 


} ; 


The pointer returned by getservbyname points to a private location, and the user should free neither 
the pointer itself nor any of its constituent structure members. Subsequent calls to this function may 
result in the values changing. 

This function is not thread-safe. Other calls to this function or to other functions accessing the 
hostname database may affect the return value from this function. 

If a match is found, the return value will be non-NULL. The returned pointer should not be freed by the 
calling routine. 

The alias names of said network are contained in the s_ aliases member as a NULL-terminated list, 
and this structure entry will never be NULL. 

If no additional network is found or an error occurs, the return value will be NULL. 

getservent, setservent, endservent 

POSIX 

Linux 
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getservbyport 


Synopsis: 

Description: 


Returns: 


See Also: 

Classification: 

Systems: 


#include <netdb.h> 

struct servent *getservbyname( int port, const char *protocol ); 

The getservbyport function searches the service database for a service listening on port using 
protocol , returning a pointer the a struct servent if found. If protocol is NULL, the first 
encountered service matching the specified port number will be returned regardless of protocol. The 
routine will query the local database only. 

The structure returned is defined as: 

struct servent { 


char 

*s_ name; 

/* 

official service name */ 

char 

**s_ aliases; 

/* 

alias list */ 

int 

s_ port; 

/* 

port number */ 

char 

*s_ proto; 

/* 

protocol to use */ 


1 ; 


The pointer returned by getservbyport points to a private location, and the user should free neither 
the pointer itself nor any of its constituent structure members. Subsequent calls to this function may 
result in the values changing. 

This function is not thread-safe. Other calls to this function or to other functions accessing the 
hostname database may affect the return value from this function. 

If a match is found, the return value will be non-NULL. The returned pointer should not be freed by the 
calling routine. 

The alias names of said network are contained in the s_ aliases member as a NULL-terminated list, 
and this structure entry will never be NULL. 

If no additional network is found or an error occurs, the return value will be NULL. 

getservent, setservent, endservent, getservbyname 

POSIX 

Linux 
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getservent 


Synopsis: 

Description: 


Returns: 


See Also: 

Classification: 

Systems: 


#include <netdb.h> 

struct servent *getservent( void ) ; 

The getservent function retrieves the next entry in the service database. If not proceeded by an 
appropriate call to set servent , the function will always return the first service in the database. The 
routine will query the local database only. 

The structure returned is defined as: 

struct servent { 


char 

*s_ name; 

/* 

official service name */ 

char 

**s_ aliases; 

/* 

alias list */ 

int 

s_ port; 

/* 

port number */ 

char 

*s_ proto; 

/* 

protocol to use */ 


1 ; 


The pointer returned by getservent points to a private location, and the user should free neither the 
pointer itself nor any of its constituent structure members. Subsequent calls to this function may result 
in the values changing. 

This function is not thread-safe. Other calls to this function or to other functions accessing the 
hostname database may affect the return value from this function. 

If the database contains more entries, the return value will be non-NULL. The returned pointer should 
not be freed by the calling routine. 

The alias names of said network are contained in the s_ aliases member as a NULL-terminated list, 
and this structure entry will never be NULL. 

If no additional network is found or an error occurs, the return value will be NULL, 
setservent, endservent, getservbyname, getservbyport 
POSIX 
Linux 
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gettextcolor 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <graph.h> 

short _ FAR _ gettextcolor ( void ) ; 

The _ gettextcolor function returns the pixel value of the current text color. This is the color used 
for displaying text with the _ outtext and_ outmem functions. The default text color value is set to 
7 whenever a new video mode is selected. 

The _ gettextcolor function returns the pixel value of the current text color. 

_ settextcolor,_ setcolor,_ outtext^ outmem 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

int old_ col; 
long old_ bk; 

_ setvideomode( _ TEXTC80 ) ; 
old_ col = _ gettextcolor () ; 
old_ bk = _ getbkcolor () ; 

_ settextcolor( 7 ) ; 

_ setbkcolor( _ BLUE ); 

_ outtext( " WATCOM \nGraphics" ); 

_ settextcolor( old_ col ); 

_ setbkcolor( old_ bk ) ; 
getch(); 

_ setvideomode ( _ DEFAULTMODE ); 

} 

PC Graphics 
DOS 
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gettextcursor 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <graph.h> 

short _ FAR _ gettextcursor( void ) ; 

The _ gettextcursor function returns the current cursor attribute, or shape. The cursor shape is set 
with the _ settextcursor function. See the_ settextcursor function for a description of the 
value returned by the _ gettextcursor function. 

The _ gettextcursor function returns the current cursor shape when successful; otherwise, (-1) is 
returned. 

_ settextcursor^. displaycursor 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

int old_ shape; 

old_ shape = _ gettextcursor () ; 

_settextcursor( 0x0007 ); 

_ outtext( "\nBlock cursor" ); 
getch(); 

_ settextcursor( 0x0407 ); 

_ outtext( "\nHalf height cursor" ); 
getch(); 

_ settextcursor( 0x2000 ); 

_ outtext( "\nNo cursor" ); 
getch(); 

_ settextcursor ( old_ shape ); 

} 

PC Graphics 
DOS 
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gettextextent 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


#include <graph.h> 

void _ FAR _ gettextextent( short x, short y, 

char _ FAR *text, 

struct xycoord _ FAR *concat, 

struct xycoord _ FAR *extent ); 

The _ gettextextent function simulates the effect of using the_ grtext function to display the 
text string text at the position (x, y) , using the current text settings. The concatenation point is 
returned in the argument concat. The text extent parallelogram is returned in the array extent. 

The concatenation point is the position to use to output text after the given string. The text extent 
parallelogram outlines the area where the text string would be displayed. The four points are returned 
in counter-clockwise order, starting at the upper-left corner. 

The _ gettextextent function does not return a value. 

_ grtext^ gettextsettings 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

struct xycoord concat; 
struct xycoord extent[ 4 ]; 

_ setvideomode( _ VRES16C0L0R ); 

_ grtext( 100, 100, "hot" ); 

_ gettextextent( 100, 100, "hot", Sconcat, extent ); 

_ polygon( _ GBORDER, 4, extent ); 

_ grtext( concat.xcoord, concat.ycoord, "dog" ); 
getch(); 

_ setvideomode( _DEFAULTMODE ); 

} 

produces the following: 
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gettextextent 



Classification: PC Graphics 
Systems: DOS 
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gettextposition 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <graph.h> 

struct rccoord _ FAR _ gettextposition( void ) ; 

The _ gettextposition function returns the current output position for text. This position is in 
terms of characters, not pixels. 

The current position defaults to the top left corner of the screen, (1,1), when a new video mode is 
selected. It is changed by successful calls to the _ outtext^_ outmenL settextposition and 
_ settextwindow functions. 

Note that the output position for graphics output differs from that for text output. The output position 
for graphics output can be set by use of the _ moveto function. 

The _ gettextposition function returns, as anrccoord structure, the current output position for 
text. 

_ outtext^_ outmem^ settextposition,_ settextwindow,_ moveto 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

struct rccoord old_pos; 

_ setvideomode( _ TEXTC80 ) ; 
old_ pos = _ gettextposition () ; 

_ settextposition( 10, 40 ); 

_ outtext( "WATCOM Graphics" ); 

_ settextposition ( old_pos.row, old_pos.col ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ); 

} 

PC Graphics 
DOS 


406 Library Functions and Macros 




gettextsettings 


Synopsis: 

Description: 


Returns: 
See Also: 

Example: 


Classification: 

Systems: 


♦include <graph.h> 

struct textsettings _ FAR * _ FAR _ gettextsettings 
( struct textsettings _ FAR *settings ); 


The _ gettextsettings function returns information about the current text settings used when text 
is displayed by the _ grtext function. The information is stored in thetextsettings structure 
indicated by the argument settings. The structure contains the following fields (all are short fields): 


basevectorx 

basevectory 

path 

height 

width 

spacing 

horizalign 

vertalign 


x-component of the current base vector 

y-component of the current base vector 

current text path 

current text height (in pixels) 

current text width (in pixels) 

current text spacing (in pixels) 

horizontal component of the current text alignment 

vertical component of the current text alignment 


The _ gettextsettings function returns information about the current graphics text settings. 


grtext^ setcharsize,_ setcharspacing,_ settextalign^_ settextpath, 
settextorient 


♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

struct textsettings ts; 

_ setvideomode ( _VRES16COLOR ); 

_ gettextsettings( &ts ) ; 

_ grtext( 100, 100, "WATCOM" ); 

_ setcharsize( 2 * ts.height, 2 * ts.width ); 
_ grtext( 100, 300, "Graphics" ); 

_ setcharsize( ts.height, ts.width ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ) ; 

} 


PC Graphics 
DOS 
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gettextwindow 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <graph.h> 

void _ FAR _ gettextwindow ( 

short _FAR *rowl, short _ FAR *coll, 
short _ FAR *row2, short _ FAR *col2 ); 

The _ gettextwindow function returns the location of the current text window. A text window is 
defined with the _ settextwindow function. By default, the text window is the entire screen. 

The current text window is a rectangular area of the screen. Text display is restricted to be within this 
window. The top left corner of the text window is placed in the arguments (rowl, col 1) . The 
bottom right corner of the text window is placed in (row2, col2) . 

The _ gettextwindow function returns the location of the current text window. 

_ settextwindow,_ outtext^ outmem^ settextposition,_ scrolltextwindow 

♦include <conio.h> 

♦include <graph.h> 

♦include <stdio.h> 

main () 

{ 

int i; 

short rl, cl, r2, c2; 
char but[ 80 ]; 

_ setvideomode( _ TEXTC80 ); 

_ gettextwindow( &rl, &cl, &r2, &c2 ); 

_ settextwindow( 5, 20, 20, 40 ); 
for( i = 1; i <= 20; ++i ) { 

sprintf ( buf, "Line %d\n", i ); 

_ outtext( buf ); 

} 

getch(); 

_ settextwindow( rl, cl, r2, c2 ); 

_ setvideomode( _DEFAULTMODE ); 

} 

PC Graphics 
DOS 


408 Library Functions and Macros 




gettid 


Synopsis: 

Description: 

Returns: 

See Also: 

Classification: 

Systems: 


♦include <process.h> 
int gettid(void); 

The gettid function returns the thread id for the current thread on Linux systems. It provides a 
wrapper around the appropriate kernel system call. 

The gettid function returns the thread id for the current thread. 

getpid 

WATCOM 

Linux 
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getuid 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <unistd.h> 
uid_ t getuid ( void ); 

The getuid function returns the user ID for the calling process. 
The user ID for the calling process 
geteuid, getgid, getegid 
/* 

* Print the user ID of this process. 

*/ 

♦include <stdio.h> 

♦include <unistd.h> 

int main( void ) 

{ 

printf ( "My userid is %d\n", getuid() ); 

return( 0 ) ; 


POSIX 1003.1 
Linux 
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getvideoconfig 


Synopsis: #include <graph.h> 

struct videoconfig _ FAR * _ FAR _ getvideoconfig 
( struct videoconfig _ FAR *config ); 

Description: The _ getvideoconfig function returns information about the current video mode and the hardware 
configuration. The information is returned in the videoconfig structure indicated by the argument 
config. The structure contains the following fields (all are short fields): 

numxpixels number of pixels in x-axis 

numypixels number of pixels in y-axis 

numtextcols number of text columns 

numtextrows number of text rows 

numcolors number of actual colors 

bitsperpixel number of bits in a pixel value 

numvideopages number of video pages 

mode current video mode 

adapter adapter type 

monitor monitor type 

memory number of kilobytes (1024 characters) of video memory 

The adapter field will contain one of the following values: 


_NODISPLA Y 

no display adapter attached 

J UNKNOWN 

unknown adapter/monitor type 

_MDPA 

Monochrome Display/Printer Adapter 

_CGA 

Color Graphics Adapter 

_HERCULES 

Hercules Monochrome Adapter 

_MCGA 

Multi-Color Graphics Array 

_EGA 

Enhanced Graphics Adapter 

_VGA 

Video Graphics Array 

_SVGA 

SuperVGA Adapter 
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getvideoconfig 


The monitor field will contain one of the following values: 

_MONO regular monochrome 

JCOLOR regular color 

_ENHANCED enhanced color 

_ANALOGMONO analog monochrome 

_ANALOGCOLOR analog color 

The amount of memory repotted by _ getvideoconfig will not always be correct for SuperVGA 
adapters. Since it is not always possible to determine the amount of memory, _ getvideoconfig 
will always report 256K, the minimum amount. 

Returns: The _ getvideoconfig function returns information about the current video mode and the hardware 

configuration. 

See Also: _ setvideomode,_ setvideomoderows 
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getvideoconfig 


Example: 


Classification: 

Systems: 


♦include <conio.h> 

♦include <graph.h> 

♦include <stdio.h> 

♦include <stdlib.h> 

main () 

{ 

int mode; 

struct videoconfig vc; 
char buf[ 80 ]; 

_ getvideoconfig( &vc ); 

/* select "best" video mode */ 
switch( vc.adapter ) { 

case _ VGA : 
case _ SVGA : 

mode = _ VRES16COLOR; 
break; 

case _ MCGA : 

mode = _ MRES256COLOR; 
break; 
case _ EGA : 

if ( vc.monitor == _ MONO ) { 

mode = _ ERESNOCOLOR; 

} else { 

mode = _ ERESCOLOR; 

} 

break; 
case _ CGA : 

mode = _ MRES4COLOR; 
break; 

case _ HERCULES : 

mode = _ HERCMONO; 
break; 
default : 

puts( "No graphics adapter" ); 
exit ( 1 ); 

} 

if ( _ setvideomode( mode ) ) { 

_ getvideoconfig( &vc ); 

sprintf ( buf, "%d x %d x %d\n", vc.numxpixels, 
vc.numypixels, vc.numcolors ); 

_ outtext( buf ); 
getch(); 

_ setvideomode( _DEFAULTMODE ) ; 

} 

} 

PC Graphics 
DOS 
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getviewcoord Functions 


Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <graph.h> 

struct xycoord _ FAR _ getviewcoord( short x, short y ); 

struct xycoord _ FAR _ getviewcoord_ w ( double x, double y ); 

struct xycoord _ FAR _ getviewcoord_ wxy ( 

struct _ wxycoord _ FAR *p ) ; 

The _ getviewcoord functions translate a point from one coordinate system to viewport coordinates. 
The _ getviewcoord function translates the point (x, y) from physical coordinates. The 
_ getviewcoord_ w and. getviewcoord_ wxy functions translate the point from the window 
coordinate system. 

Viewport coordinates are defined by the _ setvieworg and_ setviewport functions. Window 
coordinates are defined by the _ setwindow function. 

Note: In previous versions of the software, the _ getviewcoord function was called 
_ getlogcoord. uindex=2 

The _ getviewcoord functions return the viewport coordinates, as anxycoord structure, of the 
given point. 

_ getphyscoord,_ setvieworg,_ setviewport^ setwindow 

♦include <conio.h> 

♦include <graph.h> 

♦include <stdlib.h> 

main () 

{ 

struct xycoord posl, pos2; 

_ setvideomode( _ VRES16C0L0R ); 

_ setvieworg( rand() % 640, rand() % 480 ); 
posl = _ getviewcoord( 0, 0 ); 
pos2 = _ getviewcoord( 639, 479 ); 

_ rectangle( _ GBORDER, posl.xcoord, posl.ycoord, 

pos2.xcoord, pos2.ycoord ); 

getch(); 

_ setvideomode( _DEFAULTMODE ); 

} 

PC Graphics 

_ getviewcoord - DOS 
_ getviewcoord_ w - DOS 
_ getviewcoord_ wxy - DOS 
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getvisualpage 


Synopsis: #include <graph.h> 

short _ FAR _ getvisualpage( void ) ; 

Description: The _ getvisualpage function returns the number of the currently selected visual graphics page. 

Only some combinations of video modes and hardware allow multiple pages of graphics to exist. When 
multiple pages are supported, the active page may differ from the visual page. The graphics 
information in the visual page determines what is displayed upon the screen. Animation may be 
accomplished by alternating the visual page. A graphics page can be constructed without affecting the 
screen by setting the active page to be different than the visual page. 

The number of available video pages can be determined by using the _ getvideoconf ig function. 
The default video page is 0. 

Returns: The _ getvisualpage function returns the number of the currently selected visual graphics page. 

See Also: _ setvisualpage,_ setactivepage,_ getactivepage,_ getvideoconf ig 

Example: #include <conio.h> 

♦include <graph.h> 

main() 

{ 

int old_ apage; 
int old_ vpage; 

_ setvideomode( _ HRES16COLOR ); 
old_ apage = _ getactivepage () ; 
old_ vpage = _ getvisualpage () ; 

/* draw an ellipse on page 0 */ 

_ setactivepage( 0 ); 

_ setvisualpage( 0 ); 

_ellipse! _ GFILLINTERIOR, 100, 50, 540, 150 ); 

/* draw a rectangle on page 1 */ 

_ setactivepage( 1 ); 

_ rectangle! _ GFILLINTERIOR, 100, 50, 540, 150 ); 
getch(); 

/* display page 1 */ 

_ setvisualpage( 1 ); 
getch() ; 

_ setactivepage ( old_ apage ); 

_ setvisualpage ( old_ vpage ) ; 

_ setvideomode( _ DEFAULTMODE ); 

} 

Classification: PC Graphics 
Systems: DOS 
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getw 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdio.h> 

int _ getw( int binint, FILE *fp ); 

The _ getw function reads a binary value of type int from the current position of the stream _//;> and 
increments the associated file pointer to point to the next unread character in the input stream. _ getw 
does not assume any special alignment of items in the stream. 

_ getw is provided primarily for compatibility with previous libraries. Portability problems may occur 
with _ getw because the size of an int and the ordering of bytes within an int differ across systems. 

The _ getw function returns the integer value read or, if a read error or end-of-file occurs, the error 
indicator is set and _ getw returnsEOF. Since EOF is a legitimate value to read from fp, use terror 
to verify that an error has occurred. 

terror, fgetc, fgetchar, fgets, fopen, getc, getchar, gets, _ putw,ungetc 

♦include <stdio.h> 

void main() 

{ 

FILE *fp; 
int c; 

fp = fopen( "file", "r" ); 
if( fp != NULL ) { 

while( (c = _ getw( fp )) != EOF ) 

_putw( c, stdout ); 
fclose ( fp ); 

} 

} 

WATCOM 

All, Linux, RDOS, Netware 
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getwindowcoord 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <graph.h> 

struct _ wxycoord _ FAR _ getwindowcoord( short x, short y ); 

The _ getwindowcoord function returns the window coordinates of the position with view 
coordinates (x,y) . Window coordinates are defined by the _ setwindow function. 

The _ getwindowcoord function returns the window coordinates, as a_ wxycoord structure, of the 
given point. 

_ setwindow^. getviewcoord 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

struct xycoord centre; 
struct _ wxycoord posl, pos2; 

/* draw a box 50 pixels square */ 

/* in the middle of the screen */ 

_ setvideomode( _ MAXRESMODE ); 

centre = _ getviewcoord_ w ( 0.5, 0.5 ); 

posl = _ getwindowcoord( centre.xcoord - 25, 

centre.ycoord - 25 ); 

pos2 = _ getwindowcoord( centre.xcoord + 25, 

centre.ycoord + 25 ); 

_ rectangle_ wxy ( _ GBORDER, &posl, &pos2 ); 
getch(); 

_ setvideomode( _DEFAULTMODE ) ; 

} 

PC Graphics 
DOS 
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gmtime Functions 


Synopsis: 


Safer C: 

Description: 


Returns: 
See Also: 

Example: 


♦include <time.h> 

struct tm * gmtime( const time_ t *timer ); 
struct tm *_ gmtime( const time_ t *timer, 

struct tm *tmbuf ); 

struct tm { 


int 

tm_ 

sec; 

/* 

seconds after the minute — 

[0,61] 

*/ 

int 

tm_ 

min; 

/* 

minutes after the hour — 

[0,59] 

*/ 

int 

tm_ 

hour; 

/* 

hours after midnight — 

[0,23] 

*/ 

int 

tm_ 

mday; 

/* 

day of the month — 

[1,31] 

*/ 

int 

tm_ 

mon; 

/* 

months since January 

[0,11] 

*/ 

int 

tm_ 

year; 

/* 

years since 1900 


*/ 

int 

tm_ 

wday; 

/* 

days since Sunday — 

[0, 6] 

*/ 

int 

tm_ 

yday; 

/* 

days since January 1 

[0,365' 

1 */ 

int 

tm_ 

isdst; 

/* 

Daylight Savings Time flag * 

/ 



} ; 


The Safer C Library extension provides the gmtime_ s function which is a safer alternative to 
gmtime This newer gmtime_ s function is recommended to be used instead of the traditional "unsafe" 
gmtime function. 

The gmt ime functions convert the calendar time pointed to by timer into a broken-down time, 
expressed as Coordinated Universal Time (UTC) (formerly known as Greenwich Mean Time, or GMT). 

The function _ gmt ime places the converted time in thetm structure pointed to by tmbuf and the 
gmtime function places the converted time in a static structure that is re-used each time gmtime is 
called. 


The time set on the computer with the DOS time command and the DOS date command reflects the 
local time. The environment variable TZ is used to establish the time zone to which this local time 
applies. See the section The TZ Environment Variable for a discussion of how to set the time zone. 

The gmtime functions return a pointer to a structure containing the broken-down time. 

a set ime Functions, asctime_ s,clock, ct ime Functions, ctime_ s,difftime, gmtime_ s, 
localtime, localtime_ sjnktime, strftime, time, tzset 


♦include <stdio.h> 
♦include <time.h> 


void main() 

{ 

time_ t time_ of_ day; 
auto char buf[26]; 
auto struct tm tmbuf; 


} 


time_ of_ day = time ( NULL ) ; 

_ gmtime( &time_ of_ day, &tmbuf ) ; 
printf ( "It is now: %.24s GMT\n", 

_ asetime( &tmbuf, buf ) ) ; 


produces the following: 


418 Library Functions and Macros 




gmtime Functions 


It is now: Fri Dec 25 15:58:27 1987 GMT 

Classification: ISO C 

_gmtime is WATCOM 

Systems: gmtime - All, Linux, RDOS, Netware 

_ gmtime - All, Linux, RDOS 
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gmtime^s 


Synopsis: 


Constraints: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <time.h> 

struct tm * gmtime_ s ( const time_ t * restrict timer, 

struct tm * restrict result ); 


struct 

tm { 





int 

tm_ sec; 

/* 

seconds after the minute — 

[0,61] 

*/ 

int 

tm_ min; 

/* 

minutes after the hour — 

[0,59] 

*/ 

int 

tm_ hour; 

/* 

hours after midnight — 

[0,23] 

*/ 

int 

tm_ mday; 

/* 

day of the month — 

[1,31] 

*/ 

int 

tm_ mon; 

/* 

months since January 

[0,11] 

*/ 

int 

tm_ year; 

/* 

years since 1900 


*/ 

int 

tm_ wday; 

/* 

days since Sunday — 

[0, 6] 

*/ 

int 

tm_ yday; 

/* 

days since January 1 

[0,365' 

1 */ 

int 

tm_ isdst; 

/* 

Daylight Savings Time flag * 

/ 



} ; 


If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and gmt ime_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither timer nor result shall be a null pointer. If there is a runtime-constraint violation, there is no 
attempt to convert the time. 

The gmtime_ s function converts the calendar time pointed to by timer into a broken-down time, 
expressed as UTC. The broken-down time is stored in the structure pointed to by result. 

The gmtime_ s function returns result, or a null pointer if the specified time cannot be converted to 
UTC or there is a runtime-constraint violation. 

asctime Functions, asctime_ s.clock, ctime Functions, ctime_ s.difftime, gmtime, 
localtime, localtime_ sjnktime, strftime, time, tzset 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <time.h> 

void main() 

{ 

time_ t time_ of_ day; 
auto char buf[26]; 
auto struct tm tmbuf; 

time_ of_ day = time ( NULL ) ; 
gmtime_ s ( &time_ of_ day, &tmbuf ) ; 
asctime_ s ( buf, sizeof( buf ), Stmbuf ); 
printf ( "It is now: %.24s GMT\n", buf ); 

} 

produces the following: 

It is now: Thu Jan 31 15:12:27 2006 GMT 
TR 24731 
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gmtime^s 


Systems: 


DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS, Netware 
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grow_handles 


Synopsis: 

Description: 


Returns: 

Errors: 
See Also: 

Example: 


♦include <stdio.h> 

int _ grow_ handles ( int new_ count ) ; 

The _ grow_ handles function increases the number of POSIX level files that are allowed to be open 
at one time. The parameter new_count is the new requested number of files that are allowed to be 
opened. The return value is the number that is allowed to be opened after the call. This may be less 
than, equal to, or greater than the number requested. If the number is less than, an error has occurred 
and the errno variable should be consulted for the reason. If the number returned is greater than or 
equal to the number requested, the call was successful. 

Note that even if _ grow_ handles returns successfully, you still might not be able to open the 
requested number of files due to some system limit (e.g. FILES= in the CONFIG.SYS file under DOS) 
or because some file handles are already in use (stdin, stdout, stderr, etc.). 

The number of file handles that the run-time system can open by default is described by _ NFILES in 
<stdio . h> but this can be changed by the application developer. To change the number of file 
handles available during execution, follow the steps outlined below. 

1. Let n represent the number of files to be opened concurrently. Ensure that the stdin, stdout, 
and stderr files are included in the count. Also include stdaux and stdprn files in the count 
for some versions of DOS. The stdaux and stdprn files are not available for Win32. 

2. For DOS-based systems, change the CONFIG. SYS file to include "FILES=n" where "n" is 
the number of file handles required by the application plus an additional 5 handles for the 
standard files. The number of standard files that are opened by DOS varies from 3 to 5 
depending on the version of DOS that you are using. 

If you are running a network such as Novell’s NetWare, this will also affect the number of 
available file handles. In this case, you may have to increase the number specified in the 
"FILES=n" statement. 

3. Add a call to _ grow_ handles in your application similar to that shown in the example 
below. 

The _ grow_ handles function returns the maximum number of file handles which the run-time 
system can accommodate. This number can exceed an operating system limit such as that imposed by 
the "FILES=" statement under DOS. This limit will be the determining factor in how many files can be 
open concurrently. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 

_ dos_ openfdopen, fileno, fopen, freopen, _ f sopen,_ hdopen,open, 

_ open_ osfhandlej_ popen,sopen, tmpfile 

♦include <stdio.h> 

FILE *fp[ 50 ]; 

void main() 

{ 

int hndl_ count; 
int i; 
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grow_handles 


Classification: 

Systems: 


hndl_ count = _NFILES; 
if( hndl_ count < 50 ) { 

hndl_ count = _ grow_ handles ( 50 ) ; 

} 

for( i = 0; i < hndl_ count; i++ ) { 

fp [ i ] = tmpfileO; 
if( fp[ i ] == NULL ) break; 

printf( "File %d successfully opened\n", i ); 

} 

printf( "%d files were successfully opened\n", i ); 


WATCOM 
All, Linux 
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grstatus 


Synopsis: 

Description: 


Returns: 

Example: 


Classification: 

Systems: 


♦include <graph.h> 

short _ FAR _ grstatus ( void ) ; 

The _ grstatus function returns the status of the most recently called graphics library function. The 
function can be called after any graphics function to determine if any errors or warnings occurred. The 
function returns 0 if the previous function was successful. Values less than 0 indicate an error occurred; 
values greater than 0 indicate a warning condition. 

The following values can be returned: uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 
uindex=2 uindex=2 uindex=2 uindex=2 


Constant 

Value 

Explanation 

_ GROK 

0 

no error 

_ GRERROR 

-1 

graphics error 

_ GRMODENOTSUPPORTED 

-2 

video mode not supported 

_ GRNOTINPROPERMODE 

-3 

function n/a in this mode 

_ GRINVALIDPARAMETER 

-4 

invalid parameter(s) 

_ GRINSUFFICIENTMEMORY 

-5 

out of memory 

_ GRFONTFILENOTFOUND 

-6 

can't open font file 

_ GRINVALIDFONTFILE 

-7 

font file has invalid format 

_ GRNOOUTPUT 

1 

nothing was done 

_ GRCLIPPED 

2 

output clipped 


The _ grstatus function returns the status of the most recently called graphics library function. 

♦include <conio.h> 

♦include <graph.h> 

♦include <stdlib.h> 

main () 

{ 

int x, y; 


setvideomode ( _VRES16C0L0R ); 


while ( _ grstatus 

0 == _ GROK ) 

{ 

x = rand() 

"6 

700; 


y = rand() 

~o 

500; 


_ setpixel ( 

X 

, y ); 



} 

getch (); 

_ setvideomode( _ DEFAULTMODE ); 


PC Graphics 
DOS 
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grtext Functions 


Synopsis: #include <graph.h> 

short _ FAR _ grtext( short x, short y, 

char _ FAR *text ); 

short _ FAR _grtext_w( double x, double y, 

char _ FAR *text ) ; 

Description: The _ grtext functions display a character string. The_ grtext function uses the view coordinate 
system. The _ grtext_ w function uses the window coordinate system. 

The character string text is displayed at the point (x, y) . The string must be terminated by a null 
character (’\0’)- The text is displayed in the current color using the current text settings. 

The graphics library can display text in three different ways. 

1. The _ outtext and_ outmem functions can be used in any video mode. However, this 
variety of text can be displayed in only one size. 

2. The _ grtext function displays text as a sequence of line segments, and can be drawn in 
different sizes, with different orientations and alignments. 

3. The _ outgtext function displays text in the currently selected font. Both bit-mapped and 
vector fonts are supported; the size and type of text depends on the fonts that are available. 

Returns: The _ grtext functions return a non-zero value when the text was successfully drawn; otherwise, zero 

is returned. 

See Also: _ outtext^ outmem^ outgtext^ setcharsize^ settextalign,_ settextpath, 

_ settextorient,_ setcharspacing 

Example: #include <conio.h> 

♦include <graph.h> 

main() 

{ 

_ setvideomode ( _VRES16COLOR ); 

_ grtext( 200, 100, " WATCOM" ); 

_ grtext( 200, 200, "Graphics" ); 
getch() ; 

_ setvideomode( _ DEFAULTMODE ); 

} 

produces the following: 
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grtext Functions 



Classification: PC Graphics 

Systems: _ grtext - DOS 

_ grtext_ w - DOS 


426 Library Functions and Macros 





halloc 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


#include <malloc.h> 

void_huge *halloc( long int numb, size_ t size ); 

The halloc function allocates space for an array of numb objects of size bytes each and initializes 
each object to 0. When the size of the array is greater than 64K bytes, then the size of an array element 
must be a power of 2 since an object could straddle a segment boundary. 

The halloc function returns a far pointer (of type void huge *) to the start of the allocated 
memory. The NULL value is returned if there is insufficient memory available. The NULL value is also 
returned if the size of the array is greater than 64K bytes and the size of an array element is not a power 
of 2. 

calloc Functions, _ expand Functions,f ree Functions, hf ree, malloc Functions, _ msize 
Functions, realloc Functions, sbrk 

♦include <stdio.h> 

♦include <malloc.h> 

void main() 

{ 

long int_huge *big_ buffer; 

big_ buffer = (long int_huge *) 

halloc( 1024L, sizeof(long) ); 
if( big_ buffer == NULL ) { 

printf ( "Unable to allocate memory\n" ); 

} else { 

/* rest of code goes here */ 

hfree ( big_ buffer ); /* deallocate */ 

} 

} 

WATCOM 

DOS/16, Windows, OS/2 l.x(all) 
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harden, _hardresume, _hardretn 


Synopsis: #include <dos.h> 

void _ harderr( int (_far *handler) () ); 

void _ hardresume( int action ); 
void _ hardretn( int error ); 

Description: The _ harderr routine installs a critical error handler (for INT 0x24) to handle hardware errors. This 
critical error handler will call the user-defined function specified by handler when a critical error occurs 
(for example, attempting to open a file on a floppy disk when the drive door is open). The parameters 
to this function are as follows: 

int handler( unsigned deverror, 
unsigned errcode, 
unsigned_far *devhdr ) ; 

The low-order byte of errcode can be one of the following values: 

Value Meaning 

0x00 Attempt to write to a write-protected disk 

0x01 Unknown unit 

0x02 Drive not ready 

0x03 Unknown command 

0x04 CRC error in data 

0x05 Bad drive-request structure length 

0x06 Seek error 

0x07 Unknown media type 

0x08 Sector not found 

0x09 Printer out of paper 

0x0A Write fault 

OxOB Read fault 

OxOC General failure 

The devhdr argument points to a device header control-block that contains information about the device 
on which the error occurred. Your error handler may inspect the information in this control-block but 
must not change it. 

If the error occurred on a disk device, bit 15 of the deverror argument will be 0 and the deverror 
argument will indicate the following: 


Bit 

Meaning 

bit 15 

0 indicates 

bit 14 

not used 

bit 13 

0 indicates 

bit 12 

0 indicates 

bit 11 

0 indicates 

bit 9,10 

location of 


Value 


00 

01 


disk error 

"Ignore" response not allowed 
"Retry" response not allowed 
"Fail" response not allowed 
error 

Meaning 

MS-DOS 

File Allocation Table (FAT) 
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Returns: 

See Also: 
Example: 


harden, _hardresume, _hardretn 


10 Directory 

11 Data area 

bit 8 0 indicates read error, 1 indicates write error 


The low-order byte of deverror indicates the drive where the error occurred; (0 = drive A, 1 = drive B, 
etc.). 

The handler is very restricted in the type of system calls that it can perform. System calls 0x01 through 
OxOC, and 0x59 are the only system calls allowed to be issued by the handler. Therefore, many of the 
standard C run-time functions such as stream I/O and low-level I/O cannot be used by the handler. 
Console I/O is allowed (e.g., cprintf, cputs). 

The handler must indicate what action to take by returning one of the following values or calling 
_ hardresume with one of the following values: 


Value 

_HARDERR_IGNORE 

_HARDERR_RETRY 

_HARDERR_ABORT 

_HARDERR_FAIL 


Meaning 

Ignore the error 

Retry the operation 

Abort the program issuing INT 0x23 

Fail the system call that is in progress (DOS 3.0 or higher) 


Alternatively, the handler can return directly to the application program rather than returning to DOS by 
using the _ hardretn function. The application program resumes at the point just after the failing I/O 
function request. The _ hardretn function should be called only from within a user-defined hardware 
error-handler function. 


The error argument of _ hardretn should be a DOS error code. See The MS-DOS Encyclopedia or 
Programmer’s PC Sourcebook, 2nd Edition, for more detailed information on DOS error codes that 
may be returned by a given DOS function call. 

If the failing I/O function request is an INT 0x21 function greater than or equal to function 0x38, 

_ hardretn will return to the application with the carry flag set and the AX register set to the 
_ hardretn error argument. If the failing INT 0x21 function request is less than function 0x38 abd 
the function can return an error, the AL register will be set to OxFF on return to the application. If the 
failing INT 0x21 function does not have a way of returning an error condition (which is true of certain 
INT 0x21 functions below 0x38), the error argument of _ hardretn is not used, and no error code is 
returned to the application. 

These functions do not return a value. The _ hardresume and_ hardretn functions do not return 
to the caller. 


chain_ intr^ dos_ getvect*. dos_ setvect 
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harden, _hardresume, _hardretn 


♦include <stdio.h> 

♦include <conio.h> 

♦include <dos.h> 

♦ if defined (_DOS ) && defined ( 386_) 

♦ define FAR_far 

♦ else 

♦ if defined(_ 386_) 

♦define FAR 

♦ else 

♦ define FAR_far 

♦endif 

♦endif 

int FAR critical_ error_ handler ( unsigned deverr, 

unsigned errcode, 
unsigned FAR *devhdr ) 

{ 

cprintf( "Critical error: " ); 
cprintf( "deverr=%4.4X errcode=%d\r\n", 
deverr, errcode ) ; 

cprintf( "devhdr = %Fp\r\n", devhdr ); 
return( _ HARDERR_ IGNORE ); 

} 

main () 

{ 

FILE *fp; 

_ harderr ( critical_ error_ handler ); 
fp = fopen( "a:tmp.tmp", "r" ); 
printf( "fp = %p\n", fp ); 

} 

produces the following: 

Critical error: deverr=lA00 errcode=2 
devhdr = 0070:01b6 
fp = 0000 

Classification: DOS 

Systems: _ harderr - DOS 

_ hardresume - DOS 
_ hardretn - DOS/16 
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hdopen 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <io.h> 

int _ hdopen ( int os_ handle, int mode ); 

The _ hdopen function takes a previously opened operating system file handle specified by osjicmdle 
and opened with access and sharing specified by mode , and creates a POSIX-style file handle. 

The _ hdopen function returns the new POSIX-style file handle if successful. Otherwise, it returns -1. 

close, _ dos_ openfdopen, fopen, freopen, _ fsopen^_ grow_ handlesopen, 

_ open_ osfhandlej. os_ handle^, popen,sopen 

♦include <stdio.h> 

♦include <dos.h> 

♦include <fcntl.h> 

♦include <io.h> 

♦include <windows.h> 

void main() 

{ 

HANDLE os_ handle; 

DWORD desired_ access, share_ mode; 
int handle; 

os_ handle = CreateFileA( "file", GENERIC_ WRITE, 

0, NULL, C RE AT E_ ALWAYS, 

FILE_ ATTRIBUTE_ NORMAL, NULL ); 

if ( os_ handle == INVALID_ HANDLE_ VALUE ) { 

printf ( "Unable to open file\n" ); 

} else { 

handle = _ hdopen ( os_ handle, 0_ RDONLY ); 
if( handle != -1 ) { 

write( handle, "hello\n", 6 ); 
close ( handle ); 

} else { 

CloseHandle ( os_ handle ); 


} 

} 

WATCOM 

All, Linux, Netware 
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heapchk Functions 


Synopsis: 

Description: 


Returns: 


See Also: 
Example: 


♦include <malloc.h> 
int _ heapchk ( void ) ; 

int _ bheapchk (_segment seg ) ; 

int _ fheapchk( void ); 
int _ nheapchk ( void ) ; 

The _ heapchk functions along with_ heapset and_ heapwalk are provided for debugging heap 
related problems in programs. 

The _ heapchk functions perform a consistency check on the unallocated memory space or "heap". 
The consistency check determines whether all the heap entries are valid. Each function checks a 
particular heap, as listed below: 


Function 

Jieapchk 

_bheapchk 

Jheapchk 

jiheapchk 


Heap Checked 

Depends on data model of the program 

Based heap specified by seg value; _ NULLSEG specifies all based heaps 
Far heap (outside the default data segment) 

Near heap (inside the default data segment) 


In a small data memory model, the _ heapchk function is equivalent to the_ nheapchk function; in a 
large data memory model, the _ heapchk function is equivalent to the_ fheapchk function. 


All four functions return one of the following manifest constants which are defined in <malloc. h> . 


Constant 

Meaning 

_HEAPOK 

The heap appears to be consistent. 

_HEAPEMPTY 

The heap is empty. 

_HEAPBADBEGIN The heap has been damaged. 

_HEAPBADNODE 

The heap contains a bad node, or is damaged. 


_ heapenable,_ heapgrow,_ heapmin,_ heapset,_ heapshrink,_ heapwalk 

♦include <stdio.h> 

♦include <malloc.h> 

void main() 

{ 

char *buffer; 
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heapchk Functions 


buffer = (char *)malloc( 80 ); 

malloc ( 1024 ) ; 

free( buffer ); 

switch ( _ heapchk () ) { 

case _ HEAPOK: 

printf( "OK - heap is good\n" ); 
break; 

case _ HEAPEMPTY: 

printf( "OK - heap is empty\n" ); 
break; 

case _ HEAPBADBEGIN: 

printf( "ERROR - heap is damaged\n" ); 
break; 

case _ HEAPBADNODE: 

printf( "ERROR - bad node in heap\n" ); 
break; 

} 

} 

Classification: WATCOM 

Systems: _ heapchk - All, Linux, RDOS 

_ bheapchk - DOS/16, Windows, OS/2 l.x(all) 

_ fheapchk - DOS/16, Windows, OS/2 l.x(all) 

_ nheapchk - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 l.x(MT), 
OS/2-32, Linux, RDOS 
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heapenable 


Synopsis: #include <malloc.h> 

int _ heapenable( int enabled ); 

Description: The _ heapenable function is used to control attempts by the heap allocation manager to request 
more memory from the operating system’s memory pool. If enabled is 0 then all further allocations 
which would normally go to the operating system for more memory will instead fail and return NULL. 
If enabled is 1 then requests for more memory from the operating system’s memory pool are re-enabled. 

This function can be used to impose a limit on the amount of system memory that is allocated by an 
application. For example, if an application wishes to allocate no more than 200K bytes of memory, it 
could allocate 200K and immediately free it. It can then call _ heapenable to disable any further 
requests from the system memory pool. After this, the application can allocate memory from the 200K 
pool that it has already obtained. 

Returns: The return value is the previous state of the system allocation flag. 

See Also: _ heapchk,_ heapgrow,_ heapmin,_ heapset,_ heapshrink,_ heapwalk 

Example: #include <stdio.h> 

♦include <malloc.h> 

void main() 

{ 

char *p; 

p = malloc ( 200*1024 ) ; 
if( p != NULL ) free ( p ); 

_ heapenable( 0 ); 

/* 

allocate memory from a pool that 
has been capped at 200K 

*/ 

} 

Classification: WATCOM 
Systems: All, Linux, RDOS 
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heapgrow Functions 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


♦include <malloc.h> 
void _ heapgrow ( void ); 
void _ nheapgrow ( void ) ; 
void _ fheapgrow ( void ) ; 

The _ nheapgrow function attempts to grow the near heap to the maximum size of 64K. You will 
want to do this in the small data models if you are using both malloc and _ fmalloc orhalloc. 
Once a call to _ fmalloc orhalloc has been made, you may not be able to allocate any memory 
with malloc unless space has been reserved for the near heap using either malloc, sbrk or 
_ nheapgrow. 

The _ fheapgrow function doesn’t do anything to the heap because the far heap will be extended 
automatically when needed. If the current far heap cannot be extended, then another far heap will be 
started. 

In a small data memory model, the _ heapgrow function is equivalent to the_ nheapgrow function; 
in a large data memory model, the _ heapgrow function is equivalent to the_ fheapgrow function. 

These functions do not return a value. 

_ heapchk,_ heapenable,_ heapmin,_ heapset,_ heapshrink^ heapwalk 

♦include <stdio.h> 

♦include <malloc.h> 

void main() 

{ 

char *p, *fmt_ string; 

fmt_ string = "Amount of memory available is %u\n"; 
printf ( fmt_ string, _ memavl () ); 

_ nheapgrow() ; 

printf ( fmt_ string, _ memavl () ); 

p = (char *) malloc( 2000 ); 
printf ( fmt_ string, _ memavl () ); 

} 

produces the following: 

Amount of memory available is 0 
Amount of memory available is 62732 
Amount of memory available is 60730 

WATCOM 

_ heapgrow - All, Linux, RDOS 
_ fheapgrow - DOS/16, Windows, OS/2 l.x(all) 

_ nheapgrow - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 l.x(MT), 
OS/2-32, Linux, RDOS 
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heapmin Functions 


Synopsis: #include <malloc.h> 

int _ heapmin ( void ) ; 

int _ bheapmin (_segment seg ) ; 

int _ fheapmin ( void ) ; 
int _ nheapmin ( void ) ; 

Description: The _ heapmin functions attempt to shrink the specified heap to its smallest possible size by returning 
all free entries at the end of the heap back to the system. This can be used to free up as much memory 
as possible before using the system function or one of the spawn . . . functions. 

The various _ heapmin functions shrink the following heaps: 

Function Heap Minimized 

Jieapmin Depends on data model of the program 

Jbheapmin Based heap specified by seg value; _ NULLSEG specifies all based heaps 

_Jheapmin Far heap (outside the default data segment) 

j/iheapmin Near heap (inside the default data segment) 

In a small data memory model, the _ heapmin function is equivalent to the_ nheapmin function; in a 
large data memory model, the _ heapmin function is equivalent to the_ fheapmin function. It is 
identical to the _ heapshrink function. 

Returns: These functions return zero if successful, and non-zero if some error occurred. 

See Also: _ heapchk,_ heapenable,_ heapgrow,_ heapset^ heapshrink,_ heapwalk 

Example: #include <stdlib.h> 

♦include <malloc.h> 

void main() 

{ 

_ heapmin(); 

system( "chdir c:\\watcomc" ); 

} 

Note the use of two adjacent backslash characters (\) within character-string constants to signify a single 
backslash. 

Classification: WATCOM 

Systems: _ heapmin - All, Linux, RDOS 

_bheapmin - DOS/16, Windows, OS/2 1.x(all) 

_ fheapmin - DOS/16, Windows, OS/2 l.x(all) 

_ nheapmin - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 l.x(MT), 
OS/2-32, Linux, RDOS 
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heapset Functions 


Synopsis: #include <malloc.h> 

int _ heapset ( unsigned int fill_ char ) ; 

int _ bheapset (_segment seg, unsigned int fill_ char ) ; 

int _ fheapset ( unsigned int fill_ char ) ; 
int _ nheapset ( unsigned int fill_ char ) ; 

Description: The _ heapset functions along with_ heapchk and_ heapwalk are provided for debugging heap 
related problems in programs. 

The _ heapset functions perform a consistency check on the unallocated memory space or "heap" just 
as _ heapchk does, and sets the heap’s free entries with the fill_char value. 

Each function checks and sets a particular heap, as listed below: 

Function Heap Filled 

Jieapset Depends on data model of the program 

_bheapset Based heap specified by seg value; _ NULLSEG specifies all based heaps 

Jheapset Far heap (outside the default data segment) 

jiheapset Near heap (inside the default data segment) 

In a small data memory model, the _ heapset function is equivalent to the_ nheapset function; in a 
large data memory model, the _ heapset function is equivalent to the_ fheapset function. 

Returns: The _ heapset functions return one of the following manifest constants which are defined in 

<malloc.h>. 

Constant Meaning 

_HEAPOK The heap appears to be consistent. 

_HEAPEMPTY The heap is empty. 

_HEAPBADBEGIN The heap has been damaged. 

_HEAPBADNODE The heap contains a bad node, or is damaged. 

See Also: _ heapchk,_ heapenable,_ heapgrow,_ heapmin,_ heapshrink,_ heapwalk 

Example: ((include <stdio.h> 

((include <malloc.h> 

void main() 

{ 

int heap_ status; 
char *buffer; 
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heapset Functions 


buffer = (char *)malloc( 80 ); 
malloc ( 1024 ) ; 
free( buffer ); 

heap_ status = _ heapset ( Oxff ) ; 
switch ( heap_ status ) { 

case _ HEAPOK: 

printf( "OK - heap is good\n" ); 
break; 

case _ HEAPEMPTY: 

printf( "OK - heap is empty\n" ); 
break; 

case _ HEAPBADBEGIN: 

printf( "ERROR - heap is damaged\n" ); 
break; 

case _ HEAPBADNODE: 

printf( "ERROR - bad node in heap\n" ); 
break; 

} 

} 

Classification: WATCOM 

Systems: _ heapset - All, Linux, RDOS 

_ bheapset - DOS/16, Windows, OS/2 l.x(all) 

_ fheapset - DOS/16, Windows, OS/2 l.x(all) 

_ nheapset - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 l.x(MT), 
OS/2-32, Linux, RDOS 
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heapshrink Functions 


Synopsis: #include <malloc.h> 

int _ heapshrink ( void ) ; 

int _ bheapshrink (_segment seg ) ; 

int _ fheapshrink ( void ) ; 
int _ nheapshrink ( void ) ; 

Description: The _ heapshrink functions attempt to shrink the heap to its smallest possible size by returning all 
free entries at the end of the heap back to the system. This can be used to free up as much memory as 
possible before using the system function or one of the spawn. . . functions. 

The various _ heapshrink functions shrink the following heaps: 

Function Heap Shrinked 

Jieapshrink Depends on data model of the program 

_bheapshrink Based heap specified by seg value; _ NULLSEG specifies all based heaps 

^fheapshrink Far heap (outside the default data segment) 

jiheapshrink Near heap (inside the default data segment) 

In a small data memory model, the _ heapshrink function is equivalent to the_ nheapshrink 
function; in a large data memory model, the _ heapshrink function is equivalent to the 
_ fheapshrink function. It is identical to the_ heapmin function. 

Returns: These functions return zero if successful, and non-zero if some error occurred. 

See Also: _ heapchk,_ heapenable,_ heapgrow,_ heapmin,_ heapset,_ heapwalk 

Example: #include <stdlib.h> 

♦include <malloc.h> 

void main() 

{ 

_ heapshrink (); 

system( "chdir c:\\watcomc" ); 

} 

Note the use of two adjacent backslash characters (\) within character-string constants to signify a single 
backslash. 

Classification: WATCOM 

Systems: _ heapshrink - All, Linux, RDOS 

_bheapshrink - DOS/16, Windows, OS/2 l.x(all) 

_ fheapshrink - DOS/16, Windows, OS/2 l.x(all) 

_ nheapshrink - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 l.x(MT), 
OS/2-32, Linux, RDOS 
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heapwalk Functions 


Synopsis: #include <malloc.h> 

int _ heapwalk( struct _ heapinfo *entry ); 

int _bheapwalk( _segment seg, struct _ heapinfo *entry ); 

int _ fheapwalk ( struct _ heapinfo *entry ); 
int _ nheapwalk( struct _ heapinfo *entry ); 

struct _ heapinfo { 

void_far *_ pentry; 

size_ t _ size; 

int _ useflag; 

} ; 

♦define _ USEDENTRY 0 

♦define _ FREEENTRY 1 

Description: The _ heapwalk functions along with_ heapchk and_ heapset are provided for debugging heap 
related problems in programs. 

The _ heapwalk functions walk through the heap, one entry per call, updating the_ heapinfo 
structure with information on the next heap entry. The structure is defined in <malloc.h>. You 
must initialize the _pentry field with NULL to start the walk through the heap. 

Each function walks a particular heap, as listed below: 

Function Heap Walked 

Jieapwalk Depends on data model of the program 

_bheapwalk Based heap specified by seg value; _ NULLSEG specifies all based heaps 

_fheapwalk Far heap (outside the default data segment) 

_nheapwalk Near heap (inside the default data segment) 

In a small data memory model, the _ heapwalk function is equivalent to the_ nheapwalk function; 
in a large data memory model, the _ heapwalk function is equivalent to the_ fheapwalk function. 

Returns: These functions return one of the following manifest constants which are defined in <malloc . h> . 

Constant Meaning 

_HEAPOK The heap is OK so far, and the _ heapinfo structure contains information about 

the next entry in the heap. 

_HEAPEMPTY The heap is empty. 

_HEAPBADPTR The _ pentry field of the entry structure does not contain a valid pointer into the 
heap. 

_HEAPBADBEGIN The header information for the heap was not found or has been damaged. 
_HEAPBADNODE The heap contains a bad node, or is damaged. 

_HEAPEND The end of the heap was reached successfully. 


/* heap pointer */ 

/* heap entry size */ 

/* heap entry 'in-use' flag */ 
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heapwalk Functions 


See Also: 
Example: 


_ heapchk,_ heapenable,_ heapgrow,_ heapmin,_ heapset,_ heapshrink 

♦include <stdio.h> 

♦include <malloc.h> 

heap_ dump() 

{ 

struct _ heapinfo h_ info; 
int heap_ status; 

h_ inf o pentry = NULL; 
for(;;) { 

heap_ status = _ heapwalk ( &h_ info ) ; 

if ( heap_ status != _ HEAP OK ) break; 

printf( " %s block at %Fp of size %4.4X\n", 

(h_ info._ useflag == _ USEDENTRY ? "USED" : "FREE"), 
h_ inf o pentry, h_ info._ size ); 

} 

switch ( heap_ status ) { 

case _ HEAPEND: 

printf ( "OK - end of heap\n" ); 
break; 

case _ HEAPEMPTY: 

printf( "OK - heap is empty\n" ) ; 
break; 

case _ HEAPBADBEGIN: 

printf( "ERROR - heap is damaged\n" ); 
break; 

case _ HEAPBADPTR: 

printf( "ERROR - bad pointer to heap\n" ); 
break; 

case _ HEAPBADNODE: 

printf( "ERROR - bad node in heap\n" ); 

} 

} 

void main() 

{ 

char *p; 

heap_ dump(); p = (char *) malloc( 80 ); 
heap_ dump () ; free ( p ) ; 
heap_ dump () ; 


produces the following: 

On 16-bit 80x86 systems, the following output is produced: 


OK - heap is empty 


USED 

block 

at 

23f8:0ab6 

of 

size 

0202 

USED 

block 

at 

23f8:0cb8 

of 

size 

0052 

FREE 

block 

at 

23f8:OdOa 

of 

size 

1DA2 

OK - end of ! 

heap 




USED 

block 

at 

23f8:0ab6 

of 

size 

0202 

FREE 

block 

at 

23f8:0cb8 

of 

size 

1DF4 


OK - end of heap 
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heapwalk Functions 


Classification: 

Systems: 


On 32-bit 80386/486 systems, the following output is produced: 


OK - heap is empty 


USED 

block 

at 

0014:00002a7c 

of 

size 

0204 

USED 

block 

at 

0014:00002c80 

of 

size 

0054 

FREE 

block 

at 

0014:00002cd4 

of 

size 

1D98 

OK - end of heap 
USED block at 

0014:00002a7c 

of 

size 

0204 

FREE 

block 

at 

0014:00002c80 

of 

size 

1DEC 


OK - end of heap 


WATCOM 

_ heapwalk - All, Linux, RDOS 
_ bheapwalk - DOS/16, Windows, OS/2 1.x(all) 

_ fheapwalk - DOS/16, Windows, OS/2 l.x(all) 

_ nheapwalk - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 l.x(MT), 
OS/2-32, Linux, RDOS 
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hfree 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


#include <malloc.h> 

void hfree( void _ huge *ptr ); 

The hfree function deallocates a memory block previously allocated by the halloo function. The 
argument ptr points to a memory block to be deallocated. After the call, the freed block is available for 
allocation. 

The hfree function returns no value. 

calloc Functions, _ expand Functions,free Functions, halloo, malloc Functions, _ msize 
Functions, realloc Functions, sbrk 

#include <stdio.h> 

♦include <malloc.h> 

void main() 

{ 

long int_huge *big_ buffer; 

big_ buffer = (long int_huge *) 

halloc( 1024L, sizeof(long) ); 
if( big_ buffer == NULL ) { 

printf ( "Unable to allocate memory\n" ); 

} else { 

/* rest of code goes here */ 

hfree ( big_ buffer ); /* deallocate */ 

} 

} 

WATCOM 

DOS/16, Windows, OS/2 l.x(all) 
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hypot 


Synopsis: 

Description: 

Returns: 

Example: 


Classification: 

Systems: 


#include <math.h> 

double hypot( double x, double y ); 

The hypot function computes the length of the hypotenuse of a right triangle whose sides are x and y 
adjacent to that right angle. The calculation is equivalent to 

sqrt( x*x + y*y ) 

The computation may cause an overflow, in which case the matherr function will be invoked. 

The value of the hypotenuse is returned. When an error has occurred, errno contains a value 
indicating the type of error that has been detected. 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", hypot( 3.0, 4.0 ) ); 

} 

produces the following: 

5.000000 

WATCOM 

Math 


444 Library Functions and Macros 




ignore_handler_s 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦ define_ STDC_ WANT_ LIB_ EXT1 1 

♦include <stdlib.h> 

void ignore_ handler_ s ( 

const char * restrict msg, 
void * restrict ptr, 
errno_ t error ); 

A pointer to the ignore_ handler_ s function may be passed as an argument to the 

set_ constraint handler_ s function. Thegnore_ handler_ s function simply returns to 

its caller. 

The ignore_ handler_ s function does not returns no value. 
abort_ handler_ s$et_ constraint handler_ s 

♦ define_ STDC_ WANT_ LIB_ EXT1 1 

♦include <stdlib.h> 

♦include <stdio.h> 

void main( void ) 

{ 

constraint handler_ t old_ handler; 
old_ handler = 

set_ constraint handler_ s ( ignore_ handler_ s ) ; 
if( getenv_ s ( NULL, NULL, 0, NULL ) ) { 

printf ( "getenv_ s failed\n" ); 

} 

set_ constraint handler_ s ( old_ handler ) ; 

} 

produces the following: 
getenv_ s failed 
TR 24731 

All, Linux, RDOS, Netware 
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ilogb 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <math.h> 
int ilogb( double x ); 

The ilogb function returns the exponent portion of the argument x as an int. 

If successful, the return value is the exponent of x. When the argument is zero, the function returns 
FP_ILOGBO. When the argument is not-a-number, or NAN, the function returns FP_ILOGBNAN. For 
positive or negative infinity, the function returns INT_MAX. 

logb 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%d\n", ilogb( 1024.0 ) ); 

} 

produces the following: 

10 

ISO C99 
Math 
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imagesize Functions 


Synopsis: 


Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


♦include <graph.h> 

long _ FAR _ imagesize( short xl, short yl, 

short x2, short y2 ); 

long _ FAR _ imagesize_ w ( double xl, double yl, 

double x2, double y2 ); 

long _ FAR _ imagesize_ wxy ( struct _ wxycoord _ FAR *pl, 

struct _ wxycoord _ FAR *p2 ) ; 

The _ imagesize functions compute the number of bytes required to store a screen image. The 
_ imagesize function uses the view coordinate system. The_ imagesize_ w and 
_ imagesize_ wxy functions use the window coordinate system. 

The screen image is the rectangular area defined by the points (xl,yl) and (x2,y2). The storage 
area used by the _ get image functions must be at least this large (in bytes). 

The _ imagesize functions return the size of a screen image. 

_ getimage,_ putimage 

♦include <conio.h> 

♦include <graph.h> 

♦include <malloc.h> 

main () 

{ 

char *buf; 
int y; 

_ setvideomode( _ VRES16C0L0R ); 

_ ellipse( _ GFILLINTERIOR, 100, 100, 200, 200 ); 
buf = (char*) malloc( 



imagesize( 

100, 

. 100, 201, 

buf != NULL 

) { 




_ getimage( 

100, 

100, 

201, 

201, buf ) 

_ putimage( 

260, 

200, 

buf. 

_ GPSET ) ; 

_ putimage( 

420, 

100, 

buf. 

_ GPSET ) ; 


for( y = 100; y < 300; ) { 


_ putimage( 
y += 20; 

420, 

Y r 

buf, _ GXOR ); 

_ putimage( 

420, 

Yr 

buf, _ GXOR ); 


} 

free( buf ) ; 

} 

getch(); 

_ setvideomode( _ DEFAULTMODE ) ; 


PC Graphics 

_ imagesize - DOS 
_ imagesize_ w - DOS 
_ imagesize_ wxy - DOS 
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imaxabs 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <inttypes.h> 

intmax_ t imaxabs ( intmax_ t j ) ; 

The imaxabs function returns the absolute value of its maximum-size integer argument j. 

The imaxabs function returns the absolute value of its argument. 

labs, llabs, abs, fabs 

♦include <stdio.h> 

♦include <inttypes.h> 

void main( void ) 

{ 

intmax_ t x, y; 

x = -500000000000; 
y = imaxabs( x ); 

printf ( "imaxabs(% j d) = %jd\n", x, y ); 

} 

produces the following: 

imaxabs(-500000000000) = 500000000000 
ISO C99 

All, Linux, RDOS, Netware 
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imaxdiv 


Synopsis: 


Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdlib.h> 

imaxdiv_ t imaxdiv( intmax_t numer, intmax_ t denom ); 
typedef struct { 

intmax_ t quot; /* quotient */ 

intmax_ t rem; /* remainder */ 

} imaxdiv_ t; 

The imaxdiv function calculates the quotient and remainder of the division of the numerator numer by 
the denominator denom. 


The imaxdiv function returns a structure of type imaxdiv_ t that contains the fieldsquot and rem, 
which are both of type intmax_ t. 

div, ldiv, lldiv 


♦include <stdio.h> 

♦include <inttypes.h> 

void print_ time ( intmax_ t ticks ) 

{ 

imaxdiv_ t sec_ ticks; 
imaxdiv_ t min_ sec; 


} 


sec_ ticks = imaxdiv( ticks, 1000000 ); 
min_ sec = imaxdiv ( sec_ ticks . quot, 60 ); 

printf( "It took %jd minutes and %jd seconds\n", 
min_ sec . quot, min_ sec.rem ); 


void main( void ) 

{ 

print_ time( 9876543210 ); 

} 


produces the following: 

It took 164 minutes and 36 seconds 


ISO C99 


All, Linux, RDOS, Netware 
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mp 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <conio.h> 
unsigned int inp( int port ); 

The inp function reads one byte from the 80x86 hardware port whose number is given by port. 

A hardware port is used to communicate with a device. One or two bytes can be read and/or written 
from each port, depending upon the hardware. Consult the technical documentation for your computer 
to determine the port numbers for a device and the expected usage of each port for a device. 

The value returned is the byte that was read. 

inpd, inpw, outp, outpd, outpw 

♦include <conio.h> 

void main() 

{ 

/* turn off speaker */ 

outp ( 0x61, inp( 0x61 ) & OxFC ); 

} 

Intel 

All, Linux, RDOS, Netware 
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inpd 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <conio.h> 

unsigned long inpd( int port ); 

The inpd function reads a double-word (four bytes) from the 80x86 hardware port whose number is 
given by port. 

A hardware port is used to communicate with a device. One or two bytes can be read and/or written 
from each port, depending upon the hardware. Consult the technical documentation for your computer 
to determine the port numbers for a device and the expected usage of each port for a device. 

The value returned is the double-word that was read. 

inp, inpw, outp, outpd, outpw 

♦include <conio.h> 

♦define DEVICE 34 

void main() 

{ 

unsigned long transmitted; 
transmitted = inpd( DEVICE ); 

} 

Intel 

DOS/32, Win386, Win32, OS/2-32, Linux, RDOS, Netware 
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inpw 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <conio.h> 

unsigned int inpw( int port ); 

The inpw function reads a word (two bytes) from the 80x86 hardware port whose number is given by 
port. 

A hardware port is used to communicate with a device. One or two bytes can be read and/or written 
from each port, depending upon the hardware. Consult the technical documentation for your computer 
to determine the port numbers for a device and the expected usage of each port for a device. 

The value returned is the word that was read. 

inp, inpd, outp, outpd, outpw 

♦include <conio.h> 

♦define DEVICE 34 

void main() 

{ 

unsigned int transmitted; 
transmitted = inpw( DEVICE ); 

} 

Intel 

All, Linux, RDOS, Netware 
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int386 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


♦include <i86.h> 

int int386( int inter_ no, 

const union REGS *in_regs, 
union REGS *out_ regs ); 

The i nt 3 8 6 function causes the computer’s central processor (CPU) to be interrupted with an interrupt 
whose number is given by inter_no. This function is present in the 386 C libraries and may be executed 
on 80386/486 systems. Before the interrupt, the CPU registers are loaded from the structure located by 
in_regs. Following the interrupt, the structure located by out_regs is filled with the contents of the CPU 
registers. These structures may be located at the same location in memory. 

You should consult the technical documentation for the computer that you are using to determine the 
expected register contents before and after the interrupt in question. 

The int 3 8 6 function returns the value of the CPU EAX register after the interrupt. 

bdos, int386x, int86, int86x, intdos, intdosx, intr, segread 

/* 

* This example clears the screen on DOS 
*/ 

♦include <i86.h> 

void main() 

{ 

union REGS regs; 

regs.w.cx = 0; 
regs.w.dx = 0x1850; 
regs.h.bh = 7; 
regs.w.ax = 0x0600; 

♦ if defined(_ 386_) && defined!_DOS_) 

int386( 0x10, &regs, &regs ); 

♦ else 

int86( 0x10, &regs, &regs ); 

♦endif 

} 

Intel 

DOS/32, Linux, RDOS, Netware 
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int386x 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


♦include <i86.h> 

int int386x( int inter_ no, 

const union REGS *in_ regs, 
union REGS *out_ regs, 
struct SREGS *seg_ regs ); 

The i nt 3 8 6 x function causes the computer’s central processor (CPU) to be interrupted with an 
interrupt whose number is given by inter_no. This function is present in the 32-bit C libraries and may 
be executed on Intel 386 compatible systems. Before the interrupt, the CPU registers are loaded from 
the structure located by in_regs and the DS, ES, FS and GS segment registers are loaded from the 
structure located by seg_regs. All of the segment registers must contain valid values. Failure to do so 
will cause a segment violation when running in protect mode. If you don't care about a particular 
segment register, then it can be set to 0 which will not cause a segment violation. The function 
segread can be used to initialize seg_regs to their current values. 

Following the interrupt, the structure located by out_regs is filled with the contents of the CPU 
registers. The injregs and out_regs structures may be located at the same location in memory. The 
original values of the DS, ES, FS and GS registers are restored. The structure seg_regs is updated with 
the values of the segment registers following the interrupt. 

You should consult the technical documentation for the computer that you are using to determine the 
expected register contents before and after the interrupt in question. 

The int 3 8 6x function returns the value of the CPU EAX register after the interrupt. 

bdos, int386, int86, int86x, intdos, intdosx, intr, segread 

♦include <stdio.h> 

♦include <i86.h> 

/* get current mouse interrupt handler address */ 

void main() 

{ 

union REGS r; 
struct SREGS s; 

s.ds = s.es = s.fs = s.gs = FP_ SEG( &s ); 

♦ if defined (_PHARLAP_) 

r.w.ax = 0x2503; /* get real-mode vector */ 

r.h.cl = 0x33; /* interrupt vector 0x33 */ 

int386( 0x21, &r, &r ); 

printf ( "mouse handler real-mode address=" 

"%lx\n", r.x.ebx ); 

r.w.ax = 0x2502; /* get protected-mode vector */ 

r.h.cl = 0x33; /* interrupt vector 0x33 */ 

int386x( 0x21, &r, &r, &s ); 

printf( "mouse handler protected-mode address=" 

"%x:%lx\n", s.es, r.x.ebx ); 
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int386x 


Classification: 

Systems: 


#else 

r.h.ah = 0x35; /* get vector */ 

r.h.al = 0x33; /* vector 0x33 */ 

int386x( 0x21, &r, &r, &s ); 

printf( "mouse handler protected-mode address=" 
"%x:%lx\n", s.es, r.x.ebx ); 

#endif 


Intel 

DOS/32, Linux, RDOS, Netware 
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int86 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


♦include <i86.h> 

int int86( int inter_ no, 

const union REGS *in_regs, 
union REGS *out_ regs ); 

The int 8 6 function causes the computer’s central processor (CPU) to be interrupted with an interrupt 
whose number is given by inter_no. Before the interrupt, the CPU registers are loaded from the 
structure located by in_regs. Following the interrupt, the structure located by out_regs is filled with the 
contents of the CPU registers. These structures may be located at the same location in memory. 

You should consult the technical documentation for the computer that you are using to determine the 
expected register contents before and after the interrupt in question. 

The int 8 6 function returns the value of the CPU AX register after the interrupt. 

bdos, int386, int386x, int86x, intdos, intdosx, intr, segread 

/* 

* This example clears the screen on DOS 
*/ 

♦include <i86.h> 

void main() 

{ 

union REGS regs; 

regs.w.cx = 0; 
regs.w.dx = 0x1850; 
regs.h.bh = 7; 
regs.w.ax = 0x0600; 

♦ if defined(_ 386_) && defined!_DOS_) 

int386( 0x10, &regs, &regs ); 

♦ else 

int86( 0x10, &regs, &regs ); 

♦endif 

} 

Intel 

DOS/16, Windows, Win386, DOS/PM 
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int86x 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


♦include <i86.h> 

int int86x( int inter_ no, 

const union REGS *in_regs, 
union REGS *out_regs, 
struct SREGS *seg_ regs ); 


The int 8 6x function causes the computer’s central processor (CPU) to be interrupted with an interrupt 
whose number is given by inter_no. Before the interrupt, the CPU registers are loaded from the 
structure located by in_regs and the DS and ES segment registers are loaded from the structure located 
by seg_regs. All of the segment registers must contain valid values. Failure to do so will cause a 
segment violation when running in protect mode. If you don’t care about a particular segment register, 
then it can be set to 0 which will not cause a segment violation. The function segread can be used to 
initialize seg_regs to their current values. 

Following the interrupt, the structure located by out_regs is filled with the contents of the CPU 
registers. The injregs and out_regs structures may be located at the same location in memory. The 
original values of the DS and ES registers are restored. The structure seg_regs is updated with the 
values of the segment registers following the interrupt. 

You should consult the technical documentation for the computer that you are using to determine the 
expected register contents before and after the interrupt in question. 

The function returns the value of the CPU AX register after the interrupt. 

bdos, int386, int386x, int86, intdos, intdosx, intr, segread 


♦include <stdio.h> 
♦include <i86.h> 


/* get current mouse interrupt handler address */ 


void main() 

{ 

union REGS r; 
struct SREGS s; 


} 


r.h.ah = 0x35; /* DOS get vector */ 

r.h.al = 0x33; /* interrupt vector 0x33 */ 

int86x( 0x21, &r, &r, &s ); 

printf ( "mouse handler address=%4.4x:%4.4x\n", 
s.es, r.w.bx ); 


Intel 


DOS/16, Windows, Win386, DOS/PM 
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intdos 


Synopsis: #include <dos.h> 

int intdos ( const union REGS *in_regs, 
union REGS *out_ regs ); 

Description: The intdos function causes the computer’s central processor (CPU) to be interrupted with an interrupt 
number hexadecimal 21 (0x21), which is a request to invoke a specific DOS function. Before the 
interrupt, the CPU registers are loaded from the structure located by in_regs. The AH register contains 
a number indicating the function requested. Following the interrupt, the structure located by out_regs is 
filled with the contents of the CPU registers. These structures may be located at the same location in 
memory. 

You should consult the technical documentation for the DOS operating system that you are using to 
determine the expected register contents before and after the interrupt in question. 

Returns: The function returns the value of the AX (EAX in 386 library) register after the interrupt has completed. 

The CARRY flag (when set, an error has occurred) is copied into the structure located by out_regs. 
When an error has occurred, errno contains a value indicating the type of error that has been detected. 

See Also: bdos, int386, int386x, int86, int86x, intdosx, intr, segread 

Example: ((include <dos.h> 

((define DISPLAY_ OUTPUT 2 

void main() 

{ 

union REGS in_ regs, out_regs; 
int rc; 

in_ regs . h . ah = DISPLAY_ OUTPUT; 
in_regs.h.al = 0; 

in_regs.w.dx = 'I'; 

rc = intdos ( &in_ regs, &out_ regs ); 
in_regs.w.dx = ' N' ; 

rc = intdos ( &in_ regs, &out_ regs ); 
in_regs.w.dx = ' T'; 

rc = intdos ( &in_ regs, &out_ regs ); 
in_regs.w.dx = ' D'; 

rc = intdos ( &in_ regs, &out_ regs ); 
in_regs.w.dx = 'O'; 

rc = intdos ( &in_ regs, &out_ regs ); 
in_regs.w.dx = 'S'; 

rc = intdos ( &in_ regs, &out_ regs ); 

} 

Classification: DOS 

Systems: DOS, Windows, Win386, DOS/PM 
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intdosx 


Synopsis: #include <dos.h> 

int intdosx ( const union REGS *in_regs, 
union REGS *out_ regs, 
struct SREGS *seg_ regs ); 

Description: The intdosx function causes the computer’s central processor (CPU) to be interrupted with an 

interrupt number hexadecimal 21 (0x21), which is a request to invoke a specific DOS function. Before 
the interrupt, the CPU registers are loaded from the structure located by injregs and the segment 
registers DS and ES are loaded from the structure located by seg_regs. The AH register contains a 
number indicating the function requested. All of the segment registers must contain valid values. 
Failure to do so will cause a segment violation when running in protect mode. If you don’t care about a 
particular segment register, then it can be set to 0 which will not cause a segment violation. The 
function segread can be used to initialize seg_regs to their current values. 

Following the interrupt, the structure located by out_regs is filled with the contents of the CPU 
registers. The injregs and out_regs structures may be located at the same location in memory. The 
original values for the DS and ES registers are restored. The structure seg_regs is updated with the 
values of the segment registers following the interrupt. 

You should consult the technical documentation for the DOS operating system that you are using to 
determine the expected register contents before and after the interrupt in question. 

Returns: The intdosx function returns the value of the AX (EAX in 32-bit library) register after the interrupt 

has completed. The CARRY flag (when set, an error has occurred) is copied into the structure located 
by out_regs. When an error has occurred, errno contains a value indicating the type of error that has 
been detected. 

See Also: bdos, int386, int386x, int86, int86x, intdos, intr, segread 

Example: ((include <stdio.h> 

♦include <dos.h> 

/* get current mouse interrupt handler address */ 

void main() 

{ 

union REGS r; 
struct SREGS s; 

#if defined(_ 386_) 

s.ds = s.es = s.fs = s.gs = FP_ SEG( &s ); 

#endif 

r.h.ah = 0x35; /* get vector */ 

r.h.al = 0x33; /* vector 0x33 */ 

intdosx ( &r, &r, &s ); 

#if defined( _ 386 _) 

printf ( "mouse handler address=%4.4x:%lx\n", 
s.es, r.x.ebx ); 

♦ else 

printf( "mouse handler address=%4.4x:%4.4x\n" , 
s.es, r.x.bx ); 

♦endif 

} 
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intdosx 


Classification: DOS 

Systems: DOS, Windows, Win386, DOS/PM 
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intr 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <i86.h> 

void intr ( int inter_ no, union REGPACK *regs ); 

The intr function causes the computer’s central processor (CPU) to be interrupted with an interrupt 
whose number is given by inter_no. Before the interrupt, the CPU registers are loaded from the 
structure located by regs. All of the segment registers must contain valid values. Failure to do so will 
cause a segment violation when running in protect mode. If you don't care about a particular segment 
register, then it can be set to 0 which will not cause a segment violation. Following the interrupt, the 
structure located by regs is filled with the contents of the CPU registers. 

This function is similar to the int 8 6x function, except that only one structure is used for the register 
values and that the BP (EBP in 386 library) register is included in the set of registers that are passed and 
saved. 

You should consult the technical documentation for the computer that you are using to determine the 
expected register contents before and after the interrupt in question. 

The intr function does not return a value. 

bdos, int386, int386x, int86, int86x, intdos, intdosx, segread 

♦include <stdio.h> 

♦include <string.h> 

♦include <i86.h> 

void main() /* Print location of Break Key Vector */ 

1 

union REGPACK regs; 

memset( &regs, 0, sizeof(union REGPACK) ); 

regs.w.ax = 0x3523; 

intr( 0x21, &regs ); 

printf ( "Break Key vector is " 

♦ if defined(_ 386_) 

"%x:%lx\n", regs.w.es, regs.x.ebx ); 

♦ else 

"%x:%x\n", regs.w.es, regs.x.bx ); 

♦endif 

} 

produces the following: 

Break Key vector is eef:13c 

Intel 

DOS, Windows, Win386, Linux, RDOS, DOS/PM, Netware 
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isalnum, iswalnum 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


Systems: 


♦include <ctype.h> 
int isalnum( int c ); 

♦include <wctype.h> 

int iswalnum( wint_ t c ); 

The isalnum function tests if the argument c is an alphanumeric character (’a’ to ’z’, ’A’ to ’Z\ or ’0’ 
to ’9’). An alphanumeric character is any character for which isalpha or isdigit is true. 

The iswalnum function is a wide-character version of isalnum that operates with wide-character 
argument. 

The isalnum function returns zero if the argument is neither an alphabetic character (A-Z or a-z) nor a 
digit (0-9). Otherwise, a non-zero value is returned. The iswalnum function returns a non-zero value 
if either iswalpha or iswdigit is true for c. 

isalpha, isblank, iscntrl, isdigit, isgraph, isleadbyte, islower, isprint, 
ispunct, isspace, isupper, iswctype, isxdigit, tolower, toupper, towctrans 

♦include <stdio.h> 

♦include <ctype.h> 

void main() 

{ 

if( isalnum( getchar() ) ) { 

printf ( "is alpha-numeric\n" ); 

} 

} 

ISOC 

iswalnum is ISO C95 

isalnum - All, Linux, RDOS, Netware 
iswalnum - All, Linux, RDOS, Netware 
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isalpha, iswalpha 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


Systems: 


♦include <ctype.h> 
int isalpha( int c ) ; 

♦include <wctype.h> 

int iswalpha( wint_ t c ) ; 

The isalpha function tests if the argument c is an alphabetic character (’a’ to ’z’ and ’A’ to ’Z'). An 
alphabetic character is any character for which isupper or islower is true. 

The iswalpha function is a wide-character version of isalpha that operates with wide-character 
argument. 

The isalpha function returns zero if the argument is not an alphabetic character (A-Z or a-z); 
otherwise, a non-zero value is returned. The iswalpha function returns a non-zero value only for 
wide characters for which iswupper or iswlower is true, or any wide character that is one of an 
implementation-defined set for which none of iswcntrl, iswdigit, iswpunct, or iswspace is 
true. 

isalnum, isblank, iscntrl, isdigit, isgraph, isleadbyte, islower, isprint, 
ispunct, isspace, isupper, iswctype, isxdigit, tolower, toupper, towctrans 

♦include <stdio.h> 

♦include <ctype.h> 

void main() 

{ 

if( isalpha( getchar() ) ) { 

printf ( "is alphabetic\n" ); 

} 

} 

ISOC 

iswalpha is ISO C95 

isalpha - All, Linux, RDOS, Netware 
iswalpha - All, Linux, RDOS, Netware 
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isascn, _isascn, iswascn 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


Systems: 


♦include <ctype.h> 
int isascii ( int c ); 

int_isascii( int c ) ; 

♦include <wctype.h> 

int iswascii( wint_ t c ) ; 

The isascii function tests for a character in the range from 0 to 127. 

The_isascii function is identical tdsascii. Use_isascii for ANSI naming conventions. 

The iswascii function is a wide-character version of isascii that operates with wide-character 
argument. 

The isascii function returns a non-zero value when the character is in the range 0 to 127; otherwise, 
zero is returned. The iswascii function returns a non-zero value when c is a wide-character 
representation of an ASCII character. 

isalnum, isalpha, isblank, iscntrl, isdigit, isgraph, isleadbyte, islower, 
isprint, ispunct, isspace, isupper, iswctype, isxdigit, tolower, toupper, 
towctrans 

♦include <stdio.h> 

♦include <ctype.h> 

char chars[] = { 

'A' , 

0 x 80 , 

' Z' 

} ; 


♦ define SIZE sizeof ( chars ) / sizeof ( char ) 

void main() 

{ 

int i; 

for( i = 0; i < SIZE; i++ ) { 

printf ( "Char %c is %san ASCII characterin'', 
chars[i], 

( isascii( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 

Char A is an ASCII character 
Char is not an ASCII character 
Char Z is an ASCII character 

WATCOM 

_isascii conforms to ANSI naming conventions 

isascii - All, Linux, RDOS, Netware 
_ isascii - All, Linux, RDOS, Netware 
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isascn, _isascn, iswascn 


iswascii 


All, Linux, RDOS, 


Netware 
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isatty, Jsatty 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <io.h> 

int isatty( int handle ); 

int _ isatty( int handle ); 

The isatty function tests if the opened file or device referenced by the file handle handle is a 
character device (for example, a console, printer or port). 

The _ isatty function is identical toisatty. Use _ isatty for ANSI naming conventions. 

The isatty function returns zero if the device or file is not a character device; otherwise, a non-zero 
value is returned. When an error has occurred, errno contains a value indicating the type of error that 
has been detected. 


open 


♦include <stdio.h> 
♦include <io.h> 


void main( void ) 

{ 

printf ( "stdin is a %stty\n", 

( isatty( fileno( stdin ) ) ) 

? "" : "not " ); 


} 


POSIX 1003.1 

_isatty conforms to ANSI naming conventions 
isatty - All, Linux, RDOS, Netware 

_ isatty - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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isblank, iswblank 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


♦include <ctype.h> 
int isblank ( int c ); 

♦include <wctype.h> 

int iswblank( wint_ t c ) ; 

The isblank function tests for the following blank characters: 

Constant Character 

’ ’ space 

’\t’ horizontal tab 

The iswblank function is a wide-character version of isblank that operates with wide-character 
argument. 

The isblank function returns a non-zero character when the argument is one of the indicated blank 
characters. The iswblank function returns a non-zero value when the argument is a wide character 
that corresponds to a standard blank character or is one of an implementation-defined set of wide 
characters for which iswalnum is false. Otherwise, zero is returned. 

isalnum, isalpha, iscntrl, isdigit, isgraph, isleadbyte, islower, isprint, 
ispunct, isspace, isupper, iswctype, isxdigit, tolower, toupper, towctrans 

♦include <stdio.h> 

♦include <ctype.h> 

char chars[] = { 

'A' , 

0x09, 

r r 

r 

0x7d 

} ; 

♦ define SIZE sizeof ( chars ) / sizeof ( char ) 

void main() 

{ 

int i; 

for( i = 0; i < SIZE; i++ ) { 

printf ( "Char %c is %sa blank characterin' 1 , 
chars [ i], 

( isblank( chars [i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 

Char A is not a blank character 
Char is a blank character 

Char is a blank character 

Char } is not a blank character 

ISO C99 
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isblank, iswblank 


Systems: 


isblank - All, Linux, RDOS, 
iswblank - All, Linux, RDOS 


Netware 

Netware 
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iscntrl, iswcntrl 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


Systems: 


♦include <ctype.h> 
int iscntrl( int c ) ; 

♦include <wchar.h> 

int iswcntrl( wint_ t c ) ; 

The iscntrl function tests for any control character. A control character is any character whose 
value is from 0 through 31. 

The iswcntrl function is a wide-character version of iscntrl that operates with wide-character 
argument. 

The iscntrl function returns a non-zero value when the argument is a control character. The 
iswcntrl function returns a non-zero value when the argument is a control wide character. 
Otherwise, zero is returned. 

isalnum, isalpha, isblank, isdigit, isgraph, isleadbyte, islower, isprint, 
ispunct, isspace, isupper, iswctype, isxdigit, tolower, toupper, towctrans 

♦include <stdio.h> 

♦include <ctype.h> 

char chars[] = { 

'A' , 

0x09, 

' Z' 

}; 


♦ define SIZE sizeof ( chars ) / sizeof ( char ) 

void main() 

{ 

int i; 

for( i = 0; i < SIZE; i++ ) { 

printf ( "Char %c is %sa Control characterin' 1 , 
chars[i], 

( iscntrl( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 

Char A is not a Control character 
Char is a Control character 

Char Z is not a Control character 

ISOC 

iswcntrl is ISO C95 

iscntrl - All, Linux, RDOS, Netware 
iswcntrl - All, Linux, RDOS, Netware 
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iscsym, _ iscsym, _iswcsym 


Synopsis: #include <ctype.h> 

int iscsym( int c ); 

int _iscsym( int c ); 

♦include <wctype.h> 

int_iswcsym( wint_ t c ) ; 


Description: 


The iscsym function tests for a letter, underscore or digit. 


The_iscsym function is identical tdscsym. Use_iscsym for ANSI naming conventions. 

The_iswcsym function is a wide-character version otscsym that operates with wide-character 

argument. 

Returns: A non-zero value is returned when the character is a letter, underscore or digit; otherwise, zero is 

returned. The_iswcsym function returns a non-zero value when c is a wide-character representation 

of a letter, underscore or digit character. 

See Also: isalnum, isalpha, isblank, iscntrl, isdigit, isgraph, isleadbyte, islower, 

isprint, ispunct, isspace, isupper, iswctype, isxdigit, tolower, toupper, 
towctrans 


Example: #include <stdio.h> 

♦include <ctype.h> 


char chars[] = { 
'A' , 

0x80, 


r r 



' +' 


} ; 


♦define SIZE sizeof( chars ) / sizeof( char ) 

void main() 

{ 

int i; 

for( i = 0; i < SIZE; i++ ) { 

printf ( "Char %c is %sa C symbol characterin'', 
chars[i], 

( _iscsym( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 

Char A is a C symbol character 
Char is not a C symbol character 
Char _ is a C symbol character 
Char 9 is a C symbol character 
Char + is not a C symbol character 

Classification: WATCOM 

_iscsym conforms to ANSI naming conventions 
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Systems: 


iscsym, _iscsym, _iswcsym 


iscsym - All, Linux, RDOS, Netware 

_iscsym - All, Linux, RDOS, Netware 

_ iswcsym - All, Linux, RDOS, Netware 
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iscsymf, _iscsymf, _iswcsymf 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


♦include <ctype.h> 
int iscsymf( int c ); 

int_iscsymf( int c ) ; 

♦include <wctype.h> 

int_iswcsymf ( wint_ t c ) ; 

The iscsymf function tests for a letter or underscore. 

The_iscsymf function is identical tcLscsymf. Use_iscsymf for ANSI naming conventions. 

The_iswcsymf function is a wide-character version otlscsymf that operates with wide-character 

argument. 

A non-zero value is returned when the character is a letter or underscore; otherwise, zero is returned. 

The_iswcsymf function returns a non-zero value when c is a wide-character representation of a 

letter or underscore character. 

isalpha, isalnum, iscntrl, isdigit, isgraph, islower, isprint, ispunct, 
isspace, isupper, isxdigit, tolower, toupper 

♦include <stdio.h> 

♦include <ctype.h> 

char chars[] = { 

'A' , 

0x80, 


r r 



' +' 


} ; 


♦define SIZE sizeof( chars ) / sizeof( char ) 

void main() 

{ 

int i; 

for( i = 0; i < SIZE; i++ ) { 

printf ( "Char %c is %sa csymf characterin'', 
chars[i], 

( _iscsymf( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 

Char A is a csymf character 
Char is not a csymf character 
Char _ is a csymf character 
Char 9 is not a csymf character 
Char + is not a csymf character 

WATCOM 

_iscsymf conforms to ANSI naming conventions 
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Systems: 


iscsymf, _iscsymf, _iswcsymf 


iscsymf - All, Linux, RDOS, Netware 

_ iscsymf - All, Linux, RDOS, Netware 

_ iswcsymf - All, Linux, RDOS, Netware 
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isdigit, iswdigit 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


Systems: 


♦include <ctype.h> 
int isdigit ( int c ); 

♦include <wctype.h> 

int iswdigit( wint_ t c ) ; 

The isdigit function tests for any decimal-digit character 'O' through '9'. 

The iswdigit function is a wide-character version of isdigit that operates with wide-character 
argument. 

The isdigit function returns a non-zero value when the argument is a decimal-digit character. The 
iswdigit function returns a non-zero value when the argument is a wide character corresponding to a 
decimal-digit character. Otherwise, zero is returned. 

isalnum, isalpha, isblank, iscntrl, isgraph, isleadbyte, islower, isprint, 
ispunct, isspace, isupper, iswctype, isxdigit, tolower, toupper, towctrans 

♦include <stdio.h> 

♦include <ctype.h> 

char chars[] = { 

'A' , 

'5', 

} ; 


♦ define SIZE sizeof ( chars ) / sizeof ( char ) 

void main() 

{ 

int i; 

for( i = 0; i < SIZE; i++ ) { 

printf ( "Char %c is %sa digit characterin'', 
chars[i], 

( isdigit( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 

Char A is not a digit character 
Char 5 is a digit character 
Char $ is not a digit character 

ISOC 

iswdigit is ISO C95 

isdigit - All, Linux, RDOS, Netware 
iswdigit - All, Linux, RDOS, Netware 
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isfinite 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <math.h> 
int isfinite( x ); 

The isfinite macro determines whether its argument x has a finite value (zero, subnormal, or 
normal, and not infinite or NaN). First, an argument represented in a format wider than its semantic 
type is converted to its semantic type. Then determination is based on the type of the argument. 

The argument x must be an expression of real floating type. 

The isfinite macro returns a nonzero value if and only if its argument has a finite value. 

fpclassify, isinf, isnan, isnormal, signbit,_ finite 

♦include <math.h> 

♦include <stdio.h> 

void main( void ) 

{ 

printf ( "zero %s a finite number\n", 

isfinite ( 0.0 ) ? "is" : "is not" ); 

} 

produces the following: 

zero is a finite number 

ISOC 

MACRO 
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isgraph, iswgraph 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


Systems: 


♦include <ctype.h> 
int isgraph( int c ); 

♦include <wctype.h> 

int iswgraph( wint_ t c ); 

The isgraph function tests for any printable character except space (’ ’). The isprint function is 
similar, except that the space character is also included in the character set being tested. 

The iswgraph function is a wide-character version of isgraph that operates with wide-character 
argument. 

The isgraph function returns non-zero when the argument is a printable character (except a space). 
The iswgraph function returns a non-zero value when the argument is a printable wide character 
(except a wide-character space). Otherwise, zero is returned. 

isalnum, isalpha, isblank, iscntrl, isdigit, isleadbyte, islower, isprint, 
ispunct, isspace, isupper, iswctype, isxdigit, tolower, toupper, towctrans 

♦include <stdio.h> 

♦include <ctype.h> 

char chars[] = { 

'A' , 

0x09, 

r r 

r 

0x7d 

} ; 


♦ define SIZE sizeof ( chars ) / sizeof ( char ) 

void main() 

{ 

int i; 

for( i = 0; i < SIZE; i++ ) { 

printf ( "Char %c is %sa printable characterin'', 
chars[i], 

( isgraph( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 

Char A is a printable character 
Char is not a printable character 

Char is not a printable character 
Char } is a printable character 

ISOC 

iswgraph is ISO C95 

isgraph - All, Linux, RDOS, Netware 
iswgraph - All, Linux, RDOS, Netware 
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isinf 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <math.h> 
int isinf( x ); 

The isinf macro determines whether its argument value is an infinity (positive or negative). First, an 
argument represented in a format wider than its semantic type is converted to its semantic type. Then 
determination is based on the type of the argument. 

The argument x must be an expression of real floating type. 

The isinf macro returns a nonzero value if and only if its argument has an infinite value. 

fpclassify, isfinite, isnan, isnormal, signbit 

♦include <math.h> 

♦include <stdio.h> 

void main( void ) 

{ 

printf ( "zero %s an infinite number\n", 
isinf ( 0.0 ) ? "is" : "is not" ); 

} 

produces the following: 

zero is not an infinite number 

ISOC 

MACRO 
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isleadbyte 


Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <ctype.h> 

int isleadbyte( int ch ) ; 

The isleadbyte function tests if the argument ch is a valid first byte of a multibyte character in the 
current code page. 

For example, in code page 932, a valid lead byte is any byte in the range 0x81 through 0x9F or OxEO 
through OxFC. 

The isleadbyte function returns a non-zero value when the argument is a valid lead byte. 
Otherwise, zero is returned. 

isalnum, isalpha, isblank, iscntrl, isdigit, isgraph, islower, isprint, 
ispunct, isspace, isupper, iswctype, isxdigit, tolower, toupper, towctrans 

♦include <stdio.h> 

♦include <ctype.h> 

♦include <mbctype.h> 

const unsigned char chars[] = { 

r f 

r 

r r 
• r 

'i', 

'A' , 


0x81, 

0x40, 

/* 

double-byte 

space */ 


0x82, 

0x60, 

/* 

double-byte 

A */ 


0x82, 

0xA6, 

/* 

double-byte 

Hiragana 

*/ 

0x83, 

0x42, 

/* 

double-byte 

Katakana 

*/ 

OxAl, 


/* 

single-byte 

Katakana 

punctuation */ 

0xA6, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxDF, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxEO, 

0x00 

OxAl, 

/* 

double-byte 

Kanji */ 



} ; 

♦ define SIZE sizeof ( chars ) / sizeof ( char ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ); 

for( i = 0; i < SIZE; i++ ) { 

printf( "%2.2x is %sa valid lead byte\n", 
chars[i], 

( isleadbyte! chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 
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isleadbyte 


20 is not a valid lead byte 

2e is not a valid lead byte 

31 is not a valid lead byte 

41 is not a valid lead byte 

81 is a valid lead byte 

40 is not a valid lead byte 

82 is a valid lead byte 

60 is not a valid lead byte 

82 is a valid lead byte 

a6 is not a valid lead byte 

83 is a valid lead byte 

42 is not a valid lead byte 

al is not a valid lead byte 

a6 is not a valid lead byte 

df is not a valid lead byte 

eO is a valid lead byte 

al is not a valid lead byte 

00 is not a valid lead byte 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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islower, iswlower 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


Systems: 


♦include <ctype.h> 
int islower( int c ) ; 

♦include <wctype.h> 

int iswlower( wint_ t c ) ; 

The islower function tests for any lowercase letter ’a’ through 'z\ 

The iswlower function is a wide-character version of islower that operates with wide-character 
argument. 

The islower function returns a non-zero value when argument is a lowercase letter. The iswlower 
function returns a non-zero value when the argument is a wide character that corresponds to a lowercase 
letter, or if it is one of an implementation-defined set of wide characters for which none of iswcntrl, 
iswdigit, iswpunct, or iswspace is true. Otherwise, zero is returned. 

isalnum, isalpha, isblank, iscntrl, isdigit, isgraph, isleadbyte, isprint, 
ispunct, isspace, isupper, iswctype, isxdigit, tolower, toupper, towctrans 

♦include <stdio.h> 

♦include <ctype.h> 

char chars[] = { 



} ; 


♦ define SIZE sizeof ( chars ) / sizeof ( char ) 

void main() 

{ 

int i; 

for( i = 0; i < SIZE; i++ ) { 

printf ( "Char %c is %sa lowercase characterin'', 
chars[i], 

( islower( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 

Char A is not a lowercase character 
Char a is a lowercase character 
Char z is a lowercase character 
Char Z is not a lowercase character 

ISOC 

iswlower is ISO C95 

islower - All, Linux, RDOS, Netware 
iswlower - All, Linux, RDOS, Netware 
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Synopsis: #include <mbctype.h> 

int _ ismbbalnum( unsigned int ch ); 

Description: The _ ismbbalnum function tests if the argument ch satisfies the condition that one of isalnum or 
_ ismbbkalnum is true. 

Note: The argument ch must represent a single-byte value (i.e., 0 <= ch <= 255 ). Incorrect results 
occur if the argument is a double-byte character. 

Returns: The _ ismbbalnum function returns a non-zero value if the argument satisfies the condition; otherwise 

a zero value is returned. 

See Also: _ getmbcp,_ mbbtombc^_ mbc jisto jms,_ mbcjmstojis^ mbctombb,_ ismbbalpha, 

_ ismbbgraph,_ ismbbkalnum,_ ismbbkalpha,_ ismbbkana,_ ismbbkprint, 

_ ismbbkpunct,_ ismbblead,_ ismbbprint,_ ismbbpunct,_ ismbbtrail^ mbbtombc, 
_ mbc jisto jms^_ mbc jmsto jis,_ mbctombb^_ mbbtype^ setmbcp 

Example: #include <stdio.h> 

♦include <mbctype.h> 

unsigned int chars[] = { 

r r 

r 

r r 
• r 

'i', 

'A' , 

0x8140, /* double-byte space */ 

0x8260, /* double-byte A */ 

0x82A6, /* double-byte Hiragana */ 

0x8342, /* double-byte Katakana */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6, /* single-byte Katakana alphabetic */ 

OxDF, /* single-byte Katakana alphabetic */ 

OxEOAl /* double-byte Kanji */ 

} ; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ); 

for ( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa single-byte alphanumeric\n" 

" or Katakana non-punctuation character\n", 
chars[i], 

( _ ismbbalnum( chars [i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 
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Classification: 

Systems: 


0x0020 is not a single-byte alphanumeric 
or Katakana non-punctuation character 
0x002e is not a single-byte alphanumeric 
or Katakana non-punctuation character 
0x0031 is a single-byte alphanumeric 
or Katakana non-punctuation character 
0x0041 is a single-byte alphanumeric 
or Katakana non-punctuation character 
0x8140 is not a single-byte alphanumeric 
or Katakana non-punctuation character 
0x8260 is not a single-byte alphanumeric 
or Katakana non-punctuation character 
0x82a6 is a single-byte alphanumeric 
or Katakana non-punctuation character 
0x8342 is a single-byte alphanumeric 
or Katakana non-punctuation character 
OxOOal is not a single-byte alphanumeric 
or Katakana non-punctuation character 
0x00a6 is a single-byte alphanumeric 
or Katakana non-punctuation character 
OxOOdf is a single-byte alphanumeric 
or Katakana non-punctuation character 
OxeOal is not a single-byte alphanumeric 
or Katakana non-punctuation character 

WATCOM 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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Synopsis: #include <mbctype.h> 

int _ ismbbalpha( unsigned int ch ); 

Description: The _ ismbbalpha function tests if the argument ch satisfies the condition that one of isalpha or 
_ ismbbkalpha is true. 

For example, in code page 932, _ ismbbalpha tests if the argument ch is a single-byte alphabetic 
character ("a" to "z" or "A" to "Z") or single-byte Katakana non-punctuation character. 

Note: The argument ch must represent a single-byte value (i.e., 0 <= ch <= 255 ). Incorrect results 
occur if the argument is a double-byte character. 

Returns: The _ ismbbalpha function returns a non-zero value if the argument satisfies the condition; otherwise 

a zero value is returned. 

See Also: _ getmbcp,_ mbbtombc^_ mbc jisto jms,_ mbcjmstojis^ mbctombb,_ ismbbalnum, 

_ ismbbgraph,_ ismbbkalnum,_ ismbbkalpha,_ ismbbkana^ ismbbkprint, 

_ ismbbkpunct,_ ismbblead,_ ismbbprint,_ ismbbpunct,_ ismbbtrail,_ mbbtombc, 
_ mbc jisto jms^_ mbc jmsto jis,_ mbctombb^_ mbbtype^ setmbcp 

Example: #include <stdio.h> 

#include <mbctype.h> 

unsigned int chars[] = { 

r r 

r 

r r 
• r 

'i', 

'A' , 

0x8140, /* double-byte space */ 

0x8260, /* double-byte A */ 

0x82A6, /* double-byte Hiragana */ 

0x8342, /* double-byte Katakana */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6, /* single-byte Katakana alphabetic */ 

OxDF, /* single-byte Katakana alphabetic */ 

OxEOAl /* double-byte Kanji */ 

} ; 

#define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ); 

for ( i = 0; i < SIZE; i++ ) { 

printf( "%#6.4x is %sa single-byte alphabetic\n" 

" or Katakana alphabetic character\n", 
chars[i], 

( _ ismbbalpha( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 
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Classification: 

Systems: 


0x0020 is not a single-byte alphabetic 
or Katakana alphabetic character 
0x002e is not a single-byte alphabetic 
or Katakana alphabetic character 
0x0031 is not a single-byte alphabetic 
or Katakana alphabetic character 
0x0041 is a single-byte alphabetic 
or Katakana alphabetic character 
0x8140 is not a single-byte alphabetic 
or Katakana alphabetic character 
0x8260 is not a single-byte alphabetic 
or Katakana alphabetic character 
0x82a6 is a single-byte alphabetic 
or Katakana alphabetic character 
0x8342 is a single-byte alphabetic 
or Katakana alphabetic character 
OxOOal is not a single-byte alphabetic 
or Katakana alphabetic character 
0x00a6 is a single-byte alphabetic 
or Katakana alphabetic character 
OxOOdf is a single-byte alphabetic 
or Katakana alphabetic character 
OxeOal is not a single-byte alphabetic 
or Katakana alphabetic character 

WATCOM 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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Synopsis: #include <mbctype.h> 

int _ ismbbgraph( unsigned int ch ); 

Description: The _ ismbbgraph function tests if the argument ch satisfies the condition that one of is graph or 
_ ismbbkprint is true. 

For example, in code page 932, _ ismbbgraph tests if the argument ch is a single-byte printable 
character excluding space (" ") or single-byte Katakana character. 

Note: The argument ch must represent a single-byte value (i.e., 0 <= ch <= 255 ). Incorrect results 
occur if the argument is a double-byte character. This is shown by the example below. 

Returns: The _ ismbbgraph function returns a non-zero value if the argument satisfies the condition; otherwise 

a zero value is returned. 

See Also: _ getmbcp,_ mbbtombc^_ mbc jisto jms,_ mbcjmstojis^ mbctombb,_ ismbbalnum, 

_ ismbbalpha,_ ismbbkalnum,_ ismbbkalpha,_ ismbbkana^_ ismbbkprint, 

_ ismbbkpunct,_ ismbblead,_ ismbbprint,_ ismbbpunct,_ ismbbtrail,_ mbbtombc, 
_ mbc jisto jms^_ mbc jmsto jis,_ mbctombb^_ mbbtype^ setmbcp 

Example: #include <stdio.h> 

#include <mbctype.h> 

unsigned int chars[] = { 

r r 

r 

r r 
• r 

'i', 

'A' , 

0x8140, /* double-byte space */ 

0x8260, /* double-byte A */ 

0x82A6, /* double-byte Hiragana */ 

0x8342, /* double-byte Katakana */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6, /* single-byte Katakana alphabetic */ 

OxDF, /* single-byte Katakana alphabetic */ 

OxEOAl /* double-byte Kanji */ 

} ; 

#define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ); 

for ( i = 0; i < SIZE; i++ ) { 

printf( "%#6.4x is %sa single-byte printable " 

"non-space character\n", 
chars[i], 

( _ ismbbgraph( chars [i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 
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0x0020 is not a single-byte printable non-space character 
0x002e is a single-byte printable non-space character 

0x0031 is a single-byte printable non-space character 

0x0041 is a single-byte printable non-space character 

0x8140 is a single-byte printable non-space character 

0x8260 is a single-byte printable non-space character 

0x82a6 is a single-byte printable non-space character 

0x8342 is a single-byte printable non-space character 

OxOOal is a single-byte printable non-space character 

0x00a6 is a single-byte printable non-space character 

OxOOdf is a single-byte printable non-space character 

OxeOal is a single-byte printable non-space character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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Synopsis: #include <mbctype.h> 

int _ ismbbkalnum( unsigned int ch ); 

Description: The _ ismbbkalnum function tests if the argument ch is a non-ASCII text symbol other than 
punctuation. 

For example, in code page 932, _ ismbbkalnum tests for a single-byte Katakana character (excluding 
the Katakana punctuation characters). Note that there are no Katakana digit characters. A single-byte 
Katakana non-punctuation character is any character for which the following expression is true: 

0xA6 <= ch <= OxDF 

Note: The argument ch must represent a single-byte value (i.e., 0 <= ch <= 255 ). Incorrect results 
occur if the argument is a double-byte character. This is shown by the example below. 

Returns: The _ ismbbkalnum function returns a non-zero value if the argument satisfies the condition; 

otherwise a zero value is returned. 

See Also: _ getmbcp,_ mbbtombc^_ mbc jisto jms,_ mbcjmstojis^ mbctombb,_ ismbbalnum, 

_ ismbbalpha,_ ismbbgraph,_ ismbbkalpha,_ ismbbkana,_ ismbbkprint, 

_ ismbbkpunct,_ ismbblead,_ ismbbprint,_ ismbbpunct,_ ismbbtrail,_ mbbtombc, 
_ mbc jisto jms^_ mbc jmsto jis,__ mbctombb^_ mbbtype^ setmbcp 

Example: ((include <stdio.h> 

((include <mbctype.h> 

unsigned int chars[] = { 

r r 

r 

r r 

• f 

'i', 

'A' , 

0x8140, /* double-byte space */ 

0x8260, /* double-byte A */ 

0x82A6, /* double-byte Hiragana */ 

0x8342, /* double-byte Katakana */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6, /* single-byte Katakana alphabetic */ 

OxDF, /* single-byte Katakana alphabetic */ 

OxEOAl /* double-byte Kanji */ 

1 ; 

((define SIZE sizeof ( chars ) / sizeof ( unsigned int ) 

void main() 

1 

int i; 

_ setmbcp( 932 ); 

for ( i = 0; i < SIZE; i++ ) { 

printf( "%#6.4x is %sa single-byte " 

"Katakana non-punctuation character\n", 
chars[i], 

( _ ismbbkalnum( chars[i] ) ) ? "" : "not " ); 

} 

} 
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produces the following: 

0x0020 is not a single-byte Katakana non-punctuation character 

0x002e is not a single-byte Katakana non-punctuation character 

0x0031 is not a single-byte Katakana non-punctuation character 

0x0041 is not a single-byte Katakana non-punctuation character 

0x8140 is not a single-byte Katakana non-punctuation character 

0x8260 is not a single-byte Katakana non-punctuation character 

0x82a6 is a single-byte Katakana non-punctuation character 
0x8342 is not a single-byte Katakana non-punctuation character 

OxOOal is not a single-byte Katakana non-punctuation character 

0x00a6 is a single-byte Katakana non-punctuation character 
OxOOdf is a single-byte Katakana non-punctuation character 
OxeOal is not a single-byte Katakana non-punctuation character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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Synopsis: #include <mbctype.h> 

int _ ismbbkana( unsigned int ch ); 

Description: The _ ismbbkana function tests if the argument ch is a single-byte Katakana character. A single-byte 
Katakana character is any character for which the following expression is true: 

OxAl <= ch <= OxDF 

Note: The argument ch must represent a single-byte value (i.e., 0 <= ch <= 255 ). Incorrect results 
occur if the argument is a double-byte character. This is shown by the example below. 

Returns: The _ ismbbkana function returns non-zero if the argument is a single-byte Katakana character; 

otherwise, a zero value is returned. 

See Also: _ getmbcp,_ mbbtombc^_ mbc jisto jms,_ mbc jmsto jis,_ mbctombb,_ ismbbalnum, 

_ ismbbalpha,_ ismbbgraph,_ ismbbkalnum,_ ismbbkalpha^ ismbbkprint, 

_ ismbbkpunct,_ ismbblead,_ ismbbprint,_ ismbbpunct,_ ismbbtrail^ mbbtombc, 
_ mbc jisto jms^_ mbc jmsto jis,_ mbctombb^_ mbbtype^ setmbcp 

Example: #include <stdio.h> 

♦include <mbctype.h> 

unsigned int chars[] = { 

r r 

r 

r f 

• f 

'i 

'A' , 

0x8140, /* double-byte space */ 

0x8260, /* double-byte A */ 

0x82A6, /* double-byte Hiragana */ 

0x8342, /* double-byte Katakana */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6, /* single-byte Katakana alphabetic */ 

OxDF, /* single-byte Katakana alphabetic */ 

OxEOAl /* double-byte Kanji */ 

} ; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ); 
for ( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa single-byte " 

"Katakana character\n", 
chars[i], 

( _ ismbbkana( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 
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0x0020 is not a single-byte Katakana character 

0x002e is not a single-byte Katakana character 

0x0031 is not a single-byte Katakana character 

0x0041 is not a single-byte Katakana character 

0x8140 is not a single-byte Katakana character 

0x8260 is not a single-byte Katakana character 

0x82a6 is a single-byte Katakana character 
0x8342 is not a single-byte Katakana character 
OxOOal is a single-byte Katakana character 
0x00a6 is a single-byte Katakana character 
OxOOdf is a single-byte Katakana character 
OxeOal is a single-byte Katakana character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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Synopsis: #include <mbctype.h> 

int _ ismbbkalpha( unsigned int ch ); 

Description: The _ ismbbkalpha function tests if the argument ch is a non-ASCII text symbol other than digits or 
punctuation. 

For example, in code page 932, _ ismbbkalpha tests for a single-byte Katakana character (excluding 
the Katakana punctuation characters). Note that there are no Katakana digit characters. A single-byte 
Katakana non-punctuation character is any character for which the following expression is true: 

0xA6 <= ch <= OxDF 

Note: The argument ch must represent a single-byte value (i.e., 0 <= ch <= 255 ). Incorrect results 
occur if the argument is a double-byte character. This is shown by the example below. 

Returns: The _ ismbbkalpha function returns a non-zero value if the argument satisfies the condition; 

otherwise a zero value is returned. 

See Also: _ getmbcp,_ mbbtombc^_ mbc jisto jms,_ mbcjmstojis^ mbctombb,_ ismbbalnum, 

_ ismbbalpha,_ ismbbgraph,_ ismbbkalnum,_ ismbbkana,_ ismbbkprint, 

_ ismbbkpunct,_ ismbblead,_ ismbbprint,_ ismbbpunct,_ ismbbtrail,_ mbbtombc, 
_ mbc jisto jms^_ mbc jmsto jis,__ mbctombb^_ mbbtype^ setmbcp 

Example: ((include <stdio.h> 

((include <mbctype.h> 

unsigned int chars[] = { 

r r 

r 

r r 

• f 

'i', 

'A' , 

0x8140, /* double-byte space */ 

0x8260, /* double-byte A */ 

0x82A6, /* double-byte Hiragana */ 

0x8342, /* double-byte Katakana */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6, /* single-byte Katakana alphabetic */ 

OxDF, /* single-byte Katakana alphabetic */ 

OxEOAl /* double-byte Kanji */ 

1 ; 

((define SIZE sizeof ( chars ) / sizeof ( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ); 

for ( i = 0; i < SIZE; i++ ) { 

printf( "%#6.4x is %sa single-byte " 

"Katakana alphabetic character\n", 
chars[i], 

( _ ismbbkalpha( charsfi] ) ) ? "" : "not " ); 

} 

} 
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produces the following: 

0x0020 is not a single-byte Katakana alphabetic character 

0x002e is not a single-byte Katakana alphabetic character 

0x0031 is not a single-byte Katakana alphabetic character 

0x0041 is not a single-byte Katakana alphabetic character 

0x8140 is not a single-byte Katakana alphabetic character 

0x8260 is not a single-byte Katakana alphabetic character 

0x82a6 is a single-byte Katakana alphabetic character 
0x8342 is not a single-byte Katakana alphabetic character 

OxOOal is not a single-byte Katakana alphabetic character 

0x00a6 is a single-byte Katakana alphabetic character 
OxOOdf is a single-byte Katakana alphabetic character 
OxeOal is not a single-byte Katakana alphabetic character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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Synopsis: #include <mbctype.h> 

int _ ismbbkprint( unsigned int ch ); 

Description: The _ ismbbkprint function tests if the argument ch is a non-ASCII text or non-ASCII punctuation 
symbol. 

For example, in code page 932, _ ismbbkprint tests if the argument ch is a single-byte Katakana 
character. A single-byte Katakana character is any character for which the following expression is true: 

OxAl <= ch <= OxDF 

Note: The argument ch must represent a single-byte value (i.e., 0 <= ch <= 255 ). Incorrect results 
occur if the argument is a double-byte character. This is shown by the example below. 

Returns: The _ ismbbkprint function returns a non-zero value if the argument satisfies the condition; 

otherwise a zero value is returned. 

See Also: _ getmbcp,_ mbbtombc^_ mbc jisto jms,_ mbcjmstojis^ mbctombb,_ ismbbalnum, 

_ ismbbalpha,_ ismbbgraph,_ ismbbkalnum,_ ismbbkalpha^ ismbbkana, 

_ ismbbkpunct,_ ismbblead,_ ismbbprint,_ ismbbpunct,_ ismbbtrail,_ mbbtombc, 
_ mbc jisto jms^_ mbc jmsto jis,_ mbctombb^_ mbbtype^ setmbcp 

Example: #include <stdio.h> 

♦include <mbctype.h> 

unsigned int chars[] = { 

r r 

r 

r r 

• f 

'i', 

'A' , 

0x8140, /* double-byte space */ 

0x8260, /* double-byte A */ 

0x82A6, /* double-byte Hiragana */ 

0x8342, /* double-byte Katakana */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6, /* single-byte Katakana alphabetic */ 

OxDF, /* single-byte Katakana alphabetic */ 

OxEOAl /* double-byte Kanji */ 

} ; 

♦ define SIZE sizeof( chars ) / sizeof ( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ); 
for ( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa single-byte " 

"Katakana printable character\n", 
chars[i], 

( _ ismbbkprint( chars[i] ) ) ? "" : "not " ); 

} 

} 
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produces the following: 

0x0020 is not a single-byte Katakana printable character 

0x002e is not a single-byte Katakana printable character 

0x0031 is not a single-byte Katakana printable character 

0x0041 is not a single-byte Katakana printable character 

0x8140 is not a single-byte Katakana printable character 

0x8260 is not a single-byte Katakana printable character 

0x82a6 is a single-byte Katakana printable character 
0x8342 is not a single-byte Katakana printable character 
OxOOal is a single-byte Katakana printable character 

0x00a6 is a single-byte Katakana printable character 

OxOOdf is a single-byte Katakana printable character 

OxeOal is a single-byte Katakana printable character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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Synopsis: #include <mbctype.h> 

int _ ismbbkpunct( unsigned int ch ); 

Description: The _ ismbbkpunct function tests if the argument ch is a non-ASCII punctuation character. 

For example, in code page 932, _ ismbbkpunct tests if the argument ch is a single-byte Katakana 
punctuation character. A single-byte Katakana punctuation character is any character for which the 
following expression is true: 

OxAl <= ch <= 0xA5 

Note: The argument ch must represent a single-byte value (i.e., 0 <= ch <= 255 ). Incorrect results 
occur if the argument is a double-byte character. This is shown by the example below. 

Returns: The _ ismbbkpunct function returns a non-zero value if the argument satisfies the condition; 

otherwise a zero value is returned. 

See Also: _ getmbcp,_ mbbtombc^_ mbc jisto jms,_ mbcjmstojis^ mbctombb,_ ismbbalnum, 

_ ismbbalpha,_ ismbbgraph,_ ismbbkalnum,_ ismbbkalpha^ ismbbkana, 

_ ismbbkprint,_ ismbblead,_ ismbbprint,_ ismbbpunct,_ ismbbtrail,_ mbbtombc, 
_ mbc jisto jms^_ mbc jmsto jis,_ mbctombb^_ mbbtype^ setmbcp 

Example: #include <stdio.h> 

♦include <mbctype.h> 

unsigned int chars[] = { 

r r 

r 

r r 

• f 

'i', 

'A' , 

0x8140, /* double-byte space */ 

0x8260, /* double-byte A */ 

0x82A6, /* double-byte Hiragana */ 

0x8342, /* double-byte Katakana */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6, /* single-byte Katakana alphabetic */ 

OxDF, /* single-byte Katakana alphabetic */ 

OxEOAl /* double-byte Kanji */ 

1 ; 

♦ define SIZE sizeof( chars ) / sizeof ( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ); 
for ( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa single-byte " 

"Katakana punctuation character\n", 
chars[i], 

( _ ismbbkpunct( chars[i] ) ) ? "" : "not " ); 

} 

} 
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produces the following: 

0x0020 is not a single-byte Katakana punctuation character 

0x002e is not a single-byte Katakana punctuation character 

0x0031 is not a single-byte Katakana punctuation character 

0x0041 is not a single-byte Katakana punctuation character 

0x8140 is not a single-byte Katakana punctuation character 

0x8260 is not a single-byte Katakana punctuation character 

0x82a6 is not a single-byte Katakana punctuation character 

0x8342 is not a single-byte Katakana punctuation character 

OxOOal is a single-byte Katakana punctuation character 
0x00a6 is not a single-byte Katakana punctuation character 

OxOOdf is not a single-byte Katakana punctuation character 

OxeOal is a single-byte Katakana punctuation character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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Synopsis: #include <mbctype.h> 

int _ ismbblead( unsigned int ch ); 

Description: The _ ismbblead function tests if the argument ch is a valid first byte of a multibyte character. 

For example, in code page 932, valid ranges are 0x81 through 0x9F and OxEO through OxFC. 

Note: The argument ch must represent a single-byte value (i.e., 0 <= ch <= 255 ). Incorrect results 
occur if the argument is a double-byte character. 

Returns: _ ismbblead returns a non-zero value if the argument is valid as the first byte of a multibyte 

character; otherwise zero is returned. 

See Also: _ getmbcp,_ mbbtombc^_ mbc jisto jms,_ mbcjmstojis^ mbctombb,_ ismbbalnum, 

_ ismbbalpha,_ ismbbgraph,_ ismbbkalnum,_ ismbbkalpha^ ismbbkana, 

_ ismbbkprint,_ ismbbkpunct,_ ismbbprint,_ ismbbpunct^ ismbbtrail, 

_ mbbtombc^_ mbc jisto jms^ mbc jmsto jis,_ mbctombb^_ mbbtype,_ setmbcp 

Example: #include <stdio.h> 

#include <mbctype.h> 

unsigned int chars[] = { 

r r 

r 

r r 
• r 

'i', 

'A' , 

0x8140, /* double-byte space */ 

0x8260, /* double-byte A */ 

0x82A6, /* double-byte Hiragana */ 

0x8342, /* double-byte Katakana */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6, /* single-byte Katakana alphabetic */ 

OxDF, /* single-byte Katakana alphabetic */ 

OxEOAl /* double-byte Kanji */ 

}; 

♦ define SIZE sizeof( chars ) / sizeof ( unsigned int ) 

void main() 

1 

int i; 

_ setmbcp( 932 ); 
for ( i = 0; i < SIZE; i++ ) { 

printf( "%#6.4x does %shave a valid first byte\n", 
chars[i] , 

( _ ismbblead! chars[i]>>8 ) ) ? "" : "not " ); 

} 

} 

produces the following: 
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0x0020 does not have a valid first byte 
0x002e does not have a valid first byte 
0x0031 does not have a valid first byte 
0x0041 does not have a valid first byte 
0x8140 does have a valid first byte 
0x8260 does have a valid first byte 
0x82a6 does have a valid first byte 
0x8342 does have a valid first byte 
OxOOal does not have a valid first byte 
0x00a6 does not have a valid first byte 
OxOOdf does not have a valid first byte 
OxeOal does have a valid first byte 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS 
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Synopsis: #include <mbctype.h> 

int _ ismbbprint( unsigned int ch ); 

Description: The _ ismbbprint function tests if the argument ch is a single-byte printable character including 
space (" "). 

For example, in code page 932, _ ismbbprint tests if the argument ch is a single-byte printable 
character including space (" ") or a single-byte Katakana character. These are any characters for which 
the following expression is true: 

isprint(ch) | | _ ismbbkprint (ch) 

Note: The argument ch must represent a single-byte value (i.e., 0 <= ch <= 255 ). Incorrect results 
occur if the argument is a double-byte character. This is shown by the example below. 

Returns: The _ ismbbprint function returns a non-zero value if the argument satisfies the condition; otherwise 

a zero value is returned. 

See Also: _ getmbcp,_ mbbtombc^_ mbc jisto jms,_ mbcjmstojis^ mbctombb,_ ismbbalnum, 

_ ismbbalpha,_ ismbbgraph,_ ismbbkalnum,_ ismbbkalpha^ ismbbkana, 

_ ismbbkprint,_ ismbbkpunct,_ ismbblead,_ ismbbpunct^ ismbbtrail,_ mbbtombc, 
_ mbc jisto jms^_ mbc jmsto jis,_ mbctombb^_ mbbtype^ setmbcp 

Example: #include <stdio.h> 

♦include <mbctype.h> 

unsigned int chars[] = { 

OxOD, 

r r 

• f 

'i', 

'A' , 

0x8140, /* double-byte space */ 

0x8260, /* double-byte A */ 

0x82A6, /* double-byte Hiragana */ 

0x8342, /* double-byte Katakana */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6, /* single-byte Katakana alphabetic */ 

OxDF, /* single-byte Katakana alphabetic */ 

OxEOAl /* double-byte Kanji */ 

}; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ); 

for ( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa single-byte " 

"printable character\n", 
chars[i], 

( _ ismbbprint( chars [i] ) ) ? "" : "not " ); 

} 

} 
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produces the following: 

OxOOOd is not a single-byte printable character 
0x002e is a single-byte printable character 
0x0031 is a single-byte printable character 
0x0041 is a single-byte printable character 
0x8140 is a single-byte printable character 
0x8260 is a single-byte printable character 
0x82a6 is a single-byte printable character 
0x8342 is a single-byte printable character 
OxOOal is a single-byte printable character 
0x00a6 is a single-byte printable character 
OxOOdf is a single-byte printable character 
OxeOal is a single-byte printable character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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ismbbpunct 


Synopsis: #include <mbctype.h> 

int _ ismbbpunct( unsigned int ch ); 

Description: The _ ismbbpunct function tests if the argument ch is a single-byte punctuation character. 

For example, in code page 932, _ ismbbpunct tests if the argument ch is a single-byte punctuation 
character or a single-byte Katakana punctuation character. These are any characters for which the 
following expression is true: 

ispunct(ch) | | _ ismbbkpunct (ch) 

Note: The argument ch must represent a single-byte value (i.e., 0 <= ch <= 255 ). Incorrect results 
occur if the argument is a double-byte character. This is shown by the example below. 

Returns: The _ ismbbpunct function returns a non-zero value if the argument satisfies the condition; otherwise 

a zero value is returned. 

See Also: _ getmbcp,_ mbbtombc^_ mbc jisto jms,_ mbcjmstojis^ mbctombb,_ ismbbalnum, 

_ ismbbalpha,_ ismbbgraph,_ ismbbkalnum,_ ismbbkalpha^ ismbbkana, 

_ ismbbkprint,_ ismbbkpunct,_ ismbblead,_ ismbbprint^ ismbbtrail,_ mbbtombc, 
_ mbc jisto jms^_ mbc jmsto jis,_ mbctombb^_ mbbtype^ setmbcp 

Example: #include <stdio.h> 

#include <mbctype.h> 

unsigned int chars[] = { 

r r 

r 

r r 
• r 

'i', 

'A' , 

0x8140, /* double-byte space */ 

0x8260, /* double-byte A */ 

0x82A6, /* double-byte Hiragana */ 

0x8342, /* double-byte Katakana */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6, /* single-byte Katakana alphabetic */ 

OxDF, /* single-byte Katakana alphabetic */ 

OxEOAl /* double-byte Kanji */ 

}; 

♦ define SIZE sizeof( chars ) / sizeof ( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ); 
for ( i = 0; i < SIZE; i++ ) { 

printf( "%#6.4x is %sa single-byte " 

"punctuation character\n", 
chars[i], 

( _ ismbbpunct( chars [i] ) ) ? "" : "not " ); 

} 

} 
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produces the following: 

0x0020 is not a single-byte punctuation character 
0x002e is a single-byte punctuation character 
0x0031 is not a single-byte punctuation character 

0x0041 is not a single-byte punctuation character 

0x8140 is a single-byte punctuation character 
0x8260 is a single-byte punctuation character 
0x82a6 is not a single-byte punctuation character 

0x8342 is not a single-byte punctuation character 

OxOOal is a single-byte punctuation character 
0x00a6 is not a single-byte punctuation character 

OxOOdf is not a single-byte punctuation character 

OxeOal is a single-byte punctuation character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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Synopsis: #include <mbstring.h> 

int _ ismbbtrail( unsigned int ch ); 

Description: The _ ismbbtrail function tests if ch is a valid second byte of a multibyte character. 

For example, in code page 932, valid ranges are 0x40 through 0x7E and 0x80 through OxFC. 

Note: Only the least significant (trailing) byte of the argument ch is tested. If the argument is a 
double-byte character, the leading byte is ignored and may be invalid. This is shown by the example 
below. 

Returns: _ ismbbtrail returns a non-zero value if the argument is valid as the second byte of a multibyte 

character; otherwise zero is returned. 

See Also: _ getmbcp,_ mbbtombc^_ mbc jisto jms,_ mbcjmstojis^ mbctombb,_ ismbbalnum, 

_ ismbbalpha,_ ismbbgraph,_ ismbbkalnum,_ ismbbkalpha^ ismbbkana, 

_ ismbbkprint,_ ismbbkpunct,_ ismbblead,_ ismbbprint,_ ismbbpunct,_ mbbtombc, 
_ mbc jisto jms^_ mbc jmsto jis,_ mbctombb^_ mbbtype^ setmbcp 

Example: ((include <stdio.h> 

♦include <mbctype.h> 

unsigned int chars[] = { 

r r 

r 

r r 

• f 

'i', 

'A' , 

0x8140, /* double-byte space */ 

0x8260, /* double-byte A */ 

0x82A6, /* double-byte Hiragana */ 

0x8342, /* double-byte Katakana */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6, /* single-byte Katakana alphabetic */ 

OxDF, /* single-byte Katakana alphabetic */ 

OxEOAl /* double-byte Kanji */ 

} ; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ); 

for ( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x does %shave a valid second byte\n", 
chars[i] , 

( _ ismbbtrail(chars[i]&0xff) ) ? "" : "not " ); 

} 

} 

produces the following: 
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0x0020 does not have a valid second byte 
0x002e does not have a valid second byte 
0x0031 does not have a valid second byte 


0x0041 

does 

have 

a 

valid 

second 

byte 

0x8140 

does 

have 

a 

valid 

second 

byte 

0x8260 

does 

have 

a 

valid 

second 

byte 

0x82a6 

does 

have 

a 

valid 

second 

byte 

0x8342 

does 

have 

a 

valid 

second 

byte 

OxOOal 

does 

have 

a 

valid 

second 

byte 

0x00a6 

does 

have 

a 

valid 

second 

byte 

OxOOdf 

does 

have 

a 

valid 

second 

byte 

OxeOal 

does 

have 

a 

valid 

second 

byte 


Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

int _ ismbcalnum( unsigned int ch ) ; 

The _ ismbcalnum function tests if the multibyte character argument ch is an alphanumeric character. 
For example, in code page 932, ’A’ through ’Z’, ’a’ through ’z\ or 'O’ through '9' and its 
corresponding double-byte versions are alphanumeric (among others). An alphanumeric character is 
any character for which _ ismbcalpha or_ ismbcdigit is true. 

The _ ismbcalnum function returns zero if the argument is not an alphanumeric character; otherwise, 
a non-zero value is returned. 

_ getmbcp,_ ismbcalpha,_ ismbccntrl^_ ismbcdigit^ ismbcgraph,_ ismbchira, 

_ ismbckata^_ ismbcl0,_ ismbcll^_ ismbcl2,_ ismbclegal,_ ismbclower, 

_ ismbcprint^ ismbcpunct,_ ismbcspace,_ ismbcsymbol,_ ismbcupper, 

_ ismbcxdigit,_ mbbtype,_ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned int chars[] = { 

r r 
• r 

'A' , 


0x8143, 

/* 

double-byte 

, */ 


0x8254, 

/* 

double-byte 

5 */ 


0x8260, 

/* 

double-byte 

A */ 


0x8279, 

/* 

double-byte 

Z */ 


0x8281, 

/* 

double-byte 

a */ 


0x82 9A, 

/* 

double-byte 

z */ 


0x82 9F, 

/* 

double-byte 

Hiragana */ 


0x8340, 

/* 

double-byte 

Katakana */ 


0x837F, 

/* 

illegal double-byte character 

0x889E, 

/* 

double-byte 

L0 character 

*/ 

0x889F, 

/* 

double-byte 

LI character 

*/ 

0x98 9F, 

/* 

double-byte 

L2 character 

*/ 

0xA6 

/* 

single-byte 

Katakana */ 



} ; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ) ; 
for( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa valid " 

"multibyte alphanumeric character\n", 
chars [ i], 

( _ ismbcalnum( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 
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0x002e is not a valid multibyte alphanumeric character 
0x0031 is a valid multibyte alphanumeric character 
0x0041 is a valid multibyte alphanumeric character 
0x8143 is not a valid multibyte alphanumeric character 
0x8254 is a valid multibyte alphanumeric character 
0x8260 is a valid multibyte alphanumeric character 
0x8279 is a valid multibyte alphanumeric character 
0x8281 is a valid multibyte alphanumeric character 
0x829a is a valid multibyte alphanumeric character 
0x829f is a valid multibyte alphanumeric character 
0x8340 is a valid multibyte alphanumeric character 
0x837f is not a valid multibyte alphanumeric character 
0x889e is not a valid multibyte alphanumeric character 
0x889f is a valid multibyte alphanumeric character 
0x989f is a valid multibyte alphanumeric character 
0x00a6 is a valid multibyte alphanumeric character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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ismbcalpha 


Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

int _ ismbcalpha( unsigned int ch ) ; 

The _ ismbcalpha function tests if the multibyte character argument ch is an alphabetic character. 
For example, in code page 932, ’A’ through ’Z’ or ’a’ through ’z’ and its corresponding double-byte 
versions and the Katakana letters (0xA6 through OxDF) are alphabetic. 

The _ ismbcalpha function returns zero if the argument is not an alphabetic character; otherwise, a 
non-zero value is returned. 

_ getmbcp,_ ismbcalnum,_ ismbccntrl^_ ismbcdigit,_ ismbcgraph,_ ismbchira, 
_ ismbckata^ ismbclO,_ ismbcll^_ ismbcl2,_ ismbclegal,_ ismbclower, 

_ ismbcprint^ ismbcpunct,_ ismbcspace,_ ismbcsymbol,_ ismbcupper, 

_ ismbcxdigit,_ mbbtype^ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned int chars[] = { 

r r 
• r 

' 1' r 

'A' , 


0x8143, 

/* 

double-byte 

, */ 


0x8254, 

/* 

double-byte 

5 */ 


0x8260, 

/* 

double-byte 

A */ 


0x8279, 

/* 

double-byte 

Z */ 


0x8281, 

/* 

double-byte 

a */ 


0x82 9A, 

/* 

double-byte 

z */ 


0x82 9F, 

/* 

double-byte 

Hiragana */ 


0x8340, 

/* 

double-byte 

Katakana */ 


0x837F, 

/* 

illegal double-byte character 

0x889E, 

/* 

double-byte 

L0 character 

*/ 

0x889F, 

/* 

double-byte 

LI character 

*/ 

0x98 9F, 

/* 

double-byte 

L2 character 

*/ 

0xA6 

/* 

single-byte 

Katakana */ 



} ; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ) ; 
for( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa valid " 

"multibyte alphabetic character\n", 
chars[i], 

( _ ismbcalpha( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 
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0x002e is not a valid multibyte alphabetic character 

0x0031 is not a valid multibyte alphabetic character 

0x0041 is a valid multibyte alphabetic character 
0x8143 is not a valid multibyte alphabetic character 

0x8254 is not a valid multibyte alphabetic character 

0x8260 is a valid multibyte alphabetic character 
0x8279 is a valid multibyte alphabetic character 
0x8281 is a valid multibyte alphabetic character 
0x829a is a valid multibyte alphabetic character 
0x829f is a valid multibyte alphabetic character 
0x8340 is a valid multibyte alphabetic character 
0x837f is not a valid multibyte alphabetic character 

0x889e is not a valid multibyte alphabetic character 

0x889f is a valid multibyte alphabetic character 
0x989f is a valid multibyte alphabetic character 
0x00a6 is a valid multibyte alphabetic character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


♦include <mbstring.h> 

int _ ismbccntrl( unsigned int ch ) ; 

The _ ismbccntrl function tests for any multibyte control character. 

The _ ismbccntrl function returns a non-zero value when the argument is a member of this set of 
characters; otherwise, zero is returned. 

_ getmbcp,_ ismbcalnum,_ ismbcalpha,_ ismbcdigit,_ ismbcgraph,_ ismbchira, 
_ ismbckata^_ ismbclO,_ ismbcll^_ ismbcl2,_ ismbclegal,_ ismbclower, 

_ ismbcprint^ ismbcpunct,_ ismbcspace,_ ismbcsymbol,_ ismbcupper, 

_ ismbcxdigit,_ mbbtype,_ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned int chars[] = { 

OxOD, 


r r 

r r 



0x8140, 

/* 

double-byte 

space */ 

0x8143, 

/* 

double-byte 

t 

*/ 

0x8254, 

/* 

double-byte 

5 

*/ 

0x8260, 

/* 

double-byte 

A 

*/ 

0x8279, 

/* 

double-byte 

Z 

*/ 

0x8281, 

/* 

double-byte 

a 

*/ 

0x82 9A, 

/* 

double-byte 

z 

*/ 

0x98 9F, 
0xA6 

/* 

double-byte 

L2 

character 


} ; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ) ; 
for ( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa valid " 

"multibyte control character\n", 
chars[i], 

( _ ismbccntrl( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 
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OxOOOd is a valid multibyte control character 
0x002e is not a valid multibyte control character 

0x0020 is not a valid multibyte control character 

0x0031 is not a valid multibyte control character 

0x0041 is not a valid multibyte control character 

0x8140 is a valid multibyte control character 
0x8143 is a valid multibyte control character 
0x8254 is not a valid multibyte control character 

0x8260 is not a valid multibyte control character 

0x8279 is not a valid multibyte control character 

0x8281 is not a valid multibyte control character 

0x829a is not a valid multibyte control character 

0x989f is not a valid multibyte control character 

0x00a6 is not a valid multibyte control character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

int _ ismbcdigit( unsigned int ch ) ; 

The _ ismbcdigit function tests for any multibyte decimal-digit character ’0’ through ’9’. In code 
page 932, this includes the corresponding double-byte versions of these characters. 

The _ ismbcdigit function returns a non-zero value when the argument is a decimal-digit character. 
Otherwise, zero is returned. 


getmbcp,_ ismbcalnum,_ ismbcalpha,_ ismbccntrl^ ismbcgraph,_ ismbchira, 
ismbckata^ ismbcl0,_ ismbcll,_ ismbcl2 v _ ismbclegal^ ismbclower, 
ismbcprint,_ ismbcpunct,_ ismbcspace,_ ismbcsymbol,_ ismbcupper, 
ismbcxdigit,_ mbbtype,_ setmbcp 


♦include <stdio.h> 
♦include <mbctype.h> 
♦include <mbstring.h> 

unsigned int chars[] = { 


r r 



0x8143, 

/* 

double-byte 

t 

*/ 

0x8183, 

/* 

double-byte 

< 

*/ 

0x8254, 

/* 

double-byte 

5 

*/ 

0x8277, 

0xA6 

/* 

double-byte 

X 

*/ 


} ; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 


_ setmbcp( 932 ); 
for ( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa valid " 

"multibyte digit characterin'', 
chars[i], 

( _ ismbcdigit( chars[i] ) ) ? "" : "not " ); 

} 

} 


produces the following: 


0x002e 

0x0031 

0x0041 

0x8143 

0x8183 

0x8254 

0x8277 

0x00a6 


is not a valid multibyte digit character 
is a valid multibyte digit character 
is not a valid multibyte digit character 
is not a valid multibyte digit character 
is not a valid multibyte digit character 
is a valid multibyte digit character 
is not a valid multibyte digit character 
is not a valid multibyte digit character 
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Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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ismbcgraph 


Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

int _ ismbcgraph( unsigned int ch ) ; 

The _ ismbcgraph function tests for any printable multibyte character except space (’ ’). The 
_ ismbcprint function is similar, except that the space character is also included in the character set 
being tested. 

The _ ismbcgraph function returns a non-zero value when the argument is a member of this set of 
characters; otherwise, zero is returned. 

_ getmbcp,_ ismbcalnum,_ ismbcalpha,_ ismbccntrl,_ ismbcdigit,_ ismbchira, 

_ ismbck.ata.L_ ismbcl0,_ ismbcll^ ismbcl2,_ ismbclegal,_ ismbclower, 

_ ismbcprint^ ismbcpunct,_ ismbcspace,_ ismbcsymbol,_ ismbcupper, 

_ ismbcxdigit,_ mbbtype^_ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned int chars[] = { 


r r 

r r 



0x8140, 

/* 

double-byte 

space */ 

0x8143, 

/* 

double-byte 

t 

*/ 

0x8254, 

/* 

double-byte 

5 

*/ 

0x8260, 

/* 

double-byte 

A 

*/ 

0x8279, 

/* 

double-byte 

Z 

*/ 

0x8281, 

/* 

double-byte 

a 

*/ 

0x82 9A, 

/* 

double-byte 

z 

*/ 

0x98 9F, 
0xA6 

/* 

double-byte 

L2 

character 


} ; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ) ; 
for ( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa valid " 

"multibyte graph characterin'', 
chars[i], 

( _ ismbcgraph( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 
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0x002e is a valid multibyte graph character 
0x0020 is not a valid multibyte graph character 
0x0031 is a valid multibyte graph character 
0x0041 is a valid multibyte graph character 
0x8140 is not a valid multibyte graph character 
0x8143 is a valid multibyte graph character 
0x8254 is a valid multibyte graph character 
0x8260 is a valid multibyte graph character 
0x8279 is a valid multibyte graph character 
0x8281 is a valid multibyte graph character 
0x829a is a valid multibyte graph character 
0x989f is a valid multibyte graph character 
0x00a6 is a valid multibyte graph character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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ismbchira 


Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

int _ ismbchira( unsigned int ch ); 

The _ ismbchira function tests for a double-byte Hiragana character. A double-byte Hiragana 
character is any character for which the following expression is true: 

0x829F <= ch <= 0x82Fl 

Note: The Japanese double-byte character set includes Kanji, Hiragana, and Katakana characters - both 
alphabetic and numeric. Kanji is the ideogram character set of the Japanese character set. Hiragana and 
Katakana are two types of phonetic character sets of the Japanese character set. The Hiragana code set 
includes 83 characters and the Katakana code set includes 86 characters. 

The _ ismbchira function returns a non-zero value when the argument is a member of this set of 
characters; otherwise, zero is returned. 

_ getmbcp^ ismbcalnum,_ ismbcalpha,_ ismbccntrl,_ ismbcdigit,_ ismbcgraph, 
_ ismbckata^ ismbcl0,_ ismbcll^ ismbcl2 v _ ismbclegal,_ ismbclower, 

_ ismbcprint^ ismbcpunct,_ ismbcspace,_ ismbcsymbol,_ ismbcupper, 

_ ismbcxdigit,_ mbbtype^ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned int chars[] = { 

'A' , 


0x8140, 

/* 

double-byte 

space */ 


0x8143, 

/* 

double-byte 

, */ 


0x8260, 

/* 

double-byte 

A */ 


0x82 9F, 

/* 

double-byte 

Hiragana 

*/ 

0x8340, 

/* 

double-byte 

Katakana 

*/ 

0x837F, 

/* 

illegal double-byte 

character 

0x98 9F, 

/* 

double-byte 

L2 character */ 

0xA6 

/* 

single-byte 

Katakana 

*/ 


}; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ) ; 
for( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa valid " 

"Hiragana character\n", 
chars [ i], 

( _ ismbchira( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 
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0x0041 is not a valid Hiragana character 

0x8140 is not a valid Hiragana character 

0x8143 is not a valid Hiragana character 

0x8260 is not a valid Hiragana character 

0x829f is a valid Hiragana character 
0x8340 is not a valid Hiragana character 

0x837f is not a valid Hiragana character 

0x989f is not a valid Hiragana character 

0x00a6 is not a valid Hiragana character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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ismbckata 


Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

int _ ismbckata( unsigned int ch ); 

The _ ismbckata function tests for a double-byte Katakana character. A double-byte Katakana 
character is any character for which the following expression is true: 

0x8340 <= ch <= 0x8396 && ch != 0x837F 

Note: The Japanese double-byte character set includes Kanji, Hiragana, and Katakana characters - both 
alphabetic and numeric. Kanji is the ideogram character set of the Japanese character set. Hiragana and 
Katakana are two types of phonetic character sets of the Japanese character set. The Hiragana code set 
includes 83 characters and the Katakana code set includes 86 characters. 

The _ ismbckata function returns a non-zero value when the argument is a member of this set of 
characters; otherwise, zero is returned. 

_ getmbcp,_ ismbcalnum,_ ismbcalpha,_ ismbccntrl,_ ismbcdigit,_ ismbcgraph, 
_ ismbchira,_ ismbcl0,_ ismbcll^ ismbcl2 v _ ismbclegal,_ ismbclower, 

_ ismbcprint^ ismbcpunct,_ ismbcspace,_ ismbcsymbol,_ ismbcupper, 

_ ismbcxdigit,_ mbbtype^ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned int chars[] = { 

'A' , 


0x8140, 

/* 

double-byte 

space */ 


0x8143, 

/* 

double-byte 

, */ 


0x8260, 

/* 

double-byte 

A */ 


0x82 9F, 

/* 

double-byte 

Hiragana 

*/ 

0x8340, 

/* 

double-byte 

Katakana 

*/ 

0x837F, 

/* 

illegal double-byte 

character 

0x98 9F, 

/* 

double-byte 

L2 character */ 

0xA6 

/* 

single-byte 

Katakana 

*/ 


}; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ) ; 
for( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa valid " 

"Katakana character\n", 
chars [ i], 

( _ ismbckata( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 
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0x0041 is not a valid Katakana character 

0x8140 is not a valid Katakana character 

0x8143 is not a valid Katakana character 

0x8260 is not a valid Katakana character 

0x829f is not a valid Katakana character 

0x8340 is a valid Katakana character 

0x837f is not a valid Katakana character 

0x989f is not a valid Katakana character 

0x00a6 is not a valid Katakana character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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ismbcIO 


Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

int _ ismbcIO( unsigned int ch ) ; 

The _ ismbcIO function tests if the argument ch is in the set of double-byte characters that include 
Hiragana, Katakana, punctuation symbols, graphical symbols, Roman and Cyrillic alphabets, etc. 
Double-byte Kanji characters are not in this set. These are any characters for which the following 
expression is true: 

0x8140 <= ch <= 0x889E && ch != 0x837F 

The _ ismbcIO function tests if the argument is a valid double-byte character (i.e., it checks that the 
lower byte is not in the ranges 0x00 - 0x3F, 0x7F, or OxFD - OxFF). 

Note: The Japanese double-byte character set includes Kanji, Hiragana, and Katakana characters - both 
alphabetic and numeric. Kanji is the ideogram character set of the Japanese character set. Hiragana and 
Katakana are two types of phonetic character sets of the Japanese character set. The Hiragana code set 
includes 83 characters and the Katakana code set includes 86 characters. 

The _ ismbcIO function returns a non-zero value when the argument is a member of this set of 
characters; otherwise, zero is returned. 

_ getmbcp,_ ismbcalnum,_ ismbcalpha,_ ismbccntrl,_ ismbcdigit,_ ismbcgraph, 
_ ismbchira,_ ismbckata^ ismbcll,_ ismbcl2,_ ismbclegal,_ ismbclower, 

_ ismbcprint^ ismbcpunct,_ ismbcspace,_ ismbcsymbol,_ ismbcupper, 

_ ismbcxdigit,_ mbbtype^ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned int chars[] = { 


'A' , 

0x8140, 

/* 

double-byte 

space */ 


0x8143, 

/* 

double-byte 

, */ 


0x8260, 

/* 

double-byte 

A */ 


0x82 9F, 

/* 

double-byte 

Hiragana */ 


0x8340, 

/* 

double-byte 

Katakana */ 


0x837F, 

/* 

illegal double-byte character */ 

0x889E, 

/* 

double-byte 

L0 character 

*/ 

0x889F, 

/* 

double-byte 

LI character 

*/ 

0x98 9F, 

/* 

double-byte 

L2 character 

*/ 

0xA6 

/* 

single-byte 

Katakana */ 


ine SIZE 

si 

.zeof( chars 

) / sizeof( 

unsigned int 


void main() 

1 

int i; 
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Classification: 

Systems: 


_ setmbcp( 932 ); 
for ( i = 0; i < SIZE; i++ ) { 

printf( "%#6.4x is %sa valid " 

"JIS L0 character\n", 
chars[i], 

( _ ismbcIO( chars[i] ) ) ? "" : "not " ); 

} 

} 


produces the following: 


0x0041 is 
0x8140 is 
0x8143 is 
0x8260 is 
0x829f is 
0x8340 is 
0x837f is 
0x889e is 
0x889f is 
0x989f is 
0x00a6 is 

WATCOM 


not a valid 
a valid JIS 
a valid JIS 
a valid JIS 
a valid JIS 
a valid JIS 
not a valid 
a valid JIS 
not a valid 
not a valid 
not a valid 


JIS L0 character 
L0 character 
L0 character 
L0 character 
L0 character 
L0 character 
JIS L0 character 
L0 character 
JIS L0 character 
JIS L0 character 
JIS L0 character 


DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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ism beII 


Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

int _ ismbcll( unsigned int ch ) ; 

The _ ismbcll function tests if the argument ch is a JIS (Japan Industrial Standard) level 1 
double-byte character code. These are any valid double-byte characters for which the following 
expression is true: 

0x889F <= ch <= 0x9872 

The _ ismbcll function tests if the argument is a valid double-byte character (i.e., it checks that the 
lower byte is not in the ranges 0x00 - 0x3F, 0x7F, or OxFD - OxFF). 

Note: JIS establishes two levels of the Kanji double-byte character set. One is called double-byte Kanji 
code set level 1 and the other is called double-byte Kanji code set level 2. Usually Japanese personal 
computers have font ROM/RAM support for both levels. 

Valid double-byte characters are those in which the first byte falls in the range 0x81 - 0x9F or OxEO - 
OxFC and whose second byte falls in the range 0x40 - 0x7E or 0x80 - OxFC. 

The _ ismbcll function returns a non-zero value when the argument is a member of this set of 
characters; otherwise, zero is returned. 

_ getmbcp^ ismbcalnum,_ ismbcalpha,_ ismbccntrl,_ ismbcdigit,_ ismbegraph, 
_ ismbehira^ ismbekata^ ismbcl0,_ ismbcl2,_ ismbclegal,_ ismbclower, 

_ ismbeprint^ ismbcpunct,_ ismbcspace,_ ismbcsymbol,_ ismbeupper, 

_ ismbcxdigit,_ mbbtype^ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned int chars[] = { 


'A' , 

0x8140, 

/* 

double-byte 

space */ 


0x8143, 

/* 

double-byte 

, */ 


0x8260, 

/* 

double-byte 

A */ 


0x82 9F, 

/* 

double-byte 

Hiragana */ 


0x8340, 

/* 

double-byte 

Katakana */ 


0x837F, 

/* 

illegal double-byte character */ 

0x889E, 

/* 

double-byte 

L0 character 

*/ 

0x889F, 

/* 

double-byte 

LI character 

*/ 

0x98 9F, 

/* 

double-byte 

L2 character 

*/ 

0xA6 

/* 

single-byte 

Katakana */ 


:ine SIZE 

si 

.zeof( chars 

) / sizeof( 

unsigned int 


void main() 

{ 

int i; 
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Classification: 

Systems: 


_ setmbcp( 932 ) ; 
for( i = 0; i < SIZE; i++ ) { 

printf( "%#6.4x is %sa valid " 

"JIS LI character\n", 
chars[i], 

( _ismbcll( chars [i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 


0x0041 

is 

not 

a 

valid 

JIS 

LI 

character 

0x8140 

is 

not 

a 

valid 

JIS 

LI 

character 

0x8143 

is 

not 

a 

valid 

JIS 

LI 

character 

0x8260 

is 

not 

a 

valid 

JIS 

LI 

character 

0x82 9f 

is 

not 

a 

valid 

JIS 

LI 

character 

0x8340 

is 

not 

a 

valid 

JIS 

LI 

character 

0x837f 

is 

not 

a 

valid 

JIS 

LI 

character 

0x889e 

is 

not 

a 

valid 

JIS 

LI 

character 

0x889f 

is 

a valid JIS 

LI i 

character 

0x98 9f 

is 

not 

a 

valid 

JIS 

LI 

character 

0x00a6 

is 

not 

a 

valid 

JIS 

LI 

character 


WATCOM 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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ismbcl2 


Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

int _ ismbcl2( unsigned int ch ) ; 

The _ ismbcl2 function tests if the argument ch is a JIS (Japan Industrial Standard) level 2 
double-byte character code. These are any valid double-byte characters for which the following 
expression is true: 

0x989F <= ch <= 0xEA9E 

The _ ismbcl2 function tests if the argument is a valid double-byte character (i.e., it checks that the 
lower byte is not in the ranges 0x00 - 0x3F, 0x7F, or OxFD - OxFF). 

Note: JIS establishes two levels of the Kanji double-byte character set. One is called double-byte Kanji 
code set level 1 and the other is called double-byte Kanji code set level 2. Usually Japanese personal 
computers have font ROM/RAM support for both levels. 

Valid double-byte characters are those in which the first byte falls in the range 0x81 - 0x9F or OxEO - 
OxFC and whose second byte falls in the range 0x40 - 0x7E or 0x80 - OxFC. 

The _ ismbcl2 function returns a non-zero value when the argument is a member of this set of 
characters; otherwise, zero is returned. 

_ getmbcp,_ ismbcalnum,_ ismbcalpha,_ ismbccntrl,_ ismbcdigit,_ ismbcgraph, 
_ ismbchira^ ismbckata^ ismbcl0,_ ismbcll,_ ismbclegal,_ ismbclower, 

_ ismbcprint^ ismbcpunct,_ ismbcspace,_ ismbcsymbol,_ ismbcupper, 

_ ismbcxdigit,_ mbbtype^ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned int chars[] = { 

'A' , 


0x8140, 

/* 

double-byte 

space */ 


0x8143, 

/* 

double-byte 

, */ 


0x8260, 

/* 

double-byte 

A */ 


0x82 9F, 

/* 

double-byte 

Hiragana */ 


0x8340, 

/* 

double-byte 

Katakana */ 


0x837F, 

/* 

illegal double-byte character */ 

0x889E, 

/* 

double-byte 

L0 character 

*/ 

0x889F, 

/* 

double-byte 

LI character 

*/ 

0x98 9F, 

/* 

double-byte 

L2 character 

*/ 

0xEA9E, 

/* 

double-byte 

L2 character 

*/ 

0xA6 

/* 

single-byte 

Katakana */ 


ine SIZE 

si 

.zeof( chars 

) / sizeof( 

unsigned int 


void main() 

{ 

int i; 
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_ setmbcp( 932 ) ; 
for( i = 0; i < SIZE; i++ ) { 

printf( "%#6.4x is %sa valid " 

"JIS L2 character\n", 
chars[i], 

( _ ismbcl2( chars[i] ) ) ? "" 

} 

} 

produces the following: 


0x0041 

is 

not 

a 

valid 

JIS 

L2 

character 

0x8140 

is 

not 

a 

valid 

JIS 

L2 

character 

0x8143 

is 

not 

a 

valid 

JIS 

L2 

character 

0x8260 

is 

not 

a 

valid 

JIS 

L2 

character 

0x82 9f 

is 

not 

a 

valid 

JIS 

L2 

character 

0x8340 

is 

not 

a 

valid 

JIS 

L2 

character 

0x837f 

is 

not 

a 

valid 

JIS 

L2 

character 

0x889e 

is 

not 

a 

valid 

JIS 

L2 

character 

0x889f 

is 

not 

a 

valid 

JIS 

L2 

character 

0x98 9f 

is 

a valid JIS 

L2 

character 

0xea9e 

is 

a valid JIS 

L2 

character 

0x00a6 

is 

not 

a 

valid 

JIS 

L2 

character 


Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 


"not " ) ; 
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ism be legal 


Synopsis: #include <mbstring.h> 

int _ ismbclegal( unsigned int dbch ); 

Description: The _ ismbclegal function tests for a valid multibyte character. Multibyte characters include both 
single-byte and double-byte characters. For example, in code page 932, a legal double-byte character is 
one in which the first byte is within the ranges 0x81 - 0x9F or OxEO - OxFC, while the second byte is 
within the ranges 0x40 - 0x7E or 0x80 - OxFC. This is summarized in the following diagram. 

[ 1st byte ] [ 2nd byte ] 

0x81-0x9F 0x40-0xFC 

or except 0x7F 

OxEO-OxFC 

Returns: The _ ismbclegal function returns a non-zero value when the argument is a member of this set of 

characters; otherwise, zero is returned. 

See Also: _ getmbcp,_ ismbcalnum,_ ismbcalpha,_ ismbccntrl^_ ismbcdigit,_ ismbegraph, 

_ ismbchira,_ ismbckata^_ ismbcl0,_ ismbcll^_ ismbcl2,_ ismbclower, 

_ ismbcprint,_ ismbcpunct,_ ismbcspace,_ ismbcsymbol,_ ismbeupper, 

_ ismbcxdigit,_ mbbtype^ setmbcp 

Example: #include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned int chars [] = { 

'A' , 

0x8131, /* illegal double-byte character */ 

0x8140, /* double-byte space */ 

0x8143, /* double-byte , */ 

0x8260, /* double-byte A */ 

0x829F, /* double-byte Hiragana */ 

0x8340, /* double-byte Katakana */ 

0x837F, /* illegal double-byte character */ 

0x889E, /* double-byte L0 character */ 

0x889F, /* double-byte LI character */ 

0x989F, /* double-byte L2 character */ 

0xEA9E, /* double-byte L2 character */ 

0xA6 /* single-byte Katakana */ 

} ; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ); 
for ( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa legal " 

"double-byte character\n", 
chars[i], 

( _ ismbclegal( chars[i] ) ) ? "" : "not " ); 

} 

} 
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ismbclegal 


produces the following: 

0x0041 is not a legal double-byte character 
0x8131 is not a legal double-byte character 
0x8140 is a legal double-byte character 
0x8143 is a legal double-byte character 
0x8260 is a legal double-byte character 
0x829f is a legal double-byte character 
0x8340 is a legal double-byte character 
0x837f is not a legal double-byte character 
0x889e is a legal double-byte character 
0x889f is a legal double-byte character 
0x989f is a legal double-byte character 
0xea9e is a legal double-byte character 
0x00a6 is not a legal double-byte character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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ismbclower 


Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

int _ ismbclower( unsigned int ch ) ; 

The _ ismbclower function tests for a valid lowercase multibyte character. Multibyte characters 
include both single-byte and double-byte characters. For example, in code page 932, a lowercase 
double-byte character is one for which the following expression is true: 

0x8281 <= c <= 0x829A 

The _ ismbclower function returns a non-zero value when the argument is a member of this set of 
characters; otherwise, zero is returned. 

_ getmbcp,_ ismbcalnum,_ ismbcalpha,_ ismbccntrl,_ ismbcdigit,_ ismbcgraph, 
_ ismbchira^ ismbckata,_ ismbcl0,_ ismbcll,_ ismbcl2 i _ ismbclegal, 

_ ismbcprint^ ismbcpunct,_ ismbcspace,_ ismbcsymbol,_ ismbcupper, 

_ ismbcxdigit,_ mbbtype^ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned int chars[] = { 

' 1 ' , 

'A' , 

'a' , 


0x8140, 

/* 

double-byte 

space */ 

0x8143, 

/* 

double-byte 

t 

*/ 

0x8254, 

/* 

double-byte 

5 

*/ 

0x8260, 

/* 

double-byte 

A 

*/ 

0x8279, 

/* 

double-byte 

Z 

*/ 

0x8281, 

/* 

double-byte 

a 

*/ 

0x82 9A, 

/* 

double-byte 

z 

*/ 

0x98 9F, 
0xA6 

/* 

double-byte 

L2 

character 


} ; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

1 

int i; 

_ setmbcp( 932 ) ; 
for( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa valid " 

"multibyte lowercase character\n", 
chars[i], 

( _ ismbclower( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 
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0x0031 is not a valid multibyte lowercase character 

0x0041 is not a valid multibyte lowercase character 

0x0061 is a valid multibyte lowercase character 
0x8140 is not a valid multibyte lowercase character 

0x8143 is not a valid multibyte lowercase character 

0x8254 is not a valid multibyte lowercase character 

0x8260 is not a valid multibyte lowercase character 

0x8279 is not a valid multibyte lowercase character 

0x8281 is a valid multibyte lowercase character 
0x829a is a valid multibyte lowercase character 
0x989f is not a valid multibyte lowercase character 

0x00a6 is not a valid multibyte lowercase character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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ismbcprint 


Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

int _ ismbcprint( unsigned int ch ) ; 

The _ ismbcprint function tests for any printable multibyte character including space (’ ’). The 
_ ismbcgraph function is similar, except that the space character is not included in the character set 
being tested. 

The _ ismbcprint function returns a non-zero value when the argument is a member of this set of 
characters; otherwise, zero is returned. 

_ getmbcp^_ ismbcalnum,_ ismbcalpha,_ ismbccntrl,_ ismbcdigit,_ ismbcgraph, 
_ ismbchira^ ismbckata,_ ismbclO,_ ismbcll,_ ismbcl2,_ ismbclegal, 

_ ismbclower^ ismbcpunct,_ ismbcspace,_ ismbcsymbol,_ ismbcupper, 

_ ismbcxdigit,_ mbbtype^_ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned int chars[] = { 


r r 

r r 



0x8140, 

/* 

double-byte 

space */ 

0x8143, 

/* 

double-byte 

t 

*/ 

0x8254, 

/* 

double-byte 

5 

*/ 

0x8260, 

/* 

double-byte 

A 

*/ 

0x8279, 

/* 

double-byte 

Z 

*/ 

0x8281, 

/* 

double-byte 

a 

*/ 

0x82 9A, 

/* 

double-byte 

z 

*/ 

0x98 9F, 
0xA6 

/* 

double-byte 

L2 

character 


} ; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ) ; 
for( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa valid " 

"multibyte print characterin'', 
chars[i], 

( _ ismbcprint( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 
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0x002e is a valid multibyte print character 
0x0020 is a valid multibyte print character 
0x0031 is a valid multibyte print character 
0x0041 is a valid multibyte print character 
0x8140 is a valid multibyte print character 
0x8143 is a valid multibyte print character 
0x8254 is a valid multibyte print character 
0x8260 is a valid multibyte print character 
0x8279 is a valid multibyte print character 
0x8281 is a valid multibyte print character 
0x829a is a valid multibyte print character 
0x989f is a valid multibyte print character 
0x00a6 is a valid multibyte print character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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ismbcpunct 


Synopsis: #include <mbstring.h> 

int _ ismbcpunct( unsigned int ch ); 

Description: The _ ismbcpunct function tests for any multibyte punctuation character. 

Returns: The _ ismbcpunct function returns a non-zero value when the argument is a member of this set of 

characters; otherwise, zero is returned. 

See Also: _ getmbcp,_ ismbcalnum,_ ismbcalpha,_ ismbccntrl^_ ismbcdigit,_ ismbcgraph, 

_ ismbchira,_ ismbckata^ ismbclO,_ ismbcll^_ ismbcl2,_ ismbclegal, 

_ ismbclower^ ismbcprint^_ ismbcspace,_ ismbcsymbol,_ ismbcupper, 

_ ismbcxdigit,_ mbbtype^_ setmbcp 

Example: #include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned int chars [ ] = { 

r r 
• r 
r r 

r 

'i', 

'A' , 

0x8140, /* double-byte space */ 

0x8143, /* double-byte , */ 

0x8254, /* double-byte 5 */ 

0x8260, /* double-byte A */ 

0x8279, /* double-byte Z */ 

0x8281, /* double-byte a */ 

0x829A, /* double-byte z */ 

0x989F, /* double-byte L2 character */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6 /* single-byte Katakana alphabetic */ 

} ; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ); 
for ( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa valid " 

"multibyte punctuation character\n", 
chars[i], 

( _ ismbcpunct( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 
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0x002e is a valid multibyte punctuation character 
0x0020 is not a valid multibyte punctuation character 

0x0031 is not a valid multibyte punctuation character 

0x0041 is not a valid multibyte punctuation character 

0x8140 is not a valid multibyte punctuation character 

0x8143 is a valid multibyte punctuation character 
0x8254 is not a valid multibyte punctuation character 

0x8260 is not a valid multibyte punctuation character 

0x8279 is not a valid multibyte punctuation character 

0x8281 is not a valid multibyte punctuation character 

0x829a is not a valid multibyte punctuation character 

0x989f is not a valid multibyte punctuation character 

OxOOal is a valid multibyte punctuation character 
0x00a6 is not a valid multibyte punctuation character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 


532 Library Functions and Macros 




ismbcspace 


Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

int _ ismbcspace( unsigned int ch ) ; 

The _ ismbcspace function tests for any multibyte space character. Multibyte characters include 
both single-byte and double-byte characters. For example, in code page 932, the double-byte space 
character is 0x8140. 

The _ ismbcspace function returns a non-zero value when the argument is a member of this set of 
characters; otherwise, zero is returned. 

_ getmbcp^_ ismbcalnum,_ ismbcalpha,_ ismbccntrl,_ ismbcdigit,_ ismbcgraph, 
_ ismbchira^ ismbckata,_ ismbcl0,_ ismbcll,_ ismbcl2,_ ismbclegal, 

_ ismbclower^ ismbcprint,_ ismbcpunct,_ ismbcsymbol,_ ismbcupper, 

_ ismbcxdigit,_ mbbtype^ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned int chars[] = { 

0x09, 


r r 

r f 



0x8140, 

/* 

double-byte 

space */ 

0x8143, 

/* 

double-byte 

t 

*/ 

0x8254, 

/* 

double-byte 

5 

*/ 

0x8260, 

/* 

double-byte 

A 

*/ 

0x8279, 

/* 

double-byte 

Z 

*/ 

0x8281, 

/* 

double-byte 

a 

*/ 

0x82 9A, 

/* 

double-byte 

z 

*/ 

0x98 9F, 
0xA6 

/* 

double-byte 

L2 

character 


} ; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ) ; 
for ( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa valid " 

"multibyte space character\n", 
chars[i], 

( _ ismbcspace( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 
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0x0009 is a valid multibyte space character 
0x002e is not a valid multibyte space character 
0x0020 is a valid multibyte space character 
0x0031 is not a valid multibyte space character 

0x0041 is not a valid multibyte space character 

0x8140 is a valid multibyte space character 
0x8143 is not a valid multibyte space character 

0x8254 is not a valid multibyte space character 

0x8260 is not a valid multibyte space character 

0x8279 is not a valid multibyte space character 

0x8281 is not a valid multibyte space character 

0x829a is not a valid multibyte space character 

0x989f is not a valid multibyte space character 

0x00a6 is not a valid multibyte space character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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ismbcsymbol 


Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

int _ ismbcsymbol( unsigned int ch ); 

The _ ismbcsymbol function tests for a valid multibyte symbol character (punctuation and other 
special graphical symbols). For example, in code page 932, _ ismbcsymbol tests for a double-byte 
Kigou character and returns true if and only if 

0x8141 <= ch <= 0x81AC && ch != 0x817F 

The _ ismbcsymbol function returns a non-zero value when the argument is a member of this set of 
characters; otherwise, zero is returned. 

_ getmbcp,_ ismbcalnum,_ ismbcalpha,_ ismbccntrl,_ ismbcdigit,_ ismbcgraph, 
_ ismbchira^ ismbckata,_ ismbcl0,_ ismbcll,_ ismbcl2,_ ismbclegal, 

_ ismbclower^ ismbcprint,_ ismbcpunct,_ ismbcspace,_ ismbcupper, 

_ ismbcxdigit,_ mbbtype^_ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned int chars[] = { 


r r 

r r 



0x8140, 

/* 

double-byte 

space */ 

0x8143, 

/* 

double-byte 

t 

*/ 

0x8254, 

/* 

double-byte 

5 

*/ 

0x8260, 

/* 

double-byte 

A 

*/ 

0x8279, 

/* 

double-byte 

Z 

*/ 

0x8281, 

/* 

double-byte 

a 

*/ 

0x82 9A, 

/* 

double-byte 

z 

*/ 

0x98 9F, 
0xA6 

/* 

double-byte 

L2 

character 


} ; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ) ; 
for( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa valid " 

"multibyte symbol character\n", 
chars [ i], 

( _ ismbcsymbol( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 
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0x002e is not a valid multibyte symbol character 

0x0020 is not a valid multibyte symbol character 

0x0031 is not a valid multibyte symbol character 

0x0041 is not a valid multibyte symbol character 

0x8140 is not a valid multibyte symbol character 

0x8143 is a valid multibyte symbol character 
0x8254 is not a valid multibyte symbol character 

0x8260 is not a valid multibyte symbol character 

0x8279 is not a valid multibyte symbol character 

0x8281 is not a valid multibyte symbol character 

0x829a is not a valid multibyte symbol character 

0x989f is not a valid multibyte symbol character 

0x00a6 is not a valid multibyte symbol character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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ismbcupper 


Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

int _ ismbcupper( unsigned int ch ) ; 

The _ ismbcupper function tests for a valid uppercase multibyte character. Multibyte characters 
include both single-byte and double-byte characters. For example, in code page 932, an uppercase 
double-byte character is one for which the following expression is true: 

0x8260 <= c <= 0x8279 

The _ ismbcupper function returns a non-zero value when the argument is a member of this set of 
characters; otherwise, zero is returned. 

_ getmbcp,_ ismbcalnum,_ ismbcalpha,_ ismbccntrl,_ ismbcdigit,_ ismbcgraph, 
_ ismbchira^ ismbckata,_ ismbcl0,_ ismbcll,_ ismbcl2,_ ismbclegal, 

_ ismbclower^ ismbcprint,_ ismbcpunct,_ ismbcspace,_ ismbcsymbol, 

_ ismbcxdigit,_ mbbtype^ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned int chars[] = { 

' 1 ' , 

'A' , 

'a' , 


0x8140, 

/* 

double-byte 

space */ 

0x8143, 

/* 

double-byte 

t 

*/ 

0x8254, 

/* 

double-byte 

5 

*/ 

0x8260, 

/* 

double-byte 

A 

*/ 

0x8279, 

/* 

double-byte 

Z 

*/ 

0x8281, 

/* 

double-byte 

a 

*/ 

0x82 9A, 

/* 

double-byte 

z 

*/ 

0x98 9F, 
0xA6 

/* 

double-byte 

L2 

character 


} ; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ) ; 
for ( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa valid " 

"multibyte uppercase character\n", 
chars[i], 

( _ ismbcupper( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 
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0x0031 is not a valid multibyte uppercase character 
0x0041 is a valid multibyte uppercase character 
0x0061 is not a valid multibyte uppercase character 

0x8140 is not a valid multibyte uppercase character 

0x8143 is not a valid multibyte uppercase character 

0x8254 is not a valid multibyte uppercase character 

0x8260 is a valid multibyte uppercase character 
0x8279 is a valid multibyte uppercase character 
0x8281 is not a valid multibyte uppercase character 

0x829a is not a valid multibyte uppercase character 

0x989f is not a valid multibyte uppercase character 

0x00a6 is not a valid multibyte uppercase character 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 


538 Library Functions and Macros 




ismbcxdigit 


Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

int _ ismbcxdigit( unsigned int ch ); 

The _ ismbcxdigit function tests for any multibyte hexadecimal-digit character ’O' through ’9’ or 
'A' through ’F\ In code page 932, this includes the corresponding double-byte versions of these 
characters. 


The _ ismbcxdigit function returns a non-zero value when the argument is a hexadecimal-digit 
character. Otherwise, zero is returned. 


_ getmbcp,_ ismbcalnum,_ ismbcalpha,_ ismbccntrl,_ ismbcdigit,_ ismbcgraph, 
_ ismbchira^ ismbckata,_ ismbclO,_ ismbcll,_ ismbcl2 v _ ismbclegal, 

_ ismbclower^ ismbcprint,_ ismbcpunct,_ ismbcspace,_ ismbcsymbol, 

_ ismbcupper^ mbbtype^_ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned int chars[] = { 


r r 



0x8143, 

/* 

double-byte 

II II 
r 

*/ 

0x8183, 

/* 

double-byte 

ii ^ ii 

*/ 

0x8254, 

/* 

double-byte 

ii 5 ii 

*/ 

0x8265, 

0xA6 

/* 

double-byte 

up ii 

*/ 


}; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ) ; 
for ( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x is %sa valid " 

"multibyte hexadecimal digit characterin' 1 , 
chars[i], 

( _ ismbcxdigit( chars[i] ) ) ? "" : "not " ); 

} 

} 


produces the following: 


0x002e 

0x0031 

0x0041 

0x8143 

0x8183 

0x8254 

0x8265 

0x00a6 


is not a valid multibyte hexadecimal digit character 
is a valid multibyte hexadecimal digit character 
is a valid multibyte hexadecimal digit character 
is not a valid multibyte hexadecimal digit character 
is not a valid multibyte hexadecimal digit character 
is a valid multibyte hexadecimal digit character 
is a valid multibyte hexadecimal digit character 
is not a valid multibyte hexadecimal digit character 
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Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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isnan 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <math.h> 
int isnan ( x ); 

The isnan macro determines whether its argument x is a NaN. First, an argument represented in a 
format wider than its semantic type is converted to its semantic type. Then determination is based on 
the type of the argument. 

The argument x must be an expression of real floating type. 

The isnan macro returns a nonzero value if and only if its argument has a NaN value. 

fpclassify, isfinite, isinf, isnormal, signbit 

♦include <math.h> 

♦include <stdio.h> 

void main( void ) 

{ 

printf( "NAN %s a NaN\n", 

isnan ( NAN ) ? "is" : "is not" ); 

} 

produces the following: 

NAN is a NaN 

ISOC 

MACRO 
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isnormal 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <math.h> 
int isnormal( x ); 

The isnormal macro determines whether its argument value is normal (neither zero, subnormal, 
infinite, nor NaN). First, an argument represented in a format wider than its semantic type is converted 
to its semantic type. Then determination is based on the type of the argument. 

The argument x must be an expression of real floating type. 

The isnormal macro returns a nonzero value if and only if its argument has a normal value. 

fpclassify, isfinite, isinf, isnan, signbit 

♦include <math.h> 

♦include <stdio.h> 

void main( void ) 

{ 

printf ( "zero %s a normal number\n", 

isnormal( 0.0 ) ? "is" : "is not" ); 

} 

produces the following: 

zero is not a normal number 

ISOC 

MACRO 


542 Library Functions and Macros 




isprint, iswprint 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


Systems: 


♦include <ctype.h> 
int isprint( int c ) ; 

♦include <wctype.h> 

int iswprint( wint_ t c ) ; 

The isprint function tests for any printable character including space (’ ’). The isgraph function 
is similar, except that the space character is excluded from the character set being tested. 

The iswprint function is a wide-character version of isprint that operates with wide-character 
argument. 

The isprint function returns a non-zero value when the argument is a printable character. The 
iswprint function returns a non-zero value when the argument is a printable wide character. 
Otherwise, zero is returned. 

isalnum, isalpha, isblank, iscntrl, isdigit, isgraph, isleadbyte, islower, 
ispunct, isspace, isupper, iswctype, isxdigit, tolower, toupper, towctrans 

♦include <stdio.h> 

♦include <ctype.h> 

char chars[] = { 

'A' , 

0x09, 

r r 

r 

0x7d 

} ; 


♦ define SIZE sizeof ( chars ) / sizeof ( char ) 

void main() 

{ 

int i; 

for( i = 0; i < SIZE; i++ ) { 

printf ( "Char %c is %sa printable characterin'', 
chars[i], 

( isprint( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 

Char A is a printable character 
Char is not a printable character 

Char is a printable character 
Char } is a printable character 

ISOC 

iswprint is ISO C95 

isprint - All, Linux, RDOS, Netware 
iswprint - All, Linux, RDOS, Netware 
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ispunct, iswpunct 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


♦include <ctype.h> 
int ispunct( int c ) ; 

♦include <wctype.h> 

int iswpunct( wint_ t c ) ; 

The ispunct function tests for any punctuation character such as a comma (,) or a period (.). 

The iswpunct function is a wide-character version of ispunct that operates with wide-character 
argument. 

The ispunct function returns a non-zero value when the argument is a punctuation character. The 
iswpunct function returns a non-zero value when the argument is a printable wide character that is 
neither the space wide character nor a wide character for which iswalnum is true. Otherwise, zero is 
returned. 

isalnum, isalpha, isblank, iscntrl, isdigit, isgraph, isleadbyte, islower, 
isprint, isspace, isupper, iswctype, isxdigit, tolower, toupper, towctrans 

♦include <stdio.h> 

♦include <ctype.h> 

char chars[] = { 

'A' , 

’ i ’ 

• r 

r r 

• f 

r r 

f f 

r . f 

• f 

r . f 

t 

} ; 

♦ define SIZE sizeof ( chars ) / sizeof( char ) 

void main() 

{ 

int i; 

for( i = 0; i < SIZE; i++ ) { 

printf ( "Char %c is %sa punctuation characterin' 1 , 
chars[i], 

( ispunct( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 

Char A is not a punctuation character 
Char ! is a punctuation character 
Char . is a punctuation character 
Char , is a punctuation character 
Char : is a punctuation character 
Char ; is a punctuation character 

ISOC 

iswpunct is ISO C95 
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ispunct, iswpunct 


Systems: 


ispunct - All, Linux, RDOS, 
iswpunct - All, Linux, RDOS 


Netware 

Netware 
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isspace, iswspace 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


♦include <ctype.h> 
int isspace( int c ); 
♦include <wctype.h> 
int iswspace( wint_ t c ) ; 


The isspace function tests for the following white-space characters: 


Constant 


Character 


,\ f , 

’\n’ 

’\r’ 

’\t’ 

’\v’ 


space 
form feed 

new-line or linefeed 
carriage return 
horizontal tab 
vertical tab 


The iswspace function is a wide-character version of isspace that operates with wide-character 
argument. 

The isspace function returns a non-zero character when the argument is one of the indicated 
white-space characters. The iswspace function returns a non-zero value when the argument is a wide 
character that corresponds to a standard white-space character or is one of an implementation-defined 
set of wide characters for which iswalnum is false. Otherwise, zero is returned. 

isalnum, isalpha, isblank, iscntrl, isdigit, isgraph, isleadbyte, islower, 
isprint, ispunct, isupper, iswctype, isxdigit, tolower, toupper, towctrans 

♦include <stdio.h> 

♦include <ctype.h> 

char chars[] = { 

'A' , 

0x09, 

r r 

r 

0x7d 

} ; 


♦define SIZE sizeof( chars ) / sizeof( char ) 

void main() 

{ 

int i; 

for( i = 0; i < SIZE; i++ ) { 

printf ( "Char %c is %sa space characterin'', 
chars[i], 

( isspace ( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 
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isspace, iswspace 


Char A is not a space character 
Char is a space character 

Char is a space character 

Char } is not a space character 

Classification: ISO C 

iswspace is ISO C95 

Systems: isspace - All, Linux, RDOS, Netware 

iswspace - All, Linux, RDOS, Netware 
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isupper, iswupper 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


Systems: 


♦include <ctype.h> 
int isupper ( int c ); 

♦include <wctype.h> 

int iswupper( wint_ t c ) ; 

The isupper function tests for any uppercase letter 'A' through 'Z\ 

The iswupper function is a wide-character version of isupper that operates with wide-character 
argument. 

The isupper function returns a non-zero value when the argument is an uppercase letter. The 
iswupper function returns a non-zero value when the argument is a wide character that corresponds 
to an uppercase letter, or if it is one of an implementation-defined set of wide characters for which none 
of iswcntrl, iswdigit, iswpunct, or iswspace is true. Otherwise, zero is returned. 

isalnum, isalpha, isblank, iscntrl, isdigit, isgraph, isleadbyte, islower, 
isprint, ispunct, isspace, iswctype, isxdigit, tolower, toupper, towctrans 

♦include <stdio.h> 

♦include <ctype.h> 

char chars[] = { 



} ; 


♦ define SIZE sizeof ( chars ) / sizeof ( char ) 

void main() 

{ 

int i; 

for( i = 0; i < SIZE; i++ ) { 

printf ( "Char %c is %san uppercase characterin'', 
chars[i], 

( isupper( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 

Char A is an uppercase character 
Char a is not an uppercase character 
Char z is not an uppercase character 
Char Z is an uppercase character 

ISOC 

iswupper is ISO C95 

isupper - All, Linux, RDOS, Netware 
iswupper - All, Linux, RDOS, Netware 
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iswctype 


Synopsis: #include <wctype.h> 

int iswctype ( wint_ t wc, wctype_ t desc ) ; 

Description: The iswctype function determines whether the wide character wc has the property described by desc. 
Valid values of desc are defined by the use of the wctype function. 

The twelve expressions listed below have a truth-value equivalent to a call to the wide character testing 
function shown. 

Expression Equivalent 

iswctype(wc, wctype("alnum")) iswalnum(wc) 

iswctype(wc, wctype)"alpha")) iswalpha(wc) 

iswctype(wc, wctype("blank")) iswblank(wc) 

iswctype(wc, wctype)"cntrl")) iswcntrl(wc) 

iswctype(wc, wctype)"digit")) iswdigit(wc) 

iswctype)wc, wctype)"graph")) iswgraph(wc) 

iswctype(wc, wctype("lower")) iswlower(wc) 

iswctype(wc, wctype)"print")) iswprint(wc) 

iswctype(wc, wctype)"punct")) iswpunct(wc) 

iswctype(wc, wctype)"space")) iswspace(wc) 

iswctype)wc, wctype("upper")) iswupper(wc) 

iswctype)wc, wctype)"xdigit")) iswxdigit(wc) 

Returns: The iswctype function returns non-zero (true) if and only if the value of the wide character wc has 

the property described by desc. 

See Also: isalnum, isalpha, isblank, iscntrl, isdigit, isgraph, isleadbyte, islower, 

isprint, ispunct, isspace, isupper, isxdigit, tolower, toupper, towctrans 

Example: 


Library Functions and Macros 549 





iswctype 


Classification: 

Systems: 


♦include <stdio.h> 
♦include <wctype.h> 

char *types[] = { 
"alnum", 
"alpha", 
"blank", 
"cntrl", 
"digit", 

"graph", 
"lower", 

"print", 

"punct", 
"space", 

"upper", 

"xdigit" 

} ; 


void main( void ) 

{ 

int i; 

wint_ t wc = 'A'; 

for( i = 0; i < 12; i 
if( iswctype ( wc, 
printf( "%s\n 

} 

produces the following: 

alnum 

alpha 

graph 

print 

upper 

xdigit 

ISO C95 

All, Linux, RDOS 


+ ) 

wctype ( types [i] ) ) ) 

, types[i] ); 
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isxdigit, iswxdigit 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


Systems: 


♦include <ctype.h> 
int isxdigit( int c ) ; 

♦include <wchar.h> 

int iswxdigit( wint_ t c ) ; 

The isxdigit function tests for any hexadecimal-digit character. These characters are the digits (’O’ 
through ’9’) and the letters (’a' through ’f) and (’A' through ’F’). 

The iswxdigit function is a wide-character version of isxdigit that operates with wide-character 
argument. 

The isxdigit function returns a non-zero value when the argument is a hexadecimal-digit character. 
The iswxdigit function returns a non-zero value when the argument is a wide character that 
corresponds to a hexadecimal-digit character. Otherwise, zero is returned. 

isalnum, isalpha, isblank, iscntrl, isdigit, isgraph, isleadbyte, islower, 
isprint, ispunct, isspace, isupper, iswctype, tolower, toupper, towctrans 

♦include <stdio.h> 

♦include <ctype.h> 

char chars[] = { 

'A' , 

'5', 

' $' 

}; 

.exmp break 

♦ define SIZE sizeof ( chars ) / sizeof( char ) 

void main() 

{ 

int i; 

for( i = 0; i < SIZE; i++ ) { 

printf( "Char %c is %sa hexadecimal digit" 

" character\n", chars[i], 

( isxdigit( chars[i] ) ) ? "" : "not " ); 

} 

} 

produces the following: 

Char A is a hexadecimal digit character 
Char 5 is a hexadecimal digit character 
Char $ is not a hexadecimal digit character 

ISOC 

iswxdigit is ISO C95 

isxdigit - All, Linux, RDOS, Netware 
iswxdigit - All, Linux, RDOS, Netware 
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itoa, Jtoa, Jtow 


Synopsis: 

Description: 


Returns: 
See Also: 

Example: 


Classification: 

Systems: 


#include <stdlib.h> 

char *itoa( int value, char *buffer, int radix ); 
char *_ itoa( int value, char *buffer, int radix ); 
wchar_ t *_ itow( int value, wchar_ t *buffer, 
int radix ); 

The itoa function converts the binary integer value into the equivalent string in base radix notation 
storing the result in the character array pointed to by buffer. A null character is appended to the result. 
The size of buffer must be at least (8 * sizeof(int) + 1) bytes when converting values in base 2. That 
makes the size 17 bytes on 16-bit machines, and 33 bytes on 32-bit machines. The value of radix must 
satisfy the condition: 

2 <= radix <= 36 


If radix is 10 and value is negative, then a minus sign is prepended to the result. 

The _ itoa function is identical toitoa. Use _ itoa for ANSI naming conventions. 

The _ itow function is a wide-character version ofitoa. It produces a wide-character string. 
The itoa function returns the pointer to the result. 

atoi, atol, atoll, Itoa, lltoa, sscanf, strtol, strtoll, strtoul, strtoull, 
strtoimax, strtoumax, ultoa, ulltoa, utoa 


♦include <stdio.h> 
♦include <stdlib.h> 

void main() 

{ 

char buffer[20]; 
int base; 


} 


for( base = 2; base <= 16; base = base + 2 ) 
printf ( "%2d %s\n", base, 

itoa( 12765, buffer, base ) ); 


produces the following: 

2 11000111011101 
4 3013131 
6 135033 
8 30735 
10 12765 
12 7479 
14 491b 
16 31dd 


WATCOM 

_itoa conforms to ANSI naming conventions 

itoa - All, Linux, RDOS, Netware 
_ itoa - All, Linux, RDOS, Netware 
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kbhit, _kbhit 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


♦include <conio.h> 
int kbhit ( void ); 
int _ kbhit ( void ) ; 

The kbhit function tests whether or not a keystroke is currently available. When one is available, the 
function getch or getche may be used to obtain the keystroke in question. 

With a stand-alone program, the kbhit function may be called continuously until a keystroke is 
available. 

The _ kbhit function is identical tokbhit. Use _ kbhit for ANSI naming conventions. 

The kbhit function returns zero when no keystroke is available; otherwise, a non-zero value is returned, 
getch, getche, putch, ungetch 
/* 

* This program loops until a key is pressed 

* or a count is exceeded. 

*/ 

♦include <stdio.h> 

♦include <conio.h> 

void main( void ) 

{ 

unsigned long i; 

printf ( "Program looping. Press any key.\n" ); 
for( i = 0; i < 10000; i++ ) { 

if( kbhit () ) { 
getch(); 
break; 


} 

} 

WATCOM 

_kbhit conforms to ANSI naming conventions 

kbhit - All, Linux, RDOS, Netware 
_ kbhit - All, RDOS, Netware 
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labs 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdlib.h> 

long int labs( long int j ); 

The labs function returns the absolute value of its long-integer argument j. 

The labs function returns the absolute value of its argument. 

abs, llabs, imaxabs, fabs 

♦include <stdio.h> 

♦include <stdlib.h> 

void main( void ) 

{ 

long x, y; 

x = -50000L; 
y = labs ( x ); 

printf ( "labs(%ld) = %ld\n", x, y ); 

} 

produces the following: 
labs(-50000) = 50000 
ISO C90 

All, Linux, RDOS, Netware 
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Idexp 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 

double Idexp( double x, int exp ) ; 

The Idexp function multiplies a floating-point number by an integral power of 2. A range error may 
occur. 

The Idexp function returns the value of x times 2 raised to the power exp. 

f rexp, modf 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

double value; 

value = Idexp( 4.7072345, 5 ); 
printf ( "%f\n", value ); 

} 

produces the following: 

150.631504 

ISOC 

Math 
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Synopsis: 


Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


ldiv 


♦include <stdlib.h> 

ldiv_ t ldiv( long int numer, long int denom ); 
typedef struct { 

long int quot; /* quotient */ 

long int rem; /* remainder */ 

} ldiv_ t; 

The ldiv function calculates the quotient and remainder of the division of the numerator numer by the 
denominator denom. 


The ldiv function returns a structure of type ldiv_ t that contains the fieldsquot and rem, which 
are both of type long int. 

div, lldiv, imaxdiv 


♦include <stdio.h> 
♦include <stdlib.h> 


void print_ time( long int ticks ) 

{ 

ldiv_ t sec_ ticks; 
ldiv_ t min_ sec; 


} 


sec_ ticks = ldiv( ticks, 100L ); 
min_ sec = ldiv ( sec_ ticks . quot, 60L ); 

printf ( "It took %ld minutes and %ld seconds\n", 
min_ sec . quot, min_ sec.rem ); 


void main( void ) 

{ 

print_ time( 86712L ); 

} 


produces the following: 

It took 14 minutes and 27 seconds 


ISO C90 


All, Linux, RDOS, Netware 
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Ifind 


Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


#include <search.h> 

void *lfind( const void *key, /* object to search for */ 
const void *base,/* base of search data */ 
unsigned *num, /* number of elements */ 

unsigned width, /* width of each element */ 

int (*compare)( const void *elementl, 

const void *element2 ) ); 

The Ifind function performs a linear search for the value key in the array of num elements pointed to 
by base. Each element of the array is width bytes in size. The argument compare is a pointer to a 
user-supplied routine that will be called by Ifind to determine the relationship of an array element with 
the key. One of the arguments to the compare function will be an array element, and the other will be 
key. 

The compare function should return 0 if elementl is identical to element2 and non-zero if the elements 
are not identical. 

The Ifind function returns a pointer to the array element in base that matches key if it is found, 
otherwise NULL is returned indicating that the key was not found. 

bsearch, lsearch 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <string.h> 

♦include <search.h> 

static const char *keywords[] = { 

"auto", 

"break", 

"case", 

"char", 

/* . */ 

/* . */ 

/* . */ 

"while" 

} ; 


void main( int argc, const char *argv[] ) 

{ 

unsigned num = 5; 

extern int compare! const void *, const void * ); 
if ( argc <= 1 ) exit ( EXIT_ FAILURE ); 

if( lfind( &argv[l], keywords, Snum, sizeof(char **), 
compare ) == NULL ) { 

printf( %s' is not a C keyword\n", argv[1] ); 

exit( EXIT_ FAILURE ); 

} else { 

printf( %s' is a C keyword\n", argv[l] ); 

exit ( EXIT_ SUCCESS ); 

} 

} 
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Ifind 


int compare( const void *opl, const void *op2 ) 

{ 

const char **pl = (const char **) opl; 
const char **p2 = (const char **) op2; 
return( strcmp( *pl, *p2 ) ); 


Classification: WATCOM 

Systems: All, Linux, RDOS, Netware 
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Igamma 


Synopsis: #include <math.h> 

double Igamma( double x ) ; 

Description: The Igamma function returns the natural logarithm of the absolute value of the Gamma function of x. 

The sign of the Gamma function after this function is called will be located in signgam. This function is 
not thread-safe if the user is interested in the sign of Gamma, and lgamma_ r should be used instead in 
multithreaded applications. 

Returns: If successful, the return value is the natural logarithm of the absolute value of the Gamma function 

computed for x. When the argument is not-a-number, the function returns NAN. For arguments of the 
values positive or negative infinity, the function returns positive or negative infinity respectively. 

See Also: lgamma_ r,tgamma 

Example: #include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", Igamma( 2.0 ) ); 

printf( "%d\n", signgam ); 

} 

produces the following: 

0.00000 

1 

Classification: ISO C99 
Systems: Math 
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igammaj 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 

double lgamma_ r( double x, int *y ); 

The lgamma_ r function returns the natural logarithm of the absolute value of the Gamma function of 
x. The sign of the Gamma function will be returned in the location pointed to by y. 

If successful, the return value is the natural logarithm of the absolute value of the Gamma function 
computed for x. When the argument is not-a-number, the function returns NAN. For arguments of the 
values positive or negative infinity, the function returns positive or negative infinity respectively. 

lgamma, tgamma 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

int i; 

printf ( "%f\n", lgamma_ r ( 2.0, &i ) ); 

printf ( "%d\n", i ); 

} 

produces the following: 

0.00000 

1 

WATCOM 

Math 
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lineto Functions 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


#include <graph.h> 

short _ FAR _ lineto( short x, short y ); 
short _ FAR _lineto_w( double x, double y ); 

The _ lineto functions draw straight lines. The_ lineto function uses the view coordinate system. 
The _ lineto_ w function uses the window coordinate system. 

The line is drawn from the current position to the point at the coordinates (x, y) . The point (x, y) 
becomes the new current position. The line is drawn with the current plotting action using the current 
line style and the current color. 

The _ lineto functions return a non-zero value when the line was successfully drawn; otherwise, zero 
is returned. 

_ moveto^ setcolor^. setlinestyle,_ setplotaction 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

_ setvideomode( _ VRES16C0L0R ); 


_ moveto( 

100, 

100 ) ; 

_ lineto( 

540, 

100 ) 

_ lineto ( 

320, 

380 ) 

_ lineto ( 

100, 

100 ) ; 

getch (); 




_ setvideomode( _ DEFAULTMODE ); 

} 

produces the following: 
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lineto Functions 



Classification: PC Graphics 

Systems: _ lineto - DOS 

_ lineto_ w - DOS 


Library Functions and Macros 563 





Ilabs 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdlib.h> 

long long int llabs( long long int j ); 

The llabs function returns the absolute value of its long long integer argument j. 

The llabs function returns the absolute value of its argument. 

labs, abs, imaxabs, fabs 

♦include <stdio.h> 

♦include <stdlib.h> 

void main( void ) 

{ 

long long x, y; 

x = -5000000000; 
y = llabs( x ); 

printf ( "llabs(%lld) = %lld\n", x, y ); 

} 

produces the following: 

llabs(-5000000000) = 5000000000 

ISO C99 

All, Linux, RDOS, Netware 
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Ildiv 


Synopsis: 


Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdlib.h> 

lldiv_ t Ildiv( long long int numer, 

long long int denom ); 

typedef struct { 

long long int quot; /* quotient */ 
long long int rem; /* remainder */ 

} lldiv_ t; 

The Ildiv function calculates the quotient and remainder of the division of the numerator numer by the 
denominator denom. 


The Ildiv function returns a structure of type lldiv_ t that contains the fieldsquot and rem, 
which are both of type long long int. 

ldiv, div, imaxdiv 


♦include <stdio.h> 
♦include <stdlib.h> 


void print_ time( long long int ticks ) 

{ 

lldiv_ t sec_ ticks; 
lldiv_ t min_ sec; 


} 


sec_ ticks = Ildiv( ticks, 100 ); 
min_ sec = Ildiv ( sec_ ticks . quot, 60 ); 

printf( "It took %lld minutes and %lld seconds\n", 
min_ sec . quot, min_ sec.rem ); 


void main( void ) 

{ 

print_ time( 73495132 ); 

} 


produces the following: 

It took 12249 minutes and 11 seconds 


ISO C99 


All, Linux, RDOS, Netware 
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localeconv 


Synopsis: #include <locale.h> 

struct lconv *localeconv( void ); 

Description: The localeconv function sets the components of an object of type struct lconv with values 

appropriate for the formatting of numeric quantities according to the current locale. The components of 
the struct lconv and their meanings are as follows: 

Component Meaning 

char * decimal_point The decimal-point character used to format non-monetary quantities. 

char thousands_sep The character used to separate groups of digits to the left of the decimal-point 
character in formatted non-monetary quantities. 

char *grouping A string whose elements indicate the size of each group of digits in formatted 
non-monetary quantities. 

char *int_curr_symbol The international currency symbol applicable to the current locale. The first 
three characters contain the alphabetic international currency symbol in 
accordance with those specified in ISO 4217 Codes for the Representation of 
Currency and Funds. The fourth character (immediately preceding the null 
character) is the character used to separate the international currency symbol from 
the monetary quantity. 

char *currency_symbol The local currency symbol applicable to the current locale. 

char *mon_decimal_point The decimal-point character used to format monetary quantities. 

char *mon_thousands_sep The character used to separate groups of digits to the left of the 
decimal-point character in formatted monetary quantities. 

char *mon_grouping A string whose elements indicate the size of each group of digits in formatted 
monetary quantities. 

char *positive_sign The string used to indicate a nonnegative-valued monetary quantity. 

char ^negative_sign The string used to indicate a negative-valued monetary quantity. 

char hit_Jrac_digits The number of fractional digits (those to the right of the decimal-point) to be 
displayed in an internationally formatted monetary quantity. 

char frac_digits The number of fractional digits (those to the right of the decimal-point) to be 
displayed in a formatted monetary quantity. 

char p_cs_precedes Set to 1 or 0 if the currency.. symbol respectively precedes or follows the 
value for a nonnegative formatted monetary quantity. 

charp_sep_by_space Set to 1 or 0 if the currency, symbol respectively is or is not separated by a 
space from the value for a nonnegative formatted monetary quantity. 

char n_cs_precedes Set to 1 or 0 if the currency, symbol respectively precedes or follows the 
value for a negative formatted monetary quantity. 
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localeconv 


Returns: 
See Also: 


char n_sep_by_space Set to 1 or 0 if the currency, symbol respectively is or is not separated by a 
space from the value for a negative formatted monetary quantity. 

charp_sign_posn The position of the positive_ sign for a nonnegative formatted monetary 

quantity. 

char njsign_posn The position of the positive_ sign for a negative formatted monetary 

quantity. 

The elements of grouping and mon_ grouping are interpreted according to the following: 

Value Meaning 

CHAR_MAX No further grouping is to be performed. 

0 The previous element is to be repeatedly used for the remainder of the digits. 

other The value is the number of digits that comprise the current group. The next 

element is examined to determine the size of the next group of digits to the left of 
the current group. 

The value of p_ sign_ posn andi_ sign_ posn is interpreted as follows: 

Value Meaning 

0 Parentheses surround the quantity and currency, symbol. 

1 The sign string precedes the quantity and currency, symbol. 

2 The sign string follows the quantity and currency, symbol. 

3 The sign string immediately precedes the quantity and currency, symbol. 

4 The sign string immediately follows the quantity and currency, symbol. 

The localeconv function returns a pointer to the filled-in object. 

setlocale 


Example: #include <stdio.h> 

#include <locale.h> 

void main() 

{ 

struct lconv *lc; 

lc = localeconv(); 
printf ( "*decimal_ point (%s)\n", 
lc->decimal_ point ); 

printf ( "*thousands_ sep (%s)\n", 
lc->thousands_ sep ); 
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localeconv 


Classification: 

Systems: 


printf ( "*int_ curr_ symbol (%s)\n", 
lc->int_ curr_ symbol ); 

printf ( "*currency_ symbol (%s)\n", 
lc->currency_ symbol ); 

printf ( "*mon_ decimal_ point (%s)\n", 
lc->mon_ decimal_ point ) ; 

printf ( "*mon_ thousands_ sep (%s)\n", 
lc->mon_ thousands_ sep ) ; 

printf ( "*mon_ grouping (%s)\n", 
lc->mon_ grouping ); 

printf ( "^grouping (%s)\n", 
lc->grouping ); 

printf ( "*positive_ sign (%s)\n", 
lc->positive_ sign ); 

printf ( "*negative_ sign (%s)\n", 
lc->negative_ sign ); 

printf ( "int_ frac_ digits (%d)\n", 
lc->int_ frac_ digits ); 

printf ( "frac_ digits (%d)\n", 
lc->frac_ digits ); 

printf ( "p_ cs_ precedes (%d)\n", 
lc->p_ cs_ precedes ) ; 

printf ( "p_ sep_ by_ space (%d)\n", 
lc->p_ sep_ by_ space ) ; 

printf ( "n_ cs_ precedes (%d)\n", 
lc->n_ cs_ precedes ) ; 

printf ( "n_ sep_ by_ space (%d)\n", 
lc->n_ sep_ by_ space ) ; 

printf ( "p_ sign_ posn (%d)\n", 
lc->p_ sign_ posn ) ; 

printf ( "n_ sign_ posn (%d)\n", 
lc->n_ sign_ posn ) ; 

} 

ISOC 

All, Linux, RDOS, Netware 
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localtime Functions 


Synopsis: 


Safer C: 

Description: 


Returns: 
See Also: 

Example: 


♦include <time.h> 

struct tm * localtime( const time_ t *timer ); 
struct tm *_ localtime( const time_ t *timer, 

struct tm *tmbuf ); 


struct 

tm { 





int 

tm_ sec; 

/* 

seconds after the minute — 

[0,61] 

*/ 

int 

tm_ min; 

/* 

minutes after the hour — 

[0,59] 

*/ 

int 

tm_ hour; 

/* 

hours after midnight — 

[0,23] 

*/ 

int 

tm_ mday; 

/* 

day of the month — 

[1,31] 

*/ 

int 

tm_ mon; 

/* 

months since January 

[0,11] 

*/ 

int 

tm_ year; 

/* 

years since 1900 


*/ 

int 

tm_ wday; 

/* 

days since Sunday — 

[0, 6] 

*/ 

int 

tm_ yday; 

/* 

days since January 1 

[0,365' 

1 */ 

int 

tm_ isdst; 

/* 

Daylight Savings Time flag * 

/ 



} ; 


The Safer C Library extension provides the localtime_ s function which is a safer alternative to 
localtime This newer localtime_ s function is recommended to be used instead of the traditional 
"unsafe" local time function. 

The localtime functions convert the calendar time pointed to by timer into a structure of type tm, of 
time information, expressed as local time. Whenever localtime is called, the tzset function is 
also called. 

The calendar time is usually obtained by using the t ime function. That time is Coordinated Universal 
Time (UTC) (formerly known as Greenwich Mean Time (GMT)). 

The _ localtime function places the converted time in thetm structure pointed to by tmbuf, and the 
localtime function places the converted time in a static structure that is re-used each time 
localtime is called. 

The time set on the computer with the DOS time command and the DOS date command reflects the 
local time. The environment variable TZ is used to establish the time zone to which this local time 
applies. See the section The TZ Environment Variable for a discussion of how to set the time zone. 

The localtime functions return a pointer to a tm structure containing the time information. 

a set ime Functions, asctime_ s,clock, ct ime Functions, ctime_ s,difftime, gmtime, 
gmtime_ s,localtime_ s,mktime, strftime, time, tzset 

♦include <stdio.h> 

♦include <time.h> 

void main() 

{ 

time_ t time_ of_ day; 
auto char buf[26]; 
auto struct tm tmbuf; 

time_ of_ day = time ( NULL ) ; 

_ localtime( &time_ of_ day, &tmbuf ) ; 

printf ( "It is now: %s", _ asetime( Stmbuf, buf ) ); 

} 
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localtime Functions 


Classification: 


Systems: 


produces the following: 

It is now: Sat Mar 21 15:58:27 1987 

ISOC 

_localtime is WATCOM 

localtime - All, Linux, RDOS, Netware 
_ localtime - All, Linux, RDOS 
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localtime s 


Synopsis: 


Constraints: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <time.h> 

struct tm * localtime_ s ( const time_ t * restrict timer, 

struct tm * restrict result); 


struct 

tm { 





int 

tm_ sec; 

/* 

seconds after the minute — 

[0,61] 

*/ 

int 

tm_ min; 

/* 

minutes after the hour — 

[0,59] 

*/ 

int 

tm_ hour; 

/* 

hours after midnight — 

[0,23] 

*/ 

int 

tm_ mday; 

/* 

day of the month — 

[1,31] 

*/ 

int 

tm_ mon; 

/* 

months since January 

[0,11] 

*/ 

int 

tm_ year; 

/* 

years since 1900 


*/ 

int 

tm_ wday; 

/* 

days since Sunday — 

[0, 6] 

*/ 

int 

tm_ yday; 

/* 

days since January 1 

[0,365' 

1 */ 

int 

tm_ isdst; 

/* 

Daylight Savings Time flag * 

/ 



} ; 


If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and localtime_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither timer nor result shall be a null pointer. If there is a runtime-constraint violation, there is no 
attempt to convert the time. 

The localtime_ s function converts the calendar time pointed to by timer into a broken-down time, 
expressed as local time. The broken-down time is stored in the structure pointed to by result. 

The localtime_ s function returns result, or a null pointer if the specified time cannot be converted 
to local time or there is a runtime-constraint violation. 

asctime Functions, asctime_ s,clock, ctime Functions, ctime_ s.difftime, gmtime, 
gmtime_ s.localtime, mktime, strftime, time, tzset 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <time.h> 

void main() 

{ 

time_ t time_ of_ day; 
auto char buf[26]; 
auto struct tm tmbuf; 

time_ of_ day = time ( NULL ) ; 
localtime_ s ( &time_ of_ day, &tmbuf ) ; 
asctime_ s ( buf, sizeof( buf ), Stmbuf ); 
printf ( "It is now: %s", buf ); 

} 

produces the following: 

It is now: Mon Jan 30 15:28:33 2006 
TR 24731 
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localtime s 


Systems: 


DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS, Netware 
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lock 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <io.h> 
int lock ( int handle, 

unsigned long offset, 
unsigned long nbytes ); 

The lock function locks nbytes amount of data in the file designated by handle starting at byte offset in 
the file. This prevents other processes from reading or writing into the locked region until an unlock 
has been done for this locked region of the file. 

Multiple regions of a file can be locked, but no overlapping regions are allowed. You cannot unlock 
multiple regions in the same call, even if the regions are contiguous. All locked regions of a file should 
be unlocked before closing a file or exiting the program. 

With DOS, locking is supported by version 3.0 or later. Note that SHARE . COM or SHARE . EXE must 
be installed. 

The lock function returns zero if successful, and -1 when an error occurs. When an error has 
occurred, errno contains a value indicating the type of error that has been detected. 

locking, open, sopen, unlock 

♦include <stdio.h> 

♦include <fcntl.h> 

♦include <io.h> 

void main() 

1 

int handle; 
char buffer[20]; 

handle = open ( "file", 0_ RDWR | 0_ TEXT ); 
if( handle != -1 ) { 

if( lock( handle, 0L, 20L ) ) { 

printf ( "Lock failed\n" ); 

} else { 

read( handle, buffer, 20 ); 

/* update the buffer here */ 
lseek ( handle, 0L, SEEK_ SET ); 
write( handle, buffer, 20 ) ; 
unlock! handle, 0L, 20L ); 

} 

close ( handle ); 

} 

} 

WATCOM 

All, RDOS, Netware 
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locking, Jocking 


Synopsis: #include <sys/locking.h> 

int locking( int handle, int mode, long nbyte ); 
int _ locking( int handle, int mode, long nbyte ); 

Description: The locking function locks or unlocks nbyte bytes of the file specified by handle. Locking a region 
of a file prevents other processes from reading or writing the locked region until the region has been 
unlocked. The locking and unlocking takes place at the current file position. The argument mode 
specifies the action to be performed. The possible values for mode are: 

Mode Meaning 

_LK_LOCK, LK_LOCK Locks the specified region. The function will retry to lock the region after 1 
second intervals until successful or until 10 attempts have been made. 

_LK_RLCK, LK_RLCK S ame action as _ LK_ LOCK. 

_LK_NBLCK, LK_NBLCK Non-blocking lock: makes only 1 attempt to lock the specified region. 
_LK_NBRLCK, LK_NBRLCK Same action as _ LK_ NBLCK. 

_LK_UNLCK, LKJUNLCK Unlocks the specified region. The region must have been previously 
locked. 

Multiple regions of a file can be locked, but no overlapping regions are allowed. You cannot unlock 
multiple regions in the same call, even if the regions are contiguous. All locked regions of a file should 
be unlocked before closing a file or exiting the program. 

With DOS, locking is supported by version 3.0 or later. Note that SHARE . COM or SHARE . EXE must 
be installed. 

The _ locking function is identical tolocking. Use _ locking for ANSI naming conventions. 

Returns: The locking function returns zero if successful. Otherwise, it returns -1 and errno is set to indicate 

the error. 

Errors: When an error has occurred, errno contains a value indicating the type of error that has been detected. 

Constant Meaning 

EACCES Indicates a locking violation (file already locked or unlocked). 

EBADF Indicates an invalid file handle. 

EDEADLOCK Indicates a locking violation. This error is returned when mode is LK_ LOCK or 
LK_ RLCK and the file cannot be locked after 10 attempts. 

EINVAL Indicates that an invalid argument was given to the function. 

See Also: creat, _ dos_ create dos_ openlock, open, sopen, unlock 


574 Library Functions and Macros 




locking, Jocking 


Example: 


Classification: 


Systems: 


♦include <stdio.h> 

♦include <sys/locking.h> 

♦include <share.h> 

♦include <fcntl.h> 

♦include <io.h> 

void main() 

{ 

int handle; 
unsigned nbytes; 
unsigned long offset; 
auto char buffer[512]; 

nbytes = 512; 
offset = 1024; 

handle = sopen ( "db.fil", 0_ RDWR, SH_ DENYNO ); 
if( handle != -1 ) { 

lseek( handle, offset, SEEK_ SET ); 
locking( handle, LK_ LOCK, nbytes ); 
read( handle, buffer, nbytes ); 

/* update data in the buffer */ 
lseek( handle, offset, SEEK_ SET ); 
write( handle, buffer, nbytes ) ; 
lseek( handle, offset, SEEK_ SET ); 
locking( handle, LK_ UNLCK, nbytes ); 
close ( handle ); 

} 

} 

WATCOM 

Jocking conforms to ANSI naming conventions 

locking - All, Linux, RDOS 
_ locking - All, Linux, RDOS 
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log 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double log( double x ) ; 

The log function computes the natural logarithm (base e) of x. A domain error occurs if the argument 
is negative. A range error occurs if the argument is zero. 

The log function returns the natural logarithm of the argument. When the argument is outside the 
permissible range, the matherr function is called. Unless the default matherr function is replaced, 
it will set the global variable errno to EDOM, and print a "DOMAIN error" diagnostic message using 
the stderr stream. 

exp, loglO, log2, pow, matherr 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", log (.5) ); 

} 

produces the following: 

-0.693147 

ISOC 

Math 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


loglO 


#include <math.h> 
double loglO ( double x ); 

The loglO function computes the logarithm (base 10) of x. A domain error occurs if the argument is 
negative. A range error occurs if the argument is zero. 

The loglO function returns the logarithm (base 10) of the argument. When the argument is outside the 
permissible range, the matherr function is called. Unless the default matherr function is replaced, 
it will set the global variable errno to EDOM, and print a "DOMAIN error" diagnostic message using 
the stderr stream. 

exp, log, log2, pow, matherr 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", loglO(.5) ); 

} 

produces the following: 

-0.301030 

ISOC 

Math 
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loglp 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double loglp( double x ); 

The loglp function computes the natural logarithm of one plus x. For small values of x this function 
provides far better accuracy than using the log function directly. 

If successful, the return value is the logarithm of one plus x. When the argument is -1.0, the function 
returns infinity. If the value of x is less than -1.0, the function returns NAN. 

log 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", loglp( 0.02 ) ); 

} 

produces the following: 

0.019803 
ISO C99 
Math 
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log2 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double log2 ( double x ); 

The log2 function computes the logarithm (base 2) of x. A domain error occurs if the argument is 
negative. A range error occurs if the argument is zero. 

The log2 function returns the logarithm (base 2) of the argument. When the argument is outside the 
permissible range, the matherr function is called. Unless the default matherr function is replaced, 
it will set the global variable errno to EDOM, and print a "DOMAIN error" diagnostic message using 
the stderr stream. 

exp, log, loglO, pow, matherr 

((include <stdio.h> 

((include <math.h> 

void main() 

{ 

printf ( "%f\n", log2(.25) ); 

} 

produces the following: 

- 2.000000 

WATCOM 

Math 
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logb 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double logb ( double x ); 

The logb function returns the exponent portion of the argument x as a double. 

If successful, the return value is the exponent of x. When the argument is zero, the function returns 
infinity. 

ilogb 

#include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", logb( 1024.0 ) ); 

} 

produces the following: 

10.0000 
ISO C99 
Math 
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longjmp 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <setjmp.h> 

void longjmp ( jmp_ buf env, int return_ value ); 

The longjmp function restores the environment saved by the most recent call to the set jmp function 
with the corresponding jmp_ buf argument. 

It is generally a bad idea to use longjmp to jump out of an interrupt function or a signal handler 
(unless the signal was generated by the raise function). 

After the longjmp function restores the environment, program execution continues as if the 
corresponding call to set jmp had just returned the value specified by return_value. If the value of 
return_value is 0, the value returned is 1. 

set jmp 

♦include <stdio.h> 

♦include <setjmp.h> 

jmp_ buf env; 

rtn () 

{ 

printf ( "about to longjmp\n" ); 
longjmp( env, 14 ); 

} 

void main() 

{ 

int ret_ val = 2 93; 

if( 0 == ( ret_ val = setjmp( env ) ) ) { 

printf( "after setjmp %d\n", ret_ val ); 
rtn (); 

printf( "back from rtn %d\n", ret_ val ); 

} else { 

printf( "back from longjmp %d\n", ret_ val ); 

} 

} 

produces the following: 

after setjmp 0 
about to longjmp 
back from longjmp 14 

ISOC 

All, Linux, RDOS, Netware 
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Irotl 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <stdlib.h> 

unsigned long _ Irotl( unsigned long value, 

unsigned int shift ) ; 

The _ Irotl function rotates the unsigned long integer, determined by value, to the left by the number 
of bits specified in shift. 

The rotated value is returned. 

_ lrotr,_ rotlv. rotr 

♦include <stdio.h> 

♦include <stdlib.h> 

unsigned long mask = 0x12345678; 

void main() 

{ 

mask = _ Irotl ( mask, 4 ); 
printf ( "%081X\n", mask ); 

} 

produces the following: 

23456781 

WATCOM 

All, Linux, RDOS, Netware 
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Irotr 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <stdlib.h> 

unsigned long _ Irotr( unsigned long value, 

unsigned int shift ) ; 

The _ Irotr function rotates the unsigned long integer, determined by value, to the right by the 
number of bits specified in shift. 

The rotated value is returned. 

_ lrotl,_ rotlv. rotr 

♦include <stdio.h> 

♦include <stdlib.h> 

unsigned long mask = 0x12345678; 

void main() 

{ 

mask = _ Irotr ( mask, 4 ); 
printf ( "%081X\n", mask ); 

} 

produces the following: 

81234567 

WATCOM 

All, Linux, RDOS, Netware 
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Isearch 


Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


#include <search.h> 
void *lsearch( const void *key, 
void *base, 
unsigned *num, 
unsigned width, 
int (*compare)( 


/* object to search for */ 
/* base of search data */ 
/* number of elements */ 
/* width of each element*/ 
const void *elementl, 
const void *element2 ) ); 


The Isearch function performs a linear search for the value key in the array of num elements pointed 
to by base. Each element of the array is width bytes in size. The argument compare is a pointer to a 
user-supplied routine that will be called by Isearch to determine the relationship of an array element 
with the key. One of the arguments to the compare function will be an array element, and the other will 
be key. 

The compare function should return 0 if elementl is identical to element2 and non-zero if the elements 
are not identical. 


If the key value is not found in the array, then it is added to the end of the array and the number of 
elements is incremented. The Isearch function returns a pointer to the array element in base that 
matches key if it is found, or the newly added key if it was not found. 

bsearch, lfind 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <string.h> 

♦include <search.h> 

void main( int argc, const char *argv[] ) 

{ 

int i; 

unsigned num = 0; 

char **array = (char **)calloc( argc, sizeof(char **) ); 

extern int compare( const void *, const void * ); 

for ( i = 1; i < argc; ++i ) { 

Isearch( &argv[i], array, Snum, sizeof(char **), 


for( i = 0; i < num; ++i ) { 

printf( "%s\n", array [i] ); 

} 

} 

int compare( const void *opl, const void *op2 ) 

const, char **pl = (const char **) opl; 
const char **p2 = (const char **) op2; 
return ( strcmp( *pl, *p2 ) ); 

} 

/* With input: one two one three four */ 
produces the following: 
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Isearch 


one 

two 

three 

four 

Classification: WATCOM 

Systems: All, Linux, RDOS, Netware 
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Iseek, Jseek, _lseeki64 


Synopsis: #include <stdio.h> 

♦include <io.h> 

off_ t Iseek( int handle, off_t offset, int origin ); 
off_ t _ Iseek ( int handle, off_ t offset, int origin ); 

_int64 _ lseeki64 ( int handle,_int64 offset, int origin ); 

Description: The Iseek function sets the current file position at the operating system level. The file is referenced 
using the file handle handle returned by a successful execution of one of the creat, dup, dup2, 
open or sopen functions. The value of offset is used as a relative offset from a file position 
determined by the value of the argument origin. 

The new file position is determined in a manner dependent upon the value of origin which may have 
one of three possible values (defined in the <stdio. h> header file): 

Origin Definition 

SEEK_SET The new file position is computed relative to the start of the file. The value of 

offset must not be negative. 

SEEK_CUR The new file position is computed relative to the current file position. The value 

of offset may be positive, negative or zero. 

SEEK_END The new file position is computed relative to the end of the file. 

An error will occur if the requested file position is before the start of the file. 

The requested file position may be beyond the end of the file. On POSIX-conforming systems, if data 
is later written at this point, subsequent reads of data in the gap will return bytes whose value is equal to 
zero until data is actually written in the gap. On systems such DOS and OS/2 that are not 
POSIX-conforming, data that are read in the gap have arbitrary values. 

Some versions of MS-DOS allow seeking to a negative offset, but it is not recommended since it is not 
supported by other platforms and may not be supported in future versions of MS-DOS. 

The Iseek function does not, in itself, extend the size of a file (see the description of the chsize 
function). 

The _ Iseek function is identical tolseek. Use _ Iseek for ANSI naming conventions. 

The _lseeki64 function is identical to Iseek except that it accepts a 64-bit value for the offset 
argument. 

The Iseek function can be used to obtain the current file position (the tell function is implemented 
in terms of _strnextc). This value can then be used with the Iseek function to reset the file position to 
that point in the file: 
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Returns: 


Errors: 


See Also: 


Example: 


Iseek, Jseek, _lseeki64 


off_ t file_posn; 
int handle; 

/* get current file position */ 

file_ posn = iseek ( handle, OL, SEEK_ CUR ); 

/* or */ 

file_ posn = tell ( handle ); 

/* return to previous file position */ 

file_ posn = Iseek ( handle, file_ posn, SEEK_ SET ) ; 

If all records in the file are the same size, the position of the n’th record can be calculated and read, as 
illustrated in the example included below. The function in this example assumes records are numbered 
starting with zero and that rec_size contains the size of a record in the file (including the 
record-separator character), (including the carriage-return character in text files). 

If successful, the current file position is returned in a system-dependent manner. A value of 0 indicates 
the start of the file. 

If an error occurs in Iseek (-1L) is returned. 

If an error occurs in _lseeki64, (-1164) is returned. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EBADF The handle argument is not a valid file handle. 

EINVAL The origin argument is not a proper value, or the resulting file offset would be 

invalid. 

chsize, close, creat, dup, dup2, eof, exec. . ., fdopen, filelength, fileno, fstat, 
_ grow_ handlesisatty, open, read, setmode, sopen, stat, tell, write, umask 

♦include <stdio.h> 

♦include <fcntl.h> 

♦include <io.h> 

int read_ record ( int handle, 

long rec_ numb, 
int rec_ size, 
char *buffer ) 

{ 

if ( Iseek ( handle, rec_ numb * rec_ size, SEEK_ SET ) 

== -1L ) { 

return ( -1 ); 

} 

return ( read( handle, buffer, rec_ size ) ); 

} 
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Iseek, Jseek, _lseeki64 


void main( void ) 

{ 

int handle; 
int size_ read; 
char buffer[80]; 

/* open a file for input */ 

handle = open ( "file", 0_ RDONLY | 0_ TEXT ); 
if( handle != -1 ) { 

/* read a piece of the text */ 
size_ read = 

read_ record( handle, 1, 80, buffer ); 

/* test for error */ 
if( size_ read == -1 ) { 

printf ( "Error reading file\n" ); 

} else { 

printf( "%.80s\n", buffer ); 

} 


/* close the file */ 
close ( handle ); 

} 

} 

Classification: POSIX 1003.1 

Jseek conforms to ANSI naming conventions 
_lseeki64 is WATCOM 

Systems: Iseek - All, Linux, RDOS, Netware 

_ Iseek - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
_ lseeki64 - All, Linux 


RDOS 
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Synopsis: 


Description: 


Returns: 
See Also: 

Example: 


lltoa, Jltoa, Jltow 


#include <stdlib.h> 
char *lltoa ( long long int value, 
char ^buffer, 
int radix ); 

char *_ lltoa( long long int value, 
char *buffer, 
int radix ); 

wchar_ t *_lltow( long long int value, 
wchar_ t *buffer, 
int radix ); 

The lltoa function converts the binary integer value into the equivalent string in base radix notation 
storing the result in the character array pointed to by buffer. A null character is appended to the result. 
The size of buffer must be at least 65 bytes when converting values in base 2. The value of radix must 
satisfy the condition: 

2 <= radix <= 36 


If radix is 10 and value is negative, then a minus sign is prepended to the result. 

The _ lltoa function is identical tolltoa. Use _ lltoa for ANSI naming conventions. 

The _ lltow function is a wide-character version oflltoa. It produces a wide-character string. 
The lltoa function returns a pointer to the result. 

atoi, atol, atoll, itoa, ltoa, sscanf, strtol, strtoll, strtoul, strtoull, 
strtoimax, strtoumax, ultoa, ulltoa, utoa 


♦include <stdio.h> 
♦include <stdlib.h> 


void print_ value( long value ) 

{ 

int base; 

char buffer[65]; 


} 


for( base = 2; base <= 16; base = base + 2 ) 
printf ( "%2d %s\n", base, 

lltoa( value, buffer, base ) ); 


void main() 

{ 


print_ value( 1234098765LL ); 

} 


produces the following: 
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Iltoa, Jltoa, Jltow 


2 1001001100011101101101001001101 
4 1021203231221031 
6 322243004113 
8 11143555115 
10 1234098765 
12 2a5369639 
14 b9c8863b 
16 498eda4d 

Classification: WATCOM 

Jltoa conforms to ANSI naming conventions 

Systems: Iltoa - All, Linux, RDOS, Netware 

_ Iltoa - All, Linux, RDOS, Netware 
_ lltow - All, Linux, RDOS 
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Synopsis: 


Description: 


Returns: 
See Also: 

Example: 


Itoa, Jtoa, Jtow 


#include <stdlib.h> 
char *ltoa ( long int value, 
char *buffer, 
int radix ); 

char *_ ltoa( long int value, 
char ^buffer, 
int radix ); 

wchar_ t *_ ltow( long int value, 
wchar_ t ^buffer, 
int radix ); 

The ltoa function converts the binary integer value into the equivalent string in base radix notation 
storing the result in the character array pointed to by buffer. A null character is appended to the result. 
The size of buffer must be at least 33 bytes when converting values in base 2. The value of radix must 
satisfy the condition: 

2 <= radix <= 36 


If radix is 10 and value is negative, then a minus sign is prepended to the result. 

The _ ltoa function is identical toltoa. Use _ ltoa for ANSI naming conventions. 

The _ ltow function is a wide-character version ofltoa. It produces a wide-character string. 
The ltoa function returns a pointer to the result. 

atoi, atol, atoll, itoa, lltoa, sscanf, strtol, strtoll, strtoul, strtoull, 
strtoimax, strtoumax, ultoa, ulltoa, utoa 

♦include <stdio.h> 

♦include <stdlib.h> 

void print_ value( long value ) 

{ 


int base; 

char buffer[33]; 


} 


for( base = 2; base <= 16; base = base + 2 ) 
printf ( "%2d %s\n", base, 

ltoa( value, buffer, base ) ); 


void main() 

{ 


print_ value( 12765L ); 

} 


produces the following: 
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Itoa, Jtoa, Jtow 


2 11000111011101 
4 3013131 
6 135033 
8 30735 
10 12765 
12 7479 
14 491b 
16 31dd 

Classification: WATCOM 

Jtoa conforms to ANSI naming conventions 

Systems: ltoa - All, Linux, RDOS, Netware 

_ ltoa - All, Linux, RDOS, Netware 
_ ltow - All, Linux, RDOS 
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main, wmain, WinMain, wWinMain 


Synopsis: int main ( void ) ; 

int main( int argc, char *argv[] ); 
int wmain( void ) ; 

int wmain ( int argc, wchar_ t *argv [ ] ); 

int PASCAL WinMain( HINSTANCE hlnstance, 

HINSTANCE hPrevInstance, 

LPSTR IpszCmdLine, 
int nCmdShow ); 

int PASCAL wWinMain( HINSTANCE hlnstance, 

HINSTANCE hPrevInstance, 
wcharT *lpszCmdLine, 
int nCmdShow ); 

Description: main is a user-supplied function where program execution begins. The command line to the program 
is broken into a sequence of tokens separated by blanks and are passed to main as an array of pointers 
to character strings in the parameter argv. The number of arguments found is passed in the parameter 
argc. The first element of argv will be a pointer to a character string containing the program name. 

The last element of the array pointed to by argv will be a NULL pointer (i.e. argvfargc] will be NULL). 
Arguments that contain blanks can be passed to main by enclosing them within double quote characters 
(which are removed from that element in the argv vector. A literal double quote character can be 
passed by preceding it with a backslash. A literal backslash followed by an enclosing double quote 
character can be passed as a pair of backslash characters and a double quote character. 

Example: echo "he\"l\lo worldW" 

passes the single argument he "No world\ 

The command line arguments can also be obtained in its original format by using the getcmd function. 

Alternatively, the main function can be declared to return void (i.e., no return value). In this case, you 
will not be able to return an exit code from main using a return statement but must use the exit 
function to do so. 

The wmain function is a user-defined wide-character version of main that operates with wide-character 
strings. If this function is present in the application, then it will be called by the run-time system startup 
code (and the main function, if present, will not be called). 

As with main the wmain function can be declared to return void and the same considerations will apply. 

The WinMain function is called by the system as the initial entry point for a Windows-based application. 
The wWinMain function is a wide-character version of WinMain. 

Parameters Meaning 

hlnstance Identifies the current instance of the application. 

hPrevInstance Identifies the previous instance of the application. For an application written for Win32, 
this parameter is always NULL. 

IpszCmdLine Points to a null-terminated string specifying the command line for the application. 

nCmdShow Specifies how the window is to be shown. This parameter can be one of the following 

values: 
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main, wmain, WinMain, wWinMain 


Returns: 


See Also: 


Example: 


Value Meaning 

SW_HIDE Hides the window and activates another window. 

SW_MINIMIZE Minimizes the specified window and activates the top-level window 
in the system’s list. 


S W_RESTORE 


Activates and displays a window. If the window is minimized or 
maximized, Windows restores it to its original size and position 
(same as SW_ SHOWNORMAL). 


SW_SHOW Activates a window and displays it in its current size and position. 

SW_SHOWMAXIMIZED Activates a window and displays it as a maximized window. 

SW_SHOWMINIMIZED Activates a window and displays it as an icon. 

SW_SHOWMINNOACTIVE Displays a window as an icon. The active window remains 
active. 


SW_SHOWNA Displays a window in its current state. The active window remains 
active. 

SW_SHOWNOACTIVATE Displays a window in its most recent size and position. The 
active window remains active. 

SW_SHOWNORMAL Activates and displays a window. If the window is minimized or 
maximized, Windows restores it to its original size and position 
(same as SW_ RESTORE). 

The WinMain function initializes an application, and then performs a message retrieval-and-dispatch loop 
that is the top-level control structure for the remainder of the application’s execution. The loop terminates 
when a WM_ QUIT message is received. At that point,WinMain exits the application, returning the value 
passed in the WM_ QUIT message’swParam parameter. If WM_ QUIT was received as a result of calling 
PostQuitMessage, the value of wParam is the value of the PostQuitMessage function’s 
nExitCode parameter. 

The main and wmain functions return an exit code to the calling program (usually the operating 
system). 

If the WinMain function terminates before entering the message loop, it should return 0. Otherwise, it 
should terminate when it receives a WM_ QUIT message and return the exit value contained in that 
message’s wParam parameter. 

abort, atexit, _ bgetcmd.exec. . ., exit, _ Exit,_ exit,getcmd, getenv, onexit, 
putenv, spawn. . system 
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main, wmain, WinMain, wWinMain 


♦include <stdio.h> 

int main( int argc, char *argv[] ) 

{ 

int i; 

for( i = 0; i < argc; ++i ) { 

printf( "argv[%d] = %s\n", i, argv[i] ); 

} 

return( 0 ) ; 

} 

#ifdef _ WIDE_ 

int wmain ( int wargc, wchar_ t *wargv[] ) 

{ 

int i; 

for( i = 0; i < wargc; ++i ) { 

wprintf ( L"wargv[%d] = %s\n", i, wargv[i] ); 

} 

return( 0 ) ; 

} 

#endif 


produces the following: 

argv[0] = C:\WATCOM\DEMO\MYPGM.EXE 

argv[l] = hhhhh 

argv[2] = another arg 

when the program mypgm is executed with the command 
mypgm hhhhh "another arg" 


A sample Windows main program is shown below. 


int 

{ 


PASCAL WinMain ( HANDLE this_inst, HANDLE prev_inst, 
LPSTR cmdline, int cmdshow ) 

MSG msg; 


if( !prev_inst ) { 

if( !Firstlnstance ( this_ inst ) ) return! 0 ); 

} 

if( !Anylnstance ( this_ inst, cmdshow ) ) return! 0 ); 

/* 

GetMessage returns FALSE when WM_ QUIT is received 

*/ 

while! GetMessage! &msg, NULL, NULL, NULL ) ) { 

TranslateMessage( &msg ) ; 

DispatchMessage( &msg ) ; 

} 

return! msg.wParam ); 


Classification: ISO C 

wmain is WATCOM 
WinMain is WATCOM 
wWinMain is WATCOM 
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main, wmain, WinMain, wWinMain 


Systems: 


main - All, Netware 
wmain - Win32, OS/2-32 
WinMain - Windows, Win386, Win32 
wWinMain - Win32 
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makepath, _wmakepath 


Synopsis: #include <stdlib.h> 

void _ makepath( char *path, 

const char *drive, 
const char *dir, 
const char *fnarae, 
const char *ext ); 
void _ wmakepath( wchar_t *path, 

const wchar_ t *drive, 
const wchar_ t *dir, 
const wchar_ t *fname, 
const wchar_ t *ext ); 

Description: The _ makepath function constructs a full pathname front the components consisting of a drive letter, 
directory path, file name and file name extension. The full pathname is placed in the buffer pointed to 
by the argument path. 

The _ wmakepath function is a wide-character version of_ makepath that operates with 
wide-character strings. 

The maximum size required for each buffer is specified by the manifest constants _ MAX_ PATH, 

_ MAX_ DRIVE.*. MAX_ DIR*. MAX_ FNAME, and. MAX_ EXT which are defined irrstdlib . h> . 

drive The drive argument points to a buffer containing the drive letter (A, B, C, etc.) followed 

by an optional colon. The _ makepath function will automatically insert a colon in the 
full pathname if it is missing. If drive is a NULL pointer or points to an empty string, no 
drive letter or colon will be placed in the full pathname. 

dir The dir argument points to a buffer containing just the pathname. Either forward slashes 

(/) or backslashes (\) may be used. The trailing slash is optional. The _ makepath 
function will automatically insert a trailing slash in the full pathname if it is missing. If 
dir is a NULL pointer or points to an empty string, no slash will be placed in the full 
pathname. 

fname Th e frame argument points to a buffer containing the base name of the file without any 

extension (suffix). 

ext The ext argument points to a buffer containing the filename extension or suffix. A 

leading period (.) is optional. The _ makepath routine will automatically insert a period 
in the full pathname if it is missing. If ext is a NULL pointer or points to an empty string, 
no period will be placed in the full pathname. 

Returns: The _ makepath function returns no value. 

See Also: _ fullpath*_ splitpath 

Example: 
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makepath, _wmakepath 


♦include <stdio.h> 

♦include <stdlib.h> 

void main() 

{ 

char full_ path [ _ MAX_ PATH ] ; 
char drive [ _ MAX_ DRIVE ] ; 
char dir[ _MAX_DIR ]; 
char f name [ _ MAX_ FNAME ] ; 
char ext [ _ MAX_ EXT ] ; 

_ makepath(full_ path, "c" , "watcomc\\h\\","stdio","h"); 

printf ( "Full path is: %s\n\n", full_ path ); 

_splitpath( full_ path, drive, dir, fname, ext ); 

printf ( "Components after _ splitpath\n" ); 

printf ( "drive: %s\n", drive ); 

printf ( "dir: %s\n", dir ); 

printf ( "fname: %s\n", fname ); 

printf ( "ext: %s\n", ext ); 

} 

produces the following: 

Full path is: c:watcomc\h\stdio.h 

Components after _ splitpath 

drive: c: 

dir: watcomc\h\ 

fname: stdio 

ext: .h 


Note the use of two adjacent backslash characters (\) within character-string constants to signify a single 
backslash. 

Classification: WATCOM 

Systems: _ makepath - All, Linux, RDOS, Netware 

_ wmakepath - All, Linux 
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malloc Functions 


Synopsis: #include <stdlib.h> For ISO C compatibility (malloc only) 

♦include <malloc.h> Required for other function prototypes 
void *malloc( size_ t size ) ; 

void_based (void) *_bmalloc(_segment seg, size_ t size ); 

void_far *_ fmalloc ( size_ t size ) ; 

void_near *_ nmalloc ( size_ t size ); 

Description: The malloc functions allocate space for an object of size bytes. Nothing is allocated when the size 
argument has a value of zero. 

Each function allocates memory from a particular heap, as listed below: 

Function Heap 

malloc Depends on data model of the program 

_bmalloc Based heap specified by seg value 
Jmalloc Far heap (outside the default data segment) 
jimalloc Near heap (inside the default data segment) 

In a small data memory model, the malloc function is equivalent to the _ nmalloc function; in a 
large data memory model, the malloc function is equivalent to the _ fmalloc function. 

Returns: The malloc functions return a pointer to the start of the allocated memory. The malloc, _ fmalloc 

and _ nmalloc functions returnNULL if there is insufficient memory available or if the requested size 
is zero. The _ bmalloc function returns_ NULLOFF if there is insufficient memory available or if the 
requested size is zero. 

See Also: calloc Functions, _ expand Functions,free Functions, halloc, hfree, _ msize Functions, 

realloc Functions, sbrk 

Example: ((include <stdlib.h> 

void main() 

{ 

char *buffer; 

buffer = (char *)malloc( 80 ); 
if ( buffer != NULL ) { 

/* body of program */ 

free( buffer ) ; 

} 

} 

Classification: ISO C 

_bmalloc is WATCOM 
Jmalloc is WATCOM 
_nmalloc is WATCOM 

Systems: malloc - All, Linux, RDOS, Netware 
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malloc Functions 


_bmalloc - DOS/16, Windows, OS/2 l.x(all) 

_ fmalloc - DOS/16, Windows, OS/2 l.x(all) 

_ nmalloc - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 l.x(MT), 
OS/2-32, Linux, RDOS 
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matherr 


Synopsis: #include <math.h> 

int matherr ( struct _ exception *err_ info ); 

Description: The matherr function is invoked each time an error is detected by functions in the math library. The 
default matherr function supplied in the library returns zero which causes an error message to be 
displayed upon stderr and errno to be set with an appropriate error value. An alternative version 
of this function can be provided, instead of the library version, in order that the error handling for 
mathematical errors can be handled by an application. 

A program may contain a user-written version of matherr to take any appropriate action when an 
error is detected. When zero is returned, an error message will be printed upon stderr and errno 
will be set as was the case with the default function. When a non-zero value is returned, no message is 
printed and errno is not changed. The value err_ inf o->retval is used as the return value for 
the function in which the error was detected. 

The matherr function is passed a pointer to a structure of type struct _ exception which 
contains information about the error that has been detected: 

struct _ exception 

{ int type; /* TYPE OF ERROR */ 

char ‘name; /* NAME OF FUNCTION */ 

double argl; /* FIRST ARGUMENT TO FUNCTION */ 

double arg2; /* SECOND ARGUMENT TO FUNCTION */ 

double retval; /* DEFAULT RETURN VALUE */ 

} ; 

The type field will contain one of the following values: 

Value Meaning 

DOMAIN A domain error has occurred, such as sqrt (-leO) . 

SING A singularity will result, such as pow (OeO, -2) . 

OVERFLOW An overflow will result, such as pow (1 OeO, 100) . 

UNDERFLOW An underflow will result, such aspow(10e0,-100) . 

TLOSS Total loss of significance will result, such as exp (1000) . 

PLOSS Partial loss of significance will result, such as sin(10e70) . 

The name field points to a string containing the name of the function which detected the error. The 
fields argl and arg2 (if required) give the values which caused the error. The field retval contains 
the value which will be returned by the function. This value may be changed by a user-supplied version 
of the matherr function. 

Returns: The matherr function returns zero when an error message is to be printed and a non-zero value 

otherwise. 
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matherr 


Example: 


Classification: 

Systems: 


#include <stdio.h> 

♦include <stdlib.h> 

♦include <string.h> 

♦include <math.h> 

/* Demonstrate error routine in which negative */ 
/* arguments to "sqrt" are treated as positive */ 

void main() 

{ 

printf ( "%e\n", sqrt( -5e0 ) ); 

exit ( 0 ) ; 

} 

int matherr ( struct _ exception *err ) 

{ 

if( strcmp( err->name, "sqrt" ) == 0 ) { 

if( err->type == DOMAIN ) { 

err->retval = sqrt( -(err->argl) ); 
return ( 1 ); 

} else 

return ( 0 ); 

} else 

return( 0 ) ; 

} 

WATCOM 

Math 
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max 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


♦include <stdlib.h> 

♦define max(a,b) (((a) > (b)) ? (a) : (b)) 

The max macro will evaluate to be the greater of two values. It is implemented as follows. 

♦define max(a,b) (((a) > (b)) ? (a) : (b)) 

The max macro will evaluate to the larger of the two values passed, 
min 

♦include <stdio.h> 

♦include <stdlib.h> 

void main() 

{ 

int a; 


/* 

* The following line will set the variable "a" to 10 

* since 10 is greater than 1. 

*/ 

a = max( 1, 10 ) ; 

printf ( "The value is: %d\n", a ); 


Classification: WATCOM 

Systems: All, Linux, RDOS, Netware 
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mbbtombc 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <mbstring.h> 

unsigned int _ mbbtombc ( unsigned int ch ); 

The _ mbbtombc function returns the double-byte character equivalent to the single-byte character ch. 
The single-byte character must be in the range 0x20 through 0x7E or OxAl through OxDF. 

Note: This function was called hantozen in earlier versions. 

The _ mbbtombc function returns ch if there is no equivalent double-byte character; otherwise 
_ mbbtombc returns a double-byte character. 

_ getmbcp,_ mbc jisto jms,_ mbc jmsto jis^_ mbctombb,_ ismbbalnum,_ ismbbalpha, 
_ ismbbgraph^ ismbbkalnum,_ ismbbkalpha,_ ismbbkana^ ismbbkprint, 

_ ismbbkpunct,_ ismbblead,_ ismbbprint,_ ismbbpunct,_ ismbbtrail, 

_ mbc jisto jms,_ mbc jmsto jis,_ mbctombb,_ mbbtype,_ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

char alphabet[] = { 

"ABCDEFGHIJKLMNOPQRSTUVWXYZ" 

} ; 


void main() 

{ 

int i; 

unsigned short c; 

_ setmbcp( 932 ); 

for ( i = 0; i < sizeof( alphabet ) - 1; i++ ) { 

c = _ mbbtombc( alphabet[ i ] ) ; 

printf( "%c%c", c>>8, c ); 

} 

printf( "\n" ) ; 


produces the following: 

ABCDEFGHIJKLMNOPQRSTUVWXYZ 

WATCOM 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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mbbtype 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

♦include <mbctype.h> (for manifest constants) 
int _ mbbtype( unsigned char ch, int type ) ; 

The _ mbbtype function determines the type of a byte in a multibyte character. If the value of type is 
any value except 1, _ mbbtype tests for a valid single-byte or lead byte of a multibyte character. If the 
value of type is 1, _ mbbtype tests for a valid trail byte of a multibyte character. 

Note: A similar function was called chkctype in earlier versions. 

If the value of type is not 1, the _ mbbtype function returns one of the following values: 

_MBC_SINGLE the character is a valid single-byte character (e.g., 0x20 - 0x7E, OxAl - OxDF 

in code page 932) 

_MBC_LEAD the character is valid lead byte character (e.g., 0x81 - 0x9F, OxEO - OxFC in 

code page 932) 

_MBC_ILLEGAL the character is an illegal character (e.g., any value except 0x20 - 0x7E, OxAl 

- OxDF, 0x81 - 0x9F, OxEO - OxFC in code page 932) 

If the value of type is 1, the _ mbbtype function returns one of the following values: 

_MBC_TRAIL the character is a valid trailing byte character (e.g., 0x40 - 0x7E, 0x80 - OxFC 

in code page 932) 

_MBC_ILLEGAL the character is an illegal character (e.g., any character except a valid trailing 

byte character) 

_ getmbcp,_ ismbcalnum,_ ismbcalpha^ ismbccntrl,_ ismbcdigit,_ ismbcgraph, 

_ ismbchira^ ismbckata,_ ismbcl0,_ ismbcll,_ ismbcl2,_ ismbclegal, 

_ ismbclower^ ismbcprint,_ ismbcpunct,_ ismbcspace,_ ismbcsymbol, 

_ ismbcupper^ ismbcxdigit,_ setmbcp 
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mbbtype 


♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

const char *types[4] = { 

"ILLEGAL", 

"SINGLE", 

"LEAD", 

"TRAIL" 

} ; 

const unsigned char chars[] = { 

r r 

r 

r f 
• r 

' i' r 
'A' , 

0x81,0x40, /* double-byte space */ 

0x82,0x60, /* double-byte A */ 

0x82,0xA6, /* double-byte Hiragana */ 

0x83,0x42, /* double-byte Katakana */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6, /* single-byte Katakana alphabetic */ 

OxDF, /* single-byte Katakana alphabetic */ 

0xE0,0xAl, /* double-byte Kanji */ 

0x00 

} ; 

♦ define SIZE sizeof ( chars ) / sizeof ( unsigned char ) 

void main() 

{ 

int i, j, k; 

_ setmbcp( 932 ); 

k = 0; 

for( i = 0; i < SIZE; i++ ) { 

j = _ mbbtype( chars[i], k ); 
printf( "%s\n", types [ 1 + j ] ); 

if ( j == _ MBC_ LEAD ) 
k = 1; 
else 
k = 0; 

} 

} 

produces the following: 
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mbbtype 


SINGLE 

SINGLE 

SINGLE 

SINGLE 

LEAD 

TRAIL 

LEAD 

TRAIL 

LEAD 

TRAIL 

LEAD 

TRAIL 

SINGLE 

SINGLE 

SINGLE 

LEAD 

TRAIL 

ILLEGAL 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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mbccmp, 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


fmbccmp 


♦include <mbstring.h> 

int _ mbccmp( const unsigned char *sl, 
const unsigned char *s2 ) ; 

int _ fmbccmp ( const unsigned char_far *sl, 

const unsigned char _ far *s2 ); 

The _ mbccmp function compares one multibyte character from si to one multibyte character from s2. 

The _ fmbccmp function is a data model independent form of the _mbccmp function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The _ mbccmp and_ fmbccmp functions return the following values. 

Value Meaning 

< 0 multibyte character at si less than multibyte character at s2 

0 multibyte character at si identical to multibyte character at s2 

> 0 multibyte character at si greater than multibyte character at s2 

_ mbccpy,_ mbcicmp^ mbc jisto jms^_ mbc jmsto jis,_ mbclen,_ mbctohira, 

_ mbctokata^ mbctolower^ mbctombb^_ mbctoupperjnblen, mbrlen, mbrtowc, 
mbsrtowcs, mbsrtowcs_ sjnbstowcs, mbstowcs_ s,mbtowc, btowc, wcrtomb, 
wcrtomb_ s.wcsrtombs, wcsrtombs_ s,wcstombs, wcstombs_ s,wctob, wctomb, 
wctomb_ s 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned char mbl[2] = { 

0x81, 0x43 

} ; 


unsigned char mb2[2] = { 
0x81, 0x42 

} ; 


void main() 

{ 

int i; 

_ setmbcp( 932 ) ; 
i = _ mbccmp( mbl, mb2 ) ; 
if( i < 0 ) 

printf ( "Less than\n" ); 
else if( i == 0 ) 

printf ( "Equal to\n" ); 

else 

printf ( "Greater than\n" ); 

} 

produces the following: 
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Classification: 


Systems: 


mbccmp, _fmbccmp 


Greater than 

ISOC 

_fmbccmp is WATCOM 


mbccmp - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
fmbccmp - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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mbccpy, Jmbccpy 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


#include <mbstring.h> 

void _ mbccpy( unsigned char *dest, 

const unsigned char *ch ); 

void _ fmbccpy ( unsigned char_far *dest, 

const unsigned char _ far *ch ); 

The _ mbccpy function copies one multibyte character from ch to dest. 

The _ fmbccpy function is a data model independent form of the _mbccpy function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The _ mbccpy function does not return a value. 

_ mbccmp,_ mbcicmp,_ mbc jisto jms^_ mbc jmsto jis,_ mbclen,_ mbctohira, 

_ mbctokata,_ mbctolower^ mbctombb,_ mbctoupperjnblen, mbrlen, mbrtowc, 
mbsrtowcs, mbsrtowcs_ sjnbstowcs, mbstowcs_ s,mbtowc, btowc, wcrtomb, 
wcrtomb_ s,wcsrtombs, wcsrtombs_ s.wcstombs, wcstombs_ s,wctob, wctomb, 
wctomb_ s 

#include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned char mbl[2] = { 

0x00, 0x00 

1 ; 


unsigned char mb2[4] = { 

0x81, 0x42, 0x81, 0x41 

1 ; 


void main() 

{ 

_ setmbcp( 932 ); 

printf ( "%^6.4x\n", mbl[0] << 8 | mbl[l] ); 

_ mbccpy( mbl, mb2 ); 

printf( "%^6.4x\n", mbl[0] << 8 | mbl[l] ); 

1 

produces the following: 

0000 

0x8142 

WATCOM 

_ mbccpy - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, Linux, 
RDOS 

_ fmbccpy - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


mbcicmp, Jmbcicmp 


♦include <mbstring.h> 

int _ mbcicmp( const unsigned char *sl, 

const unsigned char *s2 ) ; 

int _ fmbcicmp ( const unsigned char_far *sl, 

const unsigned char_far *s2 ) ; 

The _ mbcicmp function compares one multibyte character from si to one multibyte character from s2 
using a case-insensitive comparison. 

The _ fmbcicmp function is a data model independent form of the _mbcicmp function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The _ mbcicmp and_ fmbcicmp functions return the following values. 

Value Meaning 

< 0 multibyte character at si less than multibyte character at s2 

0 multibyte character at si identical to multibyte character at s2 

> 0 multibyte character at si greater than multibyte character at s2 

_ mbccmp,_ mbccpy,_ mbc jisto jms^ mbcjmstojis,_ mbclen^ mbctohira, 

_ mbctokata^ mbctolower^ mbctombb^ mbctoupperjnblen, mbrlen, mbrtowc, 
mbsrtowcs, mbsrtowcs_ sjnbstowcs, mbstowcs_ s,mbtowc, btowc, wcrtomb, 
wcrtomb_ s,wcsrtombs, wcsrtombs_ s,wcstombs, wcstombs_ s,wctob, wctomb, 
wctomb_ s 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned char mbl[2] = { 

0x41, 0x42 

} ; 


unsigned char mb2[2] = { 
0x61, 0x43 

} ; 


void main() 

{ 

int i; 

_ setmbcp( 932 ) ; 
i = _ mbcicmp( mbl, mb2 ); 
if( i < 0 ) 

printf ( "Less than\n" ); 
else if( i == 0 ) 

printf ( "Equal to\n" ); 

else 

printf ( "Greater than\n" ); 
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mbcicmp, Jmbcicmp 


Classification: 

Systems: 


produces the following: 
Equal to 
WATCOM 


mbcicmp - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
fmbcicmp - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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mbcjistojms 


Synopsis: 

Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <mbstring.h> 

unsigned int _ mbcjistojms( unsigned int ch ); 

The _ mbc j i sto jms converts a JIS character set code to a shift-JIS character set code. If the 
argument is out of range, _ mbcjistojms returns 0. Valid JIS double-byte characters are those in 
which the first and second byte fall in the range 0x21 through 0x7E. This is summarized in the 
following diagram. 

[ 1st byte ] [ 2nd byte ] 

0x21-0x7E 0x21-0x7E 

Note: The JIS character set code is a double-byte character set defined by JIS, the Japan Industrial 
Standard Institutes. Shift-JIS is another double-byte character set. It is defined by Microsoft for 
personal computers and is based on the JIS code. The first byte and the second byte of JIS codes can 
have values less than 0x80. Microsoft has designed shift-JIS code so that it can be mixed in strings with 
single-byte alphanumeric codes. Thus the double-byte shift-JIS codes are greater than or equal to 
0x8140. 

Note: This function was called jisto jms in earlier versions. 

The _ mbcjistojms function returns zero if the argument is not in the range; otherwise, the 
corresponding shift-JIS code is returned. 

_ getmbcp,_ mbbtombc,_ mbc jmsto jis,_ mbctombb,_ ismbbalnum,_ ismbbalpha, 

_ ismbbgraph^ ismbbkalnum,_ ismbbkalpha,_ ismbbkana,_ ismbbkprint, 

_ ismbbkpunct,_ ismbblead,_ ismbbprint,_ ismbbpunct,_ ismbbtrail,_ mbbtombc, 
_ mbc jmsto jis,_ mbctombb,_ mbbtype,_ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

void main() 

{ 

unsigned short c; 

_ setmbcp( 932 ) ; 
c = _ mbcjistojms( 0x2152 ); 
printf( "%^6.4x\n", c ); 

} 

produces the following: 

0x8171 

WATCOM 

All, Linux, RDOS 
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mbcjmstojis 


Synopsis: 

Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <mbstring.h> 

unsigned int _ mbcjmstojis( unsigned int ch ); 

The _ mbc jmsto j i s converts a shift-JIS character set code to a JIS character set code. If the 
argument is out of range, _ mbcjmstojis returns 0. Valid shift-JIS double-byte characters are those 
in which the first byte falls in the range 0x81 through 0x9F or OxEO through OxFC and whose second 
byte falls in the range 0x40 through 0x7E or 0x80 through OxFC. This is summarized in the following 
diagram. 


[ 1st byte ] [ 2nd byte ] 

0x81-0x9F 0x40-0xFC 

or except 0x7F 

OxEO-OxFC 

Note: The JIS character set code is a double-byte character set defined by JIS, the Japan Industrial 
Standard Institutes. Shift-JIS is another double-byte character set. It is defined by Microsoft for 
personal computers and is based on the JIS code. The first byte and the second byte of JIS codes can 
have values less than 0x80. Microsoft has designed shift-JIS code so that it can be mixed in strings with 
single-byte alphanumeric codes. Thus the double-byte shift-JIS codes are greater than or equal to 
0x8140. 

Note: This function was called jmsto j is in earlier versions. 

The _ mbcjmstojis function returns zero if the argument is not in the range; otherwise, the 
corresponding shift-JIS code is returned. 

_ getmbcp,_ mbbtombc,_ mbc jisto jms,_ mbctombb^. ismbbalnum,_ ismbbalpha, 

_ ismbbgraph^ ismbbkalnum,_ ismbbkalpha,_ ismbbkana,_ ismbbkprint, 

_ ismbbkpunct,_ ismbblead,_ ismbbprint,_ ismbbpunct,_ ismbbtrail^_ mbbtombc, 
_ mbc jisto jms,_ mbctombb,__ mbbtype,_ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

void main() 

1 

unsigned short c; 

_ setmbcp( 932 ) ; 
c = _ mbcjmstojis( 0x8171 ); 
printf( "%^6.4x\n", c ); 

} 

produces the following: 

0x2152 

WATCOM 

All, Linux, RDOS 
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mbclen, _fmbclen 


Synopsis: #include <mbstring.h> 

size_t _ mbclen( const unsigned char *ch ); 

size_ t far _ fmbclen ( const unsigned char_far *ch ) ; 

Description: The _ mbclen function determines the number of bytes comprising the multibyte character pointed to 
by ch. 

The _ fmbclen function is a data model independent form of the _mbclen function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

Returns: If ch is a NULL pointer, the _ mbclen function returns zero if multibyte character encodings do not 

have state-dependent encoding, and non-zero otherwise. If ch is not a NULL pointer, the _ mbclen 
function returns: 

Value Meaning 

0 if ch points to the null character 

1 if ch points to a single-byte character 

2 if ch points to a double-byte character 

-1 if ch does not point to a valid multibyte character 

See Also: _ mbccmp,_ mbccpy,_ mbcicmp,_ mbc jisto jms,_ mbc jmsto jis,_ mbctohira, 

_ mbctokata,_ mbctolower^ mbctombb,_ mbctoupperjnblen, mbrlen, mbrtowc, 
mbsrtowcs, mbsrtowcs_ sjnbstowcs, mbstowcs_ s,mbtowc, btowc, wcrtomb, 
wcrtomb_ s,wcsrtombs, wcsrtombs_ s,wcstombs, wcstombs_ s,wctob, wctomb, 
wctomb_ s 

Example: #include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned char chars[] = { 

r r 

r 

r r 
• r 

'i', 

'A' , 

0x81,0x40, /* double-byte space */ 

0x82,0x60, /* double-byte A */ 

0x82,0xA6, /* double-byte Hiragana */ 

0x83,0x42, /* double-byte Katakana */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6, /* single-byte Katakana alphabetic */ 

OxDF, /* single-byte Katakana alphabetic */ 

0xE0,0xAl, /* double-byte Kanji */ 

0x00 /* null character */ 

} ; 
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mbclen, _fmbclen 


void main() 

{ 

int i, j; 

_ setmbcp ( 932 ) ; 

for ( i = 0; i < sizeof(chars); i += j ) { 

j = _ mbclen( &chars[i] ); 
printf ( "%d bytes in characterin'', j ); 

} 

} 


produces the following: 


1 

bytes 

in 

character 

1 

bytes 

in 

character 

1 

bytes 

in 

character 

1 

bytes 

in 

character 

2 

bytes 

in 

character 

2 

bytes 

in 

character 

2 

bytes 

in 

character 

2 

bytes 

in 

character 

1 

bytes 

in 

character 

1 

bytes 

in 

character 

1 

bytes 

in 

character 

2 

bytes 

in 

character 

1 

bytes 

in 

character 


Classification: WATCOM 


Systems: 

_ mbclen - 

DOS, 

Windows, 

Win386, 

Win32, 

OS/2 1 

.x(all), 

OS/2-32, 

Linux 


RDOS 










_ fmbclen 

- DOS, 

Windows, 

Win386, 

Win32, 

OS/2 

1.x(all) 

, OS/2-32, 

RDOS 
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mbctolower 


Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

unsigned int _ mbctolower( unsigned int c ); 

The _ mbctolower function converts an uppercase multibyte character to an equivalent lowercase 
multibyte character. 

For example, in code page 932, this includes the single-byte uppercase letters A-Z and the double-byte 
uppercase characters such that: 

0x8260 <= c <= 0x8279 

Note: This function was called jtolower in earlier versions. 

The _ mbctolower function returns the argument value if the argument is not a double-byte uppercase 
character; otherwise, the equivalent lowercase character is returned. 

_ mbccmp,_ mbccpy,_ mbcicmp,_ mbcjistojms,_ mbc jmsto jis,_ mbclen,_ mbctohira, 
_ mbctokata^ mbctombb,_ mbctoupperjnblen, mbrlen, mbrtowc, mbsrtowcs, 
mbsrtowcs_ sjnbstowcs, mbstowcs_ s^nbtowc, btowc, wcrtomb, wcrtomb_ s, 
wcsrtombs, wcsrtombs_ s,wcstombs, wcstombs_ s,wctob, wctomb, wctomb_ s 

♦include <stdio.h> 

♦include <mbctype.h> 


♦include 

<mbstring. 

. h> 




unsigned 

int 

chars 

[] = { 




'A' , 


/* 

single- 

-byte 

A 

*/ 

'B' , 


/* 

single- 

-byte 

B 

*/ 

'C' , 


/* 

single- 

-byte 

C 

*/ 

'D' , 


/* 

single- 

-byte 

D 

*/ 

'E' , 


/* 

single- 

-byte 

E 

*/ 

0x8260, 

/* 

double- 

-byte 

A 

*/ 

0x8261, 

/* 

double- 

-byte 

B 

*/ 

0x8262, 

/* 

double- 

-byte 

C 

*/ 

0x8263, 

/* 

double- 

-byte 

D 

*/ 

0x8264 

/* 

double- 

-byte 

E 

*/ 


} ; 


♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 
unsigned int c; 

_ setmbcp( 932 ) ; 
for( i = 0; i < SIZE; i++ ) { 

c = _ mbctolower( chars[ i ] ); 

if( c > Oxff ) 

printf( "%c%c", c>>8, c ); 
else 

printf ( "%c", c ); 

} 

printf ( "\n" ); 

} 


Library Functions and Macros 617 




mbctolower 


Classification: 

Systems: 


produces the following: 
abcde abode 
WATCOM 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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mbctoupper 


Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

unsigned int _ mbctoupper( unsigned int c ); 

The _ mbctoupper function converts a lowercase multibyte character to an equivalent uppercase 
multibyte character. 

For example, in code page 932, this includes the single-byte lowercase letters a-z and the double-byte 
lowercase characters such that: 

0x8281 <= c <= 0x829A 

Note: This function was called jtoupper in earlier versions. 

The _ mbctoupper function returns the argument value if the argument is not a double-byte lowercase 
character; otherwise, the equivalent uppercase character is returned. 

_ mbccmp,_ mbccpy,_ mbcicmp,_ mbcjistojms,_ mbc jmsto jis,_ mbclen,_ mbctohira, 
_ mbctokata,_ mbctolower^. mbctombb^nblen, mbrlen, mbrtowc, mbsrtowcs, 
mbsrtowcs_ sjnbstowcs, mbstowcs_ s^nbtowc, btowc, wcrtomb, wcrtomb_ s, 
wcsrtombs, wcsrtombs_ s,wcstombs, wcstombs_ s,wctob, wctomb, wctomb_ s 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned int chars[] = { 


'a' , 

/* 

single- 

-byte 

a 

*/ 

'b' , 

/* 

single- 

-byte 

b 

*/ 

' c' , 

/* 

single- 

-byte 

c 

*/ 

'd' , 

/* 

single- 

-byte 

d 

*/ 

' e' , 

/* 

single- 

-byte 

e 

*/ 

0x8281, 

/* 

double- 

-byte 

a 

*/ 

0x8282, 

/* 

double- 

-byte 

b 

*/ 

0x8283, 

/* 

double- 

-byte 

c 

*/ 

0x8284, 

/* 

double- 

-byte 

d 

*/ 

0x8285 

/* 

double- 

-byte 

e 

*/ 


} ; 

♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 
unsigned int c; 

_ setmbcp( 932 ) ; 
for( i = 0; i < SIZE; i++ ) { 

c = _ mbctoupper( chars[ i ] ); 

if( c > Oxff ) 

printf( "%c%c", c>>8, c ); 
else 

printf ( "%c", c ); 

} 

printf ( "\n" ); 

} 
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mbctoupper 


Classification: 

Systems: 


produces the following: 

ABODE ABODE 
WATCOM 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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mbctohira 


Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

unsigned int _ mbctohira( unsigned int ch ); 

The _ mbctohira converts a double-byte Katakana character to a Hiragana character. A double-byte 
Katakana character is any character for which the following expression is true: 

0x8340 <= ch <= 0x8396 && ch != 0x837F 

Any Katakana character whose value is less than 0x8393 is converted to Hiragana (there are 3 extra 
Katakana characters that have no equivalent). 

Note: The Japanese double-byte character set includes Kanji, Hiragana, and Katakana characters - both 
alphabetic and numeric. Kanji is the ideogram character set of the Japanese character set. Hiragana and 
Katakana are two types of phonetic character sets of the Japanese character set. The Hiragana code set 
includes 83 characters and the Katakana code set includes 86 characters. 


Note: This function was called jtohira in earlier versions. 

The _ mbctohira function returns the argument value if the argument is not a double-byte Katakana 
character; otherwise, the equivalent Hiragana character is returned. 

_ mbccmp,_ mbccpy,_ mbcicmp,_ mbcjistojms,_ mbc jmsto jis,_ mbclen,_ mbctokata, 
_ mbctolower^ mbctombb^ mbctoupperjnblen, mbrlen, mbrtowc, mbsrtowcs, 
mbsrtowcs_ sjnbstowcs, mbstowcs_ sjnbtowc, btowc, wcrtomb, wcrtomb_ s, 
wcsrtombs, wcsrtombs_ s,wcstombs, wcstombs_ s,wctob, wctomb, wctomb_ s 


♦include <stdio.h> 
♦include <mbctype.h> 
♦include <mbstring.h> 

unsigned int chars[] = { 
0x8340, 

0x8364, 

0x8396 

} ; 


♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 


} 


_ setmbcp( 932 ) ; 
for( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x - %^6.4x\n", 
chars [ i ], 

_ mbctohira( chars[ i 


} 


) ; 


produces the following: 


Library Functions and Macros 621 




mbctohira 


0x8340 - 0x829f 
0x8364 - 0x82c3 
0x8396 - 0x8396 

Classification: WATCOM 

Systems: All, Linux, RDOS 
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mbctokata 


Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


Classification: 


♦include <mbstring.h> 

unsigned int _ mbctokata ( unsigned int ch ); 

The _ mbctokata converts a double-byte Hiragana character to a Katakana character. A double-byte 
Hiragana character is any character for which the following expression is true: 

0x829F <= c <= 0x82Fl 

Note: The Japanese double-byte character set includes Kanji, Hiragana, and Katakana characters - both 
alphabetic and numeric. Kanji is the ideogram character set of the Japanese character set. Hiragana and 
Katakana are two types of phonetic character sets of the Japanese character set. The Hiragana code set 
includes 83 characters and the Katakana code set includes 86 characters. 


Note: This function was called jtokata in earlier versions. 

The _ mbctokata function returns the argument value if the argument is not a double-byte Hiragana 
character; otherwise, the equivalent Katakana character is returned. 

_ mbccmp,_ mbccpy,_ mbcicmp,_ mbcjistojms,_ mbc jmsto jis,_ mbclen,_ mbctohira, 
_ mbctolower^ mbctombb^ mbctoupperjnblen, mbrlen, mbrtowc, mbsrtowcs, 
mbsrtowcs_ sjnbstowcs, mbstowcs_ s,mbtowc, btowc, wcrtomb, wcrtomb_ s, 
wcsrtombs, wcsrtombs_ s,wcstombs, wcstombs_ s,wctob, wctomb, wctomb_ s 


♦include <stdio.h> 
♦include <mbctype.h> 
♦include <mbstring.h> 

unsigned int chars[] = { 
0x82 9F, 

0x82B0, 

0x82Fl 

} ; 


♦define SIZE sizeof( chars ) / sizeof( unsigned int ) 

void main() 

1 

int i; 


} 


_ setmbcp( 932 ) ; 
for( i = 0; i < SIZE; i++ ) { 

printf( "%^6.4x - %^6.4x\n", 
chars [ i ], 

_ mbctokata( chars[ i 


} 


) ; 


produces the following: 

0x829f - 0x8340 
0x82b0 - 0x8351 
0x82f1 - 0x8393 


WATCOM 
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mbctokata 


Systems: 


All, Linux, RDOS 
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mbctombb 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <mbstring.h> 

unsigned int _ mbctombb ( unsigned int ch ); 

The _ mbctombb function returns the single-byte character equivalent to the double-byte character ch. 
The single-byte character will be in the range 0x20 through 0x7E or OxAl through OxDF. 

Note: This function was called zentohan in earlier versions. 

The _ mbctombb function returns ch if there is no equivalent single-byte character; otherwise 
_ mbctombb returns a single-byte character. 


_ getmbcp,_ mbbtombc,_ mbc jisto jms,_ mbc jmsto jis,_ ismbbalnum,_ ismbbalpha, 
_ ismbbgraph^ ismbbkalnum,_ ismbbkalpha,_ ismbbkana,_ ismbbkprint, 

_ ismbbkpunct,_ ismbblead,_ ismbbprint,_ ismbbpunct,_ ismbbtrail^_ mbbtombc, 
_ mbc jisto jms,_ mbc jmsto jis,_ mbbtype^_ setmbcp 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

♦define ZEN(x) 130*256+(x-1+32) 

unsigned int alphabet[26] = { 

ZEN (' A' ) , ZEN (' B' ) , ZEN (' C' ) , ZEN (' D' ) , ZEN (' E' ) , 

ZEN (' F' ) , ZEN (' G' ) ,ZEN('H' ) ,ZEN('I' ) , ZEN (' J' ) , 

ZEN (' K' ) , ZEN (' L' ) , ZEN (' M' ) , ZEN (' N' ) , ZEN (' O' ) , 

ZEN (' P' ) , ZEN (' Q' ) , ZEN (' R' ) , ZEN ('S' ) ,ZEN('T' ) , 

ZEN (' U' ) , ZEN (' V' ) , ZEN (' W' ) , ZEN (' X' ) , ZEN (' Y' ) , 

ZEN('Z') 

} ; 

♦define SIZE sizeof( alphabet ) / sizeof( unsigned int ) 

void main() 

{ 

int i; 

unsigned int c; 

_ setmbcp( 932 ) ; 

for( i = 0; i < SIZE; i++ ) { 

c = _ mbctombb( alphabet[ i ] ); 

printf ( "%c", c ); 

} 

printf ( "\n" ); 

} 

produces the following: 

ABCDEFGHIJKLMNOPQRSTUVWXYZ 
WATCOM 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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mbgetcode, Jmbgetcode 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <mbstring.h> 

unsigned char *_ mbgetcode( unsigned char *mbstr, 

unsigned int *dbchp ); 

unsigned char far *_ fmbgetcode( unsigned char far *mbstr, 

unsigned int *dbchp ); 

The _ mbgetcode function places the next single- or double-byte character from the start of the Kanji 
string specified by mbstr in the wide character pointed to by dbchp. If the second-half of a double-byte 
character is NULL, then the returned wide character is NULL. 

The _ fmbgetcode function is a code and data model independent form of the_ mbgetcode 
function. It accepts far pointer arguments and returns a far pointer. It is most useful in mixed memory 
model applications. 

The _ mbgetcode function returns a pointer to the next character to be obtained from the string. If 
mbstr points at a null character then mbstr is returned. 

_ mbsnccnt^ mbputchar 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

unsigned char set[] = { 

"ab\x81\x41\x81\x42\cd\x81" 

} ; 


void main() 

{ 

unsigned int c; 
unsigned char *str; 

_ setmbcp( 932 ) ; 
str = set; 

for ( ; *str != ' \0'; ) { 

str = _ mbgetcode ( str, &c ) ; 

printf ( "Character code 0x%2.2x\n", c ); 

} 

} 


produces the following: 


Character 

Character 

Character 

Character 

Character 

Character 

Character 


code 0x61 
code 0x62 
code 0x8141 
code 0x8142 
code 0x63 
code 0x64 
code 0x00 


WATCOM 


_ mbgetcode - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
RDOS 
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mbgetcode, Jmbgetcode 


_ fmbgetcode - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
RDOS 


Library Functions and Macros 627 




mblen, _fmblen 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


#include <stdlib.h> 
or 

♦include <mbstring.h> 

int mblen( const char *s, size_t n ); 

int _ fmblen ( const char_far *s, size_ t n ); 

The mblen function determines the number of bytes comprising the multibyte character pointed to by 
s. At most n bytes of the array pointed to by 5 will be examined. 

The _ fmblen function is a data model independent form of the mblen function. It accepts far pointer 
arguments and returns a far pointer. It is most useful in mixed memory model applications. 

If ,v is a NULL pointer, the mblen function returns zero if multibyte character encodings are not state 
dependent, and non-zero otherwise. If .5 is not a NULL pointer, the mblen function returns: 

Value Meaning 

0 if ,v points to the null character 

len the number of bytes that comprise the multibyte character (if the next n or fewer bytes form a 

valid multibyte character) 

-1 if the next n bytes do not form a valid multibyte character 

_ mbccmp,_ mbccpy,_ mbcicmp,_ mbcjistojms,_ mbc jmsto jis,_ mbclen,_ mbctohira, 
_ mbctokata^ mbctolower^. mbctombb,_ mbctoupperjnbrlen, mbrtowc, mbsrtowcs, 
mbsrtowcs_ sjnbstowcs, mbstowcs_ s^nbtowc, btowc, wcrtomb, wcrtomb_ s, 
wcsrtombs, wcsrtombs_ s,wcstombs, wcstombs_ s,wctob, wctomb, wctomb_ s 
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mblen, Jrnblen 


♦include <stdio.h> 
♦include <mbstring.h> 


const char chars[] = { 

r r 

r 

r r 
• r 

'i', 

'A' , 

0x81,0x40, /* double-byte space */ 

0x82,0x60, /* double-byte A */ 

0x82,0xA6, /* double-byte Hiragana */ 

0x83,0x42, /* double-byte Katakana */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6, /* single-byte Katakana alphabetic */ 

OxDF, /* single-byte Katakana alphabetic */ 

0xE0,0xAl, /* double-byte Kanji */ 

0x00 

} ; 

void main() 

{ 

int i, j, k; 

_ setmbcp( 932 ) ; 

printf ( "Character encodings are %sstate dependent\n", 

( mblen ( NULL, MB_ CUR_ MAX ) ) ? "" : "not " ); 

j = i; 

for ( i = 0; j > 0; i += j ) { 

j = mblen ( &chars[i], MB_ CUR_ MAX ); 
printf( "%d bytes in character ", j ); 
if( j == 0 ) { 
k = 0; 

} else if ( j == 1 ) { 

k = chars [ i]; 

} else if( j == 2 ) { 

k = chars [i]«8 | chars [i + 1]; 

} 

printf( " (%#6. 4x)\n", k ); 

} 

} 

produces the following: 

Character encodings are not state dependent 
1 bytes in character (0x0020) 

1 bytes in character (0x002e) 

1 bytes in character (0x0031) 

1 bytes in character (0x0041) 

2 bytes in character (0x8140) 

2 bytes in character (0x8260) 

2 bytes in character (0x82a6) 

2 bytes in character (0x8342) 

1 bytes in character (OxOOal) 

1 bytes in character (0x00a6) 

1 bytes in character (OxOOdf) 

2 bytes in character (OxeOal) 

0 bytes in character ( 0000) 
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mblen, _fmblen 


Classification: 


Systems: 


ISOC 

_fmblen is WATCOM 

mblen - All, Linux, RDOS, Netware 

_ fmblen - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 


RDOS 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


mbputchar, Jmbputchar 


♦include <mbstring.h> 

unsigned char *_ mbputchar( unsigned char *mbstr, 

unsigned int dbch ) ; 

unsigned char far *_ fmbputchar( unsigned char far *mbstr, 

unsigned int dbch ) ; 

The _ mbputchar function places the next single- or double-byte character specified by dbch at the 
start of the buffer specified by mbstr. 

The _ fmbputchar function is a code and data model independent form of the_ mbputchar 
function. It accepts far pointer arguments and returns a far pointer. It is most useful in mixed memory 
model applications. 

The _ mbputchar function returns a pointer to the next location in which to store a character. 

_ mbsnccnt^ mbgetcode 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

void main() 

{ 

unsigned int c; 
unsigned char *strl; 
unsigned char *str2; 
unsigned char buff30]; 

_ setmbcp( 932 ); 

strl = "ab\x82\x62\x82\x63\ef\x81\x66"; 
str2 = buf; 


; *strl != '\0'; ) 

{ 


strl = _ mbgetcode ( 

strl, 

&c ) ; 

str2 = _ mbputchar ( 

str2, 

’<’ ) 

str2 = _ mbputchar ( 

str2, 

c ) ; 

str2 = _ mbputchar ( 

str2, 

'>' ) 


} 

*str2 = '\0'; 

printf( "%s\n", buf ); 

} 

produces the following: 

<a><b>< C>< D><e><f>< G> 

WATCOM 

_ mbputchar - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
RDOS 

_ fmbputchar - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
RDOS 
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mbrlen, Jmbrlen 


Synopsis: 


Description: 


Returns: 


See Also: 


♦include <wchar.h> 

int mbrlen ( const char *s, size_ t n, mbstate_ t *ps ); 

int _ fmbrlen ( const char far *s, size_ t n, mbstate_ t far *ps ); 

The mbrlen function determines the number of bytes comprising the multibyte character pointed to by 
s. The mbrlen function is equivalent to the following call: 

mbrtowc((wchar_ t *)0, s, n, ps != 0 ? ps : Sinternal) 

where & internal is the address of the internal mbstate_ t object for thembrlen function. 

The _ fmbrlen function is a data model independent form of the mbrlen function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The restartable multibyte/wide character conversion functions differ from the corresponding 
internal-state multibyte character functions ( mblen, mbtowc, and wctomb) in that they have an extra 
argument, ps, of type pointer to mbstate_ t that points to an object that can completely describe the 
current conversion state of the associated multibyte character sequence. If ps is a null pointer, each 
function uses its own internal mbstate_ t object instead. You are guaranteed that no other function in 
the library calls these functions with a null pointer for ps, thereby ensuring the stability of the state. 

Also unlike their corresponding functions, the return value does not represent whether the encoding is 
state-dependent. 

If the encoding is state-dependent, on entry each function takes the described conversion state (either 
internal or pointed to by ps) as current. The conversion state described by the pointed-to object is 
altered as needed to track the shift state of the associated multibyte character sequence. For encodings 
without state dependency, the pointer to the mbstate_ t argument is ignored. 

The mbrlen function returns a value between -2 and n, inclusive. The mbrlen function returns the 
first of the following that applies: 

Value Meaning 

0 if the next n or fewer bytes form the multibyte character that corresponds to the null 

wide character. 

>0 if the next n or fewer bytes form a valid multibyte character; the value returned is the 

number of bytes that constitute that multibyte character. 

-2 if the next n bytes form an incomplete (but potentially valid) multibyte character, and 

all n bytes have been processed; it is unspecified whether this can occur when the value 
of n is less than that of the MB_ CUR_ MAX macro. 

-1 if an encoding error occurs (when the next n or fewer bytes do not form a complete and 

valid multibyte character); the value of the macro EILSEQ will be stored in errno, 
but the conversion state will be unchanged. 

_ mbccmp,_ mbccpy,_ mbcicmp,_ mbcjistojms,_ mbc jmsto jis,_ mbclen,_ mbctohira, 
_ mbctokata^ mbctolower,_ mbctombb,_ mbctoupperjnblen, mbrtowc, mbsrtowcs, 
mbsrtowcs_ sjnbstowcs, mbstowcs_ sjnbtowc, btowc, wcrtomb, wcrtomb_ s, 
wcsrtombs, wcsrtombs_ s,wcstombs, wcstombs_ s,wctob, wctomb, wctomb_ s 
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mbrlen, Jmbrlen 


Example: #include <stdio.h> 

♦include <wchar.h> 
♦include <mbctype.h> 
♦include <errno.h> 


const char chars[] = { 

r r 

r 

r r 
• r 

'A' , 


0x81, 

0x40, 

/* 

double-byte 

space */ 


0x82, 

0x60, 

/* 

double-byte 

A */ 


0x82, 

0xA6, 

/* 

double-byte 

Hiragana 

*/ 

0x83, 

0x42, 

/* 

double-byte 

Katakana 

*/ 

OxAl, 


/* 

single-byte 

Katakana 

punctuation */ 

0xA6, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxDF, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxEO, 
0x00 

OxAl, 

/* 

double-byte 

Kanji */ 



void main() 

{ 

int i, j, k; 

_ setmbcp( 932 ) ; 
j = 1; 

for ( i = 0; j > 0; i += j ) { 

j = mbrlen ( &chars[i], MB_ CUR_ MAX, NULL ); 
printf( "%d bytes in character ", j ); 
if( errno == EILSEQ ) { 

printf ( " - illegal multibyte characterin' 1 ) ; 
} else { 

if( j == 0 ) { 
k = 0; 

} else if ( j == 1 ) { 

k = chars[i]; 

} else if( j == 2 ) { 

k = chars[i]<<8 | chars[i+1]; 

} 

printf ( " (%#6. 4x)\n", k ); 

} 

} 

} 

produces the following: 
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mbrlen, Jmbrlen 


Classification: 


Systems: 


1 

bytes 

in 

character 

(0x0020) 

1 

bytes 

in 

character 

(0x002e) 

1 

bytes 

in 

character 

(0x0031) 

1 

bytes 

in 

character 

(0x0041) 

2 

bytes 

in 

character 

(0x8140) 

2 

bytes 

in 

character 

(0x8260) 

2 

bytes 

in 

character 

(0x82a6) 

2 

bytes 

in 

character 

(0x8342) 

1 

bytes 

in 

character 

(OxOOal) 

1 

bytes 

in 

character 

(0x00a6) 

1 

bytes 

in 

character 

(OxOOdf) 

2 

bytes 

in 

character 

(OxeOal) 

0 

bytes 

in 

character 

( 0000) 


ISO C95 

_fmbrlen is WATCOM 

mbrlen - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, Linux, 
RDOS 

_ fmbrlen - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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mbrtowc, _fmbrtowc 


Synopsis: 


Description: 


Returns: 


♦include <wchar.h> 

int mbrtowc( wchar_ t *pwc, const char *s, 
size_ t n, mbstate_ t *ps ) ; 

int _ fmbrtowc ( wchar_ t_far *pwc, const char_far *s, 

size_ t n, mbstate_ t_far *ps ) ; 

If ,v is a null pointer, the mbrtowc function determines the number of bytes necessary to enter the 
initial shift state (zero if encodings are not state-dependent or if the initial conversion state is described). 
In this case, the value of the pwc argument will be ignored, and the resulting state described will be the 
initial conversion state. 

If ,v is not a null pointer, the mbrtowc function determines the number of bytes that are contained in 
the multibyte character (plus any leading shift sequences) pointed to by s, produces the value of the 
corresponding wide character and then, if pwc is not a null pointer, stores that value in the object 
pointed to by pwc. If the corresponding wide character is the null wide character, the resulting state 
described will be the initial conversion state. 

The function is a data model independent form of the mbrtowc function that accepts far pointer 
arguments. It is most useful in mixed memory model applications. 

The restartable multibyte/wide character conversion functions differ from the corresponding 
internal-state multibyte character functions ( mblen, mbtowc, and wctomb) in that they have an extra 
argument, ps, of type pointer to mbstate_ t that points to an object that can completely describe the 
current conversion state of the associated multibyte character sequence. If ps is a null pointer, each 
function uses its own internal mbstate_ t object instead. You are guaranteed that no other function in 
the library calls these functions with a null pointer for ps, thereby ensuring the stability of the state. 

Also unlike their corresponding functions, the return value does not represent whether the encoding is 
state-dependent. 

If the encoding is state-dependent, on entry each function takes the described conversion state (either 
internal or pointed to by ps) as current. The conversion state described by the pointed-to object is 
altered as needed to track the shift state of the associated multibyte character sequence. For encodings 
without state dependency, the pointer to the mbstate_ t argument is ignored. 

If .5 is a null pointer, the mbrtowc function returns the number of bytes necessary to enter the initial 
shift state. The value returned will not be greater than that of the MB_ CUR_ MAX macro. 

If ,v is not a null pointer, the mbrtowc function returns the first of the following that applies: 

Value Meaning 

0 if the next n or fewer bytes form the multibyte character that corresponds to the null 

wide character. 

>0 if the next n or fewer bytes form a valid multibyte character; the value returned is the 

number of bytes that constitute that multibyte character. 

-2 if the next n bytes form an incomplete (but potentially valid) multibyte character, and 

all n bytes have been processed; it is unspecified whether this can occur when the value 
of n is less than that of the MB_ CUR_ MAX macro. 
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mbrtowc, _fmbrtowc 


See Also: 


Example: 


-1 if an encoding error occurs (when the next n or fewer bytes do not form a complete and 

valid multibyte character); the value of the macro EILSEQ will be stored in errno, 
but the conversion state will be unchanged. 

_ mbccmp,_ mbccpy,_ mbcicmp,_ mbcjistojms,_ mbc jmsto jis,_ mbclen,_ mbctohira, 
_ mbctokata,_ mbctolower,_ mbctombb^ mbctoupperjnblen, mbrlen, mbsrtowcs, 
mbsrtowcs_ sjnbstowcs, mbstowcs_ sjnbtowc, btowc, wcrtomb, wcrtomb_ s, 
wcsrtombs, wcsrtombs_ s,wcstombs, wcstombs_ s,wctob, wctomb, wctomb_ s 

#include <stdio.h> 

♦include <wchar.h> 

♦include <mbctype.h> 

♦include <errno.h> 


const char chars[] = { 

r r 

t 

r r 
• r 

'i', 

'A' , 


0x81, 

0x40, 

/* 

double-byte 

space */ 


0x82, 

0x60, 

/* 

double-byte 

A */ 


0x82, 

0xA6, 

/* 

double-byte 

Hiragana 

* / 

0x83, 

0x42, 

/* 

double-byte 

Katakana 

*/ 

OxAl, 


/* 

single-byte 

Katakana 

punctuation */ 

0xA6, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxDF, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxEO, 
0 x00 

OxAl, 

/* 

double-byte 

Kanji */ 
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mbrtowc, _fmbrtowc 


void main() 

{ 

int i, j, k; 

wchar_ t pwc; 

_ setmbcp( 932 ) ; 

i = mbrtowc ( NULL, NULL, MB_ CUR_ MAX, NULL ) ; 
printf( "Number of bytes to enter " 

"initial shift state = %d\n", i ); 

j = 1; 

for( i = 0; j > 0; i += j ) { 

j = mbrtowc ( &pwc, &chars[i], MB_ CUR_ MAX, NULL ); 
printf( "%d bytes in character ", j ) ; 
if( errno == EILSEQ ) { 

printf ( " - illegal multibyte characterin'' ) ; 

} else { 

if( j == 0 ) { 
k = 0; 

} else if ( j == 1 ) { 

k = chars[i]; 

} else if( j == 2 ) { 

k = chars[i]<<8 | chars[i+1]; 

} 

printf ( "(%#6.4x->%#6.4x)\n", k, pwc ); 

} 

} 

} 

produces the following: 

Number of bytes to enter initial shift state = 0 
1 bytes in character (0x0020->0x0020) 

1 bytes in character (0x002e->0x002e) 

1 bytes in character (0x0031->0x0031) 

1 bytes in character (0x0041->0x0041) 

2 bytes in character (0x8140->0x3000) 

2 bytes in character (0x8260->0xff21) 

2 bytes in character (0x82a6->0x3048) 

2 bytes in character (0x8342->0x30a3) 

1 bytes in character (0x00al->0xff61) 

1 bytes in character (0x00a6->0xff66) 

1 bytes in character (0x00df->0xff9f) 

2 bytes in character (0xe0al->0x720d) 

0 bytes in character ( 0000-> 0000) 

Classification: ISO C95 

_fmbrtowc is WATCOM 

Systems: mbrtowc - DOS, Windows, Win386, Win32, OS/2 1.x (all), OS/2-32, Linux, 

RDOS 

_ fmbrtowc - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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mbsbtype, Jmbsbtype 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


♦include <mbstring.h> 

♦include <mbctype.h> (for manifest constants) 

int _ mbsbtype( const unsigned char *mbstr, int count ); 

int _ fmbsbtype( const unsigned char _ far *mbstr, 

int count ); 


The _ mbsbtype function determines the type of a byte in a multibyte character string. The function 
examines only the byte at offset count in mbstr, ignoring invalid characters before the specified byte 

Note: A similar function was called nthctype in earlier versions. 


The _ mbsbtype function returns one of the following values: 

_MBC_SINGLE the character is a valid single-byte character (e.g., 0x20 - 0x7E, OxAl - OxDF 

in code page 932) 


_MBC_LEAD 


the character is a valid lead byte character (e.g., 0x81 - 0x9F, OxEO - OxFC in 
code page 932) 


MBC TRAIL 


the character is a valid trailing byte character (e.g., 0x40 - 0x7E, 0x80 - OxFC 
in code page 932) 


MBC ILLEGAL 


the character is an illegal character (e.g., any value except 0x20 - 0x7E, OxAl 
- OxDF, 0x81 - 0x9F, OxEO - OxFC in code page 932) 


getmbcp,_ ismbcalnum,_ ismbcalpha^ ismbccntrl^ ismbcdigit,_ ismbcgraph, 
ismbchira^ ismbckata,_ ismbcl0,_ ismbcll^_ ismbcl2,_ ismbclegal, 
ismbclower,_ ismbcprint,_ ismbcpunct,_ ismbcspace,_ ismbcsymbol, 
ismbcupper,_ ismbcxdigit,_ mbbtype,_ setmbcp 
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mbsbtype, Jmbsbtype 


♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

const char *types[4] = { 
"ILLEGAL", 

"SINGLE", 

"LEAD", 

"TRAIL" 

} ; 

const unsigned char chars[] = { 

r r 

r 

r r 
• r 

'A' , 


0x81, 

0x40, 

/* 

double-byte 

space */ 


0x82, 

0x60, 

/* 

double-byte 

A */ 


0x82, 

0xA6, 

/* 

double-byte 

Hiragana 

*/ 

0x83, 

0x42, 

/* 

double-byte 

Katakana 

*/ 

OxAl, 


/* 

single-byte 

Katakana 

punctuation */ 

0xA6, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxDF, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxEO, 
0x00 

OxAl, 

/* 

double-byte 

Kanji */ 



} ; 

♦ define SIZE sizeof ( chars ) / sizeof ( unsigned char ) 

void main() 

{ 

int i; 

_ setmbcp( 932 ) ; 
for ( i = 0; i < SIZE; i++ ) 

printf ( "%s\n", types [ l+_ mbsbtype ( chars, i ) ] ); 

} 

produces the following: 

SINGLE 

SINGLE 

SINGLE 

SINGLE 

LEAD 

TRAIL 

LEAD 

TRAIL 

LEAD 

TRAIL 

LEAD 

TRAIL 

SINGLE 

SINGLE 

SINGLE 

LEAD 

TRAIL 

ILLEGAL 
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mbsbtype, Jmbsbtype 


Classification: 

Systems: 


WATCOM 


_ mbsbtype - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS 
_ fmbsbtype - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 

RDOS 
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Synopsis: 


Description: 


Returns: 
See Also: 
Example: 


mbsnbcat, Jmbsnbcat 


♦include <mbstring.h> 

unsigned char *_ mbsnbcat ( unsigned char *dst, 

const unsigned char *src, 
size_ t n ) ; 

unsigned char_far *_ fmbsnbcat ( unsigned char_far *dst, 

const unsigned char _ far *src, 

size_ t n ) ; 

The _ mbsnbcat function appends not more than n bytes of the string pointed to by src to the end of 
the string pointed to by dst. If the byte immediately preceding the null character in dst is a lead byte, 
the initial byte of src overwrites this lead byte. Otherwise, the initial byte of src overwrites the 
terminating null character at the end of dst. If the last byte to be copied from src is a lead byte, the lead 
byte is not copied and a null character replaces it in dst. In any case, a terminating null character is 
always appended to the result. 

The _ fmbsnbcat function is a data model independent form of the _mbsnbcat function. It accepts far 
pointer arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The _ mbsnbcat function returns the value of dst. 


mbsnbcmp,_ mbsnbcpy,_ mbsnbset,_ mbsnccnt,strncat, strcat 


♦include <stdio.h> 
♦include <string.h> 
♦include <mbctype.h> 
♦include <mbstring.h> 


const unsigned char strl[] = { 

0x81,0x40, /* double-byte space */ 
0x82,0x60, /* double-byte A */ 

0x00 


const unsigned 
0x81,0x40, 
0x82,0xA6, 
0x83,0x42, 
0x00 


char str2 [ ] = 
/* double-byte 
/* double-byte 
/* double-byte 


space */ 
Hiragana 
Katakana 


} ; 


*/ 

*/ 


void main() 

{ 

unsigned char big_ string[10]; 
int i; 


_ setmbcp( 932 ) ; 

memset( (char *) big_ string, Oxee, 10 ); 

big_ string[9] = 0x00; 

printf ( "Length of string = %d\n", 

strlen( (char *) big_ string ) ); 

for( i = 0; i < 10; i++ ) 

printf ( "%2.2x ", big_ string[i] ); 

printf ( "\n" ); 
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mbsnbcat, Jmbsnbcat 


_ rabsnset ( big_ string, 0x8145, 5 ); 
for( i = 0; i < 10; i++ ) 

printf ( "%2.2x ", big_ string[i] ); 

printf ( "\n" ); 

big_ string[0] = 0x00; 

_ mbsnbcat ( big_ string, strl, 3 ); 
for( i = 0; i < 10; i++ ) 

printf ( "%2.2x ", big_ string[i] ); 

printf ( "\n" ); 

big_ string[2] = 0x84; 
big_ string[3] = 0x00; 
for( i = 0; i < 10; i++ ) 

printf ( "%2.2x ", big_ string[i] ); 

printf ( "\n" ); 

_ mbsnbcat( big_ string, str2, 5 ); 
for( i = 0; i < 10; i++ ) 

printf ( "%2.2x ", big_ string[i] ); 

printf ( "\n" ); 

} 

produces the following: 


Length of string = 9 


ee 

ee 

ee 

ee 

ee 

ee 

ee 

ee 

ee 

00 

81 

45 

81 

45 

81 

45 

81 

45 

20 

00 

81 

40 

00 

00 

81 

45 

81 

45 

20 

00 

81 

40 

84 

00 

81 

45 

81 

45 

20 

00 

81 

40 

81 

40 

82 

a6 

00 

00 

20 

00 


Classification: WATCOM 


Systems: 

_ mbsnbcat - 

DOS, 

Windows, 

Win386, 

Win32, 

OS/2 1 

.x(all), 

OS/2-32, RDOS 


_ fmbsnbcat 

- DOS, 

Windows, 

Win386, 

Win32, 

OS/2 

1.x(all) 

, OS/2-32, 


RDOS 
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Synopsis: 


Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


mbsnbcmp, _fmbsnbcmp 


♦include <mbstring.h> 

int _ mbsnbcmp( const unsigned char *sl, 
const unsigned char *s2, 
size_ t n ) ; 

int _ fmbsnbcmp( const unsigned char _ far *sl, 

const unsigned char _far *s2, 

size_ t n ) ; 

The _ mbsnbcmp lexicographically compares not more than n bytes from the string pointed to by si to 
the string pointed to by s2. 

The _ fmbsnbcmp function is a data model independent form of the _mbsnbcmp function that accepts 
far pointer arguments. It is most useful in mixed memory model applications. 

The _ mbsnbcmp function returns an integer less than, equal to, or greater than zero, indicating that the 
string pointed to by si is less than, equal to, or greater than the string pointed to by s2. _ mbsnbcmp is 
similar to _ mbsncmp, except that_ mbsnbcmp compares strings by bytes rather than by characters. 

_ mbsnbcat^_ mbsnbicmp,strncmp, strnicmp 


♦include <stdio.h> 
♦include <mbctype.h> 
♦include <mbstring.h> 


const unsigned char strl[] = { 

0x81,0x40, /* double-byte space */ 
0x82,0x60, /* double-byte A */ 

0x00 


const unsigned 
0x81,0x40, 
0x82,0xA6, 
0x83,0x42, 
0x00 


char str2 [ ] = 
/* double-byte 
/* double-byte 
/* double-byte 


space */ 
Hiragana 
Katakana 


} ; 


*/ 

*/ 


void main() 

{ 

_ setmbcp( 932 ); 

printf ( "%d\n", _ mbsnbcmp( strl, str2, 3 ) ); 

} 


produces the following: 
0 


WATCOM 


_ mbsnbcmp - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS 
_ fmbsnbcmp - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 

RDOS 
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mbsnbcnt, Jmbsnbcnt, _stmcnt, _wcsncnt 


Synopsis: #include <mbstring.h> 

size_ t _ mbsnbcnt( const unsigned char ^string, size_ t n ) ; 

size_ t _ fmbsnbcnt( const unsigned char_far *string, 

size_ t n ) ; 

♦include <tchar.h> 

size_t _ strncnt( const char *string, size_ t n ) ; 
size_ t _ wcsncnt ( const wchar_ t *string, size_ t n ) { 

Description: The function counts the number of bytes in the first n multibyte characters of the string string. 

Note: This function was called mtob in earlier versions. 

The function is a data model independent form of the _mbsnbcnt function that accepts far pointer 
arguments. It is most useful in mixed memory model applications. 

The header file <tchar . h> defines the generic-text routine _ tcsnbcnt. This macro maps to if 
_ MBCS has been defined, or to the_ wcsncnt macro if_ UNICODE has been defined. Otherwise 
_ tcsnbcnt maps to _mbsnbcnt. _ mbsnbcnt and_ wcsncnt are single-byte character string and 
wide-character string versions of. The _ mbsnbcnt and_ wcsncnt macros are provided only for this 
mapping and should not be used otherwise. 

The _ mbsnbcnt function returns the number of characters (i.e., n) in the first n bytes of the 
single-byte string string. The _ wcsncnt function returns the number of bytes (i.e., 2 * n) in the first n 
wide characters of the wide-character string string. 

Returns: The _ mbsnbcnt functions return the number of bytes in the string up to the specified number of 

characters or until a null character is encountered. The null character is not included in the count. If the 
character preceding the null character was a lead byte, the lead byte is not included in the count. 

See Also: _ mbsnbcat^_ mbsnccnt 

Example: #include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

const unsigned char chars[] = { 

r r 

r 

r r 

• f 

'i', 

'A' , 

0x81,0x40, /* double-byte space */ 

0x82,0x60, /* double-byte A */ 

0x82,0xA6, /* double-byte Hiragana */ 

0x83,0x42, /* double-byte Katakana */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6, /* single-byte Katakana alphabetic */ 

OxDF, /* single-byte Katakana alphabetic */ 

0xE0,0xAl, /* double-byte Kanji */ 

0x00 

} ; 
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Classification: 

Systems: 


mbsnbcnt, Jmbsnbcnt, _stmcnt, _wcsncnt 


void main() 

{ 

_ setmbcp( 932 ); 

printf ( "%d bytes foundin'', 

_ mbsnbcnt( chars, 10 ) 


} 


); 


produces the following: 
14 bytes found 
WATCOM 


_ mbsnbcnt - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS 
_ fmbsnbcnt - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 

RDOS 

_ strncnt - MACRO 
_ wcsncnt - MACRO 
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mbsnbcpy, Jmbsnbcpy 


Synopsis: 


Description: 


Returns: 
See Also: 
Example: 


♦include <mbstring.h> 

unsigned char *_ mbsnbcpy ( unsigned char *dst, 

const unsigned char *src, 
size_ t n ) ; 

unsigned char_far *_ fmbsnbcpy ( unsigned char_far *dst, 

const unsigned char _ far *src, 

size_ t n ) ; 

The _ mbsnbcpy function copies no more than n bytes from the string pointed to by src into the array 
pointed to by dst. Copying of overlapping objects is not guaranteed to work properly. 

If the string pointed to by src is shorter than n bytes, null characters are appended to the copy in the 
array pointed to by dst, until n bytes in all have been written. If the string pointed to by src is longer 
than n characters, then the result will not be terminated by a null character. 

The _ fmbsnbcpy function is a data model independent form of the _mbsnbcpy function. It accepts 
far pointer arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The _ mbsnbcpy function returns the value of dst. 

strcpy, strdup 
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Classification: 

Systems: 


mbsnbcpy, Jmbsnbcpy 


♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

const unsigned char chars[] = { 

r r 

r 

r r 
• r 

'A' , 


0x81, 

0x40, 

/* 

double-byte 

space */ 


0x82, 

0x60, 

/* 

double-byte 

A */ 


0x82, 

0xA6, 

/* 

double-byte 

Hiragana 

*/ 

0x83, 

0x42, 

/* 

double-byte 

Katakana 

*/ 

OxAl, 


/* 

single-byte 

Katakana 

punctuation */ 

0xA6, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxDF, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxEO, 
0x00 

OxAl, 

/* 

double-byte 

Kanji */ 



} ; 

void main() 

{ 

unsigned char chars2[20]; 
int i; 

_ setmbcp( 932 ) ; 

_ mbsnset( chars2, OxFF, 20 ); 

_ mbsnbcpy( chars2, chars, 11 ); 
for( i = 0; i < 20; i++ ) 

printf ( "%2.2x ", chars2[i] ); 
printf ( "\n" ); 

_ mbsnbcpy( chars2, chars, 20 ); 
for ( i = 0; i < 20; i++ ) 

printf ( "%2.2x ", chars2[i] ); 
printf ( "\n" ); 

} 

produces the following: 

20 2e 31 41 81 40 82 60 82 a6 83 ff ff ff ff ff ff ff ff ff 
20 2e 31 41 81 40 82 60 82 a6 83 42 al a6 df eO al 00 00 00 

WATCOM 

_ mbsnbcpy - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS 
_ fmbsnbcpy - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 

RDOS 
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mbsnbicmp, Jmbsnbicmp 


Synopsis: #include <mbstring.h> 

int _ mbsnbicmp( const unsigned char *sl, 
const unsigned char *s2, 
size_ t n ) ; 

int _ fmbsnbicmp( const unsigned char _far *sl, 

const unsigned char _far *s2, 

size_ t n ) ; 

Description: The _ mbsnbicmp lexicographically compares not more than n bytes from the string pointed to by si 
to the string pointed to by s2. The comparison is insensitive to case. 

The _ fmbsnbicmp function is a data model independent form of the _mbsnbicmp function that 
accepts far pointer arguments. It is most useful in mixed memory model applications. 

Returns: The _ mbsnbicmp function returns an integer less than, equal to, or greater than zero, indicating that 

the string pointed to by si is less than, equal to, or greater than the string pointed to by s2. 

_ mbsnbicmp is similar to_ mbsncmp, except that_ mbsnbicmp compares strings by bytes rather 
than by characters. 

See Also: _ mbsnbcat,_ mbsnbcmp,strncmp, strnicmp 

Example: #include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

const unsigned char strl[] = { 

0x81,0x40, /* double-byte space */ 

0x82,0x60, /* double-byte A */ 

0x82,0x79, /* double-byte Z */ 

0x00 

} ; 

const unsigned char str2[] = { 

0x81,0x40, /* double-byte space */ 

0x82,0x81, /* double-byte a */ 

0x82,0x9a, /* double-byte z */ 

0x00 

} ; 

void main() 

{ 

_ setmbcp( 932 ); 

printf ( "%d\n", _ mbsnbicmp ( strl, str2, 5 ) ); 

} 

produces the following: 

0 

Classification: WATCOM 

Systems: _ mbsnbicmp - DOS, Windows, Win386, Win32, OS/2 1.x (all), OS/2-32, 

RDOS 

_ fmbsnbicmp - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
RDOS 
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Synopsis: 


Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


mbsnbset, Jmbsnbset 


♦include <mbstring.h> 

unsigned char *_ mbsnbset ( unsigned char *str, 

unsigned int fill, 
size_ t count ); 

unsigned char_far *_ fmbsnbset ( unsigned char_far *str, 

unsigned int fill, 
size_ t count ); 

The _ mbsnbset function fills the string str with the value of the argument////. When the value of len 
is greater than the length of the string, the entire string is filled. Otherwise, that number of characters at 
the start of the string are set to the fill character. 

_ mbsnbset is similar to_ mbsnset, except that it fills in count bytes rather than count characters. If 
the number of bytes to be filled is odd and fill is a double-byte character, the partial byte at the end is 
filled with an ASCII space character. 

The _ fmbsnbset function is a data model independent form of the _mbsnbset function. It accepts far 
pointer arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The address of the original string str is returned. 

strnset, strset 

♦include <stdio.h> 

♦include <string.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

void main() 

{ 

unsigned char big_ string[10]; 

int i; 

_ setmbcp( 932 ) ; 

memset( (char *) big_ string, Oxee, 10 ); 
big_ string[9] = 0x00; 
for( i = 0; i < 10; i++ ) 

printf ( "%2.2x ", big_ string[i] ); 

printf ( "\n" ); 

_ mbsnbset ( big_ string, 0x8145, 5 ); 
for( i = 0; i < 10; i++ ) 

printf ( "%2.2x ", big_ string[i] ); 

printf ( "\n" ); 


} 

produces the following: 

ee ee ee ee ee ee ee ee ee 00 
81 45 81 45 20 ee ee ee ee 00 

WATCOM 

_ mbsnbset - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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mbsnbset, Jmbsnbset 


_ fmbsnbset - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
RDOS 
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Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


mbsnccnt, Jmbsnccnt, _stmcnt, _wcsncnt 


♦include <mbstring.h> 

size_ t _ mbsnccnt( const unsigned char *string, size_ t n ) ; 

size_ t _ fmbsnccnt( const unsigned char _ far *string, 

size_ t n ) ; 

♦include <tchar.h> 

size_ t _ strncnt( const char *string, size_ t n ) ; 
size_ t _ wcsncnt ( const wchar_ t *string, size_ t n ) { 

The function counts the number of multibyte characters in the first n bytes of the string string. If finds a 
null byte as the second byte of a double-byte character, the first (lead) byte is not included in the count. 

Note: This function was called btom in earlier versions. 

The function is a data model independent form of the _mbsnccnt function that accepts far pointer 
arguments. It is most useful in mixed memory model applications. 

The header file <tchar . h> defines the generic-text routine _ tcsnccnt. This macro maps to if 
_ MBCS has been defined, or to the_ wcsncnt macro if_ UNICODE has been defined. Otherwise 
_ tcsnccnt maps to _mbsnccnt. _ mbsnccnt and_ wcsncnt are single-byte character string and 
wide-character string versions of. The _ mbsnccnt and_ wcsncnt macros are provided only for this 
mapping and should not be used otherwise. 

The _ mbsnccnt function returns the number of characters (i.e., n) in the first n bytes of the 
single-byte string string. The _ wcsncnt function returns the number of bytes (i.e., 2 * n) in the first n 
wide characters of the wide-character string string. 

_ mbsnccnt returns the number of characters from the beginning of the string to byte n. _ wcsncnt 
returns the number of wide characters from the beginning of the string to byte n. returns the number of 
multibyte characters from the beginning of the string to byte n. If these functions find a null character 
before byte n, they return the number of characters before the null character. If the string consists of 
fewer than n characters, these functions return the number of characters in the string. 

_ mbsnbcat,_ mbsnbcnt 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

const unsigned char chars[] = { 

r r 

r 

r r 
• r 

'i', 

'A' , 


0x81, 

0x40, 

/* 

double-byte 

space */ 


0x82, 

0x60, 

/* 

double-byte 

A */ 


0x82, 

0xA6, 

/* 

double-byte 

Hiragana 

*/ 

0x83, 

0x42, 

/* 

double-byte 

Katakana 

*/ 

OxAl, 


/* 

single-byte 

Katakana 

punctuation */ 

0xA6, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxDF, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxEO, 
0x00 

OxAl, 

/* 

double-byte 

Kanji */ 



} ; 
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mbsnccnt, Jmbsnccnt, _strncnt, _wcsncnt 


void main() 

{ 

_ setmbcp( 932 ); 

printf( "%d characters found\n", 

_ mbsnccnt ( chars, 10 ) ); 

} 


produces the following: 

7 characters found 


Classification: WATCOM 


Systems: _ mbsnccnt - DOS, Windows, Win386, Win32, OS/2 1.x (all), OS/2-32, 

_ fmbsnccnt - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
RDOS 

_ strncnt - MACRO 
_ wcsncnt - MACRO 


RDOS 
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Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


mbsnextc, Jmbsnextc, _stmextc, _wcsnextc 


#include <mbstring.h> 

unsigned int _ mbsnextc( const unsigned char *string ); 
unsigned int _ fmbsnextc( 

const unsigned char _ far *string ); 

♦include <tchar.h> 

unsigned int _strnextc( const char *string ); 
unsigned int _ wcsnextc( const wchar_t *string ) { 

The function returns the integer value of the next multibyte-character in string , without advancing the 
string pointer, recognizes multibyte character sequences according to the multibyte code page currently 
in use. 

The header file <tchar . h> defines the generic-text routine _ tcsnextc. This macro maps to if 
_ MBCS has been defined, or to_ wcsnextc if_ UNICODE has been defined. Otherwise_ tcsnextc 
maps to _mbsnextc. _ mbsnextc and_ wcsnextc are single-byte character string and wide-character 
string versions of. _ mbsnextc and_ wcsnextc are provided only for this mapping and should not 
be used otherwise. _ mbsnextc returns the integer value of the next single-byte character in the string. 
_ wcsnextc returns the integer value of the next wide character in the string. 

These functions return the integer value of the next character (single-byte, wide, or multibyte) pointed 
to by string. 

_ strdec,_ strinc,_ strninc 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

const unsigned char chars[] = { 

r r 

r 

r r 

• f 

'i', 

'A' , 


0x81, 

0x40, 

/* 

double-byte 

space */ 


0x82, 

0x60, 

/* 

double-byte 

A */ 


0x82, 

0xA6, 

/* 

double-byte 

Hiragana 

*/ 

0x83, 

0x42, 

/* 

double-byte 

Katakana 

*/ 

OxAl, 


/* 

single-byte 

Katakana 

punctuation */ 

0xA6, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxDF, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxEO, 
0x00 

OxAl, 

/* 

double-byte 

Kanji */ 



} ; 

void main() 

{ 

_ setmbcp( 932 ); 


printf( 

"%# 6 . 4x\n", 

_ mbsnextc( 

Schars[2] ) 

) ; 

printf( 

"%# 6 . 4x\n", 

_ mbsnextc( 

Schars[4] ) 

); 

printf( 

" %# 6 . 4x\n", 

_ mbsnextc( 

Schars[12] ; 

1 ); 


} 

produces the following: 
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mbsnextc, Jmbsnextc, _strnextc, _wcsnextc 


0x0031 

0x8140 

OxOOal 

Classification: WATCOM 

Systems: _ mbsnextc - DOS, Windows, Win386, Win32, OS/2 1.x (all), OS/2-32, 

_ fmbsnextc - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
RDOS 

_strnextc - MACRO 
_ wcsnextc - MACRO 


RDOS 
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mbsrtowcs, Jmbsrtowcs 


Synopsis: 


Safer C: 


Description: 


Returns: 


#include <wchar.h> 
size_ t mbsrtowcs( wchar_t *dst, 
const char **src, 
size_ t len, mbstate_ t *ps ); 

#include <mbstring.h> 

size_ t _ fmbsrtowcs ( wchar_ t_far *dst, 

const char_far *_far *src, 

size_ t len, mbstate_ t_far *ps ) ; 

The Safer C Library extension provides the mbsrtowcs_ s function which is a safer alternative to 
mbsrtowcs This newer mbsrtowcs_ s function is recommended to be used instead of the traditional 
"unsafe" mbsrtowcs function. 

The mbsrtowcs function converts a sequence of multibyte characters that begins in the shift state 
described by ps from the array indirectly pointed to by src into a sequence of corresponding wide 
characters, which, if dst is not a null pointer, are then stored into the array pointed to by dst. 

Conversion continues up to and including a terminating null character, but the terminating null wide 
character will not be stored. Conversion will stop earlier in two cases: when a sequence of bytes is 
reached that does not form a valid multibyte character, or (if dst is not a null pointer) when len codes 
have been stored into the array pointed to by dst. Each conversion takes place as if by a call to the 
mbrtowc function. 

If dst is not a null pointer, the pointer object pointed to by src will be assigned either a null pointer (if 
conversion stopped due to reaching a terminating null character) or the address just past the last 
multibyte character converted. If conversion stopped due to reaching a terminating null character and if 
dst is not a null pointer, the resulting state described will be the initial conversion state. 

The _ fmbsrtowcs function is a data model independent form of the mbsrtowcs function that accepts 
far pointer arguments. It is most useful in mixed memory model applications. 

The restartable multibyte/wide string conversion functions differ from the corresponding internal-state 
multibyte string functions ( mbstowcs and wcstombs) in that they have an extra argument, ps, of 
type pointer to mbstate_ t that points to an object that can completely describe the current conversion 
state of the associated multibyte character sequence. If ps is a null pointer, each function uses its own 
internal mbstate_ t object instead. You are guaranteed that no other function in the library calls these 
functions with a null pointer for ps. thereby ensuring the stability of the state. 

Also unlike their corresponding functions, the conversion source argument, src , has a pointer-to-pointer 
type. When the function is storing conversion results (that is, when dst is not a null pointer), the pointer 
object pointed to by this argument will be updated to reflect the amount of the source processed by that 
invocation. 

If the encoding is state-dependent, on entry each function takes the described conversion state (either 
internal or pointed to by ps) as current and then, if the destination pointer, dst, is not a null pointer, the 
conversion state described by the pointed-to object is altered as needed to track the shift state of the 
associated multibyte character sequence. For encodings without state dependency, the pointer to the 
mb st at e_ t argument is ignored. 

If the input string does not begin with a valid multibyte character, an encoding error occurs: The 
mbsrtowcs function stores the value of the macro EILSEQ in errno and returns (size_ t) -1, 
but the conversion state will be unchanged. Otherwise, it returns the number of multibyte characters 
successfully converted, which is the same as the number of array elements modified when dst is not a 
null pointer. 
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mbsrtowcs, Jmbsrtowcs 


See Also: 


Example: 


_ mbccmp,_ mbccpy,_ mbcicmp,_ mbcjistojms,_ mbc jmsto jis,_ mbclen^_ mbctohira, 
_ mbctokata,_ mbctolower^ mbctombb^ mbctoupperjnblen, mbrlen, mbrtowc, 
mbsrtowcs_ sjnbstowcs, mbstowcs_ sjnbtowc, btowc, wcrtomb, wcrtomb_ s, 
wcsrtombs, wcsrtombs_ s,wcstombs, wcstombs_ s,wctob, wctomb, wctomb_ s 

♦include <stdio.h> 

♦include <wchar.h> 

♦include <mbctype.h> 

♦include <errno.h> 

const char chars[] = { 

r r 

r 

r r 
• r 

'i', 

'A' , 


0x81, 

0x40, 

/* 

double-byte 

space */ 


0x82, 

0x60, 

/* 

double-byte 

A */ 


0x82, 

0xA6, 

/* 

double-byte 

Hiragana 

*/ 

0x83, 

0x42, 

/* 

double-byte 

Katakana 

*/ 

OxAl, 


/* 

single-byte 

Katakana 

punctuation */ 

0xA6, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxDF, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxEO, 

OxAl, 

/* 

double-byte 

Kanji */ 


0x00 






main () 





int 


i 

r 



size_ 

. t 

elements; 



const 

char 

★ 

src; 




wchar_ t wc[50]; 

mbstate_ t pstate; 

_ setmbcp( 932 ); 
src = chars; 

elements = mbsrtowcs( wc, &src, 50, Spstate ); 
if( errno == EILSEQ ) { 

printf ( "Error in multibyte character string\n" ); 
} else { 

for( i = 0; i < elements; i++ ) { 

printf( "%^6.4x\n", wc[i] ); 


} 

} 

produces the following: 
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mbsrtowcs, Jmbsrtowcs 


Classification: 


Systems: 


0x0020 
0x002e 
0x0031 
0x0041 
0x3000 
Oxff21 
0x3048 
0x30a3 
Oxff61 
Oxff66 
Oxff9f 
0x720d 

ISO C95 

_fmbsrtowcs is WATCOM 


mbsrtowcs - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, 
Linux, RDOS 

_ fmbsrtowcs - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
RDOS 
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mbsrtowcss, _fmbsrtowcs_s 


Synopsis: #def ine_STDC_ WANT_ LIB_ EXT1_1 

♦include <wchar.h> 

errno_ t mbsrtowcs_ s ( size_ t * restrict retval, 

wchar_t * restrict dst, rsize_t dstmax, 
const char ** restrict src, rsize_t len, 
mbstate_ t * restrict ps); 

errno_ t _ fmbsrtowcs_ s ( size_ t_far * restrict retval, 

wchar_ t_far * restrict dst, rsize_ t dstmax, 

const char _ far * _ far * restrict src, rsize 

_t len, 

mbstate_t _far * restrict ps); 

Constraints: If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and mbsrtowcs_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

None of retval , src , *src , or ps shall be null pointers. If dst is not a null pointer, then neither len nor 
dstmax shall be greater than RSI ZE_ MAX. If dst is a null pointer, then dstmax shall equal zero. If dst is 
not a null pointer, then dstmax shall not equal zero. If dst is not a null pointer and len is not less than 
dstmax .then a null character shall occur within the first dstmax multibyte characters of the array pointed 
to by *src. 

If there is a runtime-constraint violation, then mbsrtowcs_ s does the following. If retval is not a null 
pointer, then mbsrtowcs_ s sets *retval to (size_t)(-l). If dst is not a null pointer and dstmax is 
greater than zero and less than RSIZE_ MAX , thenmbsrtowcs_ s sets dst[0] to the null wide 
character. 

Description: The mbsrtowcs_ s function converts a sequence of multibyte characters that begins in the conversion 
state described by the object pointed to by ps, from the array indirectly pointed to by src into a sequence 
of corresponding wide characters. If dst is not a null pointer, the converted characters are stored into 
the array pointed to by dst. Conversion continues up to and including a terminating null character, 
which is also stored. 

Conversion stops earlier in two cases: when a sequence of bytes is encountered that does not form a 
valid multibyte character, or (if dst is not a null pointer) when len wide characters have been stored into 
the array pointed to by dst. If dst is not a null pointer and no null wide character was stored into the 
array pointed to by dst, then dst [len ] is set to the null wide character. Each conversion takes place as if 
by a call to the mbrtowc function. 

If dst is not a null pointer, the pointer object pointed to by src is assigned either a null pointer (if 
conversion stopped due to reaching a terminating null character) or the address just past the last 
multibyte character converted (if any). If conversion stopped due to reaching a terminating null 
character and if dst is not a null pointer, the resulting state described is the initial conversion state. 

Regardless of whether dst is or is not a null pointer, if the input conversion encounters a sequence of 
bytes that do not form a valid multibyte character, an encoding error occurs: the mbsrtowcs_ s 
function stores the value (size_t)(-l) into *retval and the conversion state is unspecified. Otherwise, the 
mbsrtowcs_ s function stores into *retval the number of multibyte characters successfully converted, 
not including the terminating null character (if any). 

All elements following the terminating null wide character (if any) written by mbsrtowcs_ s in the 
array of dstmax wide characters pointed to by dst take unspecified values when mbsrtowcs_ s returns. 

If copying takes place between objects that overlap, the objects take on unspecified values. 
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mbsrtowcss, _fmbsrtowcs_s 


The function is a data model independent form of the mbsrtowcs_s function that accepts far pointer 
arguments. It is most useful in mixed memory model applications. 

Returns: The mbsrtowcs_ s function returns zero if there was no runtime-constraint violation. Otherwise, a 

non-zero value is returned. 

See Also: _ mbccmp,_ mbccpy,_ mbcicmp^. mbc jisto jms,_ mbc jmsto jis,_ mbclen,_ mbctohira, 

_ mbctokata,_ mbctolower^ mbctombb,_ mbctoupperjnblen, mbrlen, mbrtowc, 
mbsrtowcs, mbstowcs, mbstowcs_ s,mbtowc, btowc, wcrtomb, wcrtomb_ s.wcsrtombs, 
wcsrtombs_ s,wcstombs, wcstombs_ s,wctob, wctomb, wctomb_ s 

Example: #define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <wchar.h> 

♦include <mbctype.h> 

♦include <errno.h> 

const char chars [ ] = { 

r r 

r 

r r 
• r 

'A' , 

0x81,0x40, /* double-byte space */ 

0x82,0x60, /* double-byte A */ 

0x82,0xA6, /* double-byte Hiragana */ 

0x83,0x42, /* double-byte Katakana */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6, /* single-byte Katakana alphabetic */ 

OxDF, /* single-byte Katakana alphabetic */ 

0xE0,0xAl, /* double-byte Kanji */ 

0x00 

} ; 

int main() 

{ 

int i; 

size_t retval; 

const char *src; 
wchar_ t wc[50]; 

mbstate_ t pstate; 

errno_ t rc; 

_ setmbcp( 932 ) ; 
src = chars; 

rc = mbsrtowcs( Sretval, wc, 50, &src, sizeof(chars), Spstate ); 
if( rc != 0 ) { 

printf ( "Error in multibyte character string\n" ); 

} else { 

for( i = 0; i < retval; i++ ) { 

printf( "%#6.4x\n", wc[i] ); 

} 

} 

return ( 0 ); 

} 

Classification: TR 24731 
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mbsrtowcss, _fmbsrtowcs_s 


Systems: 


_fmbsrtowcs_s is WATCOM 

mbsrtowcs_ s - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
Linux, RDOS 

_ fmbsrtowcs_ s - DOS, Windows, Win386, Win32, OS/2 1.x (all), OS/2-32, 
RDOS 
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mbstowcs, Jmbstowcs 


Synopsis: 

Safer C: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdlib.h> 

size_ t mbstowcs ( wchar_ t *pwcs, const char *s, size_ t n ); 

♦include <mbstring.h> 

size_ t _ fmbstowcs( const wchar_ t _far *pwcs, 

char _ far *s, 

size_ t n ) ; 

The Safer C Library extension provides the mbstowcs_ s function which is a safer alternative to 
mbstowcs This newer mbstowcs_ s function is recommended to be used instead of the traditional 
"unsafe" mbstowcs function. 

The mbstowcs function converts a sequence of multibyte characters pointed to by 5 into their 
corresponding wide character codes and stores not more than n codes into the array pointed to by pwcs. 
The mbstowcs function does not convert any multibyte characters beyond the null character. At most 
n elements of the array pointed to by pwcs will be modified. 

The _ fmbstowcs function is a data model independent form of the mbstowcs function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

If an invalid multibyte character is encountered, the mbstowcs function returns (size_ t) -1. 
Otherwise, the mbstowcs function returns the number of array elements modified, not including the 
terminating zero code if present. 

mbstowcs_ sjnblen, mbtowc, wctomb, wctomb_ s,wcstombs, wcstombs_ s 

♦include <stdio.h> 

♦include <stdlib.h> 

void main() 

{ 

char *wc = "string"; 

wchar_ t wbuffer[50]; 
int i, len; 

len = mbstowcs( wbuffer, wc, 50 ); 
if( len != -1 ) { 

wbuffer[len] = '\0'; 

printf( "%s(%d)\n", wc, len ); 

for( i = 0; i < len; i++ ) 

printf ( "/%4.4x", wbuffer [i] ); 

printf( " \n" ); 

} 

} 

produces the following: 
string(6) 

/0073/0074/0072/0069/006e/0067 

ISO C95 

_fmbstowcs is WATCOM 

mbstowcs - All, Linux, RDOS, Netware 
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mbstowcs, Jmbstowcs 


_ fmbstowcs - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
RDOS 
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mbstowcs^s, _fmbstowcs_s 


Synopsis: 


Constraints: 


Description: 


Returns: 


♦ define_ STDC_ WANT_ LIB_ EXT1_1 

♦include <stdlib.h> 

errno_ t mbstowcs_ s ( size_ t * restrict retval, 

wchar_t * restrict dst, 
rsize_ t dstmax, 

const char * restrict src, rsize_ t len) ; 

errno_ t _ fmbstowcs_ s ( size_ t_far * restrict retval, 

wchar_ t_far * restrict dst, 

rsize_ t dstmax, 

const char_far * restrict src, rsize_ t len) ; 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and mbstowcs_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither retval nor src shall be a null pointer. If dst is not a null pointer, then neither len nor dstmax 
shall be greater than RSI ZE_ MAX. If dst is a null pointer, then dstmax shall equal zero. If dst is not a 
null pointer, then dstmax shall not equal zero. If dst is not a null pointer and len is not less than dstmax, 
then a null character shall occur within the first dstmax multibyte characters of the array pointed to by 
src. 

If there is a runtime-constraint violation, then mbstowcs_ s does the following. If retval is not a null 
pointer, then mbstowcs_ s sets :e retval to (size_t)(-l). If dst is not a null pointer and dstmax is greater 
than zero and less than RSIZE_ MAX, thenmbstowcs_ s sets dst[0] to the null wide character. 

The mbstowcs_ s function converts a sequence of multibyte characters that begins in the initial shift 
state from the array pointed to by src into a sequence of corresponding wide characters. If dst is not a 
null pointer, the converted characters are stored into the array pointed to by dst. 

Conversion continues up to and including a terminating null character, which is also stored. Conversion 
stops earlier in two cases: when a sequence of bytes is encountered that does not form a valid multibyte 
character, or (if dst is not a null pointer) when len wide characters have been stored into the array 
pointed to by dst. If dst is not a null pointer and no null wide character was stored into the array pointed 
to by dst, then dst [len] is set to the null wide character. Each conversion takes place as if by a call to 
the mbrtowc function. 

Regardless of whether dst is or is not a null pointer, if the input conversion encounters a sequence of 
bytes that do not form a valid multibyte character, an encoding error occurs: the mbstowcs_ s 
function stores the value (size_t)(-l) into *retval. Otherwise, the mbstowcs_ s function stores into 
*retval the number of multibyte characters successfully converted, not including the terminating null 
character (if any). 

All elements following the terminating null wide character (if any) written by mbstowcs_ s in the 
array of dstmax wide characters pointed to by dst take unspecified values when mbstowcs_ s returns. 

If copying takes place between objects that overlap, the objects take on unspecified values. 

The function is a data model independent form of the mbstowcs_s function that accepts far pointer 
arguments. It is most useful in mixed memory model applications. 

The mbstowcs_ s function returns zero if there was no runtime-constraint violation. Otherwise, a 
non-zero value is returned. 
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mbstowcs_s, _fmbstowcs_s 


See Also: 
Example: 


Classification: 

Systems: 


mbstowcs, mblen, mbtowc, wctomb, wctomb_ s,wcstombs, wcstombs_ s 

♦ define_STDC_ WANT_ LIB_ EXT1 1 

♦include <stdio.h> 

♦include <stdlib.h> 

int main() 

{ 

char *wc = "string"; 

wchar_ t wbuffer[50]; 
int i; 

errno_ t rc; 
size_ t retval; 

rc = mbstowcs_ s( Sretval, wbuffer, 50, wc, 10); 
if( rc == 0 ) { 

wbuffer[retval] = L'\0'; 
printf( "%s(%d)\n", wc, retval ); 
for( i = 0; i < retval; i++ ) 
printf ( "/%4.4x", wbuffer[i] ); 

printf ( "\n" ); 

} 

return ( 0 ); 

} 

produces the following: 
string(6) 

/0073/0074/0072/0069/006e/0067 

TR 24731 

_fmbstowcs_s is WATCOM 

mbstowcs_ s - All, Linux, RDOS, Netware 

_ fmbstowcs_ s - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, 
RDOS 
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Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


mbterm, _fmbterm 


♦include <mbstring.h> 

int _ mbterm( const unsigned char *ch ); 

int _ fmbterm( const unsigned char _ far *ch ); 

The _ mbterm function determines if the next multibyte character in the string pointed to by ch is a null 
character or a valid lead byte followed by a null character. 

The _ fmbterm function is a data model independent form of the _mbterm function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The _ mbterm function returns 1 if the multibyte character pointed to by ch is a null character. The 
_ mbterm function returns 2 if the multibyte character pointed to by ch is a valid lead byte character 
followed by a null character. Otherwise, the _ mbterm function returns 0. 

_ mbccmp,_ mbccpy,_ mbcicmp,_ mbcjistojms,_ mbc jmsto jis^ mbclen^_ mbctohira, 
_ mbctokata^ mbctolower^ mbctombb^ mbctoupperjnblen, mbrlen, mbrtowc, 
mbsrtowcs, mbsrtowcs_ sjnbstowcs, mbstowcs_ s,mbtowc, btowc, wcrtomb, 
wcrtomb_ s,wcsrtombs, wcsrtombs_ s,wcstombs, wcstombs_ s,wctob, wctomb, 
wctomb_ s 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

const unsigned char chars[] = { 

r r 

r 

r r 
• r 

'i' , 

'A' , 

0x81,0x40, /* double-byte space */ 

0x82,0x00 /* invalid double-byte */ 

} ; 


♦define SIZE sizeof( chars ) / sizeof( unsigned char ) 

void main() 

{ 

int i; 


} 


_ setmbcp( 932 ) ; 

for( i = 0; i < SIZE; i++ ) { 

printf( "0x%2.2x %d\n", chars[i], 
_ mbterm( &chars[i] ) ); 


} 


produces the following: 
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mbterm, Jmbterm 


0x20 0 
0x2e 0 
0x31 0 
0x41 0 
0x81 0 
0x40 0 
0x82 2 
0x00 1 


Classification: WATCOM 


Systems: 


mbterm - DOS, Windows, Win386, Win32, 
fmbterm - DOS, Windows, Win386, Win32 


OS/2 1.x(all), 
OS/2 1.x(all) 


OS/2-32, RDOS 
OS/2-32, RDOS 
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mbtowc, Jmbtowc 


Synopsis: 

Description: 


Returns: 


See Also: 
Example: 


♦include <stdlib.h> 

int mbtowc ( wchar_ t *pwc, const char *s, size_ t n ); 

♦include <mbstring.h> 

int _ fmbtowc ( wchar_ t_far *pwc, 

const char _ far *s, 

size_ t n ) ; 

The mbtowc function converts a single multibyte character pointed to by s into the wide character code 
that corresponds to that multibyte character. The code for the null character is zero. If the multibyte 
character is valid and pwc is not a NULL pointer, the code is stored in the object pointed to by pwc. At 
most n bytes of the array pointed to by 5 will be examined. 

The mbtowc function does not examine more than MB_ CUR_ MAX bytes. 

The function is a data model independent form of the mbtowc function that accepts far pointer 
arguments. It is most useful in mixed memory model applications. 

If .5 is a NULL pointer, the mbtowc function returns zero if multibyte character encodings are not state 
dependent, and non-zero otherwise. If s is not a NULL pointer, the mbtowc function returns: 

Value Meaning 

0 if ,v points to the null character 

len the number of bytes that comprise the multibyte character (if the next n or fewer bytes form a 

valid multibyte character) 

-1 if the next n bytes do not form a valid multibyte character 

mblen, wctomb, mbstowcs, wcstombs 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <mbctype.h> 

void main() 

{ 

char *wc = "string"; 
wchar_ t wbuffer[10]; 
int i, len; 

_ setmbcp( 932 ); 

printf ( "Character encodings are %sstate dependent\n", 

( mbtowc( wbuffer, NULL, 0 ) ) 

? "" : "not " ); 

len = mbtowc ( wbuffer, wc, MB_ CUR_ MAX ) ; 

wbuffer[len] = '\0'; 

printf ( "%s(%d)\n", wc, len ); 

for( i = 0; i < len; i++ ) 

printf ( "/%4.4x", wbuffer [i] ); 

printf ( "\n" ); 

} 
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mbtowc, Jmbtowc 


Classification: 


Systems: 


produces the following: 

Character encodings are not state dependent 
string(1) 

/0073 

ISOC 

_fmbtowc is WATCOM 

mbtowc - All, Linux, RDOS, Netware 

_ fmbtowc - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 


RDOS 
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Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


mbvtop, Jmbvtop 


♦include <mbstring.h> 

unsigned char *_ mbvtop ( unsigned int ch, 

unsigned char *addr ); 

unsigned char _far *_ fmbvtop( unsigned int ch, 

unsigned char _ far *addr ); 

The _ mbvtop function stores the multibyte character ch into the string pointed to by addr. 

The _ f mbvtop function is a data model independent form of the _mbvtop function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The _ mbvtop function returns the value of the argument addr. 

_ mbccmp,_ mbccpy,_ mbcicmp,_ mbcjistojms,_ mbc jmsto jis,_ mbclen,_ mbctohira, 
_ mbctokata,_ mbctolower^ mbctombb,_ mbctoupperjnblen, mbrlen, mbrtowc, 
mbsrtowcs, mbsrtowcs_ sjnbstowcs, mbstowcs_ s,mbtowc, btowc, wcrtomb, 
wcrtomb_ s,wcsrtombs, wcsrtombs_ s.wcstombs, wcstombs_ s,wctob, wctomb, 
wctomb_ s 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 


void main() 

{ 

unsigned char string[10]; 
unsigned char *p; 
int i; 


_ setmbcp( 
p = string; 
_ mbvtop( 
p++; 

_ mbvtop( 

p++; 

_ mbvtop( 
p++; 

_mbvtop( 

p += 2; 

_ mbvtop( 

p += 2; 

_ mbvtop( 

p += 2; 

_ mbvtop( 


932 ) ; 

P ) ; 
p ) ; 
'A' , p ) ; 
0x8140, p ) 
0x8260, p ) 
0x82A6, p ) 

'\0', p ); 


for( i = 0; i < 10; i++ ) 

printf( "%2.2x ", string[i] ); 
printf( "\n" ); 


produces the following: 

2e 31 41 81 40 82 60 82 a6 00 
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mbvtop, Jmbvtop 


Classification: WATCOM 

Systems: _ mbvtop - DOS, Windows, Win386, Win32, OS/2 1.x (all), OS/2-32, RDOS 

_ fmbvtop - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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memavl 


Synopsis: #include <malloc.h> 

size_ t _ memavl ( void ) ; 

Description: The _ memavl function returns the number of bytes of memory available for dynamic memory 

allocation in the near heap (the default data segment). In the tiny, small and medium memory models, 
the default data segment is only extended as needed to satisfy requests for memory allocation. 
Therefore, you will need to call _ nheapgrow in these memory models before calling_ memavl in 
order to get a meaningful result. 

The number returned by _ memavl may not represent a single contiguous block of memory. Use the 
_ memmax function to find the largest contiguous block of memory that can be allocated. 

Returns: The _ memavl function returns the number of bytes of memory available for dynamic memory 

allocation in the near heap (the default data segment). 

See Also: calloc Functions, _ f reect^_ memmax^_ heapgrow Functions,malloc Functions, realloc 

Functions 

Example: #include <stdio.h> 

♦include <malloc.h> 

void main() 

{ 

char *p; 

char *fmt = "Memory available = %u\n"; 

printf ( fmt, _ memavl() ); 

_ nheapgrow(); 
printf ( fmt, _ memavl() ); 

p = (char *) malloc ( 2000 ); 
printf ( fmt, _ memavl () ); 

} 

produces the following: 

Memory available = 0 
Memory available = 62732 
Memory available = 60730 

Classification: WATCOM 

Systems: All, Linux, RDOS 
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memccpy, Jmemccpy 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <string.h> 

void *memccpy( void *dest, const void *src, 
int c, size_ t cnt ); 

void_far *_ fmemccpy ( void_far *dest, 

const void _ far *src, 

int c, size_ t cnt ); 

The memccpy function copies bytes from src to dest up to and including the first occurrence of the 
character c or until cnt bytes have been copied, whichever comes first. 

The _ fmemccpy function is a data model independent form of the memccpy function. It accepts far 
pointer arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The memccpy function returns a pointer to the byte in dest following the character c if one is found and 
copied, otherwise it returns NULL. 

memcpy, memmove, memset 

#include <stdio.h> 

♦include <string.h> 

char *msg = "This is the string: not copied"; 

void main() 

1 

auto char buffer[80]; 

memset( buffer, '\0', 80 ); 
memccpy! buffer, msg, 80 ); 

printf ( "%s\n", buffer ); 

} 

produces the following: 

This is the string: 

WATCOM 

memccpy - All, Linux, RDOS, Netware 
_ fmemccpy - All, Linux, RDOS 
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memchr, _fmemchr, wmemchr 


Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <string.h> 

void *memchr( const void *buf, int ch, size_t length ); 

void_far *_ fmemchr ( const void_far *buf, 

int ch, 

size_ t length ) ; 

♦include <wchar.h> 

wchar_ t *wmemchr( const wchar_ t *buf, wchar_ t ch, size_ t length ); 

The memchr function locates the first occurrence of ch (converted to an unsigned char) in the first 
length characters of the object pointed to by buf 

The _ fmemchr function is a data model independent form of the memchr function. It accepts far 
pointer arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The wmemchr function is a wide-character version of memchr that operates with wide-character 
strings. The argument length is interpreted to mean the number of wide characters. 

The memchr function returns a pointer to the located character, or NULL if the character does not occur 
in the object. 

memcmp, memcpy, memicmp, memset 

♦include <stdio.h> 

♦include <string.h> 

void main( void ) 

{ 

char buffer [80]; 
char *where; 

strcpy( buffer, "video x-rays" ); 

where = (char *)memchr( buffer, 'x', 6 ); 

if( where == NULL ) 

printf ( "'x' not foundin' 1 ); 

else 

printf ( "%s\n", where ); 
where = (char *)memchr( buffer, ' r', 9 ); 
if( where == NULL ) 

printf ( ”'r r not foundin'' ); 

else 

printf ( "%sln", where ); 

} 

ISOC 

_fmemchr is WATCOM 
wmemchr is ISO C95 

memchr - All, Linux, RDOS, Netware 
_ fmemchr - All, Linux, RDOS 
wmemchr - All, Linux 
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memcmp, Jmemcmp, wmemcmp 


Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <string.h> 
int memcmp( const void *sl, 
const void *s2, 
size_ t length ); 

int _ fmemcmp ( const void_far *sl, 

const void _ far *s2, 

size_ t length ) ; 

♦include <wchar.h> 
int wmemcmp( const wchar_ t *sl, 
const wchar_t *s2, 
size_ t length ); 

The memcmp function compares the first length characters of the object pointed to by si to the object 
pointed to by s2. 

The _ fmemcmp function is a data model independent form of the memcmp function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The wmemcmp function is a wide-character version of memcmp that operates with wide-character 
strings. The argument length is interpreted to mean the number of wide characters. 

The memcmp function returns an integer less than, equal to, or greater than zero, indicating that the 
object pointed to by si is less than, equal to, or greater than the object pointed to by s2. 

memchr, memcpy, memicmp, memset 

♦include <stdio.h> 

♦include <string.h> 

void main( void ) 

{ 

auto char buffer[80]; 

strcpy( buffer, "world" ); 
if( memcmp( buffer, "Hello ", 6 ) < 0 ) { 

printf( "Less than\n" ) ; 

} 

} 

ISOC 

_fmemcmp is WATCOM 
wmemcmp is ISO C95 

memcmp - All, Linux, RDOS, Netware 
_ fmemcmp - All, Linux, RDOS 
wmemcmp - All, Linux 
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memcpy, Jmemcpy, wmemcpy 


Synopsis: 


Safer C: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <string.h> 
void *memcpy( void *dst, 

const void *src, 
size_ t length ) ; 

void_far *_ fmemcpy ( void_far *dst, 

const void _ far *src, 

size_ t length ) ; 

♦include <wchar.h> 

wchar_ t *wmemcpy ( wchar_ t *dst, 

const wchar_ t *src, 
size_ t length ); 

The Safer C Library extension provides the memcpy_ s function which is a safer alternative to 
memcpy This newer memcpy_ s function is recommended to be used instead of the traditional "unsafe" 
memcpy function. 

The memcpy function copies length characters from the buffer pointed to by src into the buffer pointed 
to by dst. Copying of overlapping objects is not guaranteed to work properly. See the memmove 
function if you wish to copy objects that overlap. 

The _ fmemcpy function is a data model independent form of the memcpy function. It accepts far 
pointer arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The wmemcpy function is a wide-character version of memcpy that operates with wide-character 
strings. The argument length is interpreted to mean the number of wide characters. 

The original value of dst is returned. 

memchr, memcmp, memicmp, memmove, memset, memcpy_ s,memmove_ s 

♦include <stdio.h> 

♦include <string.h> 

void main( void ) 

{ 

auto char buffer[80]; 

memcpy( buffer, "Hello", 5 ); 

buffer [5] = '\0'; 

printf ( "%s\n", buffer ); 

1 

ISOC 

_fmemcpy is WATCOM 
wmemcpy is ISO C95 

memcpy - All, Linux, RDOS, Netware 
_ fmemcpy - All, Linux, RDOS 
wmemcpy - All, Linux 
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memcpy_s, wmemcpy_s 


Synopsis: 


Constraints: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <string.h> 

errno_ t memcpy_ s ( void * restrict si, 

rsize_ t slmax, 

const void * restrict s2, 

rsize_ t n ) ; 

♦include <wchar.h> 

errno_ t wmemcpy_ s ( wchar_ t * restrict si, 

rsize_ t slmax, 

const wchar_ t * restrict s2, 

size_ t n ) ; 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and memcpy_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither si nor s2 shall be a null pointer. Neither slmax nor n shall be greater than RSIZE_ MAX. n 
shall not be greater than slmax. Copying shall not take place between objects that overlap. 

If there is a runtime-constraint violation, the memcpy_ s function stores zeros in the first slmax 
characters of the object pointed to by si if si is not a null pointer and slmax is not greater than 
RSI ZE_ MAX. 

The memcpy_ s function copies n characters from the buffer pointed to by s2 into the buffer pointed to 
by si. Copying between overlapping objects is not allowed. See the memmove_ s function if you wish 
to copy objects that overlap. 

The wmemcpy_ s function is a wide-character version ofmemcpy_ s that operates with wide-character 
strings. The arguments slmax and n are interpreted to mean the number of wide characters. 

The memcpy_ s function returns zero if there was no runtime-constraint violation. Otherwise, a 
non-zero value is returned. 

memcpy, memchr, memcmp, memcpy, memicmp, memmove, memset, memmove_ s 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <string.h> 

void main( void ) 

{ 

char buffer[80]; 

memcpy_ s ( buffer, sizeof( buffer ), "Hello", 5 ); 

buffer[5] = '\0'; 

printf( "%s\n", buffer ); 

} 

TR 24731 

memcpy_ s - All, Linux, RDOS, Netware 
wmemcpy_ s - All, Linux 
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Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


memicmp, _memicmp, Jmemicmp 


♦include <string.h> 
int memicmp( const void *sl, 
const void *s2, 
size_ t length ); 
int _ memicmp( const void *sl, 
const void *s2, 
size_ t length ) ; 

int _ fmemicmp ( const void_far *sl, 

const void _ far *s2, 

size_ t length ); 

The memicmp function compares, with case insensitivity (upper- and lowercase characters are 
equivalent), the first length characters of the object pointed to by si to the object pointed to by s2. 

The _ fmemicmp function is a data model independent form of the memicmp function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The _ memicmp function is identical tomemicmp. Use _ memicmp for ANSI naming conventions. 

The memicmp function returns an integer less than, equal to, or greater than zero, indicating that the 
object pointed to by si is less than, equal to, or greater than the object pointed to by s2. 

memchr, memcmp, memcpy, memset 

♦include <stdio.h> 

♦include <string.h> 

void main() 

{ 

char buffer [80]; 

if( memicmp( buffer, "Hello", 5 ) < 0 ) { 

printf( "Less than\n" ); 

} 

} 

WATCOM 

_memicmp conforms to ANSI naming conventions 
memicmp - All, Linux, RDOS, Netware 

_ memicmp - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 

Linux, RDOS 

_ fmemicmp - All, Linux, RDOS 
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memmax 


Synopsis: #include <malloc.h> 

size_ t _ memmax ( void ); 

Description: The _ memmax function returns the size of the largest contiguous block of memory available for 

dynamic memory allocation in the near heap (the default data segment). In the tiny, small and medium 
memory models, the default data segment is only extended as needed to satisfy requests for memory 
allocation. Therefore, you will need to call _ nheapgrow in these memory models before calling 
_memmax in order to get a meaningful result. 

Returns: The _ memmax function returns the size of the largest contiguous block of memory available for 

dynamic memory allocation in the near heap. If 0 is returned, then there is no more memory available 
in the near heap. 

See Also: calloc, _ freect,_ memavl^_ heapgrowjnalloc 

Example: ((include <stdio.h> 

((include <malloc.h> 

void main() 

{ 

char *p; 
size_ t size; 

size = _ memmax () ; 

printf( "Maximum memory available is %u\n", size ); 

_ nheapgrow(); 
size = _ memmax () ; 

printf( "Maximum memory available is %u\n", size ); 
p = (char *) _ nmalloc ( size ); 
size = _ memmax () ; 

printf( "Maximum memory available is %u\n", size ); 

} 

produces the following: 

Maximum memory available is 0 
Maximum memory available is 62700 
Maximum memory available is 0 

Classification: WATCOM 

Systems: All, Linux, RDOS 
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Synopsis: 


Safer C: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


memmove, Jmemmove, wmemmove 


#include <string.h> 
void *memmove( void *dst, 

const void *src, 
size_ t length ); 

void_far *_ fmemmove ( void_far *dst, 

const void _ far *src, 

size_ t length ); 

♦include <wchar.h> 

wchar_ t *wmemmove ( wchar_ t *dst, 

const wchar_ t *src, 
size_ t length ); 

The Safer C Library extension provides the memmove_ s function which is a safer alternative to 
memmove This newer memmove_ s function is recommended to be used instead of the traditional 
"unsafe" memmove function. 

The memmove function copies length characters from the buffer pointed to by src to the buffer pointed 
to by dst. Copying of overlapping objects will take place properly. See the memcpy function to copy 
objects that do not overlap. 

The _ fmemmove function is a data model independent form of the memmove function. It accepts far 
pointer arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The wmemmove function is a wide-character version of memmove that operates with wide-character 
strings. The argument length is interpreted to mean the number of wide characters. 

The memmove function returns dst. 

memchr, memcmp, memcpy, memicmp, memset, memmove_ s,memcpy_ s 
♦include <string.h> 

void main( void ) 

{ 

char buffer[80]; 

memmove( buffer + 1, buffer, 79 ); 
buffer[0] = '*'; 

} 

ISOC 

_fmemmove is WATCOM 
wmemmove is ISO C95 

memmove - All, Linux, RDOS, Netware 
_ fmemmove - All, Linux, RDOS 
wmemmove - All, Linux 
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memmove_ 

Synopsis: 


Constraints: 


Description: 


Returns: 

See Also: 
Example: 


s, wmemmove_s 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <string.h> 

errno_ t memmove_ s ( void * restrict si, 

rsize_ t slmax, 

const void * restrict s2, 

rsize_ t n ) ; 

♦include <wchar.h> 

errno_ t wmemmove_ s ( wchar_ t * restrict si, 

rsize_ t slmax, 

const wchar_ t * restrict s2, 

size_ t n ) ; 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and memmove_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither si nor s2 shall be a null pointer. Neither slmax nor n shall be greater than RSIZE_MAX. n shall 
not be greater than slmax. 

If there is a runtime-constraint violation, the memmove_ s function stores zeros in the first slmax 
characters of the object pointed to by si if si is not a null pointer and slmax is not greater than 
RSIZE_MAX. 

The memmove_ s function copies n characters from the buffer pointed to by s2 into the buffer pointed 
to by si. This copying takes place as if the n characters from the buffer pointed to by s2 are first copied 
into a temporary array of n characters that does not overlap the objects pointed to by si or s2 ,and then 
the n characters from the temporary array are copied into the object pointed to by si. 

See the memcpy_s function if you wish to copy objects that do not overlap. 

The wmemmove_ s function is a wide-character version ofmemmove_ s that operates with 
wide-character strings. The arguments slmax and n are interpreted to mean the number of wide 
characters. 

The memmove_ s function returns zero if there was no runtime-constraint violation. Otherwise, a 
non-zero value is returned. 

memchr, memcmp, memcpy, memicmp, memmove, memset, memcpy_ s 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <string.h> 

void main( void ) 

{ 

char buffer[80] = "0123456789"; 

memmove_ s ( buffer + 1, sizeof( buffer ), buffer, 79 ); 
buffer[0] = ' 
printf( buffer ) ; 

} 

produces the following: 

*0123456789 
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memmove^s, wmemmove_s 


Classification: 

Systems: 


TR 24731 

memmove_ s - All, Linux, RDOS, 
wmemmove_ s - All 


Netware 
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m_empty 


Synopsis: 

Description: 


Returns: 
See Also: 

Example: 


#include <mmintrin.h> 
void _ m_ empty (void) ; 

The _ m_ empty function empties the multimedia state. The values in the Multimedia Tag Word (TW) 
are set to empty (i.e., all ones). This will indicate that no Multimedia registers are in use. 

This function is useful for applications that mix floating-point (FP) instructions with multimedia 
instructions. Intel maps the multimedia registers onto the floating-point registers. For this reason, you 
are discouraged from intermixing MM code and FP code. The recommended way to write an 
application with FP instructions and MM instructions is: 

• Split the FP code and MM code into two separate instruction streams such that each stream 
contains only instructions of one type. 

• Do not rely on the contents of FP/MM registers across transitions from one stream to the other. 

• Leave the MM state empty at the end of an MM stream using the _ m_ empty function. 

• Similarly, leave the FP stack empty at the end of an FP stream. 

The _ m_ empty function does not return a value. 

_ m_ from_ int.,m_ to_ int.,m_ packsswbj, m_ paddb^. m_ pancL m_ pcmpeqb, 

_ m_ pmaddwck. m_ psllw^ m_ psraw^ m_ psrlw^ m_ psubbj_ m_ punpckhbw 

#include <stdio.h> 

♦include <mmintrin.h> 

long featureflags( void ) ; 

♦pragma aux featureflags = \ 


".586" \ 
"mov eax,1" \ 
"cpuid" \ 
"mov eax,edx" \ 


modify [eax ebx ecx edx] 

♦ define MM_ EXTENSION 0x00800000 

void main( void ) 

{ 

if( featureflags () & MM_ EXTENSION ) { 

/* 

sequence of code that uses Multimedia functions 


*/ 

_ m_ empty () ; 

} 
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Classification: 

Systems: 


m_empty 


/* 

sequence of code that uses floating-point 


*/ 

} 

Intel 

MACRO 
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memset, Jmemset, wmemset 


Synopsis: 


Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <string.h> 

void *memset( void *dst, int c, size_ t length ); 

void_far *_ fmemset ( void_far *dst, int c, 

size_ t length ) ; 
wchar_ t *wmemset ( wchar_ t *dst, 

wchar_ t c, 
size_ t length ); 

The memset function fills the first length characters of the object pointed to by dst with the value c. 

The _ fmemset function is a data model independent form of the memset function. It accepts far 
pointer arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The wmemset function is a wide-character version of memset that operates with wide-character 
strings. The argument length is interpreted to mean the number of wide characters. 

The memset function returns the pointer dst. 

memchr, memcmp, memcpy, memicmp, memmove 

♦include <string.h> 

void main( void ) 

{ 

char buffer[80]; 

memset( buffer, ' =', 80 ); 

} 

ISOC 

_fmemset is WATCOM 
wmemset is ISO C95 

memset - All, Linux, RDOS, Netware 
_ fmemset - All, Linux, RDOS 
wmemset - All, Linux 
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Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


m_from_int 


♦include <mmintrin.h> 

_m64 _ m_ from_ int (int i) ; 

The _ m_ f rom_ int function forms a 64-bit MM value from an unsigned 32-bit integer value. 

The 64-bit result of loading MMO with an unsigned 32-bit integer value is returned. 

_ m_ empty^. m_ to_ int,m_ packsswbj, m_ paddb^ m_ pancL m_ empty^. m_ pcmpeqb, 
_ m_ pmaddwcL m_ psllw^_ m_ psraw^_ m_ psrlw^ m_ empty^, m_ psubb*. m_ punpckhbw 

♦include <stdio.h> 

♦include <mmintrin.h> 

_ m64 a; 

int k = 0xFlF2F3F4; 

void main() 

{ 

a = _ m_ from_ int ( k ) ; 

printf ( "int=%8.81x m=%8.81x%8.81x\n", 
k, a32[1], a32[0] ); 


} 

produces the following: 

int=fIf2f3f4 m=00000000flf2f3f4 

Intel 

MACRO 
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mm 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdlib.h> 

♦define min(a,b) (((a) < (b)) ? (a) : (b)) 

The min macro will evaluate to be the lesser of two values. It is implemented as follows. 

♦define min(a,b) (((a) < (b)) ? (a) : (b)) 

The min macro will evaluate to the smaller of the two values passed, 
max 

♦include <stdio.h> 

♦include <stdlib.h> 

void main() 

{ 

int a; 

/* 

* The following line will set the variable "a" to 1 

* since 10 is greater than 1. 

*/ 

a = min( 1, 10 ); 

printf ( "The value is: %d\n", a ); 


WATCOM 

All, Linux, RDOS, Netware 
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mkdir, _mkdir, _wmkdir 


Synopsis: #include <sys/types .h> 

♦include <direct.h> 

int mkdir( const char *path ); 

int _ mkdir( const char *path ); 

int _ wmkdir ( const wchar_ t *path ) ; 

Description: The mkdir function creates a new subdirectory with name path. The path can be either relative to the 
current working directory or it can be an absolute path name. 

The _ mkdir function is identical tomkdir. Use _ mkdir for ANSI naming conventions. 

The _ wmkdir function is a wide-character version ofmkdir that operates with wide-character strings. 
Returns: The mkdir function returns zero if successful, and a non-zero value otherwise. 

Errors: When an error has occurred, errno contains a value indicating the type of error that has been detected. 

Constant Meaning 

EACCES Search permission is denied for a component of path or write permission is denied 

on the parent directory of the directory to be created. 

EEXIST The named file exists. 

ENOENT The specified path does not exist or path is an empty string. 

See Also: chdir, chmod, getcwd, rmdir, stat, umask 

Example: To make a new directory called \watcom on drive C : 

♦include <sys/types.h> 

♦include <direct.h> 

void main( void ) 

{ 

mkdir( "c:\\watcom" ); 

} 

Note the use of two adjacent backslash characters (\) within character-string constants to signify a single 
backslash. 

Classification: POSIX 1003.1 

_mkdir conforms to ANSI naming conventions 
_wmkdir is WATCOM 

Systems: mkdir - All, Linux, RDOS, Netware 

_ mkdir - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ wmkdir - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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MK FP 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <i86.h> 

void_far *MK_ FP ( unsigned int segment, 

unsigned int offset ); 

The MK_ FP macro can be used to obtain the far pointer value given by the segment segment value and 
the offset offset value. These values may be obtained by using the FP_ SEG andFP_ OFF macros. 

The macro returns a far pointer. 

FP_ OFF,FP_ SEG,segread 

♦include <i86.h> 

♦include <stdio.h> 

void main() 

{ 

unsigned short_far *bios_ prtr_ port_ 1; 

bios_ prtr_ port_ 1 = 

(unsigned short_far *) MK_ FP ( 0x40, 0x8 ); 

printf ( "Port address is %x\n", *bios_ prtr_ port_ 1 ); 

} 

Intel 

MACRO 
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mkstemp 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 


♦include <stdlib.h> 

int mkstemp( char *template ) ; 

The mkstemp function creates a file with unique name by modifying the template argument, and 
returns its file handle open for reading and writing in binary mode. The use of mkstemp prevents any 
possible race condition between testing whether the file exists and opening it for use. 

The string template has the form baseXXXXXX where base is the fixed part of the generated filename 
and XXXXXX is the variable part of the generated filename. Each of the 6 X’s is a placeholder for a 
character supplied by mkstemp. Each placeholder character in template must be an uppercase "X". 
mkstemp preserves base and replaces the first of the 6 trailing X’s with a unique sequence of 
alphanumeric characters. The string template therefore must be writable. 

mkstemp checks to see if a file with the generated name already exists and if so selects another name, 
until it finds a file that doesn't exist. If it is unsuccessful at finding a name for a file that does not 
already exist or is unable to create a file, mkstemp returns -1. 

The mkstemp function returns a file handle. When an error occurs while creating the file, -1 is 
returned. 

fopen, freopen, _ mktemp,_ tempnam,tmpfile, tmpnam 

♦include <stdio.h> 

♦include <string.h> 

♦include <stdlib.h> 

♦include <unistd.h> 

♦define TEMPLATE tXXXXXX" 

♦define MAX_ TEMPS 5 

void main( void ) 

{ 

char name[sizeof( TEMPLATE )]; 

int i; 

int handles [MAX_ TEMPS] ; 

for ( i = 0; i < MAX_ TEMPS; i++ ) { 

strcpy( name, TEMPLATE ); 
handles[i] = mkstemp( name ); 
if( handles[i] == -1 ) { 

printf ( "Failed to create temporary file\n" ); 

} else { 

printf( "Created temporary file '%s'\n", name ); 


} 

for ( i = 0; i < MAX_ TEMPS; i + + ) { 

if( handles[i] != -1 ) { 

close( handles[i] ); 


} 

} 

POSIX 
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mkstemp 


Systems: 


All, Linux, Netware 
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Synopsis: 

Description: 


Returns: 

Errors: 
See Also: 
Example: 


mktemp, _wmktemp 


#include <io.h> 

char *_ mktemp ( char *template ) ; 

♦include <wchar.h> 

wchar_ t *_ wmktemp ( wchar_ t *template ) ; 

The _ mktemp function creates a unique filename by modifying the template argument. _ mktemp 
automatically handles multibyte-character string arguments as appropriate, recognizing 
multibyte-character sequences according to the multibyte code page currently in use by the run-time 
system. 

The _ wmktemp function is a wide-character version of_ mktemp that operates with wide-character 
strings. 

The string template has the form baseXXXXXX where base is the fixed part of the generated filename 
and XXXXXX is the variable part of the generated filename. Each of the 6 X’s is a placeholder for a 
character supplied by _mktemp. Each placeholder character in template must be an uppercase "X". 

_ mktemp preservesbase and replaces the first of the 6 trailing X’s with a lowercase alphabetic 
character (a-z). _ mktemp replaces the following 5 trailing X’s with a five-digit value; this value is a 
unique number identifying the calling process or thread. 

_ mktemp checks to see if a file with the generated name already exists and if so selects another letter, 
in succession, from "a" to "z" until it finds a file that doesn’t exist. If it is unsuccessful at finding a 
name for a file that does not already exist, _ mktemp returns NULL. At most, 26 unique file names can 
be returned to the calling process or thread. 

The _ mktemp function returns a pointer to the modified template. The_ mktemp function returns 
NULL if template is badly formed or no more unique names can be created from the given template. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 

fopen, freopen, mkstemp, _ tempnam,tmpfile, tmpnam 
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mktemp, _wmktemp 


♦include <stdio.h> 

♦include <string.h> 

♦include <io.h> 

♦define TMPLTE tXXXXXX" 

void main() 

{ 

char name[sizeof(TMPLTE)]; 
char *mknm; 
int i; 

FILE *fp; 

for( i = 0; i < 30; i++ ) { 

strcpy( name, TMPLTE ); 
mknm = _ mktemp ( name ) ; 
if( mknm == NULL ) 

printf( "Name is badly formed\n" ); 
else { 

printf( "Name is %s\n", mknm ); 
fp = fopen( mknm, "w" ) ; 
if( fp != NULL ) { 

fprintf( fp, "Name is %s\n", mknm ); 
fclose( fp ); 

} 

} 

} 

} 

Classification: WATCOM 

Systems: _ mktemp - DOS, Windows, Win386, Win32, OS/2 1.x (all), OS/2-32 

_ wmktemp - Win32 
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mktime 


Synopsis: 


Description: 


Returns: 
See Also: 

Example: 


♦include <time.h> 

time_ t mktime( struct tm *timeptr ); 
struct tm { 


int 

tm_ sec; 

/* 

seconds after the minute — 

[0,61] 

*/ 

int 

tm_ min; 

/* 

minutes after the hour — 

[0,59] 

*/ 

int 

tm_ hour; 

/* 

hours after midnight — 

[0,23] 

*/ 

int 

tm_ mday; 

/* 

day of the month — 

[1,31] 

*/ 

int 

tm_ mon; 

/* 

months since January — 

[0,11] 

*/ 

int 

tm_ year; 

/* 

years since 1900 


*/ 

int 

tm_ wday; 

/* 

days since Sunday — 

[0, 6] 

*/ 

int 

tm_ yday; 

/* 

days since January 1 

[0,365' 

1 */ 

int 

tm_ isdst; 

/* 

Daylight Savings Time flag * 

/ 



} ; 


The mktime function converts the local time information in the structure pointed to by timeptr into a 
calendar time (Coordinated Universal Time) with the same encoding used by the time function. The 
original values of the fields tm_ sec,tm_ min,tm_ hour,tm_ mday, andtm_ mon are not restricted 
to ranges described for struct tm. If these fields are not in their proper ranges, they are adjusted so 
that they are in the proper ranges. Values for the fields tm_ wday andtm_ yday are computed after all 
the other fields have been adjusted. 

If the original value of tm_ isdst is negative, this field is computed also. Otherwise, a value of 0 is 
treated as "daylight savings time is not in effect" and a positive value is treated as "daylight savings time 
is in effect". 

Whenever mktime is called, the tzset function is also called. 

The mktime function returns the converted calendar time. 

asctime Functions, asctime_ s,clock, ctime Functions, ctime_ s,difftime, gmtime, 
gmtime_ s,localtime, localtime_ s,strftime, time, tzset 

♦include <stdio.h> 

♦include <time.h> 

static const char *week_ day [ ] = { 

"Sunday", "Monday", "Tuesday", "Wednesday", 

"Thursday", "Friday", "Saturday" 

} ; 

void main() 

{ 

struct tm new_ year; 
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mktime 


Classification: 

Systems: 


new_ year . tm_ year = 
new_ year . tm_ mon = 
new_ year . tra_ mday = 
new_ year . tm_ hour = 
new_ year . tm_ min = 
new_ year. tm_ sec = 
new_ year . tra_ isdst = 
mktime( &new_ year ); 
printf( "The 21st century bega 
week_ day[ new_ year.t 


2001 - 1900; 
0 ; 
i; 

0 ; 

0 ; 

0 ; 

0 ; 


.n on a %s\n", 


_n_ 


produces the following: 

The 21st century began on a Monday 

ISOC 


All, Linux, RDOS, Netware 
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mlock 


Synopsis: 

Description: 

Returns: 

Errors: 


See Also: 

Classification: 

Systems: 


♦include <sys/mman.h> 

int mlock(void *address, size_t len) 

The mlock function causes memory located at address measuring len bytes to be held in physical 
memory until unlocked or the process terminates. 

If successful, the function will return 0. Upon failure, the function will return -1, and errno will be set 
appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINVAL The argument address is not a multiple of the page size or the len is zero or causes an 
overflow 

ENOMEM The arguments do not correspond to a region of the process’s address space or the requested 
lock region exceeds an allowable limit 

EAGAIN Some portion of the memory could not be locked 

EPERM The calling process lacks the approriate permissions 

mlockall, munlock, munlockall 

POSIX 

Linux 
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mlockall 


Synopsis: 

Description: 


Returns: 

Errors: 


See Also: 

Classification: 

Systems: 


♦include <sys/mman.h> 
int mlockall(int flags) 

The mlockall function causes all memory in the current process’s address space to reside in physical 
memory until unlocked. The flags argument may be one or a combination of the following: 

MCL_CURRENT Lock all pages currently mapped for the process 

MCL_FUTURE Lock all pages that may be mapped in the future for this process 

If successful, the function will return 0. Upon failure, the function will return -1, and errno will be set 
appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINVAL The argument flags is zero or invalid 

ENOMEM The amount of memory requested for locking exceeds an allowable limit 

EAGAIN Some portion of the memory could not be locked 

EPERM The calling process lacks the approriate permissions 

mlock, munlock, munlockall 

POSIX 

Linux 
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mmap 


Synopsis: 


Description: 


Returns: 


Errors: 


♦include <sys/mman.h> 

void *mmap(void *address, size_ t len, int prot, int flags, int fd, of 
f_ t offset) 

The mmap function creates a mapping of a file specified by fd and the process address space, allowing 
the file to be accessed via the returned pointer. 

The argument address provides the kernel a "suggestion" as to where to locate the pointer returned by 
this function. The argument address is normally set to NULL, however. 

The argument len specifies the number of bytes of the file to map. 

The prot argument specifies allowed access, being one of: 

PROT_READ Data can be read 

PROT_WRITE Data can be written 

PROT_EXEC Data can be executed 

PROT_NONE No access allowed 

The flags argument specifies flags related to memory mapping, and may be one or a combination of the 
following: 

MAP_ANONYMOUS Don't use an actual file, ignoring fd entirely 

MAP_FIXED Use address exactly 

MAP_LOCKED Lock the memory contents 

MAP-NORESERVE Memory for the file is not reserved in swap 

MAP_POPULATE Populate (prefault) page tables 

MAP-PRIVATE Changes to the file are private 

MAP-SHARED Share changes to the file 

An additional flag, MAP_ANON, is an alias for MAP_ANONYMOUS. 

The argument fd is a file descriptor for mapping. It is ignored if MAP_ANONYMOUS is specified. 

The offset argument specifies the offset within the file or device to be mapped, in bytes, at which 
mapping will start. 

If successful, the function will return a pointer to mapped file. Upon failure, the function will return 
MAP_FAILED, and errno will be set appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
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mmap 


See Also: 

Classification: 

Systems: 


Constant Meaning 

EINVAL The value of address could not be read or the len is zero, or value of any argument was 
invalid 

ENOMEM Memory could not be allocated 

EOVERFLOW An overflow occurred due to the len value 

EPERM The memory could not be locked when requested 

EACCES Access was denied for the specified /of file descriptor 

.ENODEV Memory mapping is unavailable for the requested device 

raunmap 

POSIX 

Linux 
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modf 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 

double modf( double value, double *iptr ); 

The modf function breaks the argument value into integral and fractional parts, each of which has the 
same sign as the argument. It stores the integral part as a double in the object pointed to by iptr. 

The modf function returns the signed fractional part of value. 

frexp, ldexp 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

double integral_ value, fractional_part; 

fractional_ part = modf ( 4.5, &integral_ value ); 
printf ( "%f %f\n", fractional_ part, integral_ value ); 
fractional_ part = modf( -4.5, &integral_ value ); 
printf ( "%f %f\n", fractional_ part, integral_ value ); 

} 

produces the following: 

0.500000 4.000000 
-0.500000 -4.000000 

ISOC 

Math 
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movedata 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


♦include <string.h> 

void movedata( unsigned int src_ segment, 
unsigned int src_ offset, 
unsigned int tgt_ segment, 
unsigned int tgt_ offset, 
size_ t length ); 

The movedata function copies length bytes from the far pointer calculated as 
(src_ segment:src_ offset) to a target location determined as a far pointer 
(tgt_ segment :tgt_ offset) . 

Overlapping data may not be correctly copied. When the source and target areas may overlap, copy the 
areas one character at a time. 

The function is useful to move data when the near address(es) of the source and/or target areas are not 
known. 

No value is returned. 

FP_ SEG,FP_ OFF/nemcpy, segread 

♦include <stdio.h> 

♦include <string.h> 

♦include <dos.h> 

void main() 

{ 

char buffer[14] = { 

0x17, 'H', 0x17, 

'1', 0x17, 'o', 0x17, 

movedata ( FP_ SEG( buffer ), 

FP_ OFF ( buffer ), 

0xB800, 

0x0720, 

14 ) ; 

} 

WATCOM 

All, Linux, RDOS, Netware 


'e', 0x17, '1', 0x17, 
'*', 0x17 }; 
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moveto Functions 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <graph.h> 

struct xycoord _ FAR _ moveto( short x, short y ); 

struct _ wxycoord _ FAR _moveto_w( double x, double y ); 

The _ moveto functions set the current output position for graphics. The_ moveto function uses the 
view coordinate system. The _ moveto_ w function uses the window coordinate system. 

The current output position is set to be the point at the coordinates (x, y) . Nothing is drawn by the 
function. The _ lineto function uses the current output position as the starting point when a line is 
drawn. 

Note that the output position for graphics output differs from that for text output. The output position 
for text output can be set by use of the _ settextposition function. 

The _ moveto functions return the previous value of the output position for graphics. 

_ getcurrentposition,_ lineto,_ settextposition 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

_ setvideomode( _ VRES16C0L0R ); 


_ moveto( 

100, 

100 ) ; 

_ lineto( 

540, 

100 ) 

_ lineto ( 

320, 

380 ) 

_ lineto ( 

100, 

100 ) ; 


getch(); 

_ setvideomode( _ DEFAULTMODE ) ; 

} 

PC Graphics 

_ moveto - DOS 
_ moveto_ w - DOS 
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m_packssdw 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


♦include <mmintrin.h> 

_m64 _ m_ packssdw (_m64 *ml,_m64 *m2); 

Convert signed packed double-words into signed packed words by packing (with signed saturation) the 
low-order words of the signed double-word elements from ml and m2 into the respective signed words 
of the result. If the signed values in the word elements of ml and m2 are smaller than 0x8000, the result 
elements are clamped to 0x8000. If the signed values in the word elements of ml and m2 are larger 
than 0x7fff, the result elements are clamped to 0x7fff. 

m2 ml 


w3 : w2 wl : wO w3 : w2 wl : wO 


x_ x_ _ r 


V 

V 

V 

V 

| w3 

| w2 

1 1 

wO | 

result 



The result of packing, with signed saturation, 32-bit signed double-words into 16-bit signed words is 
returned. 


m_ empty^ m_ packs swbj_ m_ packuswb 


♦include <stdio.h> 

♦include Cmmintrin.h> 

♦define AS_ BYTES "%2.2x %2.2x %2.2x %2.2x " \ 
"%2.2x %2.2x %2.2x %2.2x" 

♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 

♦ define AS_ DWORDS "%8.81x %8.81x" 

_ m64 a; 

_m64 b = { 0x0000567800001234 }; 

_m64 c = { OxfffffffeOOOlOlOl }; 

void main() 

{ 

a = _m_ packssdw ( b, c ) ; 
printf ( "m2 = "AS_ DWORDS" " 

"ml = "AS_ DWORDS"\ n" 

" mm= " AS_ WORD S " \ n " , 
c 32[1], c32[0] , 
b._ 32 [1], b._ 32[0], 

a 16 [3] , a 16 [2 ] , a._16[l], a._16[0] ); 

} 


produces the following: 


m2=fffffffe 00010101 ml=00005678 00001234 
mm=fffe 7fff 5678 1234 
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m_packssdw 


Classification: Intel 
Systems: MACRO 
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m_packsswb 


Synopsis: #include <mmintrin.h> 

_m64 _m_packsswb(_m64 *ml,_m64 *m2); 

Description: Convert signed packed words into signed packed bytes by packing (with signed saturation) the 

low-order bytes of the signed word elements from ml and m2 into the respective signed bytes of the 
result. If the signed values in the word elements of ml and m2 are smaller than 0x80, the result 
elements are clamped to 0x80. If the signed values in the word elements of ml and m2 are larger than 
0x7f, the result elements are clamped to 0x7f. 

m2 ml 


b7 b6 b5 b4 b3 b2 bl bO b7 b6 b5 b4 b3 b2 bl bO 



VVVVVVVV 


b7 b6 b5 b4 b3 b2 bl bO 


result 

Returns: The result of packing, with signed saturation, 16-bit signed words into 8-bit signed bytes is returned. 

See Also: _ m_ empty^ m_ packssdw^ m_ packuswb 

Example: #include <stdio.h> 

♦include <mmintrin.h> 

♦define AS_ BYTES "%2.2x %2.2x %2.2x %2.2x " \ 

"%2.2x %2.2x %2.2x %2.2x" 

♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 

♦ define AS_ DWORDS "%8.81x %8.81x" 

_ m64 a; 

_m64 b = { 0x0004000300020001 }; 

_m64 c = { 0xff7fff800080007f }; 

void main() 

{ 

a = _m_packsswb( b, c ) ; 
printf ( "m2 = "AS_ WORDS" " 

"ml="AS_ WORDS"\ n" 

"mm= "AS_ BYTES"\n", 

c 16[3], c16[2], c16[1], c16[0], 
b 16 [3], b._ 16[2] , b._ 16[1] , b 16[0] , 
a 8 [ 7 ] , a 8 [ 6 ] , a._8[5], a._8[4], 

a 8 [ 3 ] , a 8 [2 ] , a._8[l], a._8[0] ); 


produces the following: 
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m_packsswb 


m2=ff7f ff80 0080 007f ml=0004 0003 0002 0001 
mm=80 80 If If 04 03 02 01 


Classification: Intel 
Systems: MACRO 
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m_packuswb 


Synopsis: #include <mmintrin.h> 

_m64 _ m_ packuswb (_m64 *ml,_m64 *m2); 

Description: Convert signed packed words into unsigned packed bytes by packing (with unsigned saturation) the 

low-order bytes of the signed word elements from ml and m2 into the respective unsigned bytes of the 
result. If the signed values in the word elements of ml and m2 are too large to be represented in an 
unsigned byte, the result elements are clamped to Oxff. 

m2 ml 


b7 b6 b5 b4 b3 b2 bl bO b7 b6 b5 b4 b3 b2 bl bO 



VVVVVVVV 


b7 b6 b5 b4 b3 b2 bl bO 


result 

Returns: The result of packing, with unsigned saturation, 16-bit signed words into 8-bit unsigned bytes is 

returned. 

See Also: _ m_ empty^ m_ packssdw^ m_ packsswb 

Example: #include <stdio.h> 

#include <mmintrin.h> 

#define AS_ BYTES "%2.2x %2.2x %2.2x %2.2x " \ 

"%2.2x %2.2x %2.2x %2.2x" 

#define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 

#define AS_ DWORDS "%8.81x %8.81x" 

_ m64 a; 

_m64 b = { 0x0004000300020001 }; 

_m64 c = { 0xff7fff800080007f }; 

void main() 

{ 

a = _ m_ packuswb( b, c ) ; 
printf ( "m2 = "AS_ WORDS" " 

"ml="AS_ WORDS"\ n" 

"mm= "AS_ BYTES"\n", 

c 16[3], c16[2], c16[1], c._ 16[0], 
b 16 [3], b._ 16[2] , b._ 16[1] , b 16[0] , 
a 8 [ 7 ] , a 8 [ 6 ] , a._8[5], a._8[4], 

a 8 [ 3 ] , a 8 [2 ] , a._8[l], a._8[0] ); 


produces the following: 


706 Library Functions and Macros 














m_packuswb 


m2=ff7f ff80 0080 007f ml=0004 0003 0002 0001 
mm=00 00 80 7f 04 03 02 01 


Classification: Intel 
Systems: MACRO 
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m_paddb 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _ m_ paddb (_m64 *ml,_m64 *m2); 

The signed or unsigned 8-bit bytes of m2 are added to the respective signed or unsigned 8-bit bytes of 
ml and the result is stored in memory. If any result element does not fit into 8 bits (overflow), the 
lower 8 bits of the result elements are stored (i.e., truncation takes place). 

The result of adding the packed bytes of two 64-bit multimedia values is returned. 

_ m_ empty^. m_ paddcL m_ paddsb^ m_ paddsw^ m_ paddusbj, m_ paddusw^ m_ paddw 


♦include <stdio.h> 
♦include Cmmintrin.h> 


♦define AS_ BYTES "%2.2x %2.2x %2.2x %2.2x " \ 
"%2.2x %2.2x %2.2x %2.2x" 

_ m64 a; 

_m64 b = { 0x0123456789abcdef }; 

_m64 c = { 0xfedcba9876543210 }; 

void main() 

{ 

a = _ m_ paddb( b, c ) ; 
printf ( "ml = "AS_ BYTES"\n" 

"m2 = "AS_ BYTES"\n" 

"mm= "AS_ BYTES"\n". 


b. 

_ 8[7] , 

b. 

_ 8[6] , 

b. 

_ 8[5] , 

b. 

_ 8[4] , 

b. 

_ 8[3], 

b. 

_ 8[2] , 

b. 

_ 8[1] , 

b. 

_ 8[0] , 

c. 

_ 8[7] , 

c. 

_ 8[6] , 

c. 

_ 8[5] , 

c. 

_ 8[4] , 

c. 

_ 8[3] , 

c. 

_ 8[2] , 

c. 

_ 8[1] , 

c. 

_ 8[0] , 

a. 

_ 8[7] , 

a. 

_ 8[6] , 

a. 

_ 8[5] , 

a. 

_ 8[4] , 

a. 

_ 8[3] , 

a. 

_ 8[2] , 

a. 

_ 8[1] , 

a. 

_ 8 [ 0 ] ) ; 


produces the following: 


ml= 

=01 

23 

45 

67 

89 

ab 

cd 

ef 

m2 = 

=fe 

dc 

ba 

98 

76 

54 

32 

10 

mm= 

=ff 

ff 

ff 

ff 

ff 

ff 

ff 

ff 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


m_paddd 


♦include <mmintrin.h> 

_m64 _ m_ paddd (_m64 *ml,_m64 *m2); 

The signed or unsigned 32-bit double-words of m2 are added to the respective signed or unsigned 32-bit 
double-words of ml and the result is stored in memory. If any result element does not fit into 32 bits 
(overflow), the lower 32-bits of the result elements are stored (i.e., truncation takes place). 

The result of adding the packed double-words of two 64-bit multimedia values is returned. 

_ m_ empty^. m_ paddb^ m_ paddsb^ m_ paddsw^ m_ paddusbj, m_ paddusw^ m_ paddw 

♦include <stdio.h> 

♦include Cmmintrin.h> 

♦ define AS_ DWORDS "%8.81x %8.81x" 

_ m64 a; 

_m64 b = { 0x0123456789abcdef }; 

_m64 c = { 0xfedcba9876543210 }; 

void main() 

{ 

a = _ m_ paddd( b, c ); 
printf ( "ml = "AS_ DWORDS"\n" 

" m2 = " AS_ DWORD S " \ n " 

" mm= " AS_ DWORD S " \ n " , 
b._ 32 [1] , b._ 32[0] , 
c 32 [ 1], c32[0], 
a._ 32[1], a._ 32[0] ); 

} 

produces the following: 

ml=01234567 89abcdef 
m2=fedcba98 76543210 
mm=ffffffff ffffffff 

Intel 
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m_paddsb 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _ m_ paddsb (_m64 *ml,_m64 *m2); 

The signed 8-bit bytes of m2 are added to the respective signed 8-bit bytes of ml and the result is stored 
in memory. Saturation occurs when a result exceeds the range of a signed byte. In the case where a 
result is a byte larger than 0x7f (overflow), it is clamped to 0x7f. In the case where a result is a byte 
smaller than 0x80 (underflow), it is clamped to 0x80. 

The result of adding the packed signed bytes, with saturation, of two 64-bit multimedia values is 
returned. 


m_ empty^ m_ paddb^ m_ paddd=_ m_ paddsw^ m_ paddusbj, m_ paddusw^ m_ paddw 


♦include <stdio.h> 

♦include Cmmintrin.h> 

♦define AS_ BYTES "%2.2x %2.2x %2.2x %2.2x " \ 
"%2.2x %2.2x %2.2x %2.2x" 

_ m64 a; 

_m64 b = { 0x8aacceef02244668 }; 

_m64 c = { 0x76543211fedcba98 }; 

void main() 

{ 

a = _ m_ paddsb( b, c ); 
printf ( "ml = "AS_ BYTES"\n" 

"m2 = "AS_ BYTES"\n" 

"mm= "AS_ BYTES"\n". 


b. 

_ 8[7] , 

b. 

_ 8[6] , 

b. 

_ 8[5] , 

b. 

_ 8[4] , 

b. 

_ 8[3], 

b. 

_ 8[2] , 

b. 

_ 8[1] , 

b. 

_ 8[0] , 

c. 

_ 8[7] , 

c. 

_ 8[6] , 

c. 

_ 8[5] , 

c. 

_ 8[4] , 

c. 

_ 8[3] , 

c. 

_ 8[2] , 

c. 

_ 8[1] , 

c. 

_ 8[0] , 

a. 

_ 8[7] , 

a. 

_ 8[6] , 

a. 

_ 8[5] , 

a. 

_ 8[4] , 

a. 

_ 8[3] , 

a. 

_ 8[2] , 

a. 

_ 8[1] , 

a. 

_ 8 [ 0 ] ) ; 


produces the following: 


ml= 

=8a 

ac 

ce 

ef 

02 

24 

46 

68 

m2 = 

=76 

54 

32 

11 

fe 

dc 

ba 

98 

mm= 

=00 

00 

00 

00 

00 

00 

00 

00 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


m_paddsw 


♦include <mmintrin.h> 

_m64 _ m_ paddsw (_m64 *ml,_m64 *m2); 

The signed 16-bit words of m2 are added to the respective signed 16-bit words of ml and the result is 
stored in memory. Saturation occurs when a result exceeds the range of a signed word. In the case 
where a result is a word larger than 0x7fff (overflow), it is clamped to 0x7fff. In the case where a result 
is a word smaller than 0x8000 (underflow), it is clamped to 0x8000. 

The result of adding the packed signed words, with saturation, of two 64-bit multimedia values is 
returned. 


m_ empty^ m_ paddb^ m_ paddd=_ m_ paddsbj, m_ paddusbj, m_ paddusw^ m_ paddw 


♦include <stdio.h> 

♦include Cmmintrin.h> 

♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 
_ m64 a; 

_m64 b = { 0x8aacceef02244668 }; 

_m64 c = { 0x76543211fedcba98 }; 

void main() 

{ 

a = _ m_ paddsw( b, c ); 
printf ( "ml = "AS_ WORDS"\n" 

" m2 = " AS_ WORD S " \ n " 

" mm= " AS_ WORD S " \ n " , 


b. 

16[3], 

b. 

16[2], 

b. 

16 [ 1 ] , 

b. 

16[0], 

c. 

16[3], 

c. 

16[2], 

c. 

16 [ 1 ] , 

c. 

16[0], 

a. 

16[3], 

a. 

16[2], 

a. 

16 [ 1 ] , 

a. 

■ _ 16 [0] ); 


produces the following: 

ml=8aac ceef 0224 4668 
m2=7654 3211 fedc ba98 
mm=0100 0100 0100 0100 
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m_paddusb 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _ m_ paddusb (_m64 *ml,_m64 *m2); 

The unsigned 8-bit bytes of m2 are added to the respective unsigned 8-bit bytes of ml and the result is 
stored in memory. Saturation occurs when a result exceeds the range of an unsigned byte. In the case 
where a result is a byte larger than Oxff (overflow), it is clamped to Oxff. 

The result of adding the packed unsigned bytes, with saturation, of two 64-bit multimedia values is 
returned. 


m_ empty^. m_ paddb^ m_ paddcL m_ paddsbj, m_ paddsw^ m_ paddusw^ m_ paddw 


♦include <stdio.h> 

♦include Cmmintrin.h> 

♦define AS_ BYTES "%2.2x %2.2x %2.2x %2.2x " \ 
"%2.2x %2.2x %2.2x %2.2x" 

_ m64 a; 

_m64 b = { 0x8aacceef02244668 }; 

_m64 c = { 0x7 6543211fedcba98 }; 

void main() 

{ 

a = _ m_ paddusb( b, c ); 
printf ( "ml = "AS_ BYTES"\n" 

"m2 = "AS_ BYTES"\n" 

"mm= "AS_ BYTES"\n". 


b. 

_ 8 [7] , 

b. 

_ 8[6], 

b. 

_ 8[5] , 

b. 

_ 8[4] , 

b. 

_ 8 [3] , 

b. 

_ 8[2] , 

b. 

_ 8 [1] , 

b. 

_ 8[0] , 

c. 

_ 8 [7] , 

c. 

_ 8[6] , 

c. 

_ 8 [5] , 

c. 

_ 8[4] , 

c. 

_ 8 [3] , 

c. 

_ 8[2] , 

c. 

_ 8[1] , 

c. 

_ 8[0] , 

a. 

_ 8 [7] , 

a. 

_ 8[6], 

a. 

_ 8 [5] , 

a. 

_ 8[4] , 

a. 

_ 8 [3] , 

a. 

_ 8[2] , 

a. 

_ 8[1] , 

a. 

_ 8 [ 0 ] ) ; 


produces the following: 


ml= 

=8a 

ac 

ce 

ef 

02 

24 

46 

68 

m2 = 

=76 

54 

32 

11 

fe 

dc 

ba 

98 

mm= 

=ff 

ff 

ff 

ff 

ff 

ff 

ff 

ff 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


m_paddusw 


♦include <mmintrin.h> 

_m64 _ m_ paddusw (_m64 *ml,_m64 *m2); 

The unsigned 16-bit words of m2 are added to the respective unsigned 16-bit words of ml and the result 
is stored in memory. Saturation occurs when a result exceeds the range of an unsigned word. In the 
case where a result is a word larger than Oxffff (overflow), it is clamped to Oxffff. 

The result of adding the packed unsigned words, with saturation, of two 64-bit multimedia values is 
returned. 


m_ empty^. m_ paddb^ m_ paddcL m_ paddsbj, m_ paddsw^ m_ paddusbj, m_ paddw 


♦include <stdio.h> 

♦include Cmmintrin.h> 

♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 
_ m64 a; 

_m64 b = { 0x8aacceef02244668 }; 

_m64 c = { 0x76543211fedcba98 }; 

void main() 

{ 

a = _ m_ paddusw ( b, c ) ; 
printf ( "ml = "AS_ WORDS"\n" 

" m2 = " AS_ WORD S " \ n " 

" mm= " AS_ WORD S " \ n " , 


b. 

16[3], 

b. 

16[2], 

b. 

16[1], 

b. 

16[0], 

c. 

16[3], 

c. 

1612], 

c. 

16 [ 1 ] , 

c. 

16[0], 

a. 

16 [3] , 

a. 

16[2], 

a. 

16 [ 1 ] , 

a. 

16 [0] ); 


produces the following: 

ml=8aac ceef 0224 4668 
m2=7654 3211 fedc ba98 
mm=ffff ffff ffff ffff 
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m_paddw 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _ m_ paddw (_m64 *ml,_m64 *m2); 

The signed or unsigned 16-bit words of m2 are added to the respective signed or unsigned 16-bit words 
of ml and the result is stored in memory. If any result element does not fit into 16 bits (overflow), the 
lower 16 bits of the result elements are stored (i.e., truncation takes place). 

The result of adding the packed words of two 64-bit multimedia values is returned. 

_ m_ empty^. m_ paddb^ m_ paddcL m_ paddsbj, m_ paddsw^ m_ paddusbj, m_ paddusw 


♦include <stdio.h> 
♦include Cmmintrin.h> 


♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 


_ m64 a; 

_m64 b = { 0x0123456789abcdef }; 

_m64 c = { 0xfedcba9876543210 }; 

void main() 

{ 

a = _ m_ paddw( b, c ) ; 
printf ( "ml = "AS_ WORDS"\n" 

" m2 = " AS_ WORD S " \ n " 

" mm= " AS_ WORD S " \ n " , 


b. 

16 [3] , 

b. 

1612], 

b. 

16 [ 1 ] , 

b. 

16[0], 

c. 

16[3], 

c. 

16[2], 

c. 

16 [ 1 ] , 

c. 

16 [0] , 

a. 

16[3], 

a. 

16[2], 

a. 

16 [ 1 ] , 

a. 

_ 16 [0] ); 


produces the following: 

ml=0123 4567 89ab cdef 
m2=fedc ba98 7654 3210 
mm=ffff ffff ffff ffff 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


m_pand 


♦include <mmintrin.h> 

_m64 _ m_ pand (_m64 *ml,_m64 *m2); 

A bit-wise logical AND is performed between 64-bit multimedia operands ml and m2 and the result is 
stored in memory. 

The bit-wise logical AND of two 64-bit values is returned. 

_ m_ empty^ m_ pandn^ m_ por^ m_ pxor 

♦include <stdio.h> 

♦include <mmintrin.h> 

♦define AS_ QWORD "%16.16Lx" 

_ m64 a; 

_m64 b = { 0x0123456789abcdef }; 

_m64 c = { 0xfedcba9876543210 }; 

void main() 

{ 

a = _ m_ pand ( b, c ) ; 
printf ( "ml = "AS_ QWORD"\n" 

" m2 = " AS_ QWORD " \ n " 

" mm= " AS_ QWORD " \ n " , 
b, c, a ) ; 

} 

produces the following: 

ml=0123456789abcdef 
m2=fedcba9876543210 
mm=0 0 00000000000000 
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mjpandn 


Synopsis: #include <mmintrin.h> 

_m64 _ m_ pandn (_m64 *ml,_m64 *m2); 

Description: A bit-wise logical AND is performed on the logical inversion of 64-bit multimedia operand ml and 
64-bit multimedia operand m2 and the result is stored in memory. 

Returns: The bit-wise logical AND of an inverted 64-bit value and a non-inverted value is returned. 

See Also: _ m_ empty^ m_ pancL m_ por^_ m_ pxor 

Example: #include <stdio.h> 

#include <mmintrin.h> 

♦define AS_ QWORD "%16.16Lx" 

_ m64 a; 

_m64 b = { 0x0123456789abcdef }; 

_m64 c = { 0xfedcba9876543210 }; 

void main() 

{ 

a = _ m_ pandn( b, c ); 
printf ( "ml = "AS_ QWORD"\n" 

" m2 = " AS_ QWORD " \ n " 

" mm= " AS_ QWORD " \ n " , 
b, c, a ) ; 

} 

produces the following: 

ml=0123456789abcdef 
m2=fedcba9876543210 
mm=fedcba987 6543210 

Classification: Intel 

Systems: MACRO 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


m_pcmpeqb 


♦include <mmintrin.h> 

_m64 _ m_ pcmpeqb (_m64 *ml,_m64 *m2); 

If the respective bytes of ml are equal to the respective bytes of m2, the respective bytes of the result 
are set to all ones, otherwise they are set to all zeros. 

The result of comparing the packed bytes of two 64-bit multimedia values is returned as a sequence of 
bytes (Oxff for equal, 0x00 for not equal). 

_ m_ empty*. m_ pcmpeqd*. m_ pcmpeqw*. m_ pcmpgtb*. m_ pcmpgtd*. m_ pcmpgtw 


♦include <stdio.h> 

♦include Cmmintrin.h> 

♦define AS_ BYTES "%2.2x %2.2x %2.2x %2.2x " \ 
"%2.2x %2.2x %2.2x %2.2x" 

_ m64 a; 

_m64 b = { 0x0004000300020001 }; 

_m64 c = { 0xff7fff800080007f }; 

void main() 

{ 

a = _ m_ pcmpeqb ( b, c ); 
printf ( "ml = "AS_ BYTES"\n" 

"m2 = "AS_ BYTES"\n" 

"mm= "AS_ BYTES"\n". 


b. 

_ 8[7] , 

b. 

_ 8[6] , 

b. 

_ 8 [5] , 

b. 

_ 8[4] , 

b. 

_ 8[3], 

b. 

_ 8[2] , 

b. 

_ 8[1] , 

b. 

_ 8[0] , 

c. 

_ 8[7] , 

c. 

_ 8[6] , 

c. 

_ 8 [5] , 

c. 

_ 8[4] , 

c. 

_ 8[3] , 

c. 

_ 8 [2] , 

c. 

_ 8[1] , 

c. 

_ 8[0] , 

a. 

_ 8[7] , 

a. 

_ 8[6] , 

a. 

_ 8 [5] , 

a. 

_ 8[4] , 

a. 

_ 8[3] , 

a. 

_ 8[2] , 

a. 

_ 8[1] , 

a. 

_ 8 [ 0 ] ) ; 


produces the following: 


ml= 

=00 

04 

00 

03 

00 

02 

00 

01 

m2 = 

=ff 

If 

ff 

80 

00 

80 

00 

If 

mm= 

=00 

00 

00 

00 

ff 

00 

ff 

00 
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m_pcmpeqd 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _m_pcmpeqd(_m64 *ml,_m64 *m2); 

If the respective double-words of ml are equal to the respective double-words of m2, the respective 
double-words of the result are set to all ones, otherwise they are set to all zeros. 

The result of comparing the 32-bit packed double-words of two 64-bit multimedia values is returned as 
a sequence of double-words (Oxffffffff for equal, 0x00000000 for not equal). 

_ m_ empty^ m_ pcmpeqbj, m_ pcmpeqw^ m_ pcmpgtbj, m_ pcmpgtcL m_ pcmpgtw 


♦include <stdio.h> 
♦include Cmmintrin.h> 


♦ define AS_ DWORDS "%8.81x %8.81x" 
_ m64 a; 

_m64 b = { 0x0004000300020001 }; 

_m64 c = { 0x000400030002007f }; 

void main() 

{ 

a = _m_pcmpeqd( b, c ); 
printf ( "ml = "AS_ DWORDS"\n" 

"m2 = "AS_ DWORDS"\n" 

" mm= " AS_ DWORD S " \ n " , 
b._ 32 [1], b._ 32[0], 
c 32[1], c32[0], 
a._ 32[1], a._ 32[0] ); 


produces the following: 

ml=00040003 00020001 
m2=00040003 0002007f 
mm=ffffffff 00000000 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


m_pcmpeqw 


♦include <mmintrin.h> 

_m64 _ m_ pcmpeqw (_m64 *ml,_m64 *m2); 

If the respective words of ml are equal to the respective words of m2, the respective words of the result 
are set to all ones, otherwise they are set to all zeros. 

The result of comparing the packed words of two 64-bit multimedia values is returned as a sequence of 
words (Oxffff for equal, 0x0000 for not equal). 

_ m_ empty*. m_ pcmpeqb*. m_ pcmpeqd*. m_ pcmpgtb*. m_ pcmpgtd*. m_ pcmpgtw 


♦include <stdio.h> 
♦include Cmmintrin.h> 


♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 


_ m64 a; 

_m64 b = { 0x0004000300020001 }; 

_m64 c = { 0x0004ff8000800001 }; 

void main() 

{ 

a = _ m_ pcmpeqw ( b, c ) ; 
printf ( "ml = "AS_ WORDS"\n" 

" m2 = " AS_ WORD S " \ n " 

" mm= " AS_ WORD S " \ n " , 


_ 16 [3] , 

b. 

1612], 

b. 

16 [ 1 ] , 

b. 

16[0], 

_ 16 [3] , 

c. 

16[2], 

c. 

16 [ 1 ] , 

c. 

16 [0] , 

_ 16 [3] , 

a. 

16[2], 

a. 

16 [ 1 ] , 

a. 

_ 16 [0] ); 


produces the following: 

ml=0004 0003 0002 0001 
m2=0004 ff80 0080 0001 
mm=ffff 0000 0000 ffff 
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m_pcmpgtb 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _ m_ pcmpgtb (_m64 *ml,_m64 *m2); 

If the respective signed bytes of ml are greater than the respective signed bytes of m2, the respective 
bytes of the result are set to all ones, otherwise they are set to all zeros. 

The result of comparing the packed signed bytes of two 64-bit multimedia values is returned as a 
sequence of bytes (Oxff for greater than, 0x00 for not greater than). 

_ m_ empty^_ m_ pcmpeqbj, m_ pcmpeqcL m_ pcmpeqw^ m_ pcmpgtcL m_ pcmpgtw 


♦include <stdio.h> 
♦include Cmmintrin.h> 


♦define AS_ BYTES "%2.2x %2.2x %2.2x %2.2x " \ 
"%2.2x %2.2x %2.2x %2.2x" 

_ m64 a; 

_m64 b = { 0x0004000300020001 }; 

_m64 c = { 0xff7fff800080007f }; 

void main() 

{ 

a = _ m_ pcmpgtb ( b, c ); 
printf ( "ml = "AS_ BYTES"\n" 

"m2 = "AS_ BYTES"\n" 

"mm= "AS_ BYTES"\n". 


b. 

_ 8 [7] , 

b. 

_ 8[6] , 

b. 

_ 8[5] , 

b. 

_ 8 [4] , 

b. 

_ 8 [3], 

b. 

_ 8 [2] , 

b. 

_ 8[1] , 

b. 

_ 8 [0] , 

c. 

_ 8 [7] , 

c. 

_ 8[6] , 

c. 

_ 8[5] , 

c. 

_ 8 [4] , 

c. 

_ 8 [3] , 

c. 

_ 8[2] , 

c. 

_ 8[1] , 

c. 

_ 8 [0] , 

a. 

_ 8 [7] , 

a . 

_ 8[6] , 

a . 

_ 8[5] , 

a . 

_ 8 [4] , 

a . 

_ 8 [3] , 

a . 

_ 8 [2] , 

a. 

_ 8[1] , 

a. 

_ 8 [ 0 ] ) ; 


produces the following: 


ml= 

=00 

04 

00 

03 

00 

02 

00 

01 

m2 = 

=ff 

7 f 

ff 

80 

00 

80 

00 

If 

mm= 

=ff 

00 

ff 

ff 

00 

ff 

00 

00 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


m_pcmpgtd 


♦include <mmintrin.h> 

_m64 _m_pcmpgtd(_m64 *ml,_m64 *m2); 

If the respective signed double-words of ml are greater than the respective signed double-words of m2, 
the respective double-words of the result are set to all ones, otherwise they are set to all zeros. 

The result of comparing the 32-bit packed signed double-words of two 64-bit multimedia values is 
returned as a sequence of double-words (Oxffffffff for greater than, 0x00000000 for not greater than). 

_ m_ empty^. ni_ pcmpeqbj, m_ pcmpeqcL m_ pcmpeqw^ m_ pcmpgtbj, m_ pcmpgtw 


♦include <stdio.h> 
♦include Cmmintrin.h> 


♦define AS_ DWORDS "%8.81x %8.81x" 


m64 a; 

m64 b = { 0x0004000400020001 }; 
m64 c = { 0x000400030080007f }; 


void main() 

{ 

a = _m_pcmpgtd( b, c ); 
printf ( "ml = "AS_ DWORDS "\n" 
"m2 = "AS_ DWORDS "\n" 

" mm= " AS_ DWORD S " \ n " , 
b._ 32 [1], b._ 32[0], 
c 32[1], c32[0], 
a._ 32[1], a._ 32[0] ); 


produces the following: 

ml=00040004 00020001 
m2=00040003 0080007f 
mm=ffffffff 00000000 

Intel 
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m_pcmpgtw 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _ m_ pcmpgtw (_m64 *ml,_m64 *m2); 

If the respective signed words of ml are greater than the respective signed words of m2, the respective 
words of the result are set to all ones, otherwise they are set to all zeros. 

The result of comparing the 16-bit packed signed words of two 64-bit multimedia values is returned as a 
sequence of words (Oxffff for greater than, 0x0000 for not greater than). 

_ m_ empty^ m_ pcmpeqbj, m_ pcmpeqcL m_ pcmpeqw^ m_ pcmpgtbj, m_ pcmpgtd 


♦include <stdio.h> 
♦include Cmmintrin.h> 


♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 


_ m64 a; 

_m64 b = { 0x0005000300020001 }; 

_m64 c = { 0x0004ff8000800001 }; 

void main() 

{ 

a = _ m_ pcmpgtw( b, c ) ; 
printf ( "ml = "AS_ WORDS"\n" 

" m2 = " AS_ WORD S " \ n " 

" mm= " AS_ WORD S " \ n " , 


b. 

_ 16 [3] , 

b. 

1612], 

b. 

16 [ 1 ] , 

b. 

_ 16 [0 

c. 

16[3], 

c. 

16[2], 

c. 

16 [ 1 ] , 

c. 

_ 16 [0 

a. 

_ 16[3] , 

a. 

16[2], 

a. 

16 [ 1 ] , 

a. 

_ 16 [0 


produces the following: 

ml=0005 0003 0002 0001 
m2=0004 ff80 0080 0001 
mm=ffff ffff 0000 0000 
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Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


m_pmaddwd 


♦include <mmintrin.h> 

_m64 _ m_ pmaddwd (_m64 *ml,_m64 *m2); 

The signed 16-bit words of ml are multiplied with the respective signed 16-bit words of m2. The 32-bit 
intermediate results are summed by pairs producing two 32-bit integers. 

MM[63-32] = Ml[63-48] xM2[63-48] 

+ Ml[47-32] x M2[47-32] 

MM[31-0] = Ml[31-16] x M2[31-16] 

+ Ml[15-0] x M2[15-0] 


In cases which overflow, the results are truncated. These two integers are packed into their respective 
elements of the result. 


The result of multiplying the packed signed 16-bit words of two 64-bit multimedia values and adding 
the 32-bit results pairwise is returned as packed double-words. 


m_ empty^. m_ pmulhw^ m_ pmullw 


♦include <stdio.h> 
♦include Cmmintrin.h> 


♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 
♦define AS_ DWORDS "%8.81x %8.81x" 


m64 a; 

m64 b = { 0x0000006000123456 }; 
m64 c = { 0x0000000200010020 }; 


void main() 

{ 

a = _ m_ pmaddwd ( b, c ); 
printf ( "ml = "AS_ WORDS "\n" 

" m2 = " AS_ WORD S " \ n " 

" mm= " AS_ DWORD S " \ n " , 
b 16 [3] , b._ 16 [2] , b16 [ 1 ] , 
c._ 16[3], c16[2], c16[1], 
a._ 32[1], a._ 32[0] ); 

} 


b. _ 16 [0], 

c. _ 16 [0] , 


produces the following: 

ml=0000 0060 0012 3456 
m2=0000 0002 0001 0020 
mm=000000c0 00068ad2 
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m_pmulhw 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _ m_ pmulhw (_m64 *ml,_m64 *m2); 

The signed 16-bit words of ml are multiplied with the respective signed 16-bit words of m2. The 
high-order 16-bits of each result are placed in the respective elements of the result. 

The packed 16-bit words in ml are multiplied with the packed 16-bit words in m2 and the high-order 
16-bits of the results are returned. 


m_ empty^. m_ pmaddwcL m_ pmullw 


♦include <stdio.h> 
♦include Cmmintrin.h> 


♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 


_ m64 a; 

_m64 b = { 0x4000006000123456 }; 

_m64 c = { 0x0008000210000020 }; 

void main() 

{ 

a = _ m_ pmulhw( b, c ) ; 
printf ( "ml = "AS_ WORDS"\n" 

" m2 = " AS_ WORD S " \ n " 

" mm= " AS_ WORD S " \ n " , 


_ 16 [3] , 

b. 

1612], 

b. 

16 [ 1 ] , 

b. 

_ 16 [0] , 

_ 16 [3] , 

c. 

16[2], 

c. 

16 [ 1 ] , 

c. 

_ 16 [0] , 

_ 16 [3] , 

a. 

16[2], 

a. 

16 [ 1 ] , 

a. 

_ 16 [0] ); 


produces the following: 

ml=4000 0060 0012 3456 
m2=0008 0002 1000 0020 
mm=0002 0000 0001 0006 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


m_pmullw 


♦include <mmintrin.h> 

_m64 _m_pmullw(_m64 *ml,_m64 *m2); 

The signed or unsigned 16-bit words of ml are multiplied with the respective signed or unsigned 16-bit 
words of m2. The low-order 16-bits of each result are placed in the respective elements of the result. 

The packed 16-bit words in ml are multiplied with the packed 16-bit words in m2 and the low-order 
16-bits of the results are returned. 


m_ empty^. m_ pmaddwcL m_ pmulhw 


♦include <stdio.h> 
♦include Cmmintrin.h> 


♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 


_ m64 a; 

_m64 b = { 0x4000006000123456 }; 

_m64 c = { 0x0008000210000020 }; 

void main() 

{ 

a = _m_pmullw( b, c ) ; 
printf ( "ml = "AS_ WORDS "\n" 

" m2 = " AS_ WORD S " \ n " 

" mm= " AS_ WORD S " \ n " , 


b. 

16 [3] , 

b. 

1612], 

b. 

16 [ 1 ] , 

b. 

16 [0 

c. 

16[3], 

c. 

16[2], 

c. 

16 [ 1 ] , 

c. 

._ 16 [0 

a. 

16[3], 

a. 

16[2], 

a. 

16 [ 1 ] , 

a. 

. _ 16 [ 0 


produces the following: 

ml=4000 0060 0012 3456 
m2=0008 0002 1000 0020 
mm=0000 OOcO 2000 8ac0 
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m_por 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _ m_ por (_m64 *ml,_m64 *m2); 

A bit-wise logical OR is performed between 64-bit multimedia operands ml and m2 and the result is 
stored in memory. 

The bit-wise logical OR of two 64-bit values is returned. 


_ m_ empty^ m_ pancL m_ pandn^ m_ pxor 

♦include <stdio.h> 

♦include <mmintrin.h> 

♦define AS_ QWORD "%16.16Lx" 

_ m64 a; 

_m64 b = { 0x0123456789abcdef }; 

_m64 c = { 0xfedcba9876543210 }; 

void main() 

{ 

a = _ m_ por ( b, c ) ; 
printf ( "ml = "AS_ QWORD"\n" 

"m2 = "AS_ QWORD"\n" 

" mm= " AS_ QWORD " \ n " , 
b, c, a ) ; 


produces the following: 

ml=0123456789abcdef 

m2=fedcba9876543210 

mm=ffffffffffffffff 
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mprotect 


Synopsis: 

Description: 


Returns: 

Errors: 


See Also: 

Classification: 

Systems: 


♦include <sys/mman.h> 

int mprotect(void *address, size_ t len, int flags) 

The mprotect function writes changes the protections for the pages encompassing the memory 
mapping at address and measuring len bytes based on the flags argument as specified. 

The flags argument may be one or a combination of the following: 

Constant Meaning 

PROT_NONE No protections 

PROT_READ Read only 

PROT WRITE Write only 

PROT_EXEC Allow execution 

The flags may be either exclusively PROT_ NONE or a combination of one or more of the remaining 
three values. 

If successful, the function will return 0. Upon failure, the function will return -1, and errno will be set 
appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EACCES The value of flags violates a the permissions that a process has to the mapped data. 

EAGAIN Write access was requested when the memory was originally mapped with the 
MAP_ PRIVATE flag and the system lacks the resources to create a private page. 

EINVAL The argument address is not a multiple of the page size or the flags argument is invalid 

ENOMEM The arguments do not correspond to a region of the process’s address space or exceed the 
process’s address space 

ENOTSUP The specified combination of flags is not supported on the underlying system 

mmap 

POSIX 

Linux 
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m_pslld 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _m_pslld(_m64 *m,_m64 *count) ; 

The 32-bit double-words in m are each independently shifted to the left by the scalar shift count in 
count. The low-order bits of each element are filled with zeros. The shift count is interpreted as 
unsigned. Shift counts greater than 31 yield all zeros. 

Shift left each 32-bit double-word in m by an amount specified in count while shifting in zeros. 

_ m_ empty^. m_ pslldij, m_ psllq*. m_ psllqij, m_ psllw^ m_ psllwi 


♦include <stdio.h> 

♦include Cmmintrin.h> 

♦ define AS_ DWORDS "%8.81x %8.81x" 
♦define AS_ QWORD "%16.16Lx" 

_ m64 a; 

_m64 b = { 0x3f04800300020001 }; 

_m64 c = { 0x0000000000000002 }; 

void main() 

{ 

a = _m_pslld( b, c ) ; 
printf ( "ml = "AS_ DWORDS"\n" 

" m2 = " AS_ QWORD " \ n " 

" mm= " AS_ DWORD S " \ n " , 

b. _ 32 [1], b._ 32[0], 

c, 

a._ 32[1], a._ 32[0] ); 

} 


produces the following: 


ml=3f048003 00020001 
m2=0000000000000002 
mm=fcl2000c 00080004 
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m_pslldi 


Synopsis: #include <mmintrin.h> 

_m64 _ m_ pslldi (_m64 *m, int count) ; 

Description: The 32-bit double-words in m are each independently shifted to the left by the scalar shift count in 
count. The low-order bits of each element are filled with zeros. The shift count is interpreted as 
unsigned. Shift counts greater than 31 yield all zeros. 

Returns: Shift left each 32-bit double-word in m by an amount specified in count while shifting in zeros. 


See Also: 


m_ empty^. m_ psllcL m_ psllcp. m_ psllqij, m_ psllWj. psllwi 


Example: #include <stdio.h> 

♦include <mmintrin.h> 

♦define AS_ DWORDS "%8.81x %8.81x" 

_ m64 a; 

_m64 b = { 0x3f04800300020001 }; 

void main() 

{ 

a = _ m_ pslldi( b, 2 ) ; 
printf ( "m ="AS_ DWORDS"\n" 

" mm= " AS_ DWORD S " \ n " , 
b._ 32 [1] , b._ 32 [0], 
a 32[1], a32[0] ); 


produces the following: 

m =3f048003 00020001 
mm=fc!2000c 00080004 


Classification: Intel 
Systems: MACRO 
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m_psllq 


Synopsis: #include <mmintrin.h> 

_m64 _m_psllq(_m64 *m,_m64 *count) ; 

Description: The 64-bit quad-word in m is shifted to the left by the scalar shift count in count. The low-order bits are 
filled with zeros. The shift count is interpreted as unsigned. Shift counts greater than 63 yield all zeros. 

Returns: Shift left the 64-bit quad-word in m by an amount specified in count while shifting in zeros. 

See Also: _ m_ empty^ m_ psllcL m_ pslldij, m_ psllqij, m_ psllw^ m_ psllwi 

Example: #include <stdio.h> 

♦include <mmintrin.h> 

♦define AS_ QWORD "%16.16Lx" 

_ m64 a; 

_m64 b = { 0x3f04800300020001 }; 

_m64 c = { 0x0000000000000002 }; 

void main() 

{ 

a = _m_psllq( b, c ); 
printf ( "ml = "AS_ QWORD"\n" 

" m2 = " AS_ QWORD " \ n " 

" mm= " AS_ QWORD " \ n " , 
b, c, a ) ; 

} 

produces the following: 

ml=3f04800300020001 
m2=0000000000000002 
mm=fcl2000c00080004 

Classification: Intel 

Systems: MACRO 
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m_psllqi 


Synopsis: 

Description: 

Returns: 

See Also: 


♦include <mmintrin.h> 

_m64 _ m_ psllqi (_m64 *m, int count); 

The 64-bit quad-word in m is shifted to the left by the scalar shift count in count. The low-order bits are 
filled with zeros. The shift count is interpreted as unsigned. Shift counts greater than 63 yield all zeros. 

Shift left the 64-bit quad-word in m by an amount specified in count while shifting in zeros. 

_ m_ empty^ m_ psllcL m_ pslldij, m_ psllq^ m_ psllw^ m_ psllwi 


Example: #include <stdio.h> 

♦include <mmintrin.h> 

♦define AS_ QWORD "%16.16Lx" 

_ m64 a; 

_m64 b = { 0x3f04800300020001 }; 

void main () 

{ 

a = _m_ psllqi ( b, 2 ) ; 
printf ( "m ="AS_ QWORD"\n" 

" mm= " AS_ QWORD " \ n " , 
b, a ) ; 


produces the following: 

m =3f04800300020001 
mm=fc12000c00080004 


Classification: Intel 
Systems: MACRO 
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m_psllw 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _m_psllw(_m64 *m,_m64 *count) ; 

The 16-bit words in m are each independently shifted to the left by the scalar shift count in count. The 
low-order bits of each element are filled with zeros. The shift count is interpreted as unsigned. Shift 
counts greater than 15 yield all zeros. 

Shift left each 16-bit word in m by an amount specified in count while shifting in zeros. 

_ m_ empty^. m_ psllcL m_ pslldij, m_ psllcp. m_ psllqij, m_ psllwi 


♦include <stdio.h> 

♦include Cmmintrin.h> 

♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 
♦define AS_ QWORD "%16.16Lx" 


_ m64 a; 

_m64 b = { 0x3f04800300020001 }; 

_m64 c = { 0x0000000000000002 }; 

void main() 

{ 

a = _m_psllw( b, c ) ; 
printf ( "ml = "AS_ WORDS "\n" 

" m2 = " AS_ QWORD " \ n " 

" mm= " AS_ WORD S " \ n " , 

b 16 [3] , b._ 16 [2] , b16 [ 1 ] , b._16[0], 

c, 

a._ 16 [3] , a 16 [2 ] , a._16[l], a._16[0] ); 


produces the following: 


ml=3f04 8003 0002 0001 
m2=0000000000000002 
mm=fcl0 000c 0008 0004 


Intel 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


m_psllwi 


♦include <mmintrin.h> 

_m64 _ m_ psllwi (_m64 *m, int count); 

The 16-bit words in m are each independently shifted to the left by the scalar shift count in count. The 
low-order bits of each element are filled with zeros. The shift count is interpreted as unsigned. Shift 
counts greater than 15 yield all zeros. 

Shift left each 16-bit word in m by an amount specified in count while shifting in zeros. 

_ m_ empty^. m_ psllcL m_ pslldij, m_ psllq^ m_ psllqij, m_ psllw 

♦include <stdio.h> 

♦include <mmintrin.h> 

♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 

_ m64 a; 

_m64 b = { 0x3f04800300020001 }; 

void main() 

{ 

a = _ m_ psllwi( b, 2 ) ; 
printf ( "m ="AS_ WORDS"\n" 

" mm= " AS_ WORD S " \ n " , 

b16 [ 3] , b._ 16 [2] , b16 [ 1 ] , b._16[0], 
a._ 16 [3] , a 16 [2 ] , a._16[l], a._16[0] ); 

} 

produces the following: 

m =3f04 8003 0002 0001 

mm=fcl0 000c 0008 0004 
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m_psrad 


Synopsis: #include <mmintrin.h> 

_m64 _m_psrad(_m64 *m,_m64 *count) ; 

Description: The 32-bit signed double-words in m are each independently shifted to the right by the scalar shift count 
in count. The high-order bits of each element are filled with the initial value of the sign bit of each 
element. The shift count is interpreted as unsigned. Shift counts greater than 31 yield all ones or zeros 
depending on the initial value of the sign bit. 

Returns: Shift right each 32-bit double-word in m by an amount specified in count while shifting in sign bits. 

See Also: _ m_ empty^ m_ psradij, m_ psraw*. m_ psrawi 

Example: #include <stdio.h> 

♦include Cmmintrin.h> 

♦ define AS_ DWORDS "%8.81x %8.81x" 

♦define AS_ QWORD "%16.16Lx" 

_ m64 a; 

_m64 b = { 0x3f04800300020001 }; 

_m64 c = { 0x0000000000000002 }; 

void main() 

{ 

a = _m_psrad( b, c ); 
printf( "ml="AS_ DWORDS"\n" 

" m2 = " AS_ QWORD " \ n " 

" mm= " AS_ DWORD S " \ n " , 

b. _ 32 [1], b._ 32[0], 

c, 

a._ 32 [1], a32[0] ); 

} 

produces the following: 

ml=3f048003 00020001 
m2=0000000000000002 
mm=0fcl2000 00008000 

Classification: Intel 

Systems: MACRO 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


m_psradi 


♦include <mmintrin.h> 

_m64 _ m_ psradi (_m64 *m, int count); 

The 32-bit signed double-words in m are each independently shifted to the right by the scalar shift count 
in count. The high-order bits of each element are filled with the initial value of the sign bit of each 
element. The shift count is interpreted as unsigned. Shift counts greater than 31 yield all ones or zeros 
depending on the initial value of the sign bit. 

Shift right each 32-bit double-word in m by an amount specified in count while shifting in sign bits. 

_ m_ empty^ m_ psracL m_ psraw^ m_ psrawi 

♦include <stdio.h> 

♦include Cmmintrin.h> 

♦ define AS_ DWORDS "%8.81x %8.81x" 

_ m64 a; 

_m64 b = { 0x3f04800300020001 }; 

void main() 

{ 

a = _ m_ psradi( b, 2 ) ; 
printf ( "m ="AS_ DWORDS"\n" 

" mm= " AS_ DWORD S " \ n " , 
b._ 32 [1] , b._ 32[0], 
a._ 32[1] , a._ 32[0] ); 

} 

produces the following: 

m =3f048003 00020001 
mm=0fcl2000 00008000 

Intel 
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m_psraw 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _m_psraw(_m64 *m,_m64 *count) ; 

The 16-bit signed words in m are each independently shifted to the right by the scalar shift count in 
count. The high-order bits of each element are filled with the initial value of the sign bit of each 
element. The shift count is interpreted as unsigned. Shift counts greater than 15 yield all ones or zeros 
depending on the initial value of the sign bit. 

Shift right each 16-bit word in m by an amount specified in count while shifting in sign bits. 

_ m_ empty^ m_ psracL m_ psradij, m_ psrawi 


♦include <stdio.h> 
♦include <mmintrin.h> 


♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 
♦define AS_ QWORD "%16.16Lx" 


m64 a; 
m64 b = 

m64 c = 


0x3f04800300040001 

0x0000000000000002 


void main() 

{ 

a = _m_psraw( b, c ) ; 
printf ( "ml = "AS_ WORDS "\n" 

" m2 = " AS_ QWORD " \ n " 

" mm= " AS_ WORD S " \ n " , 
b 16[3], b16[2], b._ 
c, 

a 16[3], a._ 16[2] , a._ 


16 [1] , 
16 [ 1 ] , 


b._ 16[0] 
a._ 16[0] 


produces the following: 

ml=3f04 8003 0004 0001 
m2=0000000000000002 
mm=0fcl eOOO 0001 0000 


Intel 
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m_psrawi 


Synopsis: #include <mmintrin.h> 

_m64 _ m_ psrawi (_m64 *m, int count) ; 

Description: The 16-bit signed words in m are each independently shifted to the right by the scalar shift count in 
count. The high-order bits of each element are filled with the initial value of the sign bit of each 
element. The shift count is interpreted as unsigned. Shift counts greater than 15 yield all ones or zeros 
depending on the initial value of the sign bit. 

Returns: Shift right each 16-bit word in m by an amount specified in count while shifting in sign bits. 

See Also: _ m_ empty^ m_ psracL m_ psradij, m_ psraw 

Example: #include <stdio.h> 

♦include <mmintrin.h> 

♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 

_ m64 a; 

_m64 b = { 0x3f04800300040001 }; 

void main() 

{ 

a = _m_ psrawi ( b, 2 ) ; 
printf ( "m ="AS_ WORDS"\n" 

" mm= " AS_ WORD S " \ n " , 

b 16 [3] , b._ 16 [2] , b._ 16 [1] , b._16[0], 
a._ 16 [3] , a 16 [2 ] , a._16[l], a._16[0] ); 

} 

produces the following: 

m =3f04 8003 0004 0001 

mm=0fcl eOOO 0001 0000 

Classification: Intel 

Systems: MACRO 
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m_psrld 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _m_psrld(_m64 *m,_m64 *count) ; 

The 32-bit double-words in m are each independently shifted to the right by the scalar shift count in 
count. The high-order bits of each element are filled with zeros. The shift count is interpreted as 
unsigned. Shift counts greater than 31 yield all zeros. 

Shift right each 32-bit double-word in m by an amount specified in count while shifting in zeros. 


m_ empty^. m_ psrldij, m_ psrlq*. m_ psrlqi^ m_ psrlw^ m_ psrlwi 


♦include <stdio.h> 
♦include Cmmintrin.h> 


♦ define AS_ DWORDS "%8.81x %8.81x" 
♦define AS_ QWORD "%16.16Lx" 

_ m64 a; 

_m64 b = { 0x3f04800300020001 }; 

_m64 c = { 0x0000000000000002 }; 

void main() 

{ 

a = _m_psrld( b, c ) ; 
printf ( "ml = "AS_ DWORDS"\n" 

" m2 = " AS_ QWORD " \ n " 

" mm= " AS_ DWORD S " \ n " , 

b. _ 32 [1], b._ 32[0], 

c, 

a._ 32[1], a._ 32[0] ); 

} 


produces the following: 

ml=3f048003 00020001 
m2=0000000000000002 
mm=0fcl2000 00008000 


Intel 
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m_psrldi 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


♦include <mmintrin.h> 

_m64 _ m_ psrldi (_m64 *m, int count); 

The 32-bit double-words in m are each independently shifted to the right by the scalar shift count in 
count. The high-order bits of each element are filled with zeros. The shift count is interpreted as 
unsigned. Shift counts greater than 31 yield all zeros. 

Shift right each 32-bit double-word in m by an amount specified in count while shifting in zeros. 

_ m_ empty^. m_ psrlcL m_ psrlq^ m_ psrlqi^ m_ psrlw^ m_ psrlwi 

♦include <stdio.h> 

♦include <mmintrin.h> 

♦define AS_ DWORDS "%8.81x %8.81x" 


m64 a; 

m64 b = { 0x3f04800300020001 }; 


void main() 


{ 


a = _ m_ psrldi( b, 2 ) ; 
printf ( "m = "AS_ DWORDS" \n" 

" mm= " AS_ DWORD S " \ n " , 
b._ 32 [1], b._ 32[0], 
a._ 32 [1], a._ 32[0] ); 


produces the following: 

m =3f048003 00020001 
mm=0fcl2000 00008000 


Classification: Intel 
Systems: MACRO 
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m_psrlq 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _m_psrlq(_m64 *m,_m64 *count) ; 

The 64-bit quad-word in m is shifted to the right by the scalar shift count in count. The high-order bits 
are filled with zeros. The shift count is interpreted as unsigned. Shift counts greater than 63 yield all 
zeros. 

Shift right the 64-bit quad-word in m by an amount specified in count while shifting in zeros. 

_ m_ empty*. m_ psrld*. m_ psrldi*. m_ psrlqij_ m_ psrlw^ m_ psrlwi 

♦include <stdio.h> 

♦include <mmintrin.h> 

♦define AS_ QWORD "%16.16Lx" 

_ m64 a; 

_m64 b = { 0x3f04800300020001 }; 

_m64 c = { 0x0000000000000002 }; 

void main() 

{ 

a = _m_psrlq( b, c ) ; 
printf ( "ml = "AS_ QWORD"\n" 

" m2 = " AS_ QWORD " \ n " 

" mm= " AS_ QWORD " \ n " , 
b, c, a ) ; 

} 

produces the following: 

ml=3f04800300020001 
m2=0000000000000002 
mm=0fcl2000c0008000 

Intel 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


m_psrlqi 


♦include <mmintrin.h> 

_m64 _ m_ psrlqi (_m64 *m, int count); 

The 64-bit quad-word in m is shifted to the right by the scalar shift count in count. The high-order bits 
are filled with zeros. The shift count is interpreted as unsigned. Shift counts greater than 63 yield all 
zeros. 

Shift right the 64-bit quad-word in m by an amount specified in count while shifting in zeros. 

_ m_ empty^. m_ psrlcL m_ psrldij, m_ psrlq^ m_ psrlw^ m_ psrlwi 

♦include <stdio.h> 

♦include <mmintrin.h> 

♦define AS_ QWORD "%16.16Lx" 

_ m64 a; 

_m64 b = { 0x3f04800300020001 }; 

void main() 

{ 

a = _ m_ psrlqi( b, 2 ) ; 
printf ( "m ="AS_ QWORD"\n" 

" mm= " AS_ QWORD " \ n " , 
b, a ) ; 

} 

produces the following: 

m =3f04800300020001 
mm=0fc!2000c0008000 

Intel 
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m_psrlw 


Synopsis: #include <mmintrin.h> 

_m64 _m_psrlw(_m64 *m,_m64 *count) ; 

Description: The 16-bit words in m are each independently shifted to the right by the scalar shift count in count. The 
high-order bits of each element are filled with zeros. The shift count is interpreted as unsigned. Shift 
counts greater than 15 yield all zeros. 

Returns: Shift right each 16-bit word in m by an amount specified in count while shifting in zeros. 

See Also: _ m_ empty^ m_ psrlcL m_ psrldij, m_ psrlcp. m_ psrlqi^ m_ psrlwi 

Example: #include <stdio.h> 

♦include <mmintrin.h> 

♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 

♦define AS_ QWORD "%16.16Lx" 

_ m64 a; 

_m64 b = { 0x3f04800300040001 }; 

_m64 c = { 0x0000000000000002 }; 

void main() 

{ 

a = _m_psrlw( b, c ); 
printf ( "ml = "AS_ WORDS"\n" 

" m2 = " AS_ QWORD " \ n " 

" mm= " AS_ WORD S " \ n " , 

b. _ 16 [3] , b._ 16[2], b._ 16[1] , b16 [ 0 ], 

c, 

a._ 16 [3] , a 16 [2 ] , a._16[l], a._16[0] ); 

} 

produces the following: 

ml=3f04 8003 0004 0001 
m2=0000000000000002 
mm=0fcl 2000 0001 0000 

Classification: Intel 

Systems: MACRO 
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m_psrlwi 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


♦include <mmintrin.h> 

_m64 _ m_ psrlwi (_m64 *m, int count); 

The 16-bit words in m are each independently shifted to the right by the scalar shift count in count. The 
high-order bits of each element are filled with zeros. The shift count is interpreted as unsigned. Shift 
counts greater than 15 yield all zeros. 

Shift right each 16-bit word in m by an amount specified in count while shifting in zeros. 

_ m_ empty^. m_ psrlcL m_ psrldij, m_ psrlq^ m_ psrlqi^ m_ psrlw 

♦include <stdio.h> 

♦include Cmmintrin.h> 

♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 


m64 a; 

m64 b = { 0x3f04800300040001 }; 


void main() 

{ 

a = _ m_ psrlwi( b, 2 ) ; 
printf ( "m ="AS_ WORDS "\n" 

" mm= " AS_ WORD S " \ n " , 

b 16 [ 3 ] , b._ 16 [2] , b16 [ 1 ] , b._16[0], 
a._ 16 [3] , a 16 [2 ] , a._16[l], a._16[0] ); 


produces the following: 

m =3f04 8003 0004 0001 
mm=0fcl 2000 0001 0000 


Classification: Intel 
Systems: MACRO 
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m_psubb 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _ m_ psubb (_m64 *ml,_m64 *m2); 

The signed or unsigned 8-bit bytes of m2 are subtracted from the respective signed or unsigned 8-bit 
bytes of ml and the result is stored in memory. If any result element does not fit into 8 bits (underflow 
or overflow), the lower 8 bits of the result elements are stored (i.e., truncation takes place). 

The result of subtracting the packed bytes of one 64-bit multimedia value from another is returned. 

_ m_ empty^. m_ psubd*. m_ psubsb^ m_ psubsw^ m_ psubusbj, m_ psubusw^ m_ psubw 


♦include <stdio.h> 
♦include Cmmintrin.h> 


♦define AS_ BYTES "%2.2x %2.2x %2.2x %2.2x " \ 
"%2.2x %2.2x %2.2x %2.2x" 

_ m64 a; 

_m64 b = { 0x0123456789abcdef }; 

_m64 c = { 0xfedcba9876543210 }; 

void main() 

{ 

a = _ m_ psubb( b, c ); 
printf ( "ml = "AS_ BYTES"\n" 

"m2 = "AS_ BYTES"\n" 

"mm= "AS_ BYTES"\n". 


b. 

_ 8[7] , 

b. 

_ 8[6] , 

b. 

_ 8[5] , 

b. 

_ 8[4] , 

b. 

_ 8[3], 

b. 

_ 8[2] , 

b. 

_ 8[1] , 

b. 

_ 8[0] , 

c. 

_ 8[7] , 

c. 

_ 8[6] , 

c. 

_ 8[5] , 

c. 

_ 8[4] , 

c. 

_ 8[3] , 

c. 

_ 8[2] , 

c. 

_ 8[1] , 

c. 

_ 8[0] , 

a. 

_ 8[7] , 

a. 

_ 8[6] , 

a. 

_ 8[5] , 

a. 

_ 8[4] , 

a. 

_ 8[3] , 

a. 

_ 8[2] , 

a. 

_ 8[1] , 

a. 

_ 8 [ 0 ] ) ; 


produces the following: 


ml= 

=01 

23 

45 

67 

89 

ab 

cd 

ef 

m2 = 

=fe 

dc 

ba 

98 

76 

54 

32 

10 

mm= 

=03 

47 

8b 

cf 

13 

57 

9b 

df 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


m_psubd 


♦include <mmintrin.h> 

_m64 _m_psubd(_m64 *ml,_m64 *m2); 

The signed or unsigned 32-bit double-words of m2 are subtracted from the respective signed or 
unsigned 32-bit double-words of ml and the result is stored in memory. If any result element does not 
fit into 32 bits (underflow or overflow), the lower 32-bits of the result elements are stored (i.e., 
truncation takes place). 

The result of subtracting one set of packed double-words from a second set of packed double-words is 
returned. 

_ m_ empty^. m_ psubb^ m_ psubsb^ m_ psubsw^ m_ psubusbj, m_ psubusw^ m_ psubw 

♦include <stdio.h> 

♦include Cmmintrin.h> 

♦ define AS_ DWORDS "%8.81x %8.81x" 

_ m64 a; 

_m64 b = { 0x0123456789abcdef }; 

_m64 c = { 0xfedcba9876543210 }; 

void main() 

{ 

a = _m_psubd( b, c ) ; 
printf ( "ml = "AS_ DWORDS"\n" 

" m2 = " AS_ DWORD S " \ n " 

" mm= " AS_ DWORD S " \ n " , 
b._ 32 [1] , b._ 32[0] , 
c 32 [ 1], c32[0], 
a._ 32[1] , a._ 32[0] ); 

} 

produces the following: 

ml=01234567 89abcdef 
m2=fedcba98 76543210 
mm=02468acf 13579bdf 

Intel 
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m_psubsb 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _ m_ psubsb (_m64 *ml,_m64 *m2); 

The signed 8-bit bytes of m2 are subtracted from the respective signed 8-bit bytes of ml and the result is 
stored in memory. Saturation occurs when a result exceeds the range of a signed byte. In the case 
where a result is a byte larger than 0x7f (overflow), it is clamped to 0x7f. In the case where a result is a 
byte smaller than 0x80 (underflow), it is clamped to 0x80. 

The result of subtracting the packed signed bytes, with saturation, of one 64-bit multimedia value from 
a second multimedia value is returned. 


m_ empty^ m_ psubb^ m_ psubcL m_ psubsw^ m_ psubusbj, m_ psubusw^ m_ psubw 


♦include <stdio.h> 

♦include Cmmintrin.h> 

♦define AS_ BYTES "%2.2x %2.2x %2.2x %2.2x " \ 
"%2.2x %2.2x %2.2x %2.2x" 

_ m64 a; 

_m64 b = { 0x8aacceef02244668 }; 

_m64 c = { 0x76543211fedcba98 }; 

void main() 

{ 

a = _ m_ psubsb( b, c ) ; 
printf ( "ml = "AS_ BYTES"\n" 

"m2 = "AS_ BYTES"\n" 

"mm= "AS_ BYTES"\n". 


b. 

_ 8[7] , 

b. 

_ 8[6] , 

b. 

_ 8[5] , 

b. 

_ 8[4] , 

b. 

_ 8[3], 

b. 

_ 8[2] , 

b. 

_ 8[1] , 

b. 

_ 8[0] , 

c. 

_ 8[7] , 

c. 

_ 8[6] , 

c. 

_ 8[5] , 

c. 

_ 8[4] , 

c. 

_ 8[3] , 

c. 

_ 8[2] , 

c. 

_ 8[1] , 

c. 

_ 8[0] , 

a. 

_ 8[7] , 

a. 

_ 8[6] , 

a. 

_ 8[5] , 

a. 

_ 8[4] , 

a. 

_ 8[3] , 

a. 

_ 8[2] , 

a. 

_ 8[1] , 

a. 

_ 8 [ 0 ] ) ; 


produces the following: 


ml= 

=8a 

ac 

ce 

ef 

02 

24 

46 

68 

m2 = 

=76 

54 

32 

11 

fe 

dc 

ba 

98 

mm= 

=80 

80 

9c 

de 

04 

48 

If 

7 f 
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m_psubsw 


Synopsis: #include <mmintrin.h> 

_m64 _ ra_ psubsw (_m64 *ml,_m64 *m2); 

Description: The signed 16-bit words of m2 are subtracted from the respective signed 16-bit words of ml and the 

result is stored in memory. Saturation occurs when a result exceeds the range of a signed word. In the 
case where a result is a word larger than 0x7fff (overflow), it is clamped to 0x7fff. In the case where a 
result is a word smaller than 0x8000 (underflow), it is clamped to 0x8000. 

Returns: The result of subtracting the packed signed words, with saturation, of one 64-bit multimedia value from 

a second multimedia value is returned. 

See Also: _ m_ empty^ m_ psubb^ m_ psubck. m_ psubsbj, m_ psubusbj, m_ psubusw^ m_ psubw 

Example: ((include <stdio.h> 

♦include <mmintrin.h> 

♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 

_ m64 a; 

_m64 b = { 0x8aacceef02244668 }; 

_m64 c = { 0x76543211fedcba98 }; 

void main () 

{ 

a = _ m_ psubsw( b, c ) ; 
printf ( "ml = "AS_ WORDS"\n" 

" m2 = " AS_ WORD S " \ n " 

" mm= " AS_ WORD S " \ n " , 

b 16 [3] , b._ 16 [2] , b 16 [ 1 ] , b._16[0], 

c._ 16 [3], c16[2], c._ 16[1], c16[0], 
a._ 16 [3] , a 16 [2 ] , a._16[l], a._16[0] ); 

} 

produces the following: 

ml=8aac ceef 0224 4668 
m2=7654 3211 fedc ba98 
mm=8000 9cde 0348 7fff 

Classification: Intel 

Systems: MACRO 
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m_psubusb 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _ m_ psubusb (_m64 *ml,_m64 *m2); 

The unsigned 8-bit bytes of m2 are subtracted from the respective unsigned 8-bit bytes of ml and the 
result is stored in memory. Saturation occurs when a result is less than zero. If a result is less than zero, 
it is clamped to Oxff. 

The result of subtracting the packed unsigned bytes, with saturation, of one 64-bit multimedia value 
from a second multimedia value is returned. 


m_ empty^. m_ psubb^ m_ psubcL m_ psubsbj, m_ psubsw^ m_ psubusw^ m_ psubw 


♦include <stdio.h> 

♦include Cmmintrin.h> 

♦define AS_ BYTES "%2.2x %2.2x %2.2x %2.2x " \ 
"%2.2x %2.2x %2.2x %2.2x" 

_ m64 a; 

_m64 b = { 0x8aacceef02244668 }; 

_m64 c = { 0x7 6543211fedcba98 }; 

void main() 

{ 

a = _ m_ psubusb( b, c ); 
printf ( "ml = "AS_ BYTES"\n" 

"m2 = "AS_ BYTES"\n" 

"mm= "AS_ BYTES"\n". 


b. 

_ 8 [7] , 

b. 

_ 8[6], 

b. 

_ 8[5] , 

b. 

_ 8[4] , 

b. 

_ 8 [3] , 

b. 

_ 8[2] , 

b. 

_ 8 [1] , 

b. 

_ 8[0] , 

c. 

_ 8 [7] , 

c. 

_ 8[6] , 

c. 

_ 8 [5] , 

c. 

_ 8[4] , 

c. 

_ 8 [3] , 

c. 

_ 8[2] , 

c. 

_ 8[1] , 

c. 

_ 8[0] , 

a. 

_ 8 [7] , 

a. 

_ 8[6], 

a. 

_ 8 [5] , 

a. 

_ 8[4] , 

a. 

_ 8 [3] , 

a. 

_ 8[2] , 

a. 

_ 8[1] , 

a. 

_ 8 [ 0 ] ) ; 


produces the following: 


ml= 

=8a 

ac 

ce 

ef 

02 

24 

46 

68 

m2 = 

=76 

54 

32 

11 

fe 

dc 

ba 

98 

mm= 

= 14 

58 

9c 

de 

00 

00 

00 

00 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


m_psubusw 


♦include <mmintrin.h> 

_m64 _ m_ psubusw (_m64 *ml,_m64 *m2); 

The unsigned 16-bit words of m2 are subtracted from the respective unsigned 16-bit words of ml and 
the result is stored in memory. Saturation occurs when a result is less than zero. If a result is less than 
zero, it is clamped to Oxffff. 

The result of subtracting the packed unsigned words, with saturation, of one 64-bit multimedia value 
from a second multimedia value is returned. 

_ m_ empty^ m_ psubb^ m_ psubcL m_ psubsbj, m_ psubsw^ m_ psubusbj, m_ psubw 

♦include <stdio.h> 

♦include Cmmintrin.h> 

♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 

_ m64 a; 

_m64 b = { 0x8aacceef02244668 }; 

_m64 c = { 0x76543211fedcba98 }; 

void main() 

{ 

a = _ ra_ psubusw( b, c ); 
printf ( "ml = "AS_ WORDS"\n" 

" m2 = " AS_ WORD S " \ n " 

" mm= " AS_ WORD S " \ n " , 


b. 

16[3], 

b. 

16[2], 

b. 

16[1], 

b. 

16[0], 

c. 

16[3], 

c. 

1612], 

c. 

16 [ 1 ] , 

c. 

16[0], 

a. 

16 [3] , 

a. 

16[2], 

a. 

16 [ 1 ] , 

a. 

16 [0] ); 


} 

produces the following: 

ml=8aac ceef 0224 4668 
m2=7654 3211 fedc ba98 
mm=1458 9cde 0000 0000 

Intel 
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m_psubw 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _ m_ psubw (_m64 *ml,_m64 *m2); 

The signed or unsigned 16-bit words of m2 are subtracted from the respective signed or unsigned 16-bit 
words of ml and the result is stored in memory. If any result element does not fit into 16 bits 
(underflow or overflow), the lower 16 bits of the result elements are stored (i.e., truncation takes place). 

The result of subtracting the packed words of two 64-bit multimedia values is returned. 

_ m_ empty^. m_ psubb^ m_ psubck. m_ psubsbj, m_ psubsw^ m_ psubusbj, m_ psubusw 


♦include <stdio.h> 
♦include Cmmintrin.h> 


♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 


_ m64 a; 

_m64 b = { 0x0123456789abcdef }; 

_m64 c = { 0xfedcba9876543210 }; 

void main() 

{ 

a = _ m_ psubw( b, c ) ; 
printf ( "ml = "AS_ WORDS"\n" 

" m2 = " AS_ WORD S " \ n " 

" mm= " AS_ WORD S " \ n " , 


b. 

16 [3] , 

b. 

1612], 

b. 

16 [ 1 ] , 

b. 

16[0], 

c. 

16[3], 

c. 

16[2], 

c. 

16 [ 1 ] , 

c. 

16 [0] , 

a. 

16[3], 

a. 

16[2], 

a. 

16 [ 1 ] , 

a. 

_ 16 [0] ); 


produces the following: 

ml=0123 4567 89ab cdef 
m2=fedc ba98 7654 3210 
mm=0247 8acf 1357 9bdf 

Intel 
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Synopsis: 

Description: 


Returns: 
See Also: 

Example: 


m_punpckhbw 


♦include <mmintrin.h> 

_m64 _ m_ punpckhbw (_m64 *ml,_m64 *m2); 

The _ m_ punpckhbw function performs an interleaved unpack of the high-order data elements of ml 
and m2. It ignores the low-order bytes. When unpacking from a memory operand, the full 64-bit 
operand is accessed from memory but only the high-order 32 bits are utilized. By choosing ml or m2 to 
be zero, an unpacking of byte elements into word elements is performed. 

m2 ml 


b7 b6 b5 b4 b3 b2 bl bO 


V V V V 
b7 b5 b3 bl 


b7 b6 b5 b4 b3 b2 bl bO 


V V V V 
b6 b4 b2 bO 


b7 b6 b5 b4 b3 b2 bl bO 


result 


The result of the interleaved unpacking of the high-order bytes of two multimedia values is returned. 


m_ empty^ m_ punpckhdcp. m_ punpckhwck. m_ punpcklbw^ m_ punpckldq, 
m_ punpcklwd 


♦include <stdio.h> 
♦include <mmintrin.h> 


♦define AS_ BYTES "%2.2x %2.2x %2.2x %2.2x " \ 
"%2.2x %2.2x %2.2x %2.2x" 

_ m64 a; 

_m64 b = { 0x0004000300020001 }; 

_m64 c = { 0xff7fff800080007f }; 

void main() 

{ 

a = _ m_ punpckhbw( b, c ); 
printf ( "m2 = "AS_ BYTES" " 

"ml = "AS_ BYTES"\ n" 

"mm= "AS_ BYTES"\n". 


c. 

_ 8[7] , 

c. 

_ 8[6] , 

c. 

_ 8[5] , 

c. 

_ 8[4] , 

c. 

_ 8[3], 

c. 

_ 8[2] , 

c. 

_ 8[1] , 

c. 

_ 8[0] , 

b. 

_ 8[7] , 

b. 

_ 8[6] , 

b. 

_ 8[5] , 

b. 

_ 8[4] , 

b. 

_ 8[3] , 

b. 

_ 8[2] , 

b. 

_ 8[1] , 

b. 

_ 8[0] , 

a. 

_ 8[7] , 

a. 

_ 8[6] , 

a. 

_ 8[5] , 

a. 

_ 8[4] , 

a. 

_ 8[3] , 

a. 

_ 8[2] , 

a. 

_ 8[1], 

a. 

_ 8 [ 0 ] ) ; 


} 

produces the following: 

m2=ff 7f ff 80 00 80 00 7f ml=00 04 00 03 00 02 00 01 
mm=ff 00 7f 04 ff 00 80 03 
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m_punpckhbw 


Classification: Intel 
Systems: MACRO 
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Synopsis: 

Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


m_punpckhdq 


♦include <mmintrin.h> 

_m64 _ m_ punpckhdq (_m64 *ml,_m64 *m2); 

The _ m_ punpckhdq function performs an interleaved unpack of the high-order data elements of ml 
and m2. It ignores the low-order double-words. When unpacking from a memory operand, the full 
64-bit operand is accessed from memory but only the high-order 32 bits are utilized. 

m2 ml 


dl 


dO 


dl 


dO 


V V 

dl dO 


dl 


dO 


result 


The result of the interleaved unpacking of the high-order double-words of two multimedia values is 
returned. 


m_ empty^ m_ punpckhbw^ m_ punpckhwck. m_ punpcklbw^ m_ punpckldq, 
m_ punpcklwd 


♦include <stdio.h> 

♦include <mmintrin.h> 

♦define AS_ DWORDS "%8.81x %8.81x" 

_ m64 a; 

_m64 b = { 0x0004000300020001 }; 

_m64 c = { 0xff7fff800080007f }; 


void main() 

{ 

a = _ m_ punpckhdq( b, c ) ; 
printf ( "m2 = "AS_ DWORDS" " 
"ml = "AS_ DWORDS "\ n" 

" mm= " AS_ DWORD S " \ n " , 
c 32 [ 1], c32[0], 
b._ 32[1], b._ 32[0] , 
a._ 32[1], a._ 32[0] ); 


produces the following: 


m2=ff7fff80 0080007f ml=00040003 00020001 
mm=ff7fff80 00040003 


Intel 

MACRO 
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m_punpckhwd 


Synopsis: 

Description: 


Returns: 
See Also: 

Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _ m_ punpckhwd (_m64 *ml,_m64 *m2); 

The _ m_ punpckhwd function performs an interleaved unpack of the high-order data elements of ml 
and m2. It ignores the low-order words. When unpacking from a memory operand, the full 64-bit 
operand is accessed from memory but only the high-order 32 bits are utilized. By choosing ml or m2 to 
be zero, an unpacking of word elements into double-word elements is performed. 

m2 ml 


w3 | 

w2 | 

wl | 

wO | 

w3 | 

w2 | 

wl | 

wO | 

V 

V 



V 

V 



w3 

wl 



w2 

wO 





w3 | 

w2 | 

wl | 

wO | 




result 


The result of the interleaved unpacking of the high-order words of two multimedia values is returned. 


m_ empty^ m_ punpckhbw^ m_ punpckhdcp. m_ punpcklbw^ m_ punpckldq, 
m_ punpcklwd 


♦include <stdio.h> 
♦include <mmintrin.h> 


♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 


_ m64 a; 

_m64 b = { 0x0004000300020001 }; 

_m64 c = { 0xff7fff800080007f }; 

void main() 

{ 

a = _ m_ punpckhwd( b, c ) ; 
printf ( "m2 = "AS_ WORDS" " 

"ml = "AS_ WORDS"\ n" 

" mm= " AS_ WORD S " \ n " , 


C . 

16[3], 

c. 

16[2], 

c. 

16[1], 

c. 

16 [0] , 

b. 

16[3], 

b. 

16[2], 

b. 

16 [ 1 ] , 

b. 

16[0], 

a. 

16[3], 

a. 

16[2], 

a. 

16 [ 1 ] , 

a. 

16[0] ); 


produces the following: 

m2=ff7f ff80 0080 007f ml=0004 0003 0002 0001 
mm=ff7f 0004 ff80 0003 


Intel 

MACRO 
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Synopsis: 

Description: 


Returns: 
See Also: 

Example: 


m_punpcklbw 


♦include <mmintrin.h> 

_m64 _ m_ punpcklbw (_m64 *ml,_m64 *m2); 

The _ m_ punpcklbw function performs an interleaved unpack of the low-order data elements of ml 
and m2. It ignores the high-order bytes. When unpacking from a memory operand, 32 bits are accessed 
and all are utilized by the instruction. By choosing ml or m2 to be zero, an unpacking of byte elements 
into word elements is performed. 

m2 ml 


b3 b2 bl bO b7 b6 b5 b4 b3 b2 bl bO 


V V V V 
b7 b5 b3 bl 


V V V V 
b6 b4 b2 bO 


b7 b6 b5 b4 b3 b2 bl bO 


result 


The result of the interleaved unpacking of the low-order bytes of two multimedia values is returned. 


m_ empty^ m_ punpckhbw^ m_ punpckhdcp. m_ punpckhwcL m_ punpckldq, 
m_ punpcklwd 


♦include <stdio.h> 
♦include <mmintrin.h> 


♦define AS_ BYTES "%2.2x %2.2x %2.2x %2.2x " \ 
"%2.2x %2.2x %2.2x %2.2x" 

_ m64 a; 

_m64 b = { 0x000200013478bcf0 }; 

_m64 c = { 0x0080007f12569ade }; 

void main() 

{ 

a = _ m_ punpcklbw( b, c ) ; 
printf ( "m2 = "AS_ BYTES" " 

"ml = "AS_ BYTES"\ n" 

"mm= "AS_ BYTES"\n". 


c. 

_ 8[7] , 

c. 

_ 8[6] , 

c._ 8 [5] , 

c. 

_ 8[4] , 

c. 

_ 8[3], 

c. 

_ 8[2] , 

c._ 8 [1] , 

c. 

_ 8[0] , 

b. 

_ 8[7] , 

b. 

_ 8[6] , 

b8 [5] , 

b. 

_ 8[4] , 

b. 

_ 8[3] , 

b. 

_ 8 [2] , 

b8 [1] , 

b. 

_ 8[0] , 

a. 

_ 8[7] , 

a. 

_ 8[6] , 

a8 [5] , 

a. 

_ 8[4] , 

a. 

_ 8[3] , 

a. 

_ 8[2] , 

a8 [1] , 

a. 

_ 8 [ 0 ] ) ; 


} 

produces the following: 

m2=00 80 00 7f 12 56 9a de ml=00 02 00 01 34 78 be fO 
mm=12 34 56 78 9a be de fO 
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m_punpcklbw 


Classification: Intel 
Systems: MACRO 
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Synopsis: 

Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


m_punpckldq 


♦include <mmintrin.h> 

_m64 _ m_ punpckldq (_m64 *ml,_m64 *m2); 

The _ m_ punpckldq function performs an interleaved unpack of the low-order data elements of ml 
and m2. It ignores the high-order double-words. When unpacking from a memory operand, 32 bits are 
accessed and all are utilized by the instruction. 

m2 ml 


dl 


dO 


dl 


dO 


V V 

dl dO 


dl 


dO 


result 


The result of the interleaved unpacking of the low-order double-words of two multimedia values is 
returned. 


m_ empty^ m_ punpckhbw^ m_ punpckhdq^ m_ punpckhwcL m_ punpcklbw, 
m_ punpcklwd 


♦include <stdio.h> 

♦include Cmmintrin.h> 

♦define AS_ DWORDS "%8.81x %8.81x" 

_ m64 a; 

_m64 b = { 0x0004000300020001 }; 

_m64 c = { 0xff7fff800080007f }; 


void main() 

{ 

a = _ m_ punpckldq( b, c ) ; 
printf ( "m2 = "AS_ DWORDS" " 
"ml = "AS_ DWORDS "\ n" 

" mm= " AS_ DWORD S " \ n " , 
c 32 [ 1], c32[0], 
b._ 32[1], b._ 32[0] , 
a._ 32[1], a._ 32[0] ); 


produces the following: 


m2=ff7fff80 0080007f ml=00040003 00020001 
mm=0080007f 00020001 


Intel 

MACRO 
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m_punpcklwd 


Synopsis: 

Description: 


Returns: 
See Also: 

Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

_m64 _ m_ punpcklwd (_m64 *ml,_m64 *m2); 

The _ m_ punpcklwd function performs an interleaved unpack of the low-order data elements of ml 
and m2. It ignores the high-order words. When unpacking from a memory operand, 32 bits are 
accessed and all are utilized by the instruction. By choosing ml or m2 to be zero, an unpacking of word 
elements into double-word elements is performed. 

m2 ml 


w3 w2 wl wO 


w3 w2 wl wO 


V V 

w3 wl 


V V 
w2 wO 


w3 w2 wl wO 


result 


The result of the interleaved unpacking of the low-order words of two multimedia values is returned. 


m_ empty^ m_ punpckhbw^ m_ punpckhdcp. m_ punpckhwcL m_ punpcklbw, 
m_ punpckldq 


♦include <stdio.h> 
♦include <mmintrin.h> 


♦define AS_ WORDS "%4.4x %4.4x %4.4x %4.4x" 


_ m64 a; 

_m64 b = { 0x0004000300020001 }; 

_m64 c = { 0xff7fff800080007f }; 

void main() 

{ 

a = _ m_ punpcklwd( b, c ) ; 
printf ( "m2 = "AS_ WORDS" " 

"ml = "AS_ WORDS"\ n" 

" mm= " AS_ WORD S " \ n " , 


c. 

16 [3], 

c. 

16[2], 

c. 

16[1], 

c. 

16 [0] , 

b. 

16 [3], 

b. 

16[2], 

b. 

16 [ 1 ] , 

b. 

16 [0] , 

a. 

16 [3] , 

a. 

16[2], 

a. 

16 [ 1 ] , 

a. 

16 [0] ); 


produces the following: 

m2=ff7f ff80 0080 007f ml=0004 0003 0002 0001 
mm=0080 0002 007f 0001 


Intel 

MACRO 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


m_pxor 


♦include <mmintrin.h> 

_m64 _ m_ pxor (_m64 *ml,_m64 *m2); 

A bit-wise logical XOR is performed between 64-bit multimedia operands ml and m2 and the result is 
stored in memory. 

The bit-wise logical exclusive OR of two 64-bit values is returned. 


m_ empty^ m_ pancL m_ pandn^ m_ por 


♦include <stdio.h> 

♦include Cmmintrin.h> 

♦define AS_ QWORD "%16.16Lx" 

_ m64 a; 

_m64 b = { 0x0123456789abcdef }; 

_m64 c = { 0xfedcba9876543210 }; 


void main() 

{ 

a = _ m_ 
printf( 


} 


pxor( b, c ); 

"ml = "AS_ QWORD"\n" 

" m2 = " AS_ QWORD " \ n " 

" mm= " AS_ QWORD " \ n " , 


b, c, a ) ; 


produces the following: 

ml=0123456789abcdef 
m2=fedcba9876543210 
mm=ffffffffffffffff 


Intel 


MACRO 
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msize Functions 


Synopsis: #include <malloc.h> 

size_ t _ msize( void ^buffer ); 

size_ t _ bmsize (_segment seg, void_based (void) *buffer ); 

size__ t _ fmsize ( void_far *buffer ); 

size_ t _ nmsize ( void_near *buffer ); 

Description: The _ msize functions return the size of the memory block pointed to by buffer that was allocated by a 
call to the appropriate version of the calloc, malloc, or realloc functions. 

You must use the correct _ msize function as listed below depending on which heap the memory block 
belongs to. 

Function Heap 

jnsize Depends on data model of the program 

_bmsize Based heap specified by seg value 

ffmsize Far heap (outside the default data segment) 
junsize Near heap (inside the default data segment) 

In small data models (small and medium memory models), _ msize maps to_ nmsize. In large data 
models (compact, large and huge memory models), _msize maps to _ fmsize. 

Returns: The _ msize functions return the size of the memory block pointed to by buffer. 

See Also: calloc Functions, _ expand Functions,free Functions, halloc, hfree, malloc Functions, 

realloc Functions, sbrk 


Example: ((include <stdio.h> 

((include <malloc.h> 

void main() 

{ 

void *buffer; 


} 


buffer = malloc( 999 ); 
printf ( "Size of block is %u bytes\n", 
_ msize( buffer ) ); 


produces the following: 

Size of block is 1000 bytes 

Classification: WATCOM 


Systems: _ msize - All, Linux, RDOS, Netware 

_bmsize - DOS/16, Windows, OS/2 l.x(all) 

_ fmsize - DOS/16, Windows, OS/2 l.x(all) 

_ nmsize - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 l.x(MT), 
OS/2-32, Linux, RDOS 
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msync 


Synopsis: 

Description: 


Returns: 

Errors: 


See Also: 

Classification: 

Systems: 


♦include <sys/mman.h> 

int msync(void *address, size_t len, int flags) 

The msync function writes all modified data to permanent storage corresponding to the memory 
mapping at address measuring len bytes. 

The flags argument may be one or a combination of the following: 

Constant Meaning 

MS_ASYNC Perform asynchronous writes 

MS_SYNC Perform synchronous writes 

MS_INVALIDATE Invalidate any cached data 

The flags MS_ ASYNC andMS_ SYNC may not be combined. 

If successful, the function will return 0. Upon failure, the function will return -1, and errno will be set 
appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINVAL The argument address is not a multiple of the page size or the flags argument is invalid 

ENOMEM The arguments do not correspond to a region of the process’s address space or exceed the 
process’s address space 

EBUSY A portion of or all of the address space specified is currently locked 
mlock, mlockall, mmap, munlock, munlockall, munmap 
POSIX 
Linux 
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_m_tojnt 

Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <mmintrin.h> 

int _ m_ to_ int (_m64 *_m) ; 

The _ m_ to_ int function returns the low-order 32 bits of a multimedia value. 

The low-order 32 bits of a multimedia value are fetched and returned as the result. 

_ m_ empty^. m_ from_ int,m_ packsswbj, m_ paddbj_ m_ pand*. m_ empty^. m_ pcmpeqb, 
_ m_ pmaddwcL m_ psllw^ m_ psraw^_ m_ psrlw^ m_ empty^, m_ psubb*. m_ punpckhbw 

♦include <stdio.h> 

♦include <mmintrin.h> 

_m64 b = { 0x0123456789abcdef }; 

int j; 

void main() 

{ 

j = _ m_ to_ int ( b ) ; 
printf ( "m=%16.16Lx int=%8.81x\n", 
b, j ) ; 

} 

produces the following: 
m=0123456789abcdef int=89abcdef 

Intel 

MACRO 
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munlock 


Synopsis: 

Description: 

Returns: 

Errors: 


See Also: 

Classification: 

Systems: 


♦include <sys/mman.h> 

int munlock(void *address, size_ t len) 

The munlock function causes memory located at address measuring len bytes to be released regardless 
of the number of prior calls to lock the referenced memory. 

If successful, the function will return 0. Upon failure, the function will return -1, and errno will be set 
appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINVAL The argument address is not a multiple of the page size or the len is zero or causes an 
overflow 

ENOMEM The arguments do not correspond to a region of the process’s address space 

mlock, mlockall, munlockall 

POSIX 

Linux 
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munlockall 


Synopsis: 

Description: 

Returns: 

See Also: 

Classification: 

Systems: 


♦include <sys/mman.h> 
int munlockall( ) 

The munlockall function unlocks all memory for a process. If, in the preceding call to mlockall 
function, the flag MCL_ FUTURE was specified, all future pages mapped for the process will also not be 
locked unless another call to mlockall specifies such behavior. 

If successful, the function will return 0. Upon failure, the function will return -1, and errno will be set 
appropriately. 

mlock, mlockall, munlock 

POSIX 

Linux 
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munmap 


Synopsis: 

Description: 

Returns: 

Errors: 

See Also: 

Classification: 

Systems: 


♦include <sys/mman.h> 

int munmap(void *address, size_ t len) 

The munmap function removes any mapping at the address address measuring len bytes from the 
process address space. 

If successful, the function will return 0. Upon failure, the function will return -1, and errno will be set 
appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINVAL Either one or both of the arguments was invalid. 

mmap 

POSIX 

Linux 
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nan 


Synopsis: 

Description: 

Returns: 

Example: 


Classification: 

Systems: 


♦include <math.h> 

float nanf( const char *str ) ; 

double nan( const char *str ); 

long double nanl( const char *str ); 

The nan function returns not-a-number, or NAN. The argument str is ignored. 

The proper not-a-number value. 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf( "%f\n", nan ( "") ); 

} 

produces the following: 
nan 

ISO C99 
Math 
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nearbyint 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 

double nearbyint ( double x ); 

The nearbyint function rounds the argument x to a nearby integer without the possibility of 
throwing an exception. The direction of the rounding is determined by the current value of 
f egetround. 

The rounded value of x. 

fegetround, fesetround, rint, round, trunc 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

fesetround (FE_ TONEAREST); 

printf ( "%f\n", nearbyint ( 1.2 ) ); 

} 

produces the following: 

1.000000 
ISO C99 
Math 
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nextafter 


Synopsis: #include <math.h> 

double nextafter( double x, double y ); 

Description: The nextafter function returns the next machine floating point number of x in the direction towards 

}’• 

Returns: The next representable floating point value after or before x in the direction of y. 

Example: #include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", nextafter ( 8.0, 9.0 ) ); 

} 

produces the following: 

8.000000 

Classification: ISO C99 
Systems: Math 
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riljanginfo 


Synopsis: #include <langinfo.h> 

char *nl_ langinfo( int item ); 

Description: The nl_ langinfo function retrieves language information, purportedly based on the current locale. 

The item argument specifies which language element to retrieve, and may be one of the following: 


Member 

Meaning 

CODESET 

The character 
encoding 
supported by 
this locale 

D_T_FMT 

The date and 

time format 
string 

D_FMT 

The date format 
string 

T_FMT 

The 24-hour 

time format 
string 

TFMTAMPM 

The 12-hour 

time format 
string 

AM_STR 

The string 

representing 

ante-meridiem 

time 

PM_STR 

The string 
representing 
post-meridiem 
time 

DAY_1 

The name of the 
first day of the 
week 

DAY_2 

The name of the 
second day of 
the week 

DAY_3 

The name of the 
third day of the 
week 

DAY_4 

The name of the 
fourth day of the 
week 
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riljanginfo 


DAY_5 


DAY_6 


DAY_7 


ABDAY_1 


ABDAYJ2 


ABDAY_3 


ABDAY_4 


ABDAY_5 


ABDAYJ6 


ABDAYJ7 


MON_l 


MON_2 


The name of the 
fifth day of the 
week 

The name of the 
sixth day of the 
week 

The name of the 
seventh day of 
the week 

The abbreviated 
name of the first 
day of the week 

The abbreviated 
name of the 
second day of 
the week 

The abbreviated 
name of the 
third day of the 
week 

The abbreviated 
name of the 
fourth day of the 
week 

The abbreviated 
name of the fifth 
day of the week 

The abbreviated 
name of the 
sixth day of the 
week 

The abbreviated 
name of the 
seventh day of 
the week 

The name of the 
first month of 
the year 

The name of the 
second month of 
the year 
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riljanginfo 


MON_3 


MON_4 


MON_5 


MON_6 


MONJ7 


MON_8 


MON_9 


MON_10 


MONJ1 


MON_12 


ABMON_1 


ABMON2 


ABMON_3 


The name of the 
third month of 
the year 

The name of the 
fourth month of 
the year 

The name of the 
fifth month of 
the year 

The name of the 
sixth month of 
the year 

The name of the 
seventh month 
of the year 

The name of the 
eighth month of 
the year 

The name of the 
ninth month of 
the year 

The name of the 
tenth month of 
the year 

The name of the 
eleventh month 
of the year 

The name of the 
twelfth month of 
the year 

The abbreviated 
name of the first 
month of the 
year 

The abbreviated 
name of the 
second month of 
the year 

The name of the 
third month of 
the year 
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riljanginfo 


ABMON_4 

ABMON_5 

ABMON_6 

ABMON7 

ABMON_8 

ABMON_9 

ABMONJO 

ABMONJ1 

ABMON_12 

RADIXCHAR 

THOUSEP 

YESEXPR 


The abbreviated 
name of the 
fourth month of 
the year 

The abbreviated 
name of the fifth 
month of the 
year 

The abbreviated 
name of the 
sixth month of 
the year 

The abbreviated 
name of the 
seventh month 
of the year 

The abbreviated 
name of the 
eighth month of 
the year 

The abbreviated 
name of the 
ninth month of 
the year 

The abbreviated 
name of the 
tenth month of 
the year 

The abbreviated 
name of the 
eleventh month 
of the year 

The abbreviated 
name of the 
twelfth month of 
the year 

The radix 
character 

The separator 
for thousands 

The string for 
indicating 
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riljanginfo 


Returns: 

Classification: 

Systems: 


affirmative 

responses 

NOEXPR The string for 

indicating 

negative 

responses 

In the default locale (C), some values may be U.S.A.-centric, specifically the RADIXCHAR and 
THOUSEP. Additionally, names are in English presently. 

The function returns a pointer to a statically allocated string that must not be freed. If item is either 
unsupported or unknown, an empty string will be returned. 

POSIX 

Linux 
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nosound 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <i86.h> 
void nosound( void ); 

The nosound function turns off the PC's speaker. 

The nosound function has no return value. 

delay, sound 

♦include <i86.h> 

void main() 

{ 

sound( 200 ); 

delay( 500 ); /* delay for 1/2 second */ 

nosound(); 


Intel 

DOS, Windows, Win386 
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offsetof 


Synopsis: 

Description: 

Returns: 

Example: 


Classification: 

Systems: 


#include <stddef.h> 

size_ t offsetof( composite, name ); 

The offsetof macro returns the offset of the element name within the struct or union composite. 
This provides a portable method to determine the offset. 

The offsetof function returns the offset of name. 

♦include <stdio.h> 

♦include <stddef.h> 

struct new_ def 
{ char *first; 

char second[10]; 
int third; 

} ; 


void main() 

{ 

printf ( "first:%d second:%d third:%d\n", 
offsetof ( struct new_ def, first ), 
offsetof ( struct new_ def, second ), 
offsetof ( struct new_ def, third ) ); 


produces the following: 

In a small data model, the following would result: 

first:0 second:2 third:12 

In a large data model, the following would result: 

first:0 second:4 third:14 

ISOC 

MACRO 
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onexit 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <stdlib.h> 

onexit_ t onexit ( onexit_ t func ); 

The onexit function is passed the address of function func to be called when the program terminates 
normally. Successive calls to onexit create a list of functions that will be executed on a "last-in, 
first-out" basis. No more than 32 functions can be registered with the onexit function. 

The functions have no parameters and do not return values. 

NOTE: The onexit function is not an ISO C function. The ISO C standard function atexit does 
the same thing that onexit does and should be used instead of onexit where ISO C portability is 
concerned. 

The onexit function returns func if the registration succeeds, NULL if it fails. 

abort, atexit, exit, _ Exit,_ exit 

♦include <stdio.h> 

♦include <stdlib.h> 

void main() 

{ 

extern void fund (void) , func2 (void) , func3 (void) ; 

onexit ( fund ) ; 
onexit( func2 ); 
onexit ( func3 ); 
printf ( "Do this first.\n" ); 

} 

void fund (void) { printf ( "last.\n" ); } 

void func2(void) { printf( "this " ); } 

void func3(void) { printf( "Do " ); } 

produces the following: 

Do this first. 

Do this last. 

WATCOM 

All, Linux, RDOS, Netware 


776 Library Functions and Macros 




Synopsis: 


Description: 


open, _open, _wopen 


#include <sys/types.h> 

♦include <sys/stat.h> 

♦include <fcntl.h> 

int open( const char *path, int access, ... ); 

int _ open( const char *path, int access, ... ); 

int _ wopen ( const wchar_ t *path, int access, ... ); 

The open function opens a file at the operating system level. The name of the file to be opened is 
given by path. The file will be accessed according to the access mode specified by access. The 
optional argument is the file permissions to be used when the 0_ CREAT flag is on in the access mode. 

The _ open function is identical toopen. Use _ open for ANSI naming conventions. 

The _ wopen function is identical toopen except that it accepts a wide character string argument for 
path. 

The access mode is established by a combination of the bits defined in the <f cntl. h> header file. 
The following bits may be set: 


Mode 

0_RD0NLY 

OJWRONLY 

0_RDWR 

0_APPEND 

OJCREAT 

OJTRUNC 

0_BINARY 

OTEXT 

OJXOINHERIT 


Meaning 

permit the file to be only read. 

permit the file to be only written. 

permit the file to be both read and written. 

causes each record that is written to be written at the end of the file. 

has no effect when the file indicated by filename already exists; otherwise, 
the file is created; 

causes the file to be truncated to contain no data when the file exists; has no 
effect when the file does not exist. 

causes the file to be opened in binary mode which means that data will be 
transmitted to and from the file unchanged. 

causes the file to be opened in text mode which means that carriage-return 
characters are written before any linefeed character that is written and causes 
carriage-return characters to be removed when encountered during reads. 

indicates that this file is not to be inherited by a child process. 


0_EXCL indicates that this file is to be opened for exclusive access. If the file exists 

and 0_ CREAT was also specified then the open will fail (i.e., useO_ EXCL to 
ensure that the file does not already exist). 


When neither 0_ TEXT norO_ BINARY are specified, the default value in the global variable_ fmode 
is used to set the file translation mode. When the program begins execution, this variable has a value of 
0_ TEXT. 


0_ CREAT must be specified when the file does not exist and it is to be written. 
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open, _open, _wopen 


When the file is to be created (0_ CREAT is specified), an additional argument must be passed which 
contains the file permissions to be used for the new file. The access permissions for the file or directory 
are specified as a combination of bits (defined in the <sys /stat. h> header file). 

The following bits define permissions for the owner. 

Permission Meaning 

S_IRWXU Read, write, execute/search 

S_IRUSR Read permission 

S_IWUSR Write permission 

S_IXUSR Execute/search permission 

The following bits define permissions for the group. 

Permission Meaning 

S_IRWXG Read, write, execute/search 

S_IRGRP Read permission 

S_IWGRP Write permission 

S_IXGRP Execute/search permission 

The following bits define permissions for others. 

Permission Meaning 

S_IRWXO Read, write, execute/search 

S_IROTH Read permission 

S_IWOTH Write permission 

S_IXOTH Execute/search permission 

The following bits define miscellaneous permissions used by other implementations. 

Permission Meaning 

SJREAD is equivalent to S_IRUSR (read permission) 

SJWRITE is equivalent to S_IWUSR (write permission) 

S_IEXEC is equivalent to S_IXUSR (execute/search permission) 

All files are readable with DOS; however, it is a good idea to set S_ I READ when read permission is 
intended for the file. 

The open function applies the current file permission mask to the specified permissions (see umask). 

Returns: If successful, open returns a handle for the file. When an error occurs while opening the file, -1 is 

returned. 

Errors: When an error has occurred, errno contains a value indicating the type of error that has been detected. 
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See Also: 


Example: 


Classification: 


Systems: 


open, _open, _wopen 


Constant 

EACCES 

EMFILE 

ENOENT 


Meaning 

Access denied because path specifies a directory or a volume ID, or attempting to 
open a read-only file for writing 

No more handles available (too many open files) 

Path or file not found 


chsize, close, creat, dup, dup2, eof, exec. . ., fdopen, filelength, fileno, fstat, 
_ grow_ handlesisatty, Iseek, read, setmode, sopen, stat, tell, write, umask 

♦include <sys/stat.h> 

♦include <sys/types.h> 

♦include <fcntl.h> 

void main() 

{ 

int handle; 

/* open a file for output */ 

/* replace existing file if it exists */ 

handle = open( "file", 

0_ WRONLY | 0_ CREAT | 0_ TRUNC, 

S_ IRUSR | S_ IWUSR | S_ IRGRP | S_ IWGRP ) ; 

/* read a file which is assumed to exist */ 

handle = open ( "file", 0_ RDONLY ); 

/* append to the end of an existing file */ 

/* write a new file if file does not exist */ 

handle = open( "file", 

0_ WRONLY | 0_ CREAT | 0_ APPEND, 

S_ IRUSR | S_ IWUSR | S_ IRGRP | S_ IWGRP ); 

} 

POSIX 1003.1 

_open conforms to ANSI naming conventions 
_wopen is WATCOM 

open - All, Linux, RDOS, Netware 

_ open - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ wopen - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, Linux 


Library Functions and Macros 779 




opendir, _wopendir 


Synopsis: #include <direct.h> 

DIR *opendir( const char *dirname ); 

WDIR *_ wopendir ( const wchar_ t *dirname ) ; 


Description: The opendir function is used in conjunction with the functions readdir and closedir to obtain 
the list of file names contained in the directory specified by dirname. The path indicated by dirname 
can be either relative to the current working directory or it can be an absolute path name. As an 
extension to POSIX, the last part of dirname can contain the characters ’?' and for matching 
multiple files within a directory. 


The file <direct. h> contains definitions for the structure dirent. 


#if defined!_0S2_) || defined!_NT_) 

♦ define NAME_ MAX 255 /* maximum for HPFS or NTFS */ 

♦ else 


♦ define NAME_ MAX 12 /* 

♦endif 

struct dirent { 

char d_dta[ 21 ]; 
char d_ attr; 

unsigned short int d_ time; 
unsigned short int d_ date; 
long d_ size; 

char d_ name [ NAME_ MAX 

unsigned short d_ ino; 
char d_ first; 

} ; 


8 chars + '.' + 3 chars */ 


/* disk transfer area */ 
/* file's attribute */ 

/* file's time */ 

/* file's date */ 

/* file's size */ 

+ 1 ]; /* file's name */ 

/* serial number */ 

/* flag for 1st time */ 


The file attribute field d_ attr field is a set of bits representing the following attributes. 


A_ RDONLY 
A_ HIDDEN 
A_ SYSTEM 
A_ VOL ID 
A_ SUBDIR 
A_ ARCH 


/* Read-only file */ 

/* Hidden file */ 

/* System file */ 

/* Volume-ID entry (only MSFT knows) */ 
/* Subdirectory */ 

/* Archive file */ 


If the _ A_ RDONLY bit is off, then the file is read/write. 

The format of the d_ time field is described by the following structure (this structure is not defined in 
any Open Watcom header file). 

typedef struct { 


unsigned 

short 

twosecs 

5; 

/* 

seconds 

/ 2 */ 

unsigned 

short 

minutes 

6; 

/* 

minutes 

(0,59) 

unsigned 

short 

hours 

5; 

/* 

hours (0 

,23) * 


} ftime_ t; 

The format of the d_ date field is described by the following structure (this structure is not defined in 
any Open Watcom header file). 
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opendir, _wopendir 


typedef struct { 


unsigned 

short 

day 

: 5; 

/* 

day (1,31) */ 

unsigned 

short 

month 

: 4; 

/* 

month (1,12) */ 

unsigned 

short 

year 

: 7; 

/* 

0 is 1980 */ 


} fdate_ t; 

See the sample program below for an example of the use of these structures. 

More than one directory can be read at the same time using the opendir, readdir, and closedir 
functions. 

The _ wopendir function is identical toopendir except that it accepts a wide-character string 
argument and returns a pointer to a _ wdirent structure that can be used with the_ wreaddir and 
_ wclosedir functions. 

The file <direct. h> contains definitions for the structure _ wdirent. 
struct _ wdirent { 

char d_dta[21]; /* disk transfer area */ 

char d_ attr; /* file's attribute */ 

unsigned short int d_time;/* file's time */ 
unsigned short int d_date;/* file's date */ 
long d_ size; /* file's size */ 

wchar_ t d_ name [NAME_ MAX+1 ] ;/* file's name */ 
unsigned short d_ ino; /* serial number (not used) */ 
char d_ first; /* flag for 1st time */ 

} ; 

Returns: The opendir function, if successful, returns a pointer to a structure required for subsequent calls to 

readdir to retrieve the file names matching the pattern specified by dirname. The opendir 
function returns NULL if dirname is not a valid pathname, or if there are no files matching dirname. 

Errors: When an error has occurred, errno contains a value indicating the type of error that has been detected. 

Constant Meaning 

EACCES Search permission is denied for a component of dirname or read permission is 

denied for dirname. 

ENOENT The named directory does not exist. 

See Also: closedir, _ dos_ find. . .peaddir, rewinddir 

Example: To get a list of files contained in the directory \watcom\h on your default disk: 
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opendir, _wopendir 


♦include <stdio.h> 
♦include <direct.h> 

typedef struct { 


unsigned short 

twosecs 

5; 

/* seconds / 2 */ 

unsigned short 

minutes 

6; 


unsigned short 
} ftime_ t; 

hours 

5; 


typedef struct { 

unsigned short 

day 

5; 


unsigned short 

month 

4; 


unsigned short 

year 

7; 



} fdate_ t; 


void main () 

{ 

DIR *dirp; 

struct dirent *direntp; 
ftime_ t *f_time; 
fdate_ t *f_ date; 

dirp = opendir( "\\watcom\\h" ); 
if( dirp != NULL ) { 

for(;;) { 

direntp = readdir( dirp ) ; 
if( direntp == NULL ) break; 
f_ time = (ftime_t *)&direntp->d_ time; 
f_ date = (fdate_ t *)&direntp->d_ date; 
printf ( "%-12s %d/%2.2d/%2.2d " 

"%2.2d:%2.2d:%2.2d \n", 
direntp->d_ name, 
f_ date->year + 1980, 
f_ date->month, 
f_ date->day, 
f_ time->hours, 
f_ time->minutes, 
f_ time->twosecs * 2 ) ; 

} 

closedir( dirp ); 

} 

} 

Note the use of two adjacent backslash characters (\) within character-string constants to signify a single 
backslash. 

Classification: POSIX 1003.1 

_wopendir is WATCOM 

Systems: opendir - All, Linux, RDOS, Netware 

_ wopendir - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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open_osfhandle 


Synopsis: 

Description: 


♦include <io.h> 

int _ open_ osfhandle( long osfhandle, int access ); 


The _ open_ osfhandle function allocates a POSIX-level file handle and sets it to point to the 
operating system’s internal file handle specified by osfhandle. The value returned by 
_ get_ osfhandle can be used as an argument to the. open_ osfhandle function. 

The access mode is established by a combination of the bits defined in the <f cntl. h> header file. 
The following bits may be set: 


Mode 

0_RD0NLY 

OJWRONLY 

0_RDWR 

0_APPEND 

OJCREAT 

0_TRUNC 

0_BINARY 

OJEXT 


Meaning 

permit the file to be only read. 

permit the file to be only written. 

permit the file to be both read and written. 

causes each record that is written to be written at the end of the file. 

has no effect when the file indicated by filename already exists; otherwise, 
the file is created; 

causes the file to be truncated to contain no data when the file exists; has no 
effect when the file does not exist. 

causes the file to be opened in binary mode which means that data will be 
transmitted to and from the file unchanged. 

causes the file to be opened in text mode which means that carriage-return 
characters are written before any linefeed character that is written and causes 
carriage-return characters to be removed when encountered during reads. 


OJYOINHERIT indicates that this file is not to be inherited by a child process. 


0_EXCL indicates that this file is to be opened for exclusive access. If the file exists 

and 0_ CREAT was also specified then the open will fail (i.e., useO_ EXCL to 
ensure that the file does not already exist). 


When neither 0_ TEXT norO_ BINARY are specified, the default value in the global variable_ fmode 
is used to set the file translation mode. When the program begins execution, this variable has a value of 
0_ TEXT. 


0_ CREAT must be specified when the file does not exist and it is to be written. 

When two or more manifest constants are used to form the flags argument, the constants are combined 
with the bitwise-OR operator (I). 

The example below demonstrates the use of the _ get_ osfhandle and_ open_ osfhandle 
functions. Note that the example shows how the dup2 function can be used to obtain almost identical 
functionality. 
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open_osfhandle 


Returns: 
See Also: 

Example: 


Classification: 


When the POSIX-level file handles associated with one OS file handle are closed, the first one closes 
successfully but the others return an error (since the first call close the file and released the OS file 
handle). So it is important to call close at the right time, i.e., after all I/O operations are completed to 
the file. 

If successful, _ open_ osfhandle returns a POSIX-style file handle. Otherwise, it returns -1. 

close, _ dos_ opendup2, fdopen, fopen, freopen, _ fsopen,_ get_ osfhandle, 

_ grow_ handles^. hdopen,open, _ os_ handle^, popen,sopen 


♦include <stdio.h> 
♦include <stdlib.h> 
♦include <io.h> 
♦include <fcntl.h> 


void main() 

{ 

long os_ handle; 
int fhl, fh2, rc; 


fhl 

= open( "file", 

0_ WRONLY 

0_ CREAT 

0_ TRUNC 


S_ IRUSR 

S_ IWUSR 

S_ IRGRP 

if ( 

fhl ==-!){ 




printf ( "Could not open output file\n" 
exit( EXIT_ FAILURE ); 


} 

printf ( "First POSIX handle %d\n", fhl ); 


0_ BINARY, 
S_ IWGRP ) ; 


♦ if defined (USE_ DUP2) 

fh2 = 6; 

if( dup2( fhl, fh2 ) == -1 ) fh2 = -1; 

♦ else 

os_ handle = _ get_ osfhandle ( fhl ) ; 
printf ( "OS Handle %ld\n", os_ handle ); 


fh2 = _ open_ osfhandle ( os_ handle, 0_ WRONLY 

0_ BINARY ); 


♦endif 

if( fh2 == -1 ) { 

printf ( "Could not open with second handle\n" 
exit( EXIT_ FAILURE ); 


} 

printf ( "Second POSIX handle %d\n", fh2 ); 


); 


rc = write( fh2, "trash\xOd\xOa", 7 ); 

printf( "Write file using second handle %d\n", rc ); 

rc = close( fh2 ) ; 

printf( "Closing second handle %d\n", rc ); 
rc = close ( fhl ); 

printf ( "Closing first handle %d\n", rc ); 


WATCOM 
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Systems: 


All, Linux, Netware 
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os handle 


Synopsis: #include <io.h> 

int _ os_ handle( int handle ) ; 

Description: The _ os_ handle function takes a POSIX-style file handle specified by handle. It returns the 
corresponding operating system level handle. 

Returns: The _ os_ handle function returns the operating system handle that corresponds to the specified 

POSIX-style file handle. 

See Also: close, fdopen, _ get_ osfhandle,^ hdopen,open, _ open_ osfhandle 

Example: #include <stdio.h> 

♦include <io.h> 

void main() 

{ 

int handle; 

FILE *fp; 

fp = fopen( "file", "r" ); 
if ( fp != NULL ) { 

handle = _ os_ handle( fileno( fp ) ) ; 

fclose ( fp ); 

} 

} 

Classification: WATCOM 

Systems: DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, Linux, Netware 
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outgtext 


Synopsis: #include <graph.h> 

void _ FAR _ outgtext ( char _ FAR *text ) ; 

Description: The _ outgtext function displays the character string indicated by the argument text. The string must 
be terminated by a null character (’\0’). 

The string is displayed starting at the current position (see the _ mo veto function) in the current color 
and in the currently selected font (see the _ set font function). The current position is updated to 
follow the displayed text. 

When no font has been previously selected with _ set font, a default font will be used. The default 
font is an 8-by-8 bit-mapped font. 

The graphics library can display text in three different ways. 

1. The _ outtext and_ outmem functions can be used in any video mode. However, this 
variety of text can be displayed in only one size. 

2. The _ grtext function displays text as a sequence of line segments, and can be drawn in 
different sizes, with different orientations and alignments. 

3. The _ outgtext function displays text in the currently selected font. Both bit-mapped and 
vector fonts are supported; the size and type of text depends on the fonts that are available. 

Returns: The _ outgtext function does not return a value. 

See Also: _ registerfonts,_ unregisterfonts,_ setfont^_ getfontinfo,_ getgtextextent, 

_ setgtextvector,_ getgtextvector,_ outtext^ outmem^ grtext 

Example: ((include <conio.h> 

((include <stdio.h> 

((include <graph.h> 

main() 

{ 

int i, n; 
char buf[ 10 ] ; 

_ setvideomode ( _VRES16COLOR ); 
n = _ registerfonts( "*.fon" ); 
for( i = 0; i < n; ++i ) { 

sprintf ( buf, "n%d", i ); 

_ setfont( buf ); 

_ moveto( 100, 100 ); 

_ outgtext( "WATCOM Graphics" ); 
getch() ; 

_ clearscreen( _ GCLEARSCREEN ); 

} 

_ unregisterfonts(); 

_ setvideomode( _DEFAULTMODE ); 

} 

Classification: PC Graphics 
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Systems: 


DOS 
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outmem 


Synopsis: 

Description: 


Returns: 
See Also: 

Example: 


Classification: 

Systems: 


#include <graph.h> 

void _ FAR _ outmem ( char _ FAR *text, short length ); 

The _ outmem function displays the character string indicated by the argument text. The argument 
length specifies the number of characters to be displayed. Unlike the _ outtext function,_ outmem 
will display the graphical representation of characters such as ASCII 10 and 0, instead of interpreting 
them as control characters. 

The text is displayed using the current text color (see the _ settextcolor function), starting at the 
current text position (see the _ settextposition function). The text position is updated to follow 
the end of the displayed text. 

The graphics library can display text in three different ways. 

1. The _ outtext and_ outmem functions can be used in any video mode. However, this 
variety of text can be displayed in only one size. 

2. The _ grtext function displays text as a sequence of line segments, and can be drawn in 
different sizes, with different orientations and alignments. 

3. The _ outgtext function displays text in the currently selected font. Both bit-mapped and 
vector fonts are supported; the size and type of text depends on the fonts that are available. 

The _ outmem function does not return a value. 


settextcolor^ settextposition,_ settextwindow,_ grtext^ outtext, 
outgtext 


♦include <conio.h> 
♦include <graph.h> 

main () 

{ 

int i; 

char buf[ 1 ]; 


_ clearscreen( _ GCLEARSCREEN 


for( i = 0; i <= 255; 
_ settextposition( 


buf[ 0 ] 
_ outmem( 


= i; 
buf. 


} 

getch(); 


++i ) 

1 + i 
1 + 5 


1 ) 


16, 
( i 


/ 16 ) ) 


PC Graphics 
DOS 
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outp 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <conio.h> 

unsigned int outp( int port, int value ); 

The outp function writes one byte, determined by value, to the 80x86 hardware port whose number is 
given by port. 

A hardware port is used to communicate with a device. One or two bytes can be read and/or written 
from each port, depending upon the hardware. Consult the technical documentation for your computer 
to determine the port numbers for a device and the expected usage of each port for a device. 

The value transmitted is returned. 

inp, inpd, inpw, outpd, outpw 

♦include <conio.h> 

void main() 

{ 

/* turn off speaker */ 

outp ( 0x61, inp( 0x61 ) & OxFC ); 

} 

Intel 

All, Linux, RDOS, Netware 
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outpd 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <conio.h> 

unsigned long outpd( int port, 

unsigned long value ); 

The outpd function writes a double-word (four bytes), determined by value , to the 80x86 hardware 
port whose number is given by port. 

A hardware port is used to communicate with a device. One or two bytes can be read and/or written 
from each port, depending upon the hardware. Consult the technical documentation for your computer 
to determine the port numbers for a device and the expected usage of each port for a device. 

The value transmitted is returned. 

inp, inpd, inpw, outp, outpw 

♦include <conio.h> 

♦define DEVICE 34 

void main() 

{ 

outpd( DEVICE, 0x12345678 ); 

} 

Intel 

DOS/32, Win386, Win32, OS/2-32, Linux, RDOS, Netware 
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Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


♦include <conio.h> 
unsigned int outpw( int port, 

unsigned int value ); 

The outpw function writes a word (two bytes), determined by value, to the 80x86 hardware port whose 
number is given by port. 

A hardware port is used to communicate with a device. One or two bytes can be read and/or written 
from each port, depending upon the hardware. Consult the technical documentation for your computer 
to determine the port numbers for a device and the expected usage of each port for a device. 

The value transmitted is returned. 

inp, inpd, inpw, outp, outpd 

♦include <conio.h> 

♦define DEVICE 34 

void main() 

{ 

outpw( DEVICE, 0x1234 ); 

} 

Intel 

All, Linux, RDOS, Netware 
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outtext 


Synopsis: 

Description: 


Returns: 
See Also: 

Example: 


Classification: 

Systems: 


#include <graph.h> 

void _ FAR _ outtext ( char _ FAR *text ) ; 

The _ outtext function displays the character string indicated by the argument text. The string must 
be terminated by a null character C\0’)- When a line-feed character (’\n’) is encountered in the string, 
the characters following will be displayed on the next row of the screen. 

The text is displayed using the current text color (see the _ settextcolor function), starting at the 
current text position (see the _ settextposition function). The text position is updated to follow 
the end of the displayed text. 

The graphics library can display text in three different ways. 

1. The _ outtext and_ outmem functions can be used in any video mode. However, this 
variety of text can be displayed in only one size. 

2. The _ grtext function displays text as a sequence of line segments, and can be drawn in 
different sizes, with different orientations and alignments. 

3. The _ outgtext function displays text in the currently selected font. Both bit-mapped and 
vector fonts are supported; the size and type of text depends on the fonts that are available. 

The _ outtext function does not return a value. 

_ settextcolor,_ settextposition,_ settextwindow,_ grtext^. outmem, 

_ outgtext 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

_ setvideomode( _ TEXTC80 ); 

_ settextposition( 10, 30 ); 

_ outtext( "WATCOM Graphics" ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ) ; 

} 

PC Graphics 
DOS 
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pclose 


Synopsis: 

Description: 

Returns: 

Errors: 


See Also: 
Example: 
Classification: 
Systems: 


#include <stdio.h> 
int pclose( FILE *fp ); 

The pclose function closes the pipe associated with^b and waits for the subprocess created by popen 
to terminate. 

The pclose function returns the termination status of the command language interpreter. If an error 
occured, pclose returns (-1) with errno set appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINTR The pclose function was interrupted by a signal while waiting for the child 

process to terminate. 

ECHILD The pclose function was unable to obtain the termination status of the child 

process. 


perror, popen 

See example provided with popen . 

POSIX 1003.1 

Linux 
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Synopsis: 

Description: 

Returns: 

Errors: 


See Also: 
Example: 
Classification: 
Systems: 


pclose 


♦include <stdio.h> 

int _ pclose( FILE *fp ); 

The _ pclose function closes the pipe associated with//; and waits for the subprocess created by 
_ popen to terminate. 

The _ pclose function returns the termination status of the command language interpreter. If an error 
occured, _ pclose returns (-1) witherrno set appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINTR The _ pclose function was interrupted by a signal while waiting for the child 

process to terminate. 

ECHILD The _ pclose function was unable to obtain the termination status of the child 

process. 

perror, _ pipe,_ popen 

See example provided with _ popen . 

WATCOM 

Win32, OS/2 l.x(all), OS/2-32, Linux 
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perror, _wperror 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <stdio.h> 

void perror( const char *prefix ); 
void _ wperror( const wchar_t ^prefix ); 

The perror function prints, on the file designated by stderr, the error message corresponding to the 
error number contained in errno. The perror function writes first the string pointed to by prefix to 
stderr. This is followed by a colon a space, the string returned by strerror (errno), and a 
newline character. 

The _ wperror function is a wide-character version ofperror that operates with wide-character 
strings. 

The perror function returns no value. Because perror uses the fprintf function, errno can be 
set when an error is detected during the execution of that function. 

clearerr, feof, ferror, strerror 

♦include <stdio.h> 

void main() 

{ 

FILE *fp; 

fp = fopen( "data.fil", "r" ); 
if( fp == NULL ) { 

perror( "Unable to open file" ); 

} 

} 

ISOC 

_wperror is WATCOM 

perror - All, Linux, RDOS, Netware 
_ wperror - All, Linux 
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pg_analyzechart Functions 


Synopsis: 


Description: 


Returns: 
See Also: 


#include <pgchart.h> 

short _ FAR _ pg_ analyzechart ( chartenv _ FAR *env, 

char _ FAR * _ FAR *cat, 
float _ FAR ‘values, short n ) ; 

short _ FAR _ pg_ analyzechartras ( chartenv _ FAR *env, 

char _ FAR * _ FAR *cat, 

float _ FAR ‘values, 

short nseries, 

short n, short dim, 

char _ FAR * _ FAR *labels ) ; 

The _ pg_ analyzechart functions analyze either a single-series or a multi-series bar, column or line 
chart. These functions calculate default values for chart elements without actually displaying the chart. 

The _ pg_ analyzechart function analyzes a single-series bar, column or line chart. The chart 
environment structure env is filled with default values based on the type of chart and the values of the 
cat and values arguments. The arguments are the same as for the _ pg_ chart function. 

The _ pg_ analyzechartms function analyzes a multi-series bar, column or line chart. The chart 
environment structure env is filled with default values based on the type of chart and the values of the 
cat, values and labels arguments. The arguments are the same as for the _ pg_ chartms function. 

The _ pg_ analyzechart functions return zero if successful; otherwise, a non-zero value is returned. 

_ pg_ defaultchart*. pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter* pg_ analyzepie^ pg_ analyzescatter 
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pgjanalyzechart Functions 


Example: #include <graph.h> 

♦include <pgchart.h> 

♦include <string.h> 

♦include <conio.h> 

♦ if defined (_ 386_) 

♦ define _ FAR 

♦ else 

♦ define _ FAR _far 

♦endif 

♦ define NUM_ VALUES 4 

char _ FAR Categories [ NUM_ VALUES ] = { 

"Jan", "Feb", "Mar", "Apr" 

}; 

float values [ NUM_ VALUES ] = { 

20, 45, 30, 25 

}; 

main () 

{ 

chartenv env; 

_ setvideomode ( _VRES16COLOR ); 

_ pg_ initchart () ; 

_ pg_ defaultchart( &env, 

_ PG_ COLUMNCHART, _ PG_ PLAINBARS ) ; 
strcpy( env.maintitle.title, "Column Chart" ); 

_ pg_ analyzechart( &env, 

categories, values, NUM_ VALUES ); 

/* use manual scaling */ 
env.yaxis.autoscale = 0; 
env.yaxis.scalemin = 0.0; 
env.yaxis.scalemax = 100.0; 
env.yaxis.ticinterval = 25.0; 

_ pg_ chart ( &env, categories, values, NUM_ VALUES ); 
getch(); 

_ setvideomode( _DEFAULTMODE ) ; 

} 

Classification: PC Graphics 

Systems: _ pg_ analyzechart - DOS 

_ pg_ analyzechartms - DOS 
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pg_analyzepie 


Synopsis: #include <pgchart.h> 

short _ FAR _ pg_ analyzepie ( chartenv _ FAR *env, 

char _ FAR * _ FAR *cat, 

float _ FAR *values, 

short _ FAR *explode, short n ) ; 

Description: The _ pg_ analyzepie function analyzes a pie chart. This function calculates default values for chart 
elements without actually displaying the chart. 

The chart environment structure env is filled with default values based on the values of the cat, values 
and explode arguments. The arguments are the same as for the _ pg_ chartpie function. 

Returns: The _ pg_ analyzepie function returns zero if successful; otherwise, a non-zero value is returned. 

See Also: _ pg_ defaultchart^ pg_ initchart*. pg_ charts pg_ chartpie, 

_ pg_ chartscatter^ pg_ analyzechart^ pg_ analyzescatter 
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pgjanalyzepie 


Example: 


Classification: 

Systems: 


♦include <graph.h> 

♦include <pgchart.h> 

♦include <string.h> 

♦include <conio.h> 

♦ if defined (_ 386_) 

♦define _ FAR 

♦ else 

♦ define _ FAR _far 

♦endif 

♦ define NUM_ VALUES 4 

char _ FAR Categories [ NUM_ VALUES ] = { 
"Jan", "Feb", "Mar", "Apr" 

} ; 


float values [ NUM_ VALUES ] = { 
20, 45, 30, 25 

} ; 

short explode [ NUM_ VALUES ] = { 

1 , 0 , 0 , 0 

} ; 


main () 

{ 

chartenv env; 

_ setvideomode( _ VRES16COLOR ); 

_ pg_ initchart () ; 

_ pg_ defaultchart( &env, 

_ PG_ PIECHART, _ PG_ NOPERCENT ); 
strcpy( env.maintitle.title, "Pie Chart" ); 
env.legend.place = _ PG_ BOTTOM; 

_ pg_ analyzepie ( &env, categories, 

values, explode, NUM_ VALUES ); 

/* make legend window same width as data window */ 
env.legend.autosize = 0; 

env.legend.legendwindow.xl = env.datawindow.xl; 
env.legend.legendwindow.x2 = env.datawindow.x2; 

_ pg_ chartpie( &env, categories, 

values, explode, NUM_ VALUES ); 

getch(); 

_ setvideomode ( _ DEFAULTMODE ); 

} 

PC Graphics 
DOS 
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pg_analyzescatter Functions 


Synopsis: 


Description: 


Returns: 


See Also: 


#include <pgchart.h> 

short _ FAR _ pg_ analyzescatter ( chartenv _ FAR *env, 

float _ FAR *x, 

float _ FAR *y, short n ) ; 

short _ FAR _ pg_ analyzescatterms ( 

chartenv _ FAR *env, 
float _ FAR *x, float _ FAR *y, 
short nseries, short n, short dim, 
char _ FAR * _ FAR *labels ) ; 

The _ pg_ analyzescatter functions analyze either a single-series or a multi-series scatter chart. 
These functions calculate default values for chart elements without actually displaying the chart. 

The _ pg_ analyzescatter function analyzes a single-series scatter chart. The chart environment 
structure env is filled with default values based on the values of the x and y arguments. The arguments 
are the same as for the _ pg_ chartscatter function. 

The _ pg_ analyzescatterms function analyzes a multi-series scatter chart. The chart environment 
structure env is filled with default values based on the values of the x, y and labels arguments. The 
arguments are the same as for the _ pg_ chartscatterms function. 

The _ pg_ analyzescatter functions return zero if successful; otherwise, a non-zero value is 
returned. 

_ pg_ defaultcharts pg_ initchart^ pg_ charts pg_ chartpie, 

_ pg_ chartscatter^ pg_ analyzechartj. pg_ analyzepie 
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pg_analyzescatter Functions 


Example: 


Classification: 

Systems: 


♦include <graph.h> 

♦include <pgchart.h> 

♦include <string.h> 

♦include <conio.h> 

♦ if defined (_ 386_) 

♦define _ FAR 

♦ else 

♦ define _ FAR _far 

♦endif 

♦ define NUM_ VALUES 4 
♦define NUM_ SERIES 2 

char _ FAR *labels [ NUM_ SERIES ] = { 
"Jan", "Feb" 

} ; 


float x [ NUM_ SERIES ][ NUM_ VALUES ] = { 
5, 15, 30, 40, 10, 20, 30, 45 

} ; 

float y [ NUM_ SERIES ][ NUM_ VALUES ] = { 
10, 15, 30, 45, 40, 30, 15, 5 

} ; 


main () 

{ 

chartenv env; 

_ setvideomode( _ VRES16COLOR ); 

_ pg_ initchart () ; 

_ pg_ defaultchart( &env, 

_ PG_ SCATTERCHART, _ PG_ POINTANDLINE ) ; 
strcpy( env.maintitle.title, "Scatter Chart" ); 

_ pg_ analyzescatterms ( &env, x, y, NUM_ SERIES, 

NUM_ VALUES, NUM_ VALUES, labels ); 
/* display x-axis labels with 2 decimal places */ 
env.xaxis.autoscale = 0; 
env.xaxis.ticdecimals = 2; 

_ pg_ chartscatterms ( &env, x, y, NUM_ SERIES, 

NUM_ VALUES, NUM_ VALUES, labels ); 

getch(); 

_ setvideomode ( _ DEFAULTMODE ); 

} 

PC Graphics 

_ pg_ analyzescatter - DOS 
_ pg_ analyzescatterms - DOS 
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pg_chart Functions 


Synopsis: 


Description: 


Returns: 
See Also: 


#include <pgchart.h> 

short _ FAR _ pg_ chart ( chartenv _ FAR *env, 

char _ FAR * _ FAR *cat, 
float _FAR *values, short n ); 

short _ FAR _ pg_ chartms ( chartenv _ FAR *env, 

char _ FAR * _ FAR *cat, 

float _ FAR ‘values, short nseries, 

short n, short dim, 

char _ FAR * _ FAR *labels ) ; 

The _ pg_ chart functions display either a single-series or a multi-series bar, column or line chart. 
The type of chart displayed and other chart options are contained in the env argument. The argument 
cat is an array of strings. These strings describe the categories against which the data in the values 
array is charted. 

The _ pg_ chart function displays a bar, column or line chart from the single series of data contained 
in the values array. The argument n specifies the number of values to chart. 

The _ pg_ chartms function displays a multi-series bar, column or line chart. The argument nseries 
specifies the number of series of data to chart. The argument values is assumed to be a two-dimensional 
array defined as follows: 

float values[ nseries ][ dim ]; 

The number of values used from each series is given by the argument n, where n is less than or equal to 
dim. The argument labels is an array of strings. These strings describe each of the series and are used 
in the chart legend. 

The _ pg_ chart functions return zero if successful; otherwise, a non-zero value is returned. 

_ pg_ defaultcharts pg_ initchart^ pg_ chartpie*. pg_ chartscatter, 

_ pg_ analyzechartj_ pg_ analyzepiej. pg_ analyzescatter 
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pg_chart Functions 


Example: #include <graph.h> 

♦include <pgchart.h> 

♦include <string.h> 

♦include <conio.h> 

♦ if defined (_ 386_) 

♦ define _ FAR 

♦ else 

♦ define _ FAR _far 

♦endif 

♦ define NUM_ VALUES 4 

char _ FAR Categories [ NUM_ VALUES ] = { 
"Jan", "Feb", "Mar", "Apr" 

}; 

float values [ NUM_ VALUES ] = { 

20, 45, 30, 25 

}; 


main () 

{ 

chartenv env; 

_ setvideomode ( _VRES16COLOR ); 

_ pg_ initchart () ; 

_ pg_ defaultchart( &env, 

_ PG_ COLUMNCHART, _ PG_ PLAINBARS ) ; 
strcpy( env.maintitle.title, "Column Chart" ); 

_ pg_ chart ( &env, categories, values, NUM_ VALUES ); 
getch(); 

_ setvideomode ( _ DEFAULTMODE ); 

} 

produces the following: 
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pg_chart Functions 


Classification: 

Systems: 



PC Graphics 

_ pg_ chart - DOS 
_ pg_ chartms - DOS 
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pg_chartpie 


Synopsis: 

Description: 


Returns: 
See Also: 


#include <pgchart.h> 

short _ FAR _ pg_ chartpie ( chartenv _ FAR *env, 

char _ FAR * _ FAR *cat, 

float _ FAR *values, 

short _ FAR *explode, short n ); 

The _ pg_ chartpie function displays a pie chart. The chart is displayed using the options specified 
in the env argument. 

The pie chart is created from the data contained in the values array. The argument n specifies the 
number of values to chart. 

The argument cat is an array of strings. These strings describe each of the pie slices and are used in the 
chart legend. The argument explode is an array of values corresponding to each of the pie slices. For 
each non-zero element in the array, the corresponding pie slice is drawn "exploded", or slightly offset 
from the rest of the pie. 

The _ pg_ chartpie function returns zero if successful; otherwise, a non-zero value is returned. 

_ pg_ defaultcharts pg_ initchart*. pg_ chart*. pg_ chartscatter, 

_ pg_ analyzechart*. pg_ analyzepie^ pg_ analyzescatter 
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pg_chartpie 


Example: #include <graph.h> 

♦include <pgchart.h> 

♦include <string.h> 

♦include <conio.h> 

♦ if defined (_ 386_) 

♦ define _ FAR 

♦ else 

♦ define _ FAR _far 

♦endif 

♦ define NUM_ VALUES 4 

char _ FAR Categories [ NUM_ VALUES ] = { 
"Jan", "Feb", "Mar", "Apr" 

}; 


float values [ NUM_ VALUES ] = { 
20, 45, 30, 25 

} ; 

short explode [ NUM_ VALUES ] = { 

1 , 0 , 0 , 0 

} ; 


main () 

{ 

chartenv env; 

_ setvideomode( _ VRES16COLOR ); 

_ pg_ initchart () ; 

_ pg_ defaultchart( &env, 

_ PG_ PIECHART, _ PG_ NOPERCENT ); 
strcpy( env.maintitle.title, "Pie Chart" ); 

_ pg_ chartpie( &env, categories, 

values, explode, NUM_ VALUES ); 

getch(); 

_ setvideomode( _ DEFAULTMODE ); 

} 

produces the following: 
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pg_chartpie 



Classification: PC Graphics 
Systems: DOS 
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pg_chartscatter Functions 


Synopsis: 


Description: 


Returns: 
See Also: 


#include <pgchart.h> 

short _ FAR _ pg_ chartscatter ( chartenv _ FAR *env, 

float _ FAR *x, 

float _ FAR *y, short n ) ; 

short _ FAR _ pg_ chartscatterms ( chartenv _ FAR *env, 

float _ FAR *x, 

float _ FAR *y, 

short nseries, 

short n, short dim, 

char _ FAR * _ FAR *labels ) ; 

The _ pg_ chartscatter functions display either a single-series or a multi-series scatter chart. The 
chart is displayed using the options specified in the env argument. 

The _ pg_ chartscatter function displays a scatter chart from the single series of data contained in 
the arrays x and y. The argument n specifies the number of values to chart. 

The _ pg_ chartscatterms function displays a multi-series scatter chart. The argument nseries 
specifies the number of series of data to chart. The arguments x and y are assumed to be 
two-dimensional arrays defined as follows: 

float x[ nseries ][ dim ]; 

The number of values used from each series is given by the argument n, where n is less than or equal to 
dim. The argument labels is an array of strings. These strings describe each of the series and are used 
in the chart legend. 

The _ pg_ chartscatter functions return zero if successful; otherwise, a non-zero value is returned. 

_ pg_ defaultchart*. pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ analyzechart*. pg_ analyzepie*. pg_ analyzescatter 
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pg_chartscatter Functions 


Example: 


♦include <graph.h> 

♦include <pgchart.h> 

♦include <string.h> 

♦include <conio.h> 

♦ if defined (_ 386_) 

♦define _ FAR 

♦ else 

♦ define _ FAR _far 

♦endif 

♦ define NUM_ VALUES 4 
♦define NUM_ SERIES 2 

char _ FAR *labels [ NUM_ SERIES ] = { 
"Jan", "Feb" 

} ; 


float x [ NUM_ SERIES ][ NUM_ VALUES ] = { 
5, 15, 30, 40, 10, 20, 30, 45 

} ; 

float y [ NUM_ SERIES ][ NUM_ VALUES ] = { 
10, 15, 30, 45, 40, 30, 15, 5 

} ; 


main () 

{ 

chartenv env; 

_ setvideomode( _ VRES16COLOR ); 

_ pg_ initchart () ; 

_ pg_ defaultchart( &env, 

_ PG_ SCATTERCHART, _ PG_ POINTANDLINE ) ; 
strcpy( env.maintitle.title, "Scatter Chart" ); 

_ pg_ chartscatterms ( &env, x, y, NUM_ SERIES, 

NUM_ VALUES, NUM_ VALUES, labels ); 

getch(); 

_ setvideomode( _ DEFAULTMODE ); 

} 

produces the following: 
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pg_chartscatter Functions 


Classification: 

Systems: 


r \ 


Scatter* Chart 



V_ J 


PC Graphics 

_ pg_ chartscatter - DOS 
_ pg_ chartscatterms - DOS 
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pg_defaultchart 


Synopsis: 

Description: 


Returns: 
See Also: 


#include <pgchart.h> 

short _ FAR _ pg_ defaultchart ( chartenv _ FAR *env, 

short type, short style ); 

The _ pg_ defaultchart function initializes the chart structure env to contain default values before a 
chart is drawn. All values in the chart structure are initialized, including blanking of all titles. The 
chart type in the structure is initialized to the value type, and the chart style is initialized to style. 

The argument type can have one of the following values: 


_PG_BARCHART 

Bar chart (horizontal bars) 


_PG_COLUMNCHART 

Column chart (vertical bars) 


_PG_LINECHART 

Line chart 


_PG_SCATTERCHART 

Scatter chart 


_PG_PIE CHAR T 

Pie chart 


Each type of chart can be drawn in one of two styles. For each chart type the argument style can have 
one of the following values: uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 

Type 

Style 1 

Style 2 

Bar 

Column 

Line 

Scatter 

Pie 

_ PG_ PLAINBARS 
_ PG_ PLAINBARS 
_ PG_ POINTANDLINE 
_ PG_ POINTANDLINE 
_ PG_ PERCENT 

_ PG_ STACKEDBARS 
_ PG_ STACKEDBARS 
_ PG_ POINTONLY 
_ PG_ POINTONLY 
_ PG_ NOPERCENT 


For single-series bar and column charts, the chart style is ignored. The "plain" (clustered) and "stacked" 
styles only apply when there is more than one series of data. The "percent" style for pie charts causes 
percentages to be displayed beside each of the pie slices. 

The _ pg_ defaultchart function returns zero if successful; otherwise, a non-zero value is returned. 
_ pg_ initchart^ pg_ charts pg_ chartpie^ pg_ chartscatter 
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pg_defaultchart 


Example: #include <graph.h> 

♦include <pgchart.h> 

♦include <string.h> 

♦include <conio.h> 

♦ if defined (_ 386_) 

♦ define _ FAR 

♦ else 

♦ define _ FAR _far 

♦endif 

♦ define NUM_ VALUES 4 

char _ FAR Categories [ NUM_ VALUES ] = { 
"Jan", "Feb", "Mar", "Apr" 

}; 

float values [ NUM_ VALUES ] = { 

20, 45, 30, 25 

}; 


main () 

{ 

chartenv env; 

_ setvideomode ( _VRES16COLOR ); 

_ pg_ initchart () ; 

_ pg_ defaultchart( &env, 

_ PG_ COLUMNCHART, _ PG_ PLAINBARS ) ; 
strcpy( env.maintitle.title, "Column Chart" ); 

_ pg_ chart ( &env, categories, values, NUM_ VALUES ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ) ; 

} 

Classification: PC Graphics 
Systems: DOS 
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pg_getchardef 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


#include <pgchart.h> 

short _ FAR _ pg_ getchardef ( short ch, 

unsigned char _ FAR *def ) ; 

The _ pg_ getchardef function retrieves the current bit-map definition for the character ch. The 
bit-map is placed in the array def. The current font must be an 8-by-8 bit-mapped font. 

The _ pg_ getchardef function returns zero if successful; otherwise, a non-zero value is returned. 

_ pg_ defaultcharts pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter* pg_ setchardef 

♦include <graph.h> 

♦include <pgchart.h> 

♦include <string.h> 

♦include <conio.h> 

♦ define NUM_ VALUES 4 

float x [ NUM_ VALUES ] = { 

5, 25, 45, 65 

} ; 

float y [ NUM_ VALUES ] = { 

5, 45, 25, 65 

} ; 

char diamond! 8 ] = { 

0x10, 0x28, 0x44, 0x82, 0x44, 0x28, 0x10, 0x00 

} ; 


main () 

{ 

chartenv env; 
char old_def[ 8 ] ; 

_ setvideomode( _ VRES16COLOR ); 

_ pg_ initchart () ; 

_ pg_ defaultchart( &env, 

_ PG_ SCATTERCHART, _ PG_ POINTANDLINE ) ; 
strcpy( env.maintitle.title, "Scatter Chart" ); 

/* change asterisk character to diamond */ 

— pg_ getchardef ( old_ def ); 

_ pg_ setchardef( diamond ); 

_ pg_ chartscatter ( &env, x, y, NUM_ VALUES ); 

_ pg_ setchardef ( old_ def ); 

getch(); 

_ setvideomode ( _ DEFAULTMODE ); 

} 

PC Graphics 
DOS 
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pg_getpalette 


Synopsis: #include <pgchart.h> 

short _ FAR _ pg_ getpalette ( paletteentry _ FAR *pal ) ; 

Description: The _ pg_ getpalette function retrieves the internal palette of the presentation graphics system. 

The palette controls the colors, line styles, fill patterns and plot characters used to display each series of 
data in a chart. 

The argument pal is an array of palette structures that will contain the palette. Each element of the 
palette is a structure containing the following fields: 

color color used to display series 

style line style used for line and scatter charts 

fill fill pattern used to fill interior of bar and pie sections 

plotchar character plotted on line and scatter charts 

Returns: The _ pg_ getpalette function returns zero if successful; otherwise, a non-zero value is returned. 

See Also: _ pg_ defaultchart*. pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter^ pg_ setpalette^ pg_ resetpalette 
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pg_getpalette 


Example: 


Classification: 

Systems: 


♦include <graph.h> 

♦include <pgchart.h> 

♦include <string.h> 

♦include <conio.h> 

♦ if defined (_ 386_) 

♦define _ FAR 

♦ else 

♦ define _ FAR _far 

♦endif 

♦ define NUM_ VALUES 4 

char _ FAR Categories [ NUM_ VALUES ] = { 
"Jan", "Feb", "Mar", "Apr" 

} ; 


float values [ NUM_ VALUES ] = { 
20, 45, 30, 25 

} ; 


char bricks[ 8 ] = { 

Oxff, 0x80, 0x80, 0x80, Oxff, 0x08, 0x08, 0x08 

} ; 


main () 

{ 

chartenv env; 
palettetype pal; 

_ setvideomode( _ VRES16COLOR ); 

_ pg_ initchart () ; 

_ pg_ defaultchart( &env, 

_ PG_ COLUMNCHART, _ PG_ PLAINBARS ) ; 
strcpy( env.maintitle.title, "Column Chart" ); 

/* get default palette and change 1st entry */ 

— P‘3— getpalette ( &pal ) ; 

pal[ 1 ].color = 12; 

memcpy( pal[ 1 ].fill, bricks, 8 ); 

/* use new palette */ 

_ pg_ setpalette ( &pal ); 

_ pg_ chart ( &env, categories, values, NUM_ VALUES ); 

/* reset palette to default */ 

_ pg_ resetpalette () ; 
getch(); 

_ setvideomode ( _ DEFAULTMODE ); 

} 

PC Graphics 
DOS 
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pg_getstyleset 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


#include <pgchart.h> 

void _ FAR _ pg_ getstyleset ( unsigned short _ FAR *style ) ; 

The _ pg_ getstyleset function retrieves the internal style-set of the presentation graphics system. 
The style-set is a set of line styles used for drawing window borders and grid-lines. The argument style 
is an array that will contain the style-set. 

The _ pg_ getstyleset function does not return a value. 

_ pg_ defaultcharts pg_ initchart*. pg_ charts pg_ chartpie, 

_ pg_ chartscatter^ pg_ setstyleset^ pg_ resetstyleset 
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pg_getstyleset 


♦include <graph.h> 

♦include <pgchart.h> 

♦include <string.h> 

♦include <conio.h> 

♦ if defined (_ 386_) 

♦define _ FAR 

♦ else 

♦ define _ FAR _far 

♦endif 

♦ define NUM_ VALUES 4 

char _ FAR Categories [ NUM_ VALUES ] = { 
"Jan", "Feb", "Mar", "Apr" 

} ; 

float values [ NUM_ VALUES ] = { 

20, 45, 30, 25 

} ; 


main () 

{ 

chartenv env; 
styleset style; 

_ setvideomode( _ VRES16COLOR ); 

_ pg_ initchart () ; 

_ pg_ defaultchart( &env, 

_ PG_ COLUMNCHART, _ PG_ PLAINBARS ) ; 
strcpy( env.maintitle.title, "Column Chart" ); 

/* turn on yaxis grid, and use style 2 */ 

env.yaxis.grid = 1; 

env.yaxis.gridstyle = 2; 

/* get default style-set and change entry 2 */ 

— P‘3— getstyleset ( Sstyle ) ; 
stylet 2 ] = 0x8888; 

/* use new style-set */ 

_ pg_ setstyleset( Sstyle ); 

_ pg_ chart ( &env, categories, values, NUM_ VALUES ); 

/* reset style-set to default */ 

_ pg_ resetstyleset (); 
getch (); 

_ setvideomode( _ DEFAULTMODE ); 


Classification: PC Graphics 
Systems: DOS 
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pg_hlabelchart 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


#include <pgchart.h> 

short _ FAR _ pg_ hlabelchart ( chartenv _ FAR *env, 

short x, short y, 

short color, 

char _ FAR *label ) ; 

The _ pg_ hlabelchart function displays the text string label on the chart described by the env chart 
structure. The string is displayed horizontally starting at the point (x, y) , relative to the upper left 
corner of the chart. The color specifies the palette color used to display the string. 

The _ pg_ hlabelchart function returns zero if successful; otherwise, a non-zero value is returned. 

_ pg_ defaultchart*. pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter* pg_ vlabelchart 

♦include <graph.h> 

♦include <pgchart.h> 

♦include <string.h> 

♦include <conio.h> 

♦ if defined (_ 386_) 

♦define _ FAR 

♦ else 

♦ define _ FAR _far 

♦endif 

♦ define NUM_ VALUES 4 

char _ FAR Categories [ NUM_ VALUES ] = { 

"Jan", "Feb", "Mar", "Apr" 

} ; 

float values [ NUM_ VALUES ] = { 

20, 45, 30, 25 

1 ; 


main () 

{ 

chartenv env; 

_ setvideomode( _ VRES16COLOR ); 

_ pg_ initchart () ; 

_ pg_ defaultchart( &env, 

_ PG_ COLUMNCHART, _ PG_ PLAINBARS ) ; 
strcpy( env.maintitle.title, "Column Chart" ); 

_ pg_ chart ( &env, categories, values, NUM_ VALUES ); 

_ pg_ hlabelchart( &env, 64, 32, 1, "Horizontal label" ); 
_ pg_ vlabelchart( &env, 48, 32, 1, "Vertical label" ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ) ; 

} 

PC Graphics 
DOS 
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pgjnitchart 


Synopsis: 

Description: 


Returns: 
See Also: 

Example: 


Classification: 


♦include <pgchart.h> 

short _ FAR _ pg_ initchart ( void ) ; 

The _ pg_ initchart function initializes the presentation graphics system. This includes initializing 
the internal palette and style-set used when drawing charts. This function must be called before any of 
the other presentation graphics functions. 

The initialization of the presentation graphics system requires that a valid graphics mode has been 
selected. For this reason the _ setvideomode function must be called before_ pg_ initchart is 
called. If a font has been selected (with the _ set font function), that font will be used when text is 
displayed in a chart. Font selection should also be done before initializing the presentation graphics 
system. 

The _ pg_ initchart function returns zero if successful; otherwise, a non-zero value is returned. 

_ pg_ defaultcharts pg_ chart*. pg_ chartpie*. pg_ chartscatter, 

_ setvideomode,_ setfont,_ registerfonts 

♦include <graph.h> 

♦include <pgchart.h> 

♦include <string.h> 

♦include <conio.h> 

♦ if defined (_ 386_) 

♦ define _ FAR 

♦ else 

♦ define _ FAR _far 

♦endif 

♦ define NUM_ VALUES 4 

char _ FAR Categories [ NUM_ VALUES ] = { 

"Jan", "Feb", "Mar", "Apr" 

1 ; 

float values [ NUM_ VALUES ] = { 

20, 45, 30, 25 

1 ; 


main () 

{ 

chartenv env; 

_ setvideomode ( _VRES16COLOR ); 

_ pg_ initchart () ; 

_ pg_ defaultchart( Senv, 

_ PG_ COLUMNCHART, _ PG_ PLAINBARS ) ; 
strcpy( env.maintitle.title, "Column Chart" ); 

_ pg_ chart ( Senv, categories, values, NUM_ VALUES ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ); 

} 

PC Graphics 
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pg_initchart 


Systems: 


DOS 
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pg_resetpalette 


Synopsis: 

Description: 

Returns: 

See Also: 


♦include <pgchart.h> 

short _ FAR _ pg_ resetpalette ( void ) ; 

The _ pg_ resetpalette function resets the internal palette of the presentation graphics system to 
default values. The palette controls the colors, line styles, fill patterns and plot characters used to 
display each series of data in a chart. The default palette chosen is dependent on the current video 
mode. 

The _ pg_ resetpalette function returns zero if successful; otherwise, a non-zero value is returned. 

_ pg_ defaultcharts pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter^ pg_ getpalette^ pg_ setpalette 
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pg_resetpalette 


Example: 


Classification: 

Systems: 


♦include <graph.h> 

♦include <pgchart.h> 

♦include <string.h> 

♦include <conio.h> 

♦ if defined (_ 386_) 

♦define _ FAR 

♦ else 

♦ define _ FAR _far 

♦endif 

♦ define NUM_ VALUES 4 

char _ FAR Categories [ NUM_ VALUES ] = { 
"Jan", "Feb", "Mar", "Apr" 

} ; 


float values [ NUM_ VALUES ] = { 
20, 45, 30, 25 

} ; 


char bricks[ 8 ] = { 

Oxff, 0x80, 0x80, 0x80, Oxff, 0x08, 0x08, 0x08 

} ; 


main () 

{ 

chartenv env; 
palettetype pal; 

_ setvideomode( _ VRES16COLOR ); 

_ pg_ initchart () ; 

_ pg_ defaultchart( &env, 

_ PG_ COLUMNCHART, _ PG_ PLAINBARS ) ; 
strcpy( env.maintitle.title, "Column Chart" ); 

/* get default palette and change 1st entry */ 

— P‘3— getpalette ( &pal ) ; 

pal[ 1 ].color = 12; 

memcpy( pal[ 1 ].fill, bricks, 8 ); 

/* use new palette */ 

_ pg_ setpalette ( &pal ); 

_ pg_ chart ( &env, categories, values, NUM_ VALUES ); 

/* reset palette to default */ 

_ pg_ resetpalette () ; 
getch(); 

_ setvideomode ( _ DEFAULTMODE ); 

} 

PC Graphics 
DOS 
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pg_resetstyleset 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


#include <pgchart.h> 

void _ FAR _ pg_ resetstyleset ( void ) ; 

The _ pg_ resetstyleset function resets the internal style-set of the presentation graphics system 
to default values. The style-set is a set of line styles used for drawing window borders and grid-lines. 

The _ pg_ resetstyleset function does not return a value. 

_ pg_ defaultcharts pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter^ pg_ getstyleset*. pg_ setstyleset 

♦include <graph.h> 

♦include <pgchart.h> 

♦include <string.h> 

♦include <conio.h> 

♦ if defined (_ 386_) 

♦define _ FAR 

♦ else 

♦ define _ FAR _far 

♦endif 

♦ define NUM_ VALUES 4 

char _ FAR Categories [ NUM_ VALUES ] = { 

"Jan", "Feb", "Mar", "Apr" 

} ; 

float values [ NUM_ VALUES ] = { 

20, 45, 30, 25 

} ; 


main () 

{ 

chartenv env; 
styleset style; 

_ setvideomode( _ VRES16COLOR ); 

_ pg_ initchart () ; 

_ pg_ defaultchart( &env, 

_ PG_ COLUMNCHART, _ PG_ PLAINBARS ) ; 
strcpy( env.maintitle.title, "Column Chart" ); 

/* turn on yaxis grid, and use style 2 */ 

env.yaxis.grid = 1; 

env.yaxis.gridstyle = 2; 

/* get default style-set and change entry 2 */ 

— P‘3— getstyleset ( Sstyle ) ; 
stylet 2 ] = 0x8888; 

/* use new style-set */ 

_ pg_ setstyleset( Sstyle ); 

_ pg_ chart ( &env, categories, values, NUM_ VALUES ); 

/* reset style-set to default */ 

_ pg_ resetstyleset (); 
getch(); 

_ setvideomode( _ DEFAULTMODE ); 
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pg_resetstyleset 


Classification: PC Graphics 
Systems: DOS 
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pg_setchardef 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


#include <pgchart.h> 

short _ FAR _ pg_ setchardef ( short ch, 

unsigned char _ FAR *def ) ; 

The _ pg_ setchardef function sets the current bit-map definition for the character ch. The bit-map 
is contained in the array def. The current font must be an 8-by-8 bit-mapped font. 

The _ pg_ setchardef function returns zero if successful; otherwise, a non-zero value is returned. 

_ pg_ defaultcharts pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter* pg_ getchardef 

♦include <graph.h> 

♦include <pgchart.h> 

♦include <string.h> 

♦include <conio.h> 

♦ define NUM_ VALUES 4 

float x [ NUM_ VALUES ] = { 

5, 25, 45, 65 

} ; 

float y [ NUM_ VALUES ] = { 

5, 45, 25, 65 

} ; 

char diamond! 8 ] = { 

0x10, 0x28, 0x44, 0x82, 0x44, 0x28, 0x10, 0x00 

} ; 


main () 

{ 

chartenv env; 
char old_def[ 8 ] ; 

_ setvideomode( _ VRES16COLOR ); 

_ pg_ initchart () ; 

_ pg_ defaultchart( &env, 

_ PG_ SCATTERCHART, _ PG_ POINTANDLINE ) ; 
strcpy( env.maintitle.title, "Scatter Chart" ); 

/* change asterisk character to diamond */ 

— pg_ getchardef ( old_ def ); 

_ pg_ setchardef( diamond ); 

_ pg_ chartscatter ( &env, x, y, NUM_ VALUES ); 

_ pg_ setchardef ( old_ def ); 

getch(); 

_ setvideomode ( _ DEFAULTMODE ); 

} 

PC Graphics 
DOS 
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pg_setpalette 


Synopsis: #include <pgchart.h> 

short _ FAR _ pg_ setpalette ( paletteentry _ FAR *pal ) ; 

Description: The _ pg_ setpalette function sets the internal palette of the presentation graphics system. The 

palette controls the colors, line styles, fill patterns and plot characters used to display each series of data 
in a chart. 

The argument pal is an array of palette structures containing the new palette. Each element of the 
palette is a structure containing the following fields: 

color color used to display series 

style line style used for line and scatter charts 

fill fill pattern used to fill interior of bar and pie sections 

plotchar character plotted on line and scatter charts 

Returns: The _ pg_ setpalette function returns zero if successful; otherwise, a non-zero value is returned. 

See Also: _ pg_ defaultchart*. pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter^ pg_ getpalette^ pg_ resetpalette 
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pg_setpalette 


Example: 


Classification: 

Systems: 


♦include <graph.h> 

♦include <pgchart.h> 

♦include <string.h> 

♦include <conio.h> 

♦ if defined (_ 386_) 

♦define _ FAR 

♦ else 

♦ define _ FAR _far 

♦endif 

♦ define NUM_ VALUES 4 

char _ FAR Categories [ NUM_ VALUES ] = { 
"Jan", "Feb", "Mar", "Apr" 

} ; 


float values [ NUM_ VALUES ] = { 
20, 45, 30, 25 

} ; 


char bricks[ 8 ] = { 

Oxff, 0x80, 0x80, 0x80, Oxff, 0x08, 0x08, 0x08 

} ; 


main () 

{ 

chartenv env; 
palettetype pal; 

_ setvideomode( _ VRES16COLOR ); 

_ pg_ initchart () ; 

_ pg_ defaultchart( &env, 

_ PG_ COLUMNCHART, _ PG_ PLAINBARS ) ; 
strcpy( env.maintitle.title, "Column Chart" ); 

/* get default palette and change 1st entry */ 

— P‘3— getpalette ( &pal ) ; 

pal[ 1 ].color = 12; 

memcpy( pal[ 1 ].fill, bricks, 8 ); 

/* use new palette */ 

_ pg_ setpalette ( &pal ); 

_ pg_ chart ( &env, categories, values, NUM_ VALUES ); 

/* reset palette to default */ 

_ pg_ resetpalette () ; 
getch(); 

_ setvideomode ( _ DEFAULTMODE ); 

} 

PC Graphics 
DOS 
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pg_setstyleset 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


#include <pgchart.h> 

void _ FAR _ pg_ setstyleset ( unsigned short _ FAR *style ); 

The _ pg_ setstyleset function retrieves the internal style-set of the presentation graphics system. 
The style-set is a set of line styles used for drawing window borders and grid-lines. The argument style 
is an array containing the new style-set. 

The _ pg_ setstyleset function does not return a value. 

_ pg_ defaultcharts pg_ initchart*. pg_ charts pg_ chartpie, 

_ pg_ chartscatter^ pg_ getstyleset^ pg_ resetstyleset 
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pg_setstyleset 


♦include <graph.h> 

♦include <pgchart.h> 

♦include <string.h> 

♦include <conio.h> 

♦ if defined (_ 386_) 

♦define _ FAR 

♦ else 

♦ define _ FAR _far 

♦endif 

♦ define NUM_ VALUES 4 

char _ FAR Categories [ NUM_ VALUES ] = { 
"Jan", "Feb", "Mar", "Apr" 

} ; 

float values [ NUM_ VALUES ] = { 

20, 45, 30, 25 

} ; 


main () 

{ 

chartenv env; 
styleset style; 

_ setvideomode( _ VRES16COLOR ); 

_ pg_ initchart () ; 

_ pg_ defaultchart( &env, 

_ PG_ COLUMNCHART, _ PG_ PLAINBARS ) ; 
strcpy( env.maintitle.title, "Column Chart" ); 

/* turn on yaxis grid, and use style 2 */ 

env.yaxis.grid = 1; 

env.yaxis.gridstyle = 2; 

/* get default style-set and change entry 2 */ 

— P‘3— getstyleset ( Sstyle ) ; 
stylet 2 ] = 0x8888; 

/* use new style-set */ 

_ pg_ setstyleset( Sstyle ); 

_ pg_ chart ( &env, categories, values, NUM_ VALUES ); 

/* reset style-set to default */ 

_ pg_ resetstyleset (); 
getch (); 

_ setvideomode( _ DEFAULTMODE ); 


Classification: PC Graphics 
Systems: DOS 
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pg_vlabelchart 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


#include <pgchart.h> 

short _ FAR _ pg_ vlabelchart ( chartenv _ FAR *env, 

short x, short y, 

short color, 

char _ FAR *label ) ; 

The _ pg_ vlabelchart function displays the text string label on the chart described by the env chart 
structure. The string is displayed vertically starting at the point (x, y) , relative to the upper left 
corner of the chart. The color specifies the palette color used to display the string. 

The _ pg_ vlabelchart function returns zero if successful; otherwise, a non-zero value is returned. 

_ pg_ defaultchart*. pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter* pg_ hlabelchart 

♦include <graph.h> 

♦include <pgchart.h> 

♦include <string.h> 

♦include <conio.h> 

♦ if defined (_ 386_) 

♦define _ FAR 

♦ else 

♦ define _ FAR _far 

♦endif 

♦ define NUM_ VALUES 4 

char _ FAR Categories [ NUM_ VALUES ] = { 

"Jan", "Feb", "Mar", "Apr" 

} ; 

float values [ NUM_ VALUES ] = { 

20, 45, 30, 25 

1 ; 


main () 

{ 

chartenv env; 

_ setvideomode( _ VRES16COLOR ); 

_ pg_ initchart () ; 

_ pg_ defaultchart( &env, 

_ PG_ COLUMNCHART, _ PG_ PLAINBARS ) ; 
strcpy( env.maintitle.title, "Column Chart" ); 

_ pg_ chart ( &env, categories, values, NUM_ VALUES ); 

_ pg_ hlabelchart( &env, 64, 32, 1, "Horizontal label" ); 
_ pg_ vlabelchart( &env, 48, 32, 1, "Vertical label" ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ) ; 

} 

PC Graphics 
DOS 
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pie Functions 


Synopsis: #include <graph.h> 

short _ FAR _pie( short fill, short xl, short yl, 

short x2, short y2, 
short x3, short y3, 
short x4, short y4 ); 

short _ FAR _pie_ w ( short fill, double xl, double yl, 

double x2, double y2, 
double x3, double y3, 
double x4, double y4 ); 

short _ FAR _ pie_ wxy ( short fill, 

struct _ wxycoord _ FAR *pl, 
struct _ wxycoord _ FAR *p2, 
struct _ wxycoord _ FAR *p3, 
struct _ wxycoord _ FAR *p4 ); 

Description: The _ pie functions draw pie-shaped wedges. The_ pie function uses the view coordinate system. 
The _ pie_ w and. pie_ wxy functions use the window coordinate system. 

The pie wedges are drawn by drawing an elliptical arc (in the way described for the _ arc functions) 
and then joining the center of the rectangle that contains the ellipse to the two endpoints of the arc. 

The elliptical arc is drawn with its center at the center of the rectangle established by the points 
(xl,yl) and (x2,y2). The arc is a segment of the ellipse drawn within this bounding rectangle. 
The arc starts at the point on this ellipse that intersects the vector from the centre of the ellipse to the 
point (x3, y3) . The arc ends at the point on this ellipse that intersects the vector from the centre of 
the ellipse to the point (x4, y4 ) . The arc is drawn in a counter-clockwise direction with the current 
plot action using the current color and the current line style. 

The following picture illustrates the way in which the bounding rectangle and the vectors specifying the 
start and end points are defined. 
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pie Functions 


Returns: 

See Also: 
Example: 


When the coordinates (xl,yl) and (x2,y2) establish a line or a point (this happens when one or 
more of the x-coordinates or y-coordinates are equal), nothing is drawn. 

The argument/;// determines whether the figure is filled in or has only its outline drawn. The argument 
can have one of two values: 

_GFILLINTERIOR fill the interior by writing pixels with the current plot action using the current 

color and the current fill mask 

_GBORDER leave the interior unchanged; draw the outline of the figure with the current 

plot action using the current color and line style 

The _ pie functions return a non-zero value when the figure was successfully drawn; otherwise, zero is 
returned. 

_ arc,_ ellipse^, setcolor^. setfillmask,_ setlinestyle,_ setplotaction 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

_ setvideomode( _ VRES16C0L0R ); 

_ pie ( _ GBORDER, 120, 90, 520, 390, 

140, 20, 190, 460 ); 

getch(); 

_ setvideomode( _DEFAULTMODE ); 

} 

produces the following: 
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pie Functions 


Classification: PC Graphics 

Systems: _ pie - DOS 

_ pie_ w - DOS 
_ pie_ wxy - DOS 
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-Pipe 


Synopsis: 

Description: 


Returns: 

Errors: 


See Also: 
Example: 


♦include <io.h> 

int _ pipe( int *phandles, unsigned psize, int textmode ); 


The _ pipe function creates a pipe (an unnamed FIFO) and places a file descriptor for the read end of 
the pipe in phandles[0] and a file descriptor for the write end of the pipe in phandles[l]. Their integer 
values are the two lowest available at the time of the _ pipe function call. TheO_ NONBLOCK flag is 
cleared for both file descriptors. (The f cntl call can be used to set the 0_ NONBLOCK flag.) 

Data can be written to file descriptor phandles[l] and read from file descriptor phandles[0]. A read on 
file descriptor phandles[0] returns the data written to phandles[l] on a first-in-first-out (FIFO) basis. 

This function is typically used to connect together standard utilities to act as filters, passing the write 
end of the pipe to the data producing process as its STDOUT_ FILENO and the read end of the pipe to 
the data consuming process as its STDIN_ FILENO. (either via the traditional fork/dup2/exec or the 
more efficient spawn calls). 

If successful, _ pipe marks for update the stjtime, st_ctime, st_atime and st_mtime fields of the pipe 
for updating. 

The _ pipe function returns zero on success. Otherwise, (-1) is returned and errno is set to indicate 
the error. 


When an error has occurred, errno contains a value indicating the type of error that has been detected. 
If any of the following conditions occur, the _ pipe function shall return (-1) and seterrno to the 
corresponding value: 


Constant 

EMFILE 

ENFILE 

ENOSPC 

EROFS 


Meaning 

The calling process does not have at least 2 unused file descriptors available. 

The number of simultaneously open files in the system would exceed the 
configured limit. 

There is insufficient space available to allocate the pipe buffer. 

The pipe pathname space is a read-only filesystem. 


open, _ pclose,perror, _ popen.read, write 


♦include 

♦include 

♦include 

♦include 

♦include 

♦include 


<stdio.h> 
<stdlib.h> 
<stddef.h> 
<fcntl.h> 
<io.h> 
<process.h> 


static int handles[2] 
static int pid; 


0 , 0 } ; 
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-Pipe 


create_ pipe () 

{ 

if ( _ pipe( (int *)Shandies, 2048, _ 0_ BINARY ) == -1 ) { 

perror ( "create_ pipe" ); 
exit( EXIT_ FAILURE ); 

} 

} 

create^ child( char *name ) 

{ 

char buff[10]; 

itoa( handles[0], buff, 10 ); 
pid = spawnl ( P_ NOWAIT, name, 

"_pipe", buff, NULL ); 
close ( handles[0] ); 

if( pid == -1 ) { 

perror ( "create_ child" ); 
close ( handles[1] ); 

exit( EXIT_ FAILURE ); 

} 

} 

f ill_ pipe () 

{ 

int i; 
int rc; 

for( i = 1; i <= 10; i++ ) { 

printf( "Child, what is 5 times %d\n", i ); 
rc = write( handles[1], &i, sizeof( int ) ); 

if ( rc < sizeof( int ) ) { 

perror ( "fill_pipe" ); 
close ( handles[1] ); 

exit( EXIT_ FAILURE ); 

} 

} 

/* indicate that we are done */ 
i = -1; 

write ( handles[1], &i, sizeof( int ) ); 

close ( handles[1] ); 

} 
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-Pipe 


Classification: 

Systems: 


empty_ pipe ( int in_ pipe ) 

{ 

int i; 
int amt; 

for (;;) { 

amt = read( in_ pipe, &i, sizeof ( int ) ); 

if( amt != sizeof ( int ) | | i == -1 ) 

break; 

printf ( "Parent, 5 times %d is %d\n", i, 5*i ); 

} 

if( amt == -1 ) { 

perror ( "empty_ pipe" ); 
exit( EXIT_ FAILURE ); 

} 

close ( in_ pipe ); 

} 

void main ( int argc, char *argv[] ) 

{ 

if( argc <= 1 ) { 

/* we are the spawning process */ 
create_ pipe (); 
create_ child( argv[0] ); 
fill_ pipe () ; 

} else { 

/* we are the spawned process */ 
empty_ pipe ( atoi ( argv[l] ) ); 

} 

exit( EXIT_ SUCCESS ); 

} 

produces the following: 

Child, what is 5 times 1 
Child, what is 5 times 2 
Parent, 5 times 1 is 5 
Parent, 5 times 2 is 10 
Child, what is 5 times 3 
Child, what is 5 times 4 
Parent, 5 times 3 is 15 
Parent, 5 times 4 is 20 
Child, what is 5 times 5 
Child, what is 5 times 6 
Parent, 5 times 5 is 25 
Parent, 5 times 6 is 30 
Child, what is 5 times 7 
Child, what is 5 times 8 
Parent, 5 times 7 is 35 
Parent, 5 times 8 is 40 
Child, what is 5 times 9 
Child, what is 5 times 10 
Parent, 5 times 9 is 45 
Parent, 5 times 10 is 50 

WATCOM 

Win32, OS/2 l.x(all), OS/2-32 
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polygon Functions 


Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


#include <graph.h> 

short _ FAR _polygon( short fill, short numpts, 

struct xycoord _ FAR *points ); 

short _ FAR _polygon_ w ( short fill, short numpts, 

double _ FAR *points ); 

short _ FAR _ polygon_ wxy( short fill, short numpts, 

struct _ wxycoord _ FAR ^points ) ; 

The _ polygon functions draw polygons. The_ polygon function uses the view coordinate system. 
The _ polygon_ w and. polygon_ wxy functions use the window coordinate system. 

The polygon is defined as containing numpts points whose coordinates are given in the array points. 

The argument//// determines whether the polygon is filled in or has only its outline drawn. The 
argument can have one of two values: 

_GFILLINTERIOR fill the interior by writing pixels with the current plot action using the current 

color and the current fill mask 

_GBORDER leave the interior unchanged; draw the outline of the figure with the current 

plot action using the current color and line style 

The _ polygon functions return a non-zero value when the polygon was successfully drawn; 
otherwise, zero is returned. 

_ setcolor^ setfillmask^ setlinestyle,_ setplotaction 

♦include <conio.h> 

♦include <graph.h> 

struct xycoord points[ 5 ] = { 

319, 140, 224, 209, 261, 320, 

378, 320, 415, 209 

} ; 

main () 

{ 

_ setvideomode( _ VRES16COLOR ); 

_ polygon( _ GBORDER, 5, points ); 
getch(); 

_ setvideomode( _DEFAULTMODE ) ; 

} 

produces the following: 
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polygon Functions 



Classification: PC Graphics 

Systems: _ polygon - DOS 

_ polygon_ w - DOS 
_ polygon_ wxy - DOS 
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popen 


Synopsis: 

Description: 


Returns: 

Errors: 


See Also: 
Example: 


♦include <stdio.h> 

FILE *popen( const char ‘command, const char ‘mode ); 

The popen function executes the command specified by command and creates a pipe between the 
calling process and the executed command. 

Depending on the mode argument, the stream pointer returned may be used to read from or write to the 
pipe. 

The executed command has an environment the same as its parents. The command will be started as 
follows: 

execl("/bin/sh", "sh", "-c", command, (char *) NULL); 

The mode argument to popen is a string that specifies an I/O mode for the pipe. 

Mode Meaning 

"r" The calling process will read from the standard output of the child process using the 

stream pointer returned by popen 

"w" The calling process will write to the standard input of the child process using the stream 

pointer returned by popen 

A stream opened by popen should be closed by the pclose function. 

The popen function returns a non-NULL stream pointer upon successful completion. If popen is 
unable to create either the pipe or the subprocess, a NULL stream pointer is returned and errno is set 
appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 

Constant Meaning 

EINVAL The mode argument is invalid. 

popen may also set errno values as described by the pipe , fork , and execl functions, 
pclose,exec... 
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/* 

* Executes the 'Is' command and prints all 

* its output preceded by an arrow. 

*/ 

♦include <stdio.h> 

int main() 

{ 

FILE *fp; 

char readbuf [256]; 

fp = popen("Is", "r"); 
if(fp == NULL) { 

printf("Failed to open pipe\n"); 
exit (1); 

} 

while(fgets(readbuf, 256, fp)) 
printf("-> %s", readbuf); 

pclose(fp); 

return 0; 

} 

Classification: POSIX 1003.1 
Systems: Linux 
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_popen, _ 


Synopsis: 


Description: 


Returns: 


Errors: 


See Also: 


wpopen 


♦include <stdio.h> 

FILE *_ popen( const char ‘command, const char *mode ); 

FILE *_ wpopen( const wchar_ t ‘command, const wchar_ t ‘mode ); 

The _ popen function executes the command specified by command and creates a pipe between the 
calling process and the executed command. 

Depending on the mode argument, the stream pointer returned may be used to read from or write to the 
pipe. 

The executed command has an environment the same as its parents. The command will be started as 
follows: spawnl(<shell_path>, <shell>, "-c", command, (char *)NULL); 

where <shell_ path> is an unspecified path for the shell utility and<shell> is one of 
"command.com" (DOS, Windows 95) or "cmd.exe" (Windows NT/2000, OS/2). 

The mode argument to _ popen is a string that specifies an I/O mode for the pipe. 

Mode Meaning 

"r" The calling process will read from the standard output of the child process using the 

stream pointer returned by _ popen 

"w" The calling process will write to the standard input of the child process using the stream 

pointer returned by _ popen 

The letter "t" may be added to any of the above modes to indicate that the file is (or must be) a text file 
(i.e., CR/LF pairs are converted to newline characters). 

The letter "b" may be added to any of the above modes to indicate that the file is (or must be) a binary 
file (an ISO C requirement for portability to systems that make a distinction between text and binary 
files). 

When default file translation is specified (i.e., no "t" or "b" is specified), the value of the global variable 
_ fmode establishes whether the file is to treated as a binary or a text file. Unless this value is changed 
by the program, the default will be text mode. 

A stream opened by _ popen should be closed by the_ pclose function. 

The _ popen function returns a non-NULL stream pointer upon successful completion. If_ popen is 
unable to create either the pipe or the subprocess, a NULL stream pointer is returned and errno is set 
appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 

Constant Meaning 

EINVAL The mode argument is invalid. 

_ popen may also seterrno values as described by the _ pipe andspawnl functions. 

_ grow_ handles^ pclose,perror, _ pipe 
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Example: 


Classification: 

Systems: 


popen, _wpopen 


/* 

* Executes a given program, converting all 

* output to upper case. 

*/ 

#include <stdio.h> 

♦include <stdlib.h> 

♦include <string.h> 

♦include <ctype.h> 

char buffer[256]; 

void main( int argc, char **argv ) 

{ 

int i; 
int c; 

FILE *f; 

for( i = 1; i < argc; i++ ) { 

strcat ( buffer, argv[i] ); 
strcat( buffer, " " ); 

} 

if ( ( f = _popen( buffer, "r" ) ) == NULL ) { 

perror( popen" ); 
exit ( 1 ); 

} 

while ( ( c = getc(f) ) != EOF ) { 

if( islower( c ) ) 

c = toupper ( c ); 
putchar( c ); 

} 

_ pclose( f ); 

} 

WATCOM 

_popen - Win32, OS/2 l.x(all), OS/2-32, Linux 
_ wpopen - Win32, OS/2 l.x(all), OS/2-32 
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pow 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 

double pow( double x, double y ); 

The pow function computes x raised to the power y. A domain error occurs if x is zero and y is less than 
or equal to 0, or if x is negative and y is not an integer. A range error may occur. 

The pow function returns the value of x raised to the power y. When the argument is outside the 
permissible range, the matherr function is called. Unless the default matherr function is replaced, 
it will set the global variable errno to EDOM, and print a "DOMAIN error" diagnostic message using 
the stderr stream. 

exp, log, sqrt 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", pow( 1.5, 2.5 ) ); 

} 

produces the following: 

2.755676 

ISOC 

Math 
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printf, wprintf 


Synopsis: #include <stdio.h> 

int printf( const char *format, ... ); 

♦include <wchar.h> 

int wprintf ( const wchar_ t *format, ... ); 

Safer C: The Safer C Library extension provides the printf_ s function which is a safer alternative to 

printf This newer print f_ s function is recommended to be used instead of the traditional "unsafe" 
printf function. 

Description: The printf function writes output to the file designated by stdout under control of the argument 
format. Th & format string is described below. 

The wprintf function is a wide-character version of printf. It accepts a wide-character string 
argument for format and produces wide character output. 

Returns: The printf function returns the number of characters written, or a negative value if an output error 

occurred. 

The wprintf function returns the number of wide characters written, or a negative value if an output 
error occurred. When an error has occurred, errno contains a value indicating the type of error that 
has been detected. 


See Also: _ bprintf,cprintf, fprintf, sprintf, _ vbprintf,vcprintf, vfprintf, vprintf, 

vsprintf 

Example: #include <stdio.h> 

void main( void ) 

{ 

char *weekday, *month; 


} 


weekday = "Saturday"; 

month = "April"; 

printf( "%s, %s %d, %d\n", 

weekday, month, 18, 1987 ) ; 
printf( "fl = %8.4f f2 = %10.2E x = %#08x i = %d\n", 
23.45, 3141.5926, Oxldb, -1 ); 


produces the following: 

Saturday, April 18, 1987 

fl = 23.4500 f2 = 3.14E+003 x = OxOOOldb i = -1 


Format Control String: The format control string consists of ordinary characters, that are written exactly as they 

occur in the format string, and conversion specifiers, that cause argument values to be written as they 
are encountered during the processing of the format string. An ordinary character in the format string is 
any character, other than a percent character (%), that is not part of a conversion specifier. A 
conversion specifier is a sequence of characters in the format string that begins with a percent character 
(%) and is followed, in sequence, by the following: 
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• zero or more format control flags that can modify the final effect of the format directive; 

• an optional decimal integer, or an asterisk character (’*’), that specifies a minimum field width to 
be reserved for the formatted item; 


• an optional precision specification in the form of a period character (.), followed by an optional 
decimal integer or an asterisk character (*); 


• an optional type length specification: one of "hh", "h", "1", "11", "j", "z", "t", "L", 
or "W"; and 


"164", "w", "N" 


• a character that specifies the type of conversion to be performed: one of the characters 
"bcCdeEfFgGinops SuxX". 

The valid format control flags are: 

the formatted item is left-justified within the field; normally, items are right-justified 

"+" a signed, positive object will always start with a plus character (+); normally, only negative items 
begin with a sign 

" " a signed, positive object will always start with a space character; if both "+" and " " are specified, 
"+" overrides " " 


"#" an alternate conversion form is used: 


• for "b" (unsigned binary) and "o" (unsigned octal) conversions, the precision is 
incremented, if necessary, so that the first digit is "0". 

• for "x" or "X" (unsigned hexadecimal) conversions, a non-zero value is prepended with 
"Ox" or "OX" respectively. 

• for "e", "E", "f", "F", "g" or "G" (any floating-point) conversions, the result always contains 
a decimal-point character, even if no digits follow it; normally, a decimal-point character 
appears in the result only if there is a digit to follow it. 

• in addition to the preceding, for "g" or "G" conversions, trailing zeros are not removed from 
the result. 


If no field width is specified, or if the value that is given is less than the number of characters in the 
converted value (subject to any precision value), a field of sufficient width to contain the converted 
value is used. If the converted value has fewer characters than are specified by the field width, the 
value is padded on the left (or right, subject to the left-justification flag) with spaces or zero characters 
("0"). If the field width begins with "0" and no precision is specified, the value is padded with zeros; 
otherwise the value is padded with spaces. If the field width is "*", a value of type int from the 
argument list is used (before a precision argument or a conversion argument) as the minimum field 
width. A negative field width value is interpreted as a left-justification flag, followed by a positive field 
width. 


As with the field width specifier, a precision specifier of causes a value of type int from the 
argument list to be used as the precision specifier. If no precision value is given, a precision of 0 is 
used. The precision value affects the following conversions: 
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• For "b", "d", "i", "o", "u", "x" and "X" (integer) conversions, the precision specifies the minimum 
number of digits to appear. 

• For "e", "E", "f" and "F" (fixed-precision, floating-point) conversions, the precision specifies the 
number of digits to appear after the decimal-point character. 

• For "g" and "G" (variable-precision, floating-point) conversions, the precision specifies the 
maximum number of significant digits to appear. 

• For "s" or "S" (string) conversions, the precision specifies the maximum number of characters to 
appear. 

A type length specifier affects the conversion as follows: 

• "hh" causes a "b", "d", "i", "o", "u", "x" or "X" (integer) format conversion to treat the argument 
as a signed char or unsigned char argument. Note that, although the argument may 
have been promoted to an int as part of the function call, the value is converted to the smaller 
type before it is formatted. 

• "hh" causes an "n" (converted length assignment) operation to assign the converted length to an 
object of type signed char. 

• "h" causes a "b", "d", "i", "o", "u", "x" or "X" (integer) format conversion to treat the argument as 
a short int or unsigned short int argument. Note that, although the argument may 
have been promoted to an int as part of the function call, the value is converted to the smaller 
type before it is formatted. 

• "h" causes an "f" format conversion to interpret a long argument as a fixed-point number 
consisting of a 16-bit signed integer part and a 16-bit unsigned fractional part. The integer part is 
in the high 16 bits and the fractional part is in the low 16 bits. 

struct fixpt { 

unsigned short fraction; /* Intel architecture! */ 
signed short integral; 

}; 


struct fixpt fool = 

{ 0x8000, 1234 }; /* represents 1234.5 */ 
struct fixpt foo2 = 

{ 0x8000, -1 }; /* represents -0.5 (-1+.5) */ 

The value is formatted with the same rules as for floating-point values. This is a Open Watcom 
extension. 

• "h" causes an "n" (converted length assignment) operation to assign the converted length to an 
object of type short int. 

• "h" causes an "s" operation to treat the argument string as an ASCII character string composed of 
8-bit characters. 

For printf and related byte input/output functions, this specifier is redundant. For wprintf 
and related wide character input/output functions, this specifier is required if the argument string 
is to be treated as an 8-bit ASCII character string; otherwise it will be treated as a wide character 
string. 
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printf ( "%s%d", "Num=", 12345 ); 

wprintf( L"%hs%d", "Num=", 12345 ); 

• "1" causes a "b", "d", "i", "o", "u", "x" or "X" (integer) conversion to process a long int or 
unsigned long int argument. 

• "1" causes an "n" (converted length assignment) operation to assign the converted length to an 
object of type long int. 

• "1" or "w" cause an "s" operation to treat the argument string as a wide character string (a string 
composed of characters of type wchar_ t). 

For printf and related byte input/output functions, this specifier is required if the argument 
string is to be treated as a wide character string; otherwise it will be treated as an 8-bit ASCII 
character string. For wprintf and related wide character input/output functions, this specifier is 
redundant. 

printf ( "%ls%d", L"Num=", 12345 ); 

wprintf( L"%s%d", L"Num=", 12345 ); 

• "11" causes a "b", "d", "i", "o", "u", "x" or "X" (integer) conversion to process a long long or 
unsigned long long argument (e.g., %lld). 

• "11" causes an "n" (converted length assignment) operation to assign the converted length to an 
object of type long long int. 

• "j" causes a "b", "d", "i", "o", "u", "x" or "X" (integer) conversion to process an intmax_ t or 
uintmax_ t argument. 

• "j" causes an "n" (converted length assignment) operation to assign the converted length to an 
object of type intmax_ t. 

• "z" causes a "b", "d", "i", "o", "u", "x" or "X" (integer) conversion to process a size_ t or the 
corresponding signed integer type argument. 

• "z" causes an "n" (converted length assignment) operation to assign the converted length to an 
object of signed integer type corresponding to size_ t. 

• "t" causes a "b", "d", "i", "o", "u", "x" or "X" (integer) conversion to process a ptrdif f_ t or 
the corresponding unsigned integer type argument. 

• "t" causes an "n" (converted length assignment) operation to assign the converted length to an 
object of type ptrdif f_ t. 

• "164" causes a "b", "d", "i", "o", "u", "x" or "X" (integer) conversion to process an_int 64 or 

unsigned_int64 argument (e.g., %I64d). 

• "L" causes an "e", "E", "f", "F", "g", "G" (double) conversion to process a long double 
argument. 

• "W" causes the pointer associated with "n", "p", "s" conversions to be treated as a far pointer. 

• "N" causes the pointer associated with "n", "p", "s" conversions to be treated as a near pointer. 
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The valid conversion type specifiers are: 

b An argument of type int is converted to an unsigned binary notation and written to the output 
stream. The default precision is 1, but if more digits are required, leading zeros are added. 

c An argument of type int is converted to a value of type char and the corresponding ASCII 
character code is written to the output stream. 

C An argument of type wchar_ t is converted to a multibyte character and written to the output 
stream. 

d, i An argument of type int is converted to a signed decimal notation and written to the output 

stream. The default precision is 1, but if more digits are required, leading zeros are added. 

e, E An argument of type double is converted to a decimal notation in the form 

[ - ] d. ddde [ + | - ] ddd similar to FORTRAN exponential (E) notation. The leading sign 
appears (subject to the format control flags) only if the argument is negative. If the argument is 
non-zero, the digit before the decimal-point character is non-zero. The precision is used as the 
number of digits following the decimal-point character. If the precision is not specified, a default 
precision of six is used. If the precision is 0, the decimal-point character is suppressed. The value 
is rounded to the appropriate number of digits. For "E" conversions, the exponent begins with the 
character "E" rather than "e". The exponent sign and a three-digit number (that indicates the 
power of ten by which the decimal fraction is multiplied) are always produced. 

f, F An argument of type double is converted to a decimal notation in the form [ - ] ddd. ddd 

similar to FORTRAN fixed-point (F) notation. The leading sign appears (subject to the format 
control flags) only if the argument is negative. The precision is used as the number of digits 
following the decimal-point character. If the precision is not specified, a default precision of six is 
used. If the precision is 0, the decimal-point character is suppressed, otherwise, at least one digit 
is produced before the decimal-point character. The value is rounded to the appropriate number of 
digits. 

g, G An argument of type double is converted using either the "f" or "e" (or "F" or "E", for a "G" 

conversion) style of conversion depending on the value of the argument. In either case, the 
precision specifies the number of significant digits that are contained in the result, "e" style 
conversion is used only if the exponent from such a conversion would be less than -4 or greater 
than the precision. Trailing zeros are removed from the result and a decimal-point character only 
appears if it is followed by a digit. 

n The number of characters that have been written to the output stream is assigned to the integer 
pointed to by the argument. No output is produced. 

o An argument of type int is converted to an unsigned octal notation and written to the output 
stream. The default precision is 1, but if more digits are required, leading zeros are added. 

p, P An argument of type void * is converted to a value of type int and the value is formatted as for 
a hexadecimal ("x") conversion. 

s Characters from the string specified by an argument of type char * or wchar_ t *, up to, but 
not including the terminating null character (’\0’), are written to the output stream. If a precision 
is specified, no more than that many characters (bytes) are written (e.g., %.7s) 

For printf this specifier refers to an ASCII character string unless the "1" or "w" modifiers are 
used to indicate a wide character string. 
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For wprintf, this specifier refers to a wide character string unless the "h" modifier is used to 
indicate an ASCII character string. *. 

S Characters from the string specified by an argument of type wchar_ t *, up to, but not including 
the terminating null wide character (L’\0’), are converted to multibyte characters and written to the 
output stream. If a precision is specified, no more than that many characters (bytes) are written 
(e.g.,%.7S) 

u An argument of type int is converted to an unsigned decimal notation and written to the output 
stream. The default precision is 1, but if more digits are required, leading zeros are added. 

x, X An argument of type int is converted to an unsigned hexadecimal notation and written to the 
output stream. The default precision is 1, but if more digits are required, leading zeros are added. 
Hexadecimal notation uses the digits "0" through "9" and the characters "a" through "f" or "A" 
through "F" for "x" or "X" conversions respectively, as the hexadecimal digits. Subject to the 
alternate-form control flag, "Ox" or "OX" is prepended to the output. 

Any other conversion type specifier character, including another percent character (%), is written to the 
output stream with no special interpretation. 

The arguments must correspond with the conversion type specifiers, left to right in the string; otherwise, 
indeterminate results will occur. 

If the value corresponding to a floating-point specifier is infinity, or not a number (NaN), then the 
output will be "inf" or "-inf' for infinity, and "nan" or "-nan" for NaN’s. If the conversion specifier is 
an uppercase character (ie. "E", "F", or "G"), the output will be uppercase as well ("INF", "NAN"), 
otherwise the output will be lowercase as noted above. 

The pointer size specification ("N" or "W") is only effective on platforms that use a segmented memory 
model, although it is always recognized. 

For example, a specifier of the form " % 8 . * f " will define a field to be at least 8 characters wide, and 
will get the next argument for the precision to be used in the conversion. 

Classification: ISO C (except for N, W pointer size modifiers and b, 164 specifiers) 
wprintf is ISO C95 

Systems: printf - All, Linux, RDOS, Netware 

wprintf - All, Linux 
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Synopsis: 


Constraints: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

int printf_ s ( const char * restrict format, ... ); 

♦include <wchar.h> 

int wprintf_ s( const wchar_ t * restrict format, ... ) ; 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and printf_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

The format argument shall not be a null pointer. The %n specifier (modified or not by flags, field width, 
or precision) shall not appear in the string pointed to by format. Any argument to print f_ s 
corresponding to a % s specifier shall not be a null pointer. 

If there is a runtime-constraint violation, the print f_ s function does not attempt to produce further 
output, and it is unspecified to what extent printf_ s produced output before discovering the 
runtime-constraint violation. 

The print f_ s function is equivalent to theprintf function except for the explicit 
runtime-constraints listed above. 

The wprintf_ s function is a wide-character version ofprintf_ s. It accepts a wide-character 
string argument for format and produces wide character output. 

The print f_ s function returns the number of characters written, or a negative value if an output error 
or runtime-constraint violation occurred. 


The wprintf_ s function returns the number of wide characters written, or a negative value if an 
output error or runtime-constraint violation occurred. 

_ bprintf,cprintf, fprintf, printf, sprintf, _ vbprintf,vcprintf, vfprintf, 
vprintf, vsprintf 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 


void main( void ) 

{ 

char *weekday, *month; 


} 


weekday = "Saturday"; 

month = "April"; 

printf_ s( "%s, %s %d, %d\n", 

weekday, month, 18, 1987 ); 

printf_ s( "fl = %8.4f f2 = %10.2E x = %#08x i = %d\n", 
23.45, 3141.5926, Oxldb, -1 ); 


produces the following: 

Saturday, April 18, 1987 

fl = 23.4500 f2 = 3.14E+003 x = OxOOOldb i = -1 


TR 24731 
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Systems: 


printf_ s - All, Linux, RDOS, Netware 
wprintf_ s - All, Linux 
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Synopsis: 

Description: 

Returns: 


See Also: 
Example: 


Classification: 

Systems: 


♦include <stdio.h> 

int putc( int c, FILE *fp ); 

♦include <stdio.h> 

♦include <wchar.h> 

wint_ t putwc ( wint_ t c, FILE *fp ); 

The putc function is equivalent to fputc, except it may be implemented as a macro. The putc 
function writes the character specified by the argument c to the output stream designated by //;. 

The putwc function is identical to putc except that it converts the wide character specified by c to a 
multibyte character and writes it to the output stream. 

The put c function returns the character written or, if a write error occurs, the error indicator is set and 
putc returns EOF. 

The putwc function returns the wide character written or, if a write error occurs, the error indicator is 
set and putwc returns WEOF. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 

fopen, fputc, fputchar, fputs, putchar, puts, ferror 

♦include <stdio.h> 

void main() 

{ 

FILE *fp; 
int c; 

fp = fopen( "file", "r" ); 
if( fp != NULL ) { 

while( (c = fgetc( fp )) != EOF ) 

putc( c, stdout ); 
fclose ( fp ); 

} 

} 

ISOC 

putc - All, Linux, RDOS, Netware 
putwc - All, Linux 
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Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <conio.h> 
int putch( int c ) ; 

The putch function writes the character specified by the argument c to the console. 

The put ch function returns the character written. 

getch, getche, kbhit, ungetch 

♦include <conio.h> 

♦include <stdio.h> 

void main() 

{ 

FILE *fp; 
int c; 

fp = fopen( "file", "r" ); 
if ( fp != NULL ) { 

while( (c = fgetc( fp )) != EOF ) 

putch ( c ); 

} 

fclose ( fp ); 

} 

WATCOM 

All, Linux, RDOS, Netware 
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Synopsis: 

Description: 


Returns: 


See Also: 
Example: 


Classification: 

Systems: 


♦include <stdio.h> 
int putchar( int c ) ; 

♦include <wchar.h> 

wint_ t putwchar ( wint_ t c ) ; 

The putchar function writes the character specified by the argument c to the output stream stdout. 
The function is equivalent to 

fputc( c, stdout ); 

The putwchar function is identical to putchar except that it converts the wide character specified 
by c to a multibyte character and writes it to the output stream. 

The putchar function returns the character written or, if a write error occurs, the error indicator is set 
and putchar returns EOF. 

The putwchar function returns the wide character written or, if a write error occurs, the error 
indicator is set and putwchar returns WEOF. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 

fopen, fputc, fputchar, fputs, putc, puts, ferror 

♦include <stdio.h> 

void main() 

{ 

FILE *fp; 
int c; 

fp = fopen( "file", "r" ); 
c = fgetc ( fp ); 
while ( c != EOF ) { 

putchar ( c ); 
c = fgetc( fp ); 

} 

fclose ( fp ); 

} 

ISOC 

putwchar is ISO C95 

putchar - All, Linux, Netware 
putwchar - All, Linux 
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Synopsis: #include <stdlib.h> 

int putenv ( const char *env_ name ); 

int _ putenv ( const char *env_ name ); 

int _ wputenv ( const wchar_ t *env_ name ); 

Description: The environment list consists of a number of environment names, each of which has a value associated 
with it. Entries can be added to the environment list with the DOS set command or with the putenv 
function. All entries in the environment list can be displayed by using the DOS set command with no 
arguments. A program can obtain the value for an environment variable by using the getenv function. 

When the value of env_name has the format 

env_ name=value 

an environment name and its value is added to the environment list. When the value of env_name has 
the format 


env_ name= 

the environment name and value is removed from the environment list. 

The matching is case-insensitive; all lowercase letters are treated as if they were in upper case. 

The space into which environment names and their values are placed is limited. Consequently, the 
putenv function can fail when there is insufficient space remaining to store an additional value. 

The _ putenv function is identical toputenv. Use _ putenv for ANSI naming conventions. 

The _ wputenv function is a wide-character version ofputenv the env_name argument to 
_ wputenv is a wide-character string. 

putenv and _ wputenv affect only the environment that is local to the current process; you cannot 
use them to modify the command-level environment. That is, these functions operate only on data 
structures accessible to the run-time library and not on the environment "segment" created for a process 
by the operating system. When the current process terminates, the environment reverts to the level of 
the calling process (in most cases, the operating-system level). However, the modified environment can 
be passed to any new processes created by _spawn, _exec, or system, and these new processes get any 
new items added by putenv and _wputenv. 

With regard to environment entries, observe the following cautions: 

• Do not change an environment entry directly; instead, use putenv or _ wputenv to change it. To 
modify the return value of putenv or _ wputenv without affecting the environment table, use 
_ strdup orstrcpy to make a copy of the string. 

• If the argument env_name is not a literal string, you should duplicate the string, since putenv 
does not copy the value; for example, 

putenv( _ strdup ( buffer ) ); 

• Never free a pointer to an environment entry, because the environment variable will then point to 
freed space. A similar problem can occur if you pass putenv or _ wputenv a pointer to a local 
variable, then exit the function in which the variable is declared. 
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Returns: 

Errors: 

See Also: 
Example: 


Classification: 

Systems: 


putenv, _putenv, _wputenv 


putenv use the global variable _environ to access the _ wputenv use _wenviron. putenv and 
_ wputenv may change the value of _environ and _wenviron, thusputenv and _ wputenv to global 
variables, see _environ, _wenviron. 

To assign a string to a variable and place it in the environment list: 

C>SET INCLUDE=C:\WATCOM\H 

To see what variables are in the environment list, and their current assignments: 

C>SET 

COMSPEC=C:\COMMAND.COM 
PATH=C:\;C:\WATCOM 
INCLUDE=C:\WATCOM\H 

C> 

The putenv function returns zero when it is successfully executed and returns -1 when it fails. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
ENOMEM Not enough memory to allocate a new environment string, 

clearenv, getenv, setenv 

The following gets the string currently assigned to INCLUDE and displays it, assigns a new value to it, 
gets and displays it, and then removes the environment name and value. 

♦include <stdio.h> 

♦include <stdlib.h> 

void main() 

{ 

char *path; 

path = getenv( "INCLUDE" ); 
if( path != NULL ) 

printf( "INCLUDE=%s\n", path ); 
if( putenv( "INCLUDE=mylib;yourlib" ) != 0 ) 

printf ( "putenv failed" ); 
path = getenv( "INCLUDE" ); 
if( path != NULL ) 

printf ( "INCLUDE=%s\n", path ); 
if( putenv( "INCLUDE=" ) != 0 ) 

printf ( "putenv failed" ); 

} 

produces the following: 

INCLUDE=C:\WATCOM\H 
INCLUDE=mylib;yourlib 

POSIX 1003.1 

_putenv conforms to ANSI naming conventions 
_wputenv is WATCOM 

putenv - All, Linux, RDOS 


Library Functions and Macros 857 




putenv, _putenv, _wputenv 


putenv - All, Linux, 
wputenv - All, Linux 


RDOS 
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putimage Functions 


Synopsis: 

Description: 


Returns: 
See Also: 


#include <graph.h> 

void _ FAR _ putimage( short x, short y, 

char _ HUGE *image, short mode ) ; 

void _ FAR _putimage_w( double x, double y, 

char _ HUGE * image, short mode ) ; 

The _ putimage functions display the screen image indicated by the argument image. The 
_ putimage function uses the view coordinate system. The_ putimage_ w function uses the window 
coordinate system. 

The image is displayed upon the screen with its top left corner located at the point with coordinates 
(x, y) . The image was previously saved using the _ get image functions. The image is displayed in 
a rectangle whose size is the size of the rectangular image saved by the _ get image functions. 

The image can be displayed in a number of ways, depending upon the value of the mode argument. 

This argument can have the following values: 


_GPSET 

replace the rectangle on the screen by the saved image 

jGPRESET 

replace the rectangle on the screen with the pixel values of the saved image 
inverted; this produces a negative image 

_GAND 

produce a new image on the screen by ANDing together the pixel values 
from the screen with those from the saved image 

_GOR 

produce a new image on the screen by ORing together the pixel values from 
the screen with those from the saved image 

_GXOR 

produce a new image on the screen by exclusive ORing together the pixel 
values from the screen with those from the saved image; the original screen 
is restored by two successive calls to the _putimage function with this value, 
providing an efficient method to produce animated effects 


The _ putimage functions do not return a value. 


getimage,_ imagesize 


Library Functions and Macros 859 




putimage Functions 


Example: #include <conio.h> 

♦include <graph.h> 
♦include <malloc.h> 


main () 

{ 

char *buf; 
int y; 


_ setvideomode ( _VRES16C0L0R ); 

_ellipse ( _ GFILLINTERIOR, 100, 100, 200, 200 ); 
buf = (char*) malloc( 



imagesize( 

100, 

, 100, 201, 

buf != NULL 

) { 




_ getimage( 

100, 

100, 

201, 

201, buf ); 

_ putimage( 

260, 

200, 

buf. 

_ GPSET ); 

_ putimage( 

420, 

100, 

buf. 

_ GPSET ); 


for( y = 100; y < 300; ) { 


_ putimage( 
y += 20; 

420, 

Y r 

buf, _ GXOR ); 

_ putimage( 

420, 

Yr 

buf, _ GXOR ); 


free( buf ) ; 

} 

getch(); 

_ setvideomode( _ DEFAULTMODE ) ; 


Classification: PC Graphics 

Systems: _ putimage - DOS 

_ putimage_ w - DOS 
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puts, _putws 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdio.h> 

int puts( const char *buf ) ; 

♦include <stdio.h> 

int _ putws ( const wchar_ t *bufs ) ; 

The puts function writes the character string pointed to by buflo the output stream designated by 
stdout, and appends a new-line character to the output. The terminating null character is not written. 

The _ putws function is identical toputs except that it converts the wide character string specified by 
buf to a multibyte character string and writes it to the output stream. 

The puts function returns EOF if an error occurs; otherwise, it returns a non-negative value (the 
number of characters written including the new-line character). The _ putws function returnsEOF if a 
write or encoding error occurs; otherwise, it returns a non-negative value (the number of characters 
written including the new-line character). When an error has occurred, errno contains a value 
indicating the type of error that has been detected. 

fopen, fputc, fputchar, fputs, putc, putchar, terror 

♦include <stdio.h> 

void main() 

{ 

FILE *fp; 

char buffer[ 80 ]; 

fp = freopen( "file", "r", stdin ); 
while] gets( buffer ) != NULL ) { 

puts( buffer ); 

1 

fclose ( fp ); 

1 

ISOC 

_putws is WATCOM 

puts - All, Linux, RDOS, Netware 
_putws - All, Linux 
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putw 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdio.h> 

int _ putw( int binint, FILE *fp ); 

The _ putw function writes a binary value of type int to the current position of the streamer _ putw 
does not affect the alignment of items in the stream, nor does it assume any special alignment. 

_ putw is provided primarily for compatibility with previous libraries. Portability problems may occur 
with _ putw because the size of an int and the ordering of bytes within an int differ across systems. 

The _ putw function returns the value written or, if a write error occurs, the error indicator is set and 
_ putw returnsEOF. Since EOF is a legitimate value to write to fp, use terror to verify that an error 
has occurred. 

terror, fopen, fputc, fputchar, fputs, putc, putchar, puts 

♦include <stdio.h> 

void main() 

{ 

FILE *fp; 
int c; 

fp = fopen( "file", "r" ); 
if( fp != NULL ) { 

while ( (c = _ getw( fp )) != EOF ) 

_putw( c, stdout ); 
fclose ( fp ); 

} 

} 

WATCOM 

All, Linux, RDOS, Netware 
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qsort 


Synopsis: 

Safer C: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <stdlib.h> 
void qsort( void *base, 
size_ t num, 
size_ t width, 

int (*compar) ( const void *, 

const void *) ); 

The Safer C Library extension provides the qsort_ s function which is a safer alternative toqsort 
This newer qsort_ s function is recommended to be used instead of the traditional "unsafe" qsort 
function. 


The qsort function sorts an array of man elements, which is pointed to by base, using a modified 
version of Sedgewick’s Quicksort algorithm. Each element in the array is width bytes in size. The 
comparison function pointed to by compar is called with two arguments that point to elements in the 
array. The comparison function shall return an integer less than, equal to, or greater than zero if the first 
argument is less than, equal to, or greater than the second argument. 

The version of the Quicksort algorithm that is employed was proposed by Jon Louis Bentley and M. 
Douglas Mcllroy in the article "Engineering a sort function" published in Software — Practice and 
Experience, 23( 11): 1249-1265, November 1993. 

The qsort function returns no value. 


qsort_ sjosearch, bsearch_ s 

#include <stdio.h> 

#include <stdlib.h> 

#include <string.h> 

char *CharVect[] = { "last", "middle", "first" }; 

int compare! const void *opl, const void *op2 ) 

{ 

const char **pl = (const char **) opl; 
const char **p2 = (const char **) op2; 
return! strcmp( *pl, *p2 ) ); 

} 


void main() 

{ 

qsort ( CharVect, sizeof(CharVect)/sizeof(char 
sizeof(char *), compare ); 
printf( "%s %s %s\n", 

CharVect[0], CharVect[1], CharVect[2] 


} 


') , 


produces the following: 
first last middle 


ISOC 


All, Linux, RDOS, Netware 
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qsort_s 


Synopsis: 


Constraints: 


Description: 


Returns: 

See Also: 
Example: 


♦ define_ STDC_ WANT_ LIB_ EXT1_1 

♦include <stdlib.h> 

errno_ t qsort_ s( void *base, 

rsize_ t nmemb, 
rsize_ t size, 

int (*compar)( const void *x, const void *y, void *context ), 
void *context ); 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and qsort_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither nmemb nor size shall be greater than RSIZE_ MAX. If nmemb is not equal to zero, then neither 
base nor compar shall be a null pointer. If there is a runtime-constraint violation, the qsort_ s 
function does not sort the array. 

The qsort_ s function sorts an array of nmemb objects, the initial element of which is pointed to by 
base. The size of each object is specified by size. The contents of the array are sorted into ascending 
order according to a comparison function pointed to by compar. which is called with three arguments. 
The first two point to the objects being compared. The function shall return an integer less than, equal 
to, or greater than zero if the first argument is considered to be respectively less than, equal to, or 
greater than the second. The third argument to the comparison function is the context argument passed 
to qsort_ s The sole use of context byqsort_ s is to pass it to the comparison function. If two 
elements compare as equal, their relative order in the resulting sorted array is unspecified. 

The qsort_ s function returns zero if there was no runtime-constraint violation. Otherwise, a 
non-zero value is returned. 


qsort, bsearch, bsearch_ s 

♦ define STDC_ WANT_ LIB_ EXT1 1 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <string.h> 

char *CharVect[] = { "last", "middle", "first" }; 

int compare! const void *opl, const void *op2, void *context ) 

{ 

const char **pl = (const char **) opl; 
const char **p2 = (const char **) op2; 
return! strcmp( *pl, *p2 ) ); 

} 


void main() 

{ 


} 


void * context = NULL; 

qsort_ s ( CharVect, sizeof(CharVect)/sizeof(char 
sizeof(char *), compare, context ); 
printf ( "%s %s %s\n", 

CharVect[0], CharVect[1], CharVect[2] ); 


★ 


produces the following: 
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qsort_s 


first last middle 

Classification: TR 24731 

Systems: All, Linux, RDOS, Netware 
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raise 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


♦include <signal.h> 

int raise( int condition ) ; 

The raise function signals the exceptional condition indicated by the condition argument. The 
possible conditions are defined in the <signal. h> header file and are documented with the signal 
function. The signal function can be used to specify the action which is to take place when such a 
condition occurs. 

The raise function returns zero when the condition is successfully raised and a non-zero value 
otherwise. There may be no return of control following the function call if the action for that condition 
is to terminate the program or to transfer control using the long jmp function. 

signal 

/* 

* This program waits until a SIGINT signal 

* is received. 

*/ 

♦include <stdio.h> 

♦include <signal.h> 

sig_ atomic_ t signal_ count; 
sig_ atomic_ t signal_ number; 

static void alarm_ handler ( int signum ) 

{ 

++signal_ count; 
signal_ number = signum; 

} 

void main() 

{ 

unsigned long i; 

signal_ count = 0; 

signal_ number = 0; 

signal ( SIGINT, alarm_ handler ); 

printf("Signal will be auto-raised on iteration " 

"10000 or hit CTRL-C.\n"); 
printf("Iteration: "); 

for( i = 0; i < 100000; ++i ) 

{ 

printf("\b\b\b\b\b%*d", 5, i); 
if( i == 10000 ) raise(SIGINT); 
if( signal_ count > 0 ) break; 

} 
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raise 


Classification: 

Systems: 


} 


if( i == 100000 ) { 

printf("\nNo signal was raised.\n"); 

} else if( i == 10000 ) { 

printf("\nSignal %d was raised by the " 

"raise () function.\n" , signal_ number); 

} else { 

printf("\nUser raised the signal.\n", 
signal_ number); 


} 


ISOC 


All, Linux, RDOS, Netware 
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rand 

Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdlib.h> 
int rand( void ); 

The rand function computes a sequence of pseudo-random integers in the range 0 to RAND 
(32767). The sequence can be started at different values by calling the srand function. 

The rand function returns a pseudo-random integer. 

srand 

♦include <stdio.h> 

♦include <stdlib.h> 

void main() 

{ 

int i; 

for( i=l; i < 10; ++i ) { 

printf( "%d\n", rand() ); 

} 

} 

ISOC 

All, Linux, RDOS, Netware 


MAX 
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read, jead 


Synopsis: 

Description: 


Returns: 


See Also: 
Example: 


♦include <io.h> 

int read( int handle, void *buffer, unsigned len ); 
int _read( int handle, void *buffer, unsigned len ); 

The read function reads data at the operating system level. The number of bytes transmitted is given 
by len and the data is transmitted starting at the address specified by buffer. 

The handle value is returned by the open function. The access mode must have included either 
0_ RDONLY orO_ RDWR when theopen function was invoked. The data is read starting at the current 
file position for the file in question. This file position can be determined with the tell function and 
can be set with the lseek function. 

When 0_ BINARY is included in the access mode, the data is transmitted unchanged. WhenO_ TEXT is 
included in the access mode, the data is transmitted with the extra carriage return character removed 
before each linefeed character encountered in the original data. 

The _ read function is identical toread. Use _ read for ANSI naming conventions. 

The read function returns the number of bytes of data transmitted from the file to the buffer (this does 
not include any carriage-return characters that were removed during the transmission). Normally, this is 
the number given by the len argument. When the end of the file is encountered before the read 
completes, the return value will be less than the number of bytes requested. 

A value of -1 is returned when an input/output error is detected. When an error has occurred, errno 
contains a value indicating the type of error that has been detected. 

close, creat, fread, open, write 

♦include <stdio.h> 

♦include <fcntl.h> 

♦include <io.h> 

void main( void ) 

{ 

int handle; 
int size_ read; 
char buffer[80]; 

/* open a file for input */ 

handle = open ( "file", 0_ RDONLY | 0_ TEXT ); 
if( handle != -1 ) { 

/* read the text */ 

size_ read = read( handle, buffer, 

sizeof( buffer ) ); 

/* test for error */ 

if ( size_ read == -1 ) { 

printf( "Error reading file\n" ); 

} 
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read, jead 


/* close the file */ 

close ( handle ); 

} 

} 

Classification: POSIX 1003.1 

_read conforms to ANSI naming conventions 

Systems: read - All, RDOS, Netware 

_ read - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 


RDOS 
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readdir, _wreaddir 


Synopsis: #include <direct.h> 

struct dirent *readdir( DIR *dirp ); 
struct _ wdirent *_ wreaddir ( WDIR *dirp ); 


Description: The readdir function obtains information about the next matching file name from the argument dirp. 

The argument dirp is the value returned from the opendir function. The readdir function can be 
called repeatedly to obtain the list of file names contained in the directory specified by the pathname 
given to opendir. The function closedir must be called to close the directory and free the 
memory allocated by opendir. 


The file <direct. h> contains definitions for the structure dirent. 


#if defined!_OS2_) || defined!_NT_) 

♦ define NAME_ MAX 255 /* maximum for HPFS or NTFS */ 

♦ else 


♦ define NAME_ MAX 12 /* 

♦endif 

struct dirent { 

char d_dta[ 21 ]; 
char d_ attr; 

unsigned short int d_ time; 
unsigned short int d_ date; 
long d_ size; 

char d_ name [ NAME_ MAX 

unsigned short d_ ino; 
char d_ first; 

} ; 


8 chars + '.' + 3 chars */ 


/* disk transfer area */ 
/* file's attribute */ 

/* file's time */ 

/* file's date */ 

/* file's size */ 

+ 1 ]; /* file's name */ 

/* serial number */ 

/* flag for 1st time */ 


The file attribute field d_ attr field is a set of bits representing the following attributes. 


A_ RDONLY 
A_ HIDDEN 
A_ SYSTEM 
A_ VOL ID 
A_ SUBDIR 
A_ ARCH 


/* Read-only file */ 

/* Hidden file */ 

/* System file */ 

/* Volume-ID entry (only MSFT knows) */ 
/* Subdirectory */ 

/* Archive file */ 


If the _ A_ RDONLY bit is off, then the file is read/write. 

The format of the d_ time field is described by the following structure (this structure is not defined in 
any Open Watcom header file). 

typedef struct { 


unsigned 

short 

twosecs 

5; 

/* 

seconds 

/ 2 */ 

unsigned 

short 

minutes 

6; 

/* 

minutes 

(0,59) 

unsigned 

short 

hours 

5; 

/* 

hours (0 

,23) * 


} ftime_ t; 

The format of the d_ date field is described by the following structure (this structure is not defined in 
any Open Watcom header file). 
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readdir, _wreaddir 


Returns: 


Errors: 

See Also: 
Example: 


typedef struct { 


unsigned 

short 

day 

: 5; 

/* 

day (1,31) */ 

unsigned 

short 

month 

: 4; 

/* 

month (1,12) */ 

unsigned 

short 

year 

: 7; 

/* 

0 is 1980 */ 


} fdate_ t; 

See the sample program below for an example of the use of these structures. 

The _ wreaddir function is identical toreaddir except that it reads a directory of wide-character 
filenames. 

The file <direct. h> contains definitions for the structure _ wdirent. 
struct _ wdirent { 

char d_dta[21]; /* disk transfer area */ 

char d_ attr; /* file's attribute */ 

unsigned short int d_time;/* file's time */ 
unsigned short int d_date;/* file's date */ 
long d_ size; /* file's size */ 

wchar_ t d_ name [NAME_ MAX+1 ] ;/* file's name */ 
unsigned short d_ ino; /* serial number (not used) */ 
char d_ first; /* flag for 1st time */ 

} ; 


When successful, readdir returns a pointer to an object of type struct dirent. When an error occurs, 
readdir returns the value NULL and errno is set to indicate the error. When the end of the 
directory is encountered, readdir returns the value NULL and errno is unchanged. 

When successful, _ wreaddir returns a pointer to an object of type struct _wdirent. When an error 
occurs, _ wreaddir returns the valueNULL and errno is set to indicate the error. When the end of 
the directory is encountered, _ wreaddir returns the valueNULL and errno is unchanged. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 

EBADF The argument dirp does not refer to an open directory stream. 

closedir, _ dos_ find...ppendir, rewinddir 

To get a list of files contained in the directory \watcom\h on your default disk: 
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readdir, _wreaddir 


♦include <stdio.h> 
♦include <direct.h> 

typedef struct { 


unsigned short 

twosecs 

5; 

/* seconds / 2 */ 

unsigned short 

minutes 

6; 


unsigned short 
} ftime_ t; 

hours 

5; 


typedef struct { 

unsigned short 

day 

5; 


unsigned short 

month 

4; 


unsigned short 

year 

7; 



} fdate_ t; 


void main () 

{ 

DIR *dirp; 

struct dirent *direntp; 
ftime_ t *f_time; 
fdate_ t *f_ date; 

dirp = opendir( "\\watcom\\h" ); 
if( dirp != NULL ) { 

for(;;) { 

direntp = readdir( dirp ) ; 
if( direntp == NULL ) break; 
f_ time = (ftime_t *)&direntp->d_ time; 
f_ date = (fdate_ t *)&direntp->d_ date; 
printf ( "%-12s %d/%2.2d/%2.2d " 

"%2.2d:%2.2d:%2.2d \n", 
direntp->d_ name, 
f_ date->year + 1980, 
f_ date->month, 
f_ date->day, 
f_ time->hours, 
f_ time->minutes, 
f_ time->twosecs * 2 ) ; 

} 

closedir( dirp ); 

} 

} 

Note the use of two adjacent backslash characters (\) within character-string constants to signify a single 
backslash. 

Classification: POSIX 1003.1 

_wreaddir is WATCOM 

Systems: readdir - All, Linux, RDOS, Netware 

_ wreaddir - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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realloc Functions 


Synopsis: #include <stdlib.h> For ISO C compatibility (realloc only) 

♦include <malloc.h> Required for other function prototypes 
void * realloc ( void *old_ blk, size_ t size ) ; 

void_based (void) *_ brealloc (_segment seg, 

void_based (void) *old_ blk, 

size_ t size ) ; 

void_far *_ frealloc ( void_far *old_ blk, 

size_ t size ) ; 

void_near *_ nrealloc ( void_near *old_ blk, 

size_ t size ) ; 

Description: When the value of the old_b!k argument is NULL, a new block of memory of size bytes is allocated. 

If the value of size is zero, the corresponding free function is called to release the memory pointed to 
by old_blk. 

Otherwise, the realloc function re-allocates space for an object of size bytes by either: 

• shrinking the allocated size of the allocated memory block oldjblk when size is sufficiently 
smaller than the size of old_blk. 

• extending the allocated size of the allocated memory block old_blk if there is a large enough 
block of unallocated memory immediately following oldjblk. 

• allocating a new block and copying the contents of oldjblk to the new block. 

Because it is possible that a new block will be allocated, any pointers into the old memory should not be 
maintained. These pointers will point to freed memory, with possible disastrous results, when a new 
block is allocated. 

The function returns NULL when the memory pointed to by old_blk cannot be re-allocated. In this case, 
the memory pointed to by oldjblk is not freed so care should be exercised to maintain a pointer to the 
old memory block. 

buffer = (char *) realloc ( buffer, 100 ); 

In the above example, buffer will be set to NULL if the function fails and will no longer point to the 
old memory block. If buf f er was your only pointer to the memory block then you will have lost 
access to this memory. 

Each function reallocates memory from a particular heap, as listed below: 

Function Heap 

realloc Depends on data model of the program 

Jjrealloc Based heap specified by seg value 
Jrealloc Far heap (outside the default data segment) 
jirealloc Near heap (inside the default data segment) 

In a small data memory model, the realloc function is equivalent to the _ nrealloc function; in a 
large data memory model, the realloc function is equivalent to the _ frealloc function. 
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realloc Functions 


Returns: 


See Also: 


Example: 


Classification: 


Systems: 


The realloc functions return a pointer to the start of the re-allocated memory. The return value is 
NULL if there is insufficient memory available or if the value of the size argument is zero. The 
_ brealloc function returns_ NULLOFF if there is insufficient memory available or if the requested 
size is zero. 

calloc Functions, _ expand Functions, free Functions, halloc, hfree, malloc Functions, 

_ msize Functions,sbrk 

♦include <stdlib.h> 

♦include <malloc.h> 

void main() 

{ 

char *buffer; 
char *new_ buffer; 

buffer = (char *) malloc ( 80 ); 

new_ buffer = (char *) realloc( buffer, 100 ); 
if ( new_ buffer == NULL ) { 

/* not able to allocate larger buffer */ 

} else { 

buffer = new_ buffer; 

} 

} 

ISOC 

_brealloc is WATCOM 
_frealloc is WATCOM 
_nrealloc is WATCOM 

realloc - All, Linux, RDOS, Netware 
_brealloc - DOS/16, Windows, OS/2 l.x(all) 

_ frealloc - DOS/16, Windows, OS/2 l.x(all) 

_ nrealloc - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 l.x(MT), 
OS/2-32, Linux, RDOS 
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rectangle Functions 


Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


#include <graph.h> 

short _ FAR _ rectangle( short fill, 

short xl, short yl, 
short x2, short y2 ); 

short _ FAR _ rectangle_ w ( short fill, 

double xl, double yl, 
double x2, double y2 ); 

short _ FAR _ rectangle_ wxy ( short fill, 

struct _ wxycoord _ FAR *pl, 
struct _ wxycoord _ FAR *p2 ); 

The _ rectangle functions draw rectangles. The_ rectangle function uses the view coordinate 
system. The _ rectangle_ w and_ rectangle_ wxy functions use the window coordinate system. 

The rectangle is defined with opposite corners established by the points (xl,yl) and (x2,y2). 

The argument/;// determines whether the rectangle is filled in or has only its outline drawn. The 
argument can have one of two values: 

JGFILLINTERIOR fill the interior by writing pixels with the current plot action using the current 

color and the current fill mask 

JGBORDER leave the interior unchanged; draw the outline of the figure with the current 

plot action using the current color and line style 

The _ rectangle functions return a non-zero value when the rectangle was successfully drawn; 
otherwise, zero is returned. 

_ setcolor^. setfillmask,_ setlinestyle,_ setplotaction 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

_ setvideomode ( _VRES16C0L0R ); 

_ rectangle! _ GBORDER, 100, 100, 540, 380 ); 
getch (); 

_ setvideomode( _ DEFAULTMODE ); 

} 

produces the following: 
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rectangle Functions 


Classification: 

Systems: 


v 


J 


PC Graphics 


rectangle - DOS 
rectangle_ w - DOS 
rectangle_ wxy - DOS 
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registerfonts 


Synopsis: 

Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <graph.h> 

short _ FAR _ registerfonts ( char _ FAR *path ) ; 

The _ registerfonts function initializes the font graphics system. Fonts must be registered, and a 
font selected, before text can be displayed with the _ outgtext function. 

The argument path specifies the location of the font files. This argument is a file specification, and can 
contain drive and directory components and may contain wildcard characters. The _ registerfonts 
function opens each of the font files specified and reads the font information. Memory is allocated to 
store the characteristics of the font. These font characteristics are used by the _ setf ont function 
when selecting a font. 

The _ registerfonts function returns the number of fonts that were registered if the function is 
successful; otherwise, a negative number is returned. 

_ unregisterfonts,_ setfont^_ getfontinfo^ outgtext^ getgtextextent, 

_ setgtextvector,_ getgtextvector 

♦include <conio.h> 

♦include <stdio.h> 

♦include <graph.h> 

main () 

{ 

int i, n; 
char buf[ 10 ]; 

_ setvideomode( _ VRES16COLOR ); 
n = _ registerfonts( "*.fon" ); 
for( i = 0; i < n; ++i ) { 

sprintf ( buf, "n%d", i ); 

_ setfont( buf ); 

_ moveto( 100, 100 ); 

_ outgtext( "WATCOM Graphics" ); 
getch(); 

_ clearscreen( _ GCLEARSCREEN ) ; 

} 

_unregisterfonts() ; 

_ setvideomode( _DEFAULTMODE ) ; 

} 

PC Graphics 
DOS 
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remainder 


Synopsis: 

Description: 

Returns: 

Example: 


Classification: 

Systems: 


#include <math.h> 

double remainder( double x, double y ); 

The remainder function computes remainder of the division of vby y. 

The remainder of the division of x by y. 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", remainder( 7.0, 2.0 ) ); 

} 

produces the following: 

1.00000 
ISO C99 
Math 
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remapallpalette 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <graph.h> 

short _ FAR _ remapallpalette ( long _ FAR ‘colors ) ; 

The _ remapallpalette function sets (or remaps) all of the colors in the palette. The color values 
in the palette are replaced by the array of color values given by the argument colors. This function is 
supported in all video modes, but only works with EGA, MCGA and VGA adapters. 

The array colors must contain at least as many elements as there are supported colors. The newly 
mapped palette will cause the complete screen to change color wherever there is a pixel value of a 
changed color in the palette. 

The representation of colors depends upon the hardware being used. The number of colors in the 
palette can be determined by using the _ getvideoconf ig function. 

The _ remapallpalette function returns (-1) if the palette is remapped successfully and zero 
otherwise. 


remappalette,_ getvideoconfig 


♦include <conio.h> 

♦include <graph.h> 

long colors[ 16 ] = { 

_ BRIGHTWHITE, _ YELLOW, _ LIGHTMAGENTA, _ LIGHTRED, 

_ LIGHTCYAN, _ LIGHTGREEN, _ LIGHTBLUE, _ GRAY, _ WHITE, 

_ BROWN, _ MAGENTA, _ RED, _ CYAN, _ GREEN, _ BLUE, _ BLACK, 

} ; 


main () 

{ 

int x, y; 

_ setvideomode ( _VRES16C0L0R ); 
for( y = 0; y < 4; ++y ) { 

for( x = 0; x < 4; ++x ) { 

_ setcolor( x + 4 * y ); 

_ rectangle( _ GFILLINTERIOR, 
x * 160, y * 120, 

( x + 1 ) * 160, ( y + 1 ) * 120 ); 


} 

getch(); 

_ remapallpalette( colors ) ; 
getch(); 

_ setvideomode( _ DEFAULTMODE ); 


PC Graphics 
DOS 
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remappalette 


Synopsis: #include <graph.h> 

long _ FAR _ remappalette( short pixval, long color ) ; 

Description: The _ remappalette function sets (or remaps) the palette color pixval to be the color color. This 
function is supported in all video modes, but only works with EGA, MCGA and VGA adapters. 

The argument pixval is an index in the color palette of the current video mode. The argument color 
specifies the actual color displayed on the screen by pixels with pixel value pixval. Color values are 
selected by specifying the red, green and blue intensities that make up the color. Each intensity can be 
in the range from 0 to 63, resulting in 262144 possible different colors. A given color value can be 
conveniently specified as a value of type long. The color value is of the form OxOObbggrr, where 
bb is the blue intensity, gg is the green intensity and rr is the red intensity of the selected color. The 
file graph . h defines constants containing the color intensities of each of the 16 default colors. 

The _ remappalette function takes effect immediately. All pixels on the complete screen which 
have a pixel value equal to the value of pixval will now have the color indicated by the argument color. 

Returns: The _ remappalette function returns the previous color for the pixel value if the palette is remapped 

successfully; otherwise, (-1) is returned. 

See Also: _ remapallpalette,_ setvideomode 

Example: ((include <conio.h> 

((include <graph.h> 

long colors [ 16 ] = { 

_ BLACK, _ BLUE, _ GREEN, _ CYAN, 

_ RED, _ MAGENTA, _ BROWN, _ WHITE, 

_ GRAY, _ LIGHTBLUE, _ LIGHTGREEN, _ LIGHTCYAN, 

_ LIGHTRED, _ LIGHTMAGENTA, _ YELLOW, _ BRIGHTWHITE 

} ; 

main() 

{ 

int col; 

_ setvideomode ( _VRES16COLOR ); 
for ( col = 0; col < 16; ++col ) { 

_ remappalette( 0, colors! col ] ); 

getch (); 

} 

_ setvideomode( _ DEFAULTMODE ); 

} 

Classification: PC Graphics 
Systems: DOS 
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remove, _wremove 


Synopsis: 


Description: 


Returns: 


Example: 


Classification: 


Systems: 


♦include <stdio.h> 

int remove( const char *filename ); 

int _ wremove( const wchar_t ^filename ); 

The remove function deletes the file whose name is the string pointed to by filename. 

The _ wremove function is a wide-character version of remove that operates with wide-character 
strings. 

The remove function returns zero if the operation succeeds, non-zero if it fails. When an error has 
occurred, errno contains a value indicating the type of error that has been detected. 

♦include <stdio.h> 

void main() 

{ 

remove! "vm.tmp" ); 

} 

ISOC 

_wremove is WATCOM 

remove - All, Linux, RDOS, Netware 

_ wremove - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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rename, _wrename 


Synopsis: 


Description: 


Returns: 


Example: 


Classification: 


Systems: 


♦include <stdio.h> 

int rename( const char *old, const char *new ) ; 

int _ wrename ( const wchar_ t *old, const wchar_ t *new ) ; 

The rename function causes the file whose name is indicated by the string old to be renamed to the 
name given by the string new. 

The _ wrename function is a wide-character version ofrename that operates with wide-character 
strings. 

The rename function returns zero if the operation succeeds, a non-zero value if it fails. When an error 
has occurred, errno contains a value indicating the type of error that has been detected. 

♦include <stdio.h> 

void main() 

1 

rename! "old.dat", "new.dat" ); 

} 

ISOC 

_wrename is WATCOM 

rename - All, Linux, RDOS, Netware 

_ wrename - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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rewind 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <stdio.h> 
void rewind( FILE *fp ); 

The rewind function sets the file position indicator for the stream indicated to by fp to the beginning 
of the file. It is equivalent to 

f seek ( fp, OL, SEEK_ SET ) ; 

except that the error indicator for the stream is cleared. 

The rewind function returns no value. 

fopen, clearerr 

#include <stdio.h> 

static assemble_ pass( int passno ) 

{ 

printf ( "Pass %d\n", passno ); 

} 

void main() 

1 

FILE *fp; 

if( (fp = fopen( "program.asm", "r")) != NULL ) { 

assemble_ pass( 1 ); 
rewind( fp ); 
assemble_ pass( 2 ); 
fclose ( fp ); 

} 

} 

ISOC 

All, Linux, RDOS, Netware 
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rewinddir, _wrewinddir 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


♦include <sys/types.h> 

♦include <direct.h> 

void rewinddir( DIR *dirp ); 

void _ wrewinddir ( WDIR *dirp ); 

The rewinddir function resets the position of the directory stream to which dirp refers to the 
beginning of the directory. It also causes the directory stream to refer to the current state of the 
corresponding directory, as a call to opendir would have done. 

The _ wrewinddir function is identical torewinddir except that it rewinds a directory of 
wide-character filenames opened by _ wopendir. 

The rewinddir function does not return a value. 

closedir, _ dos_ find. . .ppendir, readdir 

The following example lists all the files in a directory, creates a new file, and then relists the directory. 

♦include <stdio.h> 

♦include <sys/types.h> 

♦include <sys/stat.h> 

♦include <direct.h> 

void main() 

{ 

DIR *dirp; 

struct dirent *direntp; 
int handle; 

dirp = opendir( "\\watcom\\h\\*); 
if( dirp != NULL ) { 

printf ( "Old directory listing\n" ) ; 
for (; ; ) { 

direntp = readdir( dirp ); 
if( direntp == NULL ) 
break; 

printf( "%s\n", direntp->d_ name ); 

} 

handle = creat ( "\\watcom\\h\\file.new", 

S_ IRUSR | S_ IWUSR | S_ IRGRP | S_ IWGRP ); 
close ( handle ); 

rewinddir( dirp ); 

printf ( "New directory listing\n" ); 
for (; ; ) { 

direntp = readdir( dirp ); 
if( direntp == NULL ) 
break; 

printf( "%s\n", direntp->d_ name ); 

} 

closedir( dirp ); 

} 

} 
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rewinddir, _wrewinddir 


Note the use of two adjacent backslash characters (\) within character-string constants to signify a single 
backslash. 

Classification: POSIX 1003.1 

_wrewinddir is WATCOM 

Systems: rewinddir - All, Linux, RDOS 

_ wrewinddir - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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rint 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double rint ( double x ); 

The rint function rounds the argument x to a nearby integer. The direction of the rounding is 
determined by the current value of fegetround. If supported, this function will throw a floating 
point error if an overflow occurs due to the current rounding mode. 

The rounded value of x. 

fegetround, fesetround, nearbyint, round, trunc 

♦include <stdio.h> 

♦include <math.h> 

void main() 

1 

fesetround (FE_ TONEAREST); 
printf ( "%f\n", rint ( 1.2 ) ); 

} 

produces the following: 

1.000000 
ISO C99 
Math 
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rmdir, _rmdir, _wrmdir 


Synopsis: #include <sys/types .h> 

♦include <direct.h> 

int rmdir( const char *path ); 

int _ rmdir( const char *path ); 

int _ wrmdir ( const wchar_ t *path ) ; 

Description: The rmdir function removes (deletes) the specified directory. The directory must not contain any files 
or directories. The path can be either relative to the current working directory or it can be an absolute 
path name. 

The _ rmdir function is identical tormdir. Use _ rmdir for ANSI naming conventions. 

The _ wrmdir function is a wide-character version of rmdir that operates with wide-character strings. 
Returns: The rmdir function returns zero if successful and -1 otherwise. 

Errors: When an error has occurred, errno contains a value indicating the type of error that has been detected. 

See Also: chdir, chmod, getcwd, mkdir, stat, umask 

Example: To remove the directory called \watcom on drive C : 

♦include <sys/types.h> 

♦include <direct.h> 

void main( void ) 

{ 

rmdir( "c:\\watcom" ); 

} 

Note the use of two adjacent backslash characters (\) within character-string constants to signify a single 
backslash. 

Classification: POSIX 1003.1 

_rmdir conforms to ANSI naming conventions 
_wrmdir is WATCOM 

Systems: rmdir - All, Linux, RDOS, Netware 

_ rmdir - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ wrmdir - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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rotl 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <stdlib.h> 

unsigned int _ rotl( unsigned int value, 

unsigned int shift ) ; 

The _ rotl function rotates the unsigned integer, determined by value, to the left by the number of bits 
specified in shift. If you port an application using _ rotl between a 16-bit and a 32-bit environment, 
you will get different results because of the difference in the size of integers. 

The rotated value is returned. 

_ lrotl,_ lrotr,_ rotr 

♦include <stdio.h> 

♦include <stdlib.h> 

unsigned int mask = OxOFOO; 

void main() 

{ 

mask = _ rotl ( mask, 4 ); 
printf ( "%04X\n", mask ); 

} 

produces the following: 

F000 

WATCOM 

All, Linux, RDOS, Netware 
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_rotr 

Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <stdlib.h> 

unsigned int _rotr( unsigned int value, 

unsigned int shift ); 

The _ rotr function rotates the unsigned integer, determined by value, to the right by the number of 
bits specified in shift. If you port an application using _ rotr between a 16-bit and a 32-bit 
environment, you will get different results because of the difference in the size of integers. 

The rotated value is returned. 

_ lrotl,_ lrotr,_ rotl 

♦include <stdio.h> 

♦include <stdlib.h> 

unsigned int mask = 0x1230; 

void main() 

1 

mask = _ rotr ( mask, 4 ); 
printf ( "%04X\n", mask ); 

} 

produces the following: 

0123 

WATCOM 

All, Linux, RDOS, Netware 
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round 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <math.h> 
double round( double x ) ; 

The round function rounds the argument x to the nearest integer. Values halfway between integers 
always rounded away from zero. 

The rounded value of x. 

nearbyint, rint, trunc 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", round( 1.5 ) ); 

} 

produces the following: 

2.000000 
ISO C99 
Math 
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sbrk 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


♦include <stdlib.h> 

int brk( void _ near *addr ); 

void _ near *sbrk( int increment ); 

Change data segment size, the "break" value. Under 16-bit DOS, Phar Lap’s 386IDOS-Extender and 
Linux, the data segment is grown contiguously. Under other systems, heap allocation is discontiguous. 
The "break" value is the address of the first byte of unallocated memory. When a program starts 
execution, the break value is placed following the code and constant data for the program. As memory 
is allocated, this pointer will advance when there is no freed block large enough to satisfy an allocation 
request. The sbrk function can be used to set a new "break" value for the program by adding the value 
of increment to the current break value. This increment may be positive or negative. 

Under other systems, heap allocation is discontiguous. The sbrk function can only be used to allocate 
additional discontiguous blocks of memory. The value of increment is used to determine the minimum 
size of the block to be allocated and may not be zero or negative. The actual size of the block that is 
allocated is rounded up to a multiple of 4K. 

The variable _ amblksiz defined in<stdlib . h> contains the default increment by which the 
"break" pointer for memory allocation will be advanced when there is no freed block large enough to 
satisfy a request to allocate a block of memory. This value may be changed by a program at any time. 

Under 16-bit DOS, a new process started with one of the spawn... or exec. . . functions is loaded 
following the break value. Consequently, decreasing the break value leaves more space available to the 
new process. Similarly, for a resident program (a program which remains in memory while another 
program executes), increasing the break value will leave more space available to be allocated by the 
resident program after other programs are loaded. 

If the call to sbrk succeeds, a pointer to the start of the new block of memory is returned. Under 
16-bit DOS, this corresponds to the old break value. If the call to sbrk fails,-1 is returned. When an 
error has occurred, errno contains a value indicating the type of error that has been detected. 

calloc Functions, _ expand Functions,free Functions, halloc, hfree, malloc Functions, 

_ msize Functions,realloc Functions 


♦include <stdio.h> 
♦include <stdlib.h> 


♦if defined(M_ 186) 

♦ define alloc ( x, y ) 

♦ else 

♦define alloc( x, y ) 
♦endif 


sbrk( x ); y = 
y = sbrk ( x ); 


sbrk ( 0 ) ; 


void main () 

{ 

void *brk; 
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Classification: 

Systems: 


sbrk 


#if defined(M_ 186) 

alloc ( 0x0000, brk ); 

/* calling printf will cause an allocation */ 

printf ( "Original break value %p\n", brk ); 

printf ( "Current amblksiz value %x\n", _ amblksiz ); 


alloc( 

0x0000, brk 

) ; 





printf( 

"New break 

value 

after 

printf 

\t\t%p\ 

n", brk 

#endif 







alloc( 

0x3100, brk 

) ; 





printf( 

"New break 
brk ) ; 

value 

after 

sbrk ( 

0x3100 ) 

\t%p\n 

alloc( 

0x0200, brk 

) ; 





printf( 

"New break 

value 

after 

sbrk ( 

0x0200 ) 

\t%p\n 


brk ) ; 

#if defined(M_ 186) 

alloc ( -0x0100, brk ); 

printf ( "New break value after sbrk( -0x0100 ) \t%p\n", 
brk ) ; 

#endif 


WATCOM 

DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 l.x(MT), OS/2-32, Linux, RDOS 
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scalbn 


Synopsis: 

Description: 

Returns: 

Example: 


Classification: 

Systems: 


#include <math.h> 

double scalbn( double x, int y ) ; 

The scalbn function computes x *(2** y ) via exponent manipulation. 

fmax( x - y, 0.0 ); 

The value of x times two raised to y. 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", scalbn ( 1.0, 3.0 ) ); 

} 

produces the following: 

8.000000 
ISO C99 
Math 
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scant, wscanf 


Synopsis: #include <stdio.h> 

int scanf( const char *format, ... ); 

♦include <wchar.h> 

int wscanf( const wchar_ t *format, ... ); 

Safer C: The Safer C Library extension provides the scanf_ s function which is a safer alternative toscanf 

This newer scanf_ s function is recommended to be used instead of the traditional "unsafe" scanf 
function. 

Description: The scanf function scans input from the file designated by stdin under control of the argument 
format. Th & format string is described below. Following the format string is the list of addresses of 
items to receive values. 

The wscanf function is identical to scanf except that it accepts a wide-character string argument for 
format. 

Returns: The scanf function returns EOF if an input failure occured before any conversion. Otherwise, the 

number of input arguments for which values were successfully scanned and stored is returned. 

See Also: cscanf, f scanf, sscanf, vcscanf, vf scanf, vscanf, vsscanf 

Example: To scan a date in the form "Saturday April 18 1987": 

♦include <stdio.h> 

void main( void ) 

{ 

int day, year; 

char weekday[10], month[10]; 

scanf( "%s %s %d %d", weekday, month, &day, &year ); 

} 

Format Control String: The format control string consists of zero or mor e format directives that specify acceptable 
input file data. Subsequent arguments are pointers to various types of objects that are assigned values 
as the format string is processed. 

A format directive can be a sequence of one or more white-space characters, an ordinary character, or a 
conversion specifier. An ordinary character in the format string is any character, other than a 
white-space character or the percent character (%), that is not part of a conversion specifier. A 
conversion specifier is a sequence of characters in the format string that begins with a percent character 
(%) and is followed, in sequence, by the following: 

• an optional assignment suppression indicator: the asterisk character (*); 

• an optional decimal integer that specifies the maximum field width to be scanned for the 
conversion; 

• an optional pointer-type specification: one of "N" or "W"; 

• an optional type length specification: one of "hh", "h", "1", "11", "j", "z", "t", "L" or "164"; 

• a character that specifies the type of conversion to be performed: one of the characters 
"cCdeEfFgGinopsSuxX[". 
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scant, wscanf 


As each format directive in the format string is processed, the directive may successfully complete, fail 
because of a lack of input data, or fail because of a matching error as defined by the particular directive. 
If end-of-file is encountered on the input data before any characters that match the current directive 
have been processed (other than leading white-space where permitted), the directive fails for lack of 
data. If end-of-file occurs after a matching character has been processed, the directive is completed 
(unless a matching error occurs), and the function returns without processing the next directive. If a 
directive fails because of an input character mismatch, the character is left unread in the input stream. 
Trailing white-space characters, including new-line characters, are not read unless matched by a 
directive. When a format directive fails, or the end of the format string is encountered, the scanning is 
completed and the function returns. 

When one or more white-space characters (space " ", horizontal tab "\t", vertical tab "\v", form feed "\f", 
carriage return "\r", new line or linefeed "\n") occur in the format string, input data up to the first 
non-white-space character is read, or until no more data remains. If no white-space characters are found 
in the input data, the scanning is complete and the function returns. 

An ordinary character in the format string is expected to match the same character in the input stream. 

A conversion specifier in the format string is processed as follows: 

• for conversion types other than "[", "c", "C" and "n", leading white-space characters are skipped 

• for conversion types other than "n", all input characters, up to any specified maximum field 
length, that can be matched by the conversion type are read and converted to the appropriate type 
of value; the character immediately following the last character to be matched is left unread; if no 
characters are matched, the format directive fails 

• unless the assignment suppression indicator ("*") was specified, the result of the conversion is 
assigned to the object pointed to by the next unused argument (if assignment suppression was 
specified, no argument is skipped); the arguments must correspond in number, type and order to 
the conversion specifiers in the format string 

A pointer-type specification is used to indicate the type of pointer used to locate the next argument to be 
scanned: 

IT pointer is a far pointer 
N pointer is a near pointer 

The pointer-type specification is only effective on platforms that use a segmented memory model, 
although it is always recognized. 

The pointer type defaults to that used for data in the memory model for which the program has been 
compiled. 

A type length specifier affects the conversion as follows: 

• "hh" causes a "d", "i", "o", "u" or "x" (integer) conversion to assign the converted value to an 
object of type signed char or unsigned char. 

• "hh" causes an "n" (read length assignment) operation to assign the number of characters that 
have been read to an object of type signed char. 
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scant, wscanf 


• "h" causes a "d", "i", "o", "u" or "x" (integer) conversion to assign the converted value to an 
object of type short int or unsigned short int. 

• "h" causes an "f" conversion to assign a fixed-point number to an object of type long consisting 
of a 16-bit signed integer part and a 16-bit unsigned fractional part. The integer part is in the high 
16 bits and the fractional part is in the low 16 bits. 

struct fixpt { 

unsigned short fraction; /* Intel architecture! */ 
signed short integral; 

1 ; 


struct fixpt fool = 

{ 0x8000, 1234 }; /* represents 1234.5 */ 
struct fixpt foo2 = 

{ 0x8000, -1 }; /* represents -0.5 (-1+.5) */ 

• "h" causes an "n" (read length assignment) operation to assign the number of characters that have 
been read to an object of type short int. *. 

• "h" causes an "s" operation to convert the input string to an ASCII character string. For scanf 
this specifier is redundant. For wscanf, this specifier is required if the wide character input string 
is to be converted to an ASCII character string; otherwise it will not be converted. *. 

• "1" causes a "d", "i", "o", "u" or "x" (integer) conversion to assign the converted value to an 
object of type long int or unsigned long int. 

• "1" causes an "n" (read length assignment) operation to assign the number of characters that have 
been read to an object of type long int. 

• "1" causes an "e", "f" or "g" (floating-point) conversion to assign the converted value to an object 
of type double. 

• "1" or "w" cause an "s" operation to convert the input string to a wide character string. For 
scanf this specifier is required if the input ASCII string is to be converted to a wide character 
string; otherwise it will not be converted. *. 

• "11" causes a "d", "i", "o", "u" or "x" (integer) conversion to assign the converted value to an 
object of type long long or unsigned long long (e.g., %lld). 

• "11" causes an "n" (read length assignment) operation to assign the number of characters that have 
been read to an object of type long long int. 

• "j" causes a "d", "i", "o", "u" or "x" (integer) conversion to assign the converted value to an 
object of type intmax_ t oruintmax_ t. 

• "j" causes an "n" (read length assignment) operation to assign the number of characters that have 
been read to an object of type intmax_ t. 

• "z" causes a "d", "i", "o", "u" or "x" (integer) conversion to assign the converted value to an 
object of type size_ t or the corresponding signed integer type. 

• "z" causes an "n" (read length assignment) operation to assign the number of characters that have 
been read to an object of signed integer type corresponding to size_ t. 
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• "t" causes a "d", "i", "o", "u" or "x" (integer) conversion to assign the converted value to an 
object of type ptrdif f_ t or the corresponding unsigned integer type. 

• "t" causes an "n" (read length assignment) operation to assign the number of characters that have 
been read to an object of type pt rdi f f_ t. 

• "164" causes a "d", "i", "o", "u" or "x" (integer) conversion to assign the converted value to an 

object of type_int64 onnsigned_int64 (e.g., %I64d). 

• "L" causes an "e", "f" or "g" (floating-point) conversion to assign the converted value to an 
object of type long double. 

The valid conversion type specifiers are: 

c Any sequence of characters in the input stream of the length specified by the field width, or a 

single character if no field width is specified, is matched. The argument is assumed to point to 
the first element of a character array of sufficient size to contain the sequence, without a 
terminating null character (’MT). For a single character assignment, a pointer to a single object 
of type char is sufficient. 

C A sequence of multibyte characters in the input stream is matched. Each multibyte character is 

converted to a wide character of type wchar_ t. The number of wide characters matched is 
specified by the field width (1 if no field width is specified). The argument is assumed to point 
to the first element of an array of wchar_ t of sufficient size to contain the sequence. No 
terminating null wide character (L'\0’) is added. For a single wide character assignment, a 
pointer to a single object of type wchar_ t is sufficient. 

d A decimal integer, consisting of an optional sign, followed by one or more decimal digits, is 

matched. The argument is assumed to point to an object of type int. 

e,fg A floating-point number, consisting of an optional sign ("+" or "-"), followed by one or more 
decimal digits, optionally containing a decimal-point character, followed by an optional 
exponent of the form "e" or "E", an optional sign and one or more decimal digits, is matched. 
The exponent, if present, specifies the power of ten by which the decimal fraction is multiplied. 
The argument is assumed to point to an object of type float. 

i An optional sign, followed by an octal, decimal or hexadecimal constant is matched. An octal 

constant consists of "0" and zero or more octal digits. A decimal constant consists of a 
non-zero decimal digit and zero or more decimal digits. A hexadecimal constant consists of 
the characters "Ox" or "OX" followed by one or more (upper- or lowercase) hexadecimal digits. 
The argument is assumed to point to an object of type int. 

n No input data is processed. Instead, the number of characters that have already been read is 

assigned to the object of type unsigned int that is pointed to by the argument. The 
number of items that have been scanned and assigned (the return value) is not affected by the 
"n" conversion type specifier. 

o An octal integer, consisting of an optional sign, followed by one or more (zero or non-zero) 

octal digits, is matched. The argument is assumed to point to an object of type int. 

p A hexadecimal integer, as described for "x" conversions below, is matched. The converted 

value is further converted to a value of type void* and then assigned to the object pointed to 
by the argument. 
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s A sequence of non-white-space characters is matched. The argument is assumed to point to the 

first element of a character array of sufficient size to contain the sequence and a terminating 
null character, which is added by the conversion operation. 

S A sequence of multibyte characters is matched. None of the multibyte characters in the 

sequence may be single byte white-space characters. Each multibyte character is converted to 
a wide character. The argument is assumed to point to the first element of an array of 
wchar_ t of sufficient size to contain the sequence and a terminating null wide character, 
which is added by the conversion operation. 

u An unsigned decimal integer, consisting of one or more decimal digits, is matched. The 

argument is assumed to point to an object of type unsigned int. 

x A hexadecimal integer, consisting of an optional sign, followed by an optional prefix "Ox" or 

"OX", followed by one or more (upper- or lowercase) hexadecimal digits, is matched. The 
argument is assumed to point to an object of type int. 

[clc2...] The longest, non-empty sequence of characters, consisting of any of the characters cl, c2, 

. . . called the scanset, in any order, is matched, cl cannot be the caret character (’ A ’). If cl 
is "]", that character is considered to be part of the scanset and a second "]" is required to end 
the format directive. The argument is assumed to point to the first element of a character array 
of sufficient size to contain the sequence and a terminating null character, which is added by 
the conversion operation. 

[ f 'clc2...] The longest, non-empty sequence of characters, consisting of any characters other than the 

characters between the " A " and "]", is matched. As with the preceding conversion, if cl is "]", 
it is considered to be part of the scanset and a second "]" ends the format directive. The 
argument is assumed to point to the first element of a character array of sufficient size to 
contain the sequence and a terminating null character, which is added by the conversion 
operation. 

For example, the specification % [ A \ n ] will match an entire input line up to but not including 
the newline character. 

A conversion type specifier ofis treated as a single ordinary character that matches a single "%" 
character in the input data. A conversion type specifier other than those listed above causes scanning to 
terminate and the function to return. 

Conversion type specifiers "E", "F", "G", "X" have meaning identical to their lowercase equivalents. 

The line 

scanf ( "%s%*f%3hx%d", name, Shexnum, Sdecnum ) 
with input 

some_ string 34.555e-3 abcl234 

will copy "some_ string" into the arrayname, skip 34.555e-3, assign Oxabc to hexnum and 
12 34 to decnum. The return value will be 3. 

The program 
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♦include <stdio.h> 

void main( void ) 

{ 

char stringl[80], string2[80]; 

scanf( "%[abcdefghijklmnopqrstuvwxyz" 

"ABCDEFGHIJKLMNOPQRSTUVWZ ]%*2s%[ A \n]", 
stringl, string2 ); 

printf( "%s\n%s\n", stringl, string2 ); 

} 

with input 

They may look alike, but they don't perform alike, 
will assign 

"They may look alike" 

to stringl, skip the comma (the " % * 2 s " will match only the comma; the following blank 
terminates that field), and assign 

" but they don't perform alike." 

to string2 . 

Classification: ISO C90 

wscanf is ISO C95 

The N, W pointer size modifiers and the 164 modifier are extensions to ISO C. 

Systems: scanf - All, Linux, RDOS, Netware 

wscanf - All, Linux 
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Synopsis: 

Constraints: 


Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

int scanf_ s ( const char * restrict format, ... ); 

♦include <wchar.h> 

int wscanf_ s( const wchar_ t * restrict format, ... ); 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and scanf_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

The format argument shall not be a null pointer. Any argument indirected through in order to store 
converted input shall not be a null pointer. 

If there is a runtime-constraint violation, the scanf_ s function does not attempt to perform further 
input, and it is unspecified to what extent scanf_ s performed input before discovering the 
runtime-constraint violation. 

The scanf_ s function is equivalent tof scanf_ s with the argument si din interposed before the 
arguments to scanf_s 

The wscanf_ s function is identical toscanf_ s except that it accepts a wide-character string 
argument for format. 

The scanf_ s function returnsEOF if an input failure occurred before any conversion or if there was a 
runtime-constraint violation. Otherwise, the scanf_ s function returns the number of input items 
successfully assigned, which can be fewer than provided for, or even zero. 

When a file input error occurs, the errno global variable may be set. 

cscanf, fscanf, scanf, sscanf, vcscanf, vfscanf, vscanf, vsscanf 

To scan a date in the form "Friday August 13 2004": 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

void main( void ) 

{ 

int day, year; 

char weekday[10], month[10]; 

scanf_ s( "%s %s %d %d", 

weekday, sizeof ( weekday ), 
month, sizeof ( month ), 

&day, Syear ); 

} 

TR 24731 

scanf_ s - All, Linux, RDOS, Netware 
wscanf_ s - All, Linux 
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sched_getparam 


Synopsis: 


Description: 

Returns: 

Errors: 


See Also: 

Classification: 

Systems: 


♦include <sched.h> 

int sched_ getparam (pid_ t pid, struct sched_ parara *sp) ; 

struct sched_ param { 

int sched_ priority; 

} ; 


The sched_ getparam function retrieves scheduling parameters for the process specified by pid and 
returns the parameters in the memory pointed to by the sp argument. 

If pid is zero, the scheduling parameters for the calling process will be returned in the sp argument. 

If successful, the function will return zero. If the call fails, the return value is -1 and errno is 
appropriately set. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

ESRCH The process ID pid is invalid or could not be found 

EPERM The calling process does not have permission to access the parameters 

EFAULT The memory at sp could not be written successfully 

sched_ setparam 

POSIX 

Linux 
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sched_get_priority_max 


Synopsis: 

Description: 

Returns: 

Errors: 

See Also: 

Classification: 

Systems: 


#include <sched.h> 

int sched_ get_ priority_ max (pid_ t pid, int policy); 

The sched_ get_ priority_ max function returns the maximum priority for the scheduling policy 
specified by the policy argument. 

If successful, the function will return the maximum priority allowed for the given scheduling policy. If 
the call fails, the return value is -1 and errno is appropriately set. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINVAL The value of policy does not represent a valid scheduling policy 

sched_ get_ priority_ min 

POSIX 

Linux 


Library Functions and Macros 903 




sched_get_priority_min 


Synopsis: 

Description: 

Returns: 

Errors: 

See Also: 

Classification: 

Systems: 


#include <sched.h> 

int sched_ get_ priority_ min (pid_ t pid, int policy); 

The sched_ get_ priority_ min function returns the minimum priority for the scheduling policy 
specified by the policy argument. 

If successful, the function will return the minimum priority allowed for the given scheduling policy. If 
the call fails, the return value is -1 and errno is appropriately set. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINVAL The value of policy does not represent a valid scheduling policy 

sched_ get_ priority_ max 

POSIX 

Linux 
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sched_getscheduler 


Synopsis: 

Description: 

Returns: 

Errors: 


See Also: 

Classification: 

Systems: 


♦include <sched.h> 

int sched_ getscheduler (pid_ t pid) ; 

The sched_ getscheduler function retrieves scheduling policy for the process specified by the pid 
argument. 

If pid is zero, the policy for the calling process will be returned. 

If successful, the function will return the kernel’s scheduling policy for the specified process. If the call 
fails, the return value is -1 and errno is appropriately set. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

ESRCH The process ID pid could not be found 

EINVAL The process ID pid is invalid 

sched_ setscheduler 

POSIX 

Linux 
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sched^rrgetjnterval 


Synopsis: 


Description: 

Returns: 

Errors: 


Classification: 

Systems: 


♦include <sched.h> 

♦include <time.h> 

int sched_ rr_ get_ interval (pid_ t pid, struct timespec *ts) ; 

struct timespec { 
time_ t tv_ sec; 
long tv_ nsec; 

} ; 


The sched_ rr_ get_ interval function retrieves the execution time limit for the process specified 
by the pid argument. The memory pointed to by ts will be populated with this time limit if the call is 
successful. 

If pid is zero, the execution time limit for the calling process will be returned in the ts argument. 

If successful, the function will return zero. If the call fails, the return value is -1 and errno is 
appropriately set. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

ESRCH The process ID pid is invalid or could not be found 

EPERM The calling process does not have permission to access the parameters 

EFAULT The memory at sp could not be written successfully 

POSIX 

Linux 
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sched^setparam 


Synopsis: 


Description: 

Returns: 

Errors: 


See Also: 

Classification: 

Systems: 


♦include <sched.h> 

int sched_ setparam (pid_ t pid, const struct sched_ parara *sp) ; 

struct sched_ param { 

int sched_ priority; 

} ; 


The sched_ setparam function sets the scheduling parameters for the process specified by the pid 
argument. 

If pid is zero, the scheduling parameters for the calling process will be set. 

If successful, the function will return zero. If the call fails, the return value is -1 and errno is 
appropriately set. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

ESRCH The process ID pid is invalid or could not be found 

EINVAL The value of pid or sp is invalid 

EFAULT The memory at sp could not be read 

sched_ getparam 

POSIX 

Linux 


Library Functions and Macros 907 




sched setscheduler 


Synopsis: 


Description: 

Returns: 

Errors: 


See Also: 

Classification: 

Systems: 


♦include <sched.h> 

int sched_ setscheduler (pid_ t pid, int policy, 
const struct sched_ param *sp) ; 

struct sched_ param { 

int sched_ priority; 

} ; 


The sched_ setscheduler function sets the scheduling policy and parameters for the process 
specified by the pid argument. 

If pid is zero, the policy and parameters for the calling process will be set. 

If successful, the function will return the kernel’s former scheduling policy for the specified process. If 
the call fails, the return value is -1 and errno is appropriately set. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

ESRCH The process ID pid could not be found 

EINVAL The process ID pid , policy value policy , or the pointer sp is invalid 
EFAULT The memory at sp could not be read 

sched_ getscheduler,sched_ setparam,sched_ getparam 

POSIX 

Linux 
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sched^yield 


Synopsis: 

Description: 

Returns: 

Classification: 

Systems: 


♦include <sched.h> 
int sched_ yield ( ); 

The sched_ yield function causes the calling thread to yield the processor to other threads until the 
kernel assigns it to be the current thread once again. 

If successful, the function will return zero. If the call fails, the return value is -1. 

POSIX 

Linux 
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scrolltextwindow 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <graph.h> 

void _ FAR _ scrolltextwindow( short rows ); 

The _ scrolltextwindow function scrolls the lines in the current text window. A text window is 
defined with the _ settextwindow function. By default, the text window is the entire screen. 

The argument rows specifies the number of rows to scroll. A positive value means to scroll the text 
window up or towards the top of the screen. A negative value means to scroll the text window down or 
towards the bottom of the screen. Specifying a number of rows greater than the height of the text 
window is equivalent to clearing the text window with the _ clearscreen function. 

Two constants are defined that can be used with the _ scrolltextwindow function: 

JGSCROLLUP the contents of the text window are scrolled up (towards the top of the 

screen) by one row 

JGSCROLLDOWN the contents of the text window are scrolled down (towards the bottom of the 

screen) by one row 

The _ scrolltextwindow function does not return a value. 

_ settextwindow,_ clearscreen^. outtext,_ outmem^ settextposition 

♦include <conio.h> 

♦include <graph.h> 

♦include <stdio.h> 

main () 

{ 

int i; 

char buff 80 ]; 

_ setvideomode( _ TEXTC80 ); 

_ settextwindow( 5, 20, 20, 40 ); 
for ( i = 1; i <= 10; ++i ) { 

sprintf( buf, "Line %d\n", i ); 

_ outtext( buf ) ; 

} 

getch(); 

_ scrolltextwindow( _ GSCROLLDOWN ); 
getch(); 

_ scrolltextwindow( _ GSCROLLUP ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ) ; 

} 

PC Graphics 
DOS 


910 Library Functions and Macros 




Synopsis: 


Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


searchenv, _wsearchenv 


#include <stdlib.h> 

void _ searchenv( const char *name, 

const char *env_ var, 

char ^pathname ); 

void _ wsearchenv( const wchar_ t *name, 

const wchar_ t *env_ var, 

wchar_ t *pathname ); 

The _ searchenv function searches for the file specified by name in the list of directories assigned to 
the environment variable specified by env_var. Common values for env_var are PATH, LIB and 
INCLUDE. 

The current directory is searched first to find the specified file. If the file is not found in the current 
directory, each of the directories specified by the environment variable is searched. 

The full pathname is placed in the buffer pointed to by the argument pathname. If the specified file 
cannot be found, then pathname will contain an empty string. 

The _ wsearchenv function is a wide-character version of_ searchenv that operates with 
wide-character strings. 

The _ searchenv function returns no value. 

getenv, setenv, _ splitpath.putenv 

♦include <stdio.h> 

♦include <stdlib.h> 

void display_ help( FILE *fp ) 

{ 

printf ( "display_ help T.B.I.Xn" ); 

} 

void main() 

{ 

FILE *help_ file; 

char full_ path [ _ MAX_ PATH ] ; 

_ searchenv( "watcomc.hip", "PATH", full_ path ); 
if( full_ path[0] == '\0' ) { 

printf ( "Unable to find help file\n" ); 

} else { 

help_ file = fopen ( full_path, "r" ); 
display_ help( help_ file ); 
fclose ( help_ file ) ; 

} 

} 

WATCOM 

_ searchenv - All, Linux, RDOS 

_ wsearchenv - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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segread 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <i86.h> 

void segread( struct SREGS *seg_ regs ); 

The segread function places the values of the segment registers into the structure located by 
seg_regs. 

No value is returned. 

FP_ OFF,FP_ SEG,MK_ FP 

♦include <stdio.h> 

♦include <i86.h> 

void main() 

{ 

struct SREGS sregs; 
segread( Ssregs ); 

printf ( "Current value of CS is %04X\n", sregs.cs ); 

} 

WATCOM 

All, RDOS, Netware 
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selectpalette 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


♦include <graph.h> 

short _ FAR _ selectpalette( short palnum ); 

The _ selectpalette function selects the palette indicated by the argument palnum from the color 
palettes available. This function is only supported by the video modes _ MRES4C0L0R and 
_ MRESNOCOLOR. 


Mode _ MRES4COLOR supports four palettes of four colors. In each palette, color 0, the background 
color, can be any of the 16 possible colors. The color values associated with the other three pixel 
values, (1,2 and 3), are determined by the selected palette. 


The following table outlines the available color palettes: 


Palette 
Number 1 


Pixel Values 
2 


3 


0 

1 

2 

3 


green 

cyan 

light green 
light cyan 


red 

magenta 
light red 
light magenta 


brown 

white 

yellow 

bright white 


The _ selectpalette function returns the number of the previously selected palette. 


setvideomode,_ getvideoconfig 


♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

int x, y, pal; 

_ setvideomode( _ MRES4COLOR ); 
for( y = 0; y < 2; ++y ) { 

for( x = 0; x < 2; ++x ) { 

_ setcolor( x + 2 * y ) ; 

_ rectangle( _ GFILLINTERIOR, 
x * 160, y * 100, 

( x + 1 ) * 160, ( y + 1 ) * 100 ); 


} 

for( pal = 0; pal < 4; ++pal ) { 

_ selectpalette( pal ); 
getch () ; 

} 

_ setvideomode( _ DEFAULTMODE ); 


PC Graphics 
DOS 
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sem_destroy 


Synopsis: 

Description: 

Returns: 

Errors: 

See Also: 

Classification: 

Systems: 


♦include <semaphore.h> 

int sem_ destroy (sem_ t ^semaphore) ; 

The sem_ destroy function destroys a semaphore pointed to by the semaphore argument. 

If successful, the function will return zero. If the call fails, the function returns -1 and errno is set 
appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EBUSY The semaphore is currently unavailable. 

sem_ init,sem_ getvalue,sem_ post,sem_ trywait,sem_ wait 

POSIX 

Linux 
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sem_getvalue 


Synopsis: 

Description: 

Returns: 

Errors: 

See Also: 

Classification: 

Systems: 


♦include <semaphore.h> 

int sem_ getvalue (sem_ t ^semaphore, int *dest); 

The sem_ getvalue function returns the current value of semaphore in the memory pointed to by the 
dest pointer. 

If successful, the function will return zero. If the call fails, the function returns -1 and errno is set 
appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 

Constant Meaning 

EINVAL The pointer value is NULL 

sem_ destroy,sem_ init,sem_ post,sem_ trywait,sem_ wait 

POSIX 

Linux 
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sem init 


Synopsis: 

Description: 

Returns: 

Errors: 


See Also: 

Classification: 

Systems: 


♦include <semaphore.h> 

int sem_ init (sem_ t *semaphore, int flags, int value); 

The sem_ init function initializes a semaphore pointed to by semaphore using value as its initial 
value. On Open Watcom, the flags argument must be zero as this runtime does not currently support 
sharing semaphores across processes. 

If successful, the function will return zero. If the call fails, the function returns -1 and errno is set 
appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINVAL The value of the value argument exceeds SEM_ VALUE_ MAX 

ENOSYS The value of flags was non-zero or semaphores are not supported on this CPU. 

sem_ destroy,sem_ getvalue,sem_ post,sem_ trywait,sem_ wait 

POSIX 

Linux 
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sem_post 


Synopsis: 

Description: 

Returns: 

Errors: 

See Also: 

Classification: 

Systems: 


♦include <semaphore.h> 

int sem_ post (sem_ t *semaphore) ; 

The sem_ post function unlocks a semaphore pointed to by the semaphore argument. Unlocking 
releases the semaphore and signals any waiting threads appropriately. 

If successful, the function will return zero. If the call fails, the function returns -1 and errno is set 
appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINVAL The pointer semaphore is NULL 

sem_ destroy,sem_ init,sem_ trywait,sem_ wait 

POSIX 

Linux 
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semjrywait 


Synopsis: 

Description: 

Returns: 

Errors: 


See Also: 

Classification: 

Systems: 


♦include <semaphore.h> 

int sem_ trywait (sem_ t ^semaphore); 

The sem_ trywait function attempts to lock a semaphore pointed to by the semaphore argument, and 
returns immediately regardless of success. 

If the semaphore was successfully locked, the function will return zero. If the call fails or the 
semaphore could not be locked, the function returns -1 and errno is set appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 

Constant Meaning 

EINVAL The pointer semaphore is NULL 
EAGAIN The semaphore is currently locked. 

sem_ destroy,sem_ getvalue,sem_ init,sem_ post,sem_ wait 

POSIX 

Linux 
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sem wait 


Synopsis: 

Description: 

Returns: 

Errors: 

See Also: 

Classification: 

Systems: 


♦include <semaphore.h> 

int sem_ wait (sem_ t *semaphore) ; 

The sem_ wait function attempts to lock a semaphore pointed to by the semaphore argument, and 
blocks until the semaphore is successfully locked. 

If the semaphore was successfully locked, the function will return zero. If the call fails or the 
semaphore could not be locked, the function returns -1 and errno is set appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 

Constant Meaning 

EINVAL The pointer semaphore is NULL 

sem_ destroy,sem_ getvalue,sem_ init,sem_ post,sem_ trywait 

POSIX 

Linux 


Library Functions and Macros 919 




set_constraint_handler_s 


Synopsis: #def ine _STDC_ WANT_ LIB_ EXT1_1 

♦include <stdlib.h> 

constraint_ handler_ t set_ constraint_ handler_ s ( 
constraint_ handler_ t handler ) ; 

Description: The set_ constraint handler_ s function sets the runtime-constraint handler to be handler. The 
runtime-constraint handler is the function called when a library function detect a runtime-constraint 
violation. Only the most recent handler registered with set_ constraint handler_ s is called 
when a runtime-constraint violation occurs. 

When the handler is called, it is passed the following arguments: 

1. A pointer to a character string describing the runtime-constraint violation. 

2. A null pointer or a pointer to an implementation defined object. This implementation passes 
a null pointer. 

3. If the function calling the handler has a return type declared as errno_ t, the return value of 
the function is passed. Otherwise, a positive value of type errno_ t is passed. 

If no calls to the set_ constraint handler_ s function have been made, a default constraint 
handler is used. This handler will display an error message and abort the program. 

If the handler argument to set_ constraint handler_ s is a null pointer, the default handler 
becomes the current constraint handler. 

Returns: The set_ constraint handler_ s function returns a pointer to the previously registered handler. 

See Also: abort_ handler_ signore_ handler_ s 

Example: #define _STDC_ WANT_ LIB_ EXT1_1 

♦include <stdlib.h> 

♦include <stdio.h> 

void my_ handler ( const char *msg, void *ptr, errno_ t error ) 

{ 

fprintf( stderr, "rt-constraint violation caught ); 
fprintf( stderr, msg ) ; 
fprintf( stderr, "\n" ); 

} 

void main( void ) 

{ 

constraint handler_ t old_ handler; 

old_ handler = set_ constraint handler_ s ( my_ handler ) ; 
if ( getenv_ s ( NULL, NULL, 0, NULL ) ) { 

printf ( "getenv_ s failed\n" ); 

} 

set_ constraint handler_ s ( old_ handler ) ; 

} 

produces the following: 
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set_constraint_handler_s 


rt-constraint violation caught: getenv_s, name == NULL. 
getenv_ s failed 

Classification: TR 24731 

Systems: All, Linux, RDOS, Netware 
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setactivepage 


Synopsis: #include <graph.h> 

short _ FAR _ setactivepage( short pagenum ); 

Description: The _ setactivepage function selects the page (in memory) to which graphics output is written. 
The page to be selected is given by the pagenum argument. 

Only some combinations of video modes and hardware allow multiple pages of graphics to exist. When 
multiple pages are supported, the active page may differ from the visual page. The graphics 
information in the visual page determines what is displayed upon the screen. Animation may be 
accomplished by alternating the visual page. A graphics page can be constructed without affecting the 
screen by setting the active page to be different than the visual page. 

The number of available video pages can be determined by using the _ getvideoconf ig function. 
The default video page is 0. 

Returns: The _ setactivepage function returns the number of the previous page when the active page is set 

successfully; otherwise, a negative number is returned. 

See Also: _ getactivepage,_ setvisualpage,_ getvisualpage,_ getvideoconf ig 

Example: ((include <conio.h> 

♦include <graph.h> 

main () 

{ 

int old_ apage; 
int old_ vpage; 

_ setvideomode( _ HRES16COLOR ); 
old_ apage = _ getactivepage () ; 
old_ vpage = _ getvisualpage () ; 

/* draw an ellipse on page 0 */ 

_ setactivepage( 0 ); 

_ setvisualpage( 0 ); 

_ellipse( _ GFILLINTERIOR, 100, 50, 540, 150 ); 

/* draw a rectangle on page 1 */ 

_ setactivepage( 1 ); 

_ rectangle! _ GFILLINTERIOR, 100, 50, 540, 150 ); 
getch(); 

/* display page 1 */ 

_ setvisualpage( 1 ); 
getch() ; 

_ setactivepage ( old_ apage ); 

_ setvisualpage ( old_ vpage ) ; 

_ setvideomode( _ DEFAULTMODE ); 

} 

Classification: PC Graphics 
Systems: DOS 
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setbkcolor 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


♦include <graph.h> 

long _ FAR _ setbkcolor( long color ) ; 

The _ setbkcolor function sets the current background color to be that of the color argument. In 
text modes, the background color controls the area behind each individual character. In graphics 
modes, the background refers to the entire screen. The default background color is 0. 

When the current video mode is a graphics mode, any pixels with a zero pixel value will change to the 
color of the color argument. When the current video mode is a text mode, nothing will immediately 
change; only subsequent output is affected. 

The _ setbkcolor function returns the previous background color. 


_ getbkcolor 

♦include <conio.h> 

♦include <graph.h> 

long colors! 16 ] = { 

_ BLACK, _ BLUE, _ GREEN, _ CYAN, 

_ RED, _ MAGENTA, _ BROWN, _ WHITE, 

_ GRAY, _ LIGHTBLUE, _ LIGHTGREEN, _ LIGHTCYAN, 

_ LIGHTRED, _ LIGHTMAGENTA, _ YELLOW, _ BRIGHTWHITE 

} ; 

main () 

{ 

long old_ bk; 
int bk; 

_ setvideomode ( _VRES16COLOR ); 

old_ bk = _ getbkcolor () ; 

for( bk = 0; bk < 16; ++bk ) { 

_ setbkcolor( colors[ bk ] ); 

getch (); 

} 

_ setbkcolor( old_ bk ) ; 

_ setvideomode( _DEFAULTMODE ) ; 

} 

PC Graphics 
DOS 
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setbuf 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <stdio.h> 

void setbuf( FILE *fp, char *buffer ); 

The setbuf function can be used to associate a buffer with the file designated by //?. If this function is 
used, it must be called after the file has been opened and before it has been read or written. If the 
argument buffer is NULL, then all input/output for the file //? will be completely unbuffered. If the 
argument buffer is not NULL, then it must point to an array that is at least BUFSIZ characters in 
length, and all input/output will be fully buffered. 

The setbuf function returns no value. 

fopen, setvbuf 

♦include <stdio.h> 

♦include <stdlib.h> 

void main() 

{ 

char *buffer; 

FILE *fp; 

fp = fopen( "file", "r" ); 

buffer = (char *) malloc( BUFSIZ ); 

setbuf( fp, buffer ) ; 

/* . */ 

/* . */ 

/* . */ 
fclose ( fp ); 

} 

ISOC 

DOS/16, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS, Netware 
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setcharsize Functions 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


#include <graph.h> 

void _ FAR _ setcharsize( short height, short width ); 

void _ FAR _ setcharsize_ w ( double height, double width ); 

The _ setcharsize functions set the character height and width to the values specified by the 
arguments height and width. For the _ setcharsize function, the arguments height and width 
represent a number of pixels. For the _ setcharsize_ w function, the arguments height and width 
represent lengths along the y-axis and x-axis in the window coordinate system. 

These sizes are used when displaying text with the _ grtext function. The default character sizes are 
dependent on the graphics mode selected, and can be determined by the _ gettextsettings 
function. 

The _ setcharsize functions do not return a value. 

_ grtext^ gettextsettings 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

struct textsettings ts; 

_ setvideomode( _ VRES16COLOR ); 

_ gettextsettings( &ts ) ; 

_ grtext( 100, 100, "WATCOM" ); 

_ setcharsize( 2 * ts.height, 2 * ts.width ); 

_ grtext( 100, 300, "Graphics" ) ; 

_ setcharsize( ts.height, ts.width ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ) ; 

} 

produces the following: 
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setcharsize Functions 


Classification: 

Systems: 



PC Graphics 

_ setcharsize - DOS 
_ setcharsize_ w - DOS 
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setcharspacing Functions 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


#include <graph.h> 

void _ FAR _ setcharspacing( short space ); 
void _FAR _ setcharspacing_ w ( double space ); 

The _ set char spacing functions set the current character spacing to have the value of the argument 
space. For the _ set char spacing function, space represents a number of pixels. For the 
_ setcharspacing_ w function, space represents a length along the x-axis in the window coordinate 
system. 

The character spacing specifies the additional space to leave between characters when a text string is 
displayed with the _ grtext function. A negative value can be specified to cause the characters to be 
drawn closer together. The default value of the character spacing is 0. 

The _ setchar spacing functions do not return a value. 

_ grtext^ gettextsettings 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

_ setvideomode( _ VRES16COLOR ); 

_ grtext( 100, 100, "WATCOM" ); 

_ setcharspacing( 20 ); 

_ grtext( 100, 300, "Graphics" ) ; 
getch(); 

_ setvideomode( _ DEFAULTMODE ) ; 

} 

produces the following: 
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setcharspacing Functions 


Classification: 

Systems: 



PC Graphics 

_ setcharspacing - DOS 
_ setcharspacing_ w - DOS 
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setcliprgn 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <graph.h> 

void _ FAR _ setcliprgn( short xl, short yl, 

short x2, short y2 ); 

The _ setcliprgn function restricts the display of graphics output to the clipping region. This region 
is a rectangle whose opposite corners are established by the physical points (xl,yl) and (x2,y2). 

The _ setcliprgn function does not affect text output using the_ outtext and_ outmem 
functions. To control the location of text output, see the _ settextwindow function. 

The _ setcliprgn function does not return a value. 

_ settextwindow,_ setvieworg^ setviewport 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

short xl, yl, x2, y2; 

_ setvideomode( _ VRES16C0L0R ); 

_getcliprgn( &xl, &yl, &x2, &y2 ); 

_ setcliprgn! 130, 100, 510, 380 ); 

_ ellipse! _ GBORDER, 120, 90, 520, 390 ); 
getch(); 

_ setcliprgn! xl, yl, x2, y2 ); 

_ setvideomode( _ DEFAULTMODE ) ; 

} 

PC Graphics 
DOS 
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setcolor 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <graph.h> 

short _ FAR _ setcolor( short pixval ) ; 

The _ setcolor function sets the pixel value for the current color to be that indicated by the pixval 
argument. The current color is only used by the functions that produce graphics output; text output with 
_ outtext uses the current text color (see the_ settextcolor function). The default color value is 
one less than the maximum number of colors in the current video mode. 

The _ setcolor function returns the previous value of the current color. 

_ getcolor^ settextcolor 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

int col, old_ col; 

_ setvideomode( _ VRES16C0L0R ); 
old_ col = _getcolor(); 
for( col = 0; col < 16; ++col ) { 

_ setcolor( col ) ; 

_ rectangle( _ GFILLINTERIOR, 100, 100, 540, 380 ); 
getch (); 

} 

_ setcolor ( old_ col ); 

_ setvideomode( _ DEFAULTMODE ); 

} 

PC Graphics 
DOS 
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Synopsis: 


Description: 


Returns: 


setenv, _setenv, _wsetenv 


♦include <env.h> 

int setenv( const char *name, 

const char *newvalue, 
int overwrite ); 
int _ setenv( const char *name, 

const char *newvalue, 
int overwrite ); 

int _wsetenv( const wchar_ t *name, 

const wchar_ t *newvalue, 
int overwrite ); 

The environment list consists of a number of environment names, each of which has a value associated 
with it. Entries can be added to the environment list with the DOS set command or with the setenv 
function. All entries in the environment list can be displayed by using the DOS set command with no 
arguments. A program can obtain the value for an environment variable by using the getenv function. 

The setenv function searches the environment list for an entry of the form name=value. If no such 
string is present, setenv adds an entry of the form name=newvalue to the environment list. 

Otherwise, if the overwrite argument is non-zero, setenv either will change the existing value to 
newvalue or will delete the string name=value and add the string name=newvalue. 

If the newvalue pointer is NULL, all strings of the form name=value in the environment list will be 
deleted. 

The value of the pointer environ may change across a call to the setenv function. 

The setenv function will make copies of the strings associated with name and newvalue. 

The matching is case-insensitive; all lowercase letters are treated as if they were in upper case. 

Entries can also be added to the environment list with the DOS set command or with the putenv or 
setenv functions. All entries in the environment list can be obtained by using the getenv function. 

To assign a string to a variable and place it in the environment list: 

C>SET INCLUDE=C:\WATCOM\H 

To see what variables are in the environment list, and their current assignments: 

C>SET 

COMSPEC=C:\COMMAND.COM 
PATH=C:\;C:\WATCOM 
INCLUDE=C:\WATCOM\H 
C> 

The _ setenv function is identical tosetenv. Use _ setenv for ANSI naming conventions. 

The _ wsetenv function is a wide-character version ofsetenv that operates with wide-character 
strings. 

The setenv function returns zero upon successful completion. Otherwise, it will return a non-zero 
value and set errno to indicate the error. 
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setenv, _setenv, _wsetenv 


Errors: 

See Also: 
Example: 


Classification: 

Systems: 


When an error has occurred, errno contains a value indicating the type of error that has been detected. 

ENOMEM Not enough memory to allocate a new environment string. 

clearenv, exec. . getenv, getenv_ s.putenv, _ searchenv.spawn. . system 

The following will change the string assigned to INCLUDE and then display the new string. 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <env.h> 

void main() 

{ 

char *path; 

if( setenv( "INCLUDE", "D:\\WATCOM\\H", 1 ) == 0 ) 

if( (path = getenv( "INCLUDE" )) != NULL ) 

printf ( "INCLUDE=%s\n", path ); 

} 

WATCOM 

_setenv conforms to ANSI naming conventions 

setenv - All, Linux, RDOS 
_ setenv - All, Linux, RDOS 
_ wsetenv - All, Linux 
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setfillmask 


Synopsis: 

Description: 


Returns: 
See Also: 

Example: 


#include <graph.h> 

void _ FAR _ setfillmask( char _ FAR *mask ); 

The _ setfillmask function sets the current fill mask to the value of the argument mask. When the 
value of the mask argument is NULL, there will be no fill mask set. 

The fill mask is an eight-byte array which is interpreted as a square pattern (8 by 8) of 64 bits. Each bit 
in the mask corresponds to a pixel. When a region is filled, each point in the region is mapped onto the 
fill mask. When a bit from the mask is one, the pixel value of the corresponding point is set using the 
current plotting action with the current color; when the bit is zero, the pixel value of that point is not 
affected. 

When the fill mask is not set, a fill operation will set all points in the fill region to have a pixel value of 
the current color. By default, no fill mask is set. 

The _ setfillmask function does not return a value. 

_ getfillmask,_ ellipse^ floodfill,_ rectangle^ polygon^ pie,_ setcolor, 

_ setplotaction 

♦include <conio.h> 

♦include <graph.h> 

char old_mask[ 8 ]; 

char new_ mask [ 8 ] = { 0x81, 0x42, 0x24, 0x18, 

0x18, 0x24, 0x42, 0x81 }; 


main () 

{ 

_ setvideomode( _ VRES16COLOR ); 

_ getfillmask ( old_ mask ); 

_ setfillmask ( new_ mask ); 

_ rectangle! _ GFILLINTERIOR, 100, 100, 540, 380 ); 
_ setfillmask ( old_ mask ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ); 

} 

produces the following: 
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setfillmask 



Classification: PC Graphics 
Systems: DOS 
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setfont 


Synopsis: 

Description: 


♦include <graph.h> 

short _ FAR _ setfont ( char _ FAR *opt ) ; 

The _ setfont function selects a font from the list of registered fonts (see the_ registerf onts 
function). The font selected becomes the current font and is used whenever text is displayed with the 
_ out gt ext function. The function will fail if no fonts have been registered, or if a font cannot be 
found that matches the given characteristics. 

The argument opt is a string of characters specifying the characteristics of the desired font. These 
characteristics determine which font is selected. The options may be separated by blanks and are not 
case-sensitive. Any number of options may be specified and in any order. The available options are: 

hX character height X (in pixels) 

wX character width X (in pixels) 

/ choose a fixed-width font 

p choose a proportional-width font 

/• choose a raster (bit-mapped) font 

v choose a vector font 

b choose the font that best matches the options 

iiX choose font number X (the number of fonts is returned by the 

_ registerf onts function) 

t’facename’ choose a font with specified facename 

The facename option is specified as a "t" followed by a facename enclosed in single quotes. The 
available facenames are: 


Courier 

Helv 

Tins Rmn 
Script 
Modern 
Roman 


fixed-width raster font with serifs 
proportional-width raster font without serifs 
proportional-width raster font with serifs 

proportional-width vector font that appears similar to hand-writing 
proportional-width vector font without serifs 
proportional-width vector font with serifs 


When "nX" is specified to select a particular font, the other options are ignored. 

If the best fit option ("b") is specified, _ setfont will always be able to select a font. The font chosen 
will be the one that best matches the options specified. The following precedence is given to the 
options when selecting a font: 


1. Pixel height (higher precedence is given to heights less than the specified height ) 
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setfont 


Returns: 
See Also: 

Example: 


Classification: 

Systems: 


2. Facename 

3. Pixel width 

4. Font type (fixed or proportional) 

When a pixel height or width does not match exactly and a vector font has been selected, the font will 
be stretched appropriately to match the given size. 

The _ setfont function returns zero if successful; otherwise, (-1) is returned. 

_ registerfonts,_ unregisterfonts,_ getfontinfo*_ outgtext, 

_ getgtextextent,_ setgtextvector,_ getgtextvector 

♦include <conio.h> 

♦include <stdio.h> 

♦include <graph.h> 

main () 

{ 

int i, n; 
char buf[ 10 ]; 

_ setvideomode( _ VRES16COLOR ); 
n = _ registerfonts( "*.fon" ); 
for( i = 0; i < n; ++i ) { 

sprintf ( buf, "n%d", i ); 

_ setfont( buf ) ; 

_ moveto( 100, 100 ); 

_ outgtext( "WATCOM Graphics" ); 
getch(); 

_ clearscreen( _ GCLEARSCREEN ) ; 

} 

_ unregisterfonts() ; 

_ setvideomode( _ DEFAULTMODE ) ; 

} 

PC Graphics 
DOS 
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setgtextvector 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


#include <graph.h> 

struct xycoord _ FAR _ setgtextvector( short x, short y ); 

The _ setgtextvector function sets the orientation for text output used by the_ outgtext 
function to the vector specified by the arguments (x, y) . Each of the arguments can have a value of 
-1, 0 or 1, allowing for text to be displayed at any multiple of a 45-degree angle. The default text 
orientation, for normal left-to-right text, is the vector (1,0) . 

The _ setgtextvector function returns, as anxycoord structure, the previous value of the text 
orientation vector. 

_ registerfonts,_ unregisterfonts,_ setfont,_ getfontinfo,_ outgtext, 

_ getgtextextent,_ getgtextvector 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

struct xycoord old_ vec; 

_ setvideomode( _ VRES16COLOR ); 
old_ vec = _ getgtextvector(); 

_ setgtextvector( 0, -1 ); 

_ moveto( 100, 100 ); 

_ outgtext( "WATCOM Graphics" ); 

_ setgtextvector ( old_ vec. xcoord, old_ vec . ycoord ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ); 

} 

PC Graphics 
DOS 
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sethostent 


Synopsis: 

Description: 

See Also: 

Classification: 

Systems: 


#include <netdb.h> 

void sethostent( int stayopen ) ; 

The sethostent function opens the network host database at /etc/hosts and sets the position for 
reading to the first entry. If the network host database is already open, the position is reset to the first 
entry. The stayopen argument, if non-zero, will cause the database to remain open after subsequent 
calls to the gethostent function. 

gethostent, endhostent 

POSIX 

Linux 
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setjmp 


Synopsis: #include <setjmp.h> 

int setjmp ( jmp_ buf env ); 

Description: The set jmp function saves its calling environment in its jmp_ buf argument, for subsequent use by 
the long jmp function. 

In some cases, error handling can be implemented by using set jmp to record the point to which a 
return will occur following an error. When an error is detected in a called function, that function uses 
long jmp to jump back to the recorded position. The original function which called set jmp must still 
be active (it cannot have returned to the function which called it). 

Special care must be exercised to ensure that any side effects that are left undone (allocated memory, 
opened files, etc.) are satisfactorily handled. 

Returns: The set jmp function returns zero when it is initially called. The return value will be non-zero if the 

return is the result of a call to the long jmp function. An if statement is often used to handle these 
two returns. When the return value is zero, the initial call to setjmp has been made; when the return 
value is non-zero, a return from a long jmp has just occurred. 

See Also: long jmp 

Example: ((include <stdio.h> 

♦include <setjmp.h> 

jmp_ buf env; 

rtn () 

{ 

printf( "about to longjmp\n" ) ; 
longjmp( env, 14 ); 

} 

void main () 

{ 

int ret_ val = 2 93; 

if( 0 == ( ret_ val = setjmp( env ) ) ) { 

printf( "after setjmp %d\n", ret_ val ); 
rtn(); 

printf( "back from rtn %d\n", ret_ val ); 

} else { 

printf( "back from longjmp %d\n", ret_ val ); 

} 

} 

produces the following: 

after setjmp 0 
about to longjmp 
back from longjmp 14 

Classification: ISO C 

Systems: MACRO 
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setlinestyle 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


#include <graph.h> 

void _ FAR _ setlinestyle( unsigned short style ); 

The _ setlinestyle function sets the current line-style mask to the value of the style argument. 

The line-style mask determines the style by which lines and arcs are drawn. The mask is treated as an 
array of 16 bits. As a line is drawn, a pixel at a time, the bits in this array are cyclically tested. When a 
bit in the array is 1, the pixel value for the current point is set using the current color according to the 
current plotting action; otherwise, the pixel value for the point is left unchanged. A solid line would 
result from a value of OxFFFF and a dashed line would result from a value of OxFOFO 

The default line style mask is OxFFFF 

The _ setlinestyle function does not return a value. 

_ getlinestyle,_ lineto,_ rectangle^ polygon^ setplotaction 

♦include <conio.h> 

♦include <graph.h> 

♦define DASHED OxfOfO 

main () 

{ 

unsigned old_ style; 

_ setvideomode( _ VRES16COLOR ); 
old_ style = _ getlinestyle (); 

_ setlinestyle ( DASHED ); 

_ rectangle! _ GBORDER, 100, 100, 540, 380 ); 

_ setlinestyle ( old_ style ); 
getch(); 

_ setvideomode ( _ DEFAULTMODE ); 

} 

produces the following: 
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setlinestyle 


r 


v 


J 


Classification: PC Graphics 
Systems: DOS 
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setlocale, _wsetlocale 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


#include <locale.h> 

char *setlocale( int category, const char *locale ); 
wchar_ t *_ wsetlocale ( int category, const wchar_ t *locale); 


The setlocale function selects a portion of a program’s locale according to the category given by 
category and the locale specified by locale. A locale affects the collating sequence (the order in which 
characters compare with one another), the way in which certain character-handling functions operate, 
the decimal-point character that is used in formatted input/output and string conversion, and the format 
and names used in the time string produced by the strftime function. 

Potentially, there may be many such environments. Open Watcom C/C++ supports only the "C" locale 
and so invoking this function will have no effect upon the behavior of a program at present. Specifying 
the "POSIX" locale is supported for POSIX compatibility and equivalent to specifying the "C" locale. 

The possible values for the argument category are as follows: 


Category 

LC_ALL 

LCJCOLLATE 

LCCTYPE 

LC_MONETARY 

LC_NUMERIC 

LCJTIME 


Meaning 

select entire environment 

select collating sequence 

select the character-handling 

select monetary formatting information 

select the numeric-format environment 

select the time-related environment 


At the start of a program, the equivalent of the following statement is executed, 
setlocale ( LC_ ALL, "C" ); 

The _ wsetlocale function is a wide-character version ofsetlocale that operates with 
wide-character strings. 

If the selection is successful, a string is returned to indicate the locale that was in effect before the 
function was invoked; otherwise, a NULL pointer is returned. 

strcoll, strftime, strxfrm 


♦include <stdio.h> 

♦include <string.h> 

♦include <locale.h> 

char src[] = { "A sample STRING" }; 
char dst[20]; 

void main() 

{ 

char *prev_ locale; 
size_ t len; 
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setlocale, _wsetlocale 


Classification: 


Systems: 


/* set native locale */ 

prev_ locale = setlocale ( LC_ ALL, "" ); 
printf ( "%s\n", prev_ locale ); 
len = strxfrm( dst, src, 20 ); 
printf ( "%s (%u)\n", dst, len ); 


produces the following: 

C 

A sample STRING (15) 

ISOC 

_wsetlocale is WATCOM 

setlocale - All, Linux, RDOS, Netware 
_ wsetlocale - All, Linux 
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set matherr 


Synopsis: #include <math.h> 

void _ set_ matherr ( int (*rtn) ( struct _ exception *err_ info ) ) 

Description: The default matherr function supplied in the library can be replaced so that the application can handle 
mathematical errors. To do this, the _ set_ matherr function must be called with the address of the 
new mathematical error handling routine. 

Note: Under some systems, the default math error handler can be replaced by providing a user-written 
function of the same name, matherr, and using linking strategies to replace the default handler. 

A program may contain a user-written version of matherr to take any appropriate action when an 
error is detected. When zero is returned by the user-written routine, an error message will be printed 
upon stderr and errno will be set as was the case with the default function. When a non-zero value 
is returned, no message is printed and errno is not changed. The value err_ info->retval is 
used as the return value for the function in which the error was detected. 

When called, the user-written math error handler is passed a pointer to a structure of type struct 
_ exception which contains information about the error that has been detected: 

struct _ exception 

{ int type; /* TYPE OF ERROR */ 

char ‘name; /* NAME OF FUNCTION */ 

double argl; /* FIRST ARGUMENT TO FUNCTION */ 

double arg2; /* SECOND ARGUMENT TO FUNCTION */ 

double retval; /* DEFAULT RETURN VALUE */ 

} ; 

The type field will contain one of the following values: 

Value Meaning 

DOMAIN A domain error has occurred, such as sqrt(-leO) . 

SING A singularity will result, such as pow (OeO, -2) . 

OVERFLOW An overflow will result, such as pow (1 OeO, 100) . 

UNDERFLOW An underflow will result, such aspow(10e0,-100) . 

TLOSS Total loss of significance will result, such as exp (1000) . 

PLOSS Partial loss of significance will result, such as sin(10e70) . 

The name field points to a string containing the name of the function which detected the error. The 
fields argl and arg2 (if required) give the values which caused the error. The field retval contains 
the value which will be returned by the function. This value may be changed by a user-supplied version 
of the _set_matherr function. 

Returns: The _ set_ matherr function returns no value. 
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Example: 


Classification: 

Systems: 


set_matherr 


♦include <stdio.h> 

♦include <string.h> 

♦include <math.h> 

/* Demonstrate error routine in which negative */ 
/* arguments to "sqrt" are treated as positive */ 


int my_ matherr ( struct _ exception *err ) 

{ 

if( strcmp( err->name, "sqrt" ) == 0 ) { 

if( err->type == DOMAIN ) { 

err->retval = sqrt( - (err->argl) ); 
return( 1 ); 

} else 

return( 0 ) ; 

} else 

return ( 0 ); 


void main( void ) 

{ 

_ set_ matherr ( &my_ matherr ) ; 
printf( "%e\n", sqrt( -5e0 ) ); 

exit( 0 ) ; 


WATCOM 

Math 
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setmbcp 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <mbctype.h> 

int _ setmbcp( int codepage ) ; 

The _ setmbcp function sets the current code page number. 

The _ setmbcp function returns zero if the code page is set successfully. If an invalid code page value 
is supplied for codepage , the function returns -1 and the code page setting is unchanged. 

_ getmbcp,_ mbbtombc^ mbc jisto jms,_ mbc jmsto jis,_ mbctombb^ ismbbalnum, 

_ ismbbalpha^ ismbbgraph,_ ismbbkalnum,_ ismbbkalpha,_ ismbbkana, 

_ ismbbkprint,_ ismbbkpunct,_ ismbblead,_ ismbbprint,_ ismbbpunct, 

_ ismbbtrail^_ mbbtombc,_ mbc jisto jms,_ mbc jmsto jis,_ mbctombb,_ mbbtype 

♦include <stdio.h> 

♦include <mbctype.h> 

void main() 

{ 

printf ( "%d\n", _ setmbcp( 932 ) ); 

printf ( "%d\n", _ getmbcp() ); 

} 

produces the following: 

0 

932 

WATCOM 

DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS 
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setmode, _setmode 


Synopsis: #include <io.h> 

♦include <fcntl.h> 

int setmode( int handle, int mode ) ; 
int _ setmode( int handle, int mode ); 

Description: The setmode function sets, at the operating system level, the translation mode to be the value of mode 
for the file whose file handle is given by handle. The mode, defined in the <f cntl. h> header file, 
can be one of: 

Mode Meaning 

OJTEXT On input, a carriage-return character that immediately precedes a linefeed character is 

removed from the data that is read. On output, a carriage-return character is inserted 
before each linefeed character. 

0_BINARY Data is read or written unchanged. 

Returns: If successful, the setmode function returns the previous mode that was set for the file; otherwise, -1 is 

returned. When an error has occurred, errno contains a value indicating the type of error that has 
been detected. 

See Also: chsize, close, creat, dup, dup2, eof, exec. . ., fdopen, filelength, fileno, fstat, 

_ grow_ handlesisatty, lseek, open, read, sopen, stat, tell, write, umask 

Example: #include <stdio.h> 

♦include <fcntl.h> 

♦include <io.h> 

void main( void ) 

{ 

FILE *fp; 
long count; 

fp = fopen( "file", "rb" ); 
if ( fp != NULL ) { 

setmode( fileno ( fp ), 0_ BINARY ); 
count = OL; 

while( fgetc( fp ) != EOF ) ++count; 

printf ( "File contains %lu characters\n", 
count ); 
fclose ( fp ); 

} 

} 

Classification: WATCOM 

Systems: setmode - All, Linux, RDOS, Netware 

_ setmode - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS, 
Netware 
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setnetent 


Synopsis: 

Description: 

See Also: 

Classification: 

Systems: 


#include <netdb.h> 

void setnetent( int stayopen ); 

The setnetent function opens or rewinds the network database for subsequent access by the 
getnetent function. If stayopen is non-zero, the network database will remain open between calls to 
the getnetent function. The database can be closed when endnetent is called. 

This function is not thread-safe. Other calls to this function or to other functions accessing the 
hostname database may affect the return value from this function. 

getnetent, endnetent, getnetbyname, getnetbyaddr 

POSIX 

Linux 
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Synopsis: 

Description: 


Returns: 


See Also: 
Example: 


set_new_handler, _set_new_handler 


♦include <new.h> 

PFV set_ new_ handler ( PFV pNewHandler ) ; 

PFU _ set_ new_ handler ( PFU pNewHandler ) ; 

The set_ new_ handler functions are used to transfer control to a user-defined error handler if the 
new operator fails to allocate memory. The argument pNewHandler is the name of a function of type 
PFV or PFU. 

Type Description 

PFV Pointer to a function that returns void (i.e., returns nothing) and takes an 

argument of type void (i.e., takes no argument). 

PFU Pointer to a function that returns int and takes an argument of type unsigned 

which is the amount of space to be allocated. 

In a multi-threaded environment, handlers are maintained separately for each process and thread. Each 
new process lacks installed handlers. Each new thread gets a copy of its parent thread's new handlers. 
Thus, each process and thread is in charge of its own free-store error handling. 

The set_ new_ handler functions return a pointer to the previous error handler so that the previous 
error handler can be reinstated at a later time. 

The error handler specified as the argument to _ set_ new_ handler returns zero indicating that 
further attempts to allocate memory should be halted or non-zero to indicate that an allocation request 
should be re-attempted. 

_ bfreeseg^ bheapseg,calloc, free, malloc, realloc 

♦include <stdio.h> 

♦include <new.h> 

♦ if defined(_ 386_ ) 

const size_t MemBlock = 8192; 

♦ else 

const size_ t MemBlock = 2048; 

♦endif 

/* 

Pre-allocate a memory block for demonstration 
purposes. The out-of-memory handler will return 
it to the system so that "new" can use it. 

*/ 

long *failsafe = new long[MemBlock]; 
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set_new_handler,set_new_handler 


Classification: 

Systems: 


/* 

Declare a customized function to handle memory 
allocation failure. 


int out_ of_ memory_ handler ( unsigned size ) 

{ 

printf( "Allocation failed, " ) ; 
printf( "%u bytes not available.\n", size ); 
/* Release pre-allocated memory if we can */ 
if( failsafe == NULL ) { 

printf( "Halting allocation.\n" ); 

/* Tell new to stop allocation attempts */ 
return( 0 ) ; 

} else { 

delete failsafe; 
failsafe = NULL; 

printf( "Retrying allocation.\n" ); 

/* Tell new to retry allocation attempt */ 
return( 1 ); 

} 


void main( void ) 

{ 

int i; 

/* Register existence of a new memory handler */ 
_ set_ new_ handler ( out_ of_ memory_ handler ) ; 
long *pmemdump = new long[MemBlock]; 
for( i=l ; pmemdump != NULL; i++ ) { 

pmemdump = new long[MemBlock]; 
if( pmemdump != NULL ) 

printf ( "Another block allocated %d\n", i ); 

} 

} 

WATCOM 

set_ new_ handler - All, Netware 
_ set_ new_ handler - All, Netware 
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setpixel Functions 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <graph.h> 

short _ FAR _ setpixel( short x, short y ) ; 
short _ FAR _setpixel_w( double x, double y ); 

The _ setpixel function sets the pixel value of the point (x, y) using the current plotting action 
with the current color. The _ setpixel function uses the view coordinate system. The 
_ setpixel_ w function uses the window coordinate system. 

A pixel value is associated with each point. The values range from 0 to the number of colors (less one) 
that can be represented in the palette for the current video mode. The color displayed at the point is the 
color in the palette corresponding to the pixel number. For example, a pixel value of 3 causes the fourth 
color in the palette to be displayed at the point in question. 

The _ setpixel functions return the previous value of the indicated pixel if the pixel value can be set; 
otherwise, (-1) is returned. 

_ getpixel^ setcolor^. setplotaction 

♦include <conio.h> 

♦include <graph.h> 

♦include <stdlib.h> 

main () 

{ 

int x, y; 
unsigned i; 

_ setvideomode( _ VRES16C0L0R ); 

_ rectangle ( _ GBORDER, 100, 100, 540, 380 ); 
for( i = 0; i <= 60000; ++i ) { 

x = 101 + rand() % 439; 
y = 101 + rand() % 279; 

_ setcolor ( _ getpixel( x, y ) + 1 ); 

_ setpixel( x, y ); 

} 

getch (); 

_ setvideomode( _DEFAULTMODE ); 

} 

PC Graphics 

_ setpixel - DOS 
_ setpixel_ w - DOS 
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setplotaction 


Synopsis: #include <graph.h> 

short _ FAR _ setplotaction( short action ); 

Description: The _ setplotaction function sets the current plotting action to the value of the action argument. 

The drawing functions cause pixels to be set with a pixel value. By default, the value to be set is 
obtained by replacing the original pixel value with the supplied pixel value. Alternatively, the replaced 
value may be computed as a function of the original and the supplied pixel values. 

The plotting action can have one of the following values: 

JGPSET replace the original screen pixel value with the supplied pixel value 

_GAND replace the original screen pixel value with the bitwise and of the original 

pixel value and the supplied pixel value 

_GOR replace the original screen pixel value with the bitwise or of the original pixel 

value and the supplied pixel value 

_GXOR replace the original screen pixel value with the bitwise exclusive-or of the 

original pixel value and the supplied pixel value. Performing this operation 
twice will restore the original screen contents, providing an efficient method 
to produce animated effects. 

Returns: The previous value of the plotting action is returned. 

See Also: _ getplotaction 

Example: #include <conio.h> 

♦include <graph.h> 

main () 

{ 

int old_ act; 

_ setvideomode ( _VRES16C0L0R ); 
old_ act = _ getplotaction () ; 

_ setplotaction( _ GPSET ); 

_ rectangle! _ GFILLINTERIOR, 100, 100, 540, 380 ); 

getch (); 

_ setplotaction ( _ GXOR ); 

_ rectangle! _ GFILLINTERIOR, 100, 100, 540, 380 ); 

getch (); 

_ setplotaction ( old_ act ); 

_ setvideomode( _ DEFAULTMODE ); 

} 

Classification: PC Graphics 
Systems: DOS 
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setprotoent 


Synopsis: 

Description: 

See Also: 

Classification: 

Systems: 


#include <netdb.h> 

void setprotoent( int stayopen ) ; 

The setprotoent function opens or rewinds the protocol database to allow reading starting at the 
first entry. If stayopen is non-zero, the database will remain open between subsequent calls to 
getprotoent until the endprotoent function is called. 

This function is not thread-safe. Other calls to this function or to other functions accessing the protocol 
database may affect the return value from this function. 

getprotoent, endprotoent, getprotobyname, getprotobynumber 

POSIX 

Linux 
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setpwent 


Synopsis: 

Description: 

See Also: 
Example: 


Classification: 

Systems: 


#include <pwd.h> 
void setpwent( void ) ; 

The setpwent function returns pointer for iterating over the system’s password database to the first 
entry. It is normally called prior to using any of the POSIX functions that access the password database 
to ensure starting at the first entry. 

getpwent, endpwent, getpwnam, getpwuid 

The following program will print out each user and their user ID in the system’s password database 

♦include <stdio.h> 

♦include <pwd.h> 

void main() 

{ 

struct passwd *pw; 
setpwent(); 

while((pw = getpwent()) != NULL) { 

printf("User id %d is %s\n", (int) pw->pw_ uid, pw->pw_ name) ; 

} 

endpwent(); 

} 

POSIX 

Linux 
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setservent 


Synopsis: 

Description: 

See Also: 

Classification: 

Systems: 


#include <netdb.h> 

void setservent( int stayopen ) ; 

The setservent function opens or rewinds the service database. If stayopen is non-zero, the 
database will be kept open between calls to getservent until endservent is called to close the 
database. 

This function is not thread-safe. Other calls to this function or to other functions accessing the 
hostname database may affect the return value from this function. 

getservent, endservent, getservbyname, getservbyport 

POSIX 

Linux 


Library Functions and Macros 955 




settextalign 


Synopsis: #include <graph.h> 

void _ FAR _ settextalign( short horiz, short vert ); 

Description: The _ settextalign function sets the current text alignment to the values specified by the arguments 
horiz and vert. When text is displayed with the _ grtext function, it is aligned (justified) horizontally 
and vertically about the given point according to the current text alignment settings. 

The horizontal component of the alignment can have one of the following values: 

NORMAL use the default horizontal alignment for the current setting of the text path 

_LEFT the text string is left justified at the given point 

jCENTER the text string is centred horizontally about the given point 

_RIGHT the text string is right justified at the given point 

The vertical component of the alignment can have one of the following values: 

NORMAL use the default vertical alignment for the current setting of the text path 

_TOP the top of the text string is aligned at the given point 

_CAP the cap line of the text string is aligned at the given point 

_HALF the text string is centred vertically about the given point 

_BASE the base line of the text string is aligned at the given point 

_BOTTOM the bottom of the text string is aligned at the given point 

The default is to use _ LEFT alignment for the horizontal component unless the text path is 
_ PATH_ LEFT, in which case_ RIGHT alignment is used. The default value for the vertical 
component is _ TOP unless the text path is_ PATH_ UP, in which case_ BOTTOM alignment is used. 

Returns: The _ settextalign function does not return a value. 

See Also: _ grtext^ gettextsettings 

Example: ((include <conio.h> 

((include <graph.h> 

main() 

{ 

_ setvideomode ( _VRES16COLOR ); 

_ grtext( 200, 100, "WATCOM" ); 

_ setpixel( 200, 100 ); 

_ settextalign( _ CENTER, _ HALF ); 

_ grtext( 200, 200, "Graphics" ); 

_ setpixel( 200, 200 ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ); 

} 
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settextalign 


produces the following: 



Classification: PC Graphics 
Systems: DOS 
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settextcolor 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


♦include <graph.h> 

short _ FAR _ settextcolor( short pixval ); 

The _ settextcolor function sets the current text color to be the color indicated by the pixel value 
of the pixval argument. This is the color value used for displaying text with the _ outtext and 
_ outmem functions. Use the_ setcolor function to change the color of graphics output. The 
default text color value is set to 7 whenever a new video mode is selected. 

The pixel value pixval is a number in the range 0-31. Colors in the range 0-15 are displayed normally. 
In text modes, blinking colors are specified by adding 16 to the normal color values. The following 
table specifies the default colors in color text modes. 


Pixel 

Color 

Pixel 

Color 

value 


value 


0 

Black 

8 

Gray 

1 

Blue 

9 

Light Blue 

2 

Green 

10 

Light Green 

3 

Cyan 

11 

Light Cyan 

4 

Red 

12 

Light Red 

5 

Magenta 

13 

Light Magenta 

6 

Brown 

14 

Yellow 

7 

White 

15 

Bright White 


The _ settextcolor function returns the pixel value of the previous text color. 

_ gettextcolor,_ outtext,_ outmem^ setcolor 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

int old_ col; 
long old_ bk; 

_ setvideomode( _ TEXTC80 ) ; 
old_ col = _ gettextcolor () ; 
old_ bk = _ getbkcolor () ; 

_ settextcolor( 7 ) ; 

_ setbkcolor( _ BLUE ); 

_ outtext( " WATCOM \nGraphics" ); 

_ settextcolor( old_ col ); 

_ setbkcolor( old_ bk ) ; 
getch(); 

_ setvideomode( _ DEFAULTMODE ); 


PC Graphics 
DOS 
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settextcursor 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <graph.h> 

short _ FAR _ settextcursor( short cursor ); 

The _ settextcursor function sets the attribute, or shape, of the cursor in text modes. The 
argument cursor specifies the new cursor shape. The cursor shape is selected by specifying the top and 
bottom rows in the character matrix. The high byte of cursor specifies the top row of the cursor; the 
low byte specifies the bottom row. 

Some typical values for cursor are; 


Cursor 

Shape 

0x0607 

normal underline cursor 

0x0007 

full block cursor 

0x0407 

half-height block cursor 

0x2000 

no cursor 


The _ settextcursor function returns the previous cursor shape when the shape is set successfully; 
otherwise, (-1) is returned. 

_ gettextcursor,_ displaycursor 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

int old_ shape; 

old_ shape = _ gettextcursor () ; 

_settextcursor( 0x0007 ); 

_ outtext( "\nBlock cursor" ); 
getch(); 

_ settextcursor( 0x0407 ); 

_ outtext( "\nHalf height cursor" ); 
getch(); 

_ settextcursor( 0x2000 ); 

_ outtext( "\nNo cursor" ); 
getch(); 

_ settextcursor ( old_ shape ); 

} 

PC Graphics 
DOS 
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settextorient 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <graph.h> 

void _ FAR _ settextorient( short vecx, short vecy ); 

The _ settextorient function sets the current text orientation to the vector specified by the 
arguments (vecx, vecy) . The text orientation specifies the direction of the base-line vector when a 
text string is displayed with the _ grtext function. The default text orientation, for normal 
left-to-right text, is the vector (1,0) . 

The _ settextorient function does not return a value. 

_ grtext^ gettextsettings 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

_ setvideomode( _ VRES16COLOR ); 

_ grtext( 200, 100, "WATCOM" ); 

_ settextorient( 1, 1 ) ; 

_ grtext( 200, 200, "Graphics" ) ; 
getch(); 

_ setvideomode( _ DEFAULTMODE ) ; 

} 

produces the following: 



PC Graphics 
DOS 
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settextpath 


Synopsis: #include <graph.h> 

void _ FAR _ settextpath( short path ); 

Description: The _ settextpath function sets the current text path to have the value of the path argument. The 
text path specifies the writing direction of the text displayed by the _ grtext function. The argument 
can have one of the following values: 

_PATH_RIGHT subsequent characters are drawn to the right of the previous character 

_PATH_LEFT subsequent characters are drawn to the left of the previous character 

_PATH_UP subsequent characters are drawn above the previous character 

_PATH_DOWN subsequent characters are drawn below the previous character 

The default value of the text path is _ PATH_ RIGHT . 

Returns: The _ settextpath function does not return a value. 

See Also: _ grtext^_ gettextsettings 

Example: #include <conio.h> 

♦include <graph.h> 

main() 

{ 

_ setvideomode ( _VRES16C0L0R ); 

_ grtext( 200, 100, "WATCOM" ); 

_ settextpath ( _ PATH_ DOWN ) ; 

_ grtext( 200, 200, "Graphics" ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ); 

} 

produces the following: 
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settextpath 
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G 
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a 
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J 


Classification: PC Graphics 
Systems: DOS 
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settextposition 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <graph.h> 

struct rccoord _ FAR _ settextposition( short row, 

short col ); 

The _ settextposition function sets the current output position for text to be (row, col) where 
this position is in terms of characters, not pixels. 

The text position is relative to the current text window. It defaults to the top left corner of the screen, 
(1,1) , when a new video mode is selected, or when a new text window is set. The position is 
updated as text is drawn with the _ outtext and_ outmem functions. 

Note that the output position for graphics output differs from that for text output. The output position 
for graphics output can be set by use of the _ moveto function. 

Also note that output to the standard output file, stdout, is line buffered by default. It may be 
necessary to flush the output stream using f flush ( stdout ) after a print f call if your output 
does not contain a newline character. Mixing of calls to _ outtext andprintf may cause 
overlapped text since _ outtext uses the output position that was set by _settextposition. 

The _ settextposition function returns, as anrccoord structure, the previous output position 
for text. 

_ gettextposition,_ outtext^ outmem^ settextwindow,_ moveto 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

struct rccoord old_pos; 

_ setvideomode( _ TEXTC80 ) ; 
old_ pos = _ gettextposition () ; 

_ settextposition( 10, 40 ); 

_ outtext( "WATCOM Graphics" ); 

_ settextposition ( old_pos.row, old_pos.col ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ); 

} 

PC Graphics 
DOS 
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settextrows 


Synopsis: #include <graph.h> 

short _ FAR _ settextrows( short rows ); 

Description: The _ settextrows function selects the number of rows of text displayed on the screen. The number 
of rows is specified by the argument rows. Computers equipped with EGA, MCGA and VGA adapters 
can support different numbers of text rows. The number of rows that can be selected depends on the 
current video mode and the type of monitor attached. 

If the argument rows has the value _MAXTEXTROWS, the maximum number of text rows will be 
selected for the current video mode and hardware configuration. In text modes the maximum number of 
rows is 43 for EGA adapters, and 50 for MCGA and VGA adapters. Some graphics modes will support 
43 rows for EGA adapters and 60 rows for MCGA and VGA adapters. 

Returns: The _ settextrows function returns the number of screen rows when the number of rows is set 

successfully; otherwise, zero is returned. 

See Also: _ getvideoconf ig,_ setvideomode,_ setvideomoderows 

Example: #include <conio.h> 

♦include <graph.h> 

♦include <stdio.h> 

int valid_rows[] = { 

14, 25, 28, 30, 

34, 43, 50, 60 

} ; 

main() 

{ 

int i, j, rows; 
char but[ 80 ]; 

for( i = 0; i < 8; ++i ) { 

rows = valid_ rows[ i ]; 
if ( _ settextrows( rows ) == rows ) { 

for( j = 1; j <= rows; ++j ) { 

sprintf( buf, "Line %d", j ); 

_ settextposition ( j, 1 ); 

_ outtext( buf ); 

} 

getch(); 

} 

} 

_ setvideomode( _ DEFAULTMODE ) ; 

} 

Classification: PC Graphics 
Systems: DOS 
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settextwindow 


Synopsis: #include <graph.h> 

void _ FAR _ settextwindow( short rowl, short coll, 

short row2, short col2 ); 

Description: The _ settextwindow function sets the text window to be the rectangle with a top left comer at 
(rowl, coll) and a bottom right corner at (row2,col2). These coordinates are in terms of 
characters not pixels. 

The initial text output position is (1,1). Subsequent text positions are reported (by the 
_ gettextposition function) and set (by the_ outtext^_ outmem and_ settextposition 
functions) relative to this rectangle. 

Text is displayed from the current output position for text proceeding along the current row and then 
downwards. When the window is full, the lines scroll upwards one line and then text is displayed on the 
last line of the window. 

Returns: The _ settextwindow function does not return a value. 

See Also: _ gettextposition,_ outtext^ outmem^ settextposition 

Example: ((include <conio.h> 

♦include <graph.h> 

♦include <stdio.h> 

main () 

{ 

int i; 

short rl, cl, r2, c2; 
char but[ 80 ]; 

_ setvideomode( _ TEXTC80 ); 

_ gettextwindow( &rl, &cl, &r2, &c2 ); 

_ settextwindow( 5, 20, 20, 40 ); 
for ( i = 1; i <= 20; ++i ) { 

sprintf( buf, "Line %d\n", i ); 

_ outtext( buf ); 

} 

getch(); 

_ settextwindow( rl, cl, r2, c2 ); 

_ setvideomode( _ DEFAULTMODE ); 

} 

Classification: PC Graphics 
Systems: DOS 
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setvbuf 


Synopsis: #include <stdio.h> 

int setvbuf( FILE *fp, 
char *buf, 
int mode, 
size_ t size ); 

Description: The setvbuf function can be used to associate a buffer with the file designated by //?. If this function 
is used, it must be called after the file has been opened and before it has been read or written. The 
argument mode determines how the file fp will be buffered, as follows: 

Mode Meaning 

JOFBF causes input/output to be fully buffered. 

JOLBF causes output to be line buffered (the buffer will be flushed when a new-line character is 

written, when the buffer is full, or when input is requested on a line buffered or 
unbuffered stream). 

JONBF causes input/output to be completely unbuffered. 

If the argument buf is not NULL, the array to which it points will be used instead of an automatically 
allocated buffer. The argument size specifies the size of the array. 

Returns: The setvbuf function returns zero on success, or a non-zero value if an invalid value is given for 

mode or size. 

See Also: fopen, setbuf 

Example: ((include <stdio.h> 

((include <stdlib.h> 

void main() 

{ 

char *buf; 

FILE *fp; 

fp = fopen( "file", "r" ); 
buf = (char *) malloc( 1024 ) ; 
setvbuf ( fp, buf, _ IOFBF, 1024 ) ; 

} 

Classification: ISO C 

Systems: All, Linux, RDOS, Netware 
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setvideomode 


Synopsis: #include <graph.h> 

short _ FAR _ setvideomode ( short mode ) ; 

Description: The _ setvideomode function sets the video mode according to the value of the mode argument. The 
value of mode can be one of the following: uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 
uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 
uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 

Mode Type Size Colors Adapter 

_ MAXRESMODE (graphics mode with highest resolution) 

_ MAXCOLORMODE (graphics mode with most colors) 

_ DEFAULTMODE (restores screen to original mode) 


_ TEXTBW40 

M, T 

40 

X 

25 

16 

MDPA, HGC,VGA, SVGA 

_ TEXTC40 

C,T 

40 

X 

25 

16 

CGA, EGA, MCGA, VGA, SVGA 

_ TEXTBW80 

M, T 

80 

X 

25 

16 

MDPA, HGC, VGA, SVGA 

_ TEXTC80 

C,T 

80 

X 

25 

16 

CGA, EGA, MCGA, VGA, SVGA 

_ MRES4COLOR 

C,G 

320 

X 

200 

4 

CGA, EGA, MCGA, VGA, SVGA 

_ MRESNOCOLOR 

C,G 

320 

X 

200 

4 

CGA, EGA, MCGA, VGA, SVGA 

_ HRESBW 

C,G 

640 

X 

200 

2 

CGA, EGA, MCGA, VGA, SVGA 

_ TEXTMONO 

M, T 

80 

X 

25 

16 

MDPA, HGC, VGA, SVGA 

_ HERCMONO 

M, G 

720 

X 

350 

2 

HGC 

_ MRES16COLOR 

C,G 

320 

X 

200 

16 

EGA, VGA, SVGA 

_ HRES16COLOR 

C, G 

640 

X 

200 

16 

EGA, VGA, SVGA 

_ ERESNOCOLOR 

M, G 

640 

X 

350 

4 

EGA, VGA, SVGA 

_ ERESCOLOR 

C,G 

640 

X 

350 

4/16 

EGA, VGA, SVGA 

_ VRES2COLOR 

C, G 

640 

X 

480 

2 

MCGA, VGA, SVGA 

_ VRES16COLOR 

C,G 

640 

X 

480 

16 

VGA, SVGA 

_ MRES256C0L0R 

C,G 

320 

X 

200 

256 

MCGA, VGA, SVGA 

_ URES256COLOR 

C, G 

640 

X 

400 

256 

SVGA 

_ VRES256C0L0R 

C,G 

640 

X 

480 

256 

SVGA 

_ SVRES16COLOR 

C, G 

800 

X 

600 

16 

SVGA 

_ SVRES256C0L0R 

C, G 

800 

X 

600 

256 

SVGA 

_ XRES16COLOR 

C,G 

1024 

X 

768 

16 

SVGA 

_ XRES256C0L0R 

C, G 

1024 

X 

768 

256 

SVGA 


In the preceding table, the Type column contains the following letters: 

M indicates monochrome; multiple colors are shades of grey 

C indicates color 

G indicates graphics mode; size is in pixels 

T indicates text mode; size is in columns and rows of characters 

The Adapter column contains the following codes: 


MDPA 

IBM Monochrome Display/Printer Adapter 

CGA 

IBM Color Graphics Adapter 

EGA 

IBM Enhanced Graphics Adapter 

VGA 

IBM Video Graphics Array 

MCGA 

IBM Multi-Color Graphics Array 

HGC 

Hercules Graphics Adapter 
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setvideomode 


Returns: 


See Also: 


SVGA SuperVGA adapters 

The modes _ MAXRESMODE and_ MAXCOLORMODE will select from among the video modes supported 
by the current graphics adapter the one that has the highest resolution or the greatest number of colors. 
The video mode will be selected from the standard modes, not including the SuperVGA modes. 

Selecting a new video mode resets the current output positions for graphics and text to be the top left 
corner of the screen. The background color is reset to black and the default color value is set to be one 
less than the number of colors in the selected mode. 

The _ setvideomode function returns the number of text rows when the new mode is successfully 
selected; otherwise, zero is returned. 

_ getvideoconfig,_ settextrows^ setvideomoderows 
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setvideomode 


Example: 


Classification: 

Systems: 


♦include <conio.h> 

♦include <graph.h> 

♦include <stdio.h> 

♦include <stdlib.h> 

main () 

{ 

int mode; 

struct videoconfig vc; 
char buf[ 80 ]; 

_ getvideoconfig( &vc ); 

/* select "best" video mode */ 
switch( vc.adapter ) { 

case _ VGA : 
case _ SVGA : 

mode = _ VRES16COLOR; 
break; 

case _ MCGA : 

mode = _ MRES256COLOR; 
break; 
case _ EGA : 

if ( vc.monitor == _ MONO ) { 

mode = _ ERESNOCOLOR; 

} else { 

mode = _ ERESCOLOR; 

} 

break; 
case _ CGA : 

mode = _ MRES4COLOR; 
break; 

case _ HERCULES : 

mode = _ HERCMONO; 
break; 
default : 

puts( "No graphics adapter" ); 
exit ( 1 ); 

} 

if ( _ setvideomode( mode ) ) { 

_ getvideoconfig( &vc ); 

sprintf ( buf, "%d x %d x %d\n", vc.numxpixels, 
vc.numypixels, vc.numcolors ); 

_ outtext( buf ); 
getch(); 

_ setvideomode( _DEFAULTMODE ) ; 

} 

} 

PC Graphics 
DOS 
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setvideomoderows 


Synopsis: #include <graph.h> 

short _ FAR _ setvideomoderows( short mode, short rows ); 

Description: The _ setvideomoderows function selects a video mode and the number of rows of text displayed 
on the screen. The video mode is specified by the argument mode and is selected with the 
_ setvideomode function. The number of rows is specified by the argument rows and is selected 
with the _ settextrows function. 

Computers equipped with EGA, MCGA and VGA adapters can support different numbers of text rows. 
The number of rows that can be selected depends on the video mode and the type of monitor attached. 

Returns: The _ setvideomoderows function returns the number of screen rows when the mode and number 

of rows are set successfully; otherwise, zero is returned. 

See Also: _ getvideoconf ig,_ setvideomode,_ settextrows 

Example: #include <conio.h> 

♦include <graph.h> 

♦include <stdio.h> 

main () 

{ 

int rows; 
char but[ 80 ]; 

rows = _ setvideomoderows( _ TEXTC80, _ MAXTEXTROWS ); 
if( rows != 0 ) { 

sprintf( buf, "Number of rows is %d\n", rows ); 

_ outtext( buf ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ); 

} 

} 

Classification: PC Graphics 
Systems: DOS 
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setvieworg 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <graph.h> 

struct xycoord _ FAR _ setvieworg( short x, short y ); 

The _ setvieworg function sets the origin of the view coordinate system, (0,0), to be located at 
the physical point (x,y) . This causes subsequently drawn images to be translated by the amount 
(x, y) . 

Note: In previous versions of the software, the _ setvieworg function was called_ setlogorg. 
uindex=2 

The _ setvieworg function returns, as anxycoord structure, the physical coordinates of the 
previous origin. 

_ getviewcoord,_ getphyscoord,_ setcliprgn,_ setviewport 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

_ setvideomode( _ VRES16COLOR ); 

_ setvieworg( 320, 240 ) ; 

_ ellipse( _ GBORDER, -200, -150, 200, 150 ); 
getch(); 

_ setvideomode( _ DEFAULTMODE ); 

} 

PC Graphics 
DOS 
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setviewport 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <graph.h> 

void _ FAR _ setviewport( short xl, short yl, 

short x2, short y2 ); 

The _ setviewport function restricts the display of graphics output to the clipping region and then 
sets the origin of the view coordinate system to be the top left corner of the region. This region is a 
rectangle whose opposite corners are established by the physical points (xl,yl) and (x2,y2). 

The _ setviewport function does not affect text output using the_ outtext and_ outmem 
functions. To control the location of text output, see the _ settextwindow function. 

The _ setviewport function does not return a value. 

_ setcliprgn^ setvieworg,_ settextwindow,_ setwindow 

♦include <conio.h> 

♦include <graph.h> 

♦define XSIZE 380 
♦define YSIZE 280 

main () 

{ 

_ setvideomode( _ VRES16COLOR ); 

_ setviewport( 130, 100, 130 + XSIZE, 100 + YSIZE ); 

_ ellipse! _ GBORDER, 0, 0, XSIZE, YSIZE ); 

getch(); 

_ setvideomode ( _ DEFAULTMODE ); 

} 

PC Graphics 
DOS 


972 Library Functions and Macros 




setvisualpage 


Synopsis: #include <graph.h> 

short _ FAR _ setvisualpage( short pagenum ); 

Description: The _ setvisualpage function selects the page (in memory) from which graphics output is 
displayed. The page to be selected is given by the pagenum argument. 

Only some combinations of video modes and hardware allow multiple pages of graphics to exist. When 
multiple pages are supported, the active page may differ from the visual page. The graphics 
information in the visual page determines what is displayed upon the screen. Animation may be 
accomplished by alternating the visual page. A graphics page can be constructed without affecting the 
screen by setting the active page to be different than the visual page. 

The number of available video pages can be determined by using the _ getvideoconf ig function. 
The default video page is 0. 

Returns: The _ setvisualpage function returns the number of the previous page when the visual page is set 

successfully; otherwise, a negative number is returned. 

See Also: _ getvisualpage,_ setactivepage,_ getactivepage,_ getvideoconf ig 

Example: ((include <conio.h> 

♦include <graph.h> 

main () 

{ 

int old_ apage; 
int old_ vpage; 

_ setvideomode( _ HRES16COLOR ); 
old_ apage = _ getactivepage () ; 
old_ vpage = _ getvisualpage () ; 

/* draw an ellipse on page 0 */ 

_ setactivepage( 0 ); 

_ setvisualpage( 0 ); 

_ellipse( _ GFILLINTERIOR, 100, 50, 540, 150 ); 

/* draw a rectangle on page 1 */ 

_ setactivepage( 1 ); 

_ rectangle! _ GFILLINTERIOR, 100, 50, 540, 150 ); 
getch(); 

/* display page 1 */ 

_ setvisualpage( 1 ); 
getch() ; 

_ setactivepage ( old_ apage ); 

_ setvisualpage ( old_ vpage ) ; 

_ setvideomode( _ DEFAULTMODE ); 

} 

Classification: PC Graphics 
Systems: DOS 
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setwindow 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 


#include <graph.h> 

short _ FAR _ setwindow( short invert, 

double xl, double yl, 
double x2, double y2 ); 

The _ setwindow function defines a window for the window coordinate system. Window coordinates 
are specified as a user-defined range of values. This allows for consistent pictures regardless of the 
video mode. 

The window is defined as the region with opposite corners established by the points (xl, yl) and 
(x2, y2) . The argument invert specifies the direction of the y-axis. If the value is non-zero, the y 
values increase from the bottom of the screen to the top, otherwise, the y values increase as you move 
down the screen. 

The window defined by the _ setwindow function is displayed in the current viewport. A viewport is 
defined by the _ setviewport function. 

By default, the window coordinate system is defined with the point (0.0,0.0) located at the lower 
left corner of the screen, and the point (1.0,1.0) at the upper right corner. 

The _ setwindow function returns a non-zero value when the window is set successfully; otherwise, 
zero is returned. 

_ setviewport 

♦include <conio.h> 

♦include <graph.h> 

main () 

{ 

_ setvideomode( _ MAXRESMODE ); 
draw_ house( "Default window" ); 

_ setwindow( 1, -0.5, -0.5, 1.5, 1.5 ); 
draw_ house( "Larger window" ); 

_ setwindow( 1, 0.0, 0.0, 0.5, 1.0 ); 
draw_ house( "Left side" ); 

_ setvideomode( _ DEFAULTMODE ) ; 

} 

draw_ house ( char *msg ) 

{ 

_ clearscreen ( _ GCLEARSCREEN ); 

_ outtext( msg ); 

_ rectangle_ w ( _ GBORDER, 0.2, 0.1, 0.8, 0.6 ); 

_moveto_w( 0.1, 0.5 ); 

_lineto_w( 0.5, 0.9 ); 

_lineto_w( 0.9, 0.5 ); 

_ arc_ w ( 0.4, 0.5, 0.6, 0.3, 0.6, 0.4, 0.4, 0.4 ); 

_ rectangle_ w ( _ GBORDER, 0.4, 0.1, 0.6, 0.4 ); 
getch(); 

} 

PC Graphics 
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setwindow 


Systems: 


DOS 


Library Functions and Macros 975 




signal 


Synopsis: #include <signal.h> 

void ( *signal(int sig, void (*func)(int)) )( int ); 

Description: The signal function is used to specify an action to take place when certain conditions are detected 
while a program executes. These conditions are defined to be: 

Condition Meaning 

SIGABRT abnormal termination, such as caused by the abort function 

SIGBREAK an interactive attention (Ctrl+Break on keyboard) is signalled 

SIGFPE an erroneous floating-point operation occurs (such as division by zero, overflow 

and underflow) 

SIGILL illegal instruction encountered 

SIGINT an interactive attention (Ctrl+C on keyboard) is signalled 

SIGSEGV an illegal memory reference is detected 

SIGTERM a termination request is sent to the program 

SIGUSR1 OS/2 process flag A via DosFlagProcess 

SIGUSR2 OS/2 process flag B via DosFlagProcess 

SIGUSR3 OS/2 process flag C via DosFlagProcess 

An action can be specified for each of the conditions, depending upon the value of th efunc argument: 

function When func is a function name, that function will be called equivalently to the following 

code sequence. 

/* "sig_no" is condition being signalled */ 
signal ( sig_ no, SIG_ DFL ); 

(*func)( sig_ no ); 

The func function may terminate the program by calling the exit or abort functions 
or call the long jmp function. Because the next signal will be handled with default 
handling, the program must again call signal if it is desired to handle the next 
condition of the type that has been signalled. 

After returning from the signal-catching function, the receiving process will resume 
execution at the point at which it was interrupted. 

The signal catching function is described as follows: 

void func ( int sig_ no ) 

{ 

/* body of function */ 

} 
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signal 


Returns: 

See Also: 
Example: 


Since signal-catching functions are invoked asynchronously with process execution, the 
type sig_ atomic_ t may be used to define variables on which an atomic operation 
(e.g., incrementation, decrementation) may be performed. 

SIG_DFL This value causes the default action for the condition to occur. 

SIG_IGN This value causes the indicated condition to be ignored. 

When a condition is detected, it may be handled by a program, it may be ignored, or it may be handled 
by the usual default action (often causing an error message to be printed upon the stderr stream 
followed by program termination). 

When the program begins execution, the equivalent of 


signal ( 

SIGABRT, 

SIG_ 

_ DFL ) 

signal ( 

SIGFPE, 

SIG_ 

DFL ) ; 

signal ( 

SIGILL, 

SIG_ 

DFL ) ; 

signal ( 

SIGINT, 

SIG_ 

DFL ) ; 

signal ( 

SIGSEGV, 

SIG_ 

_ DFL ) 

signal ( 

SIGTERM, 

SIG_ 

_ DFL ) 

signal ( 

SIGBREAK 

, SIG_ DFL 

signal ( 

SIGUSR1, 

SIG_ 

_ IGN ) 

signal ( 

SIGUSR2, 

SIG_ 

_ IGN ) 

signal ( 

SIGUSR3, 

SIG_ 

_ IGN ) 


is executed. 

The SIGINT signal is generated by pressing the Ctrl+C or Ctrl+Break key combination on the 
keyboard. Under DOS, if "BREAK=ON", a signal will be delivered at the next DOS call; otherwise, if 
"BREAK=OFF", a signal will be delivered only at the next standard input/output DOS call. The 
BREAK setting is configured in the CONFIG . SYS file. 


Under OS/2, the SIGBREAK signal can only be received if Ctrl+Break is pressed and the keyboard is in 
binary (raw) mode. In ASCII (cooked) mode, which is the default, both Ctrl+C and Ctrl+Break 
combinations will raise the SIGINT signal. 

A condition can be generated by a program using the raise function. 

A return value of SIG_ ERR indicates that the request could not be handled, anderrno is set to the 
value EINVAL. 


Otherwise, the previous value of func for the indicated condition is returned, 
raise 

♦include <stdio.h> 

♦include <signal.h> 

♦include <i86.h> 

/* SIGINT Test */ 

sig_ atomic_ t signal_ count; 
sig_ atomic_ t signal_ number; 
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signal 


Classification: 

Systems: 


void MylntHandler( int signo ) 

{ 

signal_ count+t; 
signal_ number = signo; 

} 

void MyBreakHandler( int signo ) 

{ 

signal_ count++; 
signal_ number = signo; 

} 

int main( void ) 

{ 

int i; 

signal_ count = 0; 

signal_ number = 0; 

signal ( SIGINT, MylntHandler ); 

signal( SIGBREAK, MyBreakHandler ); 

printf ( "Press Ctrl+C or Ctrl+Break\n" ); 

for( i = 0; i < 50; i++ ) { 

printf ( "Iteration # %d\n", i ); 
delay( 500 ); /* sleep for 1/2 second */ 
if ( signal_ count > 0 ) break; 

} 

printf ( "SIGINT count %d number %d\n", 

signal_ count, signal_ number ); 

signal_ count = 0; 
signal_ number = 0; 

signal ( SIGINT, SIG_ DFL ); /* Default action */ 

signal ( SIGBREAK, SIG_ DFL ); /* Default action */ 

printf ( "Default signal handling\n" ); 
for( i = 0; i < 50; i++ ) { 

printf ( "Iteration # %d\n", i ); 

delay( 500 ); /* sleep for 1/2 second */ 

if( signal_ count > 0 ) break; /* Won't happen */ 

} 

return ( signal_ count ); 

} 

ISOC 

All, Linux, RDOS, Netware 
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signbit 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <math.h> 
int signbit ( x ); 

The signbit macro determines whether the sign of its argument value is negative. 

The argument x must be an expression of real floating type. 

The signbit macro returns a nonzero value if and only if the sign of its argument has value is 
negative. 

fpclassify, isfinite, isinf, isnan, isnormal 

♦include <math.h> 

♦include <stdio.h> 

void main( void ) 

{ 

printf ( "-4.5 %s negative\n", 

signbit! -4.5 ) ? "is" : "is not" ); 

} 

produces the following: 

-4.5 is negative 


ISOC 

MACRO 
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sin 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double sin( double x ); 

The sin function computes the sine of x (measured in radians). A large magnitude argument may yield 
a result with little or no significance. 

The sin function returns the sine value. 

acos, asin, atan, atan2, cos, tan 

((include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", sin (.5) ); 

} 

produces the following: 

0.479426 

ISOC 

Math 
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sinh 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double sinh( double x ); 

The sinh function computes the hyperbolic sine of x. A range error occurs if the magnitude of x is too 
large. 

The sinh function returns the hyperbolic sine value. When the argument is outside the permissible 
range, the matherr function is called. Unless the default matherr function is replaced, it will set the 
global variable errno to ERANGE, and print a "RANGE error" diagnostic message using the stderr 
stream. 

cosh, tanh, matherr 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", sinh(.5) ); 

} 

produces the following: 

0.521095 

ISOC 

Math 
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mbsinit, sisinit 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


#include <wchar.h> 

int mbsinit( const mbstate_ t *ps ) ; 
int sisinit ( const mbstate_ t *ps ) ; 

If ps is not a null pointer, the mbsinit function determines whether the pointed-to mbstate_ t 
object describes an initial conversion state. 

The mbsinit function returns nonzero if ps is a null pointer or if the pointed-to object describes an 
initial conversion state; otherwise, it returns zero. 

_ mbccmp,_ mbccpy,_ mbcicmp,_ mbcjistojms,_ mbc jmsto jis,_ mbclen,_ mbctohira, 
_ mbctokata^ mbctolower^ mbctombb^ mbctoupperjnblen, mbrlen, mbrtowc, 
mbsrtowcs, mbsrtowcs_ sjnbstowcs, mbstowcs_ s,mbtowc, btowc, wcrtomb, 
wcrtomb_ s.wcsrtombs, wcsrtombs_ s.wcstombs, wcstombs_ s.wctob, wctomb, 
wctomb_ s 
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mbsinit, sisinit 


♦include <stdio.h> 
♦include <wchar.h> 
♦include <mbctype.h> 
♦include <errno.h> 


const char chars[] = { 

r r 

r 

r r 
• r 

'A' , 


0x81, 

0x40, 

/* 

double-byte 

space */ 


0x82, 

0x60, 

/* 

double-byte 

A */ 


0x82, 

0xA6, 

/* 

double-byte 

Hiragana 

*/ 

0x83, 

0x42, 

/* 

double-byte 

Katakana 

*/ 

OxAl, 


/* 

single-byte 

Katakana 

punctuation */ 

0xA6, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxDF, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxEO, 
0x00 

OxAl, 

/* 

double-byte 

Kanji */ 



} ; 

void main( void ) 

{ 

int i, j, k; 

wchar_ t pwc; 

mbstate_ t pstate = { 0 } ; 

_ setmbcp( 932 ); 
j = 1; 

for( i = 0; j > 0; i += j ) { 

printf( "We are %sin an initial conversion state\n", 
mbsinit( Spstate ) ? "not " : "" ); 

j = mbrtowc( &pwc, &chars[i], MB_ CUR_ MAX, Spstate ); 
printf ( "%d bytes in character ", j ); 
if( errno == EILSEQ ) { 

printf ( " - illegal multibyte character\n" ); 

} else { 

if( j == 0 ) { 
k = 0; 

} else if ( j == 1 ) { 

k = chars[i]; 

} else if( j == 2 ) { 

k = chars[i]<<8 | chars[i+1]; 

} 

printf ( "(%^6.4x->%^6.4x)\n", k, pwc ); 

} 

} 

} 

produces the following: 


Library Functions and Macros 983 




mbsinit, sisinit 


Classification: 


Systems: 


We are in an initial 
1 bytes in character 
We are in an initial 
1 bytes in character 
We are in an initial 
1 bytes in character 
We are in an initial 

1 bytes in character 
We are in an initial 

2 bytes in character 
We are in an initial 
2 bytes in character 
We are in an initial 
2 bytes in character 
We are in an initial 
2 bytes in character 
We are in an initial 
1 bytes in character 
We are in an initial 
1 bytes in character 
We are in an initial 

1 bytes in character 
We are in an initial 

2 bytes in character 
We are in an initial 
0 bytes in character 


conversion state 
(0x0020->0x0020) 
conversion state 
(0x002e->0x002e) 
conversion state 
(0x0031->0x0031) 
conversion state 
(0x0041->0x0041) 
conversion state 
(0x8140->0x3000) 
conversion state 
(0x8260->0xff21) 
conversion state 
(0x82a6->0x3048) 
conversion state 
(0x8342->0x30a3) 
conversion state 
(0x00al->0xff61) 
conversion state 
(0x00a6->0xff66) 
conversion state 
(0x00df->0xff9f) 
conversion state 
(0xe0al->0x720d) 
conversion state 
( 0000 -> 0000 ) 


ISO C95 

sisinit is WATCOM 

mbsinit - All, Linux, RDOS, Netware 

sisinit - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 


RDOS 
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sleep 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <dos.h> 

unsigned sleep( unsigned seconds ); 

The sleep function suspends execution by the specified number of seconds. 
The sleep function always returns zero. 

delay, timer_ create,timer_ gettime,timer_ settime 
/* 

* The following program sleeps for the 

* number of seconds specified in argv[1]. 

*/ 

♦include <stdlib.h> 

♦include <dos.h> 

void main( int argc, char *argv[] ) 

{ 

unsigned seconds; 

seconds = (unsigned) strtol ( argv[l], NULL, 0 ); 
sleep( seconds ); 

} 

WATCOM 

All, Linux, RDOS, Netware 
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snprintf, _snwprintf 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


♦include <stdio.h> 

int _ snprintf( char *buf, 

size_ t count, 

const char *format, ... ); 

♦include <wchar.h> 
int _ snwprintf ( wchar_ t *buf, 
size_t count, 

const wchar_ t *format, ... ); 

The _ snprintf function is equivalent to thefprintf function, except that the argument buf 
specifies a character array into which the generated output is placed, rather than to a file. The 
maximum number of characters to store is specified by count. A null character is placed at the end of 
the generated character string if fewer than count characters were stored. The format string is described 
under the description of the print f function. 

The _ snwprintf function is a wide-character version of_ snprintf. It accepts a wide-character 
string argument for format and produces wide character output. The argument buf specifies an array of 
wide characters into which the generated output is to be written, rather than converted to multibyte 
characters and written to a stream. The maximum number of wide characters to store is specified by 
count. A null wide character is placed at the end of the generated wide character string if fewer than 
count wide characters were stored. 

The _ snprintf function returns the number of characters written into the array, not counting the 
terminating null character, or a negative value if more than count characters were requested to be 
generated. An error can occur while converting a value for output. The _ snwprintf function returns 
the number of wide characters written into the array, not counting the terminating null wide character, 
or a negative value if more than count wide characters were requested to be generated. When an error 
has occurred, errno contains a value indicating the type of error that has been detected. 

_ bprintf.cprintf, fprintf, printf, sprintf, _ vbprintf.vcprintf, vfprintf, 
vprintf, vsprintf 

♦include <stdio.h> 

/* Create temporary file names using a counter */ 

char namebuf[13]; 
int TempCount = 0; 

char *make_ temp_ name () 

{ 

_ snprintf( namebuf, 13, "ZZ%. 60 .TMP", TempCount++ ); 

return( namebuf ); 

} 

void main() 

{ 

FILE *tfl, *tf2; 
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Classification: 

Systems: 


snprintf, _snwprintf 


tfl = fopen ( make_ temp_ name ( ) , "w" ); 

tf2 = fopen ( make_ temp_ name () , "w" ); 

fputs( "temp file 1", tfl ); 

fputs( "temp file 2", tf2 ); 

fclose( tfl ); 

fclose( tf2 ) ; 


WATCOM 


snprintf - All, Linux, RDOS, Netware 
snwprintf - All, Linux 
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snprintf, snwprintf 


Synopsis: 


Safer C: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


#include <stdio.h> 
int snprintf( char *buf, 

size_ t count, 

const char *format, ... ); 

♦include <wchar.h> 
int snwprintf ( wchar_ t *buf, 
size_ t count, 

const wchar_ t *format, ... ); 

The Safer C Library extension provides the snprintf_ s function which is a safer alternative to 
snprintf This newer snprintf_ s function is recommended to be used instead of the traditional 
"unsafe" snprintf function. 

The snprintf function is equivalent to the fprintf function, except that the argument buf specifies 
a character array into which the generated output is placed, rather than to a file. A null character is 
placed at the end of the generated character string. The maximum number of characters to store, 
including a terminating null character, is specified by count. The format string is described under the 
description of the print f function. 

The snwprintf function is a wide-character version of snprintf. It accepts a wide-character 
string argument for format and produces wide character output. The argument buf specifies an array of 
wide characters into which the generated output is to be written, rather than converted to multibyte 
characters and written to a stream. The maximum number of wide characters to store, including a 
terminating null wide character, is specified by count. 

The snprint f function returns the number of characters that would have been written had count been 
sufficiently large, not counting the terminating null character, or a negative value if an encoding error 
occurred. Thus, the null-terminated output has been completely written if and only if the returned value 
is nonnegative and less than count. The snwprintf function returns the number of wide characters 
that would have been written had count been sufficiently large, not counting the terminating null wide 
character, or a negative value if an encoding error occurred. Thus, the null-terminated output has been 
completely written if and only if the returned value is nonnegative and less than count. When an error 
has occurred, errno contains a value indicating the type of error that has been detected. 

_ bprintf.cprintf, fprintf, printf, sprintf, _ vbprintf.vcprintf, vfprintf, 
vprintf, vsprintf 

♦include <stdio.h> 

♦include <stdlib.h> 

/* Format output into a buffer after determining its size */ 

void main( void ) 

{ 

int bufsize; 

char *buffer; 

bufsize = snprintf( NULL, 0, "%3d %P", 42, 42 ); 
buffer = malloc( bufsize + 1 ); 

snprintf! buffer, bufsize + 1, "%3d %P", 42, 42 ); 

free( buffer ); 

} 

ISOC 
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snprintf, snwprintf 


Systems: 


snwprintf is WATCOM 

snprintf - All, Linux, RDOS, Netware 
snwprintf - All, Linux 
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snprintf_s, snwprintf_s 


Synopsis: 


Constraints: 


Description: 


Returns: 


See Also: 


Example: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

int snprintf_ s ( char * restrict s, rsize_t n 
const char * restrict format, ... ); 
♦include <wchar.h> 

int snwprintf_ s( char * restrict s, rsize_t n, 
const wchar_ t * restrict format, ... ); 


If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and snprintf_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither ,v nor format shall be a null pointer. The n argument shall neither equal zero nor be greater than 
RSI ZE_ MAX . The number of characters (including the trailing null) required for the result to be 
written to the array pointed to by 5 shall not be greater than n. The %n specifier (modified or not by 
flags, field width, or precision) shall not appear in the string pointed to by format. Any argument to 
snprintf_ s corresponding to a%s specifier shall not be a null pointer. No encoding error shall 
occur. 

If there is a runtime-constraint violation, then if ,v is not a null pointer and n is greater than zero and less 
than RSIZE_ MAX, then thesnprintf_ s function sets s[0] to the null character. 

The snprintf_ s function is equivalent to thesnprintf function except for the explicit 
runtime-constraints listed above. 

The snprintf_ s function, unlikesprintf_ s, will truncate the result to fit within the array pointed 
to by s. 

The snwprintf_ s function is a wide-character version ofsnprintf_ s. It accepts a wide-character 
string argument for format and produces wide character output. 

The snprintf_ s function returns the number of characters that would have been written had n been 
sufficiently large, not counting the terminating null character, or a negative value if a runtime-constraint 
violation occurred. Thus, the null-terminated output has been completely written if and only if the 
returned value is nonnegative and less than n. 

The snwprintf_ s function returns the number of wide characters that would have been written had n 
been sufficiently large, not counting the terminating wide null character, or a negative value if a 
runtime-constraint violation occurred. Thus, the null-terminated output has been completely written if 
and only if the returned value is nonnegative and less than n. 

_ bprintf.cprintf, fprintf, printf, sprintf, _ vbprintf.vcprintf, vfprintf, 
vprintf, vsprintf 
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Classification: 

Systems: 


♦ define STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <stdlib.h> 

/* Format output into a buffer after determining its size */ 

void main( void ) 

{ 

int bufsize; 

char *buffer; 

bufsize = snprintf( NULL, 0, "%3d %P", 42, 42 ) + 1; 
buffer = malloc( bufsize ); 

snprintf_ s( buffer, bufsize, "%3d %P", 42, 42 ); 
free( buffer ); 

} 

TR 24731 

snprintf_ s - All, Linux, RDOS, Netware 
snwprintf_ s - All, Linux 
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sopen, _sopen, _wsopen 


Synopsis: #include <io.h> 

♦include <fcntl.h> 

♦include <sys/stat.h> 

♦include <sys/types.h> 

♦include <share.h> 

int sopen ( const char *filename, 

int access, int share, ... ); 

int _ sopen( const char *filename, 

int access, int share, ... ); 

int _ wsopen( const wchar_t ^filename, 

int access, int share, ... ); 

Description: The sopen function opens a file at the operating system level for shared access. The name of the file 

to be opened is given by filename. The file will be accessed according to the access mode specified by 
access. When the file is to be created, the optional argument must be given which establishes the future 
access permissions for the file. Additionally, the sharing mode of the file is given by the share 
argument. The optional argument is the file permissions to be used when 0_ CREAT flag is on in the 
access mode. 

The _ sopen function is identical tosopen. Use _ sopen for ANSI naming conventions. 

The _ wsopen function is identical tosopen except that it accepts a wide character string argument. 

The access mode is established by a combination of the bits defined in the <f cntl. h> header file. 

The following bits may be set: 

Mode Meaning 

0_RD0NLY permit the file to be only read. 

O JWRONLY permit the file to be only written. 

0_RDWR permit the file to be both read and written. 

0_APPEND causes each record that is written to be written at the end of the file. 

OJCREAT has no effect when the file indicated by filename already exists; otherwise, 

the file is created; 

0_TRUNC causes the file to be truncated to contain no data when the file exists; has no 

effect when the file does not exist. 

O _BINARY causes the file to be opened in binary mode which means that data will be 

transmitted to and from the file unchanged. 

OTEXT causes the file to be opened in text mode which means that carriage-return 

characters are written before any linefeed character that is written and causes 
carriage-return characters to be removed when encountered during reads. 

ONOINIIERIT indicates that this file is not to be inherited by a child process. 

0_EXCL indicates that this file is to be opened for exclusive access. If the file exists 

and 0_ CREAT was also specified then the open will fail (i.e., useO_ EXCL to 
ensure that the file does not already exist). 
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When neither 0_ TEXT norO_ BINARY are specified, the default value in the global variable_ fmode 
is used to set the file translation mode. When the program begins execution, this variable has a value of 
0_ TEXT. 

0_ CREAT must be specified when the file does not exist and it is to be written. 

When the file is to be created (0_ CREAT is specified), an additional argument must be passed which 
contains the file permissions to be used for the new file. The access permissions for the file or directory 
are specified as a combination of bits (defined in the <sys/ stat. h> header file). 

The following bits define permissions for the owner. 

Permission Meaning 

S_IRWXU Read, write, execute/search 

S_IRUSR Read permission 

S_IWUSR Write permission 

S_IXUSR Execute/search permission 

The following bits define permissions for the group. 

Permission Meaning 

S_IRWXG Read, write, execute/search 

S_IRGRP Read permission 

S_IWGRP Write permission 

S_IXGRP Execute/search permission 

The following bits define permissions for others. 

Permission Meaning 

S_IRWXO Read, write, execute/search 

S_IROTH Read permission 

S_IWOTH Write permission 

S_IXOTH Execute/search permission 

The following bits define miscellaneous permissions used by other implementations. 

Permission Meaning 

SJREAD is equivalent to S_IRUSR (read permission) 

SJWRITE is equivalent to S_IWUSR (write permission) 

S_IEXEC is equivalent to S_IXUSR (execute/search permission) 

All files are readable with DOS; however, it is a good idea to set S_ I READ when read permission is 
intended for the file. 

The sopen function applies the current file permission mask to the specified permissions (see umask). 

The shared access for the file, share , is established by a combination of bits defined in the <share . h> 
header file. The following values may be set: 
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Value Meaning 

SHjCOMPA T Set compatibility mode. 

SH_DENYRW Prevent read or write access to the file. 

SH_DENYWR Prevent write access of the file. 

SH_DENYRD Prevent read access to the file. 

SH_DENYNO Permit both read and write access to the file. 

You should consult the technical documentation for the DOS system that you are using for more 
detailed information about these sharing modes. 

Returns: If successful, sopen returns a handle for the file. When an error occurs while opening the file, -1 is 

returned. When an error has occurred, errno contains a value indicating the type of error that has 
been detected. 

Errors: When an error has occurred, errno contains a value indicating the type of error that has been detected. 

Constant Meaning 

EACCES Access denied because path specifies a directory or a volume ID, or sharing mode 

denied due to a conflicting open. 

EMFILE No more handles available (too many open files) 

ENOENT Path or file not found 

See Also: chsize, close, creat, dup, dup2, eof, exec. . fdopen, filelength, fileno, fstat, 

_ grow_ handlesisatty, lseek, open, read, setmode, stat, tell, write, umask 

Example: ((include <sys/stat.h> 

♦include <sys/types.h> 

♦include <fcntl.h> 

♦include <share.h> 

void main( void ) 

{ 

int handle; 
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Classification: 


Systems: 


sopen, _sopen, _wsopen 


/* open a file for output */ 

/* replace existing file if it exists */ 

handle = sopen( "file", 

0_ WRONLY | 0_ CREAT | 0_ TRUNC, 

SH_ DENYWR, 

S_ IRUSR | S_ IWUSR | S_ IRGRP | S_ IWGRP ); 

/* read a file which is assumed to exist */ 

handle = sopen ( "file", 0_ RDONLY, SH_ DENYWR ); 

/* append to the end of an existing file */ 

/* write a new file if file does not exist */ 

handle = sopen ( "file", 

0_ WRONLY | 0_ CREAT | 0_ APPEND, 

SH_ DENYWR, 

S_ IRUSR | S_ IWUSR | S_ IRGRP | S_ IWGRP ); 


WATCOM 

_sopen conforms to ANSI naming conventions 
sopen - All, Linux, RDOS, Netware 

_ sopen - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ wsopen - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, Linux 
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sound 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


#include <i86.h> 

void sound( unsigned frequency ); 

The sound function turns on the PC's speaker at the specified frequency. The frequency is in Hertz 
(cycles per second). The speaker can be turned off by calling the no sound function after an 
appropriate amount of time. 

The sound function has no return value. 


delay, nosound 
♦include <i86.h> 

/* 

The numbers in this table are the timer divisors 
necessary to produce the pitch indicated in the 
lowest octave that is supported by the "sound" 
function. 

To raise the pitch by N octaves, simply divide the 
number in the table by 2**N since a pitch which is 
an octave above another has double the frequency of 
the original pitch. 

The frequency obtained by these numbers is given by 
1193180 / X where X is the number obtained in the 
table. 


unsigned short Notes[] = { 


19327 , 

/* 

C 

b 



*/ 

18242 , 

/* 

C 




*/ 

17218 , 

/* 

c 

# 

( D 

b ) 

*/ 

16252 , 

/* 

D 




*/ 

15340 , 

/* 

D 

# 

( E 

b ) 

*/ 

14479 , 

/* 

E 


( F 

b ) 

*/ 

13666 , 

/* 

F 


( E 

# ) 

*/ 

12899 , 

/* 

F 

# 

( G 

b ) 

*/ 

12175 , 

/* 

G 




*/ 

11492 , 

/* 

G 

# 

( A 

b ) 

*/ 

10847 , 

/* 

A 




*/ 

10238 , 

/* 

A 

# 

( B 

b ) 

*/ 

9664 , 

/* 

B 


( c 

b ) 

*/ 

9121 , 

/* 

B 

# 



*/ 


0 

} ; 
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sound 


Classification: 

Systems: 


♦define FACTOR 1193180 
♦define OCTAVE 4 

void main() /* play the scale */ 

{ 

int i; 

for( i = 0; Notes [i]; ++i ) { 

sound( FACTOR / (Notes[i] / (1 « OCTAVE)) ); 
delay( 200 ); 
nosound(); 

} 

} 

Intel 

DOS, Windows, Win386 
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Synopsis: 


Description: 


♦include <process.h> 


int 

spawnl( 

mode. 

path. 

argO, argl. 

.., argn. 

NULL 

) ; 

int 

spawnle( 

mode. 

path. 

argO, argl. 

.., argn. 

NULL, 

envp); 

int 

spawnlp( 

mode. 

file. 

argO, argl. 

.., argn. 

NULL 

) ; 

int 

spawnlpe( 

mode. 

file. 

argO, argl. 

.., argn. 

NULL, 

envp); 

int 

spawnv( 

mode. 

path. 

argv ); 




int 

spawnve( 

mode. 

path. 

argv, envp 

) ; 



int 

spawnvp( 

mode. 

file. 

argv ); 




int 

spawnvpe( 

mode. 

file. 

argv, envp 

); 




int _ spawnl( mode, path, argO, argl. 
int _ spawnle( mode, path, argO, argl. 
int _ spawnlp( mode, file, argO, argl. 
int _ spawnlpe( mode, file, argO, argl. 
int _ spawnv ( mode, path, argv ); 
int _ spawnve( mode, path, argv, envp 
int _ spawnvp( mode, file, argv ); 
int _ spawnvpe( mode, file, argv, envp 


argn, NULL ); 
argn, NULL, envp); 
argn, NULL ); 
argn, NULL, envp); 


int 

const char 
const char 
const char 
const char 
const char 


mode; 

*path; 

*file; 

*argO, ..., *argn; 
*const argv[]; 
*const envp[]; 


/* mode for parent */ 
/* file name incl. path */ 
/* file name */ 
/* arguments */ 
/* array of arguments */ 
/* environment strings */ 


int _ 

wspawnl( 

mode, 

path. 

argO, 

argl..., 

argn, NULL 

); 


int _ 

wspawnle( 

mode. 

path. 

argO, 

argl 

argn, NULL, 

envp); 

int _ 

wspawnlp( 

mode. 

file. 

argO, 

argl..., 

argn, NULL 

); 


int _ 

wspawnlpe( 

mode. 

file. 

argO, 

argl..., 

argn, NULL, 

envp); 

int _ 

wspawnv( 

mode, 

path. 

argv ) 

r 




int _ 

wspawnve( 

mode, 

path. 

argv. 

envp ) ; 




int _ 

wspawnvp( 

mode. 

file. 

argv ) 

r 




int _ 

wspawnvpe( 

mode. 

file. 

argv. 

envp ) ; 




int 


mode; 



/* mode 

for parent 


*/ 

const wchar_ t 

*path; 



/* file 

name incl. 

path 

*/ 

const wchar_ t 

*file; 



/* file 

name 


*/ 

const wchar_ t 

*argO, 

• • • r 

*argn; 

/* arguments 


*/ 

const wchar_ t 

*const 

argv [ 

]; 

/* array of arguments 

*/ 

const wchar_ t 

*const 

envp [ 

]; 

/* environment strings 

*/ 


The spawn... functions create and execute a new child process, named by pgm. The value of mode 
determines how the program is loaded and how the invoking program will behave after the invoked 
program is initiated: 


Mode 

PWAIT 


P_NOWAIT 

P_NOWAITO 


Meaning 

The invoked program is loaded into available memory, is executed, and then 
the original program resumes execution. This option is supported under DOS, 
OS/2, Win32 and QNX. 

Causes the current program to execute concurrently with the new child 
process. This option is supported under OS/2, Win32 and QNX. 

Causes the current program to execute concurrently with the new child 
process. This option is supported under OS/2, Win32 and QNX. The wait 
and cwait functions cannot be used to obtain the exit code. 
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PjOVERLAY The invoked program replaces the original program in memory and is 

executed. No return is made to the original program. This option is supported 
under DOS (16-bit only), OS/2, Win32, and QNX. This is equivalent to 
calling the appropriate exec. . . function. 

P_DETACH Launches the child process in the background without access to the keyboard 

or console. This option is supported under only Windows NT. 

The program is located by using the following logic in sequence: 

1. An attempt is made to locate the program in the current working directory if no directory 
specification precedes the program name; otherwise, an attempt is made in the specified 
directory. 

2. If no file extension is given, an attempt is made to find the program name, in the directory 
indicated in the first point, with . COM concatenated to the end of the program name. 

3. If no file extension is given, an attempt is made to find the program name, in the directory 
indicated in the first point, with . EXE concatenated to the end of the program name. 

4. When no directory specification is given as part of the program name, the spawnlp, 
spawnlpe, spawnvp, and spawnvpe functions will repeat the preceding three steps for 
each of the directories specified by the PATH environment variable. The command 

path c:\myapps;d:\lib\applns 

indicates that the two directories 

c:\myapps 
d:\lib\applns 

are to be searched. The DOS PATH command (without any directory specification) will 
cause the current path definition to be displayed. 

An error is detected when the program cannot be found. 

Arguments are passed to the child process by supplying one or more pointers to character strings as 
arguments in the spawn... call. These character strings are concatenated with spaces inserted to 
separate the arguments to form one argument string for the child process. The length of this 
concatenated string must not exceed 128 bytes for DOS systems. 

The arguments may be passed as a list of arguments (spawnl, spawnle, spawnlp and spawnlpe) 
or as a vector of pointers (spawnv, spawnve, spawnvp, and spawnvpe). At least one argument, 
argO or argv[0], must be passed to the child process. By convention, this first argument is a pointer to 
the name of the program. 

If the arguments are passed as a list, there must be a NULL pointer to mark the end of the argument list. 
Similarly, if a pointer to an argument vector is passed, the argument vector must be terminated by a 
NULL pointer. 

The environment for the invoked program is inherited from the parent process when you use the 
spawnl, spawnlp, spawnv and spawnvp functions. The spawnle, spawnlpe, spawnve and 
spawnvpe functions allow a different environment to be passed to the child process through the envp 
argument. The argument envp is a pointer to an array of character pointers, each of which points to a 
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Returns: 


string defining an environment variable. The array is terminated with a NULL pointer. Each pointer 
locates a character string of the form 

variable=value 

that is used to define an environment variable. If the value of envp is NULL, then the child process 
inherits the environment of the parent process. 

The environment is the collection of environment variables whose values that have been defined with 
the DOS SET command or by the successful execution of the putenv function. A program may read 
these values with the getenv function. 

The following example invokes "myprog" as if myprog ARG1 ARG2 had been entered as a command 
to DOS. 

spawnl( P_ WAIT, "myprog", 

"myprog", "ARG1", "ARG2", NULL ); 

The program will be found if one of "myprog.", "myprog.com", or "myprog.exe" is found in the current 
working directory. 

The following example includes a new environment for "myprog". 

char *env_ list [ ] = { " SOURCE=MYDATA" , 

"TARGET=OUTPUT", 

" lines=65", 

NULL 

} ; 

spawnle( P_ WAIT, "myprog", 

"myprog", "ARG1", "ARG2", NULL, 
env_ list ); 

The environment for the invoked program will consist of the three environment variables SOURCE, 
TARGET and lines. 

The following example is another variation on the first example. 

char *arg_list[] = { "myprog", "ARG1", "ARG2", NULL }; 

spawnv ( P_ WAIT, "myprog", arg_ list ); 

The _ wspawn . . . functions are similar to their counterparts but operate on wide-character strings. 
When the value of mode is: 

Mode Meaning 

P_WAIT then the return value from spawn... is the exit status of the child process. 

PNOWAIT then the return value from spawn... is the process ID (or process handle under 

Win32) of the child process. To obtain the exit code for a process spawned 
with P_ NOWAIT, you must call thewait (under OS/2 or QNX) or cwait 
(under OS/2 or Win32) function specifying the process ID/handle. If the child 
process terminated normally, then the low order byte of the returned status 
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word will be set to 0, and the high order byte will contain the low order byte of 
the return code that the child process passed to the DOSEXIT function. 

PJVOWAITO then the return value from spawn... is the process ID of the child process. The 

exit code cannot be obtained for a process spawned with P_ NOWAITO. 

P_DETACH then the return value from spawn... is zero (0) if successful. 

When an error is detected while invoking the indicated program, spawn... returns -1 and errno is set 
to indicate the error. 

Errors: When an error has occurred, errno contains a value indicating the type of error that has been detected. 

Constant Meaning 

E2BIG The argument list exceeds 128 bytes, or the space required for the environment 

information exceeds 32K. 

EINVAL The mode argument is invalid. 

ENOENT Path or file not found 

ENOMEM Not enough memory is available to execute the child process. 

See Also: abort, atexit, cwait, exec . . ., exit, _ Exit,. exit.getcmd, getenv, main, putenv, 

system, wait 

Example: #include <stdio.h> 

♦include <stdlib.h> 

♦include <process.h> 

♦include <errno.h> 

♦include <string.h> 

void main() 

{ 

int process, id; 

♦ if defined!_OS2_) || defined!_NT_) 

int status, rc; 

♦endif 

process, id = spawnl( P_ NOWAIT, "child.exe", 

"child", "5", NULL ); 
if( process, id == -1 ) { 

printf ( "spawn failed - %s\n", strerror ( errno ) ); 

exit( EXIT_ FAILURE ); 

} 

printf! "Process id = %d\n", process, id ) ; 
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#if defined (_0S2_) || defined (_NT_) 

rc = cwait ( Sstatus, process_ id, WAIT_ CHILD ) ; 
if( rc == -1 ) { 

printf ( "wait failed - %s\n", strerror ( errno ) ); 

} else { 

printf ( "wait succeeded - %x\n", status ); 
switch ( status & Oxff ) { 

case 0: 

printf( "Normal termination exit code = %d\n", 
status >> 8 ); 

break; 
case 1: 

printf ( "Hard-error abortin' 1 ) ; 
break; 
case 2 : 

printf( "Trap operation\n" ); 
break; 
case 3: 

printf( "SIGTERM signal not interceptedin" ); 
break; 
default: 

printf( "Bogus return statusin" ); 


} 

#endif 

printf( "spawn completedin" ); 

} 

/* 

[child.c] 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <dos.h> 

void main( int argc, char *argv[] ) 

{ 

int delay; 

if( argc <= 1 ) 

exit( EXIT_ FAILURE ); 
delay = atoi ( argv[l] ); 
printf ( "I am a child going to sleep " 

"for %d secondsin", delay ); 
sleep( delay ); 

printf ( "I am a child awakeningin" ); 
exit( 123 ); 

} 

*/ 

Classification: WATCOM 

_spawn... conforms to ANSI naming conventions 

Systems: spawnl - DOS, Win32, OS/2 1.x (all), OS/2-32, Linux, RDOS 

spawnle - DOS, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS 
spawnlp - DOS, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS, 
spawnlpe - DOS, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS 
spawnv - DOS, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS 


Netware 
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spawnve - DOS, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS 
spawnvp - DOS, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS, Netware 
spawnvpe - DOS, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS 
_ spawnl - DOS, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS 
_ spawnle - DOS, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS 

_ spawnlp - DOS, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS, Netware 

_ spawnlpe - DOS, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS 
_ spawnv - DOS, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS 
_ spawnve - DOS, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS 

_ spawnvp - DOS, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS, Netware 

_ spawnvpe - DOS, Win32, OS/2 l.x(all), OS/2-32, Linux, RDOS 
_ wspawnl - DOS, Win32, OS/2 l.x(all), OS/2-32 
_ wspawnle - DOS, Win32, OS/2 l.x(all), OS/2-32 

_ wspawnlp - DOS, Win32, OS/2 l.x(all), OS/2-32 

_ wspawnlpe - DOS, Win32, OS/2 l.x(all), OS/2-32 
_ wspawnv - DOS, Win32, OS/2 l.x(all), OS/2-32 
_ wspawnve - DOS, Win32, OS/2 l.x(all), OS/2-32 

_ wspawnvp - DOS, Win32, OS/2 1.x(all), OS/2-32 

_ wspawnvpe - DOS, Win32, OS/2 1.x(all), OS/2-32 
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splitpath, _wsplitpath 


Synopsis: #include <stdlib.h> 

void _ splitpath( const char *path, 

char *drive, 
char *dir, 
char *fname, 
char *ext ); 

void _wsplitpath( const wchar_ t *path, 

wchar_ t *drive, 
wchar_ t *dir, 
wchar_ t *fname, 
wchar_ t *ext ); 

Description: The _ splitpath function splits up a full pathname into four components consisting of a drive letter, 
directory path, file name and file name extension. The argument path points to a buffer containing the 
full pathname to be split up. 

The _ wsplitpath function is a wide-character version of_ splitpath that operates with 
wide-character strings. 

The maximum size required for each buffer is specified by the manifest constants _ MAX_ PATH, 

_ MAX_ DRIVE (or. MAX_ VOLUME for Netware applications)^ MAX_ DIR^ MAX_ FNAME, and 
_ MAX_ EXT which are defined incstdlib . h> . 

drive The drive argument points to a buffer that will be filled in with the drive letter (e.g.. A, B, 

C, etc.) followed by a colon if a drive is specified in the full pathname (filled in by 
_ splitpath). 

For Netware applications, the drive argument points to a buffer that will be filled in with 
the volume identifier (e.g., WNAME_SPACE) if a volume is specified in the full 
pathname (filled in by _ splitpath ). 

dir The dir argument points to a buffer that will be filled in with the pathname including the 

trailing slash. Either forward slashes (/) or backslashes (\) may be used. 

fname Th & frame argument points to a buffer that will be filled in with the base name of the file 

without any extension (suffix) if a file name is specified in the full pathname (filled in by 
_ splitpath). 

ext The ext argument points to a buffer that will be filled in with the filename extension 

(suffix) including the leading period if an extension is specified in the full pathname 
(filled in by _ splitpath ). 

The arguments drive, dir, fname and ext will not be filled in if they are NULL pointers. 

For each component of the full pathname that is not present, its corresponding buffer will be set to an 
empty string. 

Returns: The_ splitpath function returns no value. 

See Also: _ fullpath^_ makepath,_ splitpath2 
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Example: #include <stdio.h> 

♦include <stdlib.h> 

void main() 

{ 

char full_ path [ _ MAX_ PATH ] ; 
char drive [ _ MAX_ DRIVE ] ; 
char dir [ _ MAX_ DIR ]; 
char fname [ _ MAX_ FNAME ] ; 
char ext [ _ MAX_ EXT ] ; 

_ makepath (full_ path, "c" , "watcomc\\h\\" , "stdio" , "h" ) ; 
printf( "Full path is: %s\n\n", full_ path ); 

_ splitpath ( full_ path, drive, dir, fname, ext ); 

printf ( "Components after _ splitpath\n" ) ; 

printf( "drive: %s\n", drive ); 

printf( "dir: %s\n", dir ); 

printf( "fname: %s\n", fname ); 

printf( "ext: %s\n", ext ); 

} 

produces the following: 

Full path is: c:watcomc\h\stdio.h 

Components after _ splitpath 

drive: c: 

dir: watcomc\h\ 

fname: stdio 

ext: .h 

Note the use of two adjacent backslash characters (\) within character-string constants to signify a single 
backslash. 

Classification: WATCOM 

Systems: _ splitpath - All, Linux, RDOS, Netware 

_ wsplitpath - All, Linux 
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splitpath2, _wsplitpath2 


Synopsis: #include <stdlib.h> 

void _ splitpath2( const char *inp, 

char *outp, 
char **drive, 
char **dir, 
char **fname, 
char **ext ); 

void _ wsplitpath2 ( const wchar_ t *inp, 

wchar_ t *outp, 
wchar_ t **drive, 
wchar_ t **dir, 
wchar_ t **fname, 
wchar_ t **ext ); 

Description: The _ splitpath2 function splits up a full pathname into four components consisting of a drive 
letter, directory path, file name and file name extension. 

inp The argument inp points to a buffer containing the full pathname to be split up. 

outp The argument outp points to a buffer that will contain all the components of the path, 

each separated by a null character. The maximum size required for this buffer is specified 
by the manifest constant _ MAX_ PATH2 which is defined ircstdlib. h> . 

drive The drive argument is the location that is to contain the pointer to the drive letter (e.g.. A, 

B, C, etc. ) followed by a colon if a drive is specified in the full pathname (filled in by 
_ splitpath2 ). 

dir The dir argument is the location that is to contain the pointer to the directory path 

including the trailing slash if a directory path is specified in the full pathname (filled in by 
_ splitpath2 ). Either forward slashes (/) or backslashes (\) may be used. 

fname Th q fname argument is the location that is to contain the pointer to the base name of the 

file without any extension (suffix) if a file name is specified in the full pathname (filled in 
by _ splitpath2 ). 

ext The ext argument is the location that is to contain the pointer to the filename extension 

(suffix) including the leading period if an extension is specified in the full pathname 
(filled in by _ splitpath2 ). 

The arguments drive, dir, fname and ext will not be filled in if they are NULL pointers. 

Lor each component of the full pathname that is not present, its corresponding pointer will be set to 
point at a NULL string f \0'). 

This function reduces the amount of memory space required when compared to the splitpath 
function. 

The _ wsplitpath2 function is a wide-character version of_ splitpath2 that operates with 
wide-character strings. 

Returns: The _ splitpath2 function returns no value. 

See Also: _ fullpath^_ makepath^_ splitpath 
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Example: #include <stdio.h> 

♦include <stdlib.h> 

void main() 

{ 

char full_ path [ _ MAX_ PATH ] ; 

char tmp_ path [ _ MAX_ PATH2 ] ; 

char *drive; 

char *dir; 

char *fname; 

char *ext; 

_ makepath (full_ path, "c" , "watcomcWh" , "stdio" , "h" ) ; 
printf( "Full path is: %s\n\n", full_ path ); 

_ splitpath2 ( full_ path, tmp_ path, 

Sdrive, &dir, Sfname, &ext ); 
printf ( "Components after _ splitpath2\n" ); 
printf ( "drive: %s\n", drive ); 

printf( "dir: %s\n", dir ); 

printf( "fname: %s\n", fname ); 

printf( "ext: %s\n", ext ); 

} 

produces the following: 

Full path is: c:watcomc\h\stdio.h 

Components after _ splitpath2 

drive: c: 

dir: watcomc\h\ 

fname: stdio 

ext: .h 

Note the use of two adjacent backslash characters (\) within character-string constants to signify a single 
backslash. 

Classification: WATCOM 

Systems: _ splitpath2 - All, Linux, RDOS 

_ wsplitpath2 - All, Linux 


Library Functions and Macros 1007 




sprintf, swprintf 


Synopsis: 


Safer C: 


Description: 


Returns: 


See Also: 


Example: 


♦include <stdio.h> 

int sprintf( char *buf, const char *format, ... ); 

♦include <wchar.h> 
int swprintf( wchar_ t *buf, 
size_ t n, 

const wchar_ t * format, ... ); 

The Safer C Library extension provides the sprintf_ s function which is a safer alternative to 
sprintf This newer sprint f_ s function is recommended to be used instead of the traditional 
"unsafe" sprintf function. 

The sprintf function is equivalent to the fprintf function, except that the argument buf specifies a 
character array into which the generated output is placed, rather than to a file. A null character is placed 
at the end of the generated character string. The format string is described under the description of the 
printf function. 

The swprintf function is a wide-character version of sprintf. It accepts a wide-character string 
argument for format and produces wide character output. The argument buf specifies an array of wide 
characters into which the generated output is to be written, rather than converted to multibyte characters 
and written to a stream. The maximum number of wide characters to write, including a terminating null 
wide character, is specified by n. 

The sprintf function returns the number of characters written into the array, not counting the 
terminating null character. An error can occur while converting a value for output. The swprintf 
function returns the number of wide characters written into the array, not counting the terminating null 
wide character, or a negative value if n or more wide characters were requested to be generated. When 
an error has occurred, errno contains a value indicating the type of error that has been detected. 

_ bprintf,cprintf, fprintf, printf, _ vbprintf,vcprintf, vfprintf, vprintf, 
vsprintf 

♦include <stdio.h> 

/* Create temporary file names using a counter */ 

char namebuf[13]; 
int TempCount = 0; 

char *make_ temp_ name ( void ) 

{ 

sprintf( namebuf, "zz%. 60 .tmp", TempCount++ ); 
return( namebuf ); 

} 

void main( void ) 

{ 

FILE *tfl, *tf2; 
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Classification: 


Systems: 


tfl = fopen ( make_ temp_ name () , "w" ); 

tf2 = fopen ( make_ temp_ name () , "w" ); 

fputs( "temp file 1", tfl ); 

fputs( "temp file 2", tf2 ); 

fclose( tfl ); 

fclose( tf2 ) ; 


ISOC 

swprintf is ISO C95 

sprintf - All, Linux, RDOS, Netware 
swprintf - All, Linux 
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sprintf_s, swprintf_s 


Synopsis: 


Constraints: 


Description: 


Returns: 


See Also: 


Example: 


♦ define_ STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

int sprintf_ s ( char * restrict s, rsize_ t n 
const char * restrict format, ... ) ; 
♦include <wchar.h> 

int swprintf_ s ( char * restrict s, rsize_ t n, 
const wchar_ t * restrict format, ... ); 


If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and sprintf_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither ,v nor format shall be a null pointer. The n argument shall neither equal zero nor be greater than 
RSI ZE_ MAX . The number of characters (including the trailing null) required for the result to be 
written to the array pointed to by 5 shall not be greater than n. The %n specifier (modified or not by 
flags, field width, or precision) shall not appear in the string pointed to by format. Any argument to 
sprintf_ s corresponding to a%s specifier shall not be a null pointer. No encoding error shall occur. 

If there is a runtime-constraint violation, then if ,v is not a null pointer and n is greater than zero and less 
than RSIZE_ MAX, then thesprintf_ s function sets s[0] to the null character. 

The sprint f_ s function is equivalent to thesprintf function except for the explicit 
runtime-constraints listed above. 

The sprint f_ s function, unlike snprintf_ s, treats a result too big for the array pointed to by s as 
a runtime-constraint violation. 

The swprintf_ s function is a wide-character version ofsprintf_ s. It accepts a wide-character 
string argument for format and produces wide character output. 

If no runtime-constraint violation occurred, the sprint f_ s function returns the number of characters 
written in the array, not counting the terminating null character. If an encoding error occurred, 
sprint f_ s returns a negative value. If any other runtime-constraint violation occurred, sprint f_ s 
returns zero. 

If no runtime-constraint violation occurred, the swprintf_ s function returns the number of wide 
characters written in the array, not counting the terminating null wide character. If an encoding error 
occurred or if n or more wide characters are requested to be written, swprint f_ s returns a negative 
value. If any other runtime-constraint violation occurred, swprintf_ s returns zero. 

_ bprintf.cprintf, fprintf, printf, sprintf, _ vbprintf.vcprintf, vfprintf, 
vprintf, vsprintf 

♦ define_ STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

/* Create temporary file names using a counter */ 

char namebuf[13]; 
int TempCount = 0; 
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sprintf_s, swprintf_s 


Classification: 

Systems: 


char *make_ temp_ name ( void ) 

{ 

sprintf_ s ( namebuf, sizeof( namebuf ) , 
"zz%. 60 .tmp" , TempCount++ ); 
return( namebuf ) ; 

} 

void main( void ) 

{ 

FILE *tfl, *tf2; 

tfl = f open ( make_ temp_ name () , "w" ); 

tf 2 = f open ( make_ temp_ name () , "w" ); 

fputs( "temp file 1 ", tfl ); 

fputs( "temp file 2 ", tf 2 ); 

fclose( tfl ); 

fclose( tf 2 ) ; 

} 

TR 24731 

sprintf_ s - All, Linux, RDOS, Netware 
swprintf_ s - All, Linux 
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sqrt 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double sqrt( double x ) ; 

The sqrt function computes the non-negative square root of x. A domain error occurs if the argument 
is negative. 

The sqrt function returns the value of the square root. When the argument is outside the permissible 
range, the matherr function is called. Unless the default matherr function is replaced, it will set the 
global variable errno to EDOM, and print a "DOMAIN error" diagnostic message using the stderr 
stream. 

exp, log, pow, matherr 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", sqrt(.5) ); 

} 

produces the following: 

0.707107 

ISOC 

Math 
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srand 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <stdlib.h> 

void srand( unsigned int seed ); 

The srand function uses the argument seed to start a new sequence of pseudo-random integers to be 
returned by subsequent calls to rand. A particular sequence of pseudo-random integers can be 
repeated by calling srand with the same seed value. The default sequence of pseudo-random integers 
is selected with a seed value of 1. 

The srand function returns no value. 

rand 

♦include <stdio.h> 

♦include <stdlib.h> 

void main() 

{ 

int i; 

srand( 982 ); 

for( i = 1; i < 10; ++i ) { 

printf ( "%d\n", rand() ); 

} 

srand( 982 ); /* start sequence over again */ 

for( i = 1; i < 10; ++i ) { 

printf ( "%d\n", rand() ); 

} 

} 

ISOC 

All, Linux, RDOS, Netware 
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sscanf, swscanf 


Synopsis: 

Safer C: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <stdio.h> 

int sscanf ( const char *in_ string, 

const char *format, ... ); 

♦include <wchar.h> 

int swscanf( const wchar_ t *in_ string, 

const wchar_ t *format, ... ); 

The Safer C Library extension provides the sscanf_ s function which is a safer alternative to 
sscanf This newer sscanf_ s function is recommended to be used instead of the traditional "unsafe" 
sscanf function. 

The sscanf function scans input from the character string in_string under control of the argument 
format. Following the format string is the list of addresses of items to receive values. 

The format string is described under the description of the scanf function. 

The swscanf function is identical to sscanf except that it accepts a wide-character string argument 
for format and the input string in_string consists of wide characters. 

The sscanf function returns EOF if the end of the input string was reached before any input 
conversion. Otherwise, the number of input arguments for which values were successfully scanned and 
stored is returned. 


cscanf, fscanf, scanf, vcscanf, vfscanf, vscanf, vsscanf 
♦include <stdio.h> 

/* Scan a date in the form "Saturday April 18 1987" 

void main( void ) 

{ 


int day, year; 

char weekday[10], month[10]; 


} 


sscanf( 

printf( 


"Friday August 0014 1987", 

”2-o 2-o 2-H 2-H” 

oo oo o LI oU f 


weekday, month, 
"%s %s %d %d\n", 
weekday, month. 


&day, Syear 
day, year ); 


*/ 


produces the following: 
Friday August 14 1987 


ISO C90 

swscanf is ISO C95 


sscanf - All, Linux, RDOS, Netware 
swscanf - All, Linux 
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sscanf_s, swscanf_s 


Synopsis: 


Constraints: 


Description: 


Returns: 

See Also: 
Example: 


♦ define_ STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

int sscanf_ s ( const char * restrict s, 

const char * restrict format, ... ); 

♦include <wchar.h> 

int swscanf_ s( const wchar_ t * restrict s, 

const wchar_ t * restrict format, ... ); 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and sscanf_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither ,v not format shall be a null pointer. Any argument indirected through in order to store 
converted input shall not be a null pointer. 

If there is a runtime-constraint violation, the sscanf_ s function does not attempt to perform further 
input, and it is unspecified to what extent sscanf_ s performed input before discovering the 
runtime-constraint violation. 


The sscanf_ s function is equivalent tof scanf_ s, except that input is obtained from a string 
(specified by the argument ,v) rather than from a stream. Reaching the end of the string is equivalent to 
encountering end-of-file for the f scanf_ s function. If copying takes place between objects that 
overlap, the objects take on unspecified values. 

The swscanf_ s function is identical tosscanf_ s except that it accepts wide-character string 
arguments for ,v and format. 

The sscanf_ s function returnsEOF if an input failure occurred before any conversion or if there was 
a runtime-constraint violation. Otherwise, the sscanf_ s function returns the number of input items 
successfully assigned, which can be fewer than provided for, or even zero. 

cscanf, fscanf, scanf, sscanf, vcscanf, vfscanf, vscanf, vsscanf 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 


void main( void ) 

{ 

int day, year; 

char weekday[10], month[10]; 


} 


sscanf_ s ( "Friday August 0013 2004", 

ii o. n 2-0 2-H 2-H” 

oo oo o LI oU r 

weekday, sizeof ( weekday ), 
month, sizeof ( month ), 

&day, Syear ); 
printf_ s( "%s %s %d %d\n", 

weekday, month, day, year ); 


produces the following: 
Friday August 13 2004 
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sscanf_s, swscanf_s 


Classification: 

Systems: 


TR 24731 

sscanf_ s - All, Linux, RDOS, 
swscanf_ s - All, Linux 


Netware 
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stackavail, _stackavail 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <malloc.h> 

size_ t stackavail ( void ) ; 

size_ t _ stackavail( void ) ; 

The stackavail function returns the number of bytes currently available in the stack. This value is 
usually used to determine an appropriate amount to allocate using alloca. 

The _ stackavail function is identical tostackavail. Use _ stackavail for ANSI naming 
conventions. 

The stackavail function returns the number of bytes currently available in the stack. 

alloca, calloc Functions, malloc Functions 

♦include <stdio.h> 

♦include <string.h> 

♦include <malloc.h> 

♦include <fcntl.h> 

♦include <io.h> 

long char_ count( FILE *fp ) 

{ 

char *buffer; 

size_ t bufsiz; 
long count; 

/* allocate half of stack for temp buffer */ 
bufsiz = stackavail!) >> 1; 
buffer = (char *) alloca ( bufsiz ); 
setvbuf( fp, buffer, _ IOFBF, bufsiz ); 
count = OL; 

while! fgetc( fp ) != EOF ) ++count; 

fclose( fp ); 
return( count ) ; 

1 

void main( void ) 

{ 

FILE *fp; 

fp = fopen( "file", "rb" ); 
if ( fp != NULL ) { 

setmode( fileno ( fp ), 0_ BINARY ); 
printf ( "File contains %lu characters\n", 
char_ count( fp ) ); 

fclose ( fp ); 

} 

} 

WATCOM 

_stackavail conforms to ANSI naming conventions 

stackavail - All, Linux, RDOS, Netware 
_ stackavail - All, Linux, RDOS, Netware 


Library Functions and Macros 1017 




stat, _stat, _stati64, _wstat, _wstati64, Istat 

Synopsis: #include <sys/stat.h> 

int stat( const char *path, struct stat *buf ) ; 

int _ stat ( const char *path, struct _ stat *buf ) ; 

int _ stati64( const char *path, struct _ stati64 *buf ); 

int _ wstat ( const wchar_ t *path, struct _ stat *buf ) ; 

int _wstati64( const wchar_ t *path, struct _ stati64 *buf ); 

int Istat( const char *path, struct stat *buf ) ; 

Description: The stat functions obtain information about the file or directory referenced in path. This information 
is placed in the structure located at the address indicated by buf. 

The file <sys/stat. h> contains definitions for the structure stat. 

Field Type/Meaning 

st_dev (dev_t) the disk drive the file resides on 

st_ino (ino_t) this inode’s number (not used for DOS) 

st_mode (unsigned short ) file mode 

st_nlink (short ) number of hard links 

st_uid (unsigned long) user-id (always ’root’ for DOS) 

st_gid (short) group-id (always ’root’ for DOS) 

st_rdev (dev_t) this should be the device type but it is the same as st_dev for the time being 

st_size (off_t) total file size 

st_atime (time_t) this should be the file "last accessed" time if the file system supports it 

stjntime (time_t) the file "last modified" time 

st_ctime (time_t) this should be the file "last status change" time if the file system supports it 

The following fields are Netware only: 
st_btime (time_t) the file "last archived" time 

st_attr (unsigned long) the file’s attributes 

st_archivedID (unsigned long) the user/object ID that last archived file 
st_updatedID (unsigned long) the user/object ID that last updated file 
st_inheritedRightsMask (unsigned short) the inherited rights mask 
st_originatingNameSpace (unsigned char) the originating name space 
The structure _ stati64 differs fronts tat in the following way: 
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stat, _stat, _stati64, _wstat, _wstati64, Istat 


st_size (_int64) total file size (as a 64-bit value) 

At least the following macros are defined in the <sys/stat. h> header file. 

Macro Meaning 

SJSFIFO(m) Test for FIFO. 

S_ISCHR(m) Test for character special file. 

S_ISDIR(m) Test for directory file. 

S_ISBLK(m) Test for block special file. 

S_ISREG(m) Test for regular file. 

The value m supplied to the macros is the value of the st_ mode field of astat structure. The macro 
evaluates to a non-zero value if the test is true and zero if the test is false. 

The following bits are encoded within the st_ mode field of astat structure. 

Mask Owner Permissions 

S_IRWXU Read, write, search (if a directory), or execute (otherwise) 

S_IRUSR Read permission bit 

S_IWUSR Write permission bit 

S_IXUSR Search/execute permission bit 

S_IREAD == S_ IRUSR (for Microsoft compatibility) 

S_IWRITE == S_ I WUSR (for Microsoft compatibility) 

S_IEXEC == S_ IXUSR (for Microsoft compatibility) 

S_ IRWXU is the bitwise inclusive OR ofS_ IRUSR,S_ IWUSR, andS_ IXUSR. 

Mask Group Permissions (same as owner’s on DOS, OS/2 or Windows) 

S_IRWXG Read, write, search (if a directory), or execute (otherwise) 

S_IRGRP Read permission bit 

S_IWGRP Write permission bit 

S_IXGRP Search/execute permission bit 

S_ IRWXG is the bitwise inclusive OR ofS_ IRGRP,S_ IWGRP, andS_ IXGRP. 

Mask Other Permissions (same as owner’s on DOS, OS/2 or Windows) 

S_IRWXO Read, write, search (if a directory), or execute (otherwise) 

S_IROTH Read permission bit 

S_IWOTH Write permission bit 

S_IXOTH Search/execute permission bit 

S_ IRWXO is the bitwise inclusive OR ofS_ IROTH,S_ IWOTH, andS_ IXOTH. 
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stat, _stat, 


Returns: 

Errors: 

See Also: 
Example: 


Classification: 


Systems: 


stati64, _wstat, _wstati64, Istat 


Mask Meaning 

S_ISUID (Not supported by DOS, OS/2 or Windows) Set user ID on execution. The 

process’s effective user ID shall be set to that of the owner of the file when the file 
is run as a program. On a regular file, this bit should be cleared on any write. 
S_ISGID (Not supported by DOS, OS/2 or Windows) Set group ID on execution. Set 

effective group ID on the process to the file’s group when the file is run as a 
program. On a regular file, this bit should be cleared on any write. 

The _ stat function is identical tostat. Use _ stat for ANSI naming conventions. 

The _ stati64,_ wstat, and_ wstati64 functions differ fromstat in the type of structure that 
they are asked to fill in. The _ wstat and_ wstati64 functions deal with wide character strings. 
The differences in the structures are described above. The Istat function is identical to stat on 
non-UNIX platforms. 

All forms of the stat function return zero when the information is successfully obtained. Otherwise, 

-1 is returned. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
EACCES Search permission is denied for a component of path. 

f stat 


♦include <stdio.h> 
♦include <sys/stat.h> 

void main() 

{ 

struct stat but; 


} 


if( stat( "file", &buf 
printf ( "File size 

} 


!= -1 ) 1 

%d\n", buf.st_size ); 


POSIX 

_stat conforms to ANSI naming conventions 

_stati64 is WATCOM 

_wstat is WATCOM 

_wstati64 is WATCOM 

Istat is POSIX 


stat - All, Linux, RDOS, Netware 

_ stat - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ stati64 - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
_ wstat - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
_wstati64 - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
Istat - All, Linux, RDOS, Netware 
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status87 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <float.h> 

unsigned int _ status87 ( void ); 

The _ status87 function returns the floating-point status word which is used to record the status of 
8087/80287/80387/80486 floating-point operations. 

The _ status8 7 function returns the floating-point status word which is used to record the status of 
8087/80287/80387/80486 floating-point operations. The description of this status is found in the 
<float.h> header file. 

_ clear87,_ control87,_ controlfp,_ finite^ fpreset 

♦include <stdio.h> 

♦include <float.h> 

♦ define TEST_ FPU(x,y) printf ( "\t%s " y "\n", \ 

((fp_ status & x) ? " " : "No") ) 


void main() 

{ 

unsigned int fp_ status; 
fp_ status = _ status87 () ; 
printf( "80x87 status\n" ); 

TEST_ FPU ( SW_ INVALID, "invalid operation" ); 
TEST_ FPU ( SW_ DENORMAL, "denormalized operand" ); 
TEST_ FPU ( SW_ ZERODIVIDE, "divide by zero" ); 
TEST_ FPU ( SW_ OVERFLOW, "overflow" ); 

TEST_ FPU ( SW_ UNDERFLOW, "underflow" ); 

TEST_ FPU( SW_ INEXACT, "inexact result" ); 

} 

Intel 

Math 
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strcasecmp 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <strings.h> 

int strcasecmp( const char *sl, const char *s2 ); 

The strcasecmp function compares, with case insensitivity, the string pointed to by si to the string 
pointed to by s2. All uppercase characters from si and s2 are mapped to lowercase for the purposes of 
doing the comparison. 

The strcasecmp function is identical to the stricmp function. 

The strcasecmp function returns an integer less than, equal to, or greater than zero, indicating that 
the string pointed to by si is, ignoring case, less than, equal to, or greater than the string pointed to by 
s2. 

strcmp, strcmpi, stricmp, strncmp, strnicmp, strncasecmp 

♦include <stdio.h> 

♦include <strings.h> 

int main( void ) 

{ 


printf( 

"%d\n", strcasecmp! 

"AbCDEF", 

"abcdef" ) 

) ; 

printf( 

"%d\n", strcasecmp! 

"abcdef", 

"ABC" ) 

) ; 

printf( 

"%d\n", strcasecmp! 

"abc", 

"ABCdef" ) 

) ; 

printf( 

"%d\n", strcasecmp! 

"Abcdef", 

"mnopqr" ) 

) ; 

printf( 

"%d\n", strcasecmp! 

"Mnopqr", 

"abcdef" ) 

); 


return( 0 ); 

} 

produces the following: 
0 

100 

-100 

-12 

12 


POSIX 

All, Linux, RDOS, Netware 
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Synopsis: 


Safer C: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


strcat, Jstrcat, wcscat, _mbscat, Jmbscat 


#include <string.h> 

char *strcat( char *dst, const char *src ) ; 

char_far *_ fstrcat ( char_far *dst, 

const char_far *src ) ; 

#include <wchar.h> 

wchar_ t *wcscat( wchar_ t *dst, const wchar_ t *src ); 

♦include <mbstring.h> 

unsigned char *_ mbscat( unsigned char *dst, 

const unsigned char *src ); 

unsigned char_far *_ fmbscat ( unsigned char_far *dst, 

const unsigned char _ far *src ); 

The Safer C Library extension provides the strcat_ s function which is a safer alternative to 
strcat This newer strcat_ s function is recommended to be used instead of the traditional "unsafe" 
strcat function. 

The strcat function appends a copy of the string pointed to by src (including the terminating null 
character) to the end of the string pointed to by dst. The first character of src overwrites the null 
character at the end of dst. 

The _ fstrcat function is a data model independent form of the strcat function. It accepts far pointer 
arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The wcscat function is a wide-character version of strcat that operates with wide-character strings. 

The _ mbscat function is a multibyte character version ofstrcat that operates with multibyte 
character strings. 

The value of dst is returned. 

strncat, strcat_ s,strncat_ s 

♦include <stdio.h> 

♦include <string.h> 

void main() 

{ 

char buffer[80]; 

strcpy( buffer, "Hello " ); 
strcat ( buffer, "world" ); 
printf ( "%s\n", buffer ); 

} 

produces the following: 

Hello world 
ISOC 

_fstrcat is WATCOM 
_mbscat is WATCOM 
_fmbscat is WATCOM 

strcat - All, Linux, RDOS, Netware 
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strcat, Jstrcat, wcscat, _mbscat, Jmbscat 


_ fstrcat - All, Linux, RDOS 
wcscat - All, Linux 

_ mbscat - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
_ fmbscat - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 


RDOS 

RDOS 
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strcat_s, wcscat_s 


Synopsis: 


Constraints: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <string.h> 

errno_ t strcat_ s ( char * restrict si, 

rsize_ t slmax, 

const char * restrict s2 ); 

♦include <wchar.h> 

errno_ t wcscat_ s( wchar_ t * restrict si, 

rsize_ t slmax, 

const wchar_ t * restrict s2 ); 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and strcat_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Let m denote the value slmax - strnlen_s(sl, slmax ) upon entry to strcat_ s. Neither si nor s2 shall 
be a null pointer, si max shall not be greater than RSIZE_ MAX. slmax shall not equal zero, m shall 
not equal zero, m shall be greater than strnlen_s(s2, m). Copying shall not take place between objects 
that overlap. 

If there is a runtime-constraint violation, then if si is not a null pointer and slmax is greater than zero 
and not greater than RSIZE_ MAX, thenstrcat_ s sets sl[0] to the null character. 

The strcat_ s function appends a copy of the string pointed to by s2 (including the terminating null 
character) to the end of the string pointed to by si. The initial character from s2 overwrites the null 
character at the end of si. All elements following the terminating null character (if any) written by 
strcat_ s in the array of slmax characters pointed to by si take unspecified values when strcat_ s 
returns. 

The wcscat_ s function is a wide-character version ofstrcat_ s that operates with wide-character 
strings. 

The strcat_ s function returns zero if there was no runtime-constraint violation. Otherwise, a 
non-zero value is returned. 

strcat, strncat, strncat_ s 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <string.h> 

void main( void ) 

{ 

char buffer[80]; 

strcpy_ s ( buffer, sizeof( buffer ), "Hello " ); 

strcat_ s ( buffer, sizeof( buffer ), "world" ); 

printf( "%s\n", buffer ); 

} 

produces the following: 

Hello world 
TR 24731 
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strcat_s, wcscat_s 


Systems: 


strcat_ s - All, Linux, RDOS, Netware 
wcscat_ s - All, Linux 
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Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


strchr, Jstrchr, wcschr, _mbschr, Jmbschr 


#include <string.h> 

char *strchr( const char *s, int c ); 

char_far *_ fstrchr( const char_far *s, int c ) ; 

♦include <wchar.h> 

wchar_ t *wcschr( const wchar_ t *s, wint_ t c ); 

♦include <mbstring.h> 

unsigned char *_ mbschr( const unsigned char *s, 

unsigned int c ); 

unsigned char_far *_ fmbschr ( 

const unsigned char _ far *s, 

unsigned int c ) ; 

The strchr function locates the first occurrence of c (converted to a char) in the string pointed to by s. 
The terminating null character is considered to be part of the string. 

The _ f strchr function is a data model independent form of the strchr function. It accepts far pointer 
arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The wcschr function is a wide-character version of strchr that operates with wide-character strings. 

The _ mbschr function is a multibyte character version ofstrchr that operates with multibyte 
character strings. 

The strchr function returns a pointer to the located character, or NULL if the character does not occur 
in the string. 

memchr, strcspn, strrchr, strspn, strstr, strtok 

♦include <stdio.h> 

♦include <string.h> 

void main() 

{ 

char buffer [80]; 
char *where; 

strcpy( buffer, "video x-rays" ); 
where = strchr( buffer, ' x' ); 
if( where == NULL ) { 

printf ( "'x' not foundin' 1 ); 

} 

} 

ISOC 

_fstrchr is WATCOM 
_mbschr is WATCOM 
_fmbschr is WATCOM 

strchr - All, Linux, RDOS, Netware 
_ fstrchr - All, Linux, RDOS 
wcschr - All, Linux 

_ mbschr - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ fmbschr - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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strcmp, Jstrcmp, wcscmp, _mbscmp, Jmbscmp 


Synopsis: #include <string.h> 

int strcmp( const char *sl, const char *s2 ); 

int _ fstrcmp( const char_far *sl, 

const char _ far *s2 ); 

♦include <wchar.h> 

int wcscmp ( const wchar_ t *sl, const wchar_ t *s2 ); 

♦include <mbstring.h> 

int _ mbscmp( const unsigned char *sl, 
const unsigned char *s2 ) ; 

int _ fmbscmp ( const unsigned char_far *sl, 

const unsigned char_far *s2 ) ; 

Description: The strcmp function compares the string pointed to by si to the string pointed to by s2. 

The _ f strcmp function is a data model independent form of the strcmp function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The wcscmp function is a wide-character version of strcmp that operates with wide-character strings. 

The _ mbscmp function is a multibyte character version ofstrcmp that operates with multibyte 
character strings. 

Returns: The strcmp function returns an integer less than, equal to, or greater than zero, indicating that the 

string pointed to by si is less than, equal to, or greater than the string pointed to by s2. 

See Also: strcmpi, stricmp, strncmp, strnicmp 

Example: ♦include <stdio.h> 

♦include <string.h> 

void main() 

{ 

printf( "%d\n", strcmp( "abcdef", "abcdef" ) ); 

printf( "%d\n", strcmp( "abcdef", "abc" ) ); 

printf( "%d\n", strcmp( "abc", "abcdef" ) ); 

printf( "%d\n", strcmp( "abcdef", "mnopqr" ) ); 

printf( "%d\n", strcmp( "mnopqr", "abcdef" ) ); 

} 

produces the following: 

0 

1 

-1 

-1 

1 

Classification: ISO C 

_fstrcmp is WATCOM 
_mbscmp is WATCOM 
_fmbscmp is WATCOM 

Systems: strcmp - All, Linux, RDOS, Netware 

_ fstrcmp - All, Linux, RDOS 
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strcmp, Jstrcmp, wcscmp, _mbscmp, Jmbscmp 


wcscmp - All, Linux 

_ mbscmp - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS 
_ fmbscmp - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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strcmpi, wcscmpi 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <string.h> 

int strcmpi( const char *sl, const char *s2 ); 

int wcscmpi ( const wchar_ t *sl, const wchar_ t *s2 ); 

The strcmpi function compares, with case insensitivity, the string pointed to by si to the string 
pointed to by s2. All uppercase characters from si and s2 are mapped to lowercase for the purposes of 
doing the comparison. The strcmpi function is identical to the stricmp function. 

The wcscmpi function is a wide-character version of strcmpi that operates with wide-character 
strings. 

The strcmpi function returns an integer less than, equal to, or greater than zero, indicating that the 
string pointed to by si is less than, equal to, or greater than the string pointed to by s2. 

strcmp, stricmp, strncmp, strnicmp 

♦include <stdio.h> 

♦include <string.h> 

void main() 

{ 


printf( 

"%d\n", strcmpi( 

"AbCDEF", 

"abcdef" ) 

) ; 

printf( 

"%d\n", strcmpi! 

"abcdef", 

"ABC" ) 

) ; 

printf( 

"%d\n", strcmpi! 

"abc", 

"ABCdef" ) 

) ; 

printf( 

"%d\n", strcmpi! 

"Abcdef", 

"mnopqr" ) 

) ; 

printf( 

"%d\n", strcmpi! 

"Mnopqr", 

"abcdef" ) 

); 


} 

produces the following: 

0 

100 

-100 

-12 

12 

WATCOM 

strcmpi - All, Linux, RDOS, Netware 
wcscmpi - All, Linux 
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strcoll, wcscoll, _mbscoll 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <string.h> 

int strcoll ( const char *sl, const char *s2 ); 

♦include <wchar.h> 

int wcscoll ( const wchar_ t *sl, const wchar_ t *s2 ); 

♦include <mbstring.h> 

int _ mbscoll( const unsigned char *sl, const unsigned char *s2 ); 

The strcoll function compares the string pointed to by si to the string pointed to by s2. The 
comparison uses the collating sequence selected by the setlocale function. The function will be 
equivalent to the strcmp function when the collating sequence is selected from the "C" locale. 

The wcscoll function is a wide-character version of strcoll that operates with wide-character 
strings. 

The _ mbscoll function is a multibyte character version ofstrcoll that operates with multibyte 
character strings. 

The strcoll function returns an integer less than, equal to, or greater than zero, indicating that the 
string pointed to by si is less than, equal to, or greater than the string pointed to by s2, according to the 
collating sequence selected. 

setlocale, strcmp, strncmp 

♦include <stdio.h> 

♦include <string.h> 

char buffer[80] = "world"; 

void main() 

{ 

if( strcoll ( buffer, "Hello" ) < 0 ) { 

printf ( "Less than\n" ); 

} 

} 

ISOC 

_mbscoll is WATCOM 

strcoll - All, Linux, RDOS, Netware 
wcscoll - All, Linux 

_ mbscoll - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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strcpy, Jstrcpy, wcscpy, _mbscpy, _fmbscpy 


Synopsis: #include <string.h> 

char *strcpy( char *dst, const char *src ); 

char_far *_ fstrcpy( char_far *dst, 

const char_far *src ) ; 

#include <wchar.h> 

wchar_ t *wcscpy( wchar_t *dst, const wchar_ t *src ); 

♦include <mbstring.h> 

int _ mbscpy( unsigned char *dst, 

const unsigned char *src ) ; 

int _ fmbscpy ( unsigned char_far *dst, 

const unsigned char _ far *src ); 

Safer C: The Safer C Library extension provides the strcpy_ s function which is a safer alternative to 

strcpy This newer strcpy_ s function is recommended to be used instead of the traditional "unsafe" 
strcpy function. 

Description: The strcpy function copies the string pointed to by src (including the terminating null character) into 
the array pointed to by dst. Copying of overlapping objects is not guaranteed to work properly. See the 
description for the memmove function to copy objects that overlap. 

The _ f strcpy function is a data model independent form of the strcpy function. It accepts far pointer 
arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The wcscpy function is a wide-character version of strcpy that operates with wide-character strings. 

The _ mbscpy function is a multibyte character version ofstrcpy that operates with multibyte 
character strings. 

Returns: The value of dst is returned. 

See Also: strdup, strncpy, strcpy_ s,strncpy_ s 

Example: #include <stdio.h> 

♦include <string.h> 

void main() 

{ 

auto char buffer[ 80 ]; 

strcpy( buffer, "Hello " ); 
strcat ( buffer, "world" ); 
printf ( "%s\n", buffer ); 

} 

produces the following: 

Hello world 

Classification: ISO C 

_fstrcpy is WATCOM 
_mbscpy is WATCOM 
_fmbscpy is WATCOM 

Systems: strcpy - All, Linux, RDOS, Netware 
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strcpy, Jstrcpy, wcscpy, _mbscpy, Jmbscpy 


_ fstrcpy - All, Linux, RDOS 
wcscpy - All, Linux 

_ mbscpy - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ fmbscpy - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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strcpy_s, wcscpy_s 


Synopsis: 


Constraints: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <string.h> 

errno_ t strcpy_ s ( char * restrict si, 

rsize_ t slmax, 

const char * restrict s2 ); 

♦include <wchar.h> 

errno_ t wcscpy_ s( wchar_ t * restrict si, 

rsize_ t slmax, 

const wchar_ t * restrict s2 ) ; 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and strcpy_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither si nor s2 shall be a null pointer, slmax shall not be greater than RSIZE_ MAX. slmax shall not 
equal zero, slmax shall be greater than strnlen_s(s2, slmax). Copying shall not take place between 
objects that overlap. 

If there is a runtime-constraint violation, then if si is not a null pointer and slmax is greater than zero 
and not greater than RSIZE_ MAX , thenstrcpy_ s sets sl[0] to the null character. 

The strcpy_ s function copies the string pointed to by s2 (including the terminating null character) 
into the array pointed to by si. All elements following the terminating null character (if any) written by 
strcpy_ s in the array of slmax characters pointed to by si take unspecified values when strcpy_ s 
returns. 

The wcscpy_ s function is a wide-character version ofstrcpy_ s that operates with wide-character 
strings. 

The strcpy_ s function returns zero if there was no runtime-constraint violation. Otherwise, a 
non-zero value is returned. 

strcpy, strdup, strncpy, strncpy_ s 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <string.h> 

void main( void ) 

{ 

auto char buffer[80]; 

strcpy_ s ( buffer, sizeof( buffer ), "Hello " ); 
strcat_ s ( buffer, sizeof( buffer ), "world" ); 
printf( "%s\n", buffer ); 

} 

produces the following: 

Hello world 
TR 24731 

strcpy_ s - All, Linux, RDOS, Netware 
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strcpy_s, wcscpy_s 


wcscpy_ s 


- All, Linux 


Library Functions and Macros 1035 




strcspn, Jstrcspn, wcscspn, _mbscspn, Jmbscspn 


Synopsis: #include <string.h> 

size_ t strcspn( const char *str, 

const char *charset ); 

size__ t _ fstrcspn ( const char_far *str, 

const char _ far *charset ); 

♦include <wchar.h> 

size_t wcscspn( const wchar_t *str, 

const wchar_ t *charset ); 

♦include <mbstring.h> 

size_t _ mbscpsn( const unsigned char *str, 

const unsigned char *charset ); 

size__ t _ fmbscpsn ( const unsigned char_far *str, 

const unsigned char _ far *charset ); 

Description: The strcspn function computes the length, in bytes, of the initial segment of the string pointed to by 
str which consists entirely of characters not from the string pointed to by charset. The terminating null 
character is not considered part of sir. 

The _ fstrcspn function is a data model independent form of the strcspn function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The wcscspn function is a wide-character version of strcspn that operates with wide-character 
strings. 

The _ mbscspn function is a multibyte character version ofstrcspn that operates with multibyte 
character strings. 

Returns: The length, in bytes, of the initial segment is returned. 

See Also: strspn 

Example: ♦include <stdio.h> 

♦include <string.h> 

void main () 

{ 

printf ( "%d\n", strcspn( "abcbcadef", "cba" ) ); 

printf( "%d\n", strcspn( "xxxbcadef", "cba" ) ); 

printf( "%d\n", strcspn( "123456789", "cba" ) ); 

} 

produces the following: 

0 

3 

9 

Classification: ISO C 

_fstrcspn is WATCOM 
_mbscspn is WATCOM 
_fmbscspn is WATCOM 

Systems: strcspn - All, Linux, RDOS, Netware 

_ fstrcspn - All, Linux, RDOS 


1036 Library Functions and Macros 




strcspn, Jstrcspn, wcscspn, _mbscspn, Jmbscspn 


wcscspn - All, Linux 

_ mbscspn - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ fmbscspn - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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strdate, _wstrdate 


Synopsis: 

Description: 


Returns: 
See Also: 

Example: 


Classification: 

Systems: 


#include <time.h> 

char *_ strdate( char *datestr ) 

wchar_ t _ wstrdate( wchar_ t *datestr ); 

The _ strdate function copies the current date to the buffer pointed to by datestr. The date is 
formatted as "MM/DD/YY" where "MM" is two digits representing the month, where "DD" is two 
digits representing the day, and where "YY" is two digits representing the year. The buffer must be at 
least 9 bytes long. 

The _ wstrdate function is a wide-character version of_ strdate that operates with wide-character 
strings. 

The _ strdate function returns a pointer to the resulting text string datestr. 

asctime Functions, ctime Functions, gmtime, localtime, mktime, _ strtime.time, 
tzset 

♦include <stdio.h> 

♦include <time.h> 

void main() 

1 

char datebuff[9]; 

printf ( "%s\n", _ strdate( datebuff ) ); 

} 

WATCOM 

_ strdate - All, Linux, RDOS 
_ wstrdate - All, Linux 
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Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


strdec, _wcsdec, _mbsdec, Jmbsdec 


#include <tchar.h> 

char *_ strdec( const char *start, const char ‘current ); 
wchar_ t *_ wcsdec( const wchar_ t ‘start, 

const wchar_ t ‘current ); 

♦include <mbstring.h> 

unsigned char *_ mbsdec( const unsigned char *start, 

const unsigned char ‘current ); 

unsigned char *_ fmbsdec( const unsigned char _far ‘start, 

const unsigned char _ far ‘current ); 

The _ strdec function returns a pointer to the previous character (single-byte, wide, or multibyte) in 
the string pointed to by start which must precede current. The current character in the string is pointed 
to by current. You must ensure that current does not point into the middle of a multibyte or wide 
character. 

The function is a data model independent form of the _strdec function that accepts far pointer 
arguments. It is most useful in mixed memory model applications. 

The _ wcsdec function is a wide-character version of_ strdec that operates with wide-character 
strings. 

The _ mbsdec function is a multibyte character version of_ strdec that operates with multibyte 
character strings. 

The _ strdec function returns a pointer to the previous character (single-byte, wide, or multibyte 
depending on the function used). 

_ strinc,_ strninc 

♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

const unsigned char chars[] = { 

r r 

r 

r r 
• r 

'i', 

'A' , 


0x81, 

0x40, 

/* 

double-byte 

space */ 


0x82, 

0x60, 

/* 

double-byte 

A */ 


0x82, 

0xA6, 

/* 

double-byte 

Hiragana 

*/ 

0x83, 

0x42, 

/* 

double-byte 

Katakana 

*/ 

OxAl, 


/* 

single-byte 

Katakana 

punctuation */ 

0xA6, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxDF, 


/* 

single-byte 

Katakana 

alphabetic */ 

OxEO, 
0x00 

OxAl, 

/* 

double-byte 

Kanji */ 



} ; 

♦define SIZE sizeof( chars ) / sizeof( unsigned char ) 
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strdec, _wcsdec, _mbsdec, Jmbsdec 


void main() 

{ 

int j, k; 

const unsigned char *prev; 

_ setmbcp( 932 ) ; 

prev = Schars[ SIZE - 1 ]; 

do { 

prev = _ mbsdec ( chars, prev ); 
j = mblen ( prev, MB_ CUR_ MAX ) ; 
if( j == 0 ) { 
k = 0; 

} else if ( j == 1 ) { 

k = *prev; 

} else if( j == 2 ) { 

k = *(prev)<<8 | *(prev+l); 

} 

printf( "Previous character %#6.4x\n", k ); 
} while ( prev != chars ); 


produces the following: 


Previous 

Previous 

Previous 

Previous 

Previous 

Previous 

Previous 

Previous 

Previous 

Previous 

Previous 

Previous 


character 

character 

character 

character 

character 

character 

character 

character 

character 

character 

character 

character 


OxeOal 

OxOOdf 

0x00a6 

OxOOal 

0x8342 

0x82a6 

0x8260 

0x8140 

0x0041 

0x0031 

0x002e 

0x0020 


Classification: WATCOM 


Systems: _ strdec - MACRO 

_ wcsdec - MACRO 

_ mbsdec - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
_ fmbsdec - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 


RDOS 

RDOS 


1040 Library Functions and Macros 




Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


strdup, _strdup, Jstrdup, _wcsdup, _mbsdup, Jmbsdup 


#include <string.h> 

char *strdup( const char *src ); 

char *_ strdup( const char *src ); 

char_far *_ fstrdup( const char_far *src ) ; 

#include <wchar.h> 

wchar_ t *_ wcsdup ( const wchar_ t *src ); 

♦include <mbstring.h> 

unsigned char *_ mbsdup ( unsigned char *src ); 

unsigned char_far *_ fmbsdup ( unsigned char_far *src ) ; 

The strdup function creates a duplicate copy of the string pointed to by src and returns a pointer to 
the new copy. For strdup the memory for the new string is obtained by using the malloc function 
and can be freed using the free function. For _fstrdup, the memory for the new string is obtained by 
using the _ fmalloc function and can be freed using the_ f f ree function. 

The _ strdup function is identical tostrdup. Use _ strdup for ANSI naming conventions. 

The _ f strdup function is a data model independent form of the strdup function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The _ wcsdup function is a wide-character version ofstrdup that operates with wide-character 
strings. 

The _ mbsdup function is a multibyte character version ofstrdup that operates with multibyte 
character strings. 

The _ fmbsdup function is a data model independent form of the _mbsdup function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The strdup function returns the pointer to the new copy of the string if successful, otherwise it returns 
NULL. 

free, malloc, strcpy, strncpy 

♦include <stdio.h> 

♦include <string.h> 

void main() 

{ 

char *dup; 

dup = strdup( "Make a copy" ); 
printf( "%s\n", dup ); 

} 

WATCOM 

_strdup conforms to ANSI naming conventions 

strdup - All, Linux, RDOS, Netware 
_ strdup - All, Linux, RDOS, Netware 
_ fstrdup - All, Linux, RDOS 
_ wcsdup - All, Linux, RDOS 

_ mbsdup - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ fmbsdup - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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strerror, wcserror 


Synopsis: 

Safer C: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <string.h> 

char *strerror( int errnum ); 

wchar_ t *wcserror( int errnum ); 

The Safer C Library extension provides the strerror_ s function which is a safer alternative to 
strerror This newer strerror_ s function is recommended to be used instead of the traditional 
"unsafe" strerror function. 

The strerror function maps the error number contained in errnum to an error message. 

The wcserror function is a wide-character version of strerror. It produces a wide-character 
string. 

The strerror function returns a pointer to the error message. The array containing the error string 
should not be modified by the program. This array may be overwritten by a subsequent call to the 
strerror function. 


clearerr, feof, terror, perror, strerror_ s,strerrorlen_ s 


♦include <stdio.h> 
♦include <string.h> 
♦include <errno.h> 


void main() 

{ 

FILE *fp; 


} 


fp = fopen( "file.nam", "r" ); 
if( fp == NULL ) { 

printf( "Unable to open file: 

strerror( errno ) ); 


} 


%s\n", 


ISOC 


strerror - All, Linux, RDOS, Netware 

wcserror - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, Linux 
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strerror_s, wcserror_s 


Synopsis: 


Constraints: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <string.h> 

errno_ t strerror_ s( char * s, 

rsize_ t maxsize, 
errno_ t errnum ); 
errno_ t wcserror_ s( wchar_ t * s, 

rsize_ t maxsize, 
errno_ t errnum ); 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and strerror_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

s shall not be a null pointer, maxsize shall not be greater than RSIZE_ MAX. maxsize shall not equal 
zero. 

If there is a runtime-constraint violation, then the array (if any) pointed to by s is not modified. 

The strerror_ s function maps the number in errnum to a locale-specific message string. 
Typically.the values for errnum come from errno, but strerror_ s shall map any value of type int to 
a message. If the length of the desired string is less than maxsize , then the string is copied to the array 
pointed to by ,v. Otherwise, if maxsize is greater than zero, then maxsize-1 characters are copied from 
the string to the array pointed to by ,v and then s[maxsize-l] is set to the null character. Then, if maxsize 
is greater than 3, then s[maxsize-2], s[maxsize-3], and s[maxsize-4] are set to the character period (.). 

The wcserror_ s function is a wide-character version ofstrerror_ s that operates with 
wide-character strings. 

The strerror_ s function returns zero if there was no runtime-constraint violation. Otherwise, a 
non-zero value is returned. 

clearerr, feof, ferror, perror, strerror, strerrorlen_ s 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <string.h> 

♦include <errno.h> 

void main( void ) 

{ 

FILE *fp; 

char emsg[ 100 ]; 

fp = fopen ( "file.nam", "r" ); 
if( fp == NULL ) { 

strerror_ s ( emsg, sizeof ( emsg ), errno ); 
printf ( "Unable to open file: %s\n", emsg ); 

} 

} 

TR 24731 

strerror_ s - All, Linux, RDOS, Netware 
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strerror_s, wcserror_s 


wcserror_ s - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
Linux 
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strerrorlen_s, wcserrorlen_s 


Synopsis: 

Constraints: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <string.h> 

size_ t strerrorlen_ s ( errno_ t errnum ); 

♦include <wchar.h> 

size_ t wcserrorlen_ s ( errno errnum ); 

None. 

The strerrorlen_ s function calculates the length of the (untruncated) locale-specific message 
string that the strerror_ s function maps to errnum. 

The wcserrorlen_ s function is a wide-character version ofstrerrorlen_ s that operates with 
wide-character strings. 

The strerrorlen_ s function returns the number of characters (not including the null character) in 
the full message string. 

strerror, strerror_ s 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <string.h> 

♦include <errno.h> 

void main( void ) 

{ 

FILE *fp; 

char emsg[ 100 ]; 

size_ t emsglen; 

fp = fopen( "file.nam", "r" ); 
if( fp == NULL ) { 

emsglen = strerrorlen_ s ( errno ); 

printf ( "Length of errormessage: %d\n", emsglen ); 
strerror_ s ( emsg, sizeof ( emsg ), errno ); 
printf ( "Unable to open file: %s\n", emsg ); 

} 

} 

TR 24731 

strerrorlen_ s - All, Linux, RDOS, Netware 

wcserrorlen_ s - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
Linux 
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strftime, wcsftime, _wstrftime_ms 


Synopsis: #include <time.h> 

size_ t strftime( char *s, 

size_ t maxsize, 

const char *format, 

const struct tm *timeptr ); 

#include <wchar.h> 

size_t wcsftime( wchar_t *s, 

size_ t maxsize, 

const wchar_t ^format, 

const struct tm *timeptr ) ; 

♦include <time.h> 

size_ t _ wstrftime_ ms ( wchar_ t *s, 

size_ t maxsize, 

const char *format, 

const struct tm *timeptr ) ; 

struct tm { 

int tm_ sec; /* seconds after the minute — [0,61] */ 

int tm_ min; /* minutes after the hour — [0,59] */ 

int tm_ hour; /* hours after midnight — [0,23] */ 

int tm_ mday; /* day of the month — [1,31] */ 

int tm_mon; /* months since January — [0,11] */ 

int tm_ year; /* years since 1900 */ 

int tm_ wday; /* days since Sunday — [0,6] */ 

int tm_ yday; /* days since January 1 — [0,365]*/ 

int tm_isdst; /* Daylight Savings Time flag */ 

} ; 

Description: The strftime function formats the time in the argument timeptr into the array pointed to by the 
argument s according to the format argument. 

The _ wstrftime_ ms function is a wide-character version ofetrftime that operates with 
wide-character strings. 

The _ wstrftime_ ms function is identical to_ wstrftime_ ms except that th e format is not a 
wide-character string. 

The format string consists of zero or more directives and ordinary characters. A directive consists of a 
character followed by a character that determines the substitution that is to take place. All ordinary 
characters are copied unchanged into the array. No more than maxsize characters are placed in the 
array. The format directives %D, %h, %n, %r, %t, and %T are from POSIX. 


Directive 

Meaning 

%a 

locale’s abbreviated weekday name 

%A 

locale’s full weekday name 

%b 

locale’s abbreviated month name 

%B 

locale’s full month name 

%c 

locale’s appropriate date and time representation 
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strftime, wcsftime, _wstrftime_ms 


%C is replaced by the year devided by 100 and truncated to an integer (00-99) 

%d day of the month as a decimal number (01-31) 

%D date in the format mm/dd/yy (POSIX) 

%e day of the month as a decimal number ( 1-31), a single digit is preceded by a blank 

%F is equivalent to ’%Y-%m-%d’ (the ISO 8601 date format) 

%g is replaced by the last 2 digits of the week-based year as a decimal number (00-99) 

%G is replaced by the week-based year as a decimal number (e.g. 2006) 

%/i locale’s abbreviated month name (POSIX) 

%H hour (24-hour clock) as a decimal number (00-23) 

%/ hour (12-hour clock) as a decimal number (01-12) 

%j day of the year as a decimal number (001-366) 

%/m month as a decimal number (01-12) 

%M minute as a decimal number (00-59) 

%/i newline character (POSIX) 

%p locale’s equivalent of either AM or PM 

%r 12-hour clock time (01-12) using the AM/PM notation in the format HH:MM:SS 

(AMIPM) (POSIX) 

%S second as a decimal number (00-59) 

%t tab character (POSIX) 

%T 24-hour clock time in the format HH:MM:SS (POSIX) 

%u is replaced by the ISO 8601 weekday as a decimal number (1-7), where Monday is 1 

%U week number of the year as a decimal number (00-52) where Sunday is the first day of 

the week 

%V is replaced by the ISO 8601 week number as a decimal number (01-53) 

%w weekday as a decimal number (0-6) where 0 is Sunday 

%W week number of the year as a decimal number (00-52) where Monday is the first day of 

the week 

%x locale’s appropriate date representation 
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strftime, wcsftime, _wstrftime_ms 


%X locale’s appropriate time representation 

%y year without century as a decimal number (00-99) 

%Y year with century as a decimal number 

%z offset from UTC in the ISO 8601 format ’-0430’ (meaning 4 hours 30 minutes behind 

UTC, west of Greenwich), or by no characters, if no timezone is determinable 

%Z timezone name, or by no characters if no timezone exists 

%% character % 

When the %Z or %z directive is specified, the tzset function is called. 

% g, %G, %V give values according to the ISO 8601 week-based year. In this system, weeks begin on 
a monday and week 1 of the year is the week that includes January 4th, which is also the week that 
includes the first Thursday of the year, and is also the first week that contains at least four days in the 
year. If the first Monday of January is the 2nd, 3rd, or 4th, the preceding days are part of the last week 
of the preceding year; thus, for Saturday 2nd January 1999, %G is replaced by 1998 and %V is replaced 
by 53. If december 29th, 30th, or 31st is a Monday, it and any following days are part of week 1 of the 
following year. Thus, for Tuesday 30th December 1997, %G is replaced by 1998 and %V is replaced 
by 01. 

The format modifiers E and O are ignored, (eg. %EY is the same as %Y) 

Returns: If the number of characters to be placed into the array is less than maxsize , the strftime function 

returns the number of characters placed into the array pointed to by ,v not including the terminating null 
character. Otherwise, zero is returned. When an error has occurred, errno contains a value indicating 
the type of error that has been detected. 

See Also: setlocale, a sctime Functions, asctime_ s,clock, ctime Functions, ctime_ s,difftime, 

gmtime, gmtime_ s,localtime, localtime_ s,mktime, time, tzset 

Example: ((include <stdio.h> 

♦include <time.h> 

void main() 

{ 

time_ t time_ of_ day; 
char buffer! 80 ]; 

time_ of_ day = time ( NULL ) ; 

strftime( buffer, 80, "Today is %A %B %d, %Y", 
localtime ( &time_ of_ day ) ) ; 

printf ( "%s\n", buffer ); 

} 

produces the following: 

Today is Friday December 25, 1987 

Classification: ISO C, POSIX 

wcsftime is ISO C95 
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strftime, wcsftime, _wstrftime_ms 


Systems: 


_wstrftime_ms is WATCOM 

strftime - All, Linux, RDOS, 
wcsftime - All, Linux 
_ wstrftime_ ms - All, Linux 


Netware 
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stricmp, 

Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


stricmp, Jstricmp, _wcsicmp, _mbsicmp, Jmbsicmp 


♦include <string.h> 

int stricmp( const char *sl, const char *s2 ); 
int _ stricmp( const char *sl, const char *s2 ); 

int _ fstricmp( const char_far *sl, 

const char _ far *s2 ); 

♦include <wchar.h> 

int _wcsicmp( const wchar_ t *sl, const wchar_ t *s2 ); 

♦include <mbstring.h> 

int _mbsicmp( const unsigned char *sl, 

const unsigned char *s2 ); 

int _ fmbsicmp( const unsigned char_far *sl, 

const unsigned char _ far *s2 ); 

The stricmp function compares, with case insensitivity, the string pointed to by si to the string 
pointed to by s2. All uppercase characters from si and s2 are mapped to lowercase for the purposes of 
doing the comparison. 

The _ stricmp function is identical tostricmp. Use _ stricmp for ANSI naming conventions. 

The _ f stricmp function is a data model independent form of the stricmp function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The _ wcsicmp function is a wide-character version of stricmp that operates with wide-character 
strings. 

The _ mbsicmp function is a multibyte character version of stricmp that operates with multibyte 
character strings. 

The _ fmbsicmp function is a data model independent form of the _mbsicmp function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The stricmp function returns an integer less than, equal to, or greater than zero, indicating that the 
string pointed to by si is less than, equal to, or greater than the string pointed to by s2. 

strcmp, strcmpi, strncmp, strnicmp 


♦include <stdio.h> 
♦include <string.h> 


void main() 

{ 

printf( 

"%d\n", stricmp( 

"AbCDEF", 

"abcdef" ) 

) ; 

printf( 

"%d\n", stricmp! 

"abcdef", 

"ABC" ) 

) ; 

printf( 

"%d\n", stricmp! 

"abc", 

"ABCdef" ) 

) ; 

printf( 

"%d\n", stricmp! 

"Abcdef", 

"mnopqr" ) 

) ; 

printf( 

"%d\n", stricmp! 

"Mnopqr", 

"abcdef" ) 

); 


} 


produces the following: 
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stricmp, _stricmp, _fstricmp, _wcsicmp, _mbsicmp, _fmbsicmp 


0 

100 

-100 

-12 

12 

Classification: WATCOM 

_stricmp conforms to ANSI naming conventions 


Systems: stricmp - All, Linux, RDOS, Netware 

_ stricmp - All, Linux, RDOS, Netware 
_ fstricmp - All, Linux, RDOS 
_ wcsicmp - All, Linux 

_ mbsicmp - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ fmbsicmp - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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stricoll, _wcsicoll, _mbsicoll 


Synopsis: #include <string.h> 

int _ stricoll ( const char *sl, const char *s2 ); 

♦include <wchar.h> 

int _ wcsicoll ( const wchar_ t *sl, const wchar_ t *s2 ); 

♦include <mbstring.h> 

int _ mbsicoll( const unsigned char *sl, const unsigned char *s2 ); 

Description: The _ stricoll function performs a case insensitive comparison of the string pointed to by si to the 
string pointed to by s2. The comparison uses the current code page which can be selected by the 
_ setmbcp function. 

The _ wcsicoll function is a wide-character version of_ stricoll that operates with 
wide-character strings. 

The _ mbsicoll function is a multibyte character version of_ stricoll that operates with multibyte 
character strings. 

Returns: These functions return an integer less than, equal to, or greater than zero, indicating that the string 

pointed to by si is less than, equal to, or greater than the string pointed to by s2, according to the 
collating sequence selected. 

See Also: _ setmbcp,strcoll, stricmp, strncmp, _ strncoll,strnicmp, _ strnicoll 

Example: ♦include <stdio.h> 

♦include <string.h> 

char buffer[80] = "world"; 

void main() 

{ 

int test; 

test = _ stricoll( buffer, "world2" ); 
if( test < 0 ) { 

printf ( "Less than\n" ); 

} else if( test == 0 ) { 

printf ( "Equal\n" ); 

} else { 

printf ( "Greater than\n" ); 

} 

} 

Classification: WATCOM 

Systems: _ stricoll - All, Linux, RDOS, Netware 

_ wcsicoll - All, Linux 

_ mbsicoll - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


strinc, _wcsinc, _mbsinc, Jmbsinc 


#include <tchar.h> 

char *_ strinc( const char ‘current ); 
wchar_ t *_ wcsinc ( const wchar_ t ‘current ) ; 

♦include <mbstring.h> 

unsigned char *_mbsinc( const unsigned char ‘current ); 
unsigned char *_fmbsinc( 

const unsigned char _ far ‘current ); 

The _ strinc function returns a pointer to the next character (single-byte, wide, or multibyte) in the 
string pointed to by current. You must ensure that current does not point into the middle of a multibyte 
or wide character. 

The function is a data model independent form of the _strinc function that accepts far pointer 
arguments. It is most useful in mixed memory model applications. 

The _ wcsinc function is a wide-character version of_ strinc that operates with wide-character 
strings. 

The _ mbsinc function is a multibyte character version of_ strinc that operates with multibyte 
character strings. 

The _ strinc function returns a pointer to the next character (single-byte, wide, or multibyte 
depending on the function used). 

_ strdec,_ strninc 
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strinc, _wcsinc, _mbsinc, Jmbsinc 


♦include <stdio.h> 

♦include <mbctype.h> 

♦include <mbstring.h> 

const unsigned char chars[] = { 

r r 

r 

r r 
• r 

'A' , 

0x81,0x40, /* double-byte space */ 

0x82,0x60, /* double-byte A */ 

0x82,0xA6, /* double-byte Hiragana */ 

0x83,0x42, /* double-byte Katakana */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6, /* single-byte Katakana alphabetic */ 

OxDF, /* single-byte Katakana alphabetic */ 

0xE0,0xAl, /* double-byte Kanji */ 

0x00 

} ; 

♦ define SIZE sizeof ( chars ) / sizeof( unsigned char ) 

void main() 

{ 

int j, k; 

const unsigned char *next; 

_ setmbcp( 932 ) ; 
next = chars; 
do { 

next = _mbsinc( next ); 
j = mblen ( next, MB_ CUR_ MAX ); 
if( j == 0 ) { 
k = 0; 

} else if ( j == 1 ) { 

k = *next; 

} else if( j == 2 ) { 

k = *(next)<<8 | *(next+l); 

} 

printf( "Next character %#6.4x\n", k ); 

} while( next != Schars[ SIZE - 1 ] ); 

} 

produces the following: 

Next character 0x002e 
Next character 0x0031 
Next character 0x0041 
Next character 0x8140 
Next character 0x8260 
Next character 0x82a6 
Next character 0x8342 
Next character OxOOal 
Next character 0x00a6 
Next character OxOOdf 
Next character OxeOal 
Next character 0000 
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Classification: 

Systems: 


strinc, _wcsinc, _mbsinc, Jmbsinc 


WATCOM 


_ strinc - MACRO 
_ wcsinc - MACRO 

_ mbsinc - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, Linux, 
RDOS 

_ fmbsinc - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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strlcat, wcslcat 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <string.h> 

size_ t strlcat( char *dst, const char *src, size_t n ); 
size_ t *wcslcat ( wchar_ t *dst, 

const wchar_ t *src, 
size_ t n ) ; 

The strlcat function appends characters of the string pointed to by src to the end of the string in a 
buffer pointed to by dst that can hold up to n characters. The first character of src overwrites the null 
character at the end of dst. A terminating null character is always appended to the result, unless n 
characters of dst are scanned and no null character is found. 

The wcslcat function is a wide-character version of strlcat that operates with wide-character 
strings. 

The strlcat function returns the total length of string it tried to create, that is the number of 
characters in both src and dst strings, not counting the terminating null characters. If n characters of dst 
were scanned without finding a null character, n is returned. 

strlcpy, strncat, strcat 

♦include <stdio.h> 

♦include <string.h> 

char buffer[80]; 

void main( void ) 

{ 

strcpy( buffer, "Hello " ); 
strlcat] buffer, "world", 12 ); 
printf( "%s\n", buffer ); 
strlcat] buffer, »*************", 16 ); 
printf] "%s\n", buffer ); 

} 

produces the following: 

Hello world 
Hello world**** 

WATCOM 

strlcat - All, Linux, RDOS, Netware 
wcslcat - All, Linux 
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strlcpy, wcslcpy 


Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <string.h> 
size_ t strlcpy ( char *dst, 

const char *src, 
size_ t n ) ; 

size_ t wcslcpy ( wchar_ t *dst, 

const wchar_ t *src, 
size_ t n ) ; 

The strlcpy function copies no more than n characters from the string pointed to by src into the array 
pointed to by dst. Copying of overlapping objects is not guaranteed to work properly. See the 
memmove function if you wish to copy objects that overlap. 

If the string pointed to by src is longer than n characters, then only n - 1 characters will be copied and 
the result will be null terminated. 

The wcslcpy function is a wide-character version of strlcpy that operates with wide-character 
strings. 

The strlcpy function returns the number of characters in the src string, not including the terminating 
null character. 

strlcat, strncpy, strcpy 

♦include <stdio.h> 

♦include <string.h> 

void main( void ) 

{ 

char buffer[10]; 

printf( "%d:'%s'\n", strlcpy( buffer, 

"Buffer overflow", sizeof ( buffer ) ), buffer ); 

} 

produces the following: 

15:'Buffer ov' 

WATCOM 

strlcpy - All, Linux, RDOS, Netware 
wcslcpy - All, Linux 
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strlen, Jstrlen, wcslen, _mbslen, Jmbslen 


Synopsis: #include <string.h> 

size_ t strlen( const char *s ); 

size_t _ fstrlen( const char_far *s ) ; 

♦include <wchar.h> 

size_ t wcslen ( const wchar_ t *s ); 

♦include <mbstring.h> 

size_ t _ mbslen( const unsigned char *s ) ; 

size_t _ fmbslen( const unsigned char _ far *s ); 

Safer C: The Safer C Library extension provides the function which is a safer alternative to strlen This newer 

strlen_ s function is recommended to be used instead of the traditional "unsafe" strlen function. 

Description: The strlen function computes the length of the string pointed to by s. 

The _ fstrlen function is a data model independent form of the strlen function that accepts far pointer 
arguments. It is most useful in mixed memory model applications. 

The wcslen function is a wide-character version of strlen that operates with wide-character strings. 

The _ mbslen function is a multibyte character version ofstrlen that operates with multibyte 
character strings. 

The _ fmbslen function is a data model independent form of the _mbslen function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

Returns: The strlen function returns the number of characters that precede the terminating null character. 

See Also: strnlen_ s 

Example: ♦include <stdio.h> 

♦include <string.h> 

void main() 

{ 

printf( "%d\n", strlen ( "Howdy" ) ); 

printf( "%d\n", strlen( "Hello world\n" ) ); 

printf( "%d\n", strlen( "" ) ); 

} 

produces the following: 

5 

12 

0 

Classification: ISO C 

_fstrlen is WATCOM 
_mbslen is WATCOM 
_fmbslen is WATCOM 

Systems: strlen - All, Linux, RDOS, Netware 

_ fstrlen - All, Linux, RDOS 
wcslen - All, Linux 

_ mbslen - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS 
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fmbslen 


strlen, Jstrien, wcslen, _mbslen, Jmbslen 


DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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stmlen_s, wcsnlen_s 


Synopsis: 


Constraints: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <string.h> 

size_ t strnlen_ s( const char * s, 

size_ t maxsize ); 

♦include <wchar.h> 

size_ t wcsnlen_ s ( const wchar_ t * s, 

size_ t maxsize ); 


None. 

The strnlen_ s function calculates the length of the string pointed to by s. 

The wcsnlen_ s function is a wide-character version ofstrnlen_ s that operates with 
wide-character strings. 

If .v is a null pointer, then the strnlen_ s function returns zero. Otherwise, thestrnlen_ s function 
returns the number of characters that precede the terminating null character. If there is no null character 
in the first maxsize characters of.? then strnlen_ s returns maxsize. At most the first maxsize 
characters of s shall be accessed by strnlen_s 

strlen 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <string.h> 

void main( void ) 

{ 

char buffer[ 30 ] = "Hello world."; 
size_ t len; 

len = strnlen_ s ( buffer, sizeof ( buffer ) ); 

printf ( "Length of text: %d\n", emsglen ); 
printf ( "Text: %s\n", buffer ); 

} 

TR 24731 

strnlen_ s - All, RDOS, Netware 
wcsnlen_ s - All, Linux 
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Synopsis: 


Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


strlwr, _strlwr, Jstrlwr, _wcslwr, _mbslwr, _fmbslwr 


#include <string.h> 

char *strlwr( char *sl ); 

char *_ strlwr ( char *sl ); 

char_far *_ fstrlwr( char_far *sl ) ; 

♦include <wchar.h> 

wchar_ t *_ wcslwr ( wchar_ t *sl ); 

♦include <mbstring.h> 

unsigned char *_mbslwr( unsigned char *sl ); 

unsigned char_far *_ fmbslwr( unsigned char_far *sl ) ; 

The strlwr function replaces the string si with lowercase characters by invoking the tolower 
function for each character in the string. 

The _ strlwr function is identical tostrlwr. Use _ strlwr for ANSI naming conventions. 

The _ f strlwr function is a data model independent form of the strlwr function. It accepts far pointer 
arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The _ wcslwr function is a wide-character version ofstrlwr that operates with wide-character 
strings. 

The _ mbslwr function is a multibyte character version ofstrlwr that operates with multibyte 
character strings. 

The _ fmbslwr function is a data model independent form of the _mbslwr function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The address of the original string si is returned. 

strupr 

♦include <stdio.h> 

♦include <string.h> 

char source[] = { "A mixed-case STRING" }; 

void main() 

{ 

printf ( "%s\n", source ); 

printf ( "%s\n", strlwr( source ) ); 

printf ( "%s\n", source ); 

} 

produces the following: 

A mixed-case STRING 
a mixed-case string 
a mixed-case string 

WATCOM 

_strlwr conforms to ANSI naming conventions 

strlwr - All, Linux, RDOS, Netware 
_ strlwr - All, Linux, RDOS, Netware 
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strlwr, _strlwr, Jstrlwr, _wcslwr, _mbslwr, Jmbslwr 


fstrlwr - All, Linux, RDOS 
wcslwr - All, Linux 

mbslwr - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
fmbslwr - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 


RDOS 

RDOS 
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strncasecmp 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <strings.h> 
int strncasecmp( const char *sl, 
const char *s2, 
size_ t len ) ; 

The strncasecmp function compares, without case sensitivity, the string pointed to by si to the 
string pointed to by s2, for at most len characters. 

The strncasecmp function is identical to the strnicmp function. 

The strncasecmp function returns an integer less than, equal to, or greater than zero, indicating that 
the string pointed to by si is, ignoring case, less than, equal to, or greater than the string pointed to by 
s2. 

strnicmp, strcmp, stricmp, strncmp, strcasecmp 

♦include <stdio.h> 

♦include <strings.h> 

int main( void ) 

{ 


printf( 

"%d\n", strncasecmp! 

"abcdef", 

"ABCXXX", 

10 ) 

) ; 

printf( 

"%d\n", strncasecmp! 

"abcdef", 

"ABCXXX", 

6 ) 

) ; 

printf( 

"%d\n", strncasecmp! 

"abcdef", 

"ABCXXX", 

3 ) 

) ; 

printf( 
return( 

"%d\n", strncasecmp! 

0 ); 

"abcdef", 

"ABCXXX", 

0 ) 

); 


} 

produces the following: 

-20 

-20 

0 

0 

POSIX 

All, RDOS, Netware 
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stmcat, Jstrncat, wcsncat, _mbsncat, Jmbsncat 


Synopsis: #include <string.h> 

char *strncat( char *dst, const char *src, size_ t n ) ; 

char_far *_ fstrncat ( char_far *dst, 

const char _ far *src, 

size_ t n ) ; 

♦include <wchar.h> 
wchar_ t *wcsncat( wchar_t *dst, 
const wchar_ t *src, 
size_ t n ) ; 

♦include <mbstring.h> 

unsigned char *_ mbsncat ( unsigned char *dst, 

const unsigned char *src, 
size_ t n ) ; 

unsigned char_far *_ fmbsncat ( unsigned char_far *dst, 

const unsigned char _ far *src, 

size_ t n ) ; 

Safer C: The Safer C Library extension provides the strncat_ s function which is a safer alternative to 

strncat This newer strncat_ s function is recommended to be used instead of the traditional 
"unsafe" strncat function. 

Description: The strncat function appends not more than n characters of the string pointed to by src to the end of 
the string pointed to by (1st. The first character of src overwrites the null character at the end of (1st. A 
terminating null character is always appended to the result. 

The _ fstrncat function is a data model independent form of the strncat function. It accepts far 
pointer arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The wcsncat function is a wide-character version of strncat that operates with wide-character 
strings. 

The _ mbsncat function is a multibyte character version ofstrncat that operates with multibyte 
character strings. 

The _ fmbsncat function is a data model independent form of the _mbsncat function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

Returns: The strncat function returns the value of (1st. 

See Also: strcat, strlcat, strncat_ s,strcat_ s 

Example: ♦include <stdio.h> 

♦include <string.h> 

char buffer[80]; 

void main( void ) 

{ 

strcpy ( buffer, "Hello " ); 

strncat ( buffer, "world", 8 ); 

printf ( "%s\n", buffer ); 

strncat ( buffer, "*************", 4 ); 

printf ( "%s\n", buffer ); 

} 
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Classification: 


Systems: 


strncat, Jstmcat, wcsncat, _mbsncat, Jmbsncat 


produces the following: 

Hello world 
Hello world**** 

ISOC 

_fstrncat is WATCOM 
_mbsncat is WATCOM 
_fmbsncat is WATCOM 

strncat - All, Linux, RDOS, Netware 
_ fstrncat - All, Linux, RDOS 
wcsncat - All, Linux 

_ mbsncat - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ fmbsncat - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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strncat_s, wcsncaLs 


Synopsis: 


Constraints: 


Description: 


Returns: 

See Also: 
Example: 


♦ define_ STDC_ WANT_ LIB_ EXT1_1 

♦include <string.h> 

errno_ t strncat_ s ( char * restrict si, 

rsize_ t slmax, 

const char * restrict s2, 

rsize_ t n ) 

♦include <wchar.h> 

errno_ t wcsncat_ s( wchar_ t * restrict si, 

rsize_ t slmax, 

const wchar_ t * restrict s2, 

rsize_ t n ) 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and strncat_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Let m denote the value slmax - strnlen_s(sl, slmax) upon entry to strncat_s 

Neither si nor s2 shall be a null pointer. Neither slmax nor n shall be greater than RSIZE_ MAX. 
slmax shall not equal zero, m shall not equal zero. If n is not less than m, then m shall be greater than 
strnlen_s(s2, m). Copying shall not take place between objects that overlap. 

If there is a runtime-constraint violation, then if ,v / is not a null pointer and slmax is greater than zero 
and not greater than RSIZE_ MAX, thenstrncat_ s sets sl[0] to the null character. 

The strncat_ s function appends not more than n successive characters (characters that follow a null 
character are not copied) from the array pointed to by s2 to the end of the string pointed to by si. The 
initial character from s2 overwrites the null character at the end of si. If no null character was copied 
from s2,then si[slmax-m+n] is set to a null character. All elements following the terminating null 
character (if any) written by strncat_ s in the array of slmax characters pointed to by si take 
unspecified values when strncat_ s returns. 

The wcsncat_ s function is a wide-character version ofstrncat_ s that operates with 
wide-character strings. 

The strncat_ s function returns zero if there was no runtime-constraint violation. Otherwise, a 
non-zero value is returned. 

strncat, strcat, strlcat, strcat_ s 

♦ define_ STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <string.h> 

char buffer[80]; 

void main( void ) 

{ 

strcpy( buffer, "Hello " ); 

strncat_ s( buffer, sizeof ( buffer ), "world", 8 ); 

printf( "%s\n", buffer ); 

strncat ( buffer, "*************", 4 ); 

printf ( "%s\n", buffer ); 

} 
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strncaLs, wcsncat_s 


produces the following: 

Hello world 
Hello world**** 

Classification: TR 24731 

Systems: strncat_ s - All, Linux, RDOS, 

wcsncat_ s - All, Linux 


Netware 
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strncmp, 

Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


fstrncmp, wcsncmp, _mbsncmp, _fmbsncmp 


#include <string.h> 
int strncmp( const char *sl, 
const char *s2, 
size_ t n ) ; 

int _ fstrncmp ( const char_far *sl, 

const char _far *s2, 

size_ t n ) ; 

♦include <wchar.h> 
int wcsncmp( const wchar_ t *sl, 
const wchar_t *s2, 
size_ t n ) ; 

♦include <mbstring.h> 

int _ mbsncmp( const unsigned char *sl, 
const unsigned char *s2, 
size_ t n ) ; 

int _ fmbsncmp ( const unsigned char_far *sl, 

const unsigned char _far *s2, 

size_ t n ) ; 

The strncmp compares not more than n characters from the string pointed to by si to the string 
pointed to by s2. 

The _ fstrncmp function is a data model independent form of the strncmp function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The wcsncmp function is a wide-character version of strncmp that operates with wide-character 
strings. 

The _ mbsncmp function is a multibyte character version ofstrncmp that operates with multibyte 
character strings. 

The _ fmbsncmp function is a data model independent form of the _mbsncmp function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The strncmp function returns an integer less than, equal to, or greater than zero, indicating that the 
string pointed to by si is less than, equal to, or greater than the string pointed to by s2. 

strcmp, stricmp, strnicmp 


♦include <stdio.h> 
♦include <string.h> 


void main() 

{ 

printf( 

"%d\n", strncmp( 

"abcdef", 

"abcDEF", 

10 ) 

) ; 

printf( 

"%d\n", strncmp! 

"abcdef", 

"abcDEF", 

6 ) 

) ; 

printf( 

"%d\n", strncmp! 

"abcdef", 

"abcDEF", 

3 ) 

) ; 

printf( 

"%d\n", strncmp! 

"abcdef", 

"abcDEF", 

0 ) 

); 


} 


produces the following: 
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Classification: 


Systems: 


strncmp, Jstrncmp, wcsncmp, _mbsncmp, Jmbsncmp 


i 

i 

0 

0 

ISOC 

_fstrncmp is WATCOM 
_mbsncmp is WATCOM 
_fmbsncmp is WATCOM 

strncmp - All, Linux, RDOS, Netware 
_ fstrncmp - All, Linux, RDOS 
wcsncmp - All, Linux 

_ mbsncmp - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS 
_ fmbsncmp - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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_strncoll, 

Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


wcsncoll, _mbsncoll 


♦include <string.h> 
int _ strncoll( const char *sl, 
const char *s2, 
size_ t count ); 

♦include <wchar.h> 

int _ wcsncoll ( const wchar_ t *sl, 
const wchar_ t *s2, 
size_ t count ); 

♦include <mbstring.h> 

int _ mbsncoll( const unsigned char *sl, 
const unsigned char *s2, 
size_ t count ); 

These functions compare the first count characters of the string pointed to by si to the string pointed to 
by s2. The comparison uses the current code page which can be selected by the _ setmbcp function. 

The _ wcsncoll function is a wide-character version of_ strncoll that operates with 
wide-character strings. 

The _ mbsncoll function is a multibyte character version of_ strncoll that operates with multibyte 
character strings. 

These functions return an integer less than, equal to, or greater than zero, indicating that the string 
pointed to by si is less than, equal to, or greater than the string pointed to by s2, according to the 
collating sequence selected. 

_ setmbcp,strcoll, stricmp, _ stricoll,strncmp, strnicmp, _ strnicoll 

♦include <stdio.h> 

♦include <string.h> 

char buffer [80] = "world"; 

void main() 

{ 

int test; 

test = _ strncoll( buffer, "world2", 5 ); 
if( test < 0 ) { 

printf ( "Less than\n" ); 

} else if( test == 0 ) { 

printf ( "Equal\n" ); 

} else { 

printf ( "Greater than\n" ); 

} 

} 

WATCOM 

_ strncoll - All, Linux, RDOS, Netware 
_ wcsncoll - All, Linux 

_ mbsncoll - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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Synopsis: 


Safer C: 

Description: 


Returns: 
See Also: 
Example: 


strncpy, Jstrncpy, wcsncpy, _mbsncpy, Jmbsncpy 


♦include <string.h> 
char *strncpy( char *dst, 

const char *src, 
size_ t n ) ; 

char_far *_ fstrncpy( char_far *dst, 

const char _ far *src, 

size_ t n ) ; 


♦include 
wchar_ t 


♦include 

unsigned 


unsigned 


<wchar.h> 

*wcsncpy( wchar_ t *dst, 

const wchar_ t *src, 
size_ t n ) ; 

<mbstring.h> 

char *_ mbsncpy ( unsigned char *dst, 
const unsigned char *src, 
size_ t n ) ; 

char_far *_ fmbsncpy ( unsigned char 

const unsigned char _ 
size_ t n ) ; 


_ far *dst, 
far *src, 


The Safer C Library extension provides the strncpy_ s function which is a safer alternative to 
strncpy This newer strncpy_ s function is recommended to be used instead of the traditional 
"unsafe" strncpy function. 


The strncpy function copies no more than n characters from the string pointed to by src into the array 
pointed to by dst. Copying of overlapping objects is not guaranteed to work properly. See the 
memmove function if you wish to copy objects that overlap. 

If the string pointed to by src is shorter than n characters, null characters are appended to the copy in the 
array pointed to by dst , until n characters in all have been written. If the string pointed to by src is 
longer than n characters, then the result will not be terminated by a null character. 

The _ f strncpy function is a data model independent form of the strncpy function. It accepts far 
pointer arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The wcsncpy function is a wide-character version of strncpy that operates with wide-character 
strings. 

The _ mbsncpy function is a multibyte character version ofstrncpy that operates with multibyte 
character strings. 

The _ fmbsncpy function is a data model independent form of the _mbsncpy function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The strncpy function returns the value of dst. 


strlcpy, strcpy, strdup, strncpy_ s,strcpy_ s 

♦include <stdio.h> 

♦include <string.h> 

void main( void ) 

{ 

char buffer[15]; 
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strncpy, Jstrncpy, wcsncpy, _mbsncpy, Jmbsncpy 


printf( 

"%s\n", strncpy! 

buffer. 

"abcdefg", 

10 ) 

) ; 

printf( 

"%s\n", strncpy! 

buffer. 

"1234567", 

6 ) 

) ; 

printf( 

"%s\n", strncpy! 

buffer. 

"abcdefg", 

3 ) 

) ; 

printf( 

"%s\n", strncpy! 

buffer. 

»»*******»» 

r 

0 ) 

); 


produces the following: 

abcdefg 

123456g 

abc456g 

abc456g 

Classification: ISO C 

_fstrncpy is WATCOM 
_mbsncpy is WATCOM 
_fmbsncpy is WATCOM 

Systems: strncpy - All, Linux, RDOS, Netware 

_ fstrncpy - All, Linux, RDOS 
wcsncpy - All, Linux 

_ mbsncpy - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ fmbsncpy - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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strncpy_s, wcsncpy_s 


Synopsis: 


Constraints: 


Description: 


Returns: 

See Also: 
Example: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <string.h> 

errno_ t strncpy_ s ( char * restrict si, 

rsize_ t slmax, 

const char * restrict s2, 

rsize_ t n ) ; 

♦include <wchar.h> 

errno_ t wcsncpy_ s ( wchar_ t * restrict si, 

rsize_ t slmax, 

const wchar_ t * restrict s2, 

rsize_ t n ) ; 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and strncpy_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither si nor s2 shall be a null pointer. Neither slmax nor n shall be greater than RSI ZE_ MAX. 
slmax shall not equal zero. If n is not less than slmax , then slmax shall be greater than strnlen_s(s2, 
slmax). 

Copying shall not take place between objects that overlap. 

If there is a runtime-constraint violation, then if si is not a null pointer and slmax is greater than zero 
and not greater than RSIZE_ MAX, thenstrncpy_ s sets sl[0] to the null character. 

The strncpy_ s function copies not more than n successive characters (characters that follow a null 
character are not copied) from the array pointed to by s2 to the array pointed to by si. If no null 
character was copied from s2, then si[n] is set to a null character. 

All elements following the terminating null character (if any) written by strncpy_ s in the array of 
slmax characters pointed to by si take unspecified values when strncpy_ s returns. 

The wcsncpy_ s function is a wide-character version ofstrncpy_ s that operates with 
wide-character strings. 

The strncpy_ s function returns zero if there was no runtime-constraint violation. Otherwise, a 
non-zero value is returned. 

strncpy, strlcpy, strcpy, strdup, strcpy_ s 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <string.h> 

void main( void ) 

{ 

char buffer[15]; 
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strncpy_s, wcsncpy_s 


Classification: 

Systems: 


strncpy_ s ( buffer, sizeof( 
printf( "%s\n", buffer ); 

buffer 

), "abcdefg". 

10 ) ; 

strncpy_ s ( buffer, sizeof( 
printf( "%s\n", buffer ); 

buffer 

), "1234567", 

6 ); 

strncpy_ s ( buffer, sizeof ( 
printf ( "%s\n", buffer ); 

buffer 

), " abcdefg". 

3 ) ; 

strncpy_ s ( buffer, sizeof ( 
printf ( "%s\n", buffer ); 

buffer 

\ H ******* H 

Jr r 

0 ); 


} 

produces the following: 

abcdefg 

123456 

abc 

(nothing) 

TR 24731 

strncpy_ s - All, Linux, RDOS, Netware 
wcsncpy_ s - All, Linux 
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Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


stmicmp, _stmicmp, Jstrnicmp, _wcsnicmp, _mbsnicmp, _fmbsnicmp 


♦include <string.h> 
int strnicmp( const char *sl, 
const char *s2, 
size_ t len ) ; 

int _ strnicmp( const char *sl, 
const char *s2, 
size_ t len ) ; 

int _ fstrnicmp( const char_far *sl, 

const char _ far *s2, 

size_ t len ) ; 

♦include <wchar.h> 

int _ wcsnicmp ( const wchar_ t *sl, 
const wchar_ t *s2, 
size_ t len ) ; 

♦include <mbstring.h> 

int _ mbsnicmp( const unsigned char *sl, 
const unsigned char *s2, 
size_ t n ) ; 

int _ fmbsnicmp( const unsigned char _ far *sl, 

const unsigned char _far *s2, 

size_ t n ) ; 

The strnicmp function compares, without case sensitivity, the string pointed to by si to the string 
pointed to by s2, for at most len characters. 

The _ strnicmp function is identical tostrnicmp. Use _ strnicmp for ANSI naming 
conventions. 

The _ f strnicmp function is a data model independent form of the strnicmp function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The _ wcsnicmp function is a wide-character version ofstrnicmp that operates with wide-character 
strings. 

The _ mbsnicmp function is a multibyte character version ofstrnicmp that operates with multibyte 
character strings. 

The _ fmbsnicmp function is a data model independent form of the _mbsnicmp function that accepts 
far pointer arguments. It is most useful in mixed memory model applications. 

The strnicmp function returns an integer less than, equal to, or greater than zero, indicating that the 
string pointed to by si is less than, equal to, or greater than the string pointed to by s2. 

strcmp, stricmp, strncmp 


♦include <stdio.h> 
♦include <string.h> 


void main() 

{ 

printf( 

"%d\n", strnicmp( 

"abcdef", 

"ABCXXX", 

10 ) 

) ; 

printf( 

"%d\n", strnicmp! 

"abcdef", 

"ABCXXX", 

6 ) 

) ; 

printf( 

"%d\n", strnicmp! 

"abcdef", 

"ABCXXX", 

3 ) 

) ; 

printf( 

"%d\n", strnicmp! 

"abcdef", 

"ABCXXX", 

0 ) 

); 


} 
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strnicmp, _stmicmp, _fstrnicmp, _wcsnicmp, _mbsnicmp, _fmbsnicmp 


produces the following: 


-20 

-20 

0 

0 

Classification: WATCOM 

_strnicmp conforms to ANSI naming conventions 


Systems: strnicmp - All, Linux, RDOS, Netware 

_ strnicmp - All, Linux, RDOS, Netware 
_ fstrnicmp - All, Linux, RDOS 
_ wcsnicmp - All, Linux 

_ mbsnicmp - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
_ fmbsnicmp - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
RDOS 


RDOS 
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Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


strnicoll, _wcsnicoll, _mbsnicoll 


♦include <string.h> 
int _ strnicoll( const char *sl, 
const char *s2, 
size_ t count ); 

♦include <wchar.h> 

int _ wcsnicoll ( const wchar_ t *sl, 
const wchar_t *s2, 
size_ t count ); 

♦include <mbstring.h> 

int _ mbsnicoll( const unsigned char *sl, 
const unsigned char *s2, 
size_ t count ); 

These functions perform a case insensitive comparison of the first count characters of the string pointed 
to by si to the string pointed to by s2. The comparison uses the current code page which can be 
selected by the _ setmbcp function. 

The _ wcsnicoll function is a wide-character version of_ strnicoll that operates with 
wide-character strings. 

The _ mbsnicoll function is a multibyte character version of_ strnicoll that operates with 
multibyte character strings. 

These functions return an integer less than, equal to, or greater than zero, indicating that the string 
pointed to by si is less than, equal to, or greater than the string pointed to by s2, according to the 
collating sequence selected. 

_ setmbcp,strcoll, stricmp, _ stricoll,strncmp, _ strncoll,strnicmp 

♦include <stdio.h> 

♦include <string.h> 

char buffer[80] = "world"; 

void main() 

{ 

int test; 

test = _ strnicoll( buffer, "World2", 5 ); 
if( test < 0 ) { 

printf ( "Less than\n" ); 

} else if( test == 0 ) { 

printf ( "Equal\n" ); 

} else { 

printf ( "Greater than\n" ); 

} 

} 

WATCOM 

_ strnicoll - All, Linux, RDOS, Netware 
_ wcsnicoll - All, Linux 

_ mbsnicoll - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 

RDOS 
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_strninc, 

Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


wcsninc, ^mbsninc, Jmbsninc 


#ninclude <tchar.h> 

char *_ strninc ( const char *str, size_ t count ); 
wchar_ t *_ wcsninc( const wchar_ t *str, size_ t count ); 

#ninclude <mbstring.h> 

unsigned char *_ mbsninc( const unsigned char *str, 

size_ t count ); 

unsigned char_far *_ fmbsninc ( 

const unsigned char _ far *str, 

size_ t count ); 

The _ mbsninc function increments str by count multibyte characters. _ mbsninc recognizes 
multibyte-character sequences according to the multibyte code page currently in use. The header file 
<tchar . h> defines the generic-text routine _ tcsninc. This macro maps to_ mbsninc if_ MBCS 
has been defined, or to _ wcsninc if_ UNICODE has been defined. Otherwise_ tcsninc maps to 
_strninc. _ strninc and_ wcsninc are single-byte-character string and wide-character string 
versions of _mbsninc. _ wcsninc and_ strninc are provided only for this mapping and should not 
be used otherwise. 

The _ strninc function returns a pointer to str after it has been incremented by count characters or 
NULL if str was NULL. If count exceeds the number of characters remaining in the string, the result is 
undefined. 

_ strdec,_ strinc 
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stminc, _wcsninc, _mbsninc, Jmbsninc 


#ninclude <stdio.h> 

#ninclude <mbctype.h> 

#ninclude <mbstring.h> 

const unsigned char chars[] = { 

r r 

r 

r r 
• r 

'i', 

'A' , 

0x81,0x40, /* double-byte space */ 

0x82,0x60, /* double-byte A */ 

0x82,0xA6, /* double-byte Hiragana */ 

0x83,0x42, /* double-byte Katakana */ 

OxAl, /* single-byte Katakana punctuation */ 

0xA6, /* single-byte Katakana alphabetic */ 

OxDF, /* single-byte Katakana alphabetic */ 

0xE0,0xAl, /* double-byte Kanji */ 

0x00 

} ; 

♦ define SIZE sizeof ( chars ) / sizeof( unsigned char ) 

void main() 

{ 

int j, k; 

const unsigned char *next; 

_ setmbcp( 932 ) ; 
next = chars; 
do { 

next = _ mbsninc ( next, 1 ); 
j = mblen ( next, MB_ CUR_ MAX ); 
if( j == 0 ) { 
k = 0; 

} else if ( j == 1 ) { 

k = *next; 

} else if( j == 2 ) { 

k = *(next)<<8 | *(next+l); 

} 

printf( "Next character %#6.4x\n", k ); 

} while( next != Schars[ SIZE - 1 ] ); 

} 

produces the following: 

Next character 0x002e 
Next character 0x0031 
Next character 0x0041 
Next character 0x8140 
Next character 0x8260 
Next character 0x82a6 
Next character 0x8342 
Next character OxOOal 
Next character 0x00a6 
Next character OxOOdf 
Next character OxeOal 
Next character 0000 


Library Functions and Macros 1079 




strninc, _wcsninc, _mbsninc, Jmbsninc 


Classification: WATCOM 

Systems: _ strninc - MACRO 

_ wcsninc - MACRO 

_ mbsninc - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
_ fmbsninc - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 


RDOS 

RDOS 
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Synopsis: 


Description: 


Returns: 
See Also: 
Example: 


strnset, _stmset, Jstrnset, _wcsnset, _mbsnset, Jmbsnset 


#include <string.h> 

char *strnset( char *str, int fill, size_ t count ); 
char *_ strnset ( char *str, int fill, size_ t count ) ; 

char_far *_ fstrnset ( char_far *str, 

int fill, 
size_ t count ); 

♦include <wchar.h> 

wchar_ t *_ wcsnset ( wchar_ t *str, int fill, size_ t count ); 

♦include <mbstring.h> 

unsigned char *_ mbsnset( unsigned char *str, 

unsigned int fill, 
size_ t count ); 

unsigned char_far *_ fmbsnset ( unsigned char_far *str, 

unsigned int fill, 
size_ t count ); 

The strnset function fills the string str with the value of the argument/;//, converted to be a 
character value. When the value of count is greater than the length of the string, the entire string is 
filled. Otherwise, that number of characters at the start of the string are set to the fill character. 

The _ strnset function is identical tostrnset. Use _ strnset for ANSI naming conventions. 

The _ fstrnset function is a data model independent form of the strnset function. It accepts far 
pointer arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The _ wcsnset function is a wide-character version ofstrnset that operates with wide-character 
strings. For _wcsnset, the value of count is the number of wide characters to fill. This is half the 
number of bytes. 

The _ mbsnset function is a multibyte character version ofstrnset that operates with multibyte 
character strings. 

The _ fmbsnset function is a data model independent form of the _mbsnset function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

For _mbsnset, the value of count is the number of multibyte characters to fill. If the number of bytes to 
be filled is odd and fill is a double-byte character, the partial byte at the end is filled with an ASCII 
space character. 

The address of the original string str is returned, 
strset 

♦include <stdio.h> 

♦include <string.h> 

char source!] = { "A sample STRING" }; 

void main() 

{ 

printf ( "%s\n", source ); 

printf ( "%s\n", strnset! source, '=', 100 ) ); 
printf ( "%s\n", strnset! source, 7 ) ); 

} 
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stmset, _strnset, Jstrnset, _wcsnset, _mbsnset, Jmbsnset 


produces the following: 
A sample STRING 




Classification: WATCOM 

_strnset conforms to ANSI naming conventions 


Systems: strnset - All, Linux, RDOS, Netware 

_ strnset - All, Linux, RDOS, Netware 
_ fstrnset - All, Linux, RDOS 
_ wcsnset - All, Linux 

_ mbsnset - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
_ fmbsnset - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 


RDOS 

RDOS 
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Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


strpbrk, Jstrpbrk, wcspbrk, _mbspbrk, Jmbspbrk 


#include <string.h> 

char *strpbrk( const char *str, const char *charset ); 

char_far *_ fstrpbrk( const char_far *str, 

const char_far *charset ) ; 

#include <wchar.h> 

wchar_ t *wcspbrk( const wchar_t *str, 

const wchar_ t *charset ); 

♦include <mbstring.h> 

unsigned char *_ mbspbrk( const unsigned char *str, 

const unsigned char *charset ); 

unsigned char_far *_ fmbspbrk ( 

const unsigned char _ far *str, 

const unsigned char _ far *charset ); 

The strpbrk function locates the first occurrence in the string pointed to by str of any character from 
the string pointed to by charset. 

The _ f strpbrk function is a data model independent form of the strpbrk function. It accepts far 
pointer arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The wcspbrk function is a wide-character version of strpbrk that operates with wide-character 
strings. 

The _ mbspbrk function is a multibyte character version ofstrpbrk that operates with multibyte 
character strings. 

The _ fmbspbrk function is a data model independent form of the _mbspbrk function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The strpbrk function returns a pointer to the located character, or NULL if no character from charset 
occurs in str. 

strchr, strrchr, strtok 

♦include <stdio.h> 

♦include <string.h> 

void main() 

{ 

char *p = "Find all vowels"; 

while( P ! = NULL ) { 

printf( "%s\n", p ); 
p = strpbrk( p+1, "aeiouAEIOU" ); 

} 

} 

produces the following: 

Find all vowels 
ind all vowels 
all vowels 
owe Is 
els 
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strpbrk, Jstrpbrk, wcspbrk, _mbspbrk, Jmbspbrk 


Classification: ISO C 

Jstrpbrk is WATCOM 
_mbspbrk is WATCOM 
Jmbspbrk is WATCOM 

Systems: strpbrk - All, Linux, RDOS, Netware 

_ fstrpbrk - All, Linux, RDOS 
wcspbrk - All, Linux 

_ mbspbrk - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ fmbspbrk - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


strrchr, Jstrrchr, wcsrchr, _mbsrchr, _fmbsrchr 


#include <string.h> 

char *strrchr( const char *s, int c ); 

char_far *_ fstrrchr( const char_far *s, int c ) ; 

♦include <wchar.h> 

wchar_ t *wcsrchr( const wchar_ t *s, wint_ t c ); 

♦include <mbstring.h> 

unsigned char *_ mbsrchr( const unsigned char *s, 

unsigned int c ); 

unsigned char_far *_ fmbsrchr ( 

const unsigned char _far *s, 

unsigned int c ); 

The strrchr function locates the last occurrence of c (converted to a char) in the string pointed to by 
s. The terminating null character is considered to be part of the string. 

The _ f strrchr function is a data model independent form of the strrchr function. It accepts far 
pointer arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The wcsrchr function is a wide-character version of strrchr that operates with wide-character 
strings. 

The _ mbsrchr function is a multibyte character version ofstrrchr that operates with multibyte 
character strings. 

The _ fmbsrchr function is a data model independent form of the _mbsrchr function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The strrchr function returns a pointer to the located character, or a NULL pointer if the character 
does not occur in the string. 

strchr, strpbrk 

♦include <stdio.h> 

♦include <string.h> 

void main() 

{ 

printf ( "%s\n", strrchr( "abcdeaaklmn", 'a' ) ); 

if ( strrchr( "abcdeaaklmn", 'x' ) == NULL ) 
printf ( "NULL\n" ); 

} 

produces the following: 

aklmn 

NULL 

ISOC 

_fstrrchr is WATCOM 
_mbsrchr is WATCOM 
_fmbsrchr is WATCOM 

strrchr - All, Linux, RDOS, Netware 
_ fstrrchr - All, Linux, RDOS 
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strrchr, Jstrrchr, wcsrchr, _mbsrchr, _fmbsrchr 


wcsrchr - All, Linux 

_ mbsrchr - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
_ fmbsrchr - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 


RDOS 

RDOS 
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Synopsis: 


Description: 


Returns: 

Example: 


Classification: 

Systems: 


strrev, _strrev, Jstrrev, _wcsrev, _mbsrev, Jmbsrev 


#include <string.h> 

char *strrev( char *sl ); 

char *_ strrev( char *sl ); 

char_far *_ fstrrev( char_far *sl ) ; 

♦include <wchar.h> 

wchar_ t *_ wcsrev ( wchar_ t *sl ) ; 

♦include <mbstring.h> 

unsigned char *_mbsrev( unsigned char *sl ); 

unsigned char_far *_ fmbsrev( unsigned char_far *sl ) ; 

The strrev function replaces the string si with a string whose characters are in the reverse order. 

The _ strrev function is identical tostrrev. Use _ strrev for ANSI naming conventions. 

The _ f strrev function is a data model independent form of the strrev function. It accepts far pointer 
arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The _ wcsrev function is a wide-character version ofstrrev that operates with wide-character 
strings. 

The _ mbsrev function is a multibyte character version ofstrrev that operates with multibyte 
character strings. 

The _ fmbsrev function is a data model independent form of the _mbsrev function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The address of the original string si is returned. 


♦include <stdio.h> 
♦include <string.h> 


"A sample STRING" } ; 


char source[] = { 

void main() 

1 

printf ( "%s\n", 
printf ( "%s\n", 
printf ( "%s\n", 

} 

produces the following: 

A sample STRING 
GNIRTS elpmas A 
A sample STRING 


source ) ; 

strrev( source ) ); 

strrev( source ) ); 


WATCOM 

_strrev conforms to ANSI naming conventions 

strrev - All, Linux, RDOS, Netware 
_ strrev - All, Linux, RDOS, Netware 
_ fstrrev - All, Linux, RDOS 
_ wcsrev - All, Linux 

_ mbsrev - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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strrev, _strrev, Jstrrev, _wcsrev, _mbsrev, Jmbsrev 


fmbsrev - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 


RDOS 
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Synopsis: 


Description: 


Returns: 
See Also: 
Example: 


Classification: 


strset, _strset, Jstrset, _wcsset, _mbsset, Jmbsset 


#include <string.h> 

char *strset( char *sl, int fill ); 
char *_ strset ( char *sl, int fill ); 

char_far *_ fstrset ( char_far *sl, int fill ) ; 

#include <wchar.h> 

wchar_ t *_ wcsset ( wchar_ t *sl, int fill ); 

♦include <mbstring.h> 

unsigned char *_ mbsset( unsigned char *sl, 

unsigned int fill ); 

unsigned char_far *_ fmbsset ( unsigned char_far *sl, 

unsigned int fill ); 

The strset function fills the string pointed to by si with the character////. The terminating null 
character in the original string remains unchanged. 

The _ strset function is identical tostrset. Use _ strset for ANSI naming conventions. 

The _ fstrset function is a data model independent form of the strset function. It accepts far pointer 
arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The _ wcsset function is a wide-character version ofstrset that operates with wide-character 
strings. 

The _ mbsset function is a multibyte character version ofstrset that operates with multibyte 
character strings. 

The _ fmbsset function is a data model independent form of the _mbsset function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The address of the original string si is returned. 

strnset 

♦include <stdio.h> 

♦include <string.h> 

char source [] = { "A sample STRING" }; 

void main() 

{ 

printf ( "%s\n", source ); 

printf ( "%s\n", strset ( source, '=' ) ); 

printf ( "%s\n", strset ( source, ) ); 

} 

produces the following: 

A sample STRING 
★★★★★★★★★★★★★★★ 

WATCOM 

_strset conforms to ANSI naming conventions 
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strset, _strset, Jstrset, _wcsset, _mbsset, Jmbsset 


Systems: strset - All, Linux, RDOS, Netware 

_ strset - All, Linux, RDOS, Netware 
_ fstrset - All, Linux, RDOS 
_ wcsset - All, Linux 

_ mbsset - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
_ fmbsset - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 


RDOS 

RDOS 
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Synopsis: 


Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


strspn, Jstrspn, wcsspn, _mbsspn, Jmbsspn 


#include <string.h> 

size_ t strspn( const char *str, 

const char *charset ); 

size_ t _fstrspn( const char _far *str, 

const char_far *charset ) ; 

♦include <wchar.h> 

size_ t wcsspn( const wchar_t *str, 

const wchar_ t *charset ); 

♦include <wchar.h> 

size_ t _ mbsspn( const unsigned char *str, 

const unsigned char *charset ); 

size_ t _ fmbsspn( const unsigned char _ far *str, 

const unsigned char_far *charset ) ; 

The strspn function computes the length, in bytes, of the initial segment of the string pointed to by 
sir which consists of characters from the string pointed to by charset. The terminating null character is 
not considered to be part of charset. 

The _ f strspn function is a data model independent form of the strspn function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The wcsspn function is a wide-character version of strspn that operates with wide-character strings. 

The _ mbsspn function is a multibyte character version ofstrspn that operates with multibyte 
character strings. 

The _ fmbsspn function is a data model independent form of the _mbsspn function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The length, in bytes, of the initial segment is returned. 

strcspn, strspnp 

♦include <stdio.h> 

♦include <string.h> 

void main() 

{ 

printf ( "%d\n", strspn( "out to lunch", "aeiou" ) ); 
printf ( "%d\n", strspn( "out to lunch", "xyz" ) ); 

} 

produces the following: 

2 

0 

ISOC 

_fstrspn is WATCOM 
_mbsspn is WATCOM 
_fmbsspn is WATCOM 

strspn - All, Linux, RDOS, Netware 
_ fstrspn - All, Linux, RDOS 


Library Functions and Macros 1091 




strspn, Jstrspn, wcsspn, _mbsspn, Jmbsspn 


wcsspn - All, Linux 

_ mbsspn - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ fmbsspn - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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Synopsis: 


Description: 


Returns: 
See Also: 
Example: 


Classification: 


strspnp, _strspnp, Jstrspnp, _wcsspnp, _mbsspnp, Jmbsspnp 


#include <string.h> 

char *strspnp( const char *str, 

const char *charset ); 
char *_ strspnp ( const char *str, 

const char *charset ); 

char_far *_ fstrspnp( const char_far *str, 

const char_far *charset ) ; 

♦include <tchar.h> 

wchar_ t *_ wcsspnp ( const wchar_ t *str, 

const wchar_ t *charset ); 

♦include <mbstring.h> 

unsigned char *_mbsspnp( const unsigned char *str, 

const unsigned char *charset ); 

unsigned char_far *_fmbsspnp( 

const unsigned char _ far *str, 

const unsigned char _ far *charset ); 

The strspnp function returns a pointer to the first character in sir that does not belong to the set of 
characters in charset. The terminating null character is not considered to be part of charset. 

The _ strspnp function is identical tostrspnp. Use _ strspnp for ANSI naming conventions. 

The _ f strspnp function is a data model independent form of the strspnp function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The _ wcsspnp function is a wide-character version ofstrspnp that operates with wide-character 
strings. 

The _ mbsspnp function is a multibyte character version ofstrspnp that operates with multibyte 
character strings. 

The _ fmbsspnp function is a data model independent form of the _mbsspnp function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The strspnp function returns NULL if sir consists entirely of characters from charset. 

strcspn, strspn 

♦include <stdio.h> 

♦include <string.h> 

void main() 

{ 

printf ( "%s\n", strspnp( "out to lunch", "aeiou" ) ); 
printf ( "%s\n", strspnp( "out to lunch", "xyz" ) ); 

} 

produces the following: 

t to lunch 
out to lunch 

WATCOM 

_strspnp conforms to ANSI naming conventions 
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strspnp, _strspnp, Jstrspnp, _wcsspnp, _mbsspnp, Jmbsspnp 


Systems: strspnp - All, Linux, RDOS, Netware 

_ strspnp - All, Linux, RDOS, Netware 
_ fstrspnp - All, Linux, RDOS 
_ wcsspnp - All, Linux 

_ mbsspnp - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ fmbsspnp - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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Synopsis: 


Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


strstr, Jstrstr, wcsstr, _mbsstr, Jmbsstr 


#include <string.h> 

char *strstr( const char *str, 

const char *substr ); 

char_far *_ fstrstr( const char_far *str, 

const char _ far *substr ); 

♦include <wchar.h> 

wchar_ t *wcsstr( const wchar_ t *str, 

const wchar_ t *substr ) ; 

♦include <mbstring.h> 

unsigned char *_mbsstr( const unsigned char *str, 

const unsigned char *substr ); 

unsigned char_far *_fmbsstr( 

const unsigned char _ far *str, 

const unsigned char _ far *substr ); 

The strstr function locates the first occurrence in the string pointed to by sir of the sequence of 
characters (excluding the terminating null character) in the string pointed to by substr. 

The _ f strstr function is a data model independent form of the strstr function. It accepts far pointer 
arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The wcsstr function is a wide-character version of strstr that operates with wide-character strings. 

The _ mbsstr function is a multibyte character version ofstrstr that operates with multibyte 
character strings. 

The _ fmbsstr function is a data model independent form of the _mbsstr function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The strstr function returns a pointer to the located string, or NULL if the string is not found. 

strcspn 

♦include <stdio.h> 

♦include <string.h> 

void main() 

{ 

printf ( "%s\n", strstr("This is an example", "is") ); 

} 

produces the following: 
is is an example 
ISOC 

_fstrstr is WATCOM 
wcsstr is ISO C95 
_mbsstr is WATCOM 
_fmbsstr is WATCOM 

strstr - All, Linux, RDOS, Netware 
_ fstrstr - All, Linux, RDOS 
wcsstr - All, Linux 
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strstr, Jstrstr, wcsstr, _mbsstr, Jmbsstr 


mbsstr - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
fmbsstr - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 


RDOS 

RDOS 
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Synopsis: 

Description: 


Returns: 
See Also: 

Example: 


Classification: 

Systems: 


strtime, _wstrtime 


#include <time.h> 

char *_ strtime( char *timestr ) 

wchar_ t _ wstrtime( wchar_ t *timestr ); 

The _ strtime function copies the current time to the buffer pointed to by timestr. The time is 
formatted as "HH:MM:SS" where "HH" is two digits representing the hour in 24-hour notation, where 
"MM" is two digits representing the minutes past the hour, and where "SS" is two digits representing 
seconds. The buffer must be at least 9 bytes long. 

The _ wstrtime function is a wide-character version of_ strtime that operates with wide-character 
strings. 

The _ strtime function returns a pointer to the resulting text string timestr. 

asctime Functions, ctime Functions, gmtime, localtime, mktime, _ strdate.time, 
tzset 

♦include <stdio.h> 

♦include <time.h> 

void main() 

{ 

char timebuff[9]; 

printf ( "%s\n", _ strtime( timebuff ) ); 

} 

WATCOM 

_ strtime - All, Linux, RDOS 
_ wstrtime - All, Linux 
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strtod, wcstod 


Synopsis: #include <stdlib.h> 

double strtod( const char *ptr, char **endptr ); 

♦include <wchar.h> 

double wcstod( const wchar_t *ptr, wchar_t **endptr ); 

Description: The strtod function converts the string pointed to by ptr to double representation. First, it 
decompose the input string into three parts: an initial, possibly empty, sequence of white-space 
characters (as specified by the isspace function), a subject sequence resembling a floating-point 
constant or representing an infinity or NaN; and a final string of one or more unrecognized characters, 
including the terminating null character of the input string. Then, it attempts to convert the subject 
sequence to a floating-point number, and return the result. 

The expected form of the subject sequence is an optional plus or minus sign, then one of the following: 

• a decimal floating-point number 

• a hexadecimal floating-point number 

• INF or INFINITY, ignoring case 

• NAN, ignoring case, optionally followed by a sequence of digits and nondigits (upper- or 
lowercase characters or underscore) enclosed in parentheses. 

The subject sequence is defined as the longest initial subsequence of the input string, starting with the 
first non-whitespace character, that is of the expected form. The subject sequence contains no 
characters if the input string is not of the expected form. 

A decimal floating-point number recognized by strtod (after optional sign was processed) is a string 
containing: 

• a sequence of digits containing an optional decimal point, 

• an optional ’e’ or ’E’ followed by an optionally signed sequence of digits. 

A hexadecimal floating-point number recognized by strtod (after optional sign was processed) is a 
string containing: 

• a OX prefix, ignoring case, 

• a sequence of hexadecimal digits containing an optional decimal point, 

• an optional ’p’ or ’P’ followed by an optionally signed sequence of decimal digits. 

The subject sequence is defined as the longest initial subsequence of the input string, starting with the 
first non-white-space character, that is of the expected form. The subject sequence contains no 
characters if the input string is not of the expected form. 

If the subject sequence contains NAN, a NaN (with appropriate sign) will be returned; the optional 
digit-nondigit sequence is ignored. If the subject sequence contains INF, the value of infinity (with 
appropriate sign) will be returned. This case can be distinguished from overflow by checking errno. 

For a hexadecimal floating-point number, the optional exponent is binary (that is, denotes a power of 
two), not decimal. 

A pointer to the final string (following the subject sequence) will be stored in the object to which endptr 
points if endptr is not NULL . By comparing the "end" pointer with ptr, it can be determined how much 
of the string, if any, was scanned by the strtod function. 

The wcstod function is a wide-character version of strtod that operates with wide-character strings. 
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strtod, wcstod 


Returns: 


See Also: 
Example: 


Classification: 

Systems: 


The strtod function returns the converted value, if any. If no conversion could be performed, zero is 
returned. If the correct value would cause overflow, plus or minus HUGE_ VAL is returned according to 
the sign, and errno is set to ERANGE. If the correct value would cause underflow, then zero is 
returned, and errno is set to ERANGE. Zero is returned when the input string cannot be converted. In 
this case, errno is not set. When an error has occurred, errno contains a value indicating the type of 
error that has been detected. 

atof 

♦include <stdio.h> 

♦include <stdlib.h> 

void main( void ) 

{ 

double pi; 

pi = strtod( "3.141592653589793", NULL ); 
printf ( "pi=%17.15f\n",pi ); 

} 

ISO C90 

strtod - Math 
wcstod - Math 
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strtok, strtok_r, Jstrtok, _fstrtok_r, wcstok, _mbstok, _mbstok_r, Jmbstok, _fmbstok_r 


Synopsis: #include <string.h> 

char *strtok( char *sl, const char *s2 ); 

char *strtok_r( char *sl, const char *s2, char **pl ); 

char_far *_ fstrtok( char_far *sl, 

const char_far *s2 ) ; 

char_far *_ fstrtok_ r( char_far *sl, 

const char _far *s2, 

char _ far **pl ); 

#include <wchar.h> 

wchar_ t *wcstok ( wchar_ t *sl, const wchar_ t *s2, 
wchar_ t **ptr ); 

♦include <mbstring.h> 

unsigned char *_ mbstok( unsigned char *sl, 

const unsigned char *s2 ); 
unsigned char *_ mbstok_ r ( unsigned char *sl, 

const unsigned char *s2, 
unsigned char **pl ) ; 

unsigned char_far *_ fmbstok( unsigned char_far *sl, 

const unsigned char _ far *s2 ); 

unsigned char_far *_ fmbstok_ r ( unsigned char_far *sl, 

const unsigned char _far *s2, 

unsigned char _ far **pl ); 

Safer C: The Safer C Library extension provides the strtok_ s function which is a safer alternative to 

strtok This newer strtok_ s function is recommended to be used instead of the traditional "unsafe" 
strtok function. 

Description: The strtok function is used to break the string pointed to by si into a sequence of tokens, each of 

which is delimited by a character from the string pointed to by s2. The first call to strtok will return 
a pointer to the first token in the string pointed to by si. Subsequent calls to strtok must pass a 
NULL pointer as the first argument, in order to get the next token in the string. The set of delimiters 
used in each of these calls to strtok can be different from one call to the next. 

The first call in the sequence searches si for the first character that is not contained in the current 
delimiter string s2. If no such character is found, then there are no tokens in si and the strtok 
function returns a NULL pointer. If such a character is found, it is the start of the first token. 

The strtok function then searches from there for a character that is contained in the current delimiter 
string. If no such character is found, the current token extends to the end of the string pointed to by si. 

If such a character is found, it is overwritten by a null character, which terminates the current token. 

The strtok function saves a pointer to the following character, from which the next search for a token 
will start when the first argument is a NULL pointer. 

Because strtok may modify the original string, that string should be duplicated if the string is to be 
re-used. 

The reentrant form of this function, strtok_ r , also requires a pointer to a string pointer to be passed. 
This pointer is used internally by the function for subsequent calls to perform tokenizing without 
relying on internal state within the function. 

The _ f strtok function is a data model independent form of the strtok function. It accepts far pointer 
arguments and returns a far pointer. It is most useful in mixed memory model applications. 
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strtok, strtok_r, Jstrtok, _fstrtok_r, wcstok, _mbstok, _mbstok_r, Jmbstok, _fmbstok_r 


The wcstok function is a wide-character version of strtok that operates with wide-character strings. 
The third argument ptr points to a caller-provided wchar_ t pointer into which thewcstok function 
stores information necessary for it to continue scanning the same wide string. 

On the first call in the sequence of calls to wcstok, si points to a wide string. In subsequent calls for the 
same string, si must be NULL. If si is NULL, the value pointed to by ptr matches that set by the 
previous call to wcstok for the same wide string. Otherwise, the value of ptr is ignored. The list of 
delimiters pointed to by s2 may be different from one call to the next. The tokenization of si is similar 
to that for the strtok function. 

The _ mbstok_ r function is a multibyte character version ofetrtok that operates with multibyte 
character strings. 

The _ fmbstok_ r function is a data model independent form of the _mbstok_r function that accepts 
far pointer arguments. It is most useful in mixed memory model applications. 

Returns: The strtok function returns a pointer to the first character of a token or NULL if there is no token 

found. 

See Also: strcspn, strpbrk, strtok_ s 

Example: #include <stdio.h> 

♦include <string.h> 

void main() 

{ 

char *p; 

char *buffer; 

char *delims = { " }; 

buffer = strdup( "Find words, all of them." ); 
printf( "%s\n", buffer ); 
p = strtok( buffer, delims ) ; 
while( P != NULL ) { 

printf( "word: %s\n", p ) ; 
p = strtok( NULL, delims ); 

} 

printf! "%s\n", buffer ); 

} 

produces the following: 

Find words, all of them. 


word: 

Find 

word: 

words 

word: 

all 

word: 

of 

word: 

them 

Find 


Classification: ISO C 



strtok_r is WATCOM 
_fstrtok is WATCOM 
_fstrtok_r is WATCOM 
wcstok is ISO C95 
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strtok, strtok_r, Jstrtok, _fstrtok_r, wcstok, _mbstok, _mbstok_r, Jmbstok, _fmbstok_r 


_mbstok is WATCOM 
_mbstok_r is WATCOM 
_fmbstok is WATCOM 
_fmbstok_r is WATCOM 

Systems: strtok - All, Linux, RDOS, Netware 

strtok_ r - All, Linux, RDOS, Netware 
_ fstrtok - All, Linux, RDOS 
_ fstrtok_ r - All, Linux, RDOS 
wcstok - All, Linux 

_ mbstok - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ mbstok_ r - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS 
_ fmbstok - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ fmbstok_ r - DOS, Windows, Win386, Win32, OS/2 1.x (all), OS/2-32, 

RDOS 
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strtok_s, wcstok_s 


Synopsis: 


Constraints: 


Description: 


Returns: 


See Also: 


♦ define_ STDC_ WANT_ LIB_ EXT1_1 

♦include <string.h> 

char *strtok_ s ( char * restrict si, 

rsize_ t * restrict slmax, 
const char * restrict s2, 
char ** restrict ptr); 

♦include <wchar.h> 

wchar_ t *wcstok_ s ( wchar_ t * restrict si, 

rsize_ t * restrict slmax, 
const wchar_ t * restrict s2, 
wchar_ t ** restrict ptr); 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and strtok_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

None of slmax, s2, or ptr shall be a null pointer. If si is a null pointer.then *ptr shall not be a null 
pointer. The value of *slmax shall not be greater than RSIZE_ MAX. The end of the token found shall 
occur within the first *slmax characters of ,v / for the first call, and shall occur within the first *slmax 
characters of where searching resumes on subsequent calls. If there is a runtime-constraint violation, 
the strtok_ s function does not indirect through the si or s2 pointers, and does not store a value in the 
object pointed to by ptr. 

A sequence of calls to the strtok_ s function breaks the string pointed to by si into a sequence of 
tokens, each of which is delimited by a character from the string pointed to by s2. The fourth argument 
points to a caller-provided char pointer into which the strtok_ s function stores information 
necessary for it to continue scanning the same string. The first call in a sequence has a non-null first 
argument and slmax points to an object whose value is the number of elements in the character array 
pointed to by the first argument. The first call stores an initial value in the object pointed to by ptr and 
updates the value pointed to by slmax to reflect the number of elements that remain in relation to ptr. 
Subsequent calls in the sequence have a null first argument and the objects pointed to by slmax and ptr 
are required to have the values stored by the previous call in the sequence, which are then updated. The 
separator string pointed to by s2 may be different from call to call. The first call in the sequence 
searches the string pointed to by si for the first character that is not contained in the current separator 
string pointed to by s2. If no such character is found, then there are no tokens in the string pointed to by 
si and the strtok_ s function returns a null pointer. If such a character is found, it is the start of the 
first token. The strtok_ s function then searches from there for the first character in si that is 
contained in the current separator string. If no such character is found, the current token extends to the 
end of the string pointed to by si, and subsequent searches in the same string for a token return a null 
pointer. If such a character is found, it is overwritten by a null character, which terminates the current 
token. In all cases, the strtok_ s function stores sufficient information in the pointer pointed to by 
ptr so that subsequent calls, with a null pointer for si and the unmodified pointer value for ptr, shall 
start searching just past the element overwritten by a null character (if any). 

The wcstok_ s function is a wide-character version ofstrtok_ s that operates with wide-character 
strings. 

The strtok_ s function returns a pointer to the first character of a token, or a null pointer if there is no 
token or there is a runtime-constraint violation. 

strtok, strcspn, strpbrk 
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strtok_s, wcstok_s 


Example: 


Classification: 

Systems: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <string.h> 


void main( void ) 
{ 


char 

*p; 


char 

*buffer; 


char 

*delims 

= { " 1 ; 

size_ t 

buflen; 


char 

*ptr; 


buffer 

= strdup( 

"Find words. 

printf( 

" % s \ n " , 

buffer ); 

buflen 

= strlen( 

buffer ); 


p = strtok_ s ( buffer, Sbuflen 
while( p != NULL ) { 

printf ( "word: %s\n", p ); 
p = strtok_ s ( NULL, Sbuflen 


all of them." 


, delims, &ptr 

, delims, &ptr 


} 


printf ( "%s\n", buffer ); 


} 


) ; 


) ; 

); 


produces the following: 

Find words, all of them. 

word: Find 

word: words 

word: all 

word: of 

word: them 

Find 

TR 24731 

strtok_ s - All, Linux, RDOS, Netware 
wcstok_ s - All, Linux 
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strtol, wcstol 


Synopsis: #include <stdlib.h> 

long int strtol ( const char *ptr, 
char **endptr, 
int base ); 

♦include <wchar.h> 

long int wcstol ( const wchar_ t *ptr, 
wchar_ t **endptr, 
int base ); 

Description: The strtol function converts the string pointed to by ptr to an object of type long int . The 
strtol function recognizes a string containing: 

• optional white space, 

• an optional plus or minus sign, 

• a sequence of digits and letters. 

The conversion ends at the first unrecognized character. A pointer to that character will be stored in the 
object to which endptr points if endptr is not NULL. 

If base is zero, the first characters after the optional sign determine the base used for the conversion. If 
the first characters are "Ox" or "OX" the digits are treated as hexadecimal. If the first character is ’O’, the 
digits are treated as octal. Otherwise the digits are treated as decimal. 

If base is not zero, it must have a value between 2 and 36. The letters a-z and A-Z represent the values 
10 through 35. Only those letters whose designated values are less than base are permitted. If the value 
of base is 16, the characters "Ox" or "OX" may optionally precede the sequence of letters and digits. 

The wcstol function is a wide-character version of strtol that operates with wide-character strings. 

Returns: The strtol function returns the converted value. If the correct value would cause overflow, 

LONG_ MAX orLONG_ MIN is returned according to the sign, anderrno is set to ERANGE. If base is 
out of range, zero is returned and errno is set to EDOM. 

See Also: atoi, atol, atoll, itoa, ltoa, lltoa, sscanf, strtoll, strtoul, strtoull, 

strtoimax, strtoumax, ultoa, ulltoa, utoa 

Example: #include <stdlib.h> 

void main () 

{ 

long int v; 

v = strtol( "12345678", NULL, 10 ); 

} 

Classification: ISO C 

Systems: strtol - All, Linux, RDOS, Netware 

wcstol - All, Linux, RDOS 
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strtoll, wcstoll 


Synopsis: 


Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <stdlib.h> 

long long int strtoll ( const char *ptr, 

char **endptr, 
int base ); 

♦include <wchar.h> 

long long int wcstoll( const wchar_t *ptr, 

wchar_ t **endptr, 
int base ); 

The strtoll function converts the string pointed to by ptr to an object of type long long int. 
The strtoll function recognizes a string containing: 

• optional white space, 

• an optional plus or minus sign, 

• a sequence of digits and letters. 

The conversion ends at the first unrecognized character. A pointer to that character will be stored in the 
object to which endptr points if endptr is not NULL. 

If base is zero, the first characters after the optional sign determine the base used for the conversion. If 
the first characters are "Ox" or "OX" the digits are treated as hexadecimal. If the first character is ’O’, the 
digits are treated as octal. Otherwise the digits are treated as decimal. 

If base is not zero, it must have a value between 2 and 36. The letters a-z and A-Z represent the values 
10 through 35. Only those letters whose designated values are less than base are permitted. If the value 
of base is 16, the characters "Ox" or "OX" may optionally precede the sequence of letters and digits. 

The wcstoll function is a wide-character version of strtoll that operates with wide-character 
strings. 

The strtoll function returns the converted value. If the correct value would cause overflow, 
LLONG_ MAX orLLONG_ MIN is returned according to the sign, anderrno is set to ERANGE. If base 
is out of range, zero is returned and errno is set to EDOM. 

atoi, atol, atoll, itoa, ltoa, lltoa, sscanf, strtol, strtoul, strtoull, 
strtoimax, strtoumax, ultoa, ulltoa, utoa 

♦include <stdlib.h> 

void main() 

{ 

long long int v; 

v = strtol ( "12345678909876", NULL, 10 ); 

} 

ISOC 

strtoll - All, Linux, RDOS, Netware 
wcstoll - All, Linux, RDOS 
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strtoimax, wcstoimax 


Synopsis: 


Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <inttypes.h> 

intmax_ t strtoimax( const char *ptr, 

char **endptr, 
int base ); 

intmax_t wcstoimax( const wchar_t *ptr, 

wchar_ t **endptr, 
int base ); 

The strtoimax function converts the string pointed to by ptr to an object of type intmax_ t. The 
strtoimax function recognizes a string containing: 

• optional white space, 

• an optional plus or minus sign, 

• a sequence of digits and letters. 

The conversion ends at the first unrecognized character. A pointer to that character will be stored in the 
object to which endptr points if endptr is not NULL. 

If base is zero, the first characters after the optional sign determine the base used for the conversion. If 
the first characters are "Ox" or "OX" the digits are treated as hexadecimal. If the first character is ’O’, the 
digits are treated as octal. Otherwise the digits are treated as decimal. 

If base is not zero, it must have a value between 2 and 36. The letters a-z and A-Z represent the values 
10 through 35. Only those letters whose designated values are less than base are permitted. If the value 
of base is 16, the characters "Ox" or "OX" may optionally precede the sequence of letters and digits. 

The wcstoimax function is a wide-character version of strtoimax that operates with 
wide-character strings. 

The strtoimax function returns the converted value. If the correct value would cause overflow, 
INTMAX_ MAX orINTMAX_ MIN is returned according to the sign, anderrno is set to ERANGE. If 
base is out of range, zero is returned and errno is set to EDOM. 

atoi, atol, atoll, itoa, ltoa, lltoa, sscanf, strtol, strtoll, strtoul, strtoull, 
strtoumax, ultoa, ulltoa, utoa 

♦include <inttypes.h> 

♦include <stdlib.h> 

void main() 

{ 

intmax_ t v; 

v = strtoimax( "12345678909876", NULL, 10 ); 

} 

ISOC 

strtoimax - All, Linux, RDOS, Netware 
wcstoimax - All, Linux, RDOS 
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strtoul, wcstoul 


Synopsis: 


Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


#include <stdlib.h> 
unsigned long int strtoul ( 


♦include <wchar.h> 
unsigned long int wcstoul( 


const char *ptr, 
char **endptr, 
int base ); 

const wchar_ t *ptr, 
wchar_ t **endptr, 
int base ); 


The strtoul function converts the string pointed to by ptr to an unsigned long. The function 
recognizes a string containing optional white space, an optional sign (+ or -), followed by a sequence of 
digits and letters. The conversion ends at the first unrecognized character. A pointer to that character 
will be stored in the object endptr points to if endptr is not NULL. 

If base is zero, the first characters determine the base used for the conversion. If the first characters are 
"Ox" or "OX" the digits are treated as hexadecimal. If the first character is ’O’, the digits are treated as 
octal. Otherwise the digits are treated as decimal. 

If base is not zero, it must have a value of between 2 and 36. The letters a-z and A-Z represent the 
values 10 through 35. Only those letters whose designated values are less than base are permitted. If 
the value of base is 16, the characters "Ox" or "OX" may optionally precede the sequence of letters and 
digits. 

If there is a leading minus sign in the string, the value is negated. 

The wcstoul function is a wide-character version of strtoul that operates with wide-character 
strings. 

The strtoul function returns the converted value. If the correct value would cause overflow, 
ULONG_ MAX is returned anderrno is set to ERANGE. If base is out of range, zero is returned and 
errno is set to EDOM. 


atoi, atol, atoll, itoa, ltoa, lltoa, sscanf, strtol, strtoll, strtoull, 
strtoimax, strtoumax, ultoa, ulltoa, utoa 

♦include <stdlib.h> 

void main() 

{ 

unsigned long int v; 
v = strtoul ( "12345678", NULL, 10 ); 

} 

ISOC 

strtoul - All, Linux, RDOS, Netware 
wcstoul - All, Linux, RDOS 
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strtoull, wcstoull 


Synopsis: 


Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <stdlib.h> 

unsigned long long int strtoull ( 


♦include <wchar.h> 

unsigned long long int wcstoull( 


const char *ptr, 
char **endptr, 
int base ); 

const wchar_ t *ptr, 
wchar_ t **endptr, 
int base ); 


The strtoull function converts the string pointed to by ptr to an unsigned long long. The 
function recognizes a string containing optional white space, an optional sign (+ or -), followed by a 
sequence of digits and letters. The conversion ends at the first unrecognized character. A pointer to 
that character will be stored in the object endptr points to if endptr is not NULL. 

If base is zero, the first characters determine the base used for the conversion. If the first characters are 
"Ox" or "OX" the digits are treated as hexadecimal. If the first character is 'O’, the digits are treated as 
octal. Otherwise the digits are treated as decimal. 

If base is not zero, it must have a value of between 2 and 36. The letters a-z and A-Z represent the 
values 10 through 35. Only those letters whose designated values are less than base are permitted. If 
the value of base is 16, the characters "Ox" or "OX" may optionally precede the sequence of letters and 
digits. 

If there is a leading minus sign in the string, the value is negated. 

The wcstoull function is a wide-character version of strtoull that operates with wide-character 
strings. 

The strtoull function returns the converted value. If the correct value would cause overflow, 
ULLONG_ MAX is returned anderrno is set to ERANGE. If base is out of range, zero is returned and 
errno is set to EDOM. 


atoi, atol, atoll, itoa, ltoa, lltoa, sscanf, strtol, strtoll, strtoul, 
strtoimax, strtoumax, ultoa, ulltoa, utoa 

♦include <stdlib.h> 

void main() 

{ 

unsigned long long int v; 

v = strtoul ( "12345678909876", NULL, 10 ); 

} 


ISOC 


strtoull 

wcstoull 


All, Linux, RDOS, Netware 
All, Linux, RDOS 
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strtoumax, wcstoumax 


Synopsis: 


Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


#include <inttypes.h> 

uintmax_ t strtoumax( const char *ptr, 

char **endptr, 
int base ); 

♦include <inttypes.h> 

uintmax_t wcstoumax( const wchar_t *ptr, 

wchar_ t **endptr, 
int base ) ; 

The strtoumax function converts the string pointed to by ptr to an uintmax_ t. The function 
recognizes a string containing optional white space, an optional sign (+ or -), followed by a sequence of 
digits and letters. The conversion ends at the first unrecognized character. A pointer to that character 
will be stored in the object endptr points to if endptr is not NULL. 

If base is zero, the first characters determine the base used for the conversion. If the first characters are 
"Ox" or "OX" the digits are treated as hexadecimal. If the first character is 'O’, the digits are treated as 
octal. Otherwise the digits are treated as decimal. 

If base is not zero, it must have a value of between 2 and 36. The letters a-z and A-Z represent the 
values 10 through 35. Only those letters whose designated values are less than base are permitted. If 
the value of base is 16, the characters "Ox" or "OX" may optionally precede the sequence of letters and 
digits. 

If there is a leading minus sign in the string, the value is negated. 

The wcstoumax function is a wide-character version of strtoumax that operates with 
wide-character strings. 

The strtoumax function returns the converted value. If the correct value would cause overflow, 
UINTMAX_ MAX is returned anderrno is set to ERANGE. If base is out of range, zero is returned and 
errno is set to EDOM. 

atoi, atol, atoll, itoa, ltoa, lltoa, sscanf, strtol, strtoll, strtoul, strtoull, 
strtoimax, ultoa, ulltoa, utoa 

♦include <inttypes.h> 

♦include <stdlib.h> 

void main() 

{ 

uintmax_ t v; 

v = strtoumax( "12345678909876", NULL, 10 ); 

} 

ISOC 

strtoumax - All, Linux, RDOS, Netware 
wcstoumax - All, Linux, RDOS 
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Synopsis: 


Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


strupr, _strupr, Jstrupr, _wcsupr, _mbsupr, Jmbsupr 


#include <string.h> 
char *strupr( char *s ); 
char *_ strupr( char *s ); 

char_far *_ fstrupr( char_far *s ) ; 

♦include <wchar.h> 

wchar_ t *_ wcsupr ( wchar_ t *s ); 

♦include <mbstring.h> 

unsigned char *_ mbsupr( unsigned char *s ); 

unsigned char_far *_ fmbsupr ( unsigned char_far *s ) ; 

The strupr function replaces the string ,v with uppercase characters by invoking the toupper 
function for each character in the string. 

The _ strupr function is identical tostrupr. Use _ strupr for ANSI naming conventions. 

The _ f strupr function is a data model independent form of the strupr function. It accepts far pointer 
arguments and returns a far pointer. It is most useful in mixed memory model applications. 

The _ wcsupr function is a wide-character version ofstrupr that operates with wide-character 
strings. 

The _ mbsupr function is a multibyte character version ofstrupr that operates with multibyte 
character strings. 

The address of the original string ,v is returned, 
strlwr 


♦include <stdio.h> 
♦include <string.h> 


"A mixed-case STRING" }; 


char source[] = { 

void main() 

1 

printf ( "%s\n", 
printf ( "%s\n", 
printf ( "%s\n", 

} 

produces the following: 

A mixed-case STRING 
A MIXED-CASE STRING 
A MIXED-CASE STRING 


source ); 

strupr( source ) ) ; 

source ) ; 


WATCOM 

_strupr conforms to ANSI naming conventions 

strupr - All, Linux, RDOS, Netware 
_ strupr - All, Linux, RDOS, Netware 
_ fstrupr - All, Linux, RDOS 
_ wcsupr - All, Linux 

_ mbsupr - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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strupr, _strupr, Jstrupr, _wcsupr, _mbsupr, Jmbsupr 


fmbsupr - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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strxfrm, wcsxfrm 


Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <string.h> 
size_ t strxfrm( char *dst, 

const char *src, 
size_ t n ) ; 

#include <wchar.h> 

size_ t wcsxfrm( wchar_ t *dst, 

const wchar_ t *src, 
size_ t n ) ; 

The strxfrm function transforms, for no more than n characters, the string pointed to by src to the 
buffer pointed to by dst. The transformation uses the collating sequence selected by the setlocale 
function so that two transformed strings will compare identically (using the strncmp function) to a 
comparison of the original two strings using the strcoll function. The function will be equivalent to 
the strncpy function (except there is no padding of the dst argument with null characters when the 
argument src is shorter than n characters) when the collating sequence is selected from the " C " locale. 

The wcsxfrm function is a wide-character version of strxfrm that operates with wide-character 
strings. For wcsxfrm, after the string transformation, a call to wcscmp with the two transformed strings 
yields results identical to those of a call to wcscoll applied to the original two strings, wcsxfrm and 
strxfrm behave identically otherwise. 

The strxfrm function returns the length of the transformed string. If this length is more than n, the 
contents of the array pointed to by dst are indeterminate. 

setlocale, strcoll 

♦include <stdio.h> 

♦include <string.h> 

♦include <locale.h> 

char src[] = { "A sample STRING" }; 
char dst[20]; 

void main() 

{ 

size_ t len; 

setlocale ( LC_ ALL, "C" ); 
printf ( "%s\n", src ); 
len = strxfrmf dst, src, 20 ); 
printf ( "%s (%u)\n", dst, len ); 

} 

produces the following: 

A sample STRING 
A sample STRING (15) 

ISOC 

strxfrm - All, Linux, RDOS, Netware 
wcsxfrm - All, Linux 
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swab 


Synopsis: 

Description: 

Returns: 

Example: 


Classification: 

Systems: 


#include <stdlib.h> 

void swab( char *src, char *dest, int num ); 

The swab function copies num bytes (which should be even) from src to dest swapping every pair of 
characters. This is useful for preparing binary data to be transferred to another machine that has a 
different byte ordering. 

The swab function has no return value. 

♦include <stdio.h> 

♦include <string.h> 

♦include <stdlib.h> 

char *msg = "hTsim seasegi swspaep.d"; 

♦define NBYTES 24 

void main() 

{ 

auto char buffer[80]; 

printf ( "%s\n", msg ); 
memset( buffer, '\0', 80 ); 
swab( msg, buffer, NBYTES ); 
printf ( "%s\n", buffer ); 

1 

produces the following: 

hTsim seasegi swspaep.d 
This message is swapped. 

WATCOM 

All, Linux, RDOS, Netware 
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sysconf 


Synopsis: #include <unistd.h> 

long sysconf( int name ) ; 

Description: The sysconf function retrieves a current system configuration parameter depending on the value of 
system information from the kernel via the name passed. This implementation currently supports the 
following inputs: 

Member Meaning 

_SC_ARG_MAX The maximum number of arguments supported by execv and related 

arguments 

_SC_CHILD_MAX The maximum number of per-user child processes 

_SC_CLK_TCK The number of clock ticks per second 

_SC_NGROUPS_MAX The maximum number of groups to which a user may be a member 

_SC_OPEN_MAX The maximum number of file that may be opened by a user 

_SC_JOB_CONTROL If job control is supported, the value of 1 is returned 

_SC_SAVED_IDS If saved identifiers are supported, the value of 1 is returned 

_SC_VERSION The release year and month of the POSIX. 1 standard attempting to be 

supported, in the format YYYYMM 

_SC_STREAM_MAX The maximum number of per-process streams supported 

_SC_TZNAME_MAX The maximum length of a time zone name 

_SC_PAGESIZE The size, in bytes, of one page of memory 

_SC_NPROCESSORS_CONF The number of processors currently configured on the system 

_SC_NPROCESSORS_ONLN The number of processors currently online and functioning on the 

system 

_SC_PHYS_PAGES The total number of physical pages of memory for the system 

_SC_AVPHYS_PAGES The available number of physical pages of memory for the system 

_SC_REALTIME_SIGNALS If real-time signals are supported, the value of 1 is returned 

_SC_SOMAXCONN For the socket listen function, retrieve the largest supported backlog 

of listen requests 

In this implementation, requesting either _SC_NPROCESSORS_CONF or 
_SC_NPROCESSORS_ONLN will return the same value. 

Some inputs, specifically _SC_OPEN_MAX and _SC_CHILD_MAX, are configurable via calls to 
setrlimit and may change between subsequent sysconf calls. 
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sysconf 


Returns: 

Errors: 

Classification: 

Systems: 


If successful, the function will return zero. If the call fails, the return value is -1, and errno will be set 
appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINVAL The value of name is unsupported on this implementation 

POSIX 

Linux 
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sysinfo 


Synopsis: #include <sys/sysinfo .h> 

int sysinfo( struct sysinfo *info ); 

struct sysinfo { 

unsigned long uptime; 
unsigned long loads[3]; 
unsigned long totalram; 
unsigned long freeram; 
unsigned long sharedram; 
unsigned long bufferram; 
unsigned long totalswap; 
unsigned long freeswap; 
unsigned short procs, pad; 
unsigned long totalhigh; 
unsigned long freehigh; 
unsigned mem_ unit; 
char_reserved!] ; 

} ; 

Description: The sysinfo function retrieves system information from the kernel via the info structure. The 
members of the structure are defined below: 

Member Meaning 

uptime The number of seconds since the system booted 

loads The 1 minute, 5 minute, and 15 minute load averages 

totalram The total usable amount of system memory in bytes 

freeram The amount of memory currently unused and unallocated 

sharedram The amount of memory currently being shared 

bufferram The amount of memory allocated to buffering 

totalswap The amount of swap space available in bytes 

freeswap The amount of unused swap space 

procs The amount of processes currently running 

pad Padding for alignment; can be ignored 

totalhigh Total amount of "high" memory 

memjunit The memory unit size in bytes 

Returns: If successful, the function will return zero. If the call fails, the return value is -1, and errno will be set 

appropriately. 

Errors: When an error has occurred, errno contains a value indicating the type of error that has been detected. 
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sysinfo 


Classification: 

Systems: 


Constant Meaning 

EINVAL The value of info is NULL 

EFAULT The value of info is invalid 

WATCOM 

Linux 
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system, _wsystem 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


Systems: 


♦include <stdlib.h> 

int system( const char *corranand ); 

int _wsystem( const wchar_ t *command ); 

If the value of command is NULL, then the system function determines whether or not a command 
processor is present ("COMMAND.COM" in DOS and Windows 95/98 or "CMD.EXE" in OS/2 and 
Windows NT/2000). 

Otherwise, the system function invokes a copy of the command processor, and passes the string 
command to it for processing. This function uses spawnl to load a copy of the command processor 
identified by the COMSPEC environment variable. 

This means that any command that can be entered to DOS can be executed, including programs, DOS 
commands and batch files. The exec . . . and spawn . . . functions can only cause programs to be 
executed. 

The _ wsystem function is a wide-character version ofsystem that operates with wide-character 
strings. 

If the value of command is NULL, then the system function returns zero if the command processor is 
not present, a non-zero value if the command processor is present. Note that Microsoft Windows 3.x 
does not support a command shell and so the system function always returns zero when command is 
NULL. 

Otherwise, the system function returns the result of invoking a copy of the command processor. A 
non-zero value is returned if the command processor could not be loaded; otherwise, zero is returned. 
When an error has occurred, errno contains a value indicating the type of error that has been detected. 

abort, atexit, _ bgetcmd.exec. . ., exit, _ Exit*_ exit,getcmd, getenv, main, 
onexit, putenv, spawn... 

♦include <stdlib.h> 

♦include <stdio.h> 

void main() 

{ 

int rc; 

rc = system( "dir" ); 
if( rc != 0 ) { 

printf( "shell could not be run\n" ); 

} 

} 

ISO C, POSIX 1003.2 
_wsystem is WATCOM 

system - All, Linux, RDOS, Netware 

_ wsystem - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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tan 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double tan( double x ) ; 

The tan function computes the tangent of x (measured in radians). A large magnitude argument may 
yield a result with little or no significance. 

The tan function returns the tangent value. When an error has occurred, errno contains a value 
indicating the type of error that has been detected. 

atan, atan2, cos, sin, tanh 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "% f\n", tan (.5) ); 

} 

produces the following: 

0.546302 

ISOC 

Math 
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tanh 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double tanh( double x ) ; 

The tanh function computes the hyperbolic tangent of x. 

When the x argument is large, partial or total loss of significance may occur. The matherr function 
will be invoked in this case. 

The tanh function returns the hyperbolic tangent value. When an error has occurred, errno contains 
a value indicating the type of error that has been detected. 

cosh, sinh, matherr 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "% f\n", tanh(.5) ); 

} 

produces the following: 

0.462117 

ISOC 

Math 
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tell, Jell, Jelli64 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


#include <io.h> 

of f_ t tell ( int handle ) ; 

off_ t _tell ( int handle ) ; 

_int64 _ telli64 ( int handle ); 

The tell function reports the current file position at the operating system level. The handle value is 
the file handle returned by a successful execution of the open function. 

The returned value may be used in conjunction with the lseek function to reset the current file 
position. 

The _ tell function is identical totell. Use _ tell for ANSI naming conventions. 

The _telli64 function is similar to the tell function but returns a 64-bit file position. This value may 
be used in conjunction with the _ lseeki64 function to reset the current file position. 

If an error occurs in tell (-1L) is returned. 

If an error occurs in _telli64, (-1164) is returned. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 

Otherwise, the current file position is returned in a system-dependent manner. A value of 0 indicates 
the start of the file. 

chsize, close, creat, dup, dup2, eof, exec. . fdopen, filelength, fileno, fstat, 
_ grow_ handlesisatty, lseek, open, read, setmode, sopen, stat, write, umask 

♦include <stdio.h> 

♦include <sys/stat.h> 

♦include <io.h> 

♦include <fcntl.h> 

char buffer[] 

= { "A text record to be written" }; 

void main( void ) 

{ 

int handle; 

int size_ written; 

/* open a file for output */ 

/* replace existing file if it exists */ 
handle = open( "file", 

0_ WRONLY | 0_ CREAT | 0_ TRUNC | 0_ TEXT, 

S_ IRUSR | S_ IWUSR | S_ IRGRP | S_ IWGRP ); 
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tell, Jell, Jelli64 


if( handle != -1 ) { 

/* print file position */ 

printf( "%ld\n", tell( handle ) ); 

/* write the text */ 

size_ written = write( handle, buffer, 

sizeof( buffer ) ); 

/* print file position */ 

printf ( "%ld\n", tell ( handle ) ); 

/* close the file */ 
close ( handle ); 

} 

} 

produces the following: 

0 

28 

Classification: WATCOM 

_tell conforms to ANSI naming conventions 

Systems: tell - All, Linux, RDOS, Netware 

_ tell - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
_telli64 - All, Linux 


RDOS 
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Jempnam, 

Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


wtempnam 


#include <stdio.h> 

char *_ tempnam( const char *dir, const char ^prefix ); 

wchar_ t *_ wtempnam( const wchar_ t *dir, const wchar_t *prefix ); 

_ tempnam creates a temporary filename for use in another directory. This filename is different from 
that of any existing file. The prefix argument is the prefix to the filename. _ tempnam usesmalloc 
to allocate space for the filename; the program is responsible for freeing this space when it is no longer 
needed. _ tempnam looks for the file with the given name in the following directories, listed in order 
of precedence. 

Directory Used Conditions 

Directory specified by TMP The TMP environment variable must be set and the directory specified by 
TMP must exist. 

dir (function argument) The TMP environment variable must not be set or the directory specified by 
TMP does not exist. 

_P_tmpdir (_wP Jmpdir) in STDIO.H The dir argument is NULL or dir is the name of a nonexistent 
directory. The _ wP_ tmpdir string is used by _wtempnam. 

Current working directory _ tempnam uses the current working directory when_ P_ tmpdir does not 
exist. _ wtempnam uses the current working directory when_ wP_ tmpdir does not 
exist. 

_ tempnam automatically handles multibyte-character string arguments as appropriate, recognizing 
multibyte-character sequences according to the OEM code page obtained from the operating system. 

The _ wtempnam function is a wide-character version of_ tempnam. It accepts a wide-character 
string argument for format and produces wide character output. The _ wtempnam function does not 
handle multibyte-character strings. 

The function generates unique filenames for up to TMP_ MAX calls. 

The _ tempnam function returns a pointer to the name generated, unless it is impossible to create this 
name or the name is not unique. If the name cannot be created or if a file with that name already exists, 

_ tempnam returns NULL. 

fopen, freopen, mkstemp, _ mktemp,tmpfile, tmpnam 
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Classification: 

Systems: 


tempnam, _wtempnam 


♦include <stdio.h> 

♦include <stdlib.h> 

/* 

Environment variable TMP=C:\WINDOWS\TEMP 

*/ 

void main() 

{ 

char *filename; 

FILE *fp; 

filename = _ tempnam( "D:\\TEMP", T" ); 

if( filename == NULL ) 

printf ( "Can't obtain temp file name\n" ); 

else { 

printf ( "Temp file name is %s\n", filename ); 
fp = fopen ( filename, "w+b" ); 

/* . */ 

/* . */ 

/* . */ 
fclose ( fp ); 
remove( filename ); 
free( filename ); 

} 

} 

produces the following: 

Temp file name is C:\WIND0WS\TEMP\_T1 

WATCOM 

_ tempnam - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
_ wtempnam - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32 
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tgamma 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double tgamma( double x ) ; 

The tgamma function returns the value of the Gamma function of x. 

If successful, the return value is the value of the Gamma function computed for x. When the argument 
is not-a-number or negative infinity, the function returns NAN. If the argument is positive infinity, the 
function returns positive infinity. 

lgamma, lgamma_ r 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", tgamma( 4.0 ) ); 

} 

produces the following: 

6.00000 
ISO C99 
Math 
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time 


Synopsis: 

Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <time.h> 

time_ t time( time_ t *tloc ); 

The time function determines the current calendar time and encodes it into the type time_ t. 

The time represents the time since January 1, 1970 Coordinated Universal Time (UTC) (formerly 
known as Greenwich Mean Time (GMT)). 

The time set on the computer with the DOS time command and the DOS date command reflects the 
local time. The environment variable TZ is used to establish the time zone to which this local time 
applies. See the section The TZ Environment Variable for a discussion of how to set the time zone. 

The time function returns the current calendar time. If tloc is not NULL, the current calendar time is 
also stored in the object pointed to by tloc. 

asctime Functions, asctime_ s,clock, ctime Functions, ctime_ s,difftime, gmtime, 
gmtime_ s.localtime, localtime_ s,mktime, strftime, tzset 

♦include <stdio.h> 

♦include <time.h> 

void main() 

{ 

time_ t time_ of_ day; 
time_ of_ day = time ( NULL ) ; 

printf( "It is now: %s", ctime( &time_ of_ day ) ); 

} 

produces the following: 

It is now: Fri Dec 25 15:58:42 1987 
ISOC, POSIX 1003.1 
All, Linux, RDOS, Netware 
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timer create 


Synopsis: 


Description: 

Returns: 

Errors: 


See Also: 

Classification: 

Systems: 


♦include <time.h> 

int timer_ create (clockid_ t clockid, struct sigevent *evp, timer_ t *ti 
merid); 

struct sigevent { 

int sigev_ signo; 

union sigval sigev_ value; 
int sigev_ notify; 

} ; 


The timer_ create function creates a new timer using the clock specified by clockid as supported by 
the underlying operating system. The evp argument can be NULL or may specify a handler for when an 
event of interest occurs. This implementation currently only supports responding using 
SIGEV_SIGNAL implementations. The pointer timerid will contain the unique, per-process timer id if 
the call is successful. 

If successful, the function will return zero, and the timerid argument will contain the timer id. If the call 
fails, the return value is -1, and errno will be set appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINVAL The value of timerid is NULL or an invalid clockid is specified 

EAGAIN The system was unable to allocate resources for a new timer 

timer_ gettime,timer_ settime,timer_ delete,timer_ getoverrun 

POSIX 

Linux 
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timer delete 


Synopsis: 

Description: 

Returns: 

Errors: 

See Also: 

Classification: 

Systems: 


♦include <time.h> 

int timer_ delete (timer_ t timerid ) ; 

The timer_ delete function disarms, if necessary, and deletes the timer timerid immediately. 

If successful, the function will return zero. If the call fails, the return value is -1, and errno will be set 
appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINVAL The value of timerid is NULL or invalid 
timer_ create,timer_ settime,timer_ gettime 
POSIX 
Linux 
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timer_gettime 


Synopsis: 


Description: 

Returns: 

Errors: 

See Also: 

Classification: 

Systems: 


♦include <time.h> 

int timer_ gettime (timer_ t timerid, 

struct itimerspec *value ); 


struct timespec { 
time_ t tv_ sec; 
long tv_ nsec; 

} ; 


struct itimerspec { 
struct timespec 
struct timespec 
int 
int 
long 


it_ interval; 
it_ value; 
notify_ type; 
timer_ type; 
data; 


The timer_ gettime function retrieves time remaining in the timer timerid until expiration. 

If successful, the function will return zero. If the call fails, the return value is -1, and errno will be set 
appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINVAL The value of timerid is NULL or invalid 

timer_ create,timer_ settime,timer_ delete,timer_ getoverrun 

POSIX 

Linux 
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timer settime 


Synopsis: 


Description: 


Returns: 

Errors: 

See Also: 

Classification: 

Systems: 


♦include <time.h> 

int timer_ settime(timer_ 

struct 

struct 


t timerid, 
itimerspec 
itimerspec 


int flags, 
*new_ value, 
*old_ value 


struct timespec { 
time_ t tv_ sec; 
long tv_ nsec; 

} ; 


struct itimerspec { 
struct timespec 
struct timespec 
int 
int 
long 


it_ interval; 
it_ value; 
notify_ type; 
timer_ type; 
data; 


The timer_ settime function arms or resets the timer timerid using the interval and value specified 
in new_value pointer. The previous interval and value is returned in the oldvalue pointer. 

The structure pointed to by the "it_value" member of new_value specifies the time in the future when 
the timer will expire, and effectively arms the timer. If the it_value member of new_value specifies a 
time of zero, the timer is disarmed. The structure pointed to by the "it_interval" member of new_value 
specifies the interval after the initial timer expiration when the timer would repeat expiration. If the 
it_interval member’s components are set to zero, the timer will expire at the time specified by the 
"it_value" member of new_value and the timer will not automatically rearm. 

The "it_value" member of new_value is regarded, by default, as a time relative to the system clock at 
the time of the function call. If flags incorporates the TIMER_ABSTIME constant, the time in 
"it_value" is regarded as an absolute system time as opposed to a time relative to calling this function. 

If successful, the function will return zero. If the call fails, the return value is -1, and errno will be set 
appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINVAL The value of timerid is NULL or invalid 

timer_ create,timer_ gettime,timer_ delete,timer_ getoverrun 

POSIX 

Linux 
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timer_getoverrun 


Synopsis: 

Description: 

Returns: 

Errors: 

See Also: 

Classification: 

Systems: 


♦include <time.h> 

int timer_ getoverrun ( timer_ t timerid ); 

The timer_ getoverrun function returns the number of intervals for the given timerid since 
expiration. 

If successful, the function will return the number of elapsed intervals since the latest timer expiration. If 
the call fails, the return value is -1, and errno will be set appropriately. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 
Constant Meaning 

EINVAL The value of timerid is NULL or invalid 
timer_ create,timer_ settime,timer_ delete 
POSIX 
Linux 
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tmpfile 


Synopsis: 

Safer C: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <stdio.h> 

FILE *tmpfile( void ) ; 

The Safer C Library extension provides the tmpf ile_ s function which is a safer alternative to 
tmpfile This newer tmpf ile_ s function is recommended to be used instead of the traditional 
"unsafe" tmpfile function. 

The tmpfile function creates a temporary binary file that will automatically be removed when it is 
closed or at program termination. The file is opened for update. For all systems except NetWare, the 
temporary file is located in the path specified by one of the following environment variables, if one is 
defined. Otherwise, the current working directory is used. They are listed in the order examined: TMP, 
TEMP, TMP DIR, and TEMPDIR. 

The tmpfile function returns a pointer to the stream of the file that it created. If the file cannot be 
created, the tmpfile function returns NULL . When an error has occurred, errno contains a value 
indicating the type of error that has been detected. 

fopen, fopen_ s,freopen, freopen_ sjnkstemp, _ mktemp,_ tempnam,tmpfile_ s, 
tmpnam, tmpnam_ s 

♦include <stdio.h> 

static FILE *TempFile; 

void main() 

{ 

TempFile = tmpfile(); 

/* . */ 

/* . */ 

/* . */ 

fclose ( TempFile ); 

} 

ISOC 

All, Linux, RDOS, Netware 
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tmpfile_s 


Synopsis: 

Constraints: 


Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

errno_ t tmpfile_ s ( FILE * restrict * restrict streamptr); 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and tmpf ile_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

streamptr shall not be a null pointer. If there is a runtime-constraint violation, tmpf ile_ s does not 
attempt to create a file. 

The tmpf ile_ s function creates a temporary binary file that is different from any other existing file 
and that will automatically be removed when it is closed or at program termination. If the program 
terminates abnormally, whether an open temporary file is removed is implementation-defined. The file 
is opened for update with "wb+" mode with the meaning that mode has in the fopen_s function 
(including the mode’s effect on exclusive access and file permissions). If the file was created 
successfully, then the pointer to FILE pointed to by streamptr will be set to the pointer to the object 
controlling the opened file. Otherwise, the pointer to FILE pointed to by streamptr will be set to a null 
pointer. For all systems except NetWare, the temporary file is located in the path specified by one of 
the following environment variables, if one is defined. Otherwise, the current working directory is 
used. They are listed in the order examined: TMP, TEMP, TMPDIR, and TEMPDIR. 

The tmpf ile_ s function returns zero if there was no runtime-constraint violation. Otherwise, a 
non-zero value is returned. 

fopen, fopen_ s.freopen, freopen_ sjnkstemp, _ mktemp^ tempnam.tmpfile, 
tmpnam, tmpnam_ s 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

void main() 

{ 

errno_ t rc; 

FILE *TempFile; 

rc = tmpfile_ s( STempFile ); 
if( rc == 0 ) { 

/* . */ 

/* . */ 

/* . */ 

fclose ( TempFile ); 

} 

} 

TR 24731 

All, RDOS, Netware 
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tmpnam_s, _wtmpnam_s 


Synopsis: #def ine_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

errno_ t tmpnam_ s ( char * s, rsize_ t maxsize ); 

♦include <wchar.h> 

errno_ t _ wtmpnam_ s ( wchar_ t * s, rsize_ t maxsize ); 

Constraints: If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and tmpnam_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

,v shall not be a null pointer, maxsize shall be less than or equal to RSIZE_ MAX. maxsize shall be 
greater than the length of the generated file name string. 

Description: The tmpnam_ s function generates a string that is a valid file name and that is not the same as the name 
of an existing file. The function is potentially capable of generating TMP_ MAX_ S different strings, but 
any or all of them may already be in use by existing files and thus not be suitable return values. The 
lengths of these strings shall be less than the value of the L_ tmpnam_ s macro. Thfcmpnam_ s 
function generates a different string each time it is called. 

The _ wtmpnam_ s function is a wide-character version o£mpnam_ s. It accepts a wide-character 
string argument for format and produces wide character output. 

Returns: If no suitable string can be generated, or if there is a runtime-constraint violation, the tmpnam_ s 

function writes a null character to s[0] (only if s is not null and maxsize is greater than zero) and returns 
a non-zero value. Otherwise, the tmpnam_ s function writes the string in the array pointed to by s and 
returns zero. 

See Also: fopen, fopen_ s,f reopen, freopen_ sjnkstemp, _ mktemp,_ tempnam.tmpf ile, 

tmpfile_ s.tmpnam 

Example: ♦define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

void main() 

{ 

char filename [ L_ tmpnam_ s ] ; 

FILE *fp; 

errno_ t rc; 

rc = tmpnam( filename, sizeof( filename ) ); 

if( rc == 0 ) { 

fp = fopen( filename, "w+b" ); 

/* . */ 

/* . */ 

/* . */ 
fclose ( fp ); 
remove( filename ); 

} 

} 

Classification: TR 24731 

_wtmpnam_s is WATCOM 

Systems: tmpnam_ s - All, Linux, RDOS, Netware 
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tmpnam_s, _wtmpnam_s 


wtmpnam_ s 


- DOS, Windows, Win386, Win32, OS/2 1.x (all), OS/2-32 
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tmpnam, _wtmpnam 


Synopsis: 


Safer C: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


Systems: 


#include <stdio.h> 

char *tmpnam( char *buffer ); 

wchar_ t *_ wtmpnam ( wchar_ t *buffer ); 

The Safer C Library extension provides the tmpnam_ s function which is a safer alternative to 
tmpnam This newer tmpnam_ s function is recommended to be used instead of the traditional "unsafe" 
tmpnam function. 

The tmpnam function generates a unique string for use as a valid file name. 

The _ wtmpnam function is a wide-character version oftmpnam. It accepts a wide-character string 
argument for format and produces wide character output. An internal static buffer is used to construct 
the filename. Subsequent calls to tmpnam reuse the internal buffer. 

The function generates unique filenames for up to TMP_ MAX calls. 

If the argument buffer is a NULL pointer, tmpnam returns a pointer to an internal buffer containing the 
temporary file name. If the argument buffer is not a NULL pointer, tmpnam copies the temporary file 
name from the internal buffer to the specified buffer and returns a pointer to the specified buffer. It is 
assumed that the specified buffer is an array of at least L_ tmpnam characters. 

If the argument buffer is a NULL pointer, you may wish to duplicate the resulting string since 
subsequent calls to tmpnam reuse the internal buffer. 

char *namel, *name2; 

namel = strdup( tmpnam( NULL ) ); 
name2 = strdup( tmpnam( NULL ) ); 

fopen, fopen_ s,freopen, freopen_ sjnkstemp, _ mktemp,_ tempnam,tmpfile, 
tmpfile_ s,tmpnam_ s 

♦include <stdio.h> 

void main() 

{ 

char filename [ L_ tmpnam ] ; 

FILE *fp; 

tmpnam( filename ); 

fp = fopen( filename, "w+b" ); 

/* . */ 

/* . */ 

/* . */ 
fclose ( fp ); 
remove( filename ); 

} 

ISOC 

_wtmpnam is WATCOM 

tmpnam - All, Linux, RDOS, Netware 

_wtmpnam - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32 
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to lower, _tolower, towlower 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


#include <ctype.h> 
int tolower( int c ) ; 
int _ tolower( int c ); 

♦include <wctype.h> 

wint_ t towlower ( wint_ t c ) ; 

The tolower function converts c to a lowercase letter if c represents an uppercase letter. 

The _ tolower function is a version oftolower to be used only when c is known to be uppercase. 

The towlower function is a wide-character version of tolower that operates with wide-character 
strings. 

The tolower function returns the corresponding lowercase letter when the argument is an uppercase 
letter; otherwise, the original character is returned. The towlower function returns the corresponding 
wide-character lowercase letter when the argument is a wide-character uppercase letter; otherwise, the 
original wide character is returned. 

The result of _ tolower is undefined if c is not an uppercase letter. 

isalnum, isalpha, isblank, iscntrl, isdigit, isgraph, isleadbyte, islower, 
isprint, ispunct, isspace, isupper, iswctype, isxdigit, toupper, towctrans, 
strlwr, strupr, toupper 

♦include <stdio.h> 

♦include <ctype.h> 

char chars[] = { 

'A' , 

'5', 

' Z' 

} ; 


♦ define SIZE sizeof ( chars ) / sizeof( char ) 

void main() 

{ 

int i; 

for( i = 0; i < SIZE; i++ ) { 

printf ( "%c ", tolower( chars[ i ] ) ); 

} 

printf ( "\n" ); 

} 

produces the following: 

a 5 $ z 

ISOC 

_tolower is WATCOM 
towlower is ISO C95 
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tolower, Jolower, towlower 


Systems: 


tolower - All, Linux, RDOS, 
_ tolower - All, Linux, RDOS 
towlower - All, Linux, RDOS, 


Netware 
, Netware 
Netware 
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toupper, Joupper, towupper 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


#include <ctype.h> 
int toupper( int c ); 
int _ toupper ( int c ) ; 

♦include <wctype.h> 

wint_ t towupper ( wint_ t c ) ; 

The toupper function converts c to a uppercase letter if c represents a lowercase letter. 

The _ toupper function is a version oftoupper to be used only when c is known to be lowercase. 

The towupper function is a wide-character version of toupper that operates with wide-character 
strings. 

The toupper function returns the corresponding uppercase letter when the argument is a lowercase 
letter; otherwise, the original character is returned. The towupper function returns the corresponding 
wide-character uppercase letter when the argument is a wide-character lowercase letter; otherwise, the 
original wide character is returned. 

The result of _ toupper is undefined if c is not a lowercase letter. 

isalnum, isalpha, isblank, iscntrl, isdigit, isgraph, isleadbyte, islower, 
isprint, ispunct, isspace, isupper, iswctype, isxdigit, tolower, towctrans, 
strlwr, strupr, tolower 

♦include <stdio.h> 

♦include <ctype.h> 

char chars[] = { 



♦ define SIZE sizeof( chars ) / sizeof ( char ) 

void main() 

{ 

int i; 

for( i = 0; i < SIZE; i++ ) { 

printf ( "%c ", toupper ( chars[ i ] ) ); 

} 

printf ( "\n" ); 

} 

produces the following: 

A 5 $ Z 
ISOC 

_toupper is WATCOM 
towupper is ISO C95 
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toupper, Joupper, towupper 


Systems: 


toupper - All, Linux, RDOS, 
_ toupper - All, Linux, RDOS 
towupper - All, Linux, RDOS, 


Netware 
, Netware 
Netware 
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to wetra ns 


Synopsis: 

Description: 


Returns: 
See Also: 

Example: 


Classification: 

Systems: 


♦include <wctype.h> 

wint_ t towetrans ( wint_ t wc, wctrans_ t desc ) ; 

The towetrans function maps the wide character wc using the mapping described by desc. Valid 
values of desc are defined by the use of the wetrans function. 

The two expressions listed below behave the same as a call to the wide character case mapping function 
shown. 

Expression Equivalent 

towctrans(wc, wctrans("tolower")) towlower(wc) 
towctrans(wc, wctrans("toupper")) towupper(wc) 

The towetrans function returns the mapped value of wc using the mapping described by desc. 

isalnum, isalpha, isblank, iscntrl, isdigit, isgraph, isleadbyte, islower, 
isprint, ispunct, isspace, isupper, iswetype, isxdigit, tolower, toupper 

♦include <stdio.h> 

♦include <wctype.h> 

char translations [2 ] = { 

"tolower", 

"toupper" 

} ; 


void main( void ) 

{ 

int i; 

wint_ t wc = 'A'; 
wint_ t twe; 

for( i = 0; i < 2; i++ ) { 

twe = towetrans! wc, wetrans ( translations [ i] ) ); 

printf( "%s(%lc): %lc\n", translations[i], wc, twe ); 

} 

} 

produces the following: 

tolower(A): a 
toupper(A): A 

ISO C95 

All, Linux, RDOS, Netware 
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trunc 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <math.h> 
double trunc( double x ) ; 

The trunc function truncates the argument x to the appropriate integer. The function is equivalent to 
floor for positive numbers and ceil for negative numbers. 

The value of x without any fractional values. 

nearbyint, rint, round, floor, ceil 

♦include <stdio.h> 

♦include <math.h> 

void main() 

{ 

printf ( "%f\n", round( 1.5 ) ); 

} 

produces the following: 

1.000000 
ISO C99 
Math 
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ttyname, ttynamej 


Synopsis: 

Description: 


Returns: 


Errors: 


See Also: 

Classification: 

Systems: 


#include <unistd.h> 
char *ttyname( int fd ) ; 

int ttyname_ r( int fd, char *buf, size_t buflen ); 

The POSIX-compliant ttyname function retrieves the name of a TTY as specified by the fd file 
descriptor, returning a static pointer to the name. Subsequent calls may change the contents of the 
string pointed to by the original call to ttyname , and the memory to which the return value points 
should not be freed. 

The ttyname_ r function performs the same function asttyname , but the name of the TTY is 
returned in the buf argument. The argument buflen should specify the size of the buf argument. The 
ttyname_ r function is an Open Watcom extension commonly implemented in other standard 
libraries. 

Upon success, the ttyname function returns a pointer to statically allocated memory containing the 
name of the TTY. Upon failure, the returned pointer will be NULL and errno will be set 
appropriately. 

Upon success, the ttyname_ r function will return zero, and the buf argument will contain the name of 
the TTY. Upon failure, the ttyname_ r function will return the error code and seterrno as well. 

When an error has occurred, errno contains a value indicating the type of error that has been detected. 

Constant Meaning 

ENOTTY The value of fd does not refer to a TTY 

EACCES The user does not have permission to query the file descriptor 

EBADFD The file descriptor fd is invalid 

ERANGE The buf is not large enough to hold the result, or the file descriptor name exceeds 
POSIX_ PATH_ MAX 

isatty 

POSIX 1003.1 

ttyname - Linux 
ttyname_ r - Linux 
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tzset 


Synopsis: #include <time.h> 

void tzset( void ) ; 

Description: The tzset function sets the global variables daylight, timezone and tzname according to the 
value of the TZ environment variable. The section The TZ Environment Variable describes how to set 
this variable. 

Under Win32, tzset also uses operating system supplied time zone information. The TZ environment 
variable can be used to override this information. 

The global variables have the following values after tzset is executed: 

daylight Zero indicates that daylight saving time is not supported in the locale; a non-zero 

value indicates that daylight saving time is supported in the locale. This variable 
is cleared/set after a call to the tzset function depending on whether a daylight 
saving time abbreviation is specified in the TZ environment variable. 

timezone Contains the number of seconds that the local time zone is earlier than 

Coordinated Universal Time (UTC) (formerly known as Greenwich Mean Time 
(GMT)). 

tzname Two-element array pointing to strings giving the abbreviations for the name of the 

time zone when standard and daylight saving time are in effect. 

The time set on the computer with the DOS time command and the DOS date command reflects the 
local time. The environment variable TZ is used to establish the time zone to which this local time 
applies. See the section The TZ Environment Variable for a discussion of how to set the time zone. 

Returns: The tzset function does not return a value. 

See Also: ctime Functions, localtime, mktime, strftime 

Example: ((include <stdio.h> 

((include <env.h> 

((include <time.h> 

void print_ zone() 

1 

char *tz; 

printf( "TZ: %s\n", (tz = getenv( "TZ" )) 

? tz : "default EST5EDT" ); 
printf( " daylight: %d\n", daylight ); 
printf( " timezone: %ld\n", timezone ); 
printf( " time zone names: %s %s\n", 
tzname[0], tzname[1] ); 

} 
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tzset 


void main() 

{ 

print_ zone(); 

setenv( "TZ", "PST8PDT", 1 ); 
tzset (); 
print_ zone(); 

} 


produces the following: 


TZ: default 
daylight: 
timezone: 
time zone 
TZ: PST8PDT 
daylight: 
timezone: 
time zone 


EST5EDT 

1 

18000 

names: EST EDT 
1 

28800 

names: PST PDT 


Classification: POSIX 1003.1 


Systems: All, Linux, RDOS, Netware 
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Synopsis: 


Description: 


Returns: 
See Also: 

Example: 


ulltoa, _ulltoa, _ulltow 


#include <stdlib.h> 

char *ulltoa( unsigned long long int value, 
char *buffer, 
int radix ); 

char *_ ulltoa( unsigned long long int value, 
char *buffer, 
int radix ); 

wchar_ t *_ulltow( unsigned long long int value, 

wchar_ t *buffer, 
int radix ); 

The ulltoa function converts the unsigned binary integer value into the equivalent string in base 
radix notation storing the result in the character array pointed to by buffer. A null character is appended 
to the result. The size of buffer must be at least 65 bytes when converting values in base 2. The value 
of radix must satisfy the condition: 

2 <= radix <= 36 


The _ ulltoa function is identical toulltoa. Use _ ulltoa for ANSI naming conventions. 

The _ ulltow function is a wide-character version ofulltoa. It produces a wide-character string. 
The ulltoa function returns the pointer to the result. 

atoi, atol, atoll, itoa, ltoa, lltoa, sscanf, strtol, strtoll, strtoul, strtoull, 
strtoimax, strtoumax, ultoa, utoa 


♦include <stdio.h> 
♦include <stdlib.h> 


void print_ value ( unsigned long long int value ) 

{ 

int base; 

char buffer[65]; 


} 


for( base = 2; base <= 16; base = 
printf ( "%2d %s\n", base, 

ultoa( value, buffer. 


base + 2 ) 
base ) ); 


void main() 

{ 

print_ value ( (unsigned long long) 1234098765LL ); 

} 


produces the following: 

2 1001001100011101101101001001101 
4 1021203231221031 
6 322243004113 
8 11143555115 
10 1234098765 
12 2a5369639 
14 b9c8863b 
16 498eda4d 
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ulltoa, _ulltoa, _ulltow 


Classification: WATCOM 

_ulltoa conforms to ANSI naming conventions 

Systems: ulltoa - All, Linux, RDOS, Netware 

_ ulltoa - All, Linux, RDOS, Netware 
_ ulltow - All, Linux, RDOS 
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Synopsis: 


Description: 


Returns: 
See Also: 

Example: 


ultoa, _ultoa, _ultow 


#include <stdlib.h> 

char *ultoa( unsigned long int value, 
char ^buffer, 
int radix ); 

char *_ ultoa( unsigned long int value, 
char *buffer, 
int radix ); 

wchar_ t *_ ultow( unsigned long int value, 
wchar_ t ^buffer, 
int radix ); 

The ultoa function converts the unsigned binary integer value into the equivalent string in base radix 
notation storing the result in the character array pointed to by buffer. A null character is appended to 
the result. The size of buffer must be at least 33 bytes when converting values in base 2. The value of 
radix must satisfy the condition: 

2 <= radix <= 36 


The _ ultoa function is identical toultoa. Use _ ultoa for ANSI naming conventions. 

The _ ultow function is a wide-character version ofultoa. It produces a wide-character string. 

The ultoa function returns the pointer to the result. 

atoi, atol, atoll, itoa, ltoa, lltoa, sscanf, strtol, strtoll, strtoul, strtoull, 
strtoimax, strtoumax, ulltoa, utoa 


♦include <stdio.h> 
♦include <stdlib.h> 


void print_ value( unsigned long int value ) 

{ 

int base; 

char buffer[33]; 


} 


for( base = 2; base <= 16; base = 
printf ( "%2d %s\n", base, 

ultoa( value, buffer. 


base + 2 
base ) ) 


) 


void main () 

{ 

print_ value( (unsigned) 12765L ); 

} 


produces the following: 

2 11000111011101 
4 3013131 
6 135033 
8 30735 
10 12765 
12 7479 
14 491b 
16 31dd 
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ultoa, _ultoa, _ultow 


Classification: WATCOM 

_ultoa conforms to ANSI naming conventions 

Systems: ultoa - All, Linux, RDOS, Netware 

_ ultoa - All, Linux, RDOS, Netware 
_ ultow - All, Linux, RDOS 
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umask, _umask 


Synopsis: #include <sys/types,h> 

♦include <sys/stat.h> 

♦include <fcntl.h> 

♦include <io.h> 

int umask( int cmask ); 

int _ umask ( int cmask ) ; 

Description: The umask function sets the process’s file mode creation mask to cmask. The process’s file mode 
creation mask is used during creat, open or sopen to turn off permission bits in the permission 
argument supplied. In other words, if a bit in the mask is on, then the corresponding bit in the file's 
requested permission value is disallowed. 

The _ umask function is identical toumask. Use _ umask for ANSI naming conventions. 

The argument cmask is a constant expression involving the constants described below. The access 
permissions for the file or directory are specified as a combination of bits (defined in the 
<sys/stat ,h> header file). 

The following bits define permissions for the owner. 

Permission Meaning 

S_IRWXU Read, write, execute/search 

S_IRUSR Read permission 

S_IWUSR Write permission 

S_IXUSR Execute/search permission 

The following bits define permissions for the group. 

Permission Meaning 

S_IRWXG Read, write, execute/search 

S_IRGRP Read permission 

S_IWGRP Write permission 

S_IXGRP Execute/search permission 

The following bits define permissions for others. 

Permission Meaning 

S_IRWXO Read, write, execute/search 

S_IROTH Read permission 

S_IWOTH Write permission 

S_IXOTH Execute/search permission 

The following bits define miscellaneous permissions used by other implementations. 

Permission Meaning 

SJREAD is equivalent to S_IRUSR (read permission) 

SJWRITE is equivalent to S_IWUSR (write permission) 
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umask, _umask 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


S_IEXEC is equivalent to S_IXUSR (execute/search permission) 

For example, if S_ IRUSR is specified, then reading is not allowed (i.e„ the file is write only). If 
S_ IWUSR is specified, then writing is not allowed (i.e., the file is read only). 

The umask function returns the previous value of cmask. 

chmod, creat, mkdir, open, sopen 


♦include <sys/types.h> 
♦include <sys/stat.h> 
♦include <fcntl.h> 
♦include <io.h> 


void main( void ) 

{ 

int old_ mask; 


} 


/* set mask to create read-only files */ 

old_ mask = umask ( S_ IWUSR | S_ IWGRP | S_ IWOTH 

S_ IXUSR | S_ IXGRP | S_ IXOTH ); 


POSIX 1003.1 

_umask conforms to ANSI naming conventions 
umask - All, Linux, RDOS, Netware 

_ umask - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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ungetc, ungetwc 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


♦include <stdio.h> 

int ungetc( int c, FILE *fp ); 

♦include <stdio.h> 

♦include <wchar.h> 

wint_ t ungetwc ( wint_ t c, FILE *fp ); 

The ungetc function pushes the character specified by c back onto the input stream pointed to by //;. 
This character will be returned by the next read on the stream. The pushed-back character will be 
discarded if a call is made to the f flush function or to a file positioning function (f seek, f setpos 
or rewind) before the next read operation is performed. 

Only one character (the most recent one) of pushback is remembered. 

The ungetc function clears the end-of-file indicator, unless the value of c is EOF. 

The ungetwc function is identical to ungetc except that it pushes the wide character specified by c 
back onto the input stream pointed to by fp. 

The ungetwc function clears the end-of-file indicator, unless the value of c is WEOF. 

The ungetc function returns the character pushed back. 

fgetc, fgetchar, fgets, fopen, getc, getchar, gets 

♦include <stdio.h> 

♦include <ctype.h> 

void main() 

{ 

FILE *fp; 
int c; 
long value; 

fp = fopen( "file", "r" ); 
value = 0; 
c = fgetc( fp ); 
while ( isdigit (c) ) { 

value = value*10 + c - 'O'; 
c = fgetc ( fp ); 

} 

ungetc( c, fp ); /* put last character back */ 
printf ( "Value=%ld\n", value ); 
fclose ( fp ); 

} 

ISOC 

ungetc - All, Linux, RDOS, Netware 
ungetwc - All, Linux 


Library Functions and Macros 1153 




ungetch 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


#include <conio.h> 
int ungetch( int c ) ; 

The ungetch function pushes the character specified by c back onto the input stream for the console. 
This character will be returned by the next read from the console (with getch or getche functions) 
and will be detected by the function kbhit. Only the last character returned in this way is 
remembered. 

The ungetch function clears the end-of-file indicator, unless the value of c is EOF. 

The ungetch function returns the character pushed back. 

getch, getche, kbhit, putch 

♦include <stdio.h> 

♦include <ctype.h> 

♦include <conio.h> 

void main() 

{ 

int c; 
long value; 

value = 0; 

c = getche(); 

while( isdigit( c ) ) { 

value = value*10 + c - 'O'; 
c = getche() ; 

} 

ungetch( c ) ; 

printf( "Value=%ld\n", value ); 

} 

WATCOM 

All, Linux, RDOS, Netware 
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Synopsis: 

Description: 


Returns: 

See Also: 
Example: 

Classification: 

Systems: 


unlink, _unlink, _wunlink 


♦include <io.h> 

int unlink( const char *path ); 

int _ unlink( const char *path ); 

int _wunlink( const wchar_ t *path ); 

The unlink function deletes the file whose name is the string pointed to by path. This function is 
equivalent to the remove function. 

The _ unlink function is identical tounlink. Use _ unlink for ANSI naming conventions. 

The _ wunlink function is a wide-character version ofunlink that operates with wide-character 
strings. 

The unlink function returns zero if the operation succeeds, non-zero if it fails. 

chdir, chmod, close, getcwd, mkdir, open, remove, rename, rmdir, stat 

♦include <io.h> 

void main( void ) 

{ 

unlink( "vm.tmp" ); 

} 

POSIX 1003.1 

_unlink conforms to ANSI naming conventions 
_wunlink is WATCOM 

unlink - All, Linux, RDOS, Netware 

_ unlink - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ wunlink - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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unlock 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


#include <io.h> 

int unlock ( int handle, 

unsigned long offset, 
unsigned long nbytes ); 

The unlock function unlocks nbytes amount of previously locked data in the file designated by handle 
starting at byte offset in the file. This allows other processes to lock this region of the file. 

Multiple regions of a file can be locked, but no overlapping regions are allowed. You cannot unlock 
multiple regions in the same call, even if the regions are contiguous. All locked regions of a file should 
be unlocked before closing a file or exiting the program. 

With DOS, locking is supported by version 3.0 or later. Note that SHARE . COM or SHARE . EXE must 
be installed. 

The unlock function returns zero if successful, and -1 when an error occurs. When an error has 
occurred, errno contains a value indicating the type of error that has been detected. 

lock, locking, open, sopen 

♦include <stdio.h> 

♦include <fcntl.h> 

♦include <io.h> 

void main() 

{ 

int handle; 
char buffer[20]; 

handle = open ( "file", 0_ RDWR | 0_ TEXT ); 
if( handle != -1 ) { 

if( lock( handle, 0L, 20L ) ) { 

printf ( "Lock failed\n" ); 

} else { 

read( handle, buffer, 20 ); 

/* update the buffer here */ 
lseek ( handle, 0L, SEEK_ SET ); 
write( handle, buffer, 20 ); 
unlock! handle, 0L, 20L ); 

} 

close ( handle ); 

} 

} 

WATCOM 

All, RDOS, Netware 
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unregisterfonts 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


#include <graph.h> 

void _ FAR _ unregisterfonts( void ) ; 

The _ unregisterfonts function frees the memory previously allocated by the 
_ registerf onts function. The currently selected font is also unloaded. 

Attempting to use the _ setfont function after calling_ unregisterfonts will result in an error. 
The _ unregisterfonts function does not return a value. 

_ registerfonts,_ setfont,_ getfontinfo,_ outgtext^_ getgtextextent, 

_ setgtextvector,_ getgtextvector 

♦include <conio.h> 

♦include <stdio.h> 

♦include <graph.h> 

main () 

{ 

int i, n; 
char buf [ 10 ] ; 

_ setvideomode( _ VRES16COLOR ); 
n = _ registerfonts( "*.fon" ); 
for( i = 0; i < n; ++i ) { 

sprintf ( buf, "n%d", i ); 

_ setfont( buf ); 

_ moveto( 100, 100 ); 

_ outgtext( "WATCOM Graphics" ); 
getch(); 

_ clearscreen( _ GCLEARSCREEN ) ; 

} 

_ unregisterfonts() ; 

_ setvideomode( _ DEFAULTMODE ) ; 


PC Graphics 
DOS 
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utime, _utime, _wutime 


Synopsis: #include <sys/utime .h> 

int utime( const char *path, 

const struct utimbuf *times ); 
int _ utime( const char *path, 

const struct utimbuf *times ) ; 
int _ wutime( const wchar_ t *path, 

const struct utimbuf *times ); 

struct utimbuf { 

time_ t actime; /* access time */ 

time_ t modtime; /* modification time */ 

} ; 

Description: The utime function records the access and modification times for the file identified by path. 

The _ utime function is identical toutime. Use _ utime for ANSI naming conventions. 

If the times argument is NULL, the access and modification times of the file or directory are set to the 
current time. Write access to this file must be permitted for the time to be recorded. 

If the times argument is not NULL, it is interpreted as a pointer to a utimbuf structure and the access 
and modification times of the file or directory are set to the values contained in the designated structure. 
The access and modification times are taken from the actime and modtime fields in this structure. 

The _ wutime function is identical toutime except that path points to a wide-character string. 

Returns: The utime function returns zero when the time was successfully recorded. A value of -1 indicates an 

error occurred. 

Errors: When an error has occurred, errno contains a value indicating the type of error that has been detected. 

Constant Meaning 

EACCES Search permission is denied for a component of path or the times argument is 

NULL and the effective user ID of the process does not match the owner of the file 
and write access is denied. 

EINVAL The date is before 1980 (DOS only). 

EMFILE There are too many open files. 

ENOENT The specified path does not exist or path is an empty string. 

Example: ((include <stdio.h> 

((include <sys/utime. h> 

void main( int argc, char *argv[] ) 

{ 

if( (utime( argv[l], NULL ) != 0) && (argc >1) ) { 
printf( "Unable to set time for %s\n", argv[l] ); 

} 

} 

Classification: POSIX 1003.1 
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Systems: 


utime, _utime, _wutime 


_utime conforms to ANSI naming conventions 
_wutime is WATCOM 

utime - All, Linux, RDOS, Netware 

_ utime - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
_ wutime - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32 
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utoa, _utoa, _utow 


Synopsis: 


Description: 


Returns: 
See Also: 

Example: 


Classification: 


#include <stdlib.h> 
char *utoa( unsigned int value, 
char *buffer, 
int radix ); 

char *_ utoa( unsigned int value, 
char ^buffer, 
int radix ); 

wchar_ t *_ utow( unsigned int value, 
wchar_ t ^buffer, 
int radix ); 

The utoa function converts the unsigned binary integer value into the equivalent string in base radix 
notation storing the result in the character array pointed to by buffer. A null character is appended to 
the result. The size of buffer must be at least (8 * sizeof(int) + 1) bytes when converting values in base 
2. That makes the size 17 bytes on 16-bit machines, and 33 bytes on 32-bit machines. The value of 
radix must satisfy the condition: 

2 <= radix <= 36 


The _ utoa function is identical toutoa. Use _ utoa for ANSI naming conventions. 

The _ utow function is a wide-character version ofutoa. It produces a wide-character string. 

The utoa function returns the pointer to the result. 

atoi, atol, atoll, itoa, ltoa, Utoa, sscanf, strtol, strtoll, strtoul, strtoull, 
strtoimax, strtoumax, ultoa, ulltoa 


♦include <stdio.h> 
♦include <stdlib.h> 


void main() 

{ 

int base; 

char buffer[18]; 


} 


for( base = 
printf( 


2; base <= 16; base = base + 2 

"%2d %s\n", base, 

utoa( (unsigned) 12765, buffer. 


base 


) ; 


produces the following: 

2 11000111011101 
4 3013131 
6 135033 
8 30735 
10 12765 
12 7479 
14 491b 
16 31dd 


WATCOM 

_utoa conforms to ANSI naming conventions 
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utoa, _utoa, _utow 


Systems: utoa - All, Linux, RDOS, Netware 

_ utoa - All, Linux, RDOS, Netware 
_ utow - All, Linux, RDOS 
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vaarg 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


#include <stdarg.h> 

type va_ arg ( va_ list param, type ); 

va_ arg is a macro that can be used to obtain the next argument in a list of variable arguments. It must 
be used with the associated macros va_ start andva_ end. A sequence such as 

void example( char *dst, ... ) 

{ 

va_ list curr_ arg; 
int next_ arg; 

va_ start ( curr_ arg, dst ) ; 

next_ arg = va_ arg ( curr_ arg, int ); 


causes next_ arg to be assigned the value of the next variable argument. The argument type (which is 
int in the example) is the type of the argument originally passed to the function. 

The macro va_ start must be executed first in order to properly initialize the variable curr_ arg 
and the macro va_ end should be executed after all arguments have been obtained. 

The data item curr_ arg is of typeva_ list which contains the information to permit successive 
acquisitions of the arguments. 

The macro returns the value of the next variable argument, according to type passed as the second 
parameter. 


va_ end,va_ start.vfprintf, vprintf, vsprintf 


♦include <stdio.h> 
♦include <stdarg.h> 


static void test_ fn ( 

const char *msg, /* message to be printed 
const char *types, /* parameter types (i,s) 

... ) /* variable arguments 


va_ list 

int 

char 

const char 


argument; 
arg_ int; 
*arg_ string; 
*types_ ptr; 


*/ 

*/ 

*/ 
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va_arg 


Classification: 

Systems: 


types_ ptr = types; 

printf( "\n%s — %s\n", msg, types ); 
va_ start( argument, types ); 
while ( *types_ ptr != '\0' ) { 

if (*types_ptr == 'i') { 

arg_ int = va_ arg ( argument, int ); 
printf( "integer: %d\n", arg_ int ); 

} else if (*types_ptr == 's') { 

arg_ string = va_ arg ( argument, char * ); 
printf( "string: %s\n", arg_ string ); 

} 

—types_ ptr; 

} 

va_ end ( argument ) ; 

} 


void main( void ) 


{ 


} 


printf ( "VA..,TEST\n" ); 

test_ fn( "PARAMETERS: 1, \"abc\", 546", 
"isi", 1, "abc", 546 ); 
test_ fn( "PARAMETERS: \"def\", 789", 
"si", "def", 789 ); 


produces the following: 

VA...TEST 

PARAMETERS: 1, "abc", 546 — isi 
integer: 1 
string: abc 

integer: 546 

PARAMETERS: "def", 789 — si 
string: def 

integer: 789 

ISO C90 

MACRO 
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va end 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdarg.h> 

void va_ end ( va_ list param ) ; 

va_ end is a macro used to complete the acquisition of arguments from a list of variable arguments. It 
must be used with the associated macros va_ start andva_ arg. See the description forva_ arg 
for complete documentation on these macros. 

The macro does not return a value. 


va_ arg,va_ start,vfprintf, vprintf, vsprintf 


♦include <stdio.h> 

♦include <stdarg.h> 

♦include <time.h> 

♦define ESCAPE 27 

void tprintf( int row, int col, char *fmt, ... ) 

{ 

auto va_ list ap; 
char *pl, *p2; 

va_ start( ap, fmt ); 

pi = va_ arg ( ap, char * ) ; 

p2 = va_ arg ( ap, char * ); 

printf( "%c[%2.2d;%2.2dH", ESCAPE, row, col ); 
printf( fmt, pi, p2 ); 
va_ end ( ap ) ; 

} 

void main() 

{ 

struct tm time_ of_ day; 
time_ t ltime; 

auto char buf[26]; 


} 


time( &ltime ); 

_ localtime( &ltime, &time_ of_ day ); 
tprintf( 12, 1, "Date and time is: %s\n", 
_ asctime( &time_ of_ day, buf ) ); 


ISOC 


MACRO 
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va start 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


♦include <stdarg.h> 

void va_ start ( va_ list param, previous ) ; 

va_ start is a macro used to start the acquisition of arguments from a list of variable arguments. The 
param argument is used by the va_ arg macro to locate the current acquired argument. The previous 
argument is the argument that immediately precedes the " . . . " notation in the original function 
definition. It must be used with the associated macros va_ arg andva_ end. See the description of 
va_ arg for complete documentation on these macros. 

The macro does not return a value. 


va_ arg,va_ end,vfprintf, vprintf, vsprintf 

♦include <stdio.h> 

♦include <stdarg.h> 

♦include <time.h> 

♦define ESCAPE 27 


void tprintf( int row, int col, char *fmt, ... ) 

{ 

auto va_ list ap; 
char *pl, *p2; 

va_ start( ap, fmt ); 

pi = va_ arg ( ap, char * ); 

p2 = va_ arg ( ap, char * ); 

printf( "%c[%2.2d;%2.2dH", ESCAPE, row, col ); 
printf( fmt, pi, p2 ); 
va_ end ( ap ) ; 


void main() 

1 

struct tm 
time_ t 
auto char 


time_ of_ day; 
ltime; 
buf[26]; 


} 


time ( &ltime ); 

_ localtime( &ltime, &time_ of_ day ); 
tprintf( 12, 1, "Date and time is: %s\n", 
_ asctime( &time_ of_ day, buf ) ); 


ISOC 


MACRO 
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_vbprintf, 

Synopsis: 

Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


vbwprintf 


#include <stdio.h> 

♦include <stdarg.h> 

int _ vbprintf( char *buf, size_ t bufsize, 

const char *format, va_ list arg ) ; 
int _ vbwprintf( wchar_ t *buf, size_ t bufsize, 

const wchar_ t *format, va_ list arg ); 

The _ vbprintf function formats data under control of the format control string and writes the result 
to buf. The argument bufsize specifies the size of the character array buf into which the generated 
output is placed. The format string is described under the description of the print f function. The 
_ vbprintf function is equivalent to the_ bprintf function, with the variable argument list 
replaced with arg, which has been initialized by the va_ start macro. 

The _ vbwprintf function is a wide-character version of_ vbprintf. It accepts a wide-character 
string argument for format and produces wide character output. 

The _ vbprintf function returns the number of characters written, or a negative value if an output 
error occurred. 

_ bprintf,cprintf, fprintf, printf, sprintf, va_ arg,va_ end,va_ start, 
vcprintf, vfprintf, vprintf, vsprintf 

The following shows the use of _ vbprintf in a general error message routine. 

♦include <stdio.h> 

♦include <stdarg.h> 

♦include <string.h> 

char msgbuf[80]; 

char *fmtmsg( char *format, ... ) 

{ 

va_ list arglist; 

va_ start ( arglist, format ); 
strcpy ( msgbuf, "Error: " ); 

_ vbprintf ( &msgbuf[7], 73, format, arglist ); 
va_ end ( arglist ) ; 
return ( msgbuf ); 

} 

void main() 

{ 

char *msg; 

msg = fmtmsg( "%s %d %s", "Failed", 100, "times" ); 
printf ( "%s\n", msg ); 

} 

WATCOM 

_ vbprintf - All, Linux, RDOS, Netware 
_ vbwprintf - All, Linux 
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vcprintf 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <conio.h> 

♦include <stdarg.h> 

int vcprintf( const char *format, va_ list arg ) ; 

The vcprintf function writes output directly to the console under control of the argument format. 
The putch function is used to output characters to the console. The format string is described under 
the description of the print f function. The vcprintf function is equivalent to the cprintf 
function, with the variable argument list replaced with arg, which has been initialized by the 
va_ start macro. 

The vcprintf function returns the number of characters written, or a negative value if an output error 
occurred. When an error has occurred, errno contains a value indicating the type of error that has 
been detected. 


_ bprintf,cprintf, fprintf, printf, sprintf, va_ arg,va_ end,va_ start, 
_ vbprintf,vfprintf, vprintf, vsprintf 

♦include <conio.h> 

♦include <stdarg.h> 

♦include <time.h> 

♦define ESCAPE 27 


void tprintf( int row, int col, char *format, ... ) 

{ 

auto va_ list arglist; 


cprintf ( "%c[%2.2d;%2.2dH", ESCAPE, row, col ); 
va_ start( arglist, format ); 
vcprintf( format, arglist ); 
va_ end ( arglist ); 


void main() 

{ 

struct tm 
time_ t 
auto char 


time_ of_ day; 
ltime; 
buf[26]; 


} 


time ( &ltime ); 

_ localtime( &ltime, &time_ of_ day ); 
tprintf( 12, 1, "Date and time is: %s\n", 
_ asctime( &time_ of_ day, buf ) ); 


WATCOM 


All, Linux, RDOS, Netware 


Library Functions and Macros 1167 




vcscanf 


Synopsis: 

Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


#include <conio.h> 

♦include <stdarg.h> 

int vcscanf( const char *format, va_ list args ) 

The vcscanf function scans input from the console under control of the argument format. The 
vcscanf function uses the function getche to read characters from the console. The format string is 
described under the description of the scanf function. 

The vcscanf function is equivalent to the cscanf function, with a variable argument list replaced 
with arg, which has been initialized using the va_ start macro. 

The vcscanf function returns EOF when the scanning is terminated by reaching the end of the input 
stream. Otherwise, the number of input arguments for which values were successfully scanned and 
stored is returned. When a file input error occurs, the errno global variable may be set. 

cscanf, fscanf, scanf, sscanf, va_ arg,va_ end,va_ start,vfscanf, vscanf, 
vsscanf 


♦include <conio.h> 

♦include <stdarg.h> 

void cfind( char *format, ... ) 

{ 

va_ list arglist; 

va_ start ( arglist, format ); 
vcscanf ( format, arglist ); 
va_ end ( arglist ); 

} 


void main() 

{ 

int day, year; 

char weekday[10], month[10]; 


} 


cfind( "%s %s %d %d", 

weekday, month, &day, Syear 
cprintf( "\n%s, %s %d, %d\n", 

weekday, month, day, year ) ; 


WATCOM 


All, Linux, RDOS, Netware 
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vfprintf, vfwprintf 


Synopsis: 


Safer C: 


Description: 


Returns: 


See Also: 


Example: 


♦include <stdarg.h> 

♦include <stdio.h> 
int vfprintf( FILE *fp, 

const char *format, 
va_ list arg ); 

♦include <stdarg.h> 

♦include <stdio.h> 

♦include <wchar.h> 
int vfwprintf( FILE *fp, 

const wchar_ t *format, 
va_ list arg ); 

The Safer C Library extension provides the vfprintf_ s function which is a safer alternative to 
vfprintf This newer vfprintf_ s function is recommended to be used instead of the traditional 
"unsafe" vfprintf function. 

The vfprintf function writes output to the file pointed to by fp under control of the argument format. 
The format string is described under the description of the print f function. The vfprintf function 
is equivalent to the fprintf function, with the variable argument list replaced with arg, which has 
been initialized by the va_ start macro. 

The vfwprintf function is a wide-character version of vfprintf. It accepts a wide-character 
string argument for format and produces wide character output. 

The vfprintf function returns the number of characters written, or a negative value if an output error 
occurred. The vfwprintf function returns the number of wide characters written, or a negative value 
if an output error occurred. When an error has occurred, errno contains a value indicating the type of 
error that has been detected. 

_ bprintf,cprintf, fprintf, printf, sprintf, va_ arg,va_ end,va_ start, 

_ vbprintf,vcprintf, vprintf, vsprintf 

♦include <stdio.h> 

♦include <stdarg.h> 

FILE *LogFile; 

/* a general error routine */ 

void errmsg( char *format, ... ) 

{ 

va_ list arglist; 

fprintf ( stderr, "Error: " ); 
va_ start( arglist, format ); 
vfprintf( stderr, format, arglist ); 
va_ end ( arglist ); 
if( LogFile != NULL ) { 

fprintf ( LogFile, "Error: " ); 
va_ start( arglist, format ); 
vfprintf ( LogFile, format, arglist ); 
va_ end( arglist ); 

} 

} 
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vfprintf, vfwprintf 


Classification: 


Systems: 


void main( void ) 

{ 

LogFile = fopen( "error.log", "w" ); 

errmsg( "%s %d %s", "Failed", 100, "times" ); 

} 

ISOC 

vfwprintf is ISO C95 

vfprintf - All, Linux, RDOS, Netware 
vfwprintf - All, Linux 
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vfprintf_s, vfwprintf_s 


Synopsis: 


Constraints: 


Description: 


Returns: 


See Also: 


Example: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdarg.h> 

♦include <stdio.h> 

int vfprintf_ s( FILE * restrict stream, 

const char * restrict format, va_ list arg ); 

♦include <stdarg.h> 

♦include <wchar.h> 

int vfwprintf_ s( FILE * restrict stream, 

const wchar_ t * restrict format, va_ list prg ) ; 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and vfprintf_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither stream nor format shall be a null pointer. The %n specifier (modified or not by flags, field 
width, or precision) shall not appear in the string pointed to by format. Any argument to vfprintf_ s 
corresponding to a % s specifier shall not be a null pointer. 

If there is a runtime-constraint violation, the vfprintf_ s function does not attempt to produce 
further output, and it is unspecified to what extent vfprintf_ s produced output before discovering 
the runtime-constraint violation. 

The vfprintf_ s function is equivalent to thevprintf function except for the explicit 
runtime-constraints listed above. 

The vfwprintf_ s function is a wide-character version ofvfprintf_ s. It accepts a wide-character 
string argument for format and produces wide character output. 

The vfprintf_ s function returns the number of characters written, or a negative value if an output 
error or runtime-constraint violation occurred. 

The vfwprintf_ s function returns the number of wide characters written, or a negative value if an 
output error or runtime-constraint violation occurred. 

_ bprintf.cprintf, fprintf, printf, sprintf, _ vbprintf.vcprintf, vfprintf, 
vprintf, vsprintf 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <stdarg.h> 

FILE *LogFile; 

/* a general error routine */ 

void errmsgf char *format, ... ) 

{ 

va_ list arglist; 
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vfprintf_s, vfwprintf_s 


Classification: 

Systems: 


fprintf_ s( stderr, "Error: " ); 
va_ start( arglist, format ); 
vfprintf_ s( stderr, format, arglist ); 
va_ end ( arglist ) ; 
if( LogFile != NULL ) { 

fprintf_ s( LogFile, "Error: " ); 
va_ start( arglist, format ); 
vfprintf_ s ( LogFile, format, arglist ); 
va_ end( arglist ); 

} 

} 

void main( void ) 

{ 

errmsg( "%s %d %s", "Failed", 100, "times" ); 

} 

produces the following: 

Error: Failed 100 times 
TR 24731 

vfprintf_ s - All, Linux, RDOS, Netware 
vfwprintf_ s - All, Linux 
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vfscanf, vfwscanf 


Synopsis: 


Safer C: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


♦include <stdio.h> 

♦include <stdarg.h> 
int vfscanf( FILE *fp, 

const char ^format, 
va_ list arg ); 
int vfwscanf( FILE *fp, 

const wchar_ t *format, 
va_ list arg ) ; 

The Safer C Library extension provides the vf scanf_ s function which is a safer alternative to 
vfscanf This newer vfscanf_ s function is recommended to be used instead of the traditional 
"unsafe" vfscanf function. 

The vfscanf function scans input from the file designated by fp under control of the argument format. 
The format string is described under the description of the scanf function. 

The vfscanf function is equivalent to the f scanf function, with a variable argument list replaced 
with arg, which has been initialized using the va_ start macro. 

The vfwscanf function is a wide-character version of vfscanf. It accepts a wide-character string 
argument for format and produces wide character output. 

The vfscanf function returns EOF if an input failure occurred before any conversion. Otherwise, the 
number of input arguments for which values were successfully scanned and stored is returned. When a 
file input error occurs, the errno global variable may be set. 

cscanf, fscanf, scanf, sscanf, va_ arg,va_ end,va_ start,vcscanf, vscanf, 
vsscanf 


♦include <stdio.h> 

♦include <stdarg.h> 

void ffind( FILE *fp, char *format, ... ) 

{ 

va_ list arglist; 

va_ start ( arglist, format ); 
vfscanf ( fp, format, arglist ); 
va_ end ( arglist ); 

} 


void main( void ) 

{ 

int day, year; 

char weekday[10], month[10]; 


} 


ffind( stdin, 

”2-o 2-o 2-H 2-H” 

oo oo o LI o LI r 

weekday, month, &day, Syear ); 
printf ( "\n%s, %s %d, %d\n", 

weekday, month, day, year ); 


ISO C99 
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vfscanf, vfwscanf 


Systems: 


vfscanf - All, Linux, RDOS, 
vfwscanf - All, Linux 


Netware 
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vfscanf_s, vfwscanf_s 


Synopsis: 


Constraints: 


Description: 


Returns: 


See Also: 


Example: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdarg.h> 

♦include <stdio.h> 

int vfscanf_ s ( FILE * restrict stream, 

const char * restrict format, va_ list arg ); 

♦include <stdarg.h> 

♦include <stdio.h> 

♦include <wchar.h> 

int vfwscanf_ s( FILE * restrict stream, 

const wchar_ t * restrict format, va_ list arg ); 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and vf scanf_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither stream nor format shall be a null pointer. Any argument indirected through in order to store 
converted input shall not be a null pointer. 

If there is a runtime-constraint violation, the vf scanf_ s function does not attempt to perform further 
input, and it is unspecified to what extent vf scanf_ s performed input before discovering the 
runtime-constraint violation. 

The vf scanf_ s function is equivalent tof scanf_ s, with the variable argument list replaced by arg , 
which shall have been initialized by the va_ start macro (and possibly subsequentva_ arg calls). 
The vf scanf_ s function does not invoke theva_ end macro. 

The vfwscanf_ s function is identical tovf scanf_ s except that it accepts a wide-character string 
argument for format. 

The vf scanf_ s function returnsEOF if an input failure occurred before any conversion or if there 
was a runtime-constraint violation. Otherwise, the vf scanf_ s function returns the number of input 
items successfully assigned, which can be fewer than provided for, or even zero. 

When a file input error occurs, the errno global variable may be set. 

cscanf, fscanf, scanf, sscanf, va_ arg,va_ end,va_ start.vcscanf, vfscanf, 
vscanf, vsscanf 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <stdarg.h> 

void ffind( FILE *fp, char *format, ... ) 

{ 

va_ list arglist; 

va_ start( arglist, format ); 
vfscanf_ s ( fp, format, arglist ); 
va_ end( arglist ); 

} 
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vfscanf_s, vfwscanf_s 


Classification: 

Systems: 


void main( void ) 

{ 

int day, year; 

char weekday[10], month[10]; 


} 


ffind( stdin, 

ft 2- o 2- q 2-H 2-H” 

oo oo oCJ. o vj. ^ 

weekday, sizeof( weekday ), 
month, sizeof ( month ), 

&day, Syear ); 

printf_ s ( "\n%s, %s %d, %d\n", 

weekday, month, day, year ); 


TR 24731 


vfscanf_ s - All, Linux, RDOS, Netware 
vfwscanf_ s - All, Linux 
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vprintf, vwprintf 


Synopsis: 


Safer C: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


Systems: 


♦include <stdarg.h> 

♦include <stdio.h> 

int vprintf( const char *format, va_ list arg ); 

♦include <stdarg.h> 

♦include <wchar.h> 

int vwprintf ( const wchar_t *format, va_ list arg ); 

The Safer C Library extension provides the vprintf_ s function which is a safer alternative to 
vprintf This newer vprintf_ s function is recommended to be used instead of the traditional 
"unsafe" vprintf function. 

The vprintf function writes output to the file stdout under control of the argument format. The 
format string is described under the description of the printf function. The vprintf function is 
equivalent to the printf function, with the variable argument list replaced with arg, which has been 
initialized by the va_ start macro. 

The vwprintf function is a wide-character version of vprintf. It accepts a wide-character string 
argument for format and produces wide character output. 

The vprintf function returns the number of characters written, or a negative value if an output error 
occurred. The vwprintf function returns the number of wide characters written, or a negative value 
if an output error occurred. When an error has occurred, errno contains a value indicating the type of 
error that has been detected. 

_ bprintf,cprintf, fprintf, printf, sprintf, va_ arg,va_ end,va_ start, 

_ vbprintf,vcprintf, vfprintf, vsprintf 

The following shows the use of vprintf in a general error message routine. 

♦include <stdio.h> 

♦include <stdarg.h> 

void errmsg( char *format, ... ) 

{ 

va_ list arglist; 

printf ( "Error: " ); 
va_ start( arglist, format ) ; 
vprintf( format, arglist ); 
va_ end( arglist ); 

} 

void main( void ) 

{ 

errmsg( "%s %d %s", "Failed", 100, "times" ); 

} 

produces the following: 

Error: Failed 100 times 
ISOC 

vwprintf is ISO C95 

vprintf - All, Linux, RDOS, Netware 
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vprintf, vwprintf 


vwprintf - All, 


Linux 


1178 Library Functions and Macros 




vprintf_s, vwprintf_s 


Synopsis: 


Constraints: 


Description: 


Returns: 


See Also: 


Example: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdarg.h> 

♦include <stdio.h> 

int vprintf_ s( const char * restrict format, va_ list arg ); 

♦include <stdarg.h> 

♦include <wchar.h> 

int vwprintf_ s( const wchar_ t * restrict format, va_ list prg ); 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and vprintf_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Th e format argument shall not be a null pointer. The %n specifier (modified or not by flags, field width, 
or precision) shall not appear in the string pointed to by format. Any argument to vprintf_ s 
corresponding to a % s specifier shall not be a null pointer. 

If there is a runtime-constraint violation, the vprintf_ s function does not attempt to produce further 
output, and it is unspecified to what extent vprintf_ s produced output before discovering the 
runtime-constraint violation. 

The vprintf_ s function is equivalent to thevprintf function except for the explicit 
runtime-constraints listed above. 

The vwprintf_ s function is a wide-character version ofvprintf_ s. It accepts a wide-character 
string argument for format and produces wide character output. 

The vprintf_ s function returns the number of characters written, or a negative value if an output 
error or runtime-constraint violation occurred. 

The vwprintf_ s function returns the number of wide characters written, or a negative value if an 
output error or runtime-constraint violation occurred. 

_ bprintf.cprintf, fprintf, printf, sprintf, _ vbprintf.vcprintf, vfprintf, 
vprintf, vsprintf 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <stdarg.h> 

void errmsg( char *format, ... ) 

{ 

va_ list arglist; 

printf_ s( "Error: " ); 
va_ start ( arglist, format ); 
vprintf_ s( format, arglist ); 
va_ end ( arglist ); 

} 

void main( void ) 

{ 

errmsg( "%s %d %s", "Failed", 100, "times" ); 

} 
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vprintf_s, vwprintf_s 


Classification: 

Systems: 


produces the following: 

Error: Failed 100 times 
TR 24731 

vprintf_ s - All, Linux, RDOS, 
vwprintf_ s - All, Linux 


Netware 
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vscanf, vwscanf 


Synopsis: 

Safer C: 

Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


#include <stdarg.h> 

♦include <stdio.h> 

int vscanf( const char *format, va_ list arg ) ; 

♦include <stdarg.h> 

♦include <wchar.h> 

int vwscanf ( const wchar_ t *format, va_ list arg ); 

The Safer C Library extension provides the vscanf_ s function which is a safer alternative to 
vscanf This newer vscanf_ s function is recommended to be used instead of the traditional "unsafe" 
vscanf function. 

The vscanf function scans input from the file designated by stdin under control of the argument 
format. The format string is described under the description of the scanf function. 

The vscanf function is equivalent to the scanf function, with a variable argument list replaced with 
arg, which has been initialized using the va_ start macro. 

The vwscanf function is identical to vscanf except that it accepts a wide-character string argument 
for format. 

The vscanf function returns EOF if an input failure occurred before any conversion, values were 
successfully scanned and stored is returned. 

cscanf, fscanf, scanf, sscanf, va_ arg,va_ end,va_ start,vcscanf, vfscanf, 
vsscanf 


♦include <stdio.h> 

♦include <stdarg.h> 

void find( char *format, ... ) 

{ 

va_ list arglist; 

va_ start( arglist, format ); 
vscanf ( format, arglist ); 
va_ end ( arglist ); 

} 


void main( void ) 

{ 

int day, year; 

char weekday[10], month[10]; 


} 


find( "%s %s %d %d", 

weekday, month, &day, Syear ) ; 
printf ( "\n%s, %s %d, %d\n", 

weekday, month, day, year ); 


ISO C99 


vscanf - All, Linux, RDOS, Netware 
vwscanf - All, Linux 
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vscanf_s, vwscanf_s 


Synopsis: 


Constraints: 


Description: 


Returns: 


See Also: 


Example: 


♦ define_ STDC_ WANT_ LIB_ EXT1_1 

♦include <stdarg.h> 

♦include <stdio.h> 

int vscanf_ s ( const char * restrict format, va_ list arg ); 

♦include <stdarg.h> 

♦include <wchar.h> 

int vwscanf_ s( const wchar_ t * restrict format, va_ list arg ); 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and vscanf_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

The argument format shall not be a null pointer. Any argument indirected through in order to store 
converted input shall not be a null pointer. 

If there is a runtime-constraint violation, the vscanf_ s function does not attempt to perform further 
input, and it is unspecified to what extent vscanf_ s performed input before discovering the 
runtime-constraint violation. 

The vscanf_ s function is equivalent toscanf_ s, with the variable argument list replaced by arg, 
which shall have been initialized by the va_ start macro (and possibly subsequentva_ arg calls). 
The vscanf_ s function does not invoke theva_ end macro. 

The vwscanf_ s function is identical tovscanf_ s except that it accepts a wide-character string 
argument for format. 

The vscanf_ s function returnsEOF if an input failure occurred before any conversion or if there was 
a runtime-constraint violation. Otherwise, the vscanf_ s function returns the number of input items 
successfully assigned, which can be fewer than provided for, or even zero. 

When a file input error occurs, the errno global variable may be set. 

cscanf, fscanf, scanf, sscanf, va_ arg,va_ end,va_ start.vcscanf, vfscanf, 
vscanf, vsscanf 

♦ define_ STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <stdarg.h> 

void find( char *format, ... ) 

{ 

va_ list arglist; 

va_ start ( arglist, format ); 
vscanf_ s( format, arglist ); 
va_ end ( arglist ); 

} 

void main( void ) 

{ 

int day, year; 

char weekday[10], month[10]; 


1182 Library Functions and Macros 




vscanf_s, vwscanf_s 


Classification: 

Systems: 


} 


find( "%s %s %d %d", 

weekday, sizeof ( weekday ), 
month, sizeof( month ), 

&day, Syear ); 

printf_ s ( "\n%s, %s %d, %d\n", 

weekday, month, day, year ); 


TR 24731 


vscanf_ s - All, Linux, RDOS, Netware 
vwscanf_ s - All, Linux 
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vsnprintf, _vsnwprintf 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


#include <stdarg.h> 

♦include <stdio.h> 

int _ vsnprintf( char *buf, 

size_t count, 
const char *format, 
va_ list arg ); 

♦include <stdarg.h> 

♦include <wchar.h> 
int _ vsnwprintf ( wchar_ t *buf, 
size_t count, 
const wchar_ t ^format, 
va_ list arg ); 

The _ vsnprintf function formats data under control of th e format control string and stores the result 
in buf. The maximum number of characters to store is specified by count. A null character is placed at 
the end of the generated character string if fewer than count characters were stored. Th s format string is 
described under the description of the print f function. The _ vsnprintf function is equivalent to 
the _ snprintf function, with the variable argument list replaced with arg, which has been initialized 
by the va_ start macro. 

The _ vsnwprintf function is a wide-character version of_ vsnprintf. It accepts a wide-character 
string argument for format and produces wide character output. The argument buf specifies an array of 
wide characters into which the generated output is to be written, rather than converted to multibyte 
characters and written to a stream. The maximum number of wide characters to write is specified by 
count. A null wide character is placed at the end of the generated wide character string if fewer than 
count wide characters were stored. 

The _ vsnprintf function returns the number of characters written into the array, not counting the 
terminating null character, or a negative value if more than count characters were requested to be 
generated. An error can occur while converting a value for output. The _ vsnwprintf function 
returns the number of wide characters written into the array, not counting the terminating null wide 
character, or a negative value if more than count wide characters were requested to be generated. When 
an error has occurred, errno contains a value indicating the type of error that has been detected. 

_ bprintf,cprintf, fprintf, printf, sprintf, va_ arg,va_ end,va_ start, 

_ vbprintf,vcprintf, vfprintf, vprintf, vsprintf 

The following shows the use of _ vsnprintf in a general error message routine. 

♦include <stdio.h> 

♦include <stdarg.h> 

♦include <string.h> 

char msgbuf[80]; 

char *fmtmsg( char *format, ... ) 

{ 

va_ list arglist; 

va_ start ( arglist, format ); 
strcpy ( msgbuf, "Error: " ); 

_ vsnprintf ( &msgbuf[7], 80-7, format, arglist ); 
va_ end( arglist ); 
return ( msgbuf ); 

} 
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Classification: 

Systems: 


vsnprintf, _vsnwprintf 


void main() 

{ 

char *msg; 

msg = fmtmsg( "%s %d %s", "Failed", 100, "times" ); 
printf ( "%s\n", msg ); 

} 

WATCOM 

_ vsnprintf - All, Linux, RDOS, Netware 
_ vsnwprintf - All, Linux 
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vsnprintf, vsnwprintf 


Synopsis: 


Safer C: 


Description: 


Returns: 


See Also: 


Example: 


#include <stdarg.h> 

♦include <stdio.h> 

int vsnprintf( char *buf, 

size_ t count, 
const char *format, 
va_ list arg ); 

♦include <stdarg.h> 

♦include <wchar.h> 
int vsnwprintf( wchar_ t *buf, 
size_t count, 
const wchar_ t ^format, 
va_ list arg ); 

The Safer C Library extension provides the vsnprintf_ s function which is a safer alternative to 
vsnprintf This newer vsnprintf_ s function is recommended to be used instead of the traditional 
"unsafe" vsnprintf function. 

The vsnprintf function formats data under control of the format control string and stores the result 
in buf. The maximum number of characters to store, including a terminating null character, is specified 
by count. The format string is described under the description of the print f function. The 
vsnprintf function is equivalent to the _ snprintf function, with the variable argument list 
replaced with arg, which has been initialized by the va_ start macro. 

The vsnwprintf function is a wide-character version of vsnprintf. It accepts a wide-character 
string argument for format and produces wide character output. The argument buf specifies an array of 
wide characters into which the generated output is to be written, rather than converted to multibyte 
characters and written to a stream. The maximum number of wide characters to write, including a 
terminating null wide character, is specified by count. 

The vsnprintf function returns the number of characters that would have been written had count 
been sufficiently large, not counting the terminating null character, or a negative value if an encoding 
error occurred. Thus, the null-terminated output has been completely written if and only if the returned 
value is nonnegative and less than count. The vsnwprintf function returns the number of wide 
characters that would have been written had count been sufficiently large, not counting the terminating 
null wide character, or a negative value if an encoding error occurred. Thus, the null-terminated output 
has been completely written if and only if the returned value is nonnegative and less than count. When 
an error has occurred, errno contains a value indicating the type of error that has been detected. 

_ bprintf,cprintf, fprintf, printf, sprintf, va_ arg,va_ end,va_ start, 

_ vbprintf,vcprintf, vfprintf, vprintf, vsprintf 

The following shows the use of vsnprintf in a general error message routine. 
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vsnprintf, vsnwprintf 


Classification: 

Systems: 


♦include <stdio.h> 

♦include <stdlib.h> 

♦include <stdarg.h> 

♦include <string.h> 

char *fmtmsg( char *format, ... ) 

{ 

char *msgbuf; 

int len; 

va_ list arglist; 

va_ start ( arglist, format ); 

len = vsnprintf ( NULL, 0, format, arglist ); 

va_ end ( arglist ); 

len = len + 1 + 7; 

msgbuf = malloc( len ); 

strcpy( msgbuf, "Error: " ); 

va_ start( arglist, format ); 

vsnprintf( &msgbuf[7], len, format, arglist ); 
va_ end ( arglist ); 
return ( msgbuf ); 

} 

void main( void ) 

{ 

char *msg; 

msg = fmtmsg( "%s %d %s", "Failed", 100, "times" ); 
printf( "%s\n", msg ); 
free( msg ); 

} 

ISOC 

vsnprintf - All, Linux, RDOS, Netware 
vsnwprintf - All, Linux 
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vsnprintf_s, vsnwprintf_s 


Synopsis: 


Constraints: 


Description: 


Returns: 


See Also: 


Example: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdarg.h> 

♦include <stdio.h> 

int vsnprintf_ s( char * restrict s, rsize_t n 

const char * restrict format, va_ list arg ) ; 

♦include <stdarg.h> 

♦include <wchar.h> 

int vsnwprintf_ s ( char * restrict s, rsize_t n, 

const wchar_ t * restrict format, va_ list arg ) ; 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and vsnprintf_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither ,v nor format shall be a null pointer. The n argument shall neither equal zero nor be greater than 
RSI ZE_ MAX . The number of characters (including the trailing null) required for the result to be 
written to the array pointed to by 5 shall not be greater than n. The %n specifier (modified or not by 
flags, field width, or precision) shall not appear in the string pointed to by format. Any argument to 
vsnprintf_ s corresponding to a%s specifier shall not be a null pointer. No encoding error shall 
occur. 

If there is a runtime-constraint violation, then if .v is not a null pointer and n is greater than zero and less 
than RSIZE_ MAX, then thevsnprintf_ s function sets s[0] to the null character. 

The vsnprintf_ s function is equivalent to thevsnprintf function except for the explicit 
runtime-constraints listed above. 

The vsnprintf_ s function, unlikevsprintf_ s, will truncate the result to fit within the array 
pointed to by s. 

The vsnwprintf_ s function is a wide-character version ofvsnprintf_ s. It accepts a 
wide-character string argument for format and produces wide character output. 

The vsnprintf_ s function returns the number of characters that would have been written had n been 
sufficiently large, not counting the terminating null character, or a negative value if a runtime-constraint 
violation occurred. Thus, the null-terminated output has been completely written if and only if the 
returned value is nonnegative and less than n. 

The vsnprintf_ s function returns the number of wide characters that would have been written had n 
been sufficiently large, not counting the terminating wide null character, or a negative value if a 
runtime-constraint violation occurred. Thus, the null-terminated output has been completely written if 
and only if the returned value is nonnegative and less than n. 

_ bprintf.cprintf, fprintf, printf, sprintf, _ vbprintf.vcprintf, vfprintf, 
vprintf, vsprintf 

The following shows the use of vsnprintf_ s in a general error message routine. 
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vsnprintf_s, vsnwprintf_s 


♦ define_STDC_ WANT_ LIB_ EXT1 1 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <stdarg.h> 

♦include <string.h> 

char *fmtmsg( char *format, ... ) 

{ 

char *msgbuf; 

int len; 

va_ list arglist; 

va_ start ( arglist, format ); 

len = vsnprintf( NULL, 0, format, arglist ); 

va_ end( arglist ); 

len = len + 1 + 7; 

msgbuf = malloc ( len ); 

strcpy( msgbuf, "Error: " ); 

va_ start( arglist, format ); 

vsnprintf_ s( &msgbuf[7], len, format, arglist ); 
va_ end( arglist ); 
return ( msgbuf ); 

} 

void main( void ) 

{ 

char *msg; 

msg = fmtmsg( "%s %d %s", "Failed", 100, "times" ); 
printf_ s( "%s\n", msg ); 
free( msg ); 

} 

Classification: TR 24731 

Systems: vsnprintf_ s - All, Linux, RDOS, Netware 

vsnwprintf_ s - All, Linux 
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vsprintf, vswprintf 


Synopsis: 


Safer C: 


Description: 


Returns: 


See Also: 


Example: 


#include <stdarg.h> 

♦include <stdio.h> 
int vsprintf( char *buf, 

const char *format, 
va_ list arg ); 

♦include <stdarg.h> 

♦include <wchar.h> 
int vswprintf( wchar_ t *buf, 
size_ t count, 
const wchar_ t *format, 
va_ list arg ); 

The Safer C Library extension provides the vsprintf_ s function which is a safer alternative to 
vsprintf This newer vsprintf_ s function is recommended to be used instead of the traditional 
"unsafe" vsprintf function. 

The vsprintf function formats data under control of th e format control string and writes the result to 
buf. The format string is described under the description of the print f function. The vsprintf 
function is equivalent to the sprint f function, with the variable argument list replaced with arg, 
which has been initialized by the va_ start macro. 

The vswprintf function is a wide-character version of vsprintf. It accepts a wide-character 
string argument for format and produces wide character output. The argument buf specifies an array of 
wide characters into which the generated output is to be written, rather than converted to multibyte 
characters and written to a stream. The maximum number of wide characters to write, including a 
terminating null wide character, is specified by count. 

The vsprintf function returns the number of characters written, or a negative value if an output error 
occurred. The vswprintf function returns the number of wide characters written into the array, not 
counting the terminating null wide character, or a negative value if count or more wide characters were 
requested to be generated. 

_ bprintf,cprintf, fprintf, printf, sprintf, va_ arg,va_ end,va_ start, 

_ vbprintf,vcprintf, vfprintf, vprintf 

The following shows the use of vsprintf in a general error message routine. 

♦include <stdio.h> 

♦include <stdarg.h> 

♦include <string.h> 

char msgbuf[80]; 

char *fmtmsg( char *format, ... ) 

{ 

va_ list arglist; 

va_ start ( arglist, format ); 

strcpy ( msgbuf, "Error: " ); 

vsprintf( &msgbuf[7], format, arglist ); 

va_ end( arglist ); 

return ( msgbuf ); 

} 
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vsprintf, vswprintf 


Classification: 


Systems: 


void main( void ) 

{ 

char *msg; 

msg = fmtmsg( "%s %d %s", "Failed", 
printf ( "%s\n", msg ); 

} 

ISOC 

vswprintf is ISO C95 

vsprintf - All, Linux, RDOS, Netware 
vswprintf - All, Linux 


100, "times" ) ; 
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vsprintf_s, vswprintf_s 


Synopsis: 


Constraints: 


Description: 


Returns: 


See Also: 


Example: 


♦ define_ STDC_ WANT_ LIB_ EXT1_1 

♦include <stdarg.h> 

♦include <stdio.h> 

int vsprintf_ s( char * restrict s, rsize_t n 

const char * restrict format, va_ list arg ); 

♦include <stdarg.h> 

♦include <wchar.h> 

int vswprintf_ s ( char * restrict s, rsize_t n, 

const wchar_ t * restrict format, va_ list arg ); 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and vsprintf_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither ,v nor format shall be a null pointer. The n argument shall neither equal zero nor be greater than 
RSI ZE_ MAX . The number of characters (including the trailing null) required for the result to be 
written to the array pointed to by 5 shall not be greater than n. The %n specifier (modified or not by 
flags, field width, or precision) shall not appear in the string pointed to by format. Any argument to 
vsprintf_ s corresponding to a%s specifier shall not be a null pointer. No encoding error shall 
occur. 

If there is a runtime-constraint violation, then if .5 is not a null pointer and n is greater than zero and less 
than RSIZE_ MAX, then thevsprintf_ s function sets s[0] to the null character. 

The vsprintf_ s function is equivalent to thevsprintf function except for the explicit 
runtime-constraints listed above. 

The vsprintf_ s function, unlikevsnprintf_ s, treats a result too big for the array pointed to by s 
as a runtime-constraint violation. 

The vswprintf_ s function is a wide-character version ofvsprintf_ s. It accepts a wide-character 
string argument for format and produces wide character output. 

If no runtime-constraint violation occurred, the vsprintf_ s function returns the number of 
characters written in the array, not counting the terminating null character. If an encoding error 
occurred, vsprintf_ s returns a negative value. If any other runtime-constraint violation occurred, 
vsprintf_ s returns zero. 

If no runtime-constraint violation occurred, the vswprintf_ s function returns the number of wide 
characters written in the array, not counting the terminating null wide character. If an encoding error 
occurred or if n or more wide characters are requested to be written, vswprintf_ s returns a negative 
value. If any other runtime-constraint violation occurred, vswprintf_ s returns zero. 

_ bprintf.cprintf, fprintf, printf, sprintf, _ vbprintf.vcprintf, vfprintf, 
vprintf, vsprintf 

The following shows the use of vsprintf_ s in a general error message routine. 

♦ define_ STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <stdarg.h> 

♦include <string.h> 

char msgbuf[80]; 
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vsprintf_s, vswprintf_s 


Classification: 

Systems: 


char *fmtmsg( char *format, ... ) 

{ 

va_ list arglist; 

va_ start( arglist, format ); 

strcpy_ s ( msgbuf, sizeof( buffer ), "Error: " ); 
vsprintf_ s( &msgbuf[7], sizeof ( msgbuf ) - 7, 
format, arglist ); 
va_ end ( arglist ) ; 
return ( msgbuf ); 

} 

void main( void ) 

{ 

char *msg; 

msg = fmtmsg( "%s %d %s", "Failed", 100, "times" ); 
printf( "%s\n", msg ); 

} 

TR 24731 

vsprintf_ s - All, Linux, RDOS, Netware 
vswprintf_ s - All, Linux 


Library Functions and Macros 1193 




vsscanf, vswscanf 


Synopsis: 


Safer C: 


Description: 


Returns: 


See Also: 


Example: 


Classification: 


#include <stdio.h> 

♦include <stdarg.h> 

int vsscanf( const char *in_ string, 
const char ^format, 
va_ list arg ); 

int vswscanf( const wchar_ t *in_ string, 
const wchar_ t *format, 
va_ list arg ); 

The Safer C Library extension provides the vsscanf_ s function which is a safer alternative to 
vsscanf This newer vsscanf_ s function is recommended to be used instead of the traditional 
"unsafe" vsscanf function. 

The vsscanf function scans input from the string designated by in_string under control of the 
argument format. The format string is described under the description of the scanf function. 

The vsscanf function is equivalent to the sscanf function, with a variable argument list replaced 
with arg, which has been initialized using the va_ start macro. 

The vswscanf function is identical to vsscanf except that it accepts a wide-character string 
argument for format. 

The vsscanf function returns EOF if the end of the input string was reached before any conversion. 
Otherwise, the number of input arguments for which values were successfully scanned and stored is 
returned. 


cscanf, fscanf, scanf, sscanf, va_ arg,va_ end,va_ start,vcscanf, vfscanf, 
vscanf 


♦include <stdio.h> 

♦include <stdarg.h> 

void sfind( char *string, char *format, ... ) 

{ 

va_ list arglist; 

va_ start ( arglist, format ); 
vsscanf ( string, format, arglist ); 
va_ end ( arglist ); 

} 


void main( void ) 

{ 

int day, year; 

char weekday[10], month[10]; 


} 


sfind( "Saturday April 18 1987", 

”2-o 2-0 2-H 2-H" 

oo oo o LI o LI f 

weekday, month, &day, Syear ); 
printf ( "\n%s, %s %d, %d\n", 

weekday, month, day, year ); 


ISO C99 
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vsscanf, vswscanf 


Systems: 


vsscanf - All, Linux, RDOS, 
vswscanf - All, Linux 


Netware 
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vsscanf_s, vswscanf_s 


Synopsis: 


Constraints: 


Description: 


Returns: 


See Also: 


Example: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdarg.h> 

♦include <stdio.h> 

int vsscanf_ s ( const char * restrict s, 

const char * restrict format, 
va_ list arg ); 

♦include <stdarg.h> 

♦include <wchar.h> 

int vswscanf_ s ( const wchar_t * restrict s, 

const wchar_t * restrict format, 
va_ list arg ); 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and vsscanf_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither ,v not format shall be a null pointer. Any argument indirected through in order to store 
converted input shall not be a null pointer. 

If there is a runtime-constraint violation, the vsscanf_ s function does not attempt to perform further 
input, and it is unspecified to what extent vsscanf_ s performed input before discovering the 
runtime-constraint violation. 

The vsscanf_ s function is equivalent toss can f_ s, with the variable argument list replaced by arg, 
which shall have been initialized by the va_ start macro (and possibly subsequentva_ arg calls). 
The vsscanf_ s function does not invoke theva_ end macro. 

The vswscanf_ s function is identical tovsscanf_ s except that it accepts wide-character string 
arguments for ,v and format. 

The vsscanf_ s function returnsEOF if an input failure occurred before any conversion or if there 
was a runtime-constraint violation. Otherwise, the vsscanf_ s function returns the number of input 
items successfully assigned, which can be fewer than provided for, or even zero. 

When a file input error occurs, the errno global variable may be set. 

cscanf, fscanf, scanf, sscanf, va_ arg,va_ end,va_ start.vcscanf, vfscanf, 
vscanf, vsscanf 

♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <stdarg.h> 

void sfind( char *string, char *format, ... ) 

{ 

va_ list arglist; 

va_ start( arglist, format ); 
vsscanf_ s ( string, format, arglist ); 
va_ end ( arglist ) ; 

} 
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vsscanf_s, vswscanf_s 


void main( void ) 

{ 

int day, year; 

char weekday[10], month[10]; 


} 


sfind( "Friday August 0013 2004", 

”2-o 2-o 2-H 2-H” 

oo oo o LI o LI f 

weekday, sizeof ( weekday ), 
month, sizeof ( month ), 
&day, Syear ); 

printf_ s ( "\n%s, %s %d, %d\n", 

weekday, month, day, year ); 


produces the following: 

Friday, August 13, 2004 

Classification: TR 24731 


Systems: 


vsscanf_ s - All, Linux, RD0S, Netware 
vswscanf_ s - All, Linux 
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Synopsis: #include <process.h> 

int wait( int *status ) ; 

Description: The wait function suspends the calling process until any of the caller’s immediate child processes 
terminate. 

Under Win32, there is no parent-child relationship amongst processes so the wait function cannot and 
does not wait for child processes to terminate. To wait for any process, you must specify its process ID. 
For this reason, the cwait function should be used (one of its arguments is a process ID). 

If status is not NULL, it points to a word that will be filled in with the termination status word and 
return code of the terminated child process. 

If the child process terminated normally, then the low order byte of the status word will be set to 0, and 
the high order byte will contain the low order byte of the return code that the child process passed to the 
DOSEXIT function. The DOSEXIT function is called whenever main returns, or exit , or _ Exit or 
_ exit are explicity called. 

If the child process did not terminate normally, then the high order byte of the status word will be set to 
0, and the low order byte will contain one of the following values: 

Value Meaning 

1 Hard-error abort 

2 Trap operation 

3 SIGTERM signal not intercepted 

Note: This implementation of the status value follows the OS/2 model and differs from the 

Microsoft implementation. Under Microsoft, the return code is returned in the low 
order byte and it is not possible to determine whether a return code of 1, 2, or 3 imply 
that the process terminated normally. For portability to Microsoft compilers, you 
should ensure that the application that is waited on does not return one of these values. 
The following shows how to handle the status value in a portable manner. 
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Returns: 


See Also: 
Example: 


Classification: 


cwait ( Sstatus, process, id, WAIT_ CHILD ); 


#if defined (_WATCOMC_) 

switch( status & Oxff ) { 

case 0: 

printf( "Normal termination exit code = %d\n 
break; 
case 1: 

printf( "Hard-error abort\n" ); 
break; 
case 2: 

printf( "Trap operation\n" ); 
break; 
case 3: 


printf( "SIGTERM signal not intercepted\n" ) 
break; 
default: 

printf( "Bogus return status\n" ) ; 

} 


status » 8 ) ; 


#else if defined (_ MSC_ VER) 
switch( status & Oxff ) { 

case 1: 

printf ( "Possible Hard-error abort\n" ); 
break; 
case 2: 

printf ( "Possible Trap operation\n" ); 
break; 
case 3: 

printf( "Possible SIGTERM signal not intercepted\n" ); 
break; 
default: 

printf( "Normal termination exit code = %d\n", status ); 

} 

#endif 


The wait function returns the child's process ID if the child process terminated normally. Otherwise, 
wait returns -1 and sets errno to one of the following values: 

Constant Meaning 

ECHILD No child processes exist for the calling process. 

EINTR The child process terminated abnormally. 

cwait, exit, _ Exit,_ exit,spawn. . . 

♦include <stdlib.h> 

♦include <process.h> 

void main() 

{ 

int process_ id, status; 

process_ id = spawnl( P_ NOWAIT, "child.exe", 

"child", "parm", NULL ); 
wait( Sstatus ); 

} 

WATCOM 
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Systems: 


Win32, OS/2 l.x(all), OS/2-32, Linux 
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wcrtomb, Jwcrtomb 


Synopsis: 


Safer C: 


Description: 


Returns: 


See Also: 


♦include <wchar.h> 

int wcrtomb ( char *s, wchar_ t wc, mbstate_ t *ps ); 

int _ fwcrtomb ( char_far *s, wchar_ t wc, mbstate_ t_far *ps ) ; 

The Safer C Library extension provides the wcrtomb_ s function which is a safer alternative to 
wcrtomb This newer wcrtomb_ s function is recommended to be used instead of the traditional 
"unsafe" wcrtomb function. 

Ifis a null pointer, the wcrtomb function determines the number of bytes necessary to enter the 
initial shift state (zero if encodings are not state-dependent or if the initial conversion state is described). 
The resulting state described will be the initial conversion state. 

If ,v is not a null pointer, the wcrtomb function determines the number of bytes needed to represent the 
multibyte character that corresponds to the wide character given by wc (including any shift sequences), 
and stores the resulting bytes in the array whose first element is pointed to by s. At most MB_ CUR_ MAX 
bytes will be stored. If wc is a null wide character, the resulting state described will be the initial 
conversion state. 

The _ fwcrtomb function is a data model independent form of the wcrtomb function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

The restartable multibyte/wide character conversion functions differ from the corresponding 
internal-state multibyte character functions ( mblen, mbtowc, and wctomb) in that they have an extra 
argument, ps, of type pointer to mbstate_ t that points to an object that can completely describe the 
current conversion state of the associated multibyte character sequence. If ps is a null pointer, each 
function uses its own internal mbstate_ t object instead. You are guaranteed that no other function in 
the library calls these functions with a null pointer for ps, thereby ensuring the stability of the state. 

Also unlike their corresponding functions, the return value does not represent whether the encoding is 
state-dependent. 

If the encoding is state-dependent, on entry each function takes the described conversion state (either 
internal or pointed to by ps) as current. The conversion state described by the pointed-to object is 
altered as needed to track the shift state of the associated multibyte character sequence. For encodings 
without state dependency, the pointer to the mbstate_ t argument is ignored. 

If ,v is a null pointer, the wcrtomb function returns the number of bytes necessary to enter the initial 
shift state. The value returned will not be greater than that of the MB_ CUR_ MAX macro. 

If 5 is not a null pointer, the wcrtomb function returns the number of bytes stored in the array object 
(including any shift sequences) when wc is a valid wide character; otherwise (when wc is not a valid 
wide character), an encoding error occurs, the value of the macro EILSEQ will be stored in errno and 
-1 will be returned, but the conversion state will be unchanged. 

_ mbccmp,_ mbccpy,_ mbcicmp,_ mbcjistojms,_ mbc jmsto jis,_ mbclen,_ mbctohira, 

_ mbctokata^ mbctolower^. mbctombb^ mbctoupperjnblen, mbrlen, mbrtowc, 
mbsrtowcs, mbsrtowcs_ sjnbstowcs, mbstowcs_ s,mbtowc, btowc, wcrtomb_ s, 
wcsrtombs, wcsrtombs_ s,wcstombs, wcstombs_ s,wctob, wctomb, wctomb_ s 
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wcrtomb, _fwcrtomb 


Example: #include <stdio.h> 

♦include <wchar.h> 

♦include <mbctype.h> 

♦include <errno.h> 

const wchar_ t wc[] = { 

0 x0020, 

0 x002e, 

0x0031, 

0x0041, 

0x3000, /* double-byte space */ 

0xff21, /* double-byte A */ 

0x3048, /* double-byte Hiragana */ 

0x30a3, /* double-byte Katakana */ 

0xff61, /* single-byte Katakana punctuation */ 

0xff66, /* single-byte Katakana alphabetic */ 

0xff9f, /* single-byte Katakana alphabetic */ 

0x720d, /* double-byte Kanji */ 

0 x0000 

}; 

♦define SIZE sizeof( wc ) / sizeof( wchar_ t ) 

void main() 

{ 

int i, j, k; 

char s [ 2]; 

_ setmbcp( 932 ); 
i = wcrtomb( NULL, 0, NULL ); 
printf( "Number of bytes to enter " 

"initial shift state = %d\n", i ); 

j = l; 

for( i = 0; i < SIZE; i++ ) { 

j = wcrtomb( s, wc[i], NULL ); 
printf( "%d bytes in character ", j ); 
if ( errno == EILSEQ ) { 

printf( " - illegal wide character\n" ); 

} else { 

if ( j == 0 ) { 
k = 0; 

} else if ( j == 1 ) { 

k = s [0] ; 

} else if( j == 2 ) { 

k = s [0] «8 | s [1] ; 

} 

printf( " (%# 6 . 4x->%^6.4x)\n", wc[i], k ); 

} 

} 

} 

produces the following: 
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wcrtomb, Jwcrtomb 


Number of bytes to enter initial shift state = 0 
1 bytes in character (0x0020->0x0020) 

1 bytes in character (0x002e->0x002e) 

1 bytes in character (0x0031->0x0031) 

1 bytes in character (0x0041->0x0041) 

2 bytes in character (0x3000->0x8140) 

2 bytes in character (0xff21->0x8260) 

2 bytes in character (0x3048->0x82a6) 

2 bytes in character (0x30a3->0x8342) 

1 bytes in character (0xff61->0x00al) 

1 bytes in character (Oxff66->0x00a6) 

1 bytes in character (Oxff9f->0x00df) 

2 bytes in character (0x720d->0xe0al) 

1 bytes in character ( 0000->0x0069) 

Classification: ISO C 

_fwcrtomb is WATCOM 

Systems: wcrtomb - DOS, Windows, Win386, Win32, OS/2 1.x (all), OS/2-32, Linux, 

RDOS 

_ fwcrtomb - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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wcrtomb_s, Jwcrtomb^s 


Synopsis: 


Constraints: 


Description: 


Returns: 


See Also: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <wchar.h> 

errno_ t wcrtomb_ s ( size_ t * restrict retval, 

char * restrict s, rsize_ t smax, 
wchar_ t wc, mbstate_ t * restrict ps) ; 

errno_ t _ wcrtomb_ s ( size_ t_far * restrict retval, 

char_far * restrict s, rsize_ t smax, 

wchar_ t wc, mbstate_ t_far * restrict ps) ; 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and wcrtomb_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither retval nor ps shall be a null pointer. If ,v is not a null pointer, then smax shall not equal zero and 
shall not be greater than RSI ZE_ MAX. If 5 is not a null pointer, then smax shall be not be less than the 
number of bytes to be stored in the array pointed to by s. If .5 is a null pointer, then smax shall equal 
zero. 

If there is a runtime-constraint violation, then wcrtomb_ s does the following. If.? is not a null pointer 
and smax is greater than zero and not greater than RSIZE_ MAX, thenwcrtomb_ s sets s[0] to the null 
character. If retval is not a null pointer, then wcrtomb_ s sets *retval to (size_t)(-l). 

If ,v is a null pointer, the wcrtomb_ s function is equivalent to the call 
wcrtomb_s(&retval, buf, sizeof buf, L'\0\ ps) 

where retval and buf axe internal variables of the appropriate types, and the size of buf is greater than 
MB_CUR_MAX. 

If ,v is not a null pointer, the wcrtomb_ s function determines the number of bytes needed to represent 
the multibyte character that corresponds to the wide character given by wc (including any shift 
sequences), and stores the multibyte character representation in the array whose first element is pointed 
to by s. At most MB_ CUR_ MAX bytes are stored. If wc is a null wide character, a null byte is stored, 
preceded by any shift sequence needed to restore the initial shift state; the resulting state described is the 
initial conversion state. 

If wc does not correspond to a valid multibyte character, an encoding error occurs: the wcrtomb_ s 
function stores the value (size_t)(-l) into *retval and the conversion state is unspecified. Otherwise, the 
wcrtomb_ s function stores into *retval the number of bytes (including any shift sequences) stored in 
the array pointed to by s. 

The function is a data model independent form of the wcrtomb_s function that accepts far pointer 
arguments. It is most useful in mixed memory model applications. 

The wcrtomb_ s function returns zero if there was no runtime-constraint violation. Otherwise, a 
non-zero value is returned. 

_ mbccmp,_ mbccpy,_ mbcicmp,_ mbcjistojms,_ mbc jmsto jis^ mbclen,_ mbctohira, 
_ mbctokata^ mbctolower^_ mbctombb^ mbctoupperjnblen, mbrlen, mbrtowc, 
mbsrtowcs, mbsrtowcs_ sjnbstowcs, mbstowcs_ s,mbtowc, btowc, wcrtomb, 
wcsrtombs, wcsrtombs_ s.wcstombs, wcstombs_ s.wctob, wctomb, wctomb_ s 
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wcrtomb_s, _fwcrtomb_s 


Example: 


♦ define_STDC_ WANT_ LIB_ EXT1 1 

♦include <stdio.h> 

♦include <wchar.h> 

♦include <mbctype.h> 

♦include <errno.h> 

const wchar_t wc[] = { 

0 x0020, 

0 x002e, 

0x0031, 

0x0041, 

0x3000, 

0 xff21, 

0x3048, 

0x30a3, 

Oxff61, 

Oxff66, 

Oxff9f, 

0x720d, 

0 x0000 

} ; 

♦define SIZE 

int main() 

{ 

int 
char 
errno_ t 
size_ t 
mbstate_ t state; 

_ setmbcp( 932 ); 

j = i; 

for( i = 0; i < SIZE; i++ ) { 

rc = wcrtomb_ s ( Sretval, s, 2, wc[i], &state ); 
if( rc != 0 ) { 

printf ( " - illegal wide character\n" ); 

} else { 

printf ( "%d bytes in character ", retval ); 
if ( retval == 0 ) { 

k = 0; 

} else if ( retval == 1 ) { 

k = s[0] ; 

} else if( retval == 2 ) { 

k = s [0]«8 | s [1] ; 

} 

printf( "(%^6.4x->%^6.4x)\n", wc[i], k ); 

} 

} 

return ( 0 ); 

} 

produces the following: 


/* 

double-byte 

space */ 


/* 

double-byte 

A */ 


/* 

double-byte 

Hiragana 

* / 

/* 

double-byte 

Katakana 

*/ 

/* 

single-byte 

Katakana 

punctuation */ 

/* 

single-byte 

Katakana 

alphabetic */ 

/* 

single-byte 

Katakana 

alphabetic */ 

/* 

double-byte 

Kanji */ 



sizeof( wc ) / sizeof( wchar_ t ) 


i, j, k; 
s [2] ; 
rc; 

retval; 
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wcrtomb_s, Jwcrtomb^s 


1 

bytes 

in 

character 

(0x0020->0x0020) 

1 

bytes 

in 

character 

(0x002e->0x002e) 

1 

bytes 

in 

character 

(0x0031->0x0031) 

1 

bytes 

in 

character 

(0x0041->0x0041) 

2 

bytes 

in 

character 

(0x3000->0x8140) 

2 

bytes 

in 

character 

(0xff21->0x8260) 

2 

bytes 

in 

character 

(0x3048->0x82a6) 

2 

bytes 

in 

character 

(0x30a3->0x8342) 

1 

bytes 

in 

character 

(0xff61->0x00al) 

1 

bytes 

in 

character 

(0xff66->0x00a6) 

1 

bytes 

in 

character 

(Oxff9f->0x00df) 

2 

bytes 

in 

character 

(0x720d->0xe0al) 

1 

bytes 

in 

character 

( 0000->0x0069) 


Classification: TR 24731 

_fwcrtomb_s is s WATCOM 


Systems: wcrtomb_ s - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 

Linux, RDOS 

_ fwcrtomb_ s - DOS, Windows, Win386, Win32, OS/2 1.x (all), OS/2-32, 
RDOS 
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wcsrtombs, Jwcsrtombs 


Synopsis: 


Safer C: 


Description: 


Returns: 


#include <wchar.h> 
size_ t wcsrtombs( char *dst, 
const wchar_t **src, 
size_ t n, mbstate_ t *ps ); 

#include <wchar.h> 

size_ t _ fwcsrtombs( char _far *dst, 

const wchar_ t_far *_far *src, 

size_ t n, mbstate_ t_far *ps ) ; 

The Safer C Library extension provides the wcsrtombs_ s function which is a safer alternative to 
wcsrtombs This newer wcsrtombs_ s function is recommended to be used instead of the traditional 
"unsafe" wcsrtombs function. 

The wcsrtombs function converts a sequence of wide characters from the array indirectly pointed to 
by src into a sequence of corresponding multibyte characters that begins in the shift state described by 
ps, which, if dst is not a null pointer, are then stored into the array pointed to by dst. Conversion 
continues up to and including a terminating null wide character, but the terminating null character (byte) 
will not be stored. Conversion will stop earlier in two cases: when a code is reached that does not 
correspond to a valid multibyte character, or (if dst is not a null pointer) when the next multibyte 
character would exceed the limit of len total bytes to be stored into the array pointed to by dst. Each 
conversion takes place as if by a call to the wcrtomb function. 

If dst is not a null pointer, the pointer object pointed to by src will be assigned either a null pointer (if 
conversion stopped due to reaching a terminating null wide character) or the address just past the last 
wide character converted. If conversion stopped due to reaching a terminating null wide character and 
if dst is not a null pointer, the resulting state described will be the initial conversion state. 

The _ fwcsrtombs function is a data model independent form of the wcsrtombs function that accepts 
far pointer arguments. It is most useful in mixed memory model applications. 

The restartable multibyte/wide string conversion functions differ from the corresponding internal-state 
multibyte string functions ( mbstowcs and wcstombs) in that they have an extra argument, ps, of 
type pointer to mbstate_ t that points to an object that can completely describe the current conversion 
state of the associated multibyte character sequence. If ps is a null pointer, each function uses its own 
internal mbstate_ t object instead. You are guaranteed that no other function in the library calls these 
functions with a null pointer for ps, thereby ensuring the stability of the state. 

Also unlike their corresponding functions, the conversion source argument, src, has a pointer-to-pointer 
type. When the function is storing conversion results (that is, when dst is not a null pointer), the pointer 
object pointed to by this argument will be updated to reflect the amount of the source processed by that 
invocation. 

If the encoding is state-dependent, on entry each function takes the described conversion state (either 
internal or pointed to by ps) as current and then, if the destination pointer, dst, is not a null pointer, the 
conversion state described by the pointed-to object is altered as needed to track the shift state of the 
associated multibyte character sequence. For encodings without state dependency, the pointer to the 
mbstate_ t argument is ignored. 

If the first code is not a valid wide character, an encoding error occurs: The wcsrtombs function 
stores the value of the macro EILSEQ in errno and returns (size_ t) -1, but the conversion state 
will be unchanged. Otherwise, it returns the number of bytes in the resulting multibyte characters 
sequence, which is the same as the number of array elements modified when dst is not a null pointer. 
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See Also: 


Example: 


_ mbccmp,_ mbccpy,_ mbcicmp,_ mbcjistojms,_ mbc jmsto jis,_ mbclen^ mbctohira, 
_ mbctokata,_ mbctolower^ mbctombb,_ mbctoupperjnblen, mbrlen, mbrtowc, 
mbsrtowcs, mbsrtowcs_ sjnbstowcs, mbstowcs_ s,mbtowc, btowc, wcrtomb, 
wcrtomb_ s,wcsrtombs_ s,wcstombs, wcstombs_ s,wctob, wctomb, wctomb_ s 

♦include <stdio.h> 

♦include <wchar.h> 

♦include <mbctype.h> 

♦include <errno.h> 

const wchar_ t wc [ ] = { 

0 x0020, 

0 x002e, 

0x0031, 

0x0041, 

0x3000, 

0 xff21, 

0x3048, 

0x30a3, 

Oxff61, 

Oxff66, 

Oxff9f, 

0x720d, 

0 x0000 

} ; 

void main() 

{ 

int 

size_ t 

const wchar_ t *src; 
char mb[50]; 

mbstate_ t pstate; 

_ setmbcp( 932 ); 
src = wc; 

elements = wcsrtombs( mb, &src, 50, Spstate ); 
if( errno == EILSEQ ) { 

printf( "Error in wide character string\n" ) ; 

} else { 

for( i = 0; i < elements; i++ ) { 

printf( "0x%2.2x\n", mb[i] ); 


/* double-byte space */ 

/* double-byte A */ 

/* double-byte Hiragana */ 

/* double-byte Katakana */ 

/* single-byte Katakana punctuation */ 

/* single-byte Katakana alphabetic */ 

/* single-byte Katakana alphabetic */ 

/* double-byte Kanji */ 


i; 

elements ; 


} 

} 

produces the following: 
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wcsrtombs, Jwcsrtombs 


Classification: 


Systems: 


0 x20 

0 x2e 

0x31 

0x41 

0x81 

0x40 

0x82 

0x60 

0x82 

0 xa6 

0x83 

0x42 

Oxal 

0 xa6 

Oxdf 

OxeO 

Oxal 

ISOC 

_fwcsrtombs is WATCOM 

wcsrtombs - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, 
Linux, RDOS 

_ fwcsrtombs - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
RDOS 
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wcsrtombs_s, _fwcsrtombs_s 


Synopsis: #def ine _STDC_ WANT_ LIB_ EXT1_1 

errno_ t wcsrtombs_ s ( size_ t * restrict retval, 

char * restrict dst, 

rsize_ t dstmax, 

const wchar_ t ** restrict src, 

rsize_ t len, 

mbstate_t * restrict ps); 

errno_ t _ fwcsrtombs_ s ( size_ t_far * restrict retval, 

char _ far * restrict dst, 

rsize_ t dstmax, 

const wchar_ t_far *_far * restrict src, 

rsize_ t len, 

mbstate_t _far * restrict ps); 

Constraints: If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and wcsrtombs_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

None of retval, src, *src, or ps shall be null pointers. If dst is not a null pointer, then neither len nor 
dstmax shall be greater than RSI ZE_ MAX. If dst is a null pointer, then dstmax shall equal zero. If dst is 
not a null pointer.then dstmax shall not equal zero. If dst is not a null pointer and len is not less than 
dstmax, then the conversion shall have been stopped (see below) because a terminating null wide 
character was reached or because an encoding error occurred. 

If there is a runtime-constraint violation, then wcsrtombs_ s does the following. If retval is not a null 
pointer.then wcsrtombs_ s sets *retval to (size_t)(-l). If dst is not a null pointer and dstmax is 
greater than zero and less than RSIZE_ MAX, thenwcsrtombs_ s sets dst[0] to the null character. 

Description: The wcsrtombs_ s function converts a sequence of wide characters from the array indirectly pointed 
to by src into a sequence of corresponding multibyte characters that begins in the conversion state 
described by the object pointed to by ps. If dst is not a null pointer, the converted characters are then 
stored into the array pointed to by dst. Conversion continues up to and including a terminating null 
wide character, which is also stored. 

Conversion stops earlier in two cases: 

• when a wide character is reached that does not correspond to a valid multibyte character; 

• (if dst is not a null pointer) when the next multibyte character would exceed the limit of n total 
bytes to be stored into the array pointed to by dst. If the wide character being converted is the 
null wide character, then n is the lesser of len or dstmax. Otherwise, n is the lesser of len or 
dstmax-1. 

If the conversion stops without converting a null wide character and dst is not a null pointer, then a null 
character is stored into the array pointed to by dst immediately following any multibyte characters 
already stored. Each conversion takes place as if by a call to the wcrtomb function. 

If dst is not a null pointer, the pointer object pointed to by src is assigned either a null pointer (if 
conversion stopped due to reaching a terminating null wide character) or the address just past the last 
wide character converted (if any). If conversion stopped due to reaching a terminating null wide 
character, the resulting state described is the initial conversion state. 

Regardless of whether dst is or is not a null pointer, if the input conversion encounters a wide character 
that does not correspond to a valid multibyte character, an encoding error occurs: the wcsrtombs_ s 
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wcsrtombs_s, _fwcsrtombs_s 


Returns: 


See Also: 


Example: 


function stores the value (size_t)(-l) into *retval and the conversion state is unspecified. Otherwise, the 
wcsrtombs_ s function stores into *retval the number of bytes in the resulting multibyte character 
sequence, not including the terminating null character (if any). 

All elements following the terminating null character (if any) written by wcsrtombs_s in the array of 
dstmax elements pointed to by dst take unspecified values when wcsrtombs_ s returns. 

If copying takes place between objects that overlap, the objects take on unspecified values. 

The function is a data model independent form of the wcsrtombs_s function that accepts far pointer 
arguments. It is most useful in mixed memory model applications. 

The wcsrtombs_ s function returns zero if there was no runtime-constraint violation. Otherwise, a 
non-zero value is returned. 

_ mbccmp,_ mbccpy,_ mbcicmp,_ mbcjistojms,_ mbc jmsto jis,_ mbclen,_ mbctohira, 
_ mbctokata,_ mbctolower^_ mbctombb,_ mbctoupperjnblen, mbrlen, mbrtowc, 
mbsrtowcs, mbsrtowcs_ sjnbstowcs, mbstowcs_ s,mbtowc, btowc, wcrtomb, 
wcrtomb_ s.wcsrtombs, wcstombs, wcstombs_ s.wctob, wctomb, wctomb_ s 
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wcsrtombs_s, _fwcsrtombs_s 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <wchar.h> 

♦include <mbctype.h> 

♦include <errno.h> 

const wchar_ t wc[] = { 



0x0020, 

0x002e, 

0x0031, 

0x0041, 

0x3000, 

/* 

double-byte 

space */ 



Oxff21. 

/* 

double-byte 

A */ 



0x3048, 

/* 

double-byte 

Hiragana 

* / 


0x30a3, 

/* 

double-byte 

Katakana 

*/ 


Oxff61, 

/* 

single-byte 

Katakana 

punctuation */ 


Oxff66, 

/* 

single-byte 

Katakana 

alphabetic */ 


Oxff9f, 

/* 

single-byte 

Katakana 

alphabetic */ 


0x720d, 

/* 

double-byte 

Kanji */ 


} ; 

0x0000 





int 

{ 

main () 





int 


i; 




size_ t 


retval; 




const wchar_ t 

*src; 




char 


mb[50]; 




mbstate_ t 


pstate; 




errno_ t 


rc; 




_ setmbcp( 

932 

); 




src = wc; 

rc = wcsrtombs_ s ( Sretval, mb, 50, Ssrc, sizeof(wc), 
if( rc != 0 ) { 

printf( "Error in wide character string\n" ); 

} else { 

for( i = 0; i < retval; i++ ) { 

printf( "0x%2.2x\n", mb[i] ); 

} 

} 

return ( rc ); 

} 

produces the following: 


Spstate ) ; 
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wcsrtombs_s, _fwcsrtombs_s 


Classification: 


Systems: 


0x20 

0x2e 

0x31 

0x41 

0x81 

0x40 

0x82 

0x60 

0x82 

0xa6 

0x83 

0x42 

Oxal 

0xa6 

Oxdf 

OxeO 

Oxal 


TR 24731 

_fwcsrtombs_s is WATCOM 

wcsrtombs_ s - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
Linux, RDOS 

_ fwcsrtombs_ s - DOS, Windows, Win386, Win32, OS/2 1.x (all), OS/2-32, 
RDOS 
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Synopsis: 

Safer C: 

Description: 


Returns: 

See Also: 
Example: 


♦include <stdlib.h> 

size_ t wcstombs ( char *s, const wchar_ t *pwcs, size_ t n ); 

♦include <mbstring.h> 

size_ t _ fwcstombs( char _far *s, 

const wchar_ t_far *pwcs, 

size_ t n ) ; 

The Safer C Library extension provides the wcstombs_ s function which is a safer alternative to 
wcstombs This newer wcstombs_ s function is recommended to be used instead of the traditional 
"unsafe" wcstombs function. 

The wcstombs function converts a sequence of wide character codes from the array pointed to by 
pwcs into a sequence of multibyte characters and stores them in the array pointed to by s. The 
wcstombs function stops if a multibyte character would exceed the limit of n total bytes, or if the null 
character is stored. At most n bytes of the array pointed to by ,v will be modified. 

The _ fwcstombs function is a data model independent form of the wcstombs function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

If an invalid multibyte character is encountered, the wcstombs function returns (size_ t) -1. 
Otherwise, the wcstombs function returns the number of array elements modified, not including the 
terminating zero code if present. 

wcstombs_ sjnblen, mbtowc, mbstowcs, mbstowcs_ s,wctomb, wctomb_ s 

♦include <stdio.h> 

♦include <stdlib.h> 

wchar_ t wbuffer[] = { 

0x0073, 

0x0074, 

0x0072, 

0x0069, 

0x006e, 

0x0067, 

0x0000 

}; 

void main() 

{ 

char mbsbuffer[50]; 

int i, len; 

len = wcstombs( mbsbuffer, wbuffer, 50 ); 
if( len != -1 ) { 

for( i = 0; i < len; i++ ) 

printf ( "/%4.4x", wbuffer[i] ); 

printf( "\n" ); 
mbsbuffer[len] = '\0'; 

printf( "%s(%d)\n", mbsbuffer, len ); 

} 

} 

produces the following: 
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wcstombs, Jwcstombs 


Classification: 


Systems: 


/0073/0074/0072/0069/006e/0067 
string(6) 

ISOC 

_fwcstombs is WATCOM 

wcstombs - All, Linux, RDOS, Netware 

_ fwcstombs - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 
RDOS 
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Synopsis: #def ine_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdlib.h> 

errno_ t wcstombs_ s ( size_ t * restrict retval, 

char * restrict dst, 

rsize_ t dstmax, 

const wchar_ t * restrict src, 

rsize_ t len) ; 

errno_ t _ fwcstombs_ s ( size_ t_far * restrict retval, 

char _ far * restrict dst, 

rsize_ t dstmax, 

const wchar_ t_far * restrict src, 

rsize_ t len) ; 

Constraints: If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and wcstombs_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Neither retval nor src shall be a null pointer. If dst is not a null pointer, then neither len nor dstmax 
shall be greater than RSI ZE_ MAX. If dst is a null pointer, then dstmax shall equal zero. If dst is not a 
null pointer.then dstmax shall not equal zero. If dst is not a null pointer and len is not less than dstmax, 
then the conversion shall have been stopped (see below) because a terminating null wide character was 
reached or because an encoding error occurred. 

If there is a runtime-constraint violation, then wcstombs_ s does the following. If retval is not a null 
pointer.then wcstombs_ s sets *retval to (size_t)(-l). If dst is not a null pointer and dstmax is greater 
than zero and less than RSIZE_ MAX, thenwcstombs_ s sets dst[0] to the null character. 

Description: The wcstombs_ s function converts a sequence of wide characters from the array pointed to by src 
into a sequence of corresponding multibyte characters that begins in the initial shift state. If dst is not a 
null pointer.the converted characters are then stored into the array pointed to by dst. Conversion 
continues up to and including a terminating null wide character, which is also stored. 

Conversion stops earlier in two cases: 

when a wide character is reached that does not correspond to a valid multibyte character; 

(if dst is not a null pointer) when the next multibyte character would exceed the limit of n total bytes to 
be stored into the array pointed to by dst. If the wide character being converted is the null wide 
character, then n is the lesser of len or dstmax. Otherwise, n is the lesser of len or dstmax-1. 

If the conversion stops without converting a null wide character and dst is not a null pointer, then a null 
character is stored into the array pointed to by dst immediately following any multibyte characters 
already stored. Each conversion takes place as if by a call to the wcrtomb function. 

Regardless of whether dst is or is not a null pointer, if the input conversion encounters a wide character 
that does not correspond to a valid multibyte character, an encoding error occurs: the wcstombs_ s 
function stores the value (size_t)(-l) into *retval. Otherwise, the wcstombs_ s function stores into 
*retval the number of bytes in the resulting multibyte character sequence, not including the terminating 
null character (if any). 

All elements following the terminating null character (if any) written by wcstombs_s in the array of 
dstmax elements pointed to by dst take unspecified values when wcstombs_ s returns. 

If copying takes place between objects that overlap, the objects take on unspecified values. 
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wcstombss, _fwcstombs_s 


The function is a data model independent form of the wcstombs_s function that accepts far pointer 
arguments. It is most useful in mixed memory model applications. 

Returns: The wcstombs_ s function returns zero if there was no runtime-constraint violation. Otherwise, a 

non-zero value is returned. 

See Also: wcstombs, mblen, mbtowc, mbstowcs, mbstowcs_ s.wctomb, wctomb_ s 

Example: #def ine_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <stdlib.h> 

wchar_ t wbuffer[] = { 

0x0073, 

0x0074, 

0x0072, 

0x0069, 

0x006e, 

0x0067, 

0x0073, 

0x0074, 

0x0072, 

0x0069, 

0x006e, 

0x0067, 

0x0000 

}; 

int main() 

{ 

char mbsbuffer [ 50]; 

int i; 

size_ t retval; 
errno_ t rc; 

rc = wcstombs_ s ( Sretval, mbsbuffer, 50, wbuffer, sizeof( wbuffer 

) ) ; 

if( rc == 0 ) { 

for( i = 0; i < retval; i++ ) 

printf( "/%4.4x", wbufferfi] ); 
printf ( "\n" ) ; 
mbsbuffer[retval] = '\0'; 
printf( "%s(%d)\n", mbsbuffer, retval ); 

} 

return( rc ); 

} 

produces the following: 

/0073/0074/0072/0069/006e/0067 
string(6) 

Classification: TR 24731 

_fwcstombs_s is WATCOM 

Systems: wcstombs_ s - All, Linux, RDOS, Netware 
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wcstombss, _fwcstombs_s 


_ fwcstombs_ s - DOS, Windows, Win386, Win32, OS/2 1.x (all), OS/2-32, 
RDOS 
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wctob 


Synopsis: 

Description: 


Returns: 


See Also: 


Example: 


♦include <wchar.h> 
int wctob ( wint_ t wc ) ; 

The wctob function determines whether wc corresponds to a member of the extended character set 
whose multibyte character representation is as a single byte when in the initial shift state. 

The wctob function returns EOF if wc does not correspond to a multibyte character with length one; 
otherwise, it returns the single byte representation. 

_ mbccmp,_ mbccpy,_ mbcicmp,_ mbcjistojms,_ mbc jmsto jis,_ mbclen^_ mbctohira, 
_ mbctokata^ mbctolower^. mbctombb^ mbctoupperjnblen, mbrlen, mbrtowc, 
mbsrtowcs, mbsrtowcs_ sjnbstowcs, mbstowcs_ s,mbtowc, btowc, wcrtomb, 
wcrtomb_ s,wcsrtombs, wcsrtombs_ s,wcstombs, wcstombs_ s,wctomb, wctomb_ s 


♦include <stdio.h> 
♦include <wchar.h> 
♦include <mbctype.h> 


const wint_ t 
0x0020, 
0x002e, 
0x0031, 
0x0041, 

wc [ ] 

= 1 



0x3000, 

/* 

double-byte 

space */ 


Oxff21. 

/* 

double-byte 

A */ 


0x3048, 

/* 

double-byte 

Hiragana 

*/ 

0x30a3, 

/* 

double-byte 

Katakana 

*/ 

Oxff61, 

/* 

single-byte 

Katakana 

punctuation */ 

Oxff66, 

/* 

single-byte 

Katakana 

alphabetic */ 

Oxff9f, 

/* 

single-byte 

Katakana 

alphabetic */ 

0x720d, 

0x0000 

/* 

double-byte 

Kanji */ 



} ; 


♦ define SIZE sizeof( wc ) / sizeof( wchar_ t ) 

void main() 

{ 

int i, j; 

_ setmbcp( 932 ) ; 
for ( i = 0; i < SIZE; i++ ) { 

j = wctob( wc[i] ) ; 

if( j == EOF ) { 

printf ( "%#6.4x EOF\n", wc[i] ); 

} else { 

printf ( "%^6.4x->%^6.4x\n", wc[i], j ); 

} 

} 

} 

produces the following: 
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wctob 


Classification: 

Systems: 


0x0020->0x0020 
0x002e->0x002e 
0x0031->0x0031 
0x0041->0x0041 
0x3000 EOF 
Oxff21 EOF 
0x3048 EOF 
0x30a3 EOF 
0xff61->0x00al 
0xff66->0x00a6 
Oxff9f->0x00df 
0x720d EOF 
0000->0x0000 

ISOC 


DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, RDOS 
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wctomb, _fwctomb 


Synopsis: 

Safer C: 

Description: 


Returns: 


See Also: 
Example: 


Classification: 


♦include <stdlib.h> 

int wctomb( char *s, wchar_ t wc ); 

♦include <mbstring.h> 

int _ fwctomb ( char_far *s, wchar_ t wc ) ; 

The Safer C Library extension provides the wctomb_ s function which is a safer alternative to 
wctomb This newer wctomb_ s function is recommended to be used instead of the traditional "unsafe" 
wctomb function. 

The wctomb function determines the number of bytes required to represent the multibyte character 
corresponding to the wide character contained in wc. If ,v is not a NULL pointer, the multibyte character 
representation is stored in the array pointed to by s. At most MB_ CUR_ MAX characters will be stored. 

The _ fwctomb function is a data model independent form of the wctomb function that accepts far 
pointer arguments. It is most useful in mixed memory model applications. 

If .5 is a NULL pointer, the wctomb function returns zero if multibyte character encodings are not state 
dependent, and non-zero otherwise. If s is not a NULL pointer, the wctomb function returns: 

Value Meaning 

-1 if the value of wc does not correspond to a valid multibyte character 

len the number of bytes that comprise the multibyte character corresponding to the value of wc. 

wctomb_ sjnblen, mbstowcs, mbstowcs_ sjnbtowc, wcstombs, wcstombs_ s 

♦include <stdio.h> 

♦include <stdlib.h> 

wchar_ t wchar = { 0x0073 }; 
char mbbuffer [2]; 

void main() 

{ 

int len; 

printf ( "Character encodings are %sstate dependent\n", 

( wctomb( NULL, 0 ) ) 

? "" : "not " ); 

len = wctomb( mbbuffer, wchar ); 
mbbuffer[len] = '\0'; 

printf ( "%s(%d)\n", mbbuffer, len ); 

} 

produces the following: 

Character encodings are not state dependent 
s (1) 

ISOC 

_fwctomb is WATCOM 
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wctomb, Jwctomb 


Systems: 


wctomb - 
_ fwctomb 


All, Linux, RDOS, Netware 
- DOS, Windows, Win386, Win32, 


OS/2 1.x(all), 


OS/2-32, 


RDOS 
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wctomb_s, _fwctomb_s 


Synopsis: 


Constraints: 


Description: 


Returns: 


See Also: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdlib.h> 

errno_ t wctomb_ s ( int * restrict status, 

char * restrict s, 
rsize_ t smax, 
wchar_ t wc) ; 

errno_ t _ fwctomb_ s ( int_far * restrict status, 

char _ far * restrict s, 

rsize_ t smax, 
wchar_ t wc) ; 

If any of the following runtime-constraints is violated, the currently active runtime-constraint handler 
will be invoked and wctomb_ s will return a non-zero value to indicate an error, or the 
runtime-constraint handler aborts the program. 

Let n denote the number of bytes needed to represent the multibyte character corresponding to the wide 
character given by wc (including any shift sequences). 

If .5 is not a null pointer, then smax shall not be less than n, and smax shall not be greater than 
RSIZE_ MAX. If s is a null pointer, then smax shall equal zero. 

If there is a runtime-constraint violation, wctomb_ s does not modify the int pointed to by status, and if 
s is not a null pointer, no more than smax elements in the array pointed to by 5 will be accessed. 

The wctomb_ s function determines n and stores the multibyte character representation of wc in the 
array whose first element is pointed to by s (if ,v is not a null pointer). The number of characters stored 
never exceeds MB_ CUR_ MAX or smax. If wc is a null wide character, a null byte is stored, preceded by 
any shift sequence needed to restore the initial shift state, and the function is left in the initial 
conversion state. 

The implementation shall behave as if no library function calls the wctomb_ s function. 

If .5 is a null pointer.the wctomb_ s function stores into the int pointed to by status a nonzero or zero 
value, if multibyte character encodings, respectively, do or do not have state-dependent encodings. 

If ,v is not a null pointer.the wctomb_ s function stores into the int pointed to by status either n or -1 if 
wc, respectively, does or does not correspond to a valid multibyte character. 

In no case will the int pointed to by status be set to a value greater than the MB_ CUR_ MAX macro. 

The function is a data model independent form of the wctomb_s function that accepts far pointer 
arguments. It is most useful in mixed memory model applications. 

The wctomb_ s function returns zero if there was no runtime-constraint violation. Otherwise, a 
non-zero value is returned. 

wctomb, mblen, mbstowcs, mbstowcs_ sjnbtowc, wcstombs, wcstombs_ s 
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Example: 


Classification: 


Systems: 


♦ define_STDC_ WANT_ LIB_ EXT1_1 

♦include <stdio.h> 

♦include <stdlib.h> 

wchar_ t wchar = { 0x0073 }; 
char mbbuffer[3]; 

int main() 

{ 

int len; 

int status; 

errno_ t rc; 

rc = wctomb_ s ( &status, NULL, 0, wchar ); 

printf ( "Character encodings are %sstate dependent\n", 

( status ) ? "" : "not " ); 

rc = wctomb_ s ( &len, mbbuffer, 2, wchar ); 
if( rc != 0) { 

printf ( "Character encoding error\n"); 

} else { 

mbbuffer[len] = '\0'; 

printf ( "%s(%d)\n", mbbuffer, len ); 

} 

return ( rc ); 

} 

produces the following: 

Character encodings are not state dependent 
s (1) 

TR 24731 

_fwctomb_s is WATCOM 

wctomb_ s - All, Linux, RDOS, Netware 

_ fwctomb_ s - DOS, Windows, Win386, Win32, OS/2 1.x (all), OS/2-32, 
RDOS 


1224 Library Functions and Macros 




wctrans 


Synopsis: 

Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


♦include <wctype.h> 

wctrans_ t wctrans( const char ^property ); 

The wctrans function constructs a value with type wctrans_ t that describes a mapping between 
wide characters identified by the string argument property. The constructed value is affected by the 
LC_ CTYPE category of the current locale; the constructed value becomes indeterminate if the 
category's setting is changed. 

The two strings listed below are valid in all locales as property arguments to the wctrans function. 
Constant Meaning 

tolower uppercase characters are mapped to lowercase 

toupper lowercase characters are mapped to uppercase 

If properly identifies a valid class of wide characters according to the LC_ CTYPE category of the 
current locale, the wctrans function returns a non-zero value that is valid as the second argument to 
the towctrans function; otherwise, it returns zero. 

isalnum, isalpha, isblank, iscntrl, isdigit, isgraph, isleadbyte, islower, 
isprint, ispunct, isspace, isupper, iswctype, isxdigit, tolower, toupper, 
towctrans 

♦include <stdio.h> 

♦include <wctype.h> 

char translations [ 2 ] = { 

"tolower", 

"toupper" 

} ; 


void main( void ) 

{ 

int i; 

wint_ t wc = 'A'; 
wint_ t twc; 

for( i = 0; i < 2; i++ ) { 

twc = towctrans! wc, wctrans! translations [ i] ) ); 

printf( "%s(%lc): %lc\n", translations[i], wc, twc ); 

} 

} 

produces the following: 

tolower(A): a 
toupper(A): A 

ISO C95 

All, Linux, RDOS, Netware 
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wctype 


Synopsis: 

Description: 


Returns: 


See Also: 


♦include <wctype.h> 

wctype_ t wctype( const char *property ) ; 

The wctype function constructs a value with type wctype_ t that describes a class of wide characters 
identified by the string argument, property. The constructed value is affected by the LC_ CTYPE 
category of the current locale; the constructed value becomes indeterminate if the category's setting is 
changed. 

The twelve strings listed below are valid in all locales as properly arguments to the wctype function. 
Constant Meaning 

alnum any wide character for which one of iswalpha or iswdigit is true 

alpha any wide character for which iswupper or iswlower is true, that is, for any wide 

character that is one of an implementation-defined set for which none of iswcntrl, 
iswdigit, iswpunct, or iswspace is true 

blank any wide character corresponding to a standard blank character (space or horizontal 

tab) or is one of an implementation-defined set of wide characters for which 
iswblank is true 

cntrl any control wide character 

digit any wide character corresponding to a decimal-digit character 

graph any printable wide character except a space wide character 

lower any wide character corresponding to a lowercase letter, or one of an 

implementation-defined set of wide characters for which none of iswcntrl, 
iswdigit, iswpunct, or iswspace is true 

print any printable wide character including a space wide character 

punct any printable wide character that is not a space wide character or a wide character for 

which iswalnum is true 

space any wide character corresponding to a standard white-space character or is one of an 

implementation-defined set of wide characters for which iswalnum is false 

upper any wide character corresponding to a uppercase letter, or if c is one of an 

implementation-defined set of wide characters for which none of iswcntrl, 
iswdigit, iswpunct, or iswspace is true 

xdigit any wide character corresponding to a hexadecimal digit character 

If property identifies a valid class of wide characters according to the LC_ CTYPE category of the 
current locale, the wctype function returns a non-zero value that is valid as the second argument to the 
iswctype function; otherwise, it returns zero. 

isalnum, isalpha, isblank, iscntrl, isdigit, isgraph, isleadbyte, islower, 
isprint, ispunct, isspace, isupper, iswctype, isxdigit, tolower, toupper, 
towctrans 
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wctype 


Example: 


Classification: 

Systems: 


♦include <stdio.h> 
♦include <wchar.h> 

char *types[] = { 
"alnum", 
"blank", 
"alpha", 
"cntrl", 
"digit", 
"graph", 
"lower", 

"print", 

"punct", 
"space", 
"upper", 
"xdigit" 

} ; 


void main( void ) 

{ 

int i; 

wint_ t wc = 'A'; 


} 


for ( 


i = 0; i < 12; i++ ) 
if( iswctype( wc, wctype( types[i] 
printf ( "%s\n", types[i] ); 


) ) ) 


produces the following: 

alnum 

alpha 

graph 

print 

upper 

xdigit 

ISO C95 


All, Linux, RDOS 
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wrapon 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


♦include <graph.h> 

short _ FAR _ wrapon ( short wrap ) ; 

The _ wrapon function is used to control the display of text when the text output reaches the right side 
of the text window. This is text displayed with the _ outtext and_ outmem functions. The wrap 
argument can take one of the following values: 

_GWRAPON causes lines to wrap at the window border 

_GWRAPOFF causes lines to be truncated at the window border 

The _ wrapon function returns the previous setting for wrapping. 

_ outtext^ outmem^ settextwindow 


♦include <conio.h> 
♦include <graph.h> 
♦include <stdio.h> 


main () 

{ 

int i; 

char buf[ 80 ]; 


_ setvideomode( _ TEXTC80 ); 

_ settextwindow( 5, 20, 20, 30 ); 

_ wrapon ( _ GWRAPOFF ); 
for( i = 1; i <= 3; ++i ) { 

_ settextposition ( 2 * i, 1 ); 

sprintf ( buf, "Very very long line %d", i ); 

_ outtext( buf ); 

1 

_ wrapon ( _ GWRAPON ); 

for( i = 4; i <= 6; ++i ) { 

_ settextposition ( 2 * i, 1 ); 

sprintf ( buf, "Very very long line %d", i ); 

_ outtext( buf ); 

} 

getch(); 

_ setvideomode( _ DEFAULTMODE ) ; 


PC Graphics 
DOS 
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write, _write 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


♦include <io.h> 

int write( int handle, void *buffer, unsigned len ); 
int _ write( int handle, void *buffer, unsigned len ); 

The write function writes data at the operating system level. The number of bytes transmitted is 
given by len and the data to be transmitted is located at the address specified by buffer. 

The _ write function is identical towrite. Use _ write for ANSI naming conventions. 

The handle value is returned by the open function. The access mode must have included either 
0_ WRONLY or0_ RDWR when theopen function was invoked. 

The data is written to the file at the end when the file was opened with 0_ APPEND included as part of 
the access mode; otherwise, it is written at the current file position for the file in question. This file 
position can be determined with the tell function and can be set with the lseek function. 

When 0_ BINARY is included in the access mode, the data is transmitted unchanged. WhenO_ TEXT is 
included in the access mode, the data is transmitted with extra carriage return characters inserted before 
each linefeed character encountered in the original data. 

A file can be truncated under DOS and OS/2 2.0 by specifying 0 as the len argument. Note, however, 
that this doesn’t work under OS/2 2.1, Windows NT/2000, and other operating systems. To truncate a 
file in a portable manner, use the chsize function. 

The write function returns the number of bytes (does not include any extra carriage-return characters 
transmitted) of data transmitted to the file. When there is no error, this is the number given by the len 
argument. In the case of an error, such as there being no space available to contain the file data, the 
return value will be less than the number of bytes transmitted. A value of -1 may be returned in the case 
of some output errors. When an error has occurred, errno contains a value indicating the type of error 
that has been detected. 


chsize, close, creat, dup, dup2, eof, exec. . ., fdopen, filelength, fileno, fstat, 
_ grow_ handlesisatty, lseek, open, read, setmode, sopen, stat, tell, umask 

♦include <stdio.h> 

♦include <io.h> 

♦include <fcntl.h> 


char bufferf] 

= { "A text record to be written" }; 

void main( void ) 

{ 

int handle; 

int size_ written; 


/* open a file for output */ 

/* replace existing file if it exists */ 
handle = open( "file", 

0_ WRONLY | 0_ CREAT | 0_ TRUNC 
S_ IRUSR | S_ IWUSR | S_ IRGRP 
if( handle != -1 ) { 


0_ TEXT, 

S_ IWGRP ) ; 
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/* write the text */ 

size_ written = write( handle, buffer, 

sizeof ( buffer ) ); 

/* test for error */ 

if ( size_ written != sizeof( buffer ) ) { 

printf( "Error writing file\n" ); 

} 


/* close the file */ 

close ( handle ); 

} 

} 

Classification: POSIX 1003.1 

_write conforms to ANSI naming conventions 

Systems: write - All, Linux, RDOS, Netware 

_ write - DOS, Windows, Win386, Win32, OS/2 l.x(all), OS/2-32, 


RDOS 
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5 Re-entrant Functions 


The following functions in the C library are re-entrant: 


abs 

atoi 

atol 

bsearch 

bsearch_ s 

div 

tabs 

_ fmbsrtowcs_ 

_ fmbstowcs_ s 

_ fmemccpy 

_ fmemchr 

_ fmemcmp 

_ fmemcpy 

_ fmemicmp 

_ fmemmove 

_ fmemset 

_ fstrcat 

_ fstrchr 

_ fstrcmp 

_ fstrcpy 

_ fstrcspn 

_ fstricmp 

_ fstrlen 

_ fstrlwr 

_ fstrncat 

_ fstrncmp 

_ fstrncpy 

_ fstrnicmp 

_ fstrnset 

_ fstrpbrk 

_ fstrrchr 

_ fstrrev 

_ fstrset 

_ fstrspn 

_ fstrstr 

_ fstrupr 

_ fwcrtombs_ s 

_ fwcsrtombs_ 

s _ fwcstombs_ 

s _ fwctomb_ 

isalnum 

isalpha 

isascii 

isblank 

iscntrl 

isdigit 

isgraph 

islower 

isprint 

ispunct 

isspace 

isupper 

isxdigit 

itoa 

labs 

ldiv 

lfind 

longjmp 

_ lrotl 

_ lrotr 

lsearch 

ltoa 

_ makepath 

mblen 

mbsrtowcs_ s 

mbstowcs 

mbstowcs_ s 

mbtowc 

memccpy 

memchr 

memcmp 

memcpy 

memcpy_ s 

memicmp 

memmove 

memmove_ s 

memset 

movedata 

qsort 

qsort_ s 

_ rotl 

_ rotr 

segread 

set jmp 

_ splitpath 

strcat 

strcat_ s 

strchr 

strcmp 

strcoll 

strcpy 

strcpy_ s 

strcspn 

strerror_ s 

strerrorlen_ s 

stricmp 

strlen 

strlwr 

strncat 

strncat_ s 

strncmp 

strncpy 

strncpy_ s 

strnicmp 

strnlen_ s 

strnset 

strpbrk 

strrchr 

strrev 

strset 

strspn 

strstr 

strtok_ s 

strupr 

swab 

tolower 

toupper 

ultoa 

utoa 

wcrtombs_ s 

wcscat_ s 

wcscpy_ s 

wcserror_ s 

wcserrorlen_ 

wcsncat_ s 

wcsncat_ s 

wcsncpy_ s 

wcsnlen_ s 

wcsrtombs_ s 

wcstok_ s 

wcstombs 

wcstombs_ s 

wctomb 

wctomb_ s 

wmemcpy_ s 

wmemmove_ s 
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Implementation-Defined Behavior of the C Library 


A. Implementation-Defined Behavior of the C 
Library 


This appendix describes the behavior of the 16-bit and 32-bit Open Watcom C libraries when the 
ISO/ANSI C Language standard describes the behavior as implementation-defined. The term describing 
each behavior is taken directly from the ISO/ANSI C Language standard. The numbers in parentheses at 
the end of each term refers to the section of the standard that discusses the behavior. 


A.1 NULL Macro 

The null pointer constant to which the macro NULL expands (7.1.6). 

The macro NULL expands to 0 in small data models and to OL in large data models. 

A.2 Diagnostic Printed by the assert Function 

The diagnostic printed by and the termination behavior of the assert function (7.2). 

The assert function prints a diagnostic message to stderr and calls the abort routine if the 
expression is false. The diagnostic message has the following form: 

Assertion failed: [expression], file [name], line [number] 


A.3 Character Testing 

The sets of characters tested for by the isalnum, isalpha, iscntrl, islower, isprint, and 

is upper functions (7.3.1). 


Function 

Characters Tested For 

isalnum 

Characters 0-9, A-Z, a-z 

isalpha 

Characters A-Z, a-z 

iscntrl 

ASCII OxOO-Oxlf, 0x7f 

islower 

Characters a-z 

isprint 

ASCII 0x20-0x7e 

isupper 

Characters A-Z 
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A.4 Domain Errors 


The values returned by the mathematics functions on domain errors (7.5.1). 


When a domain error occurs, the listed values are returned by the following functions: 

Function 

Value returned 

acos 

0.0 

acosh 

- HUGE_VAL 

asin 

0.0 

atan2 

0.0 

atanh 

- HUGEJVAL 

log 

- HUGEJVAL 

loglO 

- HUGEJVAL 

log2 

- HUGEJVAL 

pow(negjrac) 

0.0 

pow(0.0,0.0) 

1.0 

pow(0.0,neg) 

- HUGEJVAL 

sqrt 

0.0 

yO 

- HUGEJVAL 

yi 

- HUGEJVAL 

yn 

- HUGEJVAL 


A.5 Underflow of Floating-Point Values 

Whether the mathematics functions set the integer expression errno to the value of the macro ERANGE 
on underflow range errors (7.5.1). 

The integer expression errno is not set to ERANGE on underflow range errors in the mathematics 
functions. 


A.6 The fmod Function 

Whether a domain error occurs or zero is returned when the fmod function has a second argument of 
zero (7.5.6.4). 

Zero is returned when the second argument to fmod is zero. 

A.7 The signal Function 

The set of signals for the signal function (7.7.1.1). 

See the description of the signal function presented earlier in this book. 

The semantics for each signal recognized by the signal function (7.7.1.1). 

See the description of the signal function presented earlier in this book. 
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The default handling and the handling at program startup for each signal recognized by the signal 
function (7.7.1.1). 

See the description of the signal function presented earlier in this book. 


A.8 Default Signals 

If the equivalent of signal( sig, SIG_DFL ) is not executed prior to the call of a signal handler, the 
blocking of the signal that is performed (7.7.1.1). 

The equivalent of 

signal ( sig, SIG_ DFL ); 

is executed prior to the call of a signal handler. 

A.9 The SIGILL Signal 

Whether the default handling is reset if the SIGILL signal is received by a handler specified to the 
signal function (7.7.1.1). 

The equivalent of 

signal ( SIGILL, SIG_ DFL ); 
is executed prior to the call of the signal handler. 

A.10 Terminating Newline Characters 

Whether the last line of a text stream requires a terminating new-line character (7.9.2). 

The last line of a text stream does not require a terminating new-line character. 


A.11 Space Characters 

Whether space characters that are written out to a text stream immediately before a new-line character 
appear when read in (7.9.2). 

All characters written out to a text stream will appear when read in. 
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A.12 Null Characters 


The number of null characters that may be appended to data written to a binary stream (7.9.2). 

No null characters are appended to data written to a binary stream. 

A. 13 File Position in Append Mode 

Whether the file position indicator of an append mode stream is initially positioned at the beginning or 
end of the file (7.9.3). 

When a file is open in append mode, the file position indicator initially points to the end of the file. 


A.14 Truncation of Text Files 

Whether a write on a text stream causes the associated file to be truncated beyond that point (7.9.3). 

Writing to a text stream does not truncate the file beyond that point. 

A. 15 File Buffering 

The characteristics of file buffering (7.9.3). 

Disk files accessed through the standard I/O functions are fully buffered. The default buffer size is 512 
bytes for 16-bit systems, and 4096 bytes for 32-bit systems. 

A. 16 Zero-Length Files 

Whether a zero-length file actually exists (7.9.3). 

A file with length zero can exist. 


A.17 File Names 


The rules of composing valid file names (7.9.3). 

A valid file specification consists of an optional drive letter (which is always followed by a colon), a series 
of optional directory names separated by backslashes, and a file name. 

FAT File System: Directory names and file names can contain up to eight characters followed optionally by 
a period and a three letter extension. The complete path (including drive, directories and file name) cannot 
exceed 143 characters. Case is ignored (lowercase letters are converted to uppercase letters). 

HPFS File System: Directory names and file names can contain up to 254 characters in the OS/2 High 
Performance File System (HPFS). However, the complete path (including drive, directories and file name) 
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cannot exceed 259 characters. The period is a valid file name character and can appear in a file name or 
directory name as many times as required; HPFS file names do not require file extensions as in the FAT file 
system. The HPFS preserves case in file names only in directory listings but ignores case in file searches 
and other system operations (i.e, a directory cannot have more than one file whose names differ only in 
case). 


A. 18 File Access Limits 

Whether the same file can be open multiple times (7.9.3). 

It is possible to open a file multiple times. 

A. 19 Deleting Open Files 

The effect of the remove function on an open file (7.9.4.1). 

The remove function deletes a file, even if the file is open. 

A.20 Renaming with a Name that Exists 

The effect if a file with the new name exists prior to a call to the rename function (7.9.4.2). 

The rename function will fail if you attempt to rename a file using a name that exists. 

A.21 Printing Pointer Values 

The output for %p conversion in the fprintf function (7.9.6.1). 

Two types of pointers are supported: near pointers (%hp), and far pointers (%lp). The output for %p 
depends on the memory model being used. 

In 16-bit mode, the fprintf function produces hexadecimal values of the form XXXX for 16-bit near 
pointers, and XXXX:XXXX (segment and offset separated by a colon) for 32-bit far pointers. 

In 32-bit mode, the fprintf function produces hexadecimal values of the form XXXXXXXX for 32-bit 
near pointers, and XXXX:XXXXXXXX (segment and offset separated by a colon) for 48-bit far pointers. 

A.22 Reading Pointer Values 

The input for %p conversion in the f scanf function (7.9.6.2). 

The f scanf function converts hexadecimal values into the correct address when the %p format specifier 
is used. 
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A.23 Reading Ranges 

The interpretation of a - character that is neither the first nor the last character in the scanlist for % [ 
conversion in the f scanf function (7.9.6.2). 

The character indicates a character range. The character prior to the is the first character in the 
range. The character following the is the last character in the range. 


A.24 File Position Errors 


The value to which the macro errno is set by the fgetpos or ftell function on failure (7.9.9.1, 
7.9.9.4). 

When the function fgetpos or ftell fails, they set errno to EBADF if the file number is bad. The 
constants are defined in the <errno . h> header file. 


A.25 Messages Generated by the perror Function 

The messages generated by the perror function (7.9.10.4). 

The perror function generates the following messages. 

Error Message 

0 "Error 0" 

1 "No such file or directory" 

2 "Argument list too big" 

3 "Exec format error" 

4 "Bad file number" 

5 "Not enough memory" 

6 "Permission denied" 

7 "File exists" 

8 "Cross-device link" 

9 "Invalid argument" 

10 "File table overflow" 

11 "Too many open files" 

12 "No space left on device" 

13 "Argument too large" 

14 "Result too large" 

15 "Resource deadlock would occur" 


A.26 Allocating Zero Memory 

The behavior of the calloc, malloc, or realloc function if the size requested is zero (7.10.3). 

The value returned will be NULL. No actual memory is allocated. 
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A.27 The abort Function 


The behavior of the abort function with regard to open and temporary files (7.10.4.1). 

The abort function does not close any files that are open or temporary, nor does it flush any output 
buffers. 


A.28 The atexit Function 


The status returned by the exit function if the value of the argument is other than zero, 

EXIT_ SUCCESS, orEXIT_ FAILURE (7.10.4.3). 

The exit function returns the value of its argument to the operating system regardless of its value. 


A.29 Environment Names 


The set of environment names and the method for altering the environment list used by the getenv 
function (7.10.4.4). 

The set of environment names is unlimited. Environment variables can be set from the DOS command line 
using the SET command. A program can modify its environment variables with the putenv function. 
Such modifications last only until the program terminates. 

A.30 The system Function 

The contents and mode of execution of the string by the system function (7.10.4.5). 

The system function executes an internal DOS, Windows, or OS/2 command, or an EXE, COM, BAT or 
CMD file from within a C program rather than from the command line. The system function examines 
the COMSPEC environment variable to find the command interpreter and passes the argument string to the 
command interpreter. 


A.31 The strerror Function 


The contents of the error message strings returned by the strerror function (7.11.6.2). 

The strerror function generates the following messages. 

Error Message 

0 "Error 0” 

1 "No such file or directory" 

2 "Argument list too big" 

3 "Exec format error" 
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4 "Bad file number” 

5 "Not enough memory" 

6 "Permission denied" 

7 "File exists" 

8 "Cross-device link" 

9 "Invalid argument" 

10 "File table overflow" 

11 "Too many open files" 

12 "No space left on device" 

13 "Argument too large" 

14 "Result too large" 

15 "Resource deadlock would occur" 


A.32 The Time Zone 

The local time zone and Daylight Saving Time (7.12.1). 

The default time zone is "Eastern Standard Time" (EST), and the corresponding daylight saving time zone 
is "Eastern Daylight Saving Time" (EDT). 


A.33 The clock Function 

The era for the clock function (7.12.2.1). 

The clock function’s era begins with a value of 0 when the program starts to execute. 
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11ntroduction to C 


1.1 History 

The C programming language was developed by Dennis Ritchie in 1972 for the UNIX operating system. 
Over the years, the language has appeared on many other systems, satisfying a need of programmers who 
want to be able to develop applications that can run in many different environments. 

Because the C language was never formally defined, each implementation interpreted the behavior of the 
language in slightly different ways, and also introduced their own extensions. As a result, the goal of true 
software portability was not achieved. 

In 1982, the American National Standards Committee formed the X3J11 Technical Committee on the C 
Programming Language, whose purpose was to formally define the C language and its library functions, 
and to describe its interaction with the execution environment. The C Programming Language standard 
was completed in 1989. 

The Open Watcom C 16 and C 32 compiler has evolved from 8086 code generation technology developed 
and refined at WATCOM International and the University of Waterloo since 1980. The first Open Watcom 
C 16 compiler was released in 1988. The first Open Watcom C 32 compiler was released in 1989. 


1.2 Uses 


C is sometimes called a "low-level" language, referring to the fact that C programmers tend to think in 
terms of bits, bytes, addresses and other concepts fundamental to assembly-language programming. 

But C is also a "broad spectrum" language. In addition to accessing the basic components of the computer, 
it also provides features common to many "high-level" languages. Structured program control, data 
structures and modular program design are recent additions to some high-level languages, but have been 
part of the C language since its inception. 

C gives the programmer the ability to write applications at a level just above the assembly language level, 
without having to know the assembly language of the machine. Language compilers provided this ability in 
the past, but the application was often quite "fat", because the code produced by the compiler was never as 
good as could be written by a good assembly language programmer. But with modern code generation 
techniques it is often difficult, if not impossible, to distinguish an assembly language program written by a 
human from the same program generated by a C compiler (based on code size). In fact, some compilers 
now generate better code than all but the best assembly language programmers. 

So, what can C be used for? It can be used to write virtually anything, the same way that assembly 
language can be used. But other programming languages continue to be used for specific programming 
applications at which they excel. 

C tends to be used for "systems programming", a term that refers to the writing of operating systems, 
programming languages and other software tools that don't fall into the class of "applications 
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programming". A classic example is the UNIX operating system, developed by Bell Laboratories. It is 
written almost entirely in C and is one of the most portable operating systems available. 

C is also used for writing large programs that require more efficiency than the average application. Typical 
examples are interpreters and compilers for programming languages. 

Another area where C is commonly used is large-scale application programs, such as databases, 
spreadsheets, word processors and so on. These require a high degree of efficiency and compactness, since 
they are often basic to an individual’s or company’s computing needs, and therefore consume a lot of 
computer resources. 

It seems that C is used extensively for commercially available products, but C can also be used for any 
application that just requires more efficiency. For example, a large transaction processing system may be 
written in COBOL, but to squeeze the last bit of speed out of the system, it may be desirable to rewrite it in 
C. That application could certainly be written in assembly language, but many programmers now prefer to 
avoid programming at such a low level, when a C compiler can generate code that is just as efficient. 

Finally, of course, a major reason for writing a program in C is that it will run with little or no modification 
on any system with a C compiler. In the past, with the proliferation of C compilers and no standard to 
guide their design, it was much more difficult. Today, with the appearance of the ISO standard for the C 
programming language, a program written entirely in a conforming C implementation should be 
transportable to a new compiler with relatively little work. Of course, issues like file names, memory 
layout and command line parameter syntax will vary from one system to another, but a properly designed C 
application will isolate these parts of the code in "system-dependent" files, which can be changed for each 
system. (Refer to "Writing Portable Programs".) 

1.3 Advantages 

C has a number of major advantages over other programming languages. 

• Most systems provide a C compiler. 

Vendors of computer systems realize that the success of a system is dependent upon the availability of 
software for that system. With the large body of C-based programs in existence, most vendors provide a C 
compiler in order to encourage the transporting of some of these programs to their system. For systems that 
don't provide a C compiler, independent companies may develop a compiler. 

With the development of the ISO/ANSI C standard, the trend towards universal availability of C compilers 
will probably accelerate. 

• C programs can be transported easily to other computers and operating systems. 

Many programming languages claim transportability. FORTRAN, COBOL and Pascal programs all have 
standards describing them, so a program written entirely within the standard definition of the language will 
likely be portable. The same is true of C. However, few languages can match portability with the other 
advantages of C, including efficiency of generated code and the ability to work close to the machine level. 

• Programs written in C are very efficient in both execution speed and code size. 

Few languages can match C in efficiency. A good assembly language programmer may be able to produce 
code better than a C compiler, but he/she will have to spend much more time in the development of the 
application, because assembly language programming lends itself more easily to errors. Compilers for 
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other languages may produce efficient code for applications within their scope, but few produce efficient 
code for all applications. 

• C programs can get close to the hardware, controlling devices directly if necessary. 

Most programs do not need this ability, but if necessary, the program can access particular features of the 
computer. For example, a fixed memory location may exist that contains a certain value of use to the 
program. It is easy to access it from C, but not from many other languages. (Of course, if the program is 
designed to be portable, this section of code will be isolated and clearly marked as depending on the 
operating system.) 

• C programs are easy to maintain. 

Assembly language code is difficult to maintain owing to the very low level of programming (registers, 
addressing modes, branching). C programs provide comparable functionality, but at a higher level. The 
programmer still thinks in terms of machine capabilities, but without having to know the exact operation of 
the hardware, leaving the programmer free to concentrate on program design rather than the intimate details 
of coding on that particular machine. 

• C programs are easy to understand. 

"Easy" is, of course, a relative term. C programs are definitely easier to understand than the equivalent 
assembly language program. Another programming language may be easier to understand for a particular 
kind of application, but in general C is a good choice. 

• All of the above advantages apply regardless of the application or the hardware or operating system 
on which it is running. 

This is the biggest advantage. Because C programs are portable, and C is not suited only to a certain class 
of applications, it is often the best choice for developing an application. 


1.4 How to Use This Book 


This book is a description of the C programming language as implemented by the Open Watcom C 16 and 
C 32 compilers for the 80x86 family of processors. It is intended to be an easy-to-read description of the C 
language. The ISO C standard is the last word on details about the language, but it describes the language 
in terms that must be interpreted for each implementation of a C compiler. 

This book attempts to describe the C language in terms of general behavior, and the specific behavior of the 
C compiler when the standard describes the behavior as implementation-defined. 

Areas that are shaded describe the interpretation of the behavior that the Open Watcom C 16 and 
C 32 compilers follow. 


Programmers who are writing a program that will be ported to other systems should pay particular attention 
when using these features, since other compilers may behave in other ways. As much as possible, an 
attempt is made to describe other likely behaviors. 

This book does not describe any of the library functions that a C program might use to interact with its 
environment. In particular, input and output is not described in this manual. The C language does not 
contain any I/O capabilities. The Open Watcom C Library Reference manual describes all of the library 
functions, including those used for input and output. 
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A glossary is included in the appendix, and describes all terms used in the book. 


6 How to Use This Book 




Language Reference 



Language Reference 


8 




2 Notation 


The C programming language contains many useful features, each of which has a number of optional parts. 
The ISO C standard describes the language in very precise terms, often giving syntax diagrams to describe 
the features. 

This book attempts to describe the C language in more friendly terms. Where possible, features are 
described using ordinary English. Jargon is avoided, although by necessity, new terminology is introduced 
throughout the book. A glossary is provided at the end of the book to describe any terms that are used. 

Where the variety of features would create excessive amounts of text, simple syntax diagrams are used. It 
is hoped that these are mostly self-explanatory. However, a brief explanation of the notation used is 
offered here: 

1. Required keywords are in normal lettering style (for example, enum). 

2. Terms that describe a class of object that replace the term are in italics (for example, identifier). 

3. When two or more optional forms are available, they are shown as follows: 

form 1 

or 

form 2 

4. Any other symbol that appears is required, unless otherwise noted. 

The following example is for an enumerated type: 

enum identifier 

or 

enum { enumeration-constant-list } 

or 

enum identifier { enumeration-constant-list } 

An enumerated type has three forms: 

1. The required keyword enum followed by an identifier that names the type. The identifier is 
chosen by the programmer. 

2. The required keyword enum followed by a brace-enclosed list of enumeration constants. The 
braces are required, and enumeration-constant-list is described elsewhere. 

3. The required keyword enum followed by an identifier and a brace-enclosed list of enumeration 
constants. As with the previous two forms, the identifier may be chosen by the programmer, the 
braces are required and enumeration-constant-list is described elsewhere. 
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3 Basic Language Elements 


The following topics are discussed: 

• Character Sets 

• Keywords 

• Identifiers 

• Comments 


3.1 Character Sets 

The source character set contains the characters used during the translation of the C source file into object 
code. The execution character set contains the characters used during the execution of the C program. In 
most cases, these two character sets are the same, since the program is compiled and executed on the same 
machine. However, C is sometimes used to cross-compile, whereby the compilation of the program occurs 
on one machine, but the compiler generates code for some other machine. If the two machines have 
different character sets (say EBCDIC and ASCII), then the compiler will, where appropriate, map 
characters from the source character set to the execution character set. This mapping is 
implementation-defined, but generally maps the visual representation of the character. 

Regardless of which C compiler is used, the source and execution character sets contain (at least) the 
following characters: 

abcdefghi jklmnopqrstuvwxyz 
ABCDEFGHIJKLMNOPQRSTUVWXYZ 
0123456789 
!"#%&' ()* + ,-./ 

:;< = >?[ \ 1 A _ 1 | }~ 

as well as the space (blank), horizontal tab, vertical tab and form feed. Also, a new line character will exist 
for both the source and execution character sets. 

Any character other than those previously listed should appear in a source file in a character constant, a 
string or a comment, otherwise the behavior is undefined. 

If the character set of the computer being used to compile the program does not contain a certain character, 
a trigraph sequence may be used to represent it. Refer to the section "Character Constants". 
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The Open Watcom C 16 and C 32 compilers use the full IBM PC character set as both the source 
and execution character sets. The set of values from hexadecimal 00 to 7F constitute the ASCII 
character set. 


3.1.1 Multibyte Characters 

A multibyte character, as its name implies, is a character whose representation consists of more than one 
byte. Multibyte characters allow compilers to provide extended character sets, often for human languages 
that contain more characters than those found in the one-byte character set. 

Multibyte characters are generally restricted to: 

• comments, 

• string literals, 

• character constants, 

• header names. 

The method for specifying multibyte characters generally varies depending upon the extended character set. 

3.2 Keywords 

The following words are reserved as part of the C language and are called keywords. They may not be used 
for any kind of identifier, including object names, function names, labels, structure or union tags (names). 


auto 

double 

inline 

static 

_ Bool 

else 

int 

struct 

break 

enum 

long 

switch 

case 

extern 

register 

typedef 

char 

float 

restrict 

union 

_ Complex 

for 

return 

unsigned 

const 

goto 

short 

void 

continue 

if 

signed 

volatile 

default 

_ Imaginary sizeof 

while 

do 




The Open Watcom compilers also reserve the following extended keywords: 

Microsoft compilers compatible 



_asm 


_ finally 

_pascal 

_based 


_ fortran 

_ saveregs 

_ cdecl 


_huge 

_ segment 

_ declspec 


_ inline 

_ segname 

_except 


_int 64 

_self 

_export 


_ interrupt 

_ stdcall 

_far 


_ leave 

_ syscall 

_ farl6 


_ loadds 

_try 

_ fastcall 


_near 

_ unalignec 

IBM compilers compatible 



_ Cdecl 


_ Finally 

_ Segl6 

_ Except 


_ Leave 

_ Syscall 
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_Export _ Packed _ System 

_Farl6 _ Pascal _ Try 

_ Fastcall 

Open Watcom specific 

_builtin_ isfloat _ow_ imaginary_ unit_watcall 

Note that, since C is sensitive to the case of letters, changing one or more letters in a keyword to upper case 
will prevent the compiler from recognizing it as a keyword, thereby allowing it to be used as an identifier. 
However, this is not a recommended programming practice. 


3.3 Identifiers 


Identifiers are used as: 

• object or variable names, 

• function names, 

• labels, 

• structure, union or enumeration tags, 

• the name of a member of a structure or union, 

• enumeration constants, 

• macro names, 

• typedef names. 

An identifier is formed by a sequence of the following characters: 

• upper-case letters "A" through "Z", 

• lower-case letters "a" through "z", 

• the digits ”0" through "9", 

• the underscore 

The first character may not be a digit. 

An identifier cannot be a member of the list of keywords. 

Identifiers can consist of any number of characters, but the compiler is not required to consider more than 
31 characters as being significant, provided the identifier does not have external linkage (shared by more 
than one compiled module of the program). If the identifier is external, the compiler is not required to 
consider more than 6 characters as being significant. External identifiers may be case-sensitive. 

Of course, any particular compiler may choose to consider more characters as being significant, but a 
portable C program will strictly adhere to the above rules. (This restriction is likely to be relaxed in future 
versions of the ISO C standard and corresponding C compilers.) 

The Open Watcom C 16 and C 32 compilers do not restrict the number of significant characters for 
functions or objects with external or internal linkage. 

The linker provided with Open Watcom C 16 and C 32 restricts the number of significant characters 
in external identifiers to 40 characters, and by default, distinguishes between identifiers that differ 
only in the case of the letters. An option may be used to force the linker to ignore case differences. 
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Any external identifier that starts with the underscore character may be reserved by the compiler. 

Any other identifier that starts with two underscores, or an underscore and an upper-case letter may be 
reserved. Generally, a program should avoid creating identifiers that start with an underscore. 

3.4 Comments 

A comment is identified by / * followed by any characters and terminated by * / . Comments are 
recognized anywhere in a program, except inside a character constant or string. Once the / * is found, 
characters are examined only until the */ is found. This excludes nesting of comments. 

A comment is treated as a "white-space" character, meaning that it is like a space character. 

For example, the program fragment, 

/* Close all the files. 

*/ 

for( i = 0; i < fcount; i++ ) { /* loop through list */ 
fclose( flist[i] ); /* close the file */ 

} 

is equivalent to, 

for( i = 0; i < fcount; i++ ) { 

fclose( flist[i] ); 

} 

Comments are sometimes used to temporarily remove a section of code during testing or debugging of a 
program. For example, the second program fragment could be "commented out" as follows: 

/* 

for( i = 0; i < fcount; i++ ) { 

fclose ( flistfi] ); 

} 

*/ 

This technique will not work on the first fragment because it contains comments, and comments may not be 
nested. For these cases, the #if directive of the C preprocessor may be used. Refer to the chapter "The 
Preprocessor" for more details. 

The Open Watcom C 16 and C 32 compilers support an extension for comments. The symbol / / 
can be used at any point in a physical source line (except inside a character constant or string 
literal). Any characters from the //to the end of the line are treated as comment characters. The 
comment is terminated by the end of the line. There is no explicit symbol for terminating the 
comment. For example, the program fragment used at the beginning of this section can be 
rewritten as, 

// Close all the files. 

for( i = 0; i < fcount; i++ ) { // loop through list 

fclose( flist[i] ); // close the file 

} 

This form of comment can be used to "comment out" code without the difficulties encountered 
with / * . 
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4 Basic Types 


The following topics are discussed: 

• Declarations of Objects 

• Integer Types 

• Floating-Point Types 

• Enumerated Types 

• Arrays 

• Strings 

4.1 Declarations of Objects 

When a name is used in a program, the compiler needs to know what that name represents. A declaration 
describes to the compiler what a name is, including: 

• How much storage it occupies (objects) or how much storage is required for the value that is 
returned (functions), and how the value in that storage is to be interpreted. This is called the type. 
Examples include int, float and struct list. 

• Whether the name is visible only within the module being compiled, or throughout the program. 

This is called the linkage, and is part of the storage class. The keywords extern and static 
determine the linkage. 

• For object names, whether the object is created every time the function is called and destroyed every 
time the function returns. This is called the storage duration, and is part of the storage class. The 
keywords extern, static, auto and register determine the storage duration. 

The placement of the declaration within the program determines whether the declaration applies to all 
functions within the module, or just to the function within which the declaration appears. 

The definition of an object is similar to its declaration, except that the storage for the object is reserved. 
Whether the declaration of an object is also a definition depends upon the placement of the declaration and 
the attributes of the object. 


Declarations of Objects 


15 




Language Reference 


The usual form for defining (creating) an object is as follows: 

storage-class-specifier type-specifier declarator ; 

or 

storage-class-specifier type-specifier declarator = initializer; 

The storage-class-specifier is optional, and is thoroughly discussed in the chapter "Storage Classes". The 
type-specifier is also optional, and is thoroughly discussed in the next section and in the chapter "Advanced 
Types". At least one of the storage-class-specifier and type-specifier must be specified, and they may be 
specified in either order, although it is recommended that the storage-class-specifier always be placed first. 

The declarator is the name of the object being defined along with other information about its type. There 
may be several declarators, separated by commas. 

The initializer is discussed in the chapter "Initialization of Objects". 

The following are examples of declarations of objects, along with a brief description of what each one 
means. A more complete discussion of the terms used may be found in the relevant section. 

int x; 

Inside a function 

The object x is declared to be an integer, with automatic storage duration. Its value is available 
only within the function (or compound statement) in which it is defined. This is also a 
definition. 

Outside a function 

The object x is created and declared to be an integer with static storage duration. 
available within the module in which it is defined, and has external linkage so that 
module may refer to it by using the declaration, 

extern int x; 

This is also a definition. 

register void * memptr; 

Inside a function 

The object memptr is declared to be a pointer to void (no particular type of object), and is 
used frequently in the function. This is also a definition. 

Outside a function 

Not valid because of the register storage class, 
auto long int x, y; 

Inside a function 

The objects x and y are declared to be signed long integers with automatic storage duration. 
This is also a definition. 


Its value is 
any other 
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Outside a function 

Not valid because of the auto storage class, 
static int nums[10]; 

Inside a function 

The object nums is declared to be an array of 10 integers with static storage duration. Its 
value is only available within the function, and will be preserved between calls to the function. 
This is also a definition. 

Outside a function 

The object nums is declared to be an array of 10 integers with static storage duration. Its 
value is only available within the module. (The difference is the scope of the object nums.) 
This is also a definition. 

extern int x; 

Inside a function 

The object x is declared to be an integer with static storage duration. No other functions within 
the current module may refer to x unless they also declare it. The object is defined in another 
module, or elsewhere in this function or module. 

Outside a function 

The object x is declared to be an integer with static storage duration. Its value is available to 
all functions within the module. The object is defined in another module, or elsewhere in this 
module. 

The appendix "Examples of Declarations" contains many more examples of declarations of objects and 
functions. 


4.2 Name Scope 

An identifier may be referenced only within its scope. 

An identifier declared within a function or within a compound statement within a function has block scope, 
and may be referenced only in the block in which it is declared. The object’s scope includes any enclosed 
blocks and terminates at the } which terminates the enclosing block. 

An identifier declared within a function prototype (as a parameter to that function) has function prototype 
scope, and may not be referenced elsewhere. Its scope terminates at the ) which terminates the prototype. 

An identifier declared outside of any function or function prototype has file scope, and may be referenced 
anywhere within the module in which it is declared. If a function contains a declaration for the same 
identifier, the identifier with file scope is hidden within the function. Following the terminating } of the 
function, the identifier with file scope becomes visible again. 

A label, which must appear within a function, has function scope. 


Name Scope 
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4.3 Type Specifiers 

Every object has a type associated with it. Functions may be defined to return a value, and that value also 
has a type. The type describes the interpretation of a value of that type, such as whether it is signed or 
unsigned, a pointer, etc. The type also describes the amount of storage required. Together, the amount of 
storage and the interpretation of stored values describes the range of values that may be stored in that type. 

There are a number of different types defined by the C language. They provide a great deal of power in 
selecting methods for storing and moving data, and also contribute to the readability of the program. 

There are a number of "basic types", those which will appear in virtually every program. More 
sophisticated types provide methods to describe data structures, and are discussed in the chapter "Advanced 
Types". 

A type specifier is one or more of: 

char 

double 

float 

int 

long 

short 

signed 

unsigned 

void 

enumeration 

structure 

union 

typedef name 

and may also include the following type qualifiers : 

const 

volatile 


The Open Watcom compilers also provide the following extended type qualifiers'. 

_based 

_ fortran 

_ Segl6 

_ Cdecl 

_huge 

_segment 

_ cdecl 

_ inline 

_segname 

_ declspec 

_int 64 

_self 

_ Export 

_ interrupt 

_stdcall 

_ export 

_ loadds 

_ Syscall 

_far 

_near 

_ syscall 

_Farl6 

_ Packed 

_ System 

_farl 6 

_ Pascal 

_ unaligned 

_Fastcall 

_pascal 

_ watcall 

_ fastcall 

_saveregs 


For the extended type qualifiers. 

see the appendix "Compiler Keywords". 


Various combinations of these keywords may be used when declaring an object. Refer to the section on the 
type being defined. 
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The main types are char, int, float and double. The keywords short, long, signed, 
unsigned, const and volatile modify these types. 

4.4 Integer Types 

The most commonly used type is the integer. Integers are used for storing most numbers that do not require 
a decimal point, such as counters, sizes and indices into arrays. The range of integers is limited by the 
underlying machine architecture and is usually determined by the range of values that can be handled by the 
most convenient storage type of the hardware. Most 16-bit machines can handle integers in the range 
-32768 to 32767. Larger machines typically handle integers in the range -2147483648 to 
2147483647. 

The general integer type includes a selection of types, specifying whether or not the value is to be 
considered as signed (negative and positive values) or unsigned (non-negative values), character (holds one 
character of the character set), short (small range), long (large range) or long long (very large range). 

Just specifying the type int indicates that the amount of storage should correspond to the most convenient 
storage type of the hardware. The value is treated as being a signed quantity. According to the C language 
standard, the minimum range for int is -327 67 to 327 67, although a compiler may provide a greater 
range. 

With Open Watcom C 16 , int has a range of -327 68 to 327 67. 

With Open Watcom C 32 , int has a range of-2147483648 to 2147483647. 


Specifying the type char indicates that the amount of storage is large enough to store any member of the 
execution character set. If a member of the required source character set (see "Character Sets") is stored in 
an object of type char, then the value is guaranteed to be positive. Whether or not other characters are 
positive is implementation-defined. (In other words, whether char is signed or unsigned is 
implementation-defined. If it is necessary for the object of type char to be signed or unsigned, then the 
object should be declared explicitly, as described below.) 

The Open Watcom C 16 and C 32 compilers define char to be unsigned, allowing objects of 
that type to store values in the range 0 to 2 55. A command line switch may be specified to cause 
char to be treated as signed. This switch should only be used when porting a C program from 
a system where char is signed. 

The int keyword may be specified with the keywords short or long. These keywords provide 
additional information about the range of values to be stored in an object of this type. According to the C 
language standard, a signed short integer has a minimum range of -32767 to 32767. A signed long 
integer has a minimum range of -2147483647 to 2147483647. A signed long long integer has a 
minimum range of -9223372 03 6854 7 75 807 to 9223372036854775807. 

With Open Watcom C 16 and C 32 , short int hasarangeof -32768 to 32767, while long 
int has a range of-2147483648 to 2147483647, and long long int has a range of 
-9223372036854775808 to 9223372 036854 7 75807. 

The char and int types may be specified with the keywords signed or unsigned. These keywords 
explicitly indicate whether the type represents a signed or unsigned (non-negative) quantity. 
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The keyword int may be omitted from the declaration if one (or more) of the keywords signed, 
unsigned, short or long is specified. In other words, short is equivalent to signed short int 
and unsigned long is equivalent to unsigned long int. 

The appendix "Macros for Numerical Limits" discusses a set of macro definitions describing the range and 
other characteristics of the various numeric types. The macros from the header <limits . h>, which 
describe the integer types, are discussed. 


The following table describes all of the various integer types and their ranges as implemented by 
the Open Watcom C 16 and C 32 compilers. Note that the table is in order of increasing storage 
size. 



Minimum 

Maximum 

Type 

Value 

Value 

signed char 

-128 

127 

unsigned char 

0 

255 

char 

0 

255 

short int 

-32768 

32767 

unsigned short int 

0 

65535 

int (C 16 ) 

-32768 

32767 

int (C 32 ) 

-2147483648 

2147483647 

unsigned int (C 16 ) 

0 

65535 

unsigned int (C 32 ) 

0 

4294967295 

long int 

-2147483648 

2147483647 

unsigned long int 

0 

18446744073709551615 

long long int 

-92233720368547758078 

9223372036854775807 

unsigned long long 

0 

18446744073709551615 


With Open Watcom C 16 , an object of type int has the same range as an object of type short 
int. 

With Open Watcom C 32 , an object of type int has the same range as an object of type long 
int. 
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The following are some examples of declarations of objects with integer type: 


char a; 

unsigned char b; 

signed char c; 

short d; 

unsigned short int e; 
int f,g; 

signed h; 

unsigned int i; 

long j; 

unsigned long k 

signed long 1; 

unsigned long int m; 
signed long long n; 
long long o; 

unsigned long long p; 
long long int q; 


4.5 Floating-Point Types 

A floating-point number is a number which may contain a decimal point and digits following the decimal 
point. The range of floating-point numbers is usually considerably larger than that of integers, but the 
efficiency of integers is usually much greater. Integers are always exact quantities, whereas floating-point 
numbers sometimes suffer from round-off error and loss of precision. 

On some computers, floating-point arithmetic is emulated (simulated) by software, rather than hardware. 
Software emulation can greatly reduce the speed of a program. While this should not affect the portability 
of a program, a prudent programmer limits the use of floating-point numbers. 

There are three floating-point number types, float, double, and long double. 

The appendix "Macros for Numerical Limits" discusses a set of macro definitions describing the range and 
other characteristics of the various numeric types. The macros from the header <f loat. h>, which 
describe the floating-point types, are discussed. 


The following table gives the ranges available on the 80x86/80x87 using the Open Watcom 
C 16 and C 32 compiler. The floating-point format is the IEEE Standard for Binary Floating-Point 
Arithmetic (ANSI/IEEE Std 754-1985). 


Type 

Smallest 

Absolute 

Value 

Largest 

Absolute 

Value 

Digits 

Of 

Accuracy 

80x87 

Type 

Name 

float 

1. IE-38 

3.4E+38 

6 

short real 

double 

2.2E-308 

1.7E+308 

15 

long real 

long double 

2.2E-308 

1.7E+308 

15 

long real 
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By default, the Open Watcom C 16 and C 32 compilers emulate floating-point arithmetic. If the 
8087 or 80x87 Numeric Processor Extension (numeric coprocessor, math chip) will be present at 
execution time, the compiler can be forced to generate floating-point instructions for the 
coprocessor by specifying a command line switch, as described in the User’s Guide. Other than an 
improvement in execution speed, the final result should be the same as if the processor is not 
present. 


The following are some examples of declarations of objects with floating-point type: 

float a; 

double b; 

long double c; 

4.6 Enumerated Types 

Sometimes it is desirable to have a list of constant values representing different things, and the exact values 
are not relevant. They may need to be unique or may have duplicates. For example, a set of actions, colors 
or keys might be represented in such a list. An enumerated type allows the creation of a list of items. 

An enumerated type is a set of identifiers that correspond to constants of type int. These identifiers are 
called enumeration constants. The first identifier in the set has the value 0, and subsequent identifiers are 
given the previous value plus one. Wherever a constant of type int is allowed, an enumeration constant 
may be specified. 

The following type specifier defines the set of actions available in a simple memo program: 

enum actions { DISPLAY, EDIT, PURGE }; 

The enumeration constant DISPLAY is equivalent to the integer constant 0, and EDIT and PURGE are 
equivalent to 1 and 2 respectively. 

An enumerated type may be given an optional tag (name) with which it may be identified elsewhere in the 
program. In the example above, the tag of the enumerated type is actions, which becomes a new type. 
If no tag is given, then only those objects listed following the definition of the type may have the 
enumerated type. 

The name space for enumerated type tags is different from that of object names, labels and member names 
of structures and unions, so a tag may be the same identifier as one of these other kinds. An enumerated 
type tag may not be the same as the tag of a structure or union, or another enumerated type. 

Enumeration constants may be given a specific value by specifying ’=’ followed by the value. For 
example, 

enum colors { RED = 1, BLUE = 2, GREEN = 4 }; 


22 


Enumerated Types 





Basic Types 


creates the constants RED, BLUE and GREEN with values 1, 2 and 4 respectively. 

enum fruits { GRAPE, ORANGE = 6, APPLE, PLUM }; 
creates constants with values 0, 6, 7 and 8. 

enum fruits { GRAPE, PLUM, RAISIN = GRAPE, PRUNE = PLUM }; 
makes GRAPE and RAISIN equal to 0, and PLUM and PRUNE equal to 1. 

The formal specification of an enumerated type is as follows: 

enum identifier 

or 

enum { enumeration-constant-list } 

or 

enum identifier { enumeration-constant-list } 

enumeration-constant-list: 

enumeration-constant 

or 

enumeration-constant, enumeration-constant-list 


en ume ration-constan t: 
identifier 

or 

identifier = constant-expression 


The type of an enumeration is implementation-defined, although it must be compatible with an integer type. 
Many compilers will use int. 


From the following table, the Open Watcom C 16 and Open Watcom C 32 compilers will choose 
the smallest type that has sufficient range to represent all of the constants of a particular 
enumeration: 


Type 

Smallest Value 

Largest Value 

signed char 
unsigned char 
signed short 
unsigned short 
signed long 
unsigned long 
signed long long 
unsigned long long 

-128 

0 

-32768 

0 

-2147483648 

0 

-9223372036854775808 

0 

127 

255 

32767 

65535 

2147483647 

4294967295 

9223372036854775807 

18446744073709551615 


A command-line option may be used to force all enumerations to int. 


To create an object with enumerated type, one of two forms may be used. The first form is to create the 
type as shown above, and then to declare an object as follows: 
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enum tag object-name ; 

For example, the declaration, 
enum fruits fruit; 

declares the object fruit to be the enumerated type fruits . 

The second form is to list the identifiers of the objects following the closing brace of the enumeration 
declaration. For example, 

enum fruits { GRAPE, ORANGE, APPLE, PLUM } fruit; 

Provided no other objects with the same enumeration are going to be declared, the enumerated type tag 
fruits is not required. The declaration could be specified as, 

enum { GRAPE, ORANGE, APPLE, PLUM } fruit; 

An identifier that is an enumeration constant may only appear in one enumeration type. For example, the 
constant ORANGE may not be included in another enumeration, because the compiler would then have two 
values for ORANGE. 


4.7 Arrays 

An array is a collection of objects which are all of the same type. All elements (objects) in the array are 
stored in contiguous (adjacent) memory. 

References to array elements are usually made through indexing into the array. To facilitate this, the 
elements of the array are numbered starting at zero. Flence an array declared with n elements is indexed 
using indices between 0 and n-1. 

An array may either be given an explicit size (using a constant expression) or its size may be determined by 
the number of values used to initialize it. Also, it is possible to declare an array without any size 
information, in the following cases: 

• a parameter to a function is declared as "array of type" (in which case the compiler alters the type to 
be "pointer to type"), 

• an array object has external linkage (extern) and the definition which creates the array is given 
elsewhere, 

• the array is fully declared later in the same module. 

An array of undetermined size is an incomplete type. 
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An array declaration is of the following form: 

type identifier [ constant-expression ] ; 

or 

type identifier [ ] = { initializer-list } ; 

or 

type identifier [ constant-expression ] = { initializer-list }; 

or 

type identifier [ ] ; 

where type is the type of each element of the array, identifier is the name of the array, constant-expression 
is an expression that evaluates to a positive integer defining the number of elements in the array, and 
initializer-list is a list of values (of type type) to be assigned to successive elements of the array. 

For example, 

int values[10]; 

declares values to be an array of 10 integers, with indices from 0 to 9. The expression values [ 5 ] 
refers to the sixth integer in the array. 

char text[] = { "some stuff" }; 

declares text to be an array of 11 characters, each containing successive letters from "some stuff" . 
The value of text [10] is ' \ 0' (the null character), representing the terminating character in the string 
(see Strings). 

extern NODES nodelist[]; 

declares nodelist to be an array of NODES (defined elsewhere), and the array is of unknown size. In 
another source file or later in the current file, there must be a corresponding declaration of nodelist 
which defines how big the array actually is. 

It is possible to declare multi-dimensional arrays by including more than one set of dimensions. For 
example, 

int tbl[2] [3] ; 

defines a 2-row by 3-column array of integers. In fact, it defines an array of 2 arrays of 3 integers. The 
values are stored in memory in the following order: 


tbl 

[0] 

[0] 

tbl 

[0] 

[1] 

tbl 

[0] 

[2] 

tbl 

[1] 

[0] 

tbl 

[1] 

[1] 

tbl 

[1] 

[2] 


The rows of the table are stored together. This form of storing an array is called row-major order. The 
expression tbl [ 1 ] [ 2 ] refers to the element in the last row and last column of the array. 

In an expression, if an array is named without specifying any indices, the value of the array name is the 
address of its first element. In the example. 
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int array[10]; 

int * aptr; 

aptr = array; 

the assignment to aptr is equivalent to, 
aptr = &array[0]; 

Since multi-dimensional arrays are just arrays of arrays, it follows that omission of some, but not all, 
dimensions is equivalent to taking the address of the first element of the sub-array. In the example, 

int array [9] [5] [2]; 

int * aptr; 

aptr = array[7]; 

the assignment to aptr is equivalent to, 

aptr = &array[7] [0] [0] ; 

Note that no checking of indices is performed at execution time. An invalid index (less than zero or greater 
than the highest index) will refer to memory as if the array was extended to accommodate the index. 

4.8 Strings 

A string is a special form of the type "array of characters", specifically an array of characters terminated by 
a null character. The null character is a character with the value zero, represented as \ 0 within a string, or 
as the character constant ' \ 0'. Because string processing is such a common task in programming, C 
provides a set of library functions for handling strings. 

A string is represented by the address of the first character in the string. The length of a string is the 
number of characters up to, but not including, the null character. 

An array can be initialized to be a string using the following form: 

type identifier [] = { "string value " }; 

(The braces are optional.) For example, 

char ident[] = "This is my program"; 

declares ident to be an array of 19 characters, the last of which has the value zero. The string has 18 
characters plus the null character. 

In the above example, ident is an array whose value is a string. However, the quote-enclosed value used 
to initialize the array is called a string literal. String literals are described in the "Constants" chapter. 
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A string may be used anywhere in a program where a "pointer to char" may be used. For example, if the 
declaration, 

char * ident; 

was encountered, the statement, 

ident = "This is my program"; 

would set the value of ident to be the address of the string "This is my program". 


Strings 
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A constant is a value which is fixed at compilation time and is often just a number, character or string. 

Every constant has a type which is determined by its form and value. For example, the value 1 may have 
the type signed int, while the value 400000 may have the type signed long. In many cases, the 
type of the constant does not matter. If, for example, the value 1 is assigned to an object of type long 
int, then the value 1 will be converted to a long integer before the assignment takes place. 

5.11nteger Constants 

An integer constant begins with a digit and contains no fractional or exponent part. A prefix may be 
included which defines whether the constant is in octal, decimal or hexadecimal format. 

A constant may be suffixed by u or U indicating an unsigned int, or by 1 or L indicating a long 
int, or by both indicating an unsigned long int. 

If a constant does not start with a zero and contains a sequence of digits, then it is interpreted as a decimal 
(base 10) constant. These are decimal constants: 

7 

762 

98765L 

If the constant starts with Ox or OX followed by the digits from 0 through 9 and the letters a (or A) through 
f (or F), then the constant is interpreted as a hexadecimal (base 16) constant. The letters A through F 
represent the values 10 through 15 respectively. These are hexadecimal constants: 

0X07FFF 

0xl2345678L 

OxFABE 

If a constant starts with a zero, then it is an octal constant and may contain only the digits 0 through 7. 

These are octal constants: 

017 

0735643L 

0 

Note that the constant 0 is actually an octal constant, but is zero in decimal, octal and hexadecimal. 

The following table describes what type the compiler will give to a constant. The left column indicates 
what base (decimal, octal or hexadecimal) is used and what suffixes (U or L) are present. The right column 
indicates the types that may be given to such a constant. The type of an integer constant is the first type 
from the table in which its value can be accurately represented. 
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Constant 

Type 

unsuffixed decimal 

int, long, unsigned long 

unsuffixed octal 

int, unsigned int, long, unsigned long 

unsuffixed hexadecimal 

int, unsigned int, long, unsigned long 

suffix U only 

unsigned int, unsigned long 

suffix L only 

long, unsigned long 

suffixes U and L 

unsigned long 

suffix LL only 

long long, unsigned long long 

suffixes U and LL 

unsigned long long 


The following table illustrates a number of constants and their interpretation and type: 


Constant 

Decimal 

Value 

Hexa 

-decimal 

Value 

Open Watcom C 16 

Type 

Open Watcom C 32 
Type 

33 

33 

21 

signed int 

signed int 

033 

27 

IB 

signed int 

signed int 

0x33 

51 

33 

signed int 

signed int 

33333 

33333 

8235 

signed long 

signed int 

033333 

14043 

36DB 

signed int 

signed int 

OxAOOO 

40960 

A0 00 

unsigned int 

signed int 

0x33333 

209715 

33333 

signed long 

signed int 

0x80000000 

2147483648 

80000000 

unsigned long 

unsigned int 

2147483648 

2147483648 

80000000 

unsigned long 

unsigned int 

4294967295 

4294967295 

FFFFFFFF 

unsigned long 

unsigned int 


5.2 Floating-Point Constants 

A floating-point constant may be distinguished by the presence of either a period, an e or E, or both. It 
consists of a value part (mantissa) optionally followed by an exponent. The mantissa may include a 
sequence of digits representing a whole number, followed by a period, followed by a sequence of digits 
representing a fractional part. The exponent must start with an e or E followed by an optional sign (+ or 
-), and a digit sequence representing (with the sign) the power of 10 by which the mantissa should be 
multiplied. Optionally, the suffix f or F may be added indicating the constant has type float, or the 
suffix 1 or L indicating the constant has type long double. If no suffix is present then the constant has 
type double. 

In the mantissa, either the whole number part or the fractional part must be present. If only the whole 
number part is present and no period is included then the exponent part must be present. 
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The following table illustrates a number of floating-point constants and their type: 


Constant 

Value 

Type 

3.14159265 

11E24 

. 5L 

7.234E-22F 

0 . 

3.14159265E0 

1.1E25 

5E-1 

7.234E-22 

0E0 

double 

double 
long double 
float 

double 


5.3 Character Constants 


A character constant is usually one character enclosed in single-quotes, and indicates a constant whose 
value is the representation of the character in the execution character set. A character constant has type 
int. 

The character enclosed in quotes may be any character in the source character set. Certain characters in the 
character set may not be directly representable, since they may be assigned other meanings. These 
characters can be entered using the following escape sequences: 


Character 

Character Name 

Escape Sequence 

T 

single quote 

V 

II 

double quote 

" or \" 

? 

question mark 

? or \? 

\ 

backslash 

V 


octal value 

\octal digits (max 3) 


hexadecimal value 

\xhexadecimal digits 


For example. 


'a' 

/* 

' V' 

/* 

' ?' 

/* 

' \?' 

/* 

'\V 

/* 


the letter a */ 
a single quote * 
a question mark 
a question mark 
a backslash */ 


/ 

*/ 

*/ 


are all simple character constants. 


The following are some character constants containing octal escape sequences, made up of a \ followed by 
one, two or three octal digits (the digits 0 through 7): 


' \ 0 ' 

'\377' 

'\ 100 ' 

If a character constant containing an octal value is found, but a non-octal character is also present, or if a 
fourth octal digit is found, it is not part of the octal character already specified, and constitutes a separate 
character. For example. 
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'\ 1000 ' 

'\109' 

the first constant is a two-character constant, consisting of the characters ' \ 10 0' and ' 0' (because an 
octal value consists of at most three octal digits). The second constant is also a two-character constant, 
consisting of the characters ' \10' and ' 9' (because 9 is not an octal digit). 

If more than one octal value is to be specified in a character constant, then each octal value must be 
specified starting with \. 

The meaning of character constants with more than one character is implementation-defined. 

The following are some character constants containing hexadecimal escape sequences, made up of a \x 
followed by one or more hexadecimal digits (the digits 0 through 9, and the letters a through f and A 
through F). (The values of these character constants are the same as the first examples of octal values 
presented above.) 

' \x0' 

'\xFF' 

'\x40' 

If a character constant containing a hexadecimal value is found, but a non-hexadecimal character is also 
present, it is not part of the hexadecimal character already specified, and constitutes a separate character. 

For example, 

' \xFAx' 

' \xFx' 

the first constant is a two-character constant, consisting of the characters ' \xFA' and ' x' (because x is 
not a hexadecimal digit). The second constant is also a two-character constant, consisting of the characters 
' \xF' and ' x'. 

If more hexadecimal digits are found than are required to specify one character, the behavior is 
implementation-defined. Specifically, any sequence of hexadecimal characters in a hexadecimal value in a 
character constant is used to specify the value of one character. If more than one hexadecimal value is to be 
specified in a character constant, then each hexadecimal value must be specified starting with \x. 

The meaning of character constants with more than one character is implementation-defined. 

In addition to the above escape sequences, the following escape sequences may be used to represent 
non-graphic characters: 


Escape 

Sequence 

Meaning 

\a 

Causes an audible or visual alert 

\b 

Back up one character 

\f 

Move to the start of the next page 

\n 

Move to the start of the next line 

\r 

Move to the start of the current line 

\t 

Move to the next horizontal tab 

\v 

Move to the next vertical tab 
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The following trigraph sequences may be used to represent characters not available on all terminals or 
systems: 


Character 

Trigraph Sequence 

[ 

?? ( 

] 

? ? ) 

{ 

? ?< 

} 

? ?> 


? ? ! 

# 

? ?= 

\ 

? ?/ 

A 

? ?' 

~ 

? ?- 


The Open Watcom C 16 and C 32 compilers also allow character constants with more than one 
character. These may be used to initialize larger types, such as int. For example, the program 
fragment: 

int code; 
code = ' ab' ; 

assigns the constant value ' ab' to the integer object code. The letter b is placed in the lowest 
order (least significant) portion of the integer value and the letter a is placed in the next highest 
portion. 

Up to four characters may be placed in a character constant. Successive characters, starting from 
the right-most character in the constant, are placed in successively higher order (more significant) 
bytes of the result. 

Note that a character constant such as 'a' is different from the corresponding string literal "a". The 
former is of type int and has the value of the letter a in the execution character set. The latter is of type 
"pointer to char" and its value is the address of the first character (a) of the string literal. 

5.3.1 Wide Character Constants 

If the value of a character constant is to be a multibyte character from an extended character set, then a wide 
character constant should be specified. Its form is similar to normal character constants, except that the 
constant is preceded by the character L. 

The type of a wide character constant is wchar_ t, which is one of the integral types, and is described in 
the header <stddef. h>. 


With Open Watcom C 16 and C 32 , wchar_ t is defined asunsigned short. 

For example, the constant L' a' is a wide character constant containing the letter a from the source 
character set, and has type wchar_ t. In contrast, the constant' a' is a character constant containing the 
letter a, and has type int. 

How the multibyte character maps onto the wide character value is defined by the mbtowc library 
function. 
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As shown above, a wide character constant may also contain a single byte character, since an extended 
character set contains the single byte characters. The single byte character is mapped onto the 
corresponding wide character code. 

5.4 String Literals 

A sequence of zero or more characters enclosed within double-quotes is a string literal. 

Most of the same rules for creating character constants also apply to creating string literals. However, the 
single-quote may be entered directly or as the \' escape sequence. The double-quote must be entered as 
the \ " escape sequence. 

The value of a string literal is the sequence of characters within the quotes, plus a null character at the end. 
The type of a string literal is "array of char". 

The following are examples of string literals: 

"Hello there" 

"V'Quotes inside stringV" 

"G'day" 

If two or more string literals are adjacent, the compiler will join them together into one string literal. The 
pair of string literals, 

"Hello" "there" 

would be joined by the compiler to be, 

"Hellothere" 

and is an array of 11 characters, including the single terminating null character. 

The joining of adjacent string literals occurs after the replacement of escape sequences. In the examples, 

"\xFAB\xFA" "B" 

"\ 012 \ 01 " " 2 " 

the first string, after joining, consists of three characters, with the values ' \xFAB', ' \xFA' and ' B'. 
The second string, after joining, also consists of three characters, with the values ' \ 012', ' \ 01' and 

' 2 '. 


A program should not attempt to modify a string literal, as this behavior is undefined. On computers where 
memory can be protected, it is likely that string literals will be placed where the program cannot modify 
them. An attempt to modify them will cause the program to fail. On other computers without such 
protection, the literal can be modified, but this is generally considered to be a poor programming practice. 
(Constants should be constant!) 

A string literal normally is a string. It is not a string if one of the characters within double-quotes is the null 
character (\ 0). If such a string literal is treated as a string, then only those characters before the first null 
character will be considered part of the string. The characters following the first null character will be 
ignored. 
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If a source file uses the same string literal in several places, the compiler may combine them so that only 
one instance of the string exists and each reference refers to that string. In other words, the addresses of 
each of the string literals would be the same. However, no program should rely on this since other 
compilers may make each string a separate instance. 

The Open Watcom C 16 and C 32 compilers combine several instances of the same string literal in 
the same module into a single string literal, provided that they occur in declarations of constant 
objects or in statements other than declarations (eg. assignment). 


If the program requires that several string literals be the same instance, then an object should be declared as 
an array of char with its value initialized to the string. 

5.4.1 Wide String Literals 

If any of the characters in a string literal are multibyte characters from an extended character set, then a 
wide string literal should be specified. Its form is similar to normal string literals, except that the string is 
preceded by the character L. 

The type of a wide string literal is "array of wchar_ t". wchar_ t is one of the integral types, and is 
described in the header <stddef . h>. 


With Open Watcom C 16 and C 32 , wchar_ t is defined asunsigned short. 


For example, the string literal L " ab " is a wide string literal containing the letters a and b. Its type is 
"array [3] of wchar_ t", and the values of its elements areL' a', L' b' and ' \ 0'. In contrast, the string 
literal "ab" has type "array [3] of char", and the values of its elements are ' a', ' b' and ' \0'. 

How the multibyte characters map onto wide character values is defined by the mbtowc library function. 

As shown above, a wide string literal may also contain single byte characters, since the extended character 
set contains the single byte characters. The single byte characters are mapped onto the corresponding wide 
character codes. 

Adjacent wide string literals will be concatenated by the compiler and a null character appended to the end. 
If a string literal and a wide string literal are adjacent, the behavior when the compiler attempts to 
concatentate them is undefined. 
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6 Type Conversion 


Whenever two operands are involved in an operation, some kind of conversion of one or both of the 
operands may take place. For example, a short int and a long int cannot be directly added. 
Instead, the short int must first be converted to a long int, then the two values can be added. 

Fortunately, C provides most conversions as implicit operations. Simply by indicating that the two values 
are to be added, the C compiler will check their types and generate the appropriate conversions. Sometimes 
it is necessary, however, to be aware of exactly how C will convert the operands. 

Conversion of operands always attempts to preserve the value of the operand. Where preservation of the 
value is not possible, the compiler will sign-extend signed quantities and discard the high bits of quantities 
being converted to smaller types. 

The rules of type conversions are fully discussed in the following sections. 

6.1 Integral Promotion 

Rule: A char, short int or int bit-field in either of their signed or unsigned forms, or an 

object that has an enumerated type, is always converted to an int. If the type int cannot 
contain the entire range of the object being converted, then the object will be converted to 
an unsigned int. 

A signed or unsigned char will be converted to a signed int without changing the value. 

With Open Watcom C 16 , a short int has the same range as int, therefore a signed 
short int is converted to a signed int, and an unsigned short int is converted to 
an unsigned int, without changing the value. 

With Open Watcom C 32 , a signed or unsigned short int is converted to an int without 
changing the value. 


These promotions are called the integral promotions. 

6.2 Signed and Unsigned Integer Conversion 

Rule: If an unsigned integer is converted to an integer type of any size, then, if the value can be 

represented in the new type, the value remains unchanged. 

If an unsigned integer is converted to a longer type (type with greater range), then the value will not 
change. If it is converted to a type with a smaller range, then provided the value can be represented in the 
smaller range, the value will remain unchanged. If the value cannot be represented, then if the result type is 
signed, the result is implementation-defined. If the result type is unsigned, the result is the integer 
modulo (1+the largest unsigned number that can be stored in the shorter type). 
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With Open Watcom C 16 , unsigned integers are promoted to longer types by extending the 
high-order bits with zeros. They are demoted to shorter types by discarding the high-order portion 
of the larger type. 

Consider the following examples of 32-bit quantities (unsigned long int) being converted to 16-bit 
quantities (signed short int or unsigned short int): 


long 

32-bit 

representation 

16-bit 

representation 

signed 

short 

unsigned 

short 

65538 

100000 

0x00010002 

0x000186A0 

0x0002 

0x8 6A0 

2 

-31072 

2 

34464 


Rule: When a signed integer is converted to an unsigned integer of equal or greater length, if the 

value is non-negative, the value will be unchanged. 

A non-negative value stored in a signed integer may be converted to an equal or larger integer type without 
affecting the value. A negative value is first converted to the signed type of the same length as the result, 
then (1+the largest unsigned number that can be stored in the result type) is added to the value to convert it 
to the unsigned type. 

With Open Watcom C 16 , signed integers are promoted to longer types by sign-extending the value 
(the high bit of the shorter type is propogated throughout the high bits of the longer type). When 
the longer type is unsigned, the sign-extended bit-pattern is then treated as an unsigned value. 


Consider the following examples of 16-bit signed quantities (signed short int) being converted to 
32-bit quantities (signed long int and unsigned long int): 


signed 

short 

16-bit 

represention 

32-bit 

representation 

signed 

long 

unsigned 

long 

-2 

32766 

OxFFFE 

0x7FFE 

OxFFFFFFFE 

0x00007FFE 

-2 

32766 

4294967294 

32766 


Rule: When a signed integer is converted to a longer signed integer, the value will not change. 

Rule: When a signed integer is converted to a shorter type, the result is implementation-defined. 

With Open Watcom C 16 , signed integers are converted to a shorter type by preserving the 
low-order (least significant) portion of the larger type. 
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6.3 Floating-Point to Integer Conversion 

Rule: When a floating-point type is converted to integer, the fractional part is discarded. If the 

value of the integer part cannot be represented in the integer type, then the result is 
undefined. 

Hence, it is valid only to convert a floating-point type to integer within the range of the integer type being 
converted to. Refer to the section "Integer Types" for details on the range of integers. 

6.4 Integer to Floating-Point Conversion 

Rule: When the value of an integer type is converted to a floating-point type, and the integer 

value cannot be represented exactly in the floating-point type, the value will be rounded 
either up or down. 

Rounding of floating-point numbers is implementation-defined. The technique being used by the compiler 
may be determined from the macro FLT_ ROUNDS found in the header<f loat. h>. The following table 
describes the meaning of the various values: 


FLT_ ROUNDS 

Technique 

-1 

indeterminable 

0 

toward zero 

1 

to nearest number 

2 

toward positive infinity 

3 

toward negative infinity 


The Open Watcom C 16 and C 32 compilers will round to the nearest number. (The value of 
FLT_ ROUNDS is 1.) 


Rule: When a floating-point value is converted to a larger floating-point type (float to 

double, float to long double, or double to long double), the value remains 
unchanged. 

Rule: When any floating-point type is demoted to a floating-point type with a smaller range, then 

the result will be undefined if the value lies outside the range of the smaller type. If the 
value lies inside the range, but cannot be represented exactly, then rounding will occur in 
an implementation-defined manner. 

The Open Watcom C 16 and C 32 compilers round to the nearest number. (The value of 
FLT_ ROUNDS is 1.) 


Integer to Floating-Point Conversion 
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6.5 Arithmetic Conversion 


Whenever two values are used with a binary operator that expects arithmetic types (integer or 
floating-point), conversions may take place implicitly. Most binary operators work on two values of the 
same type. If the two values have different types, then the type with the smaller range is always promoted 
to the type with the greater range. Conceptually, each type is found in the table below and the type found 
lower in the table is converted to the type found higher in the table. 

long double 

double 

float 

unsigned long 
long 

unsigned int 
int 

Note that any types smaller than int have integral promotions performed on them to promote them to 
int. 

The following table illustrates the result type of performing an addition on combinations of various types: 


Operation 

Result Type 

signed char + signed char 

signed int 

unsigned char + signed int 

signed int 

signed int + signed int 

signed int 

signed int + unsigned int 

unsigned int 

unsigned int + signed long 

signed long 

signed int + unsigned long 

unsigned long 

signed char + float 

float 

signed long + double 

double 

float + double 

double 

float + long double 

long double 


6.6 Default Argument Promotion 

When a call is made to a function, the C compiler checks to see if the function has been defined already, or 
if a prototype for that function has been found. If so, then the arguments to the function are converted to 
the specified types. If neither is true, then the arguments to the function are promoted as follows: 

• all integer types have the integral promotions performed on them, and, 

• all arguments of type float are promoted to double. 

If the definition of the function does not have parameters with types that match the promoted types, the 
behavior is undefined. 
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The following topics are discussed: 

• Structures 

• Unions 

• Pointers 

• Void 

• The const and volatile Declarations 


7 .1 Structures 


A structure is a type composed of a sequential group of members of various types. Like other types, a 
structure is a model describing storage requirements and interpretations, and does not reserve any storage. 
Storage is reserved when an object is declared to be an instance of the structure. 

Each of the members of a structure must have a name, with the exception of bit-fields. 

With Open Watcom C 16 and C 32 , a structure member may be unnamed if the member is a 
structure or union. 


A structure may not contain a member with an incomplete type. In particular, it may not contain a member 
with a type of the structure being defined (otherwise the structure would have indeterminate size), although 
it may contain a pointer to it. 

The structure may be given an optional tag with which the structure may be referenced elsewhere in the 
program. If no tag is given, then only those objects listed following the definition of the structure may have 
the structure type. 

The name space for structure tags is different from that of object names, labels and member names, so a tag 
may be the same identifier as one of these other kinds. A structure tag may not be the same as the tag of a 
union or enumerated type, or another structure. 

Each structure has its own name space, so an identifier may be used as a member name in more than one 
structure. An identifier that is an object name, structure tag, union tag, union member name, enumeration 
tag or label may also be used as a member name without ambiguity. 

Structures help to organize program data by collecting several related objects into one object. They are also 
used for linked lists, trees and for describing externally-defined regions of data that the application must 
access. 
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The following structure might describe a token identified by parsing a typed command: 

struct tokendef { 
int length; 

int type; 

char text[80]; 

} ; 


This defines a structure containing three members, an integer containing the token length, another integer 
containing some encoding of the token type, and the third an array of 80 characters containing the text of 
the token. The tag of the structure is tokendef. 

The above definition does not actually create an object containing the structure. Creation of an instance of 
the structure requires a list of identifiers following the structure definition, or to use struct tokendef 
in place of a type for declaring an object. For example, 

struct tokendef { 
int length; 

int type; 

char text[80]; 

} token; 

is equivalent to, 

struct tokendef { 
int length; 

int type; 

char text[80]; 

} ; 


struct tokendef token; 

Both create the object token as an instance of the structure tokendef. The type of token is struct 
tokendef. 

References to a member of a structure are made using the dot operator (.). The first operand of the . 
operator is the object containing the structure. The second operand is the name of the member. For 
example, token . length refers to the length member of the tokendef structure contained in 
token. 

If tokenptr is declared as, 

struct tokendef * tokenptr; 

(tokenptr is a pointer to a tokendef structure), then, 

(*tokenptr).length 
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refers to the length member of the tokendef structure that tokenptr points to. Alternatively, to 
refer to a member of a structure, the arrow operator (->) is used: 

tokenptr->length 

is equivalent to, 

(*tokenptr).length 


If a structure contains an unnamed member which is a structure or union, then the members of the 
inner structure or union are referenced as if they were members of the outer structure. For 
example, 

struct outer { 

struct inner { 

int a, b; 

} ; 

int c; 

} X; 

The members of X are referenced as X. a, X. b and X. c. 

Each member of a structure is at a higher address than the previous member. Alignment of members may 
cause (unnamed) gaps between members, and an unnamed area at the end of the structure. 

The Open Watcom C 16 and C 32 compilers provide a command-line switch and a #pragma to 
control the alignment of members of structures. See the User’s Guide for details. 

In addition, the _ Packed keyword is provided, and if specified before thestruct keyword, will 
force the structure to be packed (no alignment, no gaps) regardless of the setting of the 
command-line switch or the #pragma controlling the alignment of members. 


A pointer to an object with a structure type, suitably cast, is also a pointer to the first member of the 
structure. 

A structure declaration of the form, 
struct tag; 

can be used to declare a new structure within a block, temporarily hiding the old structure. When the block 
ends, the previous structure’s hidden declaration will be restored. For example, 

struct thing { int a,b; }; 

/* ... */ 

{ 

struct thing; 

struct si { struct thing * thingptr; } tptr; 

struct thing { struct si * slptr; } sptr; 

} 

the original definition of struct thing is suppressed in order to create a new definition. Failure to 
suppress the original definition would result in thingptr being a pointer to the old definition of thing 
rather than the new one. 
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Redefining structures can be confusing and should be avoided. 

7.1.1 Bit-fields 

A member of a structure can be declared as a bit-field, provided the type of the member is int, 
unsigned int or signed int. 

In addition, the Open Watcom C 16 and C 32 compilers allow the types char, unsigned char, 
short int and unsigned short int to be bit-fields. 


A bit-field declares the member to be a number of bits. A value may be assigned to the bit-field in the same 
manner as other integral types, provided the value can be stored in the number of bits available. If the 
value is too big for the bit-field, excess high bits are discarded when the value is stored. 

The type of the bit-field determines the treatment of the highest bit of the bit-field. Signed types cause the 
high bit to be treated as a sign bit, while unsigned types do not treat it as a sign bit. For a bit-field defined 
with type int (and no signed or unsigned keyword), whether or not the high bit is considered a sign 
bit is implementation-defined. 

The Open Watcom C 16 and C 32 compilers treat the high bit of a bit-field of type int as a sign 
bit. 

A bit-field is declared by following the member name by a colon and a constant expression which evaluates 
to a non-negative value that does not exceed the number of bits in the type. 

A bit-field may be declared without a name and may be used to align a structure to an imposed form. Such 
a bit-field cannot be referenced. 

If two bit-fields are declared sequentially within the same structure, and they would both fit within the 
storage unit assigned to them by the compiler, then they are both placed within the same storage unit. If the 
second bit-field doesn’t fit, then whether it is placed in the next storage unit, or partially placed in the same 
unit as the first and spilled over into the next unit, is implementation-defined. 

The Open Watcom C 16 and C 32 compilers place a bit-field in the next storage unit if it will not fit 
in the remaining portion of the previously defined bit-field. Bit-fields are not allowed to straddle 
storage unit boundaries. 


An unnamed member declared as : 0 prevents the next bit-field from being placed in the same storage 

unit as the previous bit-field. 

The order that bit-fields are placed in the storage unit is implementation-defined. 

The Open Watcom C 16 and C 32 compilers place bit-fields starting at the low-order end (least 
significant bit) of the storage unit. If a 1-bit bit-field is placed alone in an unsigned int then a 
value of 1 in the bit-field corresponds to a value of 1 in the integer. 
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Consider the following structure definition: 
struct list_ el { 


struct list_ el 

* link; 


unsigned short 

elnum; 


unsigned int 

length 

: 3; 

signed int 

offset 

: 4; 

int 

flag 

: 1; 

char * 

text; 



} ; 

The structure list_ el contains the following members: 

1. link is a pointer to a list_ el structure, indicating that instances of this structure will 
probably be used in a linked list, 

2. elnum is an unsigned short integer, 

3. length is an unsigned bit-field containing 3 bits, allowing values in the range 0 through 7, 

4. offset is a signed bit-field containing 4 bits, which will be placed in the same integer with 
length. Since the type is signed int, the range of values for this bit-field is -8 through 7, 

5. flag is a 1-bit field. 

Since the type is int, the Open Watcom C 16 and C 32 compilers will treat the bit as a 
sign bit, and the set of values for the bit-field is -1 and 0. 

6. text is a pointer to character, possibly a string. 

7.2 Unions 

A union is similar to a structure, except that each member of a union is placed starting at the same storage 
location, rather than in sequentially higher storage locations. (The Pascal term for a union is "variant 
record".) 

The name space for union tags is different from that of object names, labels and member names, so a tag 
may be the same identifier as one of these other kinds. The tag may not be the same identifier as the tag of 
a structure, enumeration or another union. 

Each union has its own name space, so an identifier may be used as a member name in several different 
unions. An identifier that is an object name, structure tag, structure member name, union tag, enumeration 
tag or label may also be used as a member name without ambiguity. 

With Open Watcom C 16 and C 32 , unions, like structures, may contain unnamed members that are 
structures or unions. References to the members of an unnamed structure or union are made as if 
the members of the inner structure or union were at the outer level. 


The size of a union is the size of the largest of the members it contains. 

A pointer to an object that is a union points to each of the members of the union. If one or more of the 
members of the union is a bit-field , then a pointer to the object also points to the storage unit in which the 
bit-field resides. 
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Storing a value in one member of a union, and then referring to it via another member is only meaningful 
when the different members have the same type. Members of a union may themselves be structures, and if 
some or all of the members start with the same members in each structure, then references to those structure 
members may be made via any of the union members. For example, consider the following structure and 
union definitions: 


struct reel 
int 
int 

char * 

} ; 


rectype; 
vl, v2,v3; 
text; 


struct rec2 { 

int rectype; 

short int flags : 8; 

enum {red, blue, green} 

} ; 


hue; 


union alt_ rec { 

struct reel vail; 
struct rec2 val2; 

} ; 


alt_ rec is a union defining two membersvall and val2, which are two different forms of a record, 
namely the structures reel and rec2 respectively. Each of the different record forms starts with the 
member rectype . The following program fragment would be valid: 

union alt_ rec record; 

/* ... */ 

record.reel.rectype = 33; 

DoSomething( record.rec2.rectype ); 

However, the following fragment would exhibit implementation-defined behavior: 

record.reel.vl = 27; 

DoSomethingElse( record.rec2.hue ); 

In other words, unless several members of a union are themselves structures where the first few members 
are of the same type, a program should not store into a union member and retrieve a value using another 
union member. Generally, a flag or other indicator is kept to describe which member of the union is 
currently the "active" member. 


7.3 Pointers 


A pointer to an object is equivalent to the address of the object in the memory of the computer. 

An object may be declared to be a pointer to a type of object, or it may be declared to be a pointer to no 
particular type. The form. 
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type * identifier; 

declares the identifier to be a pointer to the given type. If type is void, then the identifier is a pointer to no 
particular type of object (a generic pointer). 

The following examples illustrate various pointer declarations: 

int * intptr; 
intptr is a pointer to an int. 

char * charptr; 
charptr is a pointer to a char. 

struct tokendef * token; 
token is a pointer to the structure tokendef. 

char * argv[] ; 

argv is an array of pointers to char or an array of pointers to strings. 

char ** strptr; 
strptr is a pointer to a pointer to char. 

void * dumpbeg; 

dumpbeg is a pointer, but to no particular type of object. 

Any place that a pointer may be used, the constant 0 may also be used. This value is the null pointer 
constant. The value that is used internally to represent a null pointer is guaranteed not to be a pointer to an 
object. It does not necessarily correspond to the integer value 0. It merely represents a pointer that does 
not currently point at anything. The macro NULL, defined in the header <stddef. h>, may also be used 
in place of 0. 

7.3.1 Special Pointer Types for Open Watcom C 16 


Note: the following sections only apply to the Open Watcom C 16 (16-bit) compiler. For the 
Open Watcom C 32 compiler, see the section "Special Pointer Types for Open Watcom C 32 ". 


On the 8086, a normal pointer (16 bits) can only point to a 64K region of the total memory available on the 
machine. This effectively limits any program to a maximum of 64K of executable code and 64K of data. 
For many applications, this does not pose a limitation. 

Some applications need more than 64K of code or data, or both. The Open Watcom C 16 compiler provides 
a mechanism whereby pointers can be declared that get beyond the 64K limit. This can be done either by 
specifying an option when compiling the files (see the User’s Guide) or by including a special type 
qualifier keyword in the declaration of the object. Later sections describe these keywords and their use. 

The use of the keywords may prevent the program from compiling using other C compilers, in particular 
when the program is being transported to another system. However, the preprocessor can be used to 
eliminate the keywords on these other systems. 

Before discussing the special pointer types, it is important to understand the different memory models that 
are available and what they mean. The five memory models are referred to as: 

small small code (code < 64K), small data (data < 64K) 
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compact small code (code < 64K), big data (total data > 64K, all objects < 64K) 

medium big code (code > 64K), small data (data < 64K) 

large big code (code > 64K), big data (total data > 64K, all objects < 64K) 

huge big code (code > 64K), huge data (total data > 64K, objects > 64K) 

The following sections discuss the memory models in terms of "small" and "big" code and data sizes. The 
terms "small", "compact", "medium", "large" and "huge" are simply concise terms used to describe the 
combinations of code and data sizes available. 

7.3.1.1 The Small and Big Code Models 

Each program can use either small code (less than 64K) or big code (more than 64K). Small code means 
that all functions (together) must fit within the 64K limit on code size. It is possible to call a function using 
only a 16-bit pointer. This is the default. 

Big code removes the restriction, but requires that all functions be called with a 32-bit pointer. A 32-bit 
pointer consists of two 16-bit quantities, called the segment and offset. (When the computer uses the 
segment and offset to refer to an actual memory location, the two values are combined to produce a 20-bit 
memory address, which allows for the addressing of 1024K of memory.) Because of the larger pointers, the 
code generated by the big code option takes more space and takes longer to execute. 

When the big code option is being used, it is possible to group functions together into several 64K (or 
smaller) regions. Each module can be its own region, or several modules can be grouped. It is possible to 
call other functions within the same group using a 16-bit value. These functions are said to be near. 
Functions outside the group can still be called, but must be called using a 32-bit value. These functions are 
said to be far. 

When the big code option is given on the command line for compiling the module, ordinary pointers to 
functions will be defined automatically to be of the larger type, and function calls will be done using the 
longer (32-bit) form. 

It is also possible to use the small code option, and to override certain functions and pointers to functions as 
being far. However, this method may lead to problems. The Open Watcom C 16 compiler generates special 
function calls that the programmer doesn’t see, such as checking for stack overflow when a function is 
invoked. These calls are either near or far depending entirely on the memory model chosen when the 
module is compiled. If the small code model is being used, all calls will be near calls. If, however, several 
code groups are created with far calls between them, they will all need to access the stack overflow 
checking routines. The linker can only place these special routines in one of the code groups, leaving the 
other functions without access to them, causing an error. 

To resolve this problem, mixing code models requires that all modules be compiled with the big code 
model, overriding certain functions as being near. In this manner, the stack checking routines can be placed 
in any code group, which the other code groups can still access. Alternatively, a command-line switch may 
be used to turn off stack checking, so no stack checking routines get called. 

7.3.1.2 The Small and Big Data Models 

Each program can use either small data (less than 64K) or big data (more than 64K). Small data requires 
that all objects exist within one 64K region of memory. It is possible to refer to each object using a 16-bit 
pointer. This is the default. 
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Big data removes the restriction, but all pointers to data objects require a 32-bit pointer. As with the big 
code option, extra instructions are required to manipulate the 32-bit pointer, so the generated code will be 
larger and not as fast. 

With either small or big data, each object is restricted in size to a maximum of 64K bytes. However, an 
object may be declared as huge, allowing the object to be bigger than 64K bytes. Pointers to huge objects 
are the least efficient because of extra code required to handle them, especially when doing pointer 
arithmetic. Huge objects are discussed in the section "The_huge Keyword". 

When the big data option is being used, the program still retains one region up to 64K in size in which 
objects can be referred to using 16-bit pointers, regardless of the code group being executed. These objects 
are said to be near. Objects outside this region can still be referenced, but must be referred to using a 
32-bit value. These objects are said to be far. 

When the big data option is given on the command line for compiling the module, ordinary pointers to 
objects other than functions will be defined automatically to be of the larger type. 

It is also possible to use the small data option, and to override certain objects as being far. The programmer 
must decide which method is easier to use. 

7.3.1.3 Mixing Memory Models 

It is possible to mix small and big code and data pointers within one program. In fact, a programmer 
striving for optimum efficiency will probably mix pointer types. But great care must be taken! 

In some applications, the programmer may want the ability to have either big code or big data, but won't 
want to pay the extra-code penalty required to compile everything accordingly. In the case of big data, the 
programmer may realize that 99% of the data structures can reside within the 64K limit, and the remaining 
ones must go beyond that limit. Similarly, it may be desirable to have only a few functions that don't fit 
within the 64K limit. 

When overriding the current memory model, it is very important to declare each type properly. 

The following sections describe how to override the current memory model. 

7.3.1.4 The _ Jar Keyword for Open Watcom C 16 

When the big code memory model is in effect, functions are far and pointers to functions are declared 
automatically to be pointers to far functions. Similarly, the big data model causes all pointers to objects 
(other than functions) to be pointers to far objects. However, when either the small code or small data 
model is being used, the keyword_far may be used to override to the big model. 

The_far keyword is a type qualifier that modifies the token that follows it. If_far preceded (as in 

_far *), then the pointer points to something far. Otherwise, if_far precedes the identifier of the 

object or function being declared (as in_far x), then the object itself is far. 

The keyword_far can only be applied to function and object names and the indirection (pointer) symbol 

*. Parameters to functions may not be declared as_far since they are always in the 64K data area that is 

near. 
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Open Watcom C 16 provides the predefined macros far and _ far for convenience and 
compatibility with the Microsoft C compiler. They may be used in place of_far. 

The following examples illustrate the use of the_far keyword. The examples assume that the small 

memory model (small code, small data) is being used. 

int _ far * ptr; 

declares ptr to be a pointer to an integer. The object ptr is near (addressable using only 16 bits), 
but the value of the pointer is the address of an integer which is far, and so the pointer contains 32 
bits. 

int *_far fptr; 

also declares fptr to be a pointer to an integer. However, the object fptr is far, but the integer 
that it points to is near. 

int_far *_far ffptr; 

declares ffptr to be a pointer (which is far) to an integer (which is far). 

When declaring a function, placing the keyword_far in front of the function name causes the compiler 

to treat the function as being far. It is important, if the function is called before its definition, that a 
function prototype be included prior to any calls. For example, the declaration, 

void_far BubbleSort() ; 

declares the function BubbleSort to be far, meaning that any calls to it must be far calls. 

Here are a few more examples. These, too, assume that the small memory model (small code, small data) is 
being used. 

struct symbol * _far FSymAlloc( void ); 

declares the function FSymAlloc to be far, returning a pointer to a near symbol structure. 

struct symbol_far *_far FFSymAlloc( void ) ; 

declares the function FFSymAlloc to be far, returning a pointer to a far symbol structure. 

void Indirect( float _far fn() ); 

declares the function Indirect to be near, taking one parameter f n which is a pointer to a far 
function that returns a float. 

int AdjustLeft( struct symbol *_far symptr ) ; 

is an invalid declaration, since it attempts to declare symptr to be far. All parameters must be 
near, since they reside in the 64K data area that is always near. 

7.3.1.5 The _ jnear Keyword for Open Watcom C 16 

When the small code memory model is in effect, functions are near, and pointers to functions are 
automatically declared to be pointers to near functions. Similarly, the small data model causes all pointers 
to objects (other than functions) to be pointers to near objects. However, when either the big code or big 
data model is being used, the keyword_near may be used to override to the small model. 

The_near keyword is a type qualifier that modifies the token that follows it. If_near preceded (as 

in_near *), then the pointer points to something near. Otherwise, if_near precedes the identifier of 

the object or function being declared (as in_near x), then the object itself is near. 
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The keyword_near can only be applied to function and object names and the indirection (pointer) 

symbol * . 

Open Watcom C 16 provides the predefined macros near and _ near for convenience and 
compatibility with the Microsoft C compiler. They may be used in place of_near. 

The following examples illustrate the use of the_near keyword. These examples assume that the large 

memory module (big code, big data) is being used. 

extern int _ near * x; 

declares the object x to be a pointer to a near integer, (x is not necessarily within the 64K data area 
that is near, but the integer that it points to is.) 

extern int * _ near nx; 

declares the object nx to be near, and is a pointer to a far integer, (nx is within the 64K data area 
that is near, but the integer that it points to might not be.) 

extern int_near *_near nnx; 

declares the object nnx to be near, and is a pointer to a near integer, (nnx and the integer that it 
points to are both within the 64K data area that is near.) 

struct symbol *_near NSymAlloc( void ) ; 

declares the function NSymAlloc to be near, and returns a pointer to a far symbol structure. 

struct symbol_near *_near NNSymAlloc( void ) ; 

declares the function NNSymAlloc to be near, and returns a pointer to a near symbol structure. 

7.3.1.6 The__huge Keyword for Open Watcom C 16 

Even using the big data model, each object is restricted in size to 64K. Some applications will need to get 

beyond this limitation. The Open Watcom C 16 compiler provides the keyword_huge to describe those 

objects that exceed 64K in size. The code generated for these objects is less efficient than for_far 

objects. 

The declaration of such objects follows the same pattern as above, with the keyword_huge preceding 

the name of the object if the object itself is bigger than 64K, or preceding the * if the pointer is to an object 
that is bigger than 64K. 

The keyword_huge can only be applied to arrays. Huge objects may be used in both the small and big 

data models. 


Open Watcom C 16 provides the predefined macros huge and _ huge for convenience and 
compatibility with the Microsoft C compiler. They may be used in place of_huge. 

These examples illustrate the use of the_huge keyword. They assume that big code, small data (the 

medium memory model) is in effect. 

int_huge iarray[50000] ; 

declares the object iarray to be an array of 50000 integers, for a total size of 100000 bytes, 
int_huge * iptr; 

declares iptr to be near, and a pointer to an integer that is part of a huge array, such as an element 
of iarray. 
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7.3.2 Special Pointer Types for Open Watcom C 32 

With an 80386 processor in "protect" mode, a normal pointer (32 bits) can point to a 4 gigabyte 
(4,294,967,296 byte) region of the memory available on the machine. (In practice, memory limits may 
mean that these regions will be smaller than 4 gigabytes.) These regions are called segments, and there may 
be more than one segment defined for the memory. Each 32-bit pointer is actually an offset within a 4 
gigabyte segment, and the offsets within two different segments are generally not related to each other in a 
known manner. 

As an example, the screen memory may be set up so that it resides in a different region of the memory from 
the program’s data. Normal pointers (those within the program’s data area) will not be able to access such 
regions. 

Like the 16-bit version of Open Watcom C (for the 8086 and 80286), Open Watcom C 32 uses the_near 

and_far keywords to describe objects that are either in the normal data space or elsewhere. 

Objects or functions that are near require a 32-bit pointer to access them. 

Objects or functions that are far require a 48-bit pointer to access them. This 48-bit pointer consists of two 
parts: a selector consisting of 16 bits, and an offset consisting of 32 bits. A selector is similar to a segment 
in a 16-bit program’s far pointer, except that the numeric value of the selector does not directly determine 
the memory region. Instead, the processor uses the selector value in conjunction with a "descriptor table" 
to determine what region of memory is to be accessed. In the discussion of far pointers on the 80386, the 
terms selector and segment may be used interchangeably. 

Like the 16-bit compiler, the Open Watcom C 32 compiler supports the small, compact, medium and large 
memory models. Throughout the discussions in the following sections, it is assumed that the small memory 
model is being used, since it is the most likely to be used. 

7.3.2.1 The _ Jar Keyword for Open Watcom C 32 

The_far keyword is a type qualifier that modifies the token that follows it. If_far preceded (as in 

_far *), then the pointer points to something that is far (not in the normal data region). Otherwise, if 

_far precedes the identifier of the object or function being declared (as in_far x), then the object or 

function is far. 

The keyword_far can only be applied to function and object names and the indirection (pointer) symbol 

*. Parameters to functions may not be declared as_far, since they are always in the normal data region. 

These examples illustrate the use of the_far keyword, and assume that the small memory model is being 

used. 


int_far * ptr; 

declares ptr to be a pointer to an integer. The object ptr is near but the integer that it points to is 
far. 

int *_far fptr; 

also declares fptr to be a pointer to an integer. However, the object fptr is far, but the integer 
that it points to is near. 

int_far *_far ffptr; 

declares ffptr to be a pointer (which is far) to an integer (which is far). 
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When declaring a function, placing the keyword_far in front of the function name causes the compiler 

to treat the function as being far. It is important, if the function is called before its definition, that a 
function prototype be included prior to any calls. For example, the declaration, 

extern void_far SystemService() ; 

declares the function SystemService to be far, meaning that any calls to it must be far calls. 

Here are a few more examples: 

extern struct systbl *_far FSysTblPtr( void ) ; 

declares the function FSysTblPtr to be far, returning a pointer to a near systbl structure. 

extern struct systbl _far * _far FFSysTblPtr( void ); 

declares the function FFSysTblPtr to be far, returning a pointer to a far systbl structure. 

extern void Indirect! char _far fn() ); 

declares the function Indirect to be near, taking one parameter f n which is a pointer to a far 
function that returns a char. 

extern int StoreSysTbl( struct systbl * _ far sysptr ); 

is an invalid declaration, since it attempts to declare sysptr to be far. All parameters must be 
near, since they reside in the normal data area that is always near. 

7.3.2.2 The __near Keyword for Open Watcom C 32 

The_near keyword is a type qualifier that modifies the token that follows it. If_near preceded (as 

in_near *), then the pointer points to something that is near (in the normal data region). Otherwise, if 

_near precedes the identifier of the object or function being declared (as in_near x), then the object 

or function is near. 

The keyword_near can only be applied to function and object names and the indirection (pointer) 

symbol *. 

For programmers using the small memory model, the_near keyword is not required, but may be useful 

for making the program more readable. 

7.3.2.3 The __far16 and_Seg16 Keywords 

With the 80386 processor, a far pointer consists of a 16-bit selector and a 32-bit offset. Open Watcom 
C 32 also supports a special kind of far pointer which consists of a 16-bit selector and a 16-bit offset. These 
pointers, referred to as farl6 pointers, allow 32-bit code to access code and data running in 16-bit mode. 

In the OS/2 operating system (version 2.0 or higher), the first 512 megabytes of the 4 gigabyte segment 
referenced by the DS register is divided into 8192 areas of 64K bytes each. A farl6 pointer consists of a 
16-bit selector referring to one of the 64K byte areas, and a 16-bit offset into that area. 

For compatibility with Microsoft C, Open Watcom C 32 provides the_farl 6 keyword. A pointer 

declared as. 
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type _far 16 * name ; 

defines an object that is a farl6 pointer. If such a pointer is accessed in the 32-bit environment, the 
compiler will generate the necessary code to convert between the farl6 pointer and a "flat" 32-bit pointer. 

For example, the declaration, 

char _farl6 * bufptr; 

declares the object bufptr to be a farl6 pointer to char. 

A function declared as, 

type _far 16 func ( parm-list ) ; 

declares a 16-bit function. Any calls to such a function from the 32-bit environment will cause the 
compiler to convert any 32-bit pointer parameters to farl6 pointers, and any int parameters from 32 bits 
to 16 bits. (In the 16-bit environment, an object of type int is only 16 bits.) Any return value from the 
function will have its return value converted in an appropriate manner. 

For example, the declaration, 

char * _farl6 Scan( char * buffer, int buflen, short err ); 


declares the 16-bit function Scan. When this function is called from the 32-bit environment, the buffer 
parameter will be converted from a flat 32-bit pointer to a farl6 pointer (which, in the 16-bit environment, 

would be declared as char_far *). Thbuflen parameter will be converted from a 32-bit integer 

to a 16-bit integer. The err parameter will be passed unchanged. Upon returning, the farl6 pointer (far 
pointer in the 16-bit environment) will be converted to a 32-bit pointer which describes the equivalent 
location in the 32-bit address space. 

For compatibility with IBM C Set/2, Open Watcom C 32 provides the _ Segl 6 keyword. Note that 
_ Segl 6 is not interchangeable with_far 16. 

A pointer declared as, 

type * _ Segl6 name; 

defines an object that is a farl6 pointer. Note that the _ Segl 6 appears on the opposite side of the* than 
the_f ar 16 keyword described above. 

For example, 

char * _ Segl6 bufptr; 

declares the object bufptr to be a farl6 pointer to char (the same as above). 

The _ Segl 6 keyword may not be used to describe a 16-bit function. A #pragma directive must be used. 
See the User’s Guide for details. A function declared as. 
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type * _ Segl6 func ( parm-list) ; 
declares a 32-bit function that returns a farl6 pointer. 

For example, the declaration, 

char * _ Segl6 Scan( char * buffer, int buflen, short err ); 

declares the 32-bit function Scan. No conversion of the parameter list will take place. The return value is 
a far 16 pointer. 

7.3.3 Based Pointers for Open Watcom C 16 and C 32 

Near pointers are generally the most efficient type of pointer because they are small, and the compiler can 
assume knowledge about what segment of the computer’s memory the pointer (offset) refers to. Far 
pointers are the most flexible because they allow the programmer to access any part of the computer’s 
memory, without limitation to a particular segment. However, far pointers are bigger and slower because 
of the additional flexibility. 

Based pointers are a compromise between the efficiency of near pointers and the flexibility of far pointers. 
With based pointers, the programmer takes responsibility to tell the compiler which segment a near pointer 
(offset) belongs to, but may still access segments of the computer’s memory outside of the normal data 
segment (DGROUP). The result is a pointer type which is as small as and almost as efficient as a near 
pointer, but with most of the flexibility of a far pointer. 

An object declared as a based pointer falls into one of the following categories: 

• the based pointer is in the segment described by another object, 

• the based pointer, used as a pointer to another object of the same type (as in a linked list), refers to 
the same segment, 

• the based pointer is an offset to no particular segment, and must be combined explicitly with a 
segment value to produce a valid pointer. 

To support based pointers, the following keywords are provided: 

_based 

_ segment 

_segname 

_self 

The following operator is also provided: 

: > 

These keywords and operator are described in the following sections. 

Two macros, defined in <malloc . h> are also provided: 

_ NULLSEG 
_ NULLOFF 

They are used in a similar manner to NULL, but are used with objects declared as_segment and 

_based respectively. 
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7.3.3.1 Segment Constant Based Pointers and Objects 

A segment constant based pointer or object has its segment value based on a specific, named segment. A 
segment constant based object is specified as: 

type _based (_segname ( "segment" ) Object-name ; 

and a segment constant based pointer is specified as: 

type _based (_segname ( "segment" ) ) Object-name ; 

where segment is the name of the segment in which the pointer or object is based. As shown above, the 
segment name is always specified as a string. There are three special segment names recognized by the 
compiler: 

CODE" 

CONST" 

DATA" 

The CODE" segment is the default code segment. The"_ CONST" segment is the segment containing 
constant values. The DATA" segment is the default data segment. If the segment name is not one of the 
three recognized names, then a segment will be created with that name. If a segment constant based object 
is being defined, then it will be placed in the named segment. If a segment constant based pointer is being 
defined, then it can point at objects in the named segment. 

The following examples illustrate segment constant based pointers and objects: 

int_based(_segname! CODE" ) ) ival = 3; 

int_based!_segname! CODE" ) ) * iptr; 

ival is an object that resides in the default code segment, iptr is an object that resides in the data 
segment (the usual place for data objects), but points at an integer which resides in the default code 
segment, iptr is suitable for pointing at ival. 

char_based!_segname! "GOODTHINGS" ) ) thing; 

thing is an object which resides in the segment GOODTHINGS, which will be created if it does not 
already exist. (The creation of segments is done by the linker, and is a method of grouping objects and 
functions. Nothing is implicitly created during the execution of the program.) 

7.3.3.2 Segment Object Based Pointers 

A segment object based pointer derives its segment value from another named object. A segment object 
based pointer is specified as follows: 

type _based ( segmen) * name; 

where segment is an object defined as type_segment. 

An object of type_segment may contain a segment value. Such an object is particularly designed for 

use with segment object based pointers. 

The following example illustrates a segment object based pointer: 
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_ segment seg; 

char_based( seg ) * cptr; 

The object seg contains only a segment value. Whenever the object cptr is used to point to a character, 
the actual pointer value will be made up of the segment value found in seg and the offset value found in 
cptr. The object seg might be assigned values such as the following: 

• a constant value (eg. the segment containing screen memory), 

• the result of the library function _ bheapseg, 

• the segment portion of another pointer value, by casting it to the type_segment. 


7.3.3.3 Void Based Pointers 

A void based pointer must be explicitly combined with a segment value to produce a reference to a memory 
location. A void based pointer does not infer its segment value from another object. The : > (base) 
operator is used to combine a segment value and a void based pointer. 

For example, on an IBM PC or PS/2 computer, running DOS, with a color monitor, the screen memory 
begins at segment 0xB800, offset 0. In a video text mode, to examine the first character currently displayed 
on the screen, the following code could be used: 

extern void main() 

{ 

_ segment screen; 

char_based ( void ) * scrptr; 

screen = 0xB800; 
scrptr = 0; 

printf( "Top left character is '%c'.\n", 


The general form of the : > operator is: 
segment : > offset 

where segment is an expression of type_segment, and offset is an expression of type_based ( 

void ) *. 

7.3.3.4 Self Based Pointers 

A self based pointer infers its segment value from itself. It is particularly useful for structures such as 
linked lists, where all of the list elements are in the same segment. A self based pointer pointing to one 
element may be used to access the next element, and the compiler will use the same segment as the original 
pointer. 

The following example illustrates a function which will print the values stored in the last two members of a 
linked list: 


struct a { 

struct a _based( _self ) * next; 

int number; 

}; 
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extern void PrintLastTwo( struct a far * list ) 

{ 

_ segment seg; 

struct a _based( seg ) * aptr; 

seg = FP_ SEG ( list ) ; 
aptr = FP_ OFF ( list ) ; 

for ( ; aptr != _ NULLOFF; aptr = aptr->next ) { 

if ( aptr->next == _ NULLOFF ) { 

printf( "Last item is %d\n", aptr->number ); 

} else if ( aptr->next->next == _ NULLOFF ) { 

printf( "Second last item is %d\n", aptr->number ); 


} 

The parameter to the function PrintLastTwo is a far pointer, pointing to a linked list structure anywhere 
in memory. It is assumed that all members of a particular linked list of this type reside in the same segment 
of the computer’s memory. ( Another instance of the linked list might reside entirely in a different 
segment.) The object seg is given the segment portion of the far pointer. The object aptr is given the 
offset portion, and is described as being based in the segment stored in seg. 

The expression aptr->next refers to the next member of the structure stored in memory at the offset 
stored in aptr and the segment implied by aptr, which is the value stored in seg . So far, the behavior 
is no different than if next had been declared as, 

struct a * next; 

The expression aptr->next->next illustrates the difference of using a self based pointer. The first 
part of the expression (aptr->next) occurs as described above. However, using the result to point to the 
next member occurs by using the offset value found in the next member and combining it with the 
segment value of the pointer used to get to that member , which is still the segment implied by aptr, which 

is the value stored in seg . If next had not been declared using_ based (_self ), then the 

second pointing operation would refer to the offset value found in the next member, but with the default 
data segment (DGROUP), which may or may not be the same segment as stored in seg. 


7.4 Void 

The void type has several purposes: 

1. To declare an object as being a pointer to no particular type. For example, 

void * membegin; 

defines membegin as being a pointer. It does not point to anything without a cast operator. 
The statement, 

*(char *) membegin = ' \0'; 
will place a zero in the character at which membegin points. 

2. To declare a function as not returning a value. For example, 

void rewind( FILE * stream ); 

declares the standard library function rewind which takes one parameter and returns nothing. 
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3. To evaluate an expression for its side-effects, discarding the result of the expression. For 
example, 

(void) getchar (); 

calls the library function getchar, which normally returns a character. In this case, the 
character is discarded, effectively advancing one character in the file without caring what 
character is read. This use of void is primarily for readability, because casting the expression 
to the void type will be done automatically. The above example could also be written as, 

getchar(); 

The keyword void is also used in one other instance. If a function takes no parameters, void may be 
used in the declaration. For example, 

int getchar( void ) ; 

declares the standard library function getchar, which takes no parameters and returns an integer. 

No object (other than a function) may be declared with type void. 


7.5 The const and volatile Declarations 


An object may be declared with the keyword const. Such an object may not be modified directly by the 
program. For objects with static storage duration, this type qualifier describes to the compiler which 
objects may be placed in read-only memory, if the computer supports such a concept. It also provides the 
opportunity for the compiler to detect attempts to modify the object. The compiler may also generate better 
code when it knows that an object will not be modified. 

Even though an object is declared to be constant, it is possible to modify its value indirectly by storing its 
address (using a cast) in another object declared to be a pointer to the same type (without the const), and 
then using the second object to modify the value to which it points. Flowever, this should be done with 
caution, and may fail on computers with protected memory. 

If the declaration of an object does not include *, that is to say it is not a pointer of any kind, then the 
keyword const appearing anywhere in the type specifier (including any typedef ’s) indicates that the 
object is constant and may not be changed. If the object is a pointer and const appears to the left of the *, 
the object is a pointer to a constant value, meaning that the value to which the pointer points may not be 
modified, although the pointer value may be changed. If const appears to the right of the *, the object is 
a constant pointer to a value, meaning that the pointer to the value may not be changed, although what the 
pointer points to may be changed. If const appears on both sides of the *, the object is a constant pointer 
to a constant value, meaning that the pointer and the object to which it points may not be changed. 

If the declaration of a structure, union or array includes const, then each member of the type, when 
referred to, is treated as if const had been specified. 
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The declarations, 

const int baseyear = 1900; 
const int * byptr; 

declare the object baseyear to be an integer whose value is constant and set to 1900, and the object 
byptr to be a pointer to a constant object of integer type. If byptr was made to point to another integer 
that was not, in fact, declared to be constant, then byptr could not be used to modify that value, byptr 
may be used to get a value from an integer object, and never to change it. Another way of stating it is that 
what byptr points to is constant, but byptr itself is not constant. 

The declarations, 

int baseyear; 

int * const byptr = Sbaseyear; 

declare the object byptr as a constant pointer to an integer, in this case the object baseyear. The value 
of baseyear may be modified via byptr, but the value of byptr itself may not be changed. In this 
case, byptr itself is constant, but what byptr points to is not constant. 

An object may be declared with the keyword volatile. Such an object may be freely modified by the 
program, and its value also may be modified through actions outside the program. For example, a flag may 
be set when a given interrupt occurs. The keyword volatile indicates to the compiler that care must be 
taken when optimizing code referring to the object, so that the meaning of the program is not altered. An 
object that the compiler might otherwise have been able to keep in a register for an extended period of time 
will be forced to reside in normal storage so that an external change to it will be reflected in the program’s 
behavior. 

If the declaration of an object does not include *, that is to say it is not a pointer of any kind, then the 
keyword volatile appearing anywhere in the type specifier (including any typedef’s) indicates that 
the object is volatile and may be changed at any time without the program knowing. If the object is a 
pointer and volatile appears to the left of the *, the object is a pointer to a volatile value, meaning that 
the value to which the pointer points may be changed at any time. If volatile appears to the right of the 
*, the object is a volatile pointer to a value, meaning that the pointer to the value may be changed at any 
time. If volatile appears on both the left and the right of the *, the object is a volatile pointer to a 
volatile value, meaning that the pointer or the value to which it points may be changed at any time. 

If the declaration of a structure, union or array includes volatile, then each member of the type, when 
referred to, is treated as if volatile had been specified. 

The declarations, 

volatile int attncount; 
volatile int * acptr; 

declare the object attncount to be an integer whose value may be altered at any time (say by an 
asynchronous attention handler), and the object acptr to be a pointer to a volatile object of integer type. 

If both const and volatile are included in the declaration of an object, then that object may not be 
modified by the program, but it may be modified through some external action. An example of such an 
object is the clock in a computer, which is modified periodically (every clock "tick"), but programs are not 
allowed to change it. 
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8 Storage Classes 


The storage class of an object describes: 

• the duration of the existence of the object. An object may exist throughout the execution of the 
program, or only during the span of time that the function in which it is defined is executing. In the 
latter case, each time the function is called, a new instance of the object is created, and that object is 
destroyed when the function returns. 

• the scope of the object. An object may be declared so that it is only accessible within the function in 
which it is defined, within the module or throughout the entire program. 

A storage class specifier is one of: 

auto 

register 

extern 

static 

typedef 

typedef is included in the list of storage class specifiers for convenience, because the syntax of a type 
definition is the same as for an object declaration. A typedef declaration does not create an object, only 
a synonym for a type, which does not have a storage class associated with it. 

Only one of these keywords (excluding typedef) may be specified in a declaration of an object. 

If an object or function is declared with a storage class, but no type specifier, then the type of the object or 
function is assumed to be int. 

While a storage class specifier may be placed following a type specifier, this tends to be difficult to read. It 
is recommended that the storage class (if present) always be placed first in the declaration. The ISO C 
standard states that the ability to place the storage class specifier other than at the beginning of the 
declaration is an obsolescent feature. 


8.1 Type Definitions 

A typedef declaration introduces a synonym for another type. It does not introduce a new type. 
The general form of a type definition is: 
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typedef type-information typedef-name ; 

The typedef-name may be a comma-separated list of identifiers, all of which become synonyms for the 
type. The names are in the same name space as ordinary object names, and can be redefined in inner 
blocks. However, this can be confusing and should be avoided. 

The simple declaration, 

typedef signed int COUNTER; 

declares the identifier COUNTER to be equivalent to the type signed int. A subsequent declaration 
like. 


COUNTER ctr; 

declares the object ctr to be a signed integer. If, later on, it is necessary to change all counters to be long 
signed integers, then only the typedef would have to be changed, as follows: 

typedef long signed int COUNTER; 

All declarations of objects of that type will use the new type. 

The typedef can be used to simplify declarations elsewhere in a program. For example, consider the 
following structure: 

struct complex { 

double real; 

double imaginary; 


To declare an object to be an instance of the structure requires the following declaration: 
struct complex cnum; 

Now consider the following structure definition with a type definition: 

typedef struct { 
double real; 

double imaginary; 

} COMPLEX; 

In this case, the identifier COMPLEX refers to the entire structure definition, including the keyword 
struct. Therefore, an object can be declared as follows: 

COMPLEX cnum; 

While this is a simple example, it illustrates a method of making object declarations more readable. 

Consider the following example, where the object f nptr is being declared as a pointer to a function which 
takes two parameters, a pointer to a structure dim3 and an integer. The function returns a pointer to the 
structure dim3 . The declarations could appear as follows: 
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struct dim3 { 
int x; 
int y; 
int z; 

}; 

struct dim3 * (*fnptr) ( struct dim3 *, int ) ; 

or as: 

typedef struct { 
int x; 
int y; 
int z; 

} DIM3; 

DIM3 * (*fnptr)( DIM3 *, int ); 

or as: 

typedef struct { 
int x; 
int y; 
int z; 

} DIM3; 

typedef DIM3 * DIM3FN( DIM3 *, int ); 

DIM3FN * fnptr; 

The last example simply declares fnptr to be a pointer to a DIM3FN, while DIM3FN is declared to be a 
function with two parameters, a pointer to a DIM3 and an integer. The function returns a pointer to a 
DIM3 . DIM3 is declared to be a structure of three co-ordinates. 

8.1.1 Compatible Types 

Some operations, such as assignment, are restricted to operating on two objects of the same type. If both 
operands are already the same type, then no special conversion is required. Otherwise, the compiler may 
alter automatically one or both operands to make them the same type. The integral promotions and 
arithmetic conversions are examples. Other types may require an explicit cast. 

The compiler decides whether or not an explicit cast is required based on the concept of compatible types. 
The following types are compatible: 

• two types that are declared exactly the same way, 

• two types that differ only in the ordering of the type specifiers, for example, unsigned long 

int and int long unsigned, 

• two arrays of members of compatible type, where both arrays have the same size, or where one array 

is declared without size information. 
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• two functions that return the same type, one containing no parameter information, and the other 

containing a fixed number of parameters (no that are not affected by the default argument 

promotions, 

• two structures, defined in separate modules, that have the same number and names of members, in 
the same order, with compatible types, 

• two unions, defined in separate modules, that have the same number and names of members, with 
compatible types, 

• two enumerated types, defined in separate modules, that have the same number of enumeration 
constants, with the same names and the same values, 

• two pointers to compatible types. 

8.2 Static Storage Duration 

An object with static storage duration is created and initialized only once, prior to the execution of the 
program. Any value stored in such an object is retained throughout the program unless it is explicitly 
altered by the program (or it is declared with the volatile keyword). 

Any object that is declared outside the scope of a function has static storage duration. 

There are three types of static objects: 

1. objects whose values are only available within the function in which they are defined (no 
linkage). For example, 

extern void Fn( int x ) 

{ 

static int ObjCount; 

/* ... */ 

} 

2. objects whose values are only available within the module in which they are defined (internal 
linkage). For example, 

static int ObjCount; 

extern void Fn( int x ) 

{ 

/* ... */ 

} 

3. objects whose values are available to all components of the program (external linkage). For 
example, 

extern int ObjCount = { 0 }; 

extern void Fn( int x ) 

{ 

/* ... */ 

} 
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The first two types are defined with the keyword static, while the third is defined with the (optional) 
keyword extern. 

8.2.1 The static Storage Class 

Any declaration of an object may be preceded by the keyword static. A declaration inside a function 
indicates to the compiler that the object has no linkage, meaning that it is available only within the function. 
A declaration not inside any function indicates to the compiler that this object has internal linkage, meaning 
that it is available in all functions within the module in which it is defined. Other modules may not refer to 
the specific object. They may have their own object defined with the same name, but this is a questionable 
programming practice and should be avoided. 

The value of the object will be preserved between function calls. Any value placed in an object with static 
storage duration will remain unchanged until changed by a function within the same module. It is also 
possible for a pointer to the object to be passed to a function outside the module in which the object is 
defined. This pointer could be used to modify the value of the object. 

8.2.2 The extern Storage Class 

If an object is declared with the keyword extern inside a function, then the object has external linkage, 
meaning that its value is available to all modules, and to the function(s) containing the definition in the 
current module. No initializer list may be specified in this case, which implies that the space for the object 
is allocated in some other module. 

If an object is declared outside of the definition of a function, and the declaration does not contain either of 
the keywords static or extern, then the space for the object is created at this point. The object has 
external linkage, meaning that it is available to other modules in the program. 

The following examples illustrate the creation of external objects, provided the declarations occur outside 
any function: 

int X; 
float F; 

If the declaration for an object, outside of the definition of a function, contains the keyword extern and 
has an initializer list, then space for the object is created at this point, and the object has external linkage. 

If, however, the declaration does not include an initializer list, then the compiler assumes that the object is 
declared elsewhere. If, during the remainder of the compilation of the module, no further declarations of 
the object are found, or more declarations with extern and no initializer list are found, then the object 
must have space allocated for it in another module. If a subsequent declaration in the same module does 
have an initializer list or omits the extern keyword, then the space for the object is created at that point. 

The following examples also illustrate the creation of external objects: 

extern LIST * ListHead = 0; 

int StartVal = 77; 

However, the next examples illustrate the tentative definition of external objects. If no further definition of 
the object of a form shown above is found, then the object is found outside of the module. 

extern LIST * ListEl; 

extern int Z; 
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Another module may define its own object with the same name (provided it has static storage class), but it 
will not be able to access the external one. However, this can be confusing and is a questionable 
programming practice. 

Any value placed in an object declared with the extern keyword will remain unchanged until changed by 
a function within the same or another module. 

A function that is declared without the keyword static has external linkage. 

Suppose a module declares an object (outside of any function definition) as follows: 
struct list_ el * ListTop; 

where the structure list_ el is defined elsewhere. This declaration allocates space for and declares the 
object ListTop to be a pointer to a structure list_ el, with external linkage. Another module with the 
declaration, 

extern struct list_ el * ListTop; 

refers to the same object ListTop, and states that it is found outside of the module. 

Within a program, possibly consisting of more than one module, each object or function with external 
linkage must be defined (have space allocated for it) exactly once. 

8.3 Automatic Storage Duration 

The most commonly used object in a C program is one that has meaning only within the function in which 
it is defined. The object is created when execution of the function is begun and destroyed when execution 
of the function is completed. Such an object is said to have automatic storage duration. The scope of the 
object is said to be the function in which it is defined. 

If such an object has the same name as another object defined outside the function (using static or 
extern), then the outside object is hidden from the function. 

Within a function, any object that does not have its declaration preceded by the keyword static or 
extern has automatic storage duration. 

It is possible to declare an object as automatic within any block of a function. The scope of such an object 
is the block in which it is declared, including any blocks inside it. Any outside block is unable to access 
such an object. 

Automatic objects may be initialized as described in the chapter "Initialization of Objects". Initialization of 
the object only occurs when the block in which the object is declared is entered normally. In particular, a 
jump into a block nested within the function will not initialize any objects declared in that block. This is a 
questionable programming practice, and should be avoided. 
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The following function checks a string to see if it contains nothing but digits: 

extern int Islnt( const char * ptr ) 
/**********************************/ 

{ 

if( *ptr == '\0' ) return! 0 ); 

for ( ; ; ) { 

char ch; 

ch = *(ptr++); 

if( ch == '\0' ) return! 1 ); 

if ( !isdigit( ch ) ) return! 0 ); 

} 

} 

The object ch has a scope consisting only of the for loop. Any statements before or after the loop cannot 
access ch. 


8.3.1 The auto Storage Class 

The declaration of an object in a function that does not contain the keywords static, extern or 
register declares an object with automatic storage duration. Such an object may precede its declaration 
with the keyword auto for readability. 

An object declared with no storage class specifier or with auto is "addressable", which means that the 
address-of operator may be applied to it. 

The programmer should not assume any relationship between the storage locations of multiple auto 
objects declared in a function. If relative placement of objects is important, a structure should be used. 

The following function illustrates a use for auto objects: 

extern int FindSize( struct thing * thingptr ) 

/★★it*****************************************/ 

{ 

auto char * start; 
auto char * finish; 

FindEnds( thingptr, &start, Sfinish ) ; 
return( finish - start + 1 ) ; 

} 

The addresses of the automatic objects start and finish are passed to FindEnds, which, presumably, 
modifies them. 


8.3.2 The register Storage Class 

An object that is declared within a function, and whose declaration includes the keyword register, is 
considered to have automatic storage duration. The register keyword merely provides a hint to the 
compiler that this object is going to be heavily used, allowing the compiler to try to put it into a high-speed 
access part of the machine, such as a machine register. The compiler may, however, ignore such a directive 
for any number of reasons, such as. 
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• the compiler does not support objects in registers, 

• there are no available registers, or, 

• the compiler makes its own decisions about register usage. 

Only certain types of objects may be placed in registers, although the set of such types is 
implementation-defined. 

The Open Watcom C 16 and C 32 compilers may place any object that is sufficiently small, 
including a small structure, in one or more registers. 

The compiler will decide which objects will be placed in registers. The register keyword is 
ignored, except to prevent taking the address of such an object. 


Objects declared with or without register may generally be treated in the same way. An exception to 
this rule is that the address-of operator (&) may not be applied to a register object, since registers are 
generally not within the normal storage of the computer. 
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Any definition of an object may include a value or list of values for initializing it, in which case the 
declaration is followed by an equal sign (=) and the initial value(s). 

The initial value for an object with static storage duration may be any expression that evaluates to a 
constant value, including using the address-of operator to take the address of a function or object with static 
storage duration. 

The initial value for an object with automatic storage duration may be any expression that would be valid as 
an assignment to that object, including references to other objects. The evaluations of the initializations 
occur in the order in which the definitions of the objects occur. 


9.1 Initialization of Scalar Types 

The initial value for a scalar type (pointers, integers and floating-point types) may be enclosed in braces, 
although braces are not required. 


The following declarations might appear inside a function: 


static 

int 

MaxRecLen 

static 

int 

MaxMemSize 


float 

Pi 

auto 

int 

X 

register 

int 

Y 


1000 ; 

{ 1000 * 8 + 10000 } ; 
3.14159; 

3; 

x * MaxRecLen; 


9.2 Initialization of Arrays 

For arrays of characters being initialized with a string literal, and for arrays of wchar_ t being initialized 
with a wide string literal, the braces around initial values are optional. For other arrays, the braces are 
required. 

If an array of unknown size is initialized, then the size of the array is determined by the number of 
initializing values provided. In particular, an array of characters of unknown size may be initialized using a 
string literal, in which case the size of the array is the number of characters in the string, plus one for the 
terminating null character. Each character of the string is placed in successive elements of the array. 
Consider the following array declarations: 

char StartPt[] = "Starting point..."; 

int Tabs [ ] = { 1, 9, 17, 25, 33, 41 }; 

float Roots[] = { 1., 1.414, 1.732, 2., 2.236 }; 

The object StartPt is an array of 18 characters. Tabs is an array of 6 integers, and Roots is an array of 
5 floating-point numbers. 
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If an array is declared to have a certain number of elements, then the maximum number of values in the 
initialization list is the number of elements in the array. An exception is made for arrays of characters, 
where the initializer may be a string with the same length as the number of characters in the array. Each 
character from the string is assigned to the corresponding element of the array. The null character at the 
end of the string literal is ignored. 


If there are fewer initialization values than elements of the array, then any elements not receiving a value 
from the list are assigned the value zero (for arithmetic types), or the null pointer constant (for pointers). 
Consider the following examples: 


char Vowelsl[6] 
char Vowels2[6] 
int Numbers[10] 
float Blort[5] 


"aeiouy"; 

{ 'a', 'e', 'i', 'o', 'u', 'y' }; 

{ 100 , 10 , 1 } ; 

{ 5.6, -2.2 }; 


The objects Vowel si and Vowel s2 are both arrays of six characters, and both contain exactly the same 
values in each of their corresponding elements. The object Numbers is an array of 10 integers, the first 
three of which are initialized to 100, 10 and 1, and the remaining seven are set to zero. The object Blort 
is an array of 5 floating-point numbers. The first two elements are initialized to 5.6 and -2.2, and the 
remaining three are set to zero. 


If an array of more than one dimension is initialized, then each subarray may be initialized using a 
brace-enclosed list of values. This form will work for an arbitrary number of dimensions. Consider the 
following two-dimensional case: 


int Box [ 3] [4] 


{ { 11, 

12, 

13, 

14 

{ 21, 

22, 

23, 

24 

\—1 
CO 

32, 

33, 

34 


The object Box is an array of 3 arrays of 4 integers. There are three values in the initialization list, 
corresponding to the first dimension (3 rows). Each initialization value is itself a list of values 
corresponding to the second dimension (4 columns). In other words, the first list of values { 11, 12, 
13, 14 } is assigned to the first row of Box, the second list of values { 21, 22, 23, 24 } is 
assigned to the second row of Box, and the third list of values { 31, 32, 33, 34 } is assigned to the 
third row of Box . 


If all values are supplied for initializing an array, or if only elements from the end of the array are omitted, 
then the sub-levels need not be within braces. For example, the following declaration of Box is the same as 
above: 


int Box [ 3] [4] 


{ 11, 

12, 

13, 

14, 

21, 

22, 

23, 

24, 

\— 1 
CO 

32, 

33, 

34 }; 


The same rules about incomplete initialization lists apply to multi-dimensional arrays. The following 
example defines a mathematical 3-by-3 identity matrix: 

int Identity[3][3] = { { 1 }, 

{ 0 , 1 }, 

{ 0 , 0 , 1 } }; 


The missing values are replaced with zeroes. The initialization also could have been given as, 

int Identity[3][3] = { { 1, 0, 0 }, 

{ 0 , 1 , 0 }, 

{ 0 , 0 , 1 } }; 
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or as, 


int Identity[3][3] = { 1, 

0 , 

0 , 

0 , 

1, 

0 , 

0 , 

0 , 

i 1; 


9.3 Initialization of Structures 

Structures may be initialized in a manner similar to arrays. The initializer list must be specified within 
braces. 

For example, 

struct printformat { 
int pagewid; 

char carr_ ctl; 

char * buffer; 

} ; 


char PrBuffer[256]; 

struct printformat PrtFmt = { 80, ' ', PrBuffer }; 

Each value from the initializer list is assigned to each successive member of the structure. Any unnamed 
gaps between members or at the end of the structure (caused by alignment) are ignored during initialization. 
If there are more members of the structure than values specified by the initializer list, then the remaining 
members are initialized to zero (for arithmetic types) or the null pointer constant (for pointers). 

If a structure member is itself an array, structure or union, then the sub-members may be initialized using a 
brace-enclosed initializer list. If braces are not specified, then for the purposes of initialization, the 
sub-members are treated as if they are members of the outer structure, as each subsequent initializer value 
initializes a sub-member, until no more sub-members are found, in which case the next member of the outer 
structure is initialized. 


9.4 Initialization of Unions 


Initializations of unions is the same as for structures, except that only the first member of the union may be 
initialized, using a brace-enclosed initializer. 

Consider the following example: 

struct first3 { 

char first, second, third; 

} ; 


union ustr { 
char 

struct first3 

} ; 

union ustr Str = { 


string[20]; 
firstthree; 

"Hello there" }; 


Initialization of Unions 
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The object Str is declared to be a union of two types, the first of which is an array of 20 characters, and 
the second of which is a structure that allows direct access to the first three characters of the string 
contained in the array. The array is initialized to the string "Hello there". The three characters of 
struct f irst3 will have the characters ' H' , ' e ' and ' 1' . Had the declaration of ustr been, 

union ustr { 

struct first3 firstthree; 
char string[20]; 

} ; 

then the initialization could only set the first three characters. 


9.5 Uninitialized Objects 

An object with static storage duration, and no explicit initialization, will be initialized as if every member 
that has arithmetic type was assigned zero and every member that has a pointer type was assigned a null 
(zero) pointer. 

An object with automatic storage duration, and no explicit initialization, is not initialized. Hence, a 
reference to such an automatic object that has not been assigned a value will yield undefined behavior. On 
most systems, the value of the object will be arbitrary and unpredictable. 
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An expression is a sequence of operators and operands that describes how to, 

• calculate a value (eg. addition) 

• create side-effects (eg. assignment, increment) 

or both. 

The order of execution of the expression is usually determined by a mixture of, 

1. parentheses (), which indicate to the compiler the desired grouping of operations, 

2. the precedence of operators, which describes the relative priority of operators in the absence of 
parentheses, 

3. the common algebraic ordering, 

4. the associativity of operators. 

In most other cases, the order of execution is determined by the compiler and may not be relied upon. 
Exceptions to this rule are described in the relevant section. Most users will find that the order of execution 
is well-defined and intuitive. However, when in doubt, use parentheses. 

The table below summarizes the levels of precedence in expressions. 

Operations at a higher level in the table will occur before those below. All operators involving more than 
one operand associate from left to right, except for the conditional and assignment operators, which 
associate from right to left. Operations at the same level, except where discussed in the relevant section, 
may be executed in any order that the compiler chooses (subject to the usual algebraic rules). In particular, 
the compiler may regroup sub-expressions that are both associative and commutative in order to improve 
the efficiency of the code, provided the meaning (i.e. types and results) of the operands and result are not 
affected by the regrouping. 

The order of any side-effects (for example, assignment, or action taken by a function call) is also subject to 
alteration by the compiler. 

An exception occurs when the operands for an operator are invalid. For example, division by zero may 
cause an exception. If an exception occurs, the behavior is undefined. If an exception is a possibility, the 
program should be prepared to handle it. 

In the following sections, a formal syntax is used to describe each level in the precedence table. This 
syntax is used in order to completely describe the relationships between the various levels. 
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Expression Type 

Operators 

primary 

identifier constant 

string (expression) 

postfix 

a[b] f() 

a.b a->b a++ a— 

unary 

sizeof u sizeof( a ) 

++a —a &a *a 

+a -a ~a !a 

cast 

(type) a 

multiplicative 

a * b a/b a%b 

additive 

a + b a - b 

shift 

a << b a >> b 

relational 

a<b a>b a <= b a >= b 

equality 

a == b a != b 

bitwise AND 

a & b 

bitwise exclusive OR 

a A b 

bitwise inclusive OR 

a | b 

logical AND 

a & & b 

logical OR 

a | | b 

conditional f 

a ? b : c 

assignment f 

a = b a += b a -= b a *= b 
a /= b a %= b a &= b a A = b 
a |= b a <<= b a >>= b 

comma 

a, b 


f associates from right to left 


10.1 Lvalues 

In order to understand certain components of expressions, it is important to understand the term lvalue. 

An lvalue is an expression that designates an object. The simplest form of lvalue is an identifier which is 
an object (for example, an integer). 
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The type of the expression may not be void or a function. The term lvalue is derived from /eft value, 
which refers to the fact that an lvalue is typically on the left side of an assignment expression. 

If ptr is a pointer to a type other than void or a function, then both ptr and *ptr are lvalues. 

A modifiable lvalue is an lvalue whose type is not an array or an incomplete type, whose declaration does 
not contain the keyword const, and, if it is a structure or union, then none of its members contains the 
keyword const. 

10.2 Primary Expressions 

primary-expression: 

identifier 

or 

constant 

or 

string-literal 

or 

(expression ) 

A primary expression is the simplest part of an expression. It consists of one of the following: 

identifier An identifier that designates a function is called a function designator. An identifier that 
designates an object is an lvalue. 

constant A constant is a primary expression whose type depends on its form. See "Constants". 

string-literal A string literal is a primary expression whose type is "array of char". A string literal is 
also an lvalue (but is not modifiable). 

expression inside parentheses 

The type and value of a parenthesized expression are the same as for the expression without 
parentheses. It may be an lvalue, function designator or void expression. 

Given these declarations. 


int 

count; 

int * 

ctrptr; 

int 

f( int ); 

int 

g( int ); 


the following are all valid primary expressions: 

count 

3 

3.2 

'a' 

"Hello there" 

(count + 3) 

(*(ctrptr+1)) 

<f< ++i ) * g( j++ )) 
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10.3 Postfix Operators 

postfix-expression: 
primary-expression 

or 

array-subscripting-expression 

or 

function-call-expression 

or 

member-designator-expression 

or 

post-increment-expression 

or 

post-decrement-expression 

10.3.1 Array Subscripting 

array-subscripting-expression: 
postfix-expression [expression ] 

The general form for array subscripting is, 

array[index] 

where array must have the type "array of type" or "pointer to type", and index must have an integral 
type. The result has type "type". 

array [index] is equivalent to (* (array+index) ),orthe index-th element of the array array, 
where the first element is numbered zero. Note that index is scaled automatically to account for the size 
of the elements of array. 

An alternate form for array subscripting is, 
index[array] 

although this form is not commonly used. 

10.3.2 Function Calls 


function-call-expression: 
postfix-expression () 

or 

postfix-expression ( argument-expression-list) 
argument-expression-list: 

one or more assignment-expressions separated by commas 

A postfix-expression followed by parentheses containing zero or more comma-separated expressions is a 
function-call-expression. The postfix-expression denotes the function to be called, and must evaluate to a 
pointer to a function. The simplest form of this expression is an identifier which is the name of a function. 
For example, Fn () calls the function Fn . 
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The expressions within the parentheses denote the arguments to the function. If a function prototype has 
been declared, then the number of arguments must match the parameter list in the prototype, and the 
arguments are converted to the types specified in the prototype. 

If the postfix-expression is simply an identifier, and no function prototype declaration for that identifier is 
in scope, then an implicit, 

extern int identifier () ; 

declaration is placed in the innermost block containing the function call. This declares the function as 
having external linkage, no information about its parameters is available, and the function returns an 
integer. 

The expressions are evaluated (in an undefined order) and the values assigned to the parameters for the 
function. All arguments are passed by value, allowing the function to modify its parameters without 
affecting the arguments used to create the parameters. However, an argument can be a pointer to an object, 
in which case the function may modify the object to which the pointer points. 

If a function prototype is in scope at both a call to a function and its definition ( and if the prototypes are the 
same), then the compiler will ensure that the required number and type of parameters are present. 

If no function prototype is in scope at a call to a function, then the default argument promotions are 
performed. (Integral types such as char and short int are converted to int, while float values are 
converted to double.) When the function definition is encountered, if the parameter types do not match 
the default argument promotions, then the behavior is undefined. (Usually, the parameters to the function 
will receive incorrect values.) 

If a function prototype has been declared at a call to a function, then each argument is converted, as if by 
assignment, to the type of the corresponding parameter. When the function definition is encountered, if the 
types of the parameters do not match the types of the parameters in the function prototype, the behavior is 
undefined. 

If the ellipsis (,...) notation is used in a function prototype, then those arguments in a function call that 
correspond to the ellipsis have only the default argument promotions performed on them. (See the chapter 
"Functions" for a complete description of the ellipsis notation.) 

Function calls may be recursive. Functions may call themselves either directly, or via other functions. 

The following are some examples of function calls: 

putchar( 'x' ); 

chr = getchar(); 

valid = isdigit( chr ) ; 

printf( "chr = %c, valid = %2x\n", chr, valid ); 
fnptr = &MyFunction; 

(*fnptr)( parml, parm2 ); 
fnptr( parml, parm2 ); 

10.3.3 Structure and Union Members 
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member-designator-expression: 
postfix-expression . identifier 

or 

postfix-expression - > identifier 

The first operand of the . operator must be an object with a structure or union type. The second operand 
must be the name of a member of that type. The result is the value of the member, and is an lvalue if the 
first operand is also an lvalue. 

The first operand of the -> operator must be a pointer to an object with a structure or union type. The 
second operand must be the name of a member of that type. The result is the value of the member of the 
structure or union to which the first expression points, and is an lvalue. 

10.3.4 Post-Increment and Post-Decrement 


post-increment-expression: 
postfix-expression ++ 

post-decrement-expression: 
postfix-expression — 

The operand of post-increment and post-decrement must be a modifiable lvalue, and a scalar (not a 
structure, union or array). 

The effect of the operation is that the operand is incremented or decremented by 1, adjusted for the type of 
the operand. For example, if the operand is declared to be a "pointer to type", then the increment or 
decrement will be by the value sizeof ( type ). 

The result of both post-increment and post-decrement (if it is just a subexpression of a larger expression) is 
the original, unmodified value of the operand. In other words, the original value of the operand is used in 
the expression, and then it is incremented or decremented. Whether the operand is incremented 
immediately after use or after completion of execution of the expression is undefined. Consider the 
statements, 

int i = 2; 
int j; 

j = (i++) + (i++); 

Depending on the compiler, j may get the value 4 or 5. If the increments are delayed until after the 
expression is evaluated, j gets the value 2 + 2 . If the increment of i happens immediately after its 
value is retrieved, then j gets the value 2 + 3 . 

To avoid ambiguity, the above expression could be written as: 

j = i + i; 
i += 2 ; 
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10.4 Unary Operators 

unary-expression: 

postfix-expression 

or 

pre-increment-expression 

or 

pre-decrement-expression 

or 

unary-operator cast-expression 

or 

sizeof-expression 

unary-operator: one of 
& * + - ~ ! 

10.4.1 Pre-Increment and Pre-Decrement Operators 

pre-increment-expression: 

++ unary-expression 

pre-decrement-expression: 

— unary-expression 

The operand of the pre-increment and pre-decrement operators must be a modifiable lvalue, and a scalar 
(not a structure, union or array). 

The operand is incremented or decremented by 1, adjusted for the type of the operand. For example, if the 
operand is declared to be a "pointer to type", then the increment or decrement will be by the value 
sizeof ( type ) . 

The expression++obj is equivalent to (obj += 1), while—ob j is equivalent to (obj -= 1) . 

10.4.2 Address-of and Indirection Operators 

unary-expression: 

& cast-expression 

or 

* cast-expression 

The unary & symbol denotes the address-of operator. Its operand must designate a function or an array, or 
be an lvalue that designates an object that is not a bit-field and is not declared with the register 
storage-class specifier. If the type of the operand is "type", then the type of the result is "pointer to type" 
and the result is the address of the operand. 

If the type of the operand is "array of type", then the type of the result is "pointer to type" and the result is 
the address of the first element of the array. 

The * symbol, in its unary form, denotes the indirection or pointer operator. Its operand must be a pointer 
type, except that it may not be a pointer to void. If the operand is a "pointer to type", then the type of the 
result is "type", and the result is the object to which the operand points. 
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No checking is performed to ensure that the value of the pointer is valid. If an invalid pointer value is used, 
the behavior of * is undefined. 


Examples: 


int 

counter; 

int * 

ctrptr; 

void 

(*fnptr)( int 

ctrpt 

r = Scounter; 


*ctrptr = 3; 

fnptr = FnRetVoid; 

fnptr( *ctrptr, Scounter ) ; 

10.4.3 Unary Arithmetic Operators 


unary-expression: 

+ cast-expression 

or 

- cast-expression 

or 

~ cast-expression 

or 

! cast-expression 

The + symbol, in its unary form, simply returns the value of its operand. The type of its operand must be 
an arithmetic type (character, integer or floating-point). Integral promotion is performed on the operand, 
and the result has the promoted type. 

The - symbol, in its unary form, is the negation or negative operator. The type of its operand must be an 
arithmetic type (character, integer or floating-point). The result is the negative of the operand. Integral 
promotion is performed on the operand, and the result has the promoted type. The expression -ob j is 
equivalent to (0-ob j ) . 

The ~ symbol is the bitwise complement, 1 ’s complement or bitwise not operator. The type of the operand 
must be an integral type, and integral promotion is performed on the operand. The type of the result is the 
type of the promoted operand. Each bit of the result is the complement of the corresponding bit in the 
operand, effectively turning 0 bits to 1, and 1 bits to 0. 

The ! symbol is the logical not operator. Its operand must be a scalar type (not a structure, union or 
array). The result type is int. If the operand has the value zero, then the result value is 1. If the operand 
has some other value, then the result is 0. 

10.4.4 The sizeof Operator 
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sizeof-expression: 

sizeof unary-expression 

or 

sizeof ( type-name ) 

The sizeof operator gives the size (in bytes) of its operand. The operand may be an expression, or a type 
in parentheses. In either case, the type must not be a function, bit-field or incomplete type (such as void, 
or an array that has not had its length declared). 

Note that an expression operand to sizeof is not evaluated. The expression is examined to determine the 
result type, from which the size is determined. 

If the operand has a character type, then the result is 1. 

If the type is a structure or union, then the result is the total number of bytes in the structure or union, 
including any internal or trailing padding included by the compiler for alignment purposes. The size of a 
structure can be greater than the sum of the sizes of its members. 

If the type is an array, then the result is the total number of bytes in the array, unless the operand is a 
parameter in the function definition enclosing the current block, in which case the result is the size of a 
pointer. 

The type of the result of the sizeof operator is implementation-defined, but it is an unsigned integer type, 
and is represented by size_ t in the<stddef . h> header. 

For the Open Watcom C 16 and C 32 compilers, the macro size_ t isunsigned int. 


Example: 

struct s { 

struct s * next; 
int objl; 

int obj2; 

} ; 

static struct s * SAllocAndFill( const struct s * def_ s ) 
/*******************************************************/ 

{ 

struct s * sptr; 

sptr = malloc( sizeof( struct s ) ) ; 

if ( sptr != NULL ) { 

memcpy( sptr, def_ s, sizeof( struct s ) ); 

} 

return( sptr ); 

} 

The function SAllocAndFill receives a pointer to a struct s . It allocates such a structure, and 
copies the contents of the structure pointed to by def_ s into the allocated memory. A pointer to the 
allocated structure is returned. 

The library function malloc takes the number of bytes to allocate as a parameter and sizeof ( struct 
s ) provides that value. The library function memcpy also takes, as the third parameter, the number of 
bytes to copy and again sizeof ( struct s ) provides that value. 
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10.5 Cast Operator 

cast-expression: 

unary-expression 

or 

( type-name ) cast-expression 

When an expression is preceded by a type name in parentheses, the value of the expression is converted to 
the named type. This is called a cast. Both the type name and the operand type must be scalar (not a 
structure, union or array), unless the type name is void. If the type name is void, the operand type must 
be a complete type (not an array of unknown size, or a structure or union that has not yet been defined). 

A cast does not yield an lvalue. 

Pointers may be freely converted from "pointer to void" to any other pointer type without using an 
explicit cast operator. Pointers also may be converted from any pointer type to "pointer to void". 

A pointer may be converted to a pointer to another type. However, the pointer may be invalid if the 
resulting pointer is not properly aligned for the type. Converting a pointer to a pointer to a type with less 
strict alignment, and back again, will yield the same pointer. However, converting it to a pointer to a type 
with more strict alignment, and back again, may yield a different pointer. On many computers, where 
alignment is not required (but may improve performance), conversion of pointers may take place freely. 

With Open Watcom C 16 and C 32 , alignment of integers, pointers and floating-point numbers is 
not required, so the compiler does not do any alignment. However, aligning these types may make 
a program run slightly faster. 

A command line switch may be used to force the compiler to do alignment on all structures. 

A pointer to a function may be converted to a pointer to a different type of function, and back again. The 
resulting pointer will be the same as the original pointer. 

If a pointer is converted to a pointer to a different type of function, and a call is made using that pointer, the 
behavior is undefined. 

A pointer may be converted to an integral type. The type of integer required to hold the value of the pointer 
is implementation-defined. If the integer is not large enough to fully contain the value, then the behavior is 
undefined. 

An integer may be converted to a pointer. The result is implementation-defined. 

With Open Watcom C 16 , for the purposes of conversion between pointers and integers,_near 

pointers are treated as unsigned int._far and_ _ huge pointers are treated aansigned 

long int, with the pointer’s segment value in the high-order (most significant) two bytes. All 
the usual integer conversion rules then apply. Note that huge pointers are not normalized in any 
way. 
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With Open Watcom C 32 , for the purposes of conversion between pointers and integers,_near 

pointers are treated as unsigned int._farl6 and_ Segl6 pointers are also treated as 

unsigned int, with the pointer’s segment value in the high-order (most significant) two bytes. 

All the usual integer conversion rules then apply. Note that_far pointers may not be con vetted 

to an integer without losing the segment information. 


10.6 Multiplicative Operators 

mul tipi icative-expression: 
cast-expression 

or 

multiplicative-expression * cast-expression 

or 

multiplicative-expression / cast-expression 

or 

multiplicative-expression % cast-expression 

The * symbol, in its binary form, yields the product of its operands. The operands must have arithmetic 
type, and have the usual arithmetic conversions performed on them. 

The / symbol yields the quotient from the division of the first operand by the second operand. The 
operands must have arithmetic type, and have the usual arithmetic conversions performed on them. Note 
that when a division by zero occurs, the behavior is undefined. 

When both operands of / are of integer type and positive value, and the division is inexact, the result is the 
largest integer less than the algebraic (exact) quotient. (The result is rounded down.) 

When one or both operands of / is negative and the division is inexact, whether the compiler rounds the 
value up or down is implementation-defined. 

The Open Watcom C 16 and C 32 compilers always round the result of integer division toward 
zero. This action is also called truncation. 


The % symbol yields the remainder from the division of the first operand by the second operand. The 
operands of % must have integral type. 

When both operands of % are positive, the result is a positive value smaller than the second operand. When 
one or both operands is negative, whether the result is positive or negative is implementation-defined. 

With the Open Watcom C 16 and C 32 compiler, the remainder has the same sign as the first 
operand. 

For integral types a and b, if b is not zero, then (a/b) *b + a%b will equal a. 


Multiplicative Operators 


83 







Language Reference 


10.7Additive Operators 

additive-expression: 

multiplicative-expression 

or 

additive-expression + multiplicative-expression 

or 

additive-expression - multiplicative-expression 
The + symbol, in its binary form, denotes the sum of its operands. 

If both operands have arithmetic type, then the usual arithmetic conversions are performed on them. 

If one of the operands is a pointer, then the other operand must have an integral type. The pointer operand 
may not be a pointer to void. Before being added to the pointer value, the integral value is multiplied by 
the size of the object to which the pointer points. The result type is the same as the pointer operand type. If 
the pointer value is a pointer to a member of an array, then the resulting pointer will point to a member of 
the same array, provided the array is large enough. If the resulting pointer does not point to a member of 
the array, then its use with the unary * (indirection) or -> (arrow) operator will yield undefined behavior. 

The - symbol, in its binary form, denotes the difference resulting from the subtraction of the second 
operand from the first. If both operands have arithmetic type, then the usual arithmetic conversions are 
performed on them. 

If the first operand is a pointer, then the second operand must either be a pointer to the same type or an 
integral type. 

In the same manner as for adding a pointer and an integral value, the integral value is multiplied by the size 
of the object to which the pointer points. The pointer operand may not be a pointer to void. The result 
type is the same type as the pointer operand. 

If both operands are pointers to the same type, the difference is divided by the size of the type, representing 
the difference of the subscripts of the two array members (assuming the type is "array of type"). The type 
of the result is implementation-defined, and is represented by ptrdif f_ t (a signed integral type) defined 
in the <stddef . h> header. 


With Open Watcom C 16 and C 32 , ptrdif f_ t isint, unless the huge memory model is being 
used, in which case ptrdif f_ t islong int. 


10.8 Bitwise Shift Operators 

shift-expression: 

additive-expression 

or 

shift-expression « additive-expression 

or 

shift-expression » additive-expression 

The << symbol denotes the left-shift operator. Both operands must have an integral type, and the integral 
promotions are performed on them. The type of the result is the type of the promoted left operand. 
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The result of op << amt is op left-shifted amt bit positions. Zero bits are filled on the right. 

Effectively, the high bits shifted out of op are discarded, and the resulting set of bits is re-interpreted as the 
result. Another interpretation is that op is multiplied by 2 raised to the power amt. 

The >> symbol denotes the right-shift operator. Both operands must have an integral type, and the integral 
promotions are performed on them. The type of the result is the type of the promoted left operand. 

The result of op >> amt is op right-shifted amt bit positions. If op has an unsigned type, or a signed 
type and a non-negative value, then op is divided by 2 raised to the power amt. Effectively, the low bits 
shifted out of op are discarded, zero bits are filled on the left, and the resulting set of bits is re-interpreted 
as the result. 

If op has a signed type and negative value, then the behavior of op >> amt is implementation-defined. 
Usually, the high bits vacated by the right shift are filled with the sign bit from before the shift (arithmetic 
right shift), or with 0 (logical right shift). 

With Open Watcom C 16 and C 32 , a right shift of a negative value of a signed type causes the sign 
bit to be propogated throughout the bits vacated by the shift. Essentially, the vacated bits are filled 
with 1 bits. 


For both bitwise shift operators, if the number of bits to shift exceeds the number of bits in the type, the 
result is undefined. 


10.9 Relational Operators 

relational-expression: 

shift-expression 

or 

relational-expression < shift-expression 

or 

relational-expression > shift-expression 

or 

relational-expression <= shift-expression 

or 

relational-expression >= shift-expression 

Each of the symbols < (less than), > (greater than), <= (less than or equal to), >= (greater than or equal 
to), yields the value 1 if the relation is true, and 0 if the relation is false. The result type is int. 

If both operands have arithmetic type, then the usual arithmetic conversions are performed on them. 

If one of the operands is a pointer, then the other operand must be a pointer to a compatible type. The 
result depends on where (in the address space of the computer) the pointers actually point. 

If both pointers point to members of the same array object, then the pointer that points to the member with a 
higher subscript will be greater than the other pointer. 

If both pointers point to different members within the same structure, then the pointer pointing to the 
member declared later in the structure will be greater than the other pointer. 

If both pointers point to the same union object, then they will be equal. 
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All other comparisons yield undefined behavior. As discussed above, the relationship between pointers is 
determined by the locations in the machine storage that the pointers reference. Typically, the numeric 
values of the pointer operands are compared. 

10.10 Equality Operators 

equality-expression: 

relational-expression 

or 

equality-expression == relational-expression 

or 

equality-expression ! = relational-expression 

The symbols == (equal to) and ! = (not equal to) yield the value 1 if the relation is true, and 0 if the relation 
is false. The result type is int. 

If both operands have arithmetic type, then the usual arithmetic conversions are performed on them. 

If both operands are pointers to the same type and they compare equal, then they are pointers to the same 
object. 

If both operands are pointers and one is a pointer to void, then the other is converted to a pointer to void. 
If one of the operands is a pointer, the other may be a null pointer constant (zero). 

No other combinations are valid. 


10.11 Bitwise AND Operator 

and-expression: 

equality-expression 

or 

and-expression & equality-expression 

The & symbol, in its binary form, denotes the bitwise AND operator. Each of the operands must have 
integral type, and the usual arithmetic conversions are performed. 

The result is the bitwise AND of the two operands. That is, the bit in the result is set if and only if each of 
the corresponding bits in the operands are set. 

The following table illustrates some bitwise AND operations: 


Operation 

Result 

0x0000 & 0x7A4C 
OxFFFF & 0x7A4C 
0x1001 & 0x0001 

0x29F4 & 0xE372 

0x0000 

0x7A4C 

0x0001 

0x2170 
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10.12 Bitwise Exclusive OR Operator 

exclusive-or-expression: 

and-expressiort 

or 

exclusive-or-expression A mid-expression 

The A symbol denotes the bitwise exclusive OR operator. Each of the operands must have integral type, and 
the usual arithmetic conversions are performed. 

The result is the bitwise exclusive OR of the two operands. That is, the bit in the result is set if and only if 
exactly one of the corresponding bits in the operands is set. 

Another interpretation is that, if one of the operands is treated as a mask, then every 1 bit in the mask 
causes the corresponding bit in the other operand to be complemented (0 becomes 1, 1 becomes 0) before 
being placed in the result, while every 0 bit in the mask causes the corresponding bit in the other operand to 
be placed unchanged in the result. 

The following table illustrates some exclusive OR operations: 


Operation 

Result 

0x0000 A 0x7A4C 

0x7A4C 

OxFFFF A 0x7A4C 

0x85B3 

OxFFFF A 0x85B3 

0x7A4C 

0x1001 A 0x0001 

0x1000 

0x29F4 A 0xE372 

0xCA8 6 


10.13 Bitwise Inclusive OR Operator 

inclusive-or-expression: 

exclusive-or-expression 

or 

inclusive-or-expression \ exclusive-or-expression 

The | symbol denotes the bitwise inclusive OR operator. Each of the operands must have integral type, and 
the usual arithmetic conversions are performed. 

The result is the bitwise inclusive OR of the two operands. That is, the bit in the result is set if at least one 
of the corresponding bits in the operands is set. 

The following table illustrates some inclusive OR operations: 
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Operation 

Result 

0x0000 

0x7A4C 

0x7A4C 

OxFFFF 

0x7A4C 

OxFFFF 

0x1100 

0x0022 

0x1122 

0x2 9F4 

0xE372 

0xEBF6 


10.14 Logical AND Operator 

logical-and-expression: 

inclusive-or-expression 

or 

logical-and-expression && inclusive-or-expression 

The && symbol denotes the logical AND operator. Each of the operands must have scalar type. 

If both of the operands are not equal to zero, then the result is 1. Otherwise, the result is zero. The result 
type is int. 

If the first operand is zero, then the second operand is not evaluated. Any side effects that would have 
happened if the second operand had been executed do not happen. Any function calls encountered in the 
second operand do not take place. 

10.15 Logical OR Operator 

logical-or-expression: 

logical-and-expression 

or 

logical-or-expression \ \ logical-and-expression 

The | | symbol denotes the logical OR operator. Each of the operands must have scalar type. 

If one or both of the operands is not equal to zero, then the result is 1. Otherwise, the result is zero (both 
operands are zero). The result type is int. 

If the first operand is not zero, then the second operand is not evaluated. Any side effects that would have 
happened if the second operand had been executed do not happen. Any function calls encountered in the 
second operand do not take place. 

10.16 Conditional Operator 

conditional-expression: 

logical-or-expression 

or 

logical-or-expression ? expression : conditional-expression 
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The ? symbol separates the first two parts of a conditional operator, and the : symbol separates the 
second and third parts. The first operand must have a scalar type (not a structure, union or array). 

The first operand is evaluated. If its value is not equal to zero, then the second operand is evaluated and its 
value is the result. Otherwise, the third operand is evaluated and its value is the result. 

Whichever operand is evaluated, the other is not evaluated. Any side effects that might have happened 
during the evaluation of the other operand do not happen. 

If both the second and third operands have arithmetic type, then the usual arithmetic conversions are 
performed on them, and the type of the result is the same type as the converted operands. 

If both operands have the same structure, union or pointer type, then the result has that type. 

If both operands are pointers, and one is "pointer to void", then the result type is "pointer to void". 

If one operand is a pointer, and the other is a null pointer constant (0), the result type is that of the pointer. 

If both operands are void expressions, then the result is a void expression. 

No other combinations of result types are permitted. 

Note that, unlike most other operators, the conditional operator associates from right to left. For example, 
the expression, 

a = b?c : d?e : f; 
is translated as if it had been parenthesized as follows: 

a=b?c: (d?e:f); 

This construct is confusing, and so should probably be avoided. 

10.17 Assignment Operators 

assignment-expression: 

conditional-expression 

or 

simple-assignment-expression 

or 

compound-assignment-expression 

An assignment operator stores a value in the object designated by the left operand. The left operand must 
be a modifiable lvalue. 

The result type and value are those of the left operand after the assignment. 

Whether the left or right operand is evaluated first is undefined. 

Note that, unlike most other operators, the assignment operators associate from right to left. For example, 
the expression, 

a += b = c; 
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is translated as if it had been bracketed as follows: 
a += (b = c); 

10.17.1 Simple Assignment 

simple-assignment-operator: 

unary-expression = assignment-expression 

The = symbol denotes simple assignment. The value of the right operand is converted to the type of the left 
operand and replaces the value designated by the left operand. 

The two operands must obey one of the following rules, 

• both have arithmetic types, 

• both have the same structure or union type, or the right operand differs only in the presence of the 
const or volatile keywords, 

• both are pointers to the same type, 

• both are pointers and one is a pointer to void, 

• the left operand is a pointer, and the right is a null pointer constant (0). 

10.17.2 Compound Assignment 

compound-assignment-expression: 
unary-expression assignment-operator assignment-expression 

assignment-operator: one of 

*= /= %= 

<<= »= 


A compound assignment operator of the form a op= b is equivalent to the simple assignment expression 
a = a op (b), except that the left operand a is evaluated only once. 

The compound assignment operator must have operands consistent with those allowed by the 
corresponding binary operator. 

10.18 Comma Operator 

expression: 

assignment-expression 

or 

expression, assignment-expression 
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At the lowest precedence, the comma operator evaluates the left operand as a void expression (it is 
evaluated and its result, if any, is discarded), and then evaluates the right operand. The result has the type 
and value of the second operand. 

In contexts where the comma is also used as a separator (function argument lists and initializer lists), a 
comma expression must be placed in parentheses. 

For example, 

Fn ( (pi=3.14159, two_ pi=2*pi) ); 

the function Fn has one parameter, which has the value 2 times pi. 

for ( i = 0, j = 0, k = 0;; i++, j++, k++ ) 

statement; 

The for statement allows three expressions. In this example, the first expression initializes three objects 
and the third expression increments the three objects. 

10.19 Constant Expressions 

A constant expression may be specified in several places: 

• the size of a bit-field member of a structure, 

• the value of an enumeration constant, 

• an initializer list, 

• the number of elements in an array, 

• the value of a case label constant, 

• with the #if and #elif preprocessor directives. 

In most cases, a constant expression consists of a series of constant values and operations that evaluate to a 
constant value. Certain operations may only appear within the operand of the sizeof operator. These 
include: 

• a function call, 

• pre- or post-increment or decrement, 

• assignment, 

• comma operator, 

• array subscripting, 

• the . and, -> operators (structure member access), 

• the unary & (address-of) operator (see exception below), 

• the unary * (indirection) operator, 

• casts to a type other than an integer type. 

In a constant expression that is an initializer, floating-point constants and casts may be specified. Objects 
that have static storage duration, and function designators (names), may be used to provide addresses, either 
explicitly using the unary & (address-of) operator, or implicitly by specifying the identifier only. 

The following examples illustrate constant expressions that may be used anywhere: 

3 

256*3 + 27 

OPSYS == OS_ DOS /* These are macro names */ 


Constant Expressions 91 




Language Reference 


The next set of examples are constant expressions that are only valid in an initializer: 

&SomeObject 
SomeFunction 
3.5 * 7.2 / 6.5 

In a constant expression that is part of a #if or #elif preprocessor directive, only integral constants and 
operators are permitted (and macros that, when replaced, follow these same rules). 
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A statement describes what actions are to be performed. Statements may only be placed inside functions. 
Statements are executed in sequence, except where described below. 


11.1 Labelled Statements 


Any statement may be preceded by a label. Labelled statements are usually the target of a goto statement, 
and hence occur infrequently. 

A label is an identifier followed by a colon. Labels do not affect the flow of execution of a program. A 
label that is encountered during execution is ignored. 

The following example illustrates a statement with a label: 

xyz: i = 0; 

Labels can only precede statements. It follows that labels may only appear inside functions. 

A label may be defined only once within any particular function. 

The identifier used for a label may be the same as another identifier for an object, function or tag, or a label 
in another function. The name space for labels is separate from non-label identifiers, and each function has 
its own label name space. 

11.2 Compound Statements 

A compound statement is a set of statements grouped together inside braces. It may have its own 
declarations of objects, with or without initializations, and may or may not have any executable statements. 
A compound statement is also called a block. 

The general form of a compound statement is: 

{ declaration-list statement-list } 

where declaration-list is a list of zero or more declarations of objects to be used in the block, statement-list 
is a list of zero or more statements to be executed when the block is entered. 

Any declarations for objects that have automatic storage duration and initializers for them are evaluated in 
the order in which they occur. 

An object declared with the keyword extern inside a block may not be initialized in the declaration, since 
the storage for that object is defined elsewhere. 

An object declared in a block, without the keyword extern, may not be redeclared within the same block, 
except in a block contained within the current block. 
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11.3 Expression Statements 

A statement that is an expression is evaluated as a void expression for its side effects, such as the assigning 
of a value with the assignment operator. The result of the expression is discarded. This discarding may be 
made explicit by casting the expression as a void. 

For example, the statement, 

count = 3; 

consists of the expression count = 3, which has the side effect of assigning the value 3 to the object 
count. The result of the expression is 3, with the type the same as the type of count. The result is not 
used any further. As another example, the statement, 

(void) memcpy( dest, src, len ); 

indicates that, regardless of the fact that memcpy returns a result, the result should be ignored. However, it 
is equally valid, and quite common, to write, 

memcpy( dest, src, len ); 

As a matter of programming style, casting an expression as void should only be done when the result of 
the expression might normally be expected to be used further. In this case, casting to void indicates that 
the result was intentionally discarded and is not an error of omission. 


11.4 Null Statements 


A null statement, which is just a semi-colon, takes no action. It is useful for placing a label just before a 
block-closing brace, or for indicating an empty block, such as in an iteration statement. Consider the 
following examples of null statements: 

{ 

gets( buffer ) ; 

while( *buffer++ != '\0' ) 

/* ... */ 
endblk: ; 

} 

The while iteration statement skips over characters in buffer until the null character is found. The 
body of the iteration is empty, since the controlling expression does all of the work. The endblk : 
declares a label just before the final }, which might be used by a goto to exit the block. 


11.5 Selection Statements 


A selection statement evaluates an expression, called the controlling expression, then based on the result 
selects from a set of statements. These statements are then executed. 
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11.5.1 The if Statement 


if ( expression ) statement 

or 

if ( expression ) statement else statement 

In both cases, the type of the controlling expression (inside the parentheses) is a scalar type (not a structure, 
union or array). If the controlling expression evaluates to a non-zero value, then the first statement is 
executed. 

In the second form, the else is executed if the controlling expression evaluates to zero. 

Each statement may be a compound statement. For example, 

if( delay > 5 ) { 

printf( "Waited too long\n" ); 
ok = FALSE; 

} else { 

ok = TRUE; 

} 

In the classic case of the dangling else, the else is bound to the nearest if that does not yet have an 
else. For example, 

if( x > 0 ) 

if( y > 0 ) 

printf( "x > 0 && y > 0\n" ) ; 

else 

printf( "x <= 0\n" ) ; 

will print x <= 0 when x > 0 is true and y > 0 is false, because the else is bound to the second if, 
not the first. To correct this example, it would have to be changed to, 

if( x > 0 ) { 

if( y > 0 ) 

printf( "x > 0 && y > 0\n" ) ; 

} else 

printf( "x <= 0\n" ) ; 

This example illustrates why it is a good idea to always use braces to explicitly state the subject of the 
control structures, rather than relying on the fact that a single statement is also a compound statement. A 
better way of writing the above example is, 

if( x > 0 ) { 

if( y > o ) { 

printf( "x > 0 && y > 0\n" ) ; 

} 

} else { 

printf( "x <= 0\n" ) ; 

} 

where all subjects of the control structures are contained within braces, leaving no doubt about the 
meaning. A dangling else cannot occur if braces are always used. 
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If the statements between the if and the else are reached via a label, the statements following the else 
will not be executed. However, jumping into a block is poor programming practice, since it makes the 
program difficult to follow. 

11.5.2 The switch Statement 

switch ( expression ) statement 

Usually, statement is a compound statement or block. Embedded within the statement are case labels and 
possibly a default label, of the following form: 

case constant-expression : statement 
default : statement 

The controlling expression and the constant-expressions on each case label all must have integral type. 

No two of the case constant-expressions may be the same value. The default label may appear at most 
once in any switch block. 

The controlling statement is evaluated, and the integral promotion is performed on the result. If the 
promoted value of the expression matches any of the case labels promoted to the same type, control is given 
to the statement following that case label. Otherwise, control is given to the statement following the 
default label (if present). If no default label is present, then no statements in the switch block are 
executed. 

When statements within a switch block are being executed and another case or default is 
encountered, it is ignored and execution continues with the statement following the label. The break 
statement may be used to terminate execution of the switch block. 

In the following example, 

int i; 

for( i = 1; i <= 8; i++ ) { 

printf( "%d ", i ); 
switch( i ) { 

case 2: 
case 4: 

printf ( "less than 5 " ); 
case 6: 
case 8: 

printf ( "even\n" ); 
break; 
default: 

printf ( "odd\n" ); 

} 

} 
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the following output is produced: 

1 odd 

2 less than 5 even 

3 odd 

4 less than 5 even 

5 odd 

6 even 

7 odd 

8 even 


11.6 Iteration Statements 

Iteration statements control looping. There are three forms of iteration statements: while, do/while and 
for. 

The controlling expression must have a scalar type. The loop body (often a compound statement or block) 
is executed repeatedly until the controlling expression is equal to zero. 

11.6.1 The while Statement 

while ( expression ) statement 

The evaluation of the controlling expression takes place before each execution of the loop body ( statement ). 
If the expression evaluates to zero the first time, the loop body is not executed at all. 

The statement may be a compound statement. 

For example, 

char * ptr; 

/* ... */ 

while( *ptr != '\0' ) { 

if ( *ptr == )break; 

++ptr; 

} 

The loop will scan characters pointed at by pt r until either a null character or a dot is found. If the initial 
value of ptr points at a null character, then no part of the loop body will be executed, leaving ptr 
pointing at the null character. 

11.6.2 The do Statement 

do statement while ( expression ) ; 

The evaluation of the controlling expression takes place after each execution of the loop body ( statement ). 

If the expression evaluates to zero the first time, the loop body is executed exactly once. 

The statement may be a compound statement. 
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For example, 

char * ptr; 
char * endptr; 

/* ... */ 

endptr = ptr + strlen ( ptr ); 
do { 

—endptr; 

} while( endptr >= ptr && *endptr == ' ' 

In this example, the loop will terminate when endptr finds a non-blank character starting from the right, 
or when endptr goes past the beginning of the string. If a non-blank character is found, endptr will be 
left pointing at that character. 

11.6.3 The for Statement 

The statement, 

for ( exprl ; expr2; expr3 ) statement 
is almost equivalent to, 
exprl ; 

while ( expr2 ) { 

statement 

expr3 ; 

} 

The difference is that the continue statement will pass control to the statement expr3 rather than to the 
end of the loop body. 

exprl is an initialization expression and may be omitted. 

exprl is the controlling expression, and specifies an evaluation to be made before each iteration of the loop 
body. If the expression evaluates to zero, the loop body is not executed, and control is passed to the 
statement following the loop body. If exprl is omitted, then a non-zero (true) value is substituted in its 
place. In this case, the statements in the loop must cause an explicit break from the loop. 

exprl specifies an operation to be performed after each iteration. A common operation would be the 
incrementing of a counter. expr3 may be omitted. 

The statement may be a compound statement. 

For example, 

char charvec[256]; 
int count; 

for ( count = 0; count <= 255; count++ ) { 

charvec[count] = count; 

} 

This example will initialize the character array charvec to the values from 0 to 255. 
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The following are examples of for statements: 

for ( ;; ) 

statement; 

All statements in the body of the loop will be executed until a break or goto statement is executed which 
passes control outside of the loop, or a return statement is executed which exits the function. This is 
sometimes called loop forever. 

for ( i = 0; i <= 100; ++i ) 
statement; 

The object i is given the initial value zero, and after each iteration of the loop is incremented by one. The 
loop is executed 101 times, with i having the successive values 0, 1, 2 ... 99, 100, and having the 

value 101 after termination of the loop. 

for( ; *bufptr != ' \0'; ++bufptr ) 
statement; 

The object bufptr is already initialized, and the loop will continue until bufptr points at a null 
character. After each iteration of the loop, bufptr will be incremented to point at the next character. 

11.7 Jump Statements 

A jump statement causes execution to continue at a specific place in a program, without executing any 
other intervening statements. There are four jump statements: goto, continue, break and return. 

11.7.1 The goto Statement 

goto identifier; 

identifier is a label somewhere in the current function (including any block within the function). The next 
statement executed will be the one following that label. 

Note: it can be confusing to use the goto statement excessively. It is easy to create spaghetti code, which 
is very difficult to understand, even by the person who wrote it. It is recommended that the goto 
statement be used, at most, to jump out o/blocks, never into them. 

11.7.2 The continue Statement 

continue; 

A continue statement may only appear within a loop body, and causes a jump to the inner-most loop’s 
loop-continuation statement (the end of the loop body). 

In a while statement, the jump is effectively back to the while. 

In a do statement, the jump is effectively down to the while. 
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In a for statement, the jump is effectively to the closing brace of the compound-statement that is the 
subject of the for loop. The third expression in the for statement, which is often an increment or 
decrement, is then executed before control is returned to the top of the loop. 

11.7.3 The break Statement 

break; 

A break statement may only appear in an iteration (loop) body or a switch statement. 

In a loop, a break will cause execution to continue at the statement following the loop body. 

In a switch statement, a break will cause execution to continue at the statement following the switch. If 
the loop or switch that contains the break is enclosed inside another loop or switch, only the 
inner-most loop or switch is terminated. The goto statement may be used to terminate more than one 
loop or switch. 

11.7.4 The return Statement 

return; 

or 

return expression ; 

A popular variation of the second form is, 
return ( expression ) ; 

The return statement causes execution of the current function to be terminated, and control is passed to 
the caller. A function may contain any number of return statements. 

If the function is declared with a return type of void (no value is returned), then no return statement 
within that function may return a value. 

If the function is declared as having a return type of other than void, then any return statement with an 
expression will evaluate the expression and convert it to the return type. That value will be the value 
returned by the function. If a return is executed without an expression, and the caller uses the value 
returned by the function, the behavior is undefined since no value was returned. An arbitrary value will 
probably be used. 

Reaching the closing brace } that terminates the function is equivalent to executing a return statement 
without an expression. 
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There are two forms for defining a function. The first form is, 

storage-class return-type identifier ( parameter-type-list ) 

{ 

declaration-list 

statement-list 

} 

The storage-class may be one of extern or static. If storage-class is omitted, extern is assumed. 
The return-type may be any valid type except an array. If return-type is omitted, int is assumed. 

The identifier is the name of the function. 

The parameter-type-list is either void or empty, meaning the function takes no parameters, or a 
comma-separated list of declarations of the objects, including both type and parameter name (identifier). If 
multiple arguments of the same type are specified, the type of each argument must be given individually. 
The form, 

type idl, id2 

is not permitted within the parameter list. 

If the parameter-type-list ends with , . . . then the function will accept a variable number of arguments. 

Any parameter declared as "array of type" is changed to "pointer to type". Any parameter declared as " 
function" is changed to "pointer to function". 

The following examples illustrate several function definitions: 

int F( void ) 

The function F has no parameters, and returns an integer, 
void G( int x ) 

The function G has one parameter, an integer object named x, and does not return a value. 
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void * H( long int len, long int wid ) 

The function H has two parameters, long integer objects named len and wid, and returns a pointer 
which does not point to any particular type of object. 

void I( char * format, ... ) 

The function I has one known parameter, an object named format that is a pointer to a character 
(string). The function also accepts a variable number of parameters following format. The 
function does not return a result. 

This form of function definition also serves as a prototype declaration for any calls to the function that 
occur later in the same module. With the function prototype in scope at the time of a call to the function, 
the arguments are converted to the type of the corresponding parameter prior to the value being assigned. 

If a call to the function is to be made prior to its definition, or from another module, a function prototype 
should be specified for it in order to ensure proper conversion of argument types. Failure to do this will 
result in the default argument promotions being performed, with undefined behavior if the function 
parameter types do not match the promoted argument types. 

The second form of function definition is, 

storage-class return-type identifier ( identifier-list ) 
declaration-list 
{ 

declaration-list 

statement-list 

} 

The storage-class, return-type and identifier parts are all the same as for the first form of definition. In this 
form, the identifier-list is a (possibly empty) comma-separated list of identifiers (object names) without any 
type information. Following the closing parenthesis, and before the opening brace of the body of the 
function, the declarations for the objects are given, using the normal rules. Any object of type int need 
not be explicitly declared. 

In the declarations of the parameter identifiers, register is the only storage-class specifier that may be 
used. 

A function prototype is created from the definition after the default argument promotions have been 
performed on each parameter. All arguments to a function declared in this manner will have the default 
argument promotions performed on them. The resulting types must match the types of the declared 
parameters, after promotion. Otherwise, the behavior is undefined. 

Note that it is impossible to pass an object of type float to a function declared in this manner. The 
argument of type float will automatically be promoted to double, and the parameter will also be 
promoted to double (assuming that it was declared as float). For similar reasons, it is not possible to 
pass an object of type char or short int without promotion taking place. 

According to the ISO standard for the C language, this form of function definition is obsolete and should 
not be used. It is provided for historical reasons, in particular, for compatibility with older C compilers. 
Using the first form of function definition often allows the compiler to generate better code. 
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The following examples are the same as those given with the first form above, with the appropriate 
modifications: 

int F () 

The function F has no parameters, and returns an integer, 
void G( x ) 

The function G has one parameter, an integer object named x, and does not return a value. This 
example could have also been written as, 

void G( x ) 
int x; 

which explicitly declares x to be an integer. 

void * H( len, wid ) 
long int len; 
long int wid; 

The function H has two parameters, both integer objects named len and wid, and returns a pointer 
which does not point to any particular type of object. Any call to this function must ensure that the 
arguments are long integers, either by using an object so declared, or by explicitly casting the object 
to the type. 

The last example using the ellipsis (,...) notation is not directly representable using the second form of 
function definition. With most compilers it is possible to handle variable argument lists in this form, but 
knowledge of the mechanism used to pass arguments to functions is required, and this mechanism may vary 
between different compilers. 

12.1 The Body of the Function 

Following the declaration of the function and the opening brace is the body of the function. It consists of 
two portions, both of which are optional. 

The first portion is the declaration list for any objects needed within the function. These objects may have 
any type and any storage class. Objects with storage class register or auto have automatic storage 
duration, meaning they are created when the function is called, and destroyed when the function returns to 
the caller. (The value of the object is not preserved between calls to the function.) Objects with storage 
class extern or static have static storage duration, meaning they are created once, before the function 
is ever called, and destroyed only when the program terminates. Any value placed in such an object will 
remain even after the function has returned, so that the next time the function is called the value will still be 
present (unless some other action is taken to change it, such as using another object containing a pointer to 
the static object to modify the value). 

Unless an explicit return statement is executed, the function will not return to the caller until the brace at 
the end of the function definition is encountered. The return will be as if a return statement with no 
expression was executed. If the function is declared as returning a value, and the caller attempts to use the 
value returned in this manner, the behavior is undefined. The value used will be arbitrary. 

A function may call itself (recursion) directly, or it may call another function or functions which in turn call 
it. Any objects declared with automatic storage duration are created as a new instance of the object upon 
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each recursion, while objects declared with static storage duration only have one instance shared between 
the recursive instances of the function. 


12.2 Function Prototypes 

A function prototype is like a definition of a function, but without the body. A semi-colon is specified 
immediately following the closing right parenthesis of the function's declaration. The prototype describes 
the name of the function, the types of parameters it expects (names are optional) and the type of the return 
value. This information can be used by the C compiler to do proper argument type checking and 
conversion for calls to the function, and to properly handle the return value. 

If no function prototype has been found by the time a call to a function is made, all arguments have the 
default argument promotions performed on them, and the return type is assumed to be int. If the actual 
definition of the function does not have parameters that match the promoted types, the behavior is 
undefined. If the return type is not int and a return value is required, the behavior is undefined. 

The prototype for a function must match the function definition. Each parameter type and the type of the 
return value must be the same, otherwise the behavior is undefined. 

All library functions have prototypes in one of several header files. That header file should be included 
whenever a function described therein is used. Refer to the Open Watcom C Library Reference manual for 
details. 

12.2.1 Variable Argument Lists 

If the prototype (and definition) for a function has a parameter list that ends with , . . . then the function 
has a variable argument list or variable parameter list meaning that the number of arguments to the 
function can vary. (The library function print f is an example.) At least one argument must be provided 
before the variable portion. This argument usually describes, in some fashion, how many other arguments 
to expect. It may be a simple count, or may involve (as with printf) an encoding of the number and 
types of arguments. 

All arguments that correspond to a variable argument list have the default argument promotions performed 
on them, since it is not possible to determine, at compilation time, what types will be required by the 
function. 

Since the parameters represented by the , . . . don't have names, special handling is required. The C 
language provides a special type and three macros for handling variable argument lists. To be able to use 
these, the header <stdarg. h> must be included. 

The type va_ list is an implementation-specific type used to store information about the variable list. 
Within the function, an object must be declared with type va_ list. This object is used by the macros and 
functions for processing the list. 

The macro va_ start has the form, 

void va_ start ( va_ list parminfo 

r 

lastparm 

) ; 
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The object parminfo is set up by the macro with information describing the variable list. The argument 
lastparm is the name (identifier) of the last parameter before the , . . . and must not have been declared 
with the storage class register. 

The macro va_ start must be executed before any processing of the variable portion of the parameter list 
is performed. 

va_ start may be executed more than once, but only if an intervening va_ end is executed. 

The macro va_ arg has the form, 
type 

va_ arg( va_ list 
parminfo 

t 

type 

) ; 

parminfo is the same object named in the call to va_ start, type is the type of argument expected. The 
types expected should only be those that result from the default argument promotions (int, long int 
and long long int and their unsigned varieties, double and long double), and those that are not 
subject to promotion (pointers, structures and unions). The type must be determined by the program. The 
va_ arg macro expands to an expression that has the type and value of the next parameter in the variable 
list. 

In the case of print f, the parameter type expected is determined by the "conversion specifications" such 
as %s, %d and so on. 

The first invocation of the va_ arg macro (after executing ava_ start) returns the value of the 
parameter following lastparm (as specified in va_ start). Each subsequent invocation ofva_ arg 
returns the next parameter in the list. At each invocation, the value of parminfo is modified (in some 
implementation-specific manner) to reflect the processing of the parameter list. 

If the type of the next parameter does not match type, or if no parameter was specified, the behavior is 
undefined. 

The macro va_ end has the form, 

void va_ end ( va_ list parminfo 

) ; 

parminfo is the same object named in the corresponding call to va_ start. The functionva_ end closes 
off processing of the variable argument list, which must be done prior to returning from the function. If 
va_ end is not called before returning, the behavior is undefined. 

If va_ end is called without a corresponding call tova_ start having been done, the behavior is 
undefined. 

After calling va_ end and prior to returning, it is possible to callva_ start again and reprocess the 
variable list. It will be necessary to call va_ end again before returning. 

The following function takes an arbitrary number of floating-point numbers as parameters along with a 
count, and returns the average of the numbers: 
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♦include <stdarg.h> 

extern double Average( int count, ... ) 
/*************************************/ 

{ 

double sum = 0; 

int i; 

va_ list parminfo; 

if( count == 0 ) { 

return ( 0.0 ) ; 

} 

va_ start( parminfo, count ); 
for( i = 0; i < count; i++ ) { 

sum += va_ arg ( parminfo, double ); 

} 

va_ end ( parminfo ) ; 
return ( sum / count ); 

} 


12.3 The Parameters to the Function main 


The function main has a special meaning in C. It is the function that receives control when a program is 
started. The function main has the following definition: 

extern int main( int argc, char * argv[] ) 

{ 

statements 

} 

The objects argc and argv have the following properties: 

• argc is the "argument count", or the number of parameters (including program name) supplied to 
the program, and its value is greater than zero, 

• argv is an array of pointers to strings containing the parameters, 

• argv [ 0 ] is the program name, if available, otherwise it is a pointer to a string containing only the 
null character, 

• argv [argc] is a null pointer, representing the end of the argument list, 

• argv [ 1 ] through argv[argc-l] are pointers to strings representing the arguments to the 
program. These strings are modifiable by the program, and exist throughout the execution of the 
program. The strings will generally be in mixed (upper and lower) case, although a system that 
cannot provide mixed case argument strings will provide them in lower case. 

The translation of the arguments to the program, as provided by the operating system (often from the 
command-line used to invoke the program), into the strings contained in argv, is implementation-defined. 
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With Open Watcom C 16 and C 32 , each unquoted, blank-separated token on the command line is 
made into a string that is an element of argv. Quoted strings are maintained as one element 
without the quotes. 

For example, the command line, 

pgm 2+ 1 tokens "one token" 

will result in argc having the value 5, and the elements of argv being the strings "pgm", "2 + ", 
"1","tokens"and "one token". 

The function main may also be declared without any parameters, as, 

extern int main( void ) 

{ 

statements 

} 

The return value of main is an integer, usually representing a termination status. If no return value is 
specified (by using a return statement with no expression or encountering the closing brace in the 
function), then the value returned is undefined. 

The exit library function may be used to terminate the program at any point. The value of the argument 
to exit is returned as if main had returned the value. 
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The preprocessor , as its name suggests, is that part of the C compiler which processes certain directives 
embedded in the source file(s) in advance of the actual compilation of the program. Specifically, the 
preprocessor allows a source file to, 

• include other files (perhaps referencing externally-defined objects, or containing the definitions of 
structures or other types which are needed by more than one source file), 

• compile certain portions of the code depending on some condition ( such as the kind of computer for 
which the code is being generated), and, 

• replace macros with other text which is then compiled. 

The preprocessing phase occurs after trigraphs have been converted and physical lines ending with \ have 
been concatenated to create longer logical lines, but before escape sequences in character constants have 
been converted, or adjacent string literals are concatenated. 

Any line whose first non-blank character is a # marks the beginning of a preprocessing directive. Spaces 
may appear between the # and the identifier for the directive. The ((include and #def ine directives 
are each contained on one line (after concatenation of lines ending with \), while the conditional 
compilation directives span multiple lines. 

A preprocessor directive is not terminated by a semi-colon. 


13.1 The Null Directive 

A preprocessing directive of the form, 

# 

(with no other tokens on the same line) has no effect and is discarded. 

13.2 Including Headers and Source Files 

A directive of the form, 

♦include <name> 

will search a sequence of places defined by the implementation for the header identified by name . A 
header declares a set of library functions and any necessary types or macros needed for their use. Headers 
are usually provided by the compiler, or by a library provided for use with the compiler. 

name may not contain a > character. If the header is found, the entire directive is replaced by the contents 
of the header. If the header is not found, an error will occur. 
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A directive of the form, 

♦include "name" 

will search for the source file identified by name . name may not contain a " (double-quote) character. If 
the source file identified by name is found, then the entire directive is replaced by the contents of the file. 
Otherwise, the directive is processed as if the, 

♦include <name> 

form had been used. 

A third form of ♦include directive is also supported. A directive of the form, 

♦include tokens 

causes all macro substitutions (described below) to take place on tokens . After substitution, the 
directive must match either the <name> or "name" forms described above (including < and >, or quotes), 
in which case the ♦include is processed in the corresponding manner. 

See the User’s Guide for details about how the compiler searches for included files. 

♦ include directives may be nested. Each implementation may allow different depths of nesting, but all 
must allow at least 8 levels. (In other words, a source file may include another file, which includes another 
file, and so on, up to a depth of eight files.) 

The operating system may further limit the number of files that may be open at one time. See the 
appropriate operating system manual for details. 


13.3 Conditionally Including Source Lines 

A directive of the form, 

♦ if constant-expression 
body of# if 
♦endif 

evaluates the constant-expression, and if it evaluates to a non-zero value, then the body of the ♦if is 
processed by the preprocessor. Processing of the body ends when a corresponding ♦elif, ♦else, or the 
terminating ♦endif is encountered. 

The ♦if directive allows source and preprocessor lines to be conditionally processed by the compiler. 

If the constant-expression evaluates to zero, then the body of the ♦if is not processed, and the 
corresponding ♦elif or ♦else (if present) is processed. If neither of these directives are present, then 
the preprocessor skips to the ♦endif. Any preprocessing directives within the body of the ♦if are not 
processed, but they are examined in order to determine any nested directives, in order to find the matching 
♦ elif, ♦else or ♦endif. 

The constant-expression is of the same form as used in the i f statement, except that the values used must 
be integer values (including character constants). No cast or sizeof operators or enumeration constants 
may be used. Each identifier that is a macro name is replaced (as described below), and remaining 
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identifiers are replaced with OL. All values are converted to long integers using the usual arithmetic 
conversions. After each item has been converted, the evaluation of the expression takes place using the 
arithmetic of the translation environment. Any character constants are evaluated as members of the source 
character set. 


With Open Watcom C 16 and C 32 , character constants have the same value in both the source and 
execution character sets. 


The unary expression, 

defined identifier 

or 

defined! identifier ) 

may be used to determine if an identifier is currently defined as a macro. Any macro name that is part of 
this unary expression is not expanded. The above expressions evaluate to 1 if the named identifier is 
currently a macro, otherwise they evaluate to 0. 

As discussed above, if the constant-expression of the #if evaluates to zero, the preprocessor looks for a 
corresponding #elif. This directive means "else if", and has a similar form as #if: 

#elif constant-expression 
body o/#elif 

An #elif may only be placed inside the body of an #if. The body of the #elif is processed only if the 
constant-expression evaluates to a non-zero value and the constant-expressions of the corresponding #if 
and (preceding) #elif statements evaluated to zero. Otherwise the body is not processed, and the 
preprocessor skips to the next corresponding #elif or #else, or to the #endif if neither of these 
directives is present. 

The #else directive has the form, 

#else 

body of #else 

The body of the #else is processed only if the constant expressions of the corresponding #if and #elif 
statements evaluated to zero. The body of the #else is processed until the corresponding #endif is 
encountered. 

The form of the #endif directive is, 

#endif 

and marks the end of the #if. 

The following are examples of conditional inclusion of source lines: 
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#if OPSYS == OS_ CMS 

fn_ syntax = "filename filetype fm"; 

#elif OPSYS == OS_ MVS 

fn_ syntax = userid.library.type(membername) ' " ; 

#elif OPSYS == 0S_ DOS | | OPSYS == 0S_ OS2 
fn_ syntax = "filename.ext"; 

#else 

fn_ syntax = "filename"; 

#endif 

The object f n_ syntax is set to the appropriate filename syntax string depending on the value of the 
macro OPSYS . If OPSYS does not match any of the stated values, then fn_ syntax is set to the default 
string "filename" . 

#if HARDWARE == HW_ IBM37 0 
#if OPSYS == 0S_ CMS 

escape_ cmd = "CMS"; 

#elif OPSYS == 0S_ MVS 
escape_ cmd = "TSO"; 

#else 

escape_ cmd = "SYSTEM"; 

#endif 

#else 

escape_ cmd = "SYSTEM"; 

#endif 

The object escape_ cmd is set to an appropriate string depending on the values of the macros HARDWARE 
and OPSYS . The indentation of the directives clearly illustrates the flow between various conditions and 
levels of directives. 

13.3.1 The #ifdef and tfifndef Directives 

The #if def directive is used to check if an identifier is currently defined as a macro. For example, the 
directive, 

#ifdef xyz 

processes the body of the #ifdef only if the identifier xyz is currently a macro. This example is 
equivalent to, 

#if defined xyz 


#if defined! xyz ) 

In a similar manner, the directive, 
#ifndef xyz 
is equivalent to, 

#if !defined xyz 
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#if !defined( xyz ) 

13.4 Macro Replacement 

A directive of the form, 

♦ define identifier replacement-list 

defines a macro with the name identifier. This particular form of macro is called an object-like macro, 
because it is used like an object (as opposed to a function). Any source line that contains a token matching 
the macro name has that token replaced by the replacement-list. The tokens of the replacement-list are then 
rescanned for more macro replacements. 

For example, the macro, 

♦define TABLE_ LIMIT 256 

defines the macro TABLE_ LIMIT to be equivalent to the token256 . This is sometimes called a manifest 
constant, because it provides a descriptive term for a value that makes programs easier to read. It is a very 
good idea to use descriptive names wherever appropriate to improve the readability of a program. It may 
also save time if the same value is used many different places, and the value must be changed at some 
point. 

Care must be exercised when using more complicated object-like macros. Consider the following example: 

♦define C0UNT1 10 
♦define COUNT2 20 

♦ define TOTAL_ COUNT COUNT 1+COUNT2 
/* ... */ 

memptr = malloc ( TOTAL_ COUNT * sizeof ( int ) ) ; 

If int is 2 bytes in size, this call to malloc will allocate 50 bytes of memory, instead of the expected 60. 
This occurs because TOTAL_ COUNT * sizeof ( int ) becomes 10+2 0 * 2 after macro 
replacement, and the precedence rules for expression evaluation cause the multiply to be done first. To 
solve this problem, the macro for TOTAL_ COUNT should be defined as: 

♦define TOTAL_ COUNT (COUNT1+COUNT2) 

A directive of the form, 

♦ define identifier { identifier-list ) replacement-list 

is called a. function-like macro, because it is used like a function call. No space may appear between 
identifier and the left parenthesis in the macro definition. Any source line(s) that contains what looks like a 
function call, where the name of the function matches a function-like macro name, and the number of 
parameters matches the number of identifiers in the identifier-list, has the entire function call replaced by 
the replacement-list, substituting the actual arguments of the function call for the occurrences of the 
identifiers in the replacement-list. If the left parenthesis following the macro name was created as the result 
of a macro substitution, no further substitution will take place. If the macro name appears but is not 
followed by a left parenthesis, no further substitution will take place. 
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Consider this example: 

♦define endof( string ) \ 

(string + strlen( string )) 

The \ causes the two lines to be joined together into one logical line, making this equivalent to, 

♦define endof( string ) (string + strlen( string )) 

The function-like macro endof can be used to find a pointer to the null character terminating a string. The 
statement, 

endptr = endof( ptr ) ; 
will have the macro replaced, so it will then be parsed as, 
endptr = (ptr + strlen ( ptr )); 

Note that, in this case, the argument is evaluated twice. If StrFn ( ptr ) was specified instead of ptr, 
then the function would get called twice, because the substitution would yield, 

endptr = (StrFn( ptr ) + strlen( StrFn ( ptr ) )); 

In gathering up the tokens used to identify the arguments, each sequence of tokens separated by a comma 
constitutes an argument, unless that comma happens to be within a matched pair of left and right 
parentheses. When a right parenthesis is found that matches the beginning left parenthesis, and the number 
of arguments matches the number of identifiers in the macro definition, then the gathering of the arguments 
is complete and the substitution takes place. 

For example, 

♦define mymemcpy( dest, src, len ) \ 
memcpy( dest, src, len ) 

/* ... */ 

mymemcpy( destptr, srcptr, (t=0, t=strlen(srcptr)) ); 

will, for the parameters dest, src and len, use the arguments destptr, srcptr and (t=0, 
t=strlen (srcptr) ) respectively. 

This form of macro is also useful for "commenting out" a function call that is used for debugging the 
program. For example, 

♦define alive( where ) printf( "Alive at" where "\n" ) 
could later be replaced by, 

♦define alive( where ) /* */ 

Alternatively, the definition, 

♦define alive( where ) 

may be used. When the module or program is recompiled using this new definition for alive, all of the 
calls to printf made as a result of the macro replacement will disappear, without the necessity of deleting 
the appropriate lines in each module. 
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A directive of the form, 

#undef identifier 

causes the macro definition for identifier to be thrown away. No error is reported if no macro definition for 
identifier exists. 

13.5 Argument Substitution 

The argument substitution capabilities of the C preprocessor are very powerful, but can be tricky. The 
following sections illustrate the capabilities, and try to shed light on the problems that might be 
encountered. 

13.5.1 Converting An Argument to a String 

In the replacement-string for a function-like macro, each occurrence of # must be followed by a parameter 
to the macro. If so, both the # and the parameter are replaced by a string created from the characters of the 
argument itself, with no further substitutions performed on the argument. Each white space within the 
argument is converted to a single blank character. If the argument contains a character constant or string 
literal, any occurrences of " (double-quote) are replaced by \ ", and any occurrences of \ (backslash) are 
replaced by \\. 

The following table gives a number of examples of the result of the application of the macro, 

#define string( parm ) # parm 

as shown in the first column: 


Argument 

After Substitution 

string( abc ) 
string( "abc" ) 
string( "abc" "def" ) 
string( \' / ) 
string ( f (x) ) 

"abc" 

"\"abc\" " 

"\"abc\" \ " def \"" 

"W/" 

"f (x)" 


13.5.2 Concatenating Tokens 

In the replacement-list, if a parameter is preceded or followed by ##, then the parameter is replaced by the 
argument itself, without examining the argument for any further replacements. After all such substitutions, 
each ## is removed and the tokens on either side are concatenated together. The newly formed token is 
then examined for further macro replacement. 

## may not be either the first or last token in the replacement-list. 

Assuming that the following macros are defined. 
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♦define first "Piece" 

♦define last "of Earth" 

♦define firstlast "Peace on Earth" 

♦define firstl "Peas" 

the following table gives a number of examples of the result of the application of the macro, 

♦define glue( x, y ) x ♦♦ y 

as shown in the first column. For the examples that span several lines, each successive line of the "Result" 
column indicates successive expansions of the macros. 


Argument 

After Substitution 

glue ( 12, 34 ) 

1234 

glue( first, 1 ) 

firstl 

"Peas" 

glue ( first, 2 ) 

f irst2 

glue ( first, last ) 

firstlast 

"Peace on Earth" 


13.5.3 Simple Argument Substitution 

In the absence of either the ♦ or ♦♦ operators, a parameter is replaced by its argument. Before this 
happens, however, the argument is scanned again to see if there are any further macro substitutions to be 
made, applying all of the above rules. The rescanning applies only to the argument, not to any other tokens 
that might be adjacent to the argument when it replaces the parameter. In other words, if the last token of 
the argument and the first token following in the replacement list together form a valid macro, no 
substitution of that macro will take place. 

Consider the following examples, with these macro definitions in place: 


♦define 

f (a) 

a 

♦define 

g(x) 

(1+x) 

♦define 

h(s, t) 

s t 

♦define 

i (y) 

2-y 

♦define 

xyz 

printf 

♦define 

rcrs 

rcrs+2 


116 Argument Substitution 





The Preprocessor 


Invocation 

After Substitution 

f (c) 

c 

f (f (C) ) 

f (C) 


c 

f (g (c)) 

f ( (1+C)) 

(lie) 

h("hello",f("there")) 

h ("hello","there") 

"hello" "there" 

f(xyz)("Hello\n") 

f (printf) ("Hello\n") 
printf("Hello\n") 


13.5.4 Variable Argument Macros 

Macros may be defined to take optional additional parameters. This is accomplished using the . . . 
(ellipsis) keyword as the last parameter in the macro declaration. There may be no further parameters past 
the variable argument, and errors will be generated if the preprocessor finds anything other than a closing 
parenthesis after the ellipsis. The variable arguments may be referenced as a whole using the 

_VA_ ARGS_keyword. Special behavior of pasting this parameter with a comma can result in the 

comma being removed (this is an extension to the standard). The only token to which this applies is a 

comma. Any other token which_VA_ ARGS_is pasted with is not removed. The_ VA_ ARGS_ 

parameter may be converted to a string using the # operator. Consider the following examples of macros 
with variable number of arguments: 


♦define 

shufflel( 

a. 

b. 

) b,_VA_ ARGS_ ##,a 

♦define 

shuffle2( 

a. 

b. 

) b,♦♦ _ 

_ VA_ ARGS_, a 

♦define 

shuffle3( 

a. 

b. 

) b,♦♦ _ 

_ VA_ ARGS_♦♦, a 

♦define 

showlist( 

. . 

. ) 

♦_VA_ 

_ ARGS_ 

♦define 

args( f, , 

. . . 

) 

_VA_ 

ARGS_ 


It is safe to assume that any time a comma is used near_VA_ ARGS_tieoperator should be used to 

paste them together. Both shuf f lei and shuf f le2 macros are valid examples of pasting 

_VA_ ARGS_together with a comma; either the leading or trailing comma may be concatenated, and if 

_VA_ ARGS_is empty, the comma is removed. The mashnf f le3 works as well; the sequence of 

concantenations happens from left to right, hence first the comma and empty_VA_ ARGS_are 

concatenated and both are removed, afterwards the trailing comma is concatentated with b. Several 
example usages of the above macros follow: 
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Invocation 

After Substitution 

shuffle(x,y,z) 

y, z, x 

shuffle(x,y) 

y, x 

shuffle(a,b,c,d,e) 

b, c, d, e, a 

showlist(x,y,z) 

"x,y,z" 


a, b, c 

args ("none") 



13.5.5 Rescanning for Further Replacement 

After all parameters in the replacement-list have been replaced, the resulting set of tokens is re-examined 
for any further replacement. If, during this scan, an apparent invocation of the macro currently being 
replaced is found, it is not replaced. Further invocations of the macro currently being replaced are not 
eligible for replacement until a new set of tokens from the source file, unrelated to the tokens resulting from 
the current substitution, are being processed. 

Consider these examples, using the above macro definitions: 


Invocation 

After Rescanning 

f (g) (r) 

g (r) 


(1+r) 

f (f) (r) 

f (r) 

h(f, (b) ) 

f (b) 
b 

i (h (i, (b) ) ) 

i(i (b)) 

2-i (b) 

i (i (b) ) 

i (2—b) 

2-2-b 

rcrs 

rcrs+2 


In other words, if an apparent invocation of a macro appears, and its name matches the macro currently 
being replaced, and the apparent invocation was manufactured by other replacements, it is not replaced. If, 
however, the apparent invocation comes directly from an argument to the macro replacement, then it is 
replaced. 

After all replacements have been done, the resulting set of tokens replaces the invocation of the macro in 
the source file, and the file is then rescanned starting at the replacement-list. Any further macro 
invocations are then replaced. However, if as a result of scanning the replacement-list with following 
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tokens another apparent invocation of the macro just replaced is found, then that macro name is not 
replaced. An invocation of the macro will again be replaced only when a new invocation of the macro is 
found, unrelated to the just-replaced macro. 

If the replacement-list of tokens resembles a preprocessor directive, the preprocessor will not process it. 
A macro definition lasts until it is undefined (with #undef) or until the end of the module. 


13.6 More Examples of Macro Replacement 

The following examples are given in the ISO C standard, and are presented here as a complete guide to the 
way in which macros are replaced. The expansions are shown in stages to better illustrate the process. 

The first set of examples illustrates the rules for creating string literals (using the # operator) and 
concatenating tokens (using the ## operator). The following definitions are used: 

#define str(s) # s 

#define xstr(s) str(s) 

#define debug(s, t) printf("x" # s "= %d, x" # t "= %s", x ## s, x ## t ) 

#define INCFILE(n) vers ## n /* comment */ 

#define glue(a, b) a ## b 

#define xglue(a, b) glue(a, b) 

#define HIGHLOW "hello" 

#define LOW LOW ", world" 

The following replacements are made. The final result shows adjacent string literals joined together to 
form a single string. This step is not actually part of the preprocessor stage, but is given for clarity. 

debug( 1, 2 ); 

printf( "x" "1" "= %d, x" "2" "= %s", xl, x2 ); 
printf( "xl= %d, x2= %s", xl, x2 ); 

fputs(str(strncmp("abc\0d", "abc", '\4') /* this goes away */ 

== 0) str(: @\n), s); 

fputs("strncmp(\"abc\\0d\", \"abc\", '\\4') == 0" ": @\n", s); 
fputs("strncmp(\"abc\\0d\", \"abc\", '\\4') == 0: @\n", s); 

#include xstr(INCFILE(2).h) 

#include xstr(vers2.h) 

#include str(vers2.h) 

#include "vers2.h" 

(and then the directive is replaced by the file contents) 

glue(HIGH, LOW) 

HIGHLOW 

"hello" 

xglue(HIGH, LOW) 

xglue(HIGH, LOW ", world") 
glue( HIGH, LOW ", world") 

HIGHLOW ", world" 

"hello" ", world" 

"hello, world" 


The following examples illustrate the rules for redefinition and re-examination of macros. The following 
definitions are used: 
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#define 

X 

3 

#define 

f (a) 

f (X 

#undef 

X 


#define 

X 

2 

#define 

g 

f 

#define 

z 

z [0] 

#define 

h 

g (~ 

#define 

m (a) 

a (w) 

#define 

w 

0,1 

#define 

t (a) 

a 


(a) ) 


The following substitutions are made: 


f (y+l) + f (f (z)) % t (t (g) (0) + t) (1) 


f (x * 
f (2 * 


f (2 * 


(y+l)) 
(y+l)) 


(y+l)) 


+ 


+ f (f (Z)) % t (t (g) (0) + t) (1) 
+ f(f (x * (z)) ) % ... 

+ f (f (2 * (z) ) ) % ... 


+ f (x * 
+ f (2 * 
+ f (2 * 


+ f (2 * 


(f(2 * (z))) ) % ... 

(f(2 * (z))) ) % ... 

(f (2 * (z [0] ) ) ) ) % t (t (g) (0) + t) (1) 

% t (g (0) + t) (1) 

% t(f (0) + t) (1) 

% t(f (x * (0)) + t) (1) 
% t(f (2 * (0)) + t) (1) 
(f (2 * (z [ 0 ] ) ) ) ) % f (2 * (0)) + t (1) 


Another example: 


g(2+(3,4)-w) | h 5) & m(f) A m(m) 

f (2+ (3,4) -w) j ... 
f (2+(3, 4)-0,1) | ... 

f (x * (2+ (3, 4) -0,1) ) 
f (2 * (2+ (3, 4) -0,1) ) h 5) & . . . 
... g(~ 5) & . . . 

f(~ 5) & . .. 
f (x * (~ 5) ) 
f (2 * (~ 5) ) 


f (2 * (2+(3, 4)-0,1) ) 


f (2 * (~ 5)) 


& ... 

& m (f) A . . . 

& f (w) A . . . 

& f (0,1) A . . . 

& f (x * (0,1) ) A . . . 

& f (2 * (0,1) ) A m(m) 

A m (w) 

& f (2 * (0,1) ) A m(0,1) 


13.7 Redefining a Macro 

Once a macro has been defined, its definition remains until it is explicitly undefined (using the #undef 
directive), or until the compilation of the source file is finished. If a macro is undefined, then it may be 
redefined in some other (or the same) way. If, during a macro replacement, the name of a macro that has 
been defined, undefined and then defined again is encountered, the current (most recent) definition of the 
macro is used, not the one that was in effect when the macro being replaced was defined. 


Consider this example: 

♦define MAXVAL 1000 

♦define g(x) CheckLimit( x, MAXVAL ) 

♦undef MAXVAL 
♦define MAXVAL 200 

g ( 10 ); 
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This macro invocation expands to, 

CheckLimit( 10, 200 ); 

A macro that has been defined may be redefined (without undefining it first) only if the new definition has 
a replacement-list that is identical to the original definition. Each preprocessing token in both the original 
and new replacement lists must have the same ordering and spelling, and there must be the same number of 
tokens. The number of spaces between tokens does not matter, unless one definition has no spaces, and the 
other has spaces. Comments count as one space. 

The following examples illustrate valid redefinitions of macros: 

♦ define OBJ_ LIKE (1-1) 

♦define OBJ_ LIKE /******/ (l-i) /****/ 

♦ define FN_ LIKE (a) ( a ) 

♦define FN_ LIKE( a ) ( /******/ \ 

£ /******* \ 

*/ ) 

The next examples illustrate invalid redefinitions of the same macros: 

♦define OBJ_ LIKE (0) 

The token sequence is different. 

♦define OBJ_ LIKE (1-1) 

The spacing is different (none versus one). 

♦ define FN_ LIKE (b) ( a ) 

The parameter is a different name, and is used differently. 

♦ define FN_ LIKE (b) ( b ) 

The parameter is a different name. 

13.8 Changing the Line Numbering and File Name 

A directive of the form, 

♦ line number 

sets the line number that the compiler associates with the current line in the source file to the specified 
number. 

A directive of the form. 
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#line number string 

sets the line number as above and also sets the name that the compiler associates with the source file that is 
being read to the name contained in the string. 

If the directive is not recognized as one of the two forms described above, then macro substitution is 
performed (if possible) on the tokens on the line, and another attempt is made. If the directive still does not 
match one of the two forms, an error is reported. 

13.9 Displaying a Diagnostic Message 

A directive of the form, 
terror tokens 

causes the compiler to display a diagnostic message containing the tokens from the directive. 

13.10 Providing Other Information to the Compiler 

A directive of the form, 

♦pragma tokens 

informs the compiler about some aspect of the compilation, in an implementation-defined manner. 

See the User’s Guide for full details of the tpragma directive. 


13.11 Standard Predefined Macros 


The following macro names are reserved by the compiler: 

_DATE_ 

The date of translation of the source file (a string literal). The form of the date is "Mmm dd yyyy" 
where: 

Mmm represents the month and is one of: 

Jan Feb Mar Apr May Jun 

Jul Aug Sep Oct Nov Dec 

dd is the day of the month. The first character is a blank if the day is less than 10. 

yyyy is the year. 

If the compiler cannot determine the current date, another date is provided. 
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With Open Watcom C 16 and C 32 , the current date is always available. 


FILE_ 

The name of the current source file (a string literal). The name may be changed using the #line 
directive. 

LINE_ 

The line number of the current source line (a decimal constant). The line number may be changed 
using the #line directive. 

STDC_ 

The integer constant 1, indicating that the compiler is a standard-conforming implementation. 
STDC_ HOSTED_ 

The integer constant 1, indicating that the compiler is a hosted (not freestanding) implementation. 
STDC_ LIB_ EXT1_ 

The long integer constant 200509L, indicating conformance to the ISO/IEC Technical Report 
24731, Extensions to the C Library, Part I: Bounds-checking interfaces. 

STDC_ VERSION_ 

A decimal constant indicating the version of ISO C language standard that the compiler adheres to. 
Depending on compile time switches, this will be either 199901L (to indicate conformance with 
ISO/IEC 9899:1999) or 199409L (to indicate conformance with ISO/IEC 9899/AMD 1:1995). 

TIME_ 

The time of translation of the source file (a string literal). The form of the time is "hh:mm:ss", with 
leading zeros provided for values less than 10. 

If the compiler cannot determine the current time, another time is provided. 

With Open Watcom C 16 and C 32 , the current time is always available. 


_ func_ 

The name of the current function (a string literal). 

Any other macros predefined by the compiler will begin with an underscore (_) character. None of the 
predefined macros, nor the identifier defined, may be undefined (with #undef) or redefined (with 
♦ define). 

13.12 Open Watcom C 16 and C 32 Predefined Macros 

The Open Watcom C 16 and C 32 compilers also provide the following predefined macros for describing the 
memory model being used: 

_ COMPACT_ 

The compact memory model is being used. 

_FLAT_ 
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The "flat" memory model is being used for the 80386 processor. All segment registers refer to the 
same segment. 

_FUNCTION_ 

The name of the current function (a string literal). 

_ HUGE_ 

The huge memory model is being used. 

_ LARGE_ 

The large memory model is being used. 

_ MEDIUM_ 

The medium memory model is being used. 

_ SMALL_ 

The small memory model is being used. 

The Open Watcom C 16 and C 32 compilers also provide the following macros for describing the target 
operating system: 

_DOS_ 

The program is being compiled for use on a DOS operating system. 

_ NETWARE_ 386_ 

The program is being compiled for use on the Novell Netware 386 operating system. 

_NT_ 

The program is being compiled for use on the Windows NT operating system. 

_OS2_ 

The program is being compiled for use on the OS/2 operating system. 

_QNX_ 

The program is being compiled for use on the QNX operating system. 

_ WINDOWS_ 

The program is being compiled for use with Microsoft Windows. 

_ WINDOWS. 386_ 

The program is being compiled for use with Microsoft Windows, using the Open Watcom 32-bit 
Windows interface. 

The Open Watcom C 16 compiler also provides the following miscellaneous macro: 

_CHEAP_ WINDOWS_ 

The program is being compiled for use with Microsoft Windows using the "zW" compiler option. 
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The Open Watcom C 16 and C 32 compilers also provide the following miscellaneous macros: 

_ CHAR_ SIGNED_ 

The program is being compiled using the "j" compiler option. The default char type is treated as a 
signed quantity. 

_FPI_ 

The program is being compiled using in-line floating point instructions. 

_INLINE_ FUNCTIONS_ 

The program is being compiled using the "oi" compiler option. 

_ WATCOMC_ 

The compiler being used is the Open Watcom C 16 or Open Watcom C 32 compiler. The value of the 
macro is the version number of the compiler times 100. 

_ 386_ 

The program is being compiled for the 80386 processor, using the Open Watcom C 32 compiler. 

The Open Watcom C 16 and C 32 compilers also provide the following predefined macros for compatibility 
with the Microsoft C compiler, even though most of these macros do not begin with an underscore (_) 
character: 

MSDOS 

The program is being compiled for use on a DOS operating system. 

_ M_ 1X8 6 

The program is being compiled for a specific target architecture. The macro is identically equal to 
100 times the architecture compiler option value (-0, -1, -2, -3, -4, -5, etc.). If "-5" (Pentium 
instruction timings) was specified as a compiler option, then the value of _ M_ 1X8 6 would be 500. 

M_ 18 6 

The program is being compiled for use on the Intel 80x86 processor. 

M_ 1386 

The program is being compiled for use on the Intel 80386 processor. 

M_ I86CM 

The compact memory model is being used. 

M_ I86HM 

The huge memory model is being used. 

M_ I86LM 

The large memory model is being used. 

M_ I86MM 

The medium memory model is being used. 

M_ I86SM 

The small memory model is being used. 
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N0_ EXT_ KEYS 

The program is being compiled for ISO/ANSI conformance using the "za" (no extended keywords) 
compiler option. 

13.13 The offsetof Macro 

The macro, 

offsetof ( type, member ) ; 

expands to a constant expression with type size_ t. The value of the expression is the offset in bytes of 
member from the start of the structure type, member should not be a bit-field. 

To use this macro, include the <stddef . h> header. 

13.14 The NULL Macro 


The NULL macro expands to a null pointer constant, which is a value that indicates a pointer does not 
currently point to anything. 

It is recommended that NULL, instead of 0, be used for null pointer constants. 

To use this macro, include the <stddef . h> header. 
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14 The Order of Translation 


This chapter describes the sequence of steps that the C compiler takes in order to translate a set of source 
files. Most programmers do not need to thoroughly understand these steps, as they are intuitive. However, 
occasionally it will be necessary to examine the sequence to solve a problem in the translation process. 

Even though the steps of translation are listed as separate phases, the compiler may combine them together. 
However, this should be transparent to the user. 

The following are the phases of translation: 

1. The characters of the source file(s) are mapped to the source character set. Any end-of-line 
markers used in the file system are translated, as necessary, to new-line characters. Any 
trigraphs are replaced by the appropriate single character. 

2. Physical source lines are joined together wherever a line is terminated by a backslash (\) 
character. Effectively, the \ and the new-line character are deleted, creating a longer line from 
that record and the one following. 

3. The source is broken down into preprocessing tokens and sequences of "white-space" (space and 
tab) characters (including comments). Each token is the longest sequence of characters that can 
be a token. Each comment is replaced by one white-space character. The new-line characters 
are retained at this point. 

4. Preprocessing directives are executed and macro invocations are substituted. A header named in 
a ((include directive is processed according to rules 1 to 4. 

5. Members of the source character set and escape sequences in character constants and string 
literals are converted to single characters in the execution character set. 

6. Adjacent character string literal tokens and adjacent wide string literal tokens are concatenated. 

7. White-space characters separating tokens are discarded. Each preprocessing token is converted 
to a token. The tokens are translated according to the syntactic and semantic rules. 

The final phase usually occurs outside of the compilation phase. In this phase, often called the linking 
phase, all external object definitions are resolved, and an executable program image is created. The 
completed image contains all the information necessary to run the program in the appropriate execution 
environment. 
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15 Modularity 


For many small programs, it is possible to write a single module which contains all of the C source for the 
program. This module can then be compiled, linked and run. 

However, for larger applications it is not possible to maintain one module with everything in it. Or, if it is 
technically possible, compiling such a large module every time a change is made to the source carries too 
great a time penalty with it. At this point, it becomes necessary to break the program into pieces, or 
modules. 

Dividing a program can be done quite easily. If the only issue is to reduce the size of the modules that need 
to be compiled, then arbitrary divisions of the code into modules will accomplish the goal. 

There are other advantages, however, to planning program modularity. Some of these advantages are: 

• recompilation time is reduced, 

• code can be grouped into logically-connected areas, making it easier to find things, 

• data structures can be hidden in one module, avoiding the temptation of letting an outside piece of 
code "peek" into a structure it really should not access directly, 

• whole modules can be rewritten or redesigned without affecting other modules, 

• areas of the code that depend on the hardware or operating system can be isolated for easy 
replacement when the program is ported. This may extend to replacing the module with an assembly 
language equivalent for increased performance. 

The following sections discuss each of these points in more detail. 

15.1 Reducing Recompilation Time 

As discussed above, merely breaking a program into pieces will reduce the amount of time spent 
recompiling the source. A bug is often a simple coding error, requiring only a one or two line change. 
Recompiling only a small percentage of the code and relinking will be faster than recompiling everything. 

Occasionally, recompiling all of the modules will be required. This usually arises when a data structure, 
constant, macro or other item that is used by several modules is changed. With good program design, such 
a change would occur in a header file, and all modules that include that header would be recompiled. 
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15.2 Grouping Code With Related Functionality 

The best way to break programs into modules is to designate each module as having some overall purpose. 
For example, one module may deal exclusively with interacting with the user. Another module may 
manage a table of names, while yet another may process some small subset of the set of actions that may be 
performed by the program. 

Many of the modules then become resource managers, and every part of the code that needs to do 
something significant with that resource must act through that resource manager. 

Using the example of the names table manager, it is likely that the manager will need to do things like 
create and delete a name entry in the table. These actions would translate directly to two functions with 
external linkage. 

By dividing up a program along lines of related functionality, it is usually easy to know where to look when 
a problem is being tracked. 

Module names that clearly state the purpose of the module also help to locate things. 

15.3 Data Hiding 

Sometimes a module is written that has exclusive ownership of a data structure, such as a linked list. All 
other modules that wish to access the structure must call a function in the module that owns it. This 
technique is known as data hiding. The actual data is hidden in the structure, and only the functional 
interface (also called the procedural interface) may be used to access it. The functional interface is just the 
set of functions provided for accessing the structure. 

The main advantage of data hiding is that the data structure may be changed with little or no impact on 
other modules. Also, access to the structure is controlled, leading to fewer errors because of misuse of the 
structure. 

It is possible to have different levels of data hiding. Complete data hiding occurs when no outside module 
has access to the structure at all. Partial data hiding occurs when elements of the structure can be accessed, 
but the overall structure may not be manipulated. 

Note that these rules work only if the programmer respects them. The rules are not enforced by the 
compiler. If a module includes a header that describes the data structures being used by another module 
that wants exclusive access to the structures, a rule is being broken. Whether this is good or bad depends 
entirely on the judgement of the programmer. 

15.3.1 Complete Data Hiding 

With complete data hiding, having a pointer to an element of the structure has no intrinsic value except as a 
parameter to the functional interface. Getting or setting a value in the structure requires a function call. 

The advantage of this technique is that the complete data structure may be totally redesigned without 
affecting other modules. The definitions of the individual structures (struct’s, union’s, arrays) may be 
changed and no other module will have to be changed, or even recompiled. 
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The main disadvantage of complete data hiding is that even simple accesses require a function call, which is 
less efficient than just referencing a storage location. 

Function-like macros may also be used to implement complete data hiding, avoiding the function call but 
hiding the true structure of the data. Recompilation of all modules may be required if the data structures 
change. 

15.3.2 Partial Data Hiding 

Partial data hiding occurs when the structure itself (for example, a linked list) is not accessible in its 
entirety, but elements of the structure (an element of the linked list) are accessible. 

Using the names table manager as an example, it may be necessary to call the names table manager to 
create a name entry, but once the name is created, a pointer to the name is returned as the return value of 
the create function. This pointer points to a structure which is defined in a header that any module can 
include. Therefore, the contents of an element of the data structure can be manipulated directly. 

This method is more efficient than the complete data hiding technique. However, when the structure used 
for the names table is changed, all modules that refer to that structure must be recompiled. 

15.4 Rewriting and Redesigning Modules 

With modular program design and data hiding, it is often possible to completely replace a module without 
affecting others. This is usually only possible when the functional interface does not change. With partial 
data hiding, the actual types used to implement the structure would have to remain unchanged, otherwise at 
least a recompilation would be required. Changing a struct, for example, would probably require a 
recompilation if only the types changed, or new members were added. If, however, the names of the 
members changed, or some other fundamental change occurred, then source code changes in these other 
modules would be necessary. 

15.5 Isolating System Dependent Code in Modules 

System dependencies are only relevant if the program being developed is to be run on different computers 
or operating systems. Isolating system dependent code is discussed more thoroughly in the chapter 
"Writing Portable Programs". 

It is quite difficult, sometimes, to identify what constitutes system dependent code. The first time a 
program is ported to a new system, a number of problem areas usually arise. These areas should be 
carefully examined, and the code that is dependent on the host environment should be isolated. Isolation 
may be accomplished by placing the code in a separate module marked as system dependent, or by placing 
macros in the code to compile differently for the different systems. 
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16 Writing Portable Programs 


Portable software is software that is written in such a way that it is relatively easy to get the software 
running on a new and different computer. By choosing the C language, the first step has been taken to 
reduce the effort involved in porting, but there are many other things that must be done. Some of these 
things include: 

• isolating the portions of the code that depend on the hardware or operating system being used, 

• being aware of what features of the C language are implementation-defined and avoiding them, or 
taking them into account, 

• being aware of the various ranges of values that may be stored in certain types, and declaring objects 
appropriately, 

• being aware of special features available on some systems that might be useful. 

No programmer can seriously expect to write a large portable program the first time. The first port of the 
program will take a significant period of time, but the final result will be a program which is much more 
portable than before. Generally, each subsequent port will be easier and take less time. Of course, if the 
new target system has a new concept that was not considered in the original program design (such as a 
totally different user-interface), then porting will necessarily take longer. 

16.1 Isolating System Dependent Code 

The biggest problem when trying to port a program is to uncover all the places in the code where an 
assumption about the underlying hardware or operating system was made, and which proves to be incorrect 
on the new system. Many of these differences are hidden in library routines, but they can still cause 
problems. 

Consider, for example, the issue of distinguishing between alphabetic and non-alphabetic characters. The 
library provides the function isalpha which takes a character argument and returns a non-zero value if 
the character is alphabetic, and 0 otherwise. Suppose a programmer, writing a FORTRAN compiler, 
wanted to know if a variable name started with the letters T through ’N’, in order to determine if it should 
be an integer variable. The programmer might write, 

upletter = toupper( name[0] ); 

if( upletter >= 'I' && upletter <= 'N' ) { 

/* ... */ 

} 

If the program was being developed on a machine using the ASCII character set, this code would work fine, 
since the upper case letters have 26 consecutive values. However, porting the program to a machine using 
the EBCDIC character set, problems may arise because between the letters T and ’J’ are 7 other characters, 
including ’}’. Thus, the name "}VAR" might be considered a valid integer variable name, which it is not. 
To solve this problem, the programmer could write. 
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if( isalpha( name[0] ) ) { 

upletter = toupper( name[0] ); 

if( upletter >= 'I' && upletter <= 'N' ) { 

/* ... */ 

} 

} 

In this case, it is not necessary to isolate the code because a relatively simple coding change covers both 
cases. But there are cases where each system will require a new set of functions for some aspect of the 
program. 

Consider the user interface of a program. If the program just displays lines of output to a scrolling 
terminal, and accepts lines of input in the same way, the user interface probably won't need to change 
between systems. But suppose the program has a sophisticated user interface involving full-screen 
presentation of data, windows, and menus, and uses a mouse and the keyboard for input. In the absence of 
standards for such interfaces, it is quite likely that each system will require a customized set of functions. 
Here is where program portability can become an art. 

An approach to this problem is to completely isolate the user interface code of the program. The processing 
of data occurs independently of what appears on the screen. At the completion of processing, a function is 
called which updates the screen. This code may or may not be portable, depending on how many layers of 
functions are built between the physical screen and the generic program. At a level fairly close to the 
screen hardware, a set of functions should be defined which perform the set of actions that the program 
needs. The full set of functions will depend extensively on the requirements of the program, but they 
should be functions that can reasonably be expected to work on any system to which the program will 
eventually be ported. 

Other areas that may be system dependent include: 

• The behavior and capabilities of devices, including printers. Some printers support multiple fonts, 
expanded and compressed characters, underlining, graphics, and so on. Others support only 
relatively simple text output. 

• Accessing memory regions outside of normally addressable storage. A good example is the Intel 
80x86 family of processors. With the Open Watcom C 16 16-bit compiler, the addressable storage is 
1024 kilobytes, but a 16-bit address can only address 64 kilobytes. Special steps must be taken when 
compiling in order to address the full storage space. Many compilers for the 8086, including Open 
Watcom C 16 and C 32 , introduce new keywords that describe pointer types beyond the 16-bit pointer. 

• Code that has been written in assembly language for speed. As code generation technology 
advances, assembly language code should become less necessary. 

• Code that accesses some special feature of the system. As an example, many systems provide the 
ability to temporarily exit to the operating system level, and later return to the program. The method 
of doing this varies between systems, and the requirements of the program often change as well. 

• Handling the command line parameters. While C breaks the list of parameters down into strings, the 
interpretation of those strings may vary between systems. A program probably should attempt to 
conform to any conventions of the system on which it is being run. 

• Handling other startup requirements. Allocation of memory, initializing devices, and so on, may be 
done at this point. 
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16.2 Beware of Long External Names 

According the C Language standard, a compiler may limit external names (functions and global objects) to 
6 significant characters. This limitation is often imposed by the "linking" stage of the development process. 

In practice, most systems allow many more significant characters. However, the developer of a portable 
program should be aware of the potential for porting the program to a system that has a small limit, and 
name external objects accordingly. 

If the developer must port a program with many names that are not unique within the limitations imposed 
by the target development system, the preprocessor may be used to provide shorter unique names for all 
objects. Note that this method may seriously impair any symbolic debugging facilities provided by the 
development system. 

16.3 Avoiding Implementation-Defined Behavior 

Several aspects of the code generated by the C compiler depend on the behavior of the particular C 
compiler being used. A portable program should avoid these where possible, and take them into 
consideration where they can’t be avoided. It may be possible to use macros to avoid some of these issues. 

An important behavior that varies between systems is the number of characters of external objects and 
functions that the system recognizes. The standard states that a system must recognize a minimum of 6 
characters, although future standards may remove or extend this limit. Most systems allow more than 6 
characters, but several recognize only 8 characters. For true portability, a function or object that has 
external linkage should be kept unique in the first 6 characters. Sometimes this requires ingenuity when 
thinking of names, but developing a system for naming objects goes a long way towards fitting within this 
restriction. The goal, of course, is to still have meaningful object names. If all systems that will eventually 
be used have a higher limit, then the programmer may decide to go past the 6 character limit. If a port is 
done to a system with the 6 character limit, a lot of source changes may be required. 

To solve this problem, macros could be used to map the actual function names into more cryptic names that 
fit within the 6 character limit. This technique may have the adverse affect of making debugging very 
difficult because many of the function and object names will not be the same as contained in the source 
code. 

Another implementation-defined behavior occurs with the type char. The standard does not impose a 
signed or unsigned interpretation on the type. A program that uses an object of type char that 
requires the values to be interpreted as signed or unsigned should explicitly declare the object with that 
type. 

16.4 Ranges of Types 

The range of an object of type int is not specified by the standard, except to say that the minimum range is 
-32767 to 32767. If an object is to contain an integer value, then thought should be given as to whether or 
not this range of values is acceptable on all systems. If the object is a counter that will never go outside the 
range 0 to 255, then the range will be adequate. However, if the object is to contain values that may exceed 
this range, then a long int may be required. 

The same argument applies to objects with type float. It may make more sense to declare them with type 
double. 
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When converting floating-point numbers to integers, the rounding behavior can also vary between 
compilers and systems. If it is important to know how the rounding behaves, then the program should refer 
to the macro FLT_ ROUNDS (defined in the header<f loat . h>), which is a value describing the type of 
rounding performed. 

16.5 Special Features 

Some systems provide special features that may or may not exist on other systems. For example, many 
provide the ability to exit to the operating system, run some other programs, then return to the program that 
was running. Other systems may not provide this ability. In an interactive program, this feature may be 
very useful. By isolating the code that deals with this feature, a program may remain easily portable. On 
the systems that don’t support this feature, it may be necessary to provide a stub function which does 
nothing, or displays a message. 

16.6 Using the Preprocessor to Aid Portability 

The preprocessor is particularly useful for providing alternate code sequences to deal with portability 
issues. Conditional compilation provided by the #if directive allows the insertion of differing code 
sequences depending on some criteria. Defining a set of macros which describe the various systems, and 
another macro that selects a particular system, makes it easy to add system-dependent code. 

For example, consider the macros, 


♦define 

OS_ 

DOS 

0 

♦define 

os_ 

CMS 

1 

♦define 

OS_ 

MVS 

2 

♦define 

os_ 

OS2 

3 

♦define 

os_ 

QNX 

4 

♦define 

HW_ 

IBMPC 

0 

♦define 

HW_ 

IBM370 

1 

♦define 

PR_ 

i8086 

0 

♦define 

PR_ 

370 

1 


They describe a set of operating systems (OS ), hardware (HW) and processors (PR) , which together can 
completely describe a computer and its operating system. If the program was being ported to a IBM 370 
running the MVS operating system, then it could include a header defining the macros above, and declare 
the macros, 

♦define OPSYS OS_ MVS 

♦define HARDWARE HW_ IBM370 

♦ define PROCESSOR PR_370 

The following code sequence would include the call only if the program was being compiled for a 370 
running MVS: 

♦ if HARDWARE == HW_ IBM37 0 && OPSYS == OS_ MVS 

DoMVSStuff(x, y ) ; 

♦endif 
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In other cases, code may be conditionally compiled based only on the hardware regardless of the operating 
system, or based only on the operating system regardless of the hardware or processor. 

This technique may work well if used in moderation. However, a module that is filled with these directives 
becomes difficult to read, and that module becomes a candidate for being rewritten entirely for each 
system. 
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17Avoiding Common Pitfalls 


Even though a C program is much easier to write than the corresponding assembly language program, there 
are a few areas where most programmers make mistakes, and spend a great deal of time staring at the code 
trying to figure out why the program doesn’t work. 

The bugs that are the most difficult to find often occur when the compiler doesn’t give an error or warning, 
but the code generated is not what the programmer expected. After a great deal of looking, the programmer 
spots the error and realizes that the compiler generated the correct code, but it wasn’t the code that was 
wanted. 

Some compilers, including Open Watcom C 16 and C 32 , have optional checking for common errors built 
into them, providing warnings when these conditions arise. It is probably better to eliminate the code that 
causes the warning than to turn off the checking done by the compiler. 

The following sections illustrate several common pitfalls, and discuss how to avoid them. 


17.1 Assignment Instead of Comparison 

The code fragment, 

chr = getc(); 
if( chr = 'a' ) { 

printf ( "letter is 'a'\n" ); 

} else { 

printf( "letter is not 'a'\n" ); 

} 

will never print the message letter is not ' a' , regardless of the value of chr . 

The problem occurs in the second line of the example. The statement, 
if( chr = 'a' ) { 

assigns the character constant ' a' to the object chr . If the value of chr is not zero, then the statement 
that is the subject of the i f is executed. 

The value of the constant ' a ' is never zero, so the first part of the i f will always be executed. The second 
part might as well not even be there! 

Of course, the correct way to code the second line is, 

if( chr == 'a' ) { 

changing the = to ==. This statement says to compare the value of chr against the constant ' a' and to 
execute the subject of the if only if the values are the same. 
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Using one equal sign (assignment) instead of two (comparison for equality) is a common errors made by 
programmers, often by those who are familiar with languages such as Pascal, where the single = means 
"comparison for equality". 

17.2 Unexpected Operator Precedence 

The code fragment, 

if( chr = getc() != EOF ) { 

printf( "The value of chr is %d\n", chr ); 

} 

will always print 1, as long as end-of-file is not detected in getc. The intention was to assign the value 
from getc to chr, then to test the value against EOF. 

The problem occurs in the first line, which says to call the library function getc. The return value from 
getc (an integer value representing a character, or EOF if end-of-file is detected), is compared against 
EOF, and if they are not equal (it’s not end-of-file), then 1 is assigned to the object chr . Otherwise, they 
are equal and 0 is assigned to chr . The value of chr is, therefore, always 0 or 1. 

The correct way to write this code fragment is, 

if( (chr = getc()) != EOF ) { 

printf ( "The value of chr is %d\n", chr ); 

} 

The extra parentheses force the assignment to occur first, and then the comparison for equality is done. 

Note: doing assignment inside the controlling expression of loop or selection statements is not a good 
programming practice. These expressions tend to be difficult to read, and problems such as using = instead 
of == are more difficult to detect when, in some cases, = is desired. 


17.3 Delayed Error From Included File 

Suppose the source file mytypes . h contained the line, 

typedef int COUNTER 

and the main source file being compiled started with, 

♦include "mytypes.h" 

extern int main( void ) 

/*********************/ 

{ 

COUNTER x; 

/* ... */ 

} 

Attempting to compile the main source file would report a message such as. 
Error! Expecting ';' but found 'extern' on line 3 
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Examining the main source file does not show any problem. The problem actually occurs in the included 
source file, since the typedef statement does not end with a semi-colon. It is this semi-colon that the 
compiler is expecting to find. The next token found is the extern keyword, so the error is reported in the 
main source file. 

When an error occurs shortly after an #include directive, and the error is not readily apparent, the error 
may actually be caused by something in the included file. 


17.4 Extra Semi-colon in Macros 


The next code fragment illustrates a common error when using the preprocessor to define constants: 
♦define MAXVAL 10; 

/* ... */ 

if( value >= MAXVAL ) break; 

The compiler will report an error message like. 

Error! Expecting ')' but found on line 372 

The problem is easily spotted when the macro substitution is performed on line 372. Using the definition 
for MAXVAL, the substituted version of line 372 reads, 

if( value >= 10; ) break; 

The semi-colon (;) in the definition was not treated as an end-of-statement indicator as expected, but was 
included in the definition of the macro ( manifest constant ) MAXVAL . The substitution then results in a 
semi-colon being placed in the middle of the controlling expression, which yields the syntax error. 

17.5 The Dangling else 

In the code fragment, 

if( valuel > 0 ) 

if( value2 > 0 ) 

printf( "Both values greater than zero\n" ); 

else 

printf ( "valuel is not greater than zero\n" ); 

suppose valuel has the value 3, while value2 has the value -7. This code fragment will cause the 
message, 

valuel is not greater than zero 
to be displayed. 

The problem occurs because of the else. The program is indented incorrectly according to the syntax that 
the compiler will determine from the statements. The correct indentation should clearly show where the 
error lies: 
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if( valuel > 0 ) 

if( value2 > 0 ) 

printf( "Both values greater than zero\n" ); 

else 

printf( "valuel is not greater than zero\n" ); 

The else belongs to the second if, not the first. Whenever there is more than one if statement without 
braces and without an else statement, the next else will be matched to the most recent if statement. 

This code fragment clearly illustrates the usefulness of using braces to state program structure. The above 
example would be (correctly) written as, 

if( valuel > 0 ) { 

if( value2 > 0 ) { 

printf ( "Both values greater than zero\n" ); 

} 

} else { 

printf( "valuel is not greater than zero\n" ); 

} 


17.6 Missing break in switch Statement 

In the code fragment, 

switch( value ) { 

case 1: 

printf( "value is l\n" ); 
default: 

printf( "value is not l\n" ) ; 

} 

if value is 1, the following output will appear: 

value is 1 
value is not 1 

This unexpected behavior occurs because, when value is 1, the switch causes control to be passed to 
the case 1: label, where the first printf occurs. Then the default label is encountered. Labels are 
ignored in execution, so the next statement executed is the second printf. 

To correct this example, it should be changed to, 

switch( value ) { 

case 1: 

printf( "value is l\n" ); 
break; 
default: 

printf( "value is not l\n" ) ; 

} 

The break statement causes control to be passed to the statement following the closing brace of the 
switch statement. 
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17.7Side-effects in Macros 


In the code fragment, 

♦define endof( ptr ) ptr + strlen( ptr ) 

/* ... */ 

endptr = endof( ptr++ ) ; 
the statement gets expanded to, 

endptr = ptr++ + strlen( ptr++ ); 

The parameter ptr gets incremented twice, rather than once as expected. 

The only way to avoid this pitfall is to be aware of what macros are being used, and to be careful when 
using them. Several library functions may be implemented as macros on some systems. These functions 
include, 

getc putc 

getchar putchar 

The ISO standard requires that documentation states which library functions evaluate their arguments more 
than once. 
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18 Programming Style 


Programming style is as individual as a person’s preference in clothing. Unfortunately, just as some 
programmers wouldn’t win a fashion contest, some code has poor style. This code is usually easy to spot, 
because it is difficult to understand. 

Good programming style can make the difference between programs that are easy to debug and modify, and 
those that you just want to avoid. 

There are a number of aspects to programming style. There is no perfect style that is altogether superior to 
all others. Each programmer must find a style that makes him or her comfortable. The intention is to write 
code that is easy to read and understand, not to try to stump the next person who has to fix a problem in the 
code. 

Good programming style will also lead to less time spent writing a program, and certainly less time spent 
debugging or modifying it. 

The following sections discuss various aspects of programming style. They reflect the author’s own biases, 
but they are biases based on years of hacking his way through code, mostly good and some bad, and much 
of it his own! 


18.1 Consistency 

Perhaps the most important aspect of style is consistency. Try, as much as possible, to use the same rules 
throughout the entire program. Having a mixed bag of styles within one program will confuse even the 
best of programmers trying to decipher the code. 

If more than one programmer is involved in the project, it may be appropriate, before the first line of code 
is written, to discuss general rules of style. Some rules are more important than others. Make sure 
everyone understands the rules, and are encouraged to follow them. 

18.2 Case Rules for Object and Function Names 

When examining a piece of code, the scope of an object is sometimes difficult to determine. One needs to 
examine the declarations of objects within the function, then those declared outside of any functions, then 
those declared included from other source files. If no strict rules of naming objects are followed, each 
place will need to be laboriously searched each time. 

Using mixed case object names, with strict rules, can make the job much easier. It does not matter what 
rules are established, as long as the rules are consistently applied throughout the program. 

Consider the following sample set of rules, used throughout this book: 

1. objects declared within a function with automatic storage duration are entirely in lower case, 
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int x, counter, limit; 

float save_ global; 

struct s * sptr; 

2. objects with static storage duration (global objects) start with an upper case letter, and words or 
word fragments also start with upper case, 

static int TotalCount; 

extern float GlobalAverage; 

static struct s SepStruct; 

3. function names start with an upper case letter, and words or word fragments also start with upper 

case, (distinguishable from global objects by the left parenthesis), 

extern int TrimLength( char * ptr, int len ); 

static field * CreateField( char * name ); 

4. all constants are entirely in upper case. 

♦define FIELD_ LIMIT 500 
♦define BUFSIZE 32 

enum { INVALID, HELP, ADD, DELETE, REPLACE }; 

5. all typedef tags are in upper case. 

typedef struct { 
float real; 
float imaginary; 

} COMPLEX; 

Thus, the storage duration and scope of each identifier can be determined without regard to context. 
Consider this program fragment: 

chr = ReadChar() ; 
if ( chr != EOF ) { 

GlbChr = chr; 

} 

Using the above rules, 

1. ReadChar is a function, 

2. chr is an object with automatic storage duration defined within the current function, 

3. EOF is a constant, 

4. GlbChr is an object with static storage duration. 

Note: the library functions do not use mixed case names. Also, the function main does not begin with an 
upper case M. Using the above coding style, library functions would stand out from other functions 
because of the letter-case difference. 
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18.3 Choose Appropriate Names 

The naming of objects can be critical to the ease with which bugs can be found, or changes can be made. 
Using object names such as linecount, columns and rownumber will make the program more 
readable. Of course, short forms will creep into the code (few programmers like to type more than is really 
necessary), but they should be used judiciously. 

Consistency of naming also helps to make the code more readable. If a structure is used throughout the 
program, and many different routines need a pointer to that structure, then the name of each object that 
points to it could be made the same. Using the example of a symbol table, the object name symptr might 
be used everywhere to mean "pointer to a symbol structure". A programmer seeing that object will 
automatically know what it is declared to be. 

Appropriate function names are also very important. Names such as Dolt, while saving the original 
programmer from trying to think of a good name, make it more difficult for the next programmer to figure 
out what is going on. 

18.4 Indent to Emphasize Structure 

The following is a valid function: 

static void BubbleSort( int list[], int n ) 
/**********************************/ { i n t indexl 
= 0; int index2; int temp; if( n < 2 )return; do { 
index2 = indexl + 1; do { if( list [ indexl ] > 
list[ index2 ] ) { temp = list[ indexl ]; list[ 
indexl ] = list [ index2 ]; list [ index2 ] = temp; 

} } while( ++index2 < n ); } while( ++indexl < n-1 

) ; 1 

(The compiler will know that it’s valid, but the programmer would find it difficult to validate.) Here is the 
same function, but using indenting to clearly illustrate the function structure: 

static void BubbleSort( int list[], int n ) 
/*****************************************/ 

{ 

int indexl = 0; 
int index2; 
int temp; 

if ( n < 2 )return; 
do { 

index2 = indexl + 1; 
do { 

if ( list[ indexl ] > list[ index2 ] ) { 

temp = list[ indexl ]; 
list[ indexl ] = list [ index2 ]; 
list[ index2 ] = temp; 

} 

} while( ++index2 < n ) ; 

} while( ++indexl < n-1 ) ; 

} 
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Generally, it is good practice to indent each level of code by a consistent amount, for example 4 spaces. 
Thus, the subject of an if statement is always indented 4 spaces inside the if. In this manner, all loop and 
selection statements will stand out, making it easier to determine when the statements end. 

The following are some recommended patterns to use when indenting statements. These patterns have been 
used throughout the book. 

int Fn( void ) 

/************ j 
{ 

/* indent 4 */ 

} 

if( condition ) { 

/* indent 4 */ 

} else { 

/* indent 4 */ 

} 

if( condition ) { 

/* indent 4 */ 

} else if( condition ) { 

/* indent 4 from first if */ 
if ( condition ) { 

/* indent 4 from nearest if */ 

} 

} else { 

/* indent 4 from first if */ 

} 

switch( condition ) { 

case VALUE: 

/* indent 4 from switch */ 
case VALUE: 
default: 

} 

do { 

/* indent 4 */ 
while( condition ) ; 

while( condition ) { 

/* indent 4 */ 

} 

for( a; b; c ) { 

/* indent 4 */ 

} 
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Two other popular indenting styles are, 

if( condition ) 

{ 

statement 

} 

and, 

if( condition ) 

{ 

statements 

} 

It is not important which style is used. However, a consistent style is an asset. 


18.5 Visually Align Object Declarations 

A lengthy series of object declarations can be difficult to read if care is not taken to improve the readability. 
Consider the declarations, 

struct flentry *flptr; 
struct fldsym *sptr; 
char *bufptr,*wsbuff; 
int length; 

Now, consider the same declarations, but with some visual alignment done: 

struct flentry * flptr; 
struct fldsym * sptr; 
char * bufptr; 

char * wsbuff; 

int length; 

It is easier to scan a list of objects when their names all begin in the same column. 


18.6 Keep Functions Small 

A function that is several hundred lines long can be difficult to comprehend, especially if it is being looked 
at on a terminal, which might only have 25 lines. Large functions also tend to have a lot of nesting of 
program structures, making it difficult to follow the logic. 

A function that fits entirely within the terminal display can be studied and understood more easily. 

Program constructs don't get as complicated. Large functions often can be broken up into smaller functions 
which are easier to maintain. 


Keep Functions Small 151 




Programmer’s Guide 


18.7 Use static for Most Functions 


Most functions do not need to be called from routines outside of the current module. Yet, if the keyword 
static is not used in the function declaration, then the function is automatically given external linkage. 
This can lead to a proliferation of external symbols, which may cause naming conflicts. Also, some linking 
programs may impose limitations. 

Only those functions that must have external linkage should be made external. All other definitions of 
functions should start with the keyword static. 

It also is a good idea to start definitions for external functions with the keyword extern, even though it is 
the default case. 


18.8 Group Static Objects Together 

Static objects that are declared outside of any function definition, and are used throughout the module, 
generally should be declared together, for example before the definition of the first function. Placing the 
declarations of these objects near the beginning of the module makes them easier to find. 

18.9 Do Not Reuse the Names of Static Objects 

If an object with static storage duration exists in one module, but has internal linkage, then another object 
with the same name should not be declared in another module. The programmer may confuse them. 

Even more importantly, if an object exists with external linkage, a module should not declare another 
object with the same name with internal linkage. This second object will overshadow the first within the 
module, but the next programmer to look at the code will likely be confused. 

18.10 Use Included Files to Organize Structures 

Included source files can be used to organize data structures and related information. They should be used 
when the same structure is needed in different modules. They should even be considered when the 
structure is used only in one place. 

Generally, each included source file should contain structures and related information for one aspect of the 
program. For example, a file that describes a symbol table might contain the actual structures or other 
types that are required, along with any manifest constants that are useful. 

18.11 Use Function Prototypes 

Function prototypes are very useful for eliminating common errors when calling functions. If every 
function in a program is prototyped (and the prototypes are used), then it is difficult to pass the wrong 
number or types of arguments, or to misinterpret the return value. 

Using the symbol table example, the included source file that describes the symbol table structure and any 
related global objects or constant values could also contain the function prototypes for the functions used to 
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access the table. Another approach is to have separate source files containing the function prototypes, 
possibly using a different naming convention for the file. For example, 

♦include "symbols.h" 

♦include "symbols.fn" 

would include the structures and related values from symbols . h, and the function prototypes from 
symbols . fn. 


18.12 Do Not Do Too Much In One Statement 


In the same manner that a big function that does too much can be confusing, so too can a long statement. 
Historically, a programmer might combine many operations into a single statement in order to get the 
compiler to produce better code. With current compilers, splitting the statement into two or more simpler 
statements will produce equivalent code, and will make the program easier to understand. 

A common example of a statement that can be split is, 

if ( (c = getcharO) != EOF ) { 

Historically, this statement might have allowed the compiler to avoid storing the value of c and then 
reloading it again to compare with EOF . However, the equivalent, 

c = getchar(); 
if ( c != EOF ) { 

is more readable, and most compilers will produce the same code. 

18.13 Do Not Use goto Too Much 

The goto statement is a very powerful tool, but it is very easy to misuse. Here are some general rules for 
the use of got o’ s: 

• don’t use them! 

If that rule is not satisfactory, then these should be followed: 

• Never goto a label that is above. That is the beginning of spaghetti code. Loop statements can 
always be used. 

• Never goto the middle of a block (compound-statement). A block should always be entered by 
passing over the opening brace. 

• Use goto to jump out of nested blocks, where the break statement is not appropriate. 

Above all, keep the use of goto’s to a minimum. 
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18.14 Use Comments 


Comments are crucial to good programming style. Regardless of how well the program is written, some 
code will be difficult to understand. Comments make it possible to give a full explanation for what the 
code is trying to do. 

Each function definition should begin with a short comment describing what the function does. 

Each module should begin with comments describing the purpose of the module. It is also a good idea to 
type in who wrote it, when it was written, who modified it and why, and when it was modified. This last 
collection of information is commonly called an audit trail, as it leaves a trail allowing a programmer to see 
the evolution of the module, along with who has been changing it. 


The following audit trail is from one module in an actual product: 


/* Modified: 

* 84 / 04/23 

* 84 / 11/08 

* 

* 84 / 12/12 

* 85 / 01/12 

* 85 / 01/29 

* 86 / 01/31 

* 86 / 12/10 
* 87 / 02/24 
*/ 


By: 

Dave McClurkin 
Jim Graham 

Steve McDowell 

Alex Kachura 
Steve McDowell 


Reason: 


Initial implementation 
Implemented TOTAL non-combinable; 

added MAXIMUM,MINIMUM,AVERAGE 
Added call to CheckBreak 
Fixed overflow problems 
Saves value of TYP_ field 
Switched to use of numeric accumulator 
Removed some commented code 
Made all commands combinable 
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A. Compiler Keywords 


The following topics are discussed: 

• Standard Keywords 

• Open Watcom C 16 and C 32 Keywords 


A.1 Standard Keywords 

The following is the list of keywords reserved by the C language: 


auto 

double 

inline 

static 

_ Bool 

else 

int 

struct 

break 

enum 

long 

switch 

case 

extern 

register 

typedef 

char 

float 

restrict 

union 

_ Complex 

for 

return 

unsigned 

const 

goto 

short 

void 

continue 

if 

signed 

volatile 

default 

_ Imaginary 

sizeof 

while 


do 


A.2 Open Watcom Extended Keywords 

The Open Watcom compilers also reserve the following extended keywords: 


Microsoft compilers compatible 

_asm 

_based 

_ cdecl 

_ declspec 

_except 

_export 

_far 

_ farl6 

_ fastcall 

IBM compilers compatible 
_ Cdecl 
_ Except 
_ Export 
_ Farl6 
_ Fastcall 

Open Watcom specific 


finally 

fortran 

huge 

inline 

int 64 

interrupt 

leave 

loadds 

near 


Finally 

Leave 

Packed 

Pascal 


_pascal 

_saveregs 

_ segment 

_segname 

_self 

_stdcall 

_syscall 

_try 

_unaligned 


Segl 6 
Syscall 
System 
Try 
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_builtin_ isfloat _ow_ imaginary_ unit_watcall 

The keywords_based,_segment,_segname and_self are described in the section "Based 

Pointers for Open Watcom C 16 and C 32 ". Open Watcom C 16 and C 32 provide the predefined macro 
_ based for convenience and compatibility with the Microsoft C compiler. It may be used in place of 

_based. Open Watcom C 16 and C 32 provide the predefined macro _ segment for convenience and 

compatibility with the Microsoft C compiler. It may be used in place of_segment. Open Watcom 

C 16 and C 32 provide the predefined macro _ segname for convenience and compatibility with the 

Microsoft C compiler. It may be used in place of_segname. Open Watcom C 16 and C 32 provide the 

predefined macro _ self for convenience and compatibility with the Microsoft C compiler. It may be used 
in place of_self. 

The keywords_far,_huge and_near are described in the sections "Special Pointer Types for 

Open Watcom C 16 " and "Special Pointer Types for Open Watcom C 32 ". Open Watcom C 16 and 

C 32 provide the predefined macros far and _ far for convenience and compatibility with the Microsoft C 

compiler. They may be used in place of_far. Open Watcom C 16 and C 32 provide the predefined 

macros huge and _ huge for convenience and compatibility with the Microsoft C compiler. They may be 

used in place of_huge. Open Watcom C 16 and C 32 provide the predefined macros near and _ near 

for convenience and compatibility with the Microsoft C compiler. They may be used in place of_near. 

The keywords_f ar 16 Far 16 and_ Segl 6 are described in the section "Special Pointer Types for 

Open Watcom C 32 ". Open Watcom C 16 and C 32 provide the predefined macro _ f ar 16 for convenience 
and compatibility with the Microsoft C compiler. It may be used in place of_f ar 16. 

The _ Packed keyword is described in the section "Structures". 

The_cdecl and_ Cdecl keywords may be used with function definitions, and indicates that the calling 

convention for the function is the same as that used by Microsoft C. All parameters are pushed onto the 
stack, instead of being passed in registers. This calling convention may be controlled by a #pragma 
directive. See the User’s Guide. Open Watcom C 16 and C 32 provide the predefined macros cdecl and 
_ cdecl for convenience and compatibility with the Microsoft C compiler. They may be used in place of 
_cdecl. 

The_fastcall and. Fastcall keywords may be used with function definitions, and indicates that 

the calling convention used is compatible with Microsoft C compiler. This calling convention may be 
controlled by a #pragma directive. Open Watcom C 16 and C 32 provide the predefined macro 
_ fastcall, for convenience and compatibility with the Microsoft C compiler. It may be used in place 
of_fastcall See the User’s Guide.. 

The_fortran keyword may be used with function definitions, and indicates that the calling convention 

for the function is suitable for calling a function written in FORTRAN. By default, this keyword has no 
effect. This calling convention may be controlled by a #pragma directive. See the User’s Guide. Open 
Watcom C 16 and C 32 provide the predefined macros fortran and _ fortran for convenience and 
compatibility with the Microsoft C compiler. They may be used in place of_fortran. 

The_pascal and_ Pascal keywords may be used with function definitions, and indicates that the 

calling convention for the function is suitable for calling a function written in Pascal. All parameters are 

pushed onto the stack, but in reverse order to the order specified by_cdecl. This calling convention 

may be controlled by a #pragma directive. See the User’s Guide. Open Watcom C 16 and C 32 provide 
the predefined macros pascal and _ pascal for convenience and compatibility with the Microsoft C 
compiler. They may be used in place of_pascal. 

The_syscall^. Syscall and_ System keywords may be used with function definitions, and 

indicates that the calling convention used is compatible with OS/2 (version 2.0 or higher). This calling 
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convention may be controlled by a #pragma directive. See the User’s Guide. Open Watcom C 16 and 
C 32 provide the predefined macro _ syscall for convenience and compatibility with the Microsoft C 
compiler. It may be used in place of_syscall. 

The_stdcall keyword may be used with function definitions, and indicates that the calling convention 

used is compatible with Win32. This calling convention may be controlled by a #pragma directive. Open 
Watcom C 16 and C 32 provide the predefined macro _ stdcall, for convenience and compatibility with 
the Microsoft C compiler. It may be used in place of_stdcall See the User’s Guide. 

The_watcall keyword may be used with function definitions, and indicates that the Open Watcom 

default calling convention is used. This calling convention may be controlled by a #pragma directive. 

See the User’s Guide. 

The_export and_ Export keywords may be used with objects with static storage duration (global 

objects) and with functions, and describes that object or function as being a known object or entry point 
within a Dynamic Link Library in OS/2 or Microsoft Windows. The object or function must also be 
declared as having external linkage (using the extern keyword). In addition, any call back function 
whose address is passed to Windows (and which Windows will "call back") must be defined with the 

_export keyword, otherwise the call will fail and cause unpredictable results. The_export 

keyword may be omitted if the object or function is exported by an option specified using the linker. See 
the Open Watcom Linker User’s Guide. Open Watcom C 16 and C 32 provide the predefined macro 
_ export for convenience and compatibility with the Microsoft C compiler. It may be used in place of 
_export. 

The_interrupt keyword may be used with function definitions for functions that handle computer 

interrupts. All registers are saved before the function begins execution and restored prior to returning from 
the interrupt. The machine language return instruction for the function is changed to iret (interrupt 

return). Functions written using_interrupt are suitable for attaching to the interrupt vector using the 

library function _ dos_ setvect. Open Watcom C 16 and C 32 provide the predefined macros 
interrupt and _ interrupt for convenience and compatibility with the Microsoft C compiler. They 
may be used in place of_interrupt. 

The_loadds keyword may be used with functions, and causes the compiler to generate code that will 

force the DS register to be set to the default data segment (DGROUP) so that near pointers will refer to that 
segment. This keyword is normally used with functions written for Dynamic Link Libraries in Windows 
and OS/2. Open Watcom C 16 and C 32 provide the predefined macro _ loadds for convenience and 
compatibility with the Microsoft C compiler. It may be used in place of_loadds. 

The_saveregs keyword may be used with functions. It is provided for compatibility with Microsoft 

C, and has no effect in Open Watcom C 16 and C 32 . Open Watcom C 16 and C 32 provide the predefined 
macro _ saveregs for convenience and compatibility with the Microsoft C compiler. It may be used in 
place of_saveregs. 

The_tryj_ Try ,_except^ Except ,_finally^. Finally ,_leave and. Leave 

keywords may be used for exception handling. See the "Structured Exception Handling" in User’s Guide. 
Open Watcom C 16 and C 32 provide the predefined macro _ try for convenience and compatibility with 

the Microsoft C compiler. It may be used in place of_try. Open Watcom C 16 and C 32 provide the 

predefined macro _ except for convenience and compatibility with the Microsoft C compiler. It may be 

used in place of_except. Open Watcom C 16 and C 32 provide the predefined macro _ finally for 

convenience and compatibility with the Microsoft C compiler. It may be used in place of_finally. 

Open Watcom C 16 and C 32 provide the predefined macro _ leave for convenience and compatibility with 
the Microsoft C compiler. It may be used in place of_leave. 

The_ow_ imaginary_ unit keyword may be used as _Imaginary constant 1.0. 
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The_builtin_ isf loat keyword may be used as function for testing symbol type. 
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B. Trigraphs 


The following is the list of trigraphs. In a C source file, all occurrences (including inside quoted strings and 
character constants) of any of the trigraph sequences below are replaced by the corresponding single 
character. 


Character 

Trigraph Sequence 

[ 

?? ( 

] 

? ? ) 

{ 

? ?< 

} 

? ?> 


? ? ! 

# 

? ?= 

\ 

? ?/ 

A 

??' 

~ 

? ?- 


No other trigraphs exist. Any question mark (?) that does not belong to one of the trigraphs is not changed. 

To get a sequence of characters that would otherwise be a trigraph, place a \ before the second question 
mark. This will cause the trigraph to be broken up so that it is not recognized, but later in the translation 
process, the \ ? will be converted to ? . For example, ?\ ?= will be translated to ? ? =. 
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C. Escape Sequences 


The following are the escape sequences and their meanings: 


Escape 

Sequence 

Meaning 

\a 

Causes an audible or visual alert 

\b 

Back up one character 

\f 

Move to the start of the next page 

\n 

Move to the start of the next line 

\r 

Move to the start of the current line 

\t 

Move to the next horizontal tab 

\v 

Move to the next vertical tab 


Each escape sequence maps to a single character. When such a character is sent to a display device, the 
action corresponding to that character is performed. 
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D. Operator Precedence 


The table below summarizes the levels of precedence in expressions. 


Expression Type 

Operators 

primary 

identifier constant 

string (expression) 

postfix 

a[b] f 0 

a.b a->b a++ a— 

unary 

sizeof u sizeof( a ) 

++a —a &a *a 

+a -a ~a !a 

cast 

(type) a 

multiplicative 

a*b a/b a%b 

additive 

a + b a - b 

shift 

a << b a >> b 

relational 

a<b a>b a <= b a >= b 

equality 

a == b a != b 

bitwise AND 

a & b 

bitwise exclusive OR 

a A b 

bitwise inclusive OR 

a | b 

logical AND 

a & & b 

logical OR 

a | | b 

conditional f 

a ? b : c 

assignment f 

a = b a += b a -= b a *= b 
a /= b a %= b a &= b a A = b 
a |= b a <<= b a >>= b 

comma 

a, b 


f associates from right to left 
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Operations at a higher level in the table will occur before those below. All operators involving more than 
one operand associate from left to right, except for the conditional and assignment operators, which 
associate from right to left. Operations at the same level, except where discussed in the relevant section, 
may be executed in any order that the compiler chooses (subject to the usual algebraic rules). In particular, 
the compiler may regroup sub-expressions that are both associative and commutative in order to improve 
the efficiency of the code, provided the meaning (i.e. types and results) of the operands and result are not 
affected by the regrouping. 

The order of any side-effects (for example, assignment, or action taken by a function call) is also subject to 
alteration by the compiler. 
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E. Formal C Grammar 


This appendix presents the formal grammar of the C programming language. The following notation is 
used: 

{digit} (0) 

Zero or more occurrences of digit are allowed. 

{digit} (l) 

One or more occurrences of digit are allowed. 

(integer-suffix) 

integer-suffix is optional, with only one occurrence being allowed if present. 

A I B I C 

Choose one of A, B or C . 


E.1 Lexical Grammar 


The following topics are discussed: 

• Tokens 

• Keywords 

• Identifiers 

• Constants 

• String Literals 

• Operators 

• Punctuators 

E.1.1 Tokens 

token 



keyword 

or 

identifier 

or 

constant 

or 

string-literal 

or 

operator 

or 

punctuator 
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E.1.2 Keywords 

keyword 

standard-keyword 

or Open Watcom-extended-keyword 
standard-keyword 


auto 

double 

inline 

static 

_ Bool 

else 

int 

struct 

break 

enum 

long 

switch 

case 

extern 

register 

typedef 

char 

float 

restrict 

union 

_ Complex 

for 

return 

unsigned 

const 

goto 

short 

void 

continue 

if 

signed 

volatile 

default 

_ Imaginary 

sizeof 

while 


do 

Open Watcom-extended-keyword 

Microsoft compilers compatible 

_asm 

_based 

_ cdecl 

_ declspec 

_ except 

_ export 

_far 

_ farl6 

_ fastcall 

IBM compilers compatible 
_ Cdecl 
_ Except 
_ Export 
_ Farl6 
_ Fastcall 

Open Watcom specific 

_ builtin_ isfloat 


E.1.3 Identifiers 

identifier 

nondigit {nondigit I digit} (0) 

nondigit 

a I b I ... I z I A I B I ... I Z 


finally 

fortran 

huge 

inline 

int 64 

interrupt 

leave 

loadds 

near 


. _ pascal 
. _ saveregs 
_ segment 
_ segname 
. _ self 
. _ stdcall 
. _ syscall 
. _ try 

_ unaligned 


Finally 

Leave 

Packed 

Pascal 


Segl 6 
Syscall 
System 
Try 


_ow_ imaginary_ unit_watcall 
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digit 

0 | 1 | . . . | 9 

E.1.4 Constants 

constant 

floating-constant 
or integer-constant 

or enumeration-constant 

or character-constant 

floating-constant 

fractional-constant (exponent-part) (floating-suffix ) 
or digit-sequence exponent-part (floating-suffix ) 

exponent-part 

e | E (+ | - ) digit-sequence 

floating-suffix 

f | F | i | L 

fractional-constant 

(digit-sequence). digit-sequence 
or digit-sequence. 

digit-sequence 

{digit} (l) 


integer-constant 

decimal-constant (integer-suffix) 
or octal-constant (integer-suffix) 

or hexadecimal-constant (integer-suffix ) 

integer-suffix 

u|u(i|l) 
or 1 | L (u j U ) 

decimal-constant 

nonzero-digit {digit} (0) 


nonzero-digit 

1 I 2 I ... I 9 


octal-constant 

0{octal-digit} (0) 
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octal-digit 

0 | 1 | . . . | 7 

hexadecimal-constant 

0 xl 0 X {hexadecimal-digit} (l) 

hexadecimal-digit 

0 | 1 | . . . | 9 | 

a | b | . . . j f j A | B | . . . F 

enumeration-constant 

identifier 

character-constant 

' {c-char}(l)' 
or 1/ {c-char} (l)' 

c-char 

any character in the source character set except 
the single-quote ', backslash \, or new-line character 
or escape-sequence 

escape-sequence is one of 

V \" \\ 

\o \oo \ooo 
\x{hexadecimal-digit} (l) 

\a \b \f \n \r \t \v 

E.1.5 String Literals 

string-literal 

" {s-char} (0) " 
or L" {s-char} (0) " 

s-char 

any character in the source character set except 
the double-quote ", backslash \, or new-line character 
or escape-sequence 

E.1.6 Operators 

operator is one of 

[ ] ( ) 

++ — & * 

/ % « » 

7 ; 

=*=/=% 

, # ## 

: > 


-> 

+ — ~ ! sizeof 

<><=>=== != A | && 

= += -= <<= »= &= A = 1 = 
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E.l. 7 Punctuators 


punctuator 




E.2 Phrase Structure Grammar 


. . . # 


The following topics are discussed: 

• Expressions 

• Declarations 

• Statements 

• External Definitions 

E.2.1 Expressions 

constant-expression 

conditional-expression 


expression 

assignment-expressionj , assignment-expression} (0) 

assignment-expression 

conditional-expression 

or unary-expression assignment-operator assignment-expression 
assignment-operator is one of 

= *= /= %= += -= <<= »= &= A = | = 
conditional-expression 

logical-OR-expression <? expression : conditional-expression ) 
logical-OR-expression 

logical-AND-expression{ | | logical-AND-expression} (0) 
logical-AND-expression 

inclusive-OR-expression {& & inclusive-OR-expression} (o) 
inclusive-OR-expression 

exclusive-OR-expression { | exclusive-OR-expression} ( 0 ) 
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exclusive-OR-expression 

AND-expression { A AND-expression} (0) 

AND-expression 

equality-expression { & equality-expression} (0) 
equality-expression 

relational-expression {==1! = relational-expression} (0) 
relational-expression 

shift-expression {<!>!<=!>= shift-expression} (0) 


shift-expression 

additive-expression {<<!>> additive-expression} (0) 
additive-expression 

multiplicative-expression {+1- multiplicative-expression} (0) 

multiplicative-expression 

cast-expression {*1/1% cast-expression} (0) 


cast-expression 

unary-expression 

or ( type-name ) cast-expression 

unary-expression 

postfix-expression 

or ++ | — | sizeof unary-expression 
or sizeof ( type-name ) 

or unary-operator cast-expression 

unary-operator is one of 

& * + - ~ ! 

postfix-expression 

primary-expression 

or postfix-expression [ expression ] 

or postfix-expression ( (argument-expression-list) ) 

or postfix-expression . identifier 

or postfix-expression -> identifier 

or postfix-expression ++ 

or postfix-expression — 

argument-expression-list 

assignment-expression {, assignment-expression} (0) 
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primary-expression 

identifier 
or constant 

or string-literal 

or ( expression ) 

E.2.2 Declarations 


declaration 

declaration-specifiers (init-declarator-list ); 


declaration-specifiers 

storage-class-specifier (declaration-specifiers) 
or type-specifier (declaration-specifiers ) 


init-declarator-list 

init-declarator {, init-declarator} (o) 


init-declarator 

declarator (= initializer) 
storage-class-specifier 

typedef | extern | static | auto 


type-specifier 

void | char | short | int | long 
double | signed | unsigned 
or struct-or-union-specifier 
or enum-specifier 

or typedef-name 

or type-qualifier 


type-qualifier 

const | volatile 
or Open Watcom-type-qualifier 


Open Watcom-type-qualifier 

_based 

_ Cdecl 

_ cdecl 

_ declspec 

_ Export 

_ export 

_far 

_ Farl6 

_farl 6 

_ Fastcall 
_ fastcall 


_ fortran 
_ huge 
_ inline 
_ int64 
_ interrupt 
_ loadds 
_ near 
Packed 
Pascal 
_ pascal 
_ saveregs 


register 


float 


Segl 6 
_ segment 
_ segname 
_ self 
_ stdcall 
Syscall 
_ syscall 
System 
_ unaligned 
_ watcall 
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struct-or-union-specifier 

struct-or-union (identifier ) { struct-declaration-list } 
or struct-or-union identifier 

struct-or-union 

struct | union 

struct-declaration-list 

{struct-declaration} ( 1 ) 

struct-declaration 

type-specifier-list struct-declarator-list ; 

type-specifier-list 

{type-specifier} (l) 

struct-declarator-list 

struct-declarator {, struct-declarator} (0) 

struct-declarator 

declarator 

or (declarator ) : constant-expression 

enum-specifier 

enum (identifier) { enumerator-list } 
or enum identifier 

enumerator-list 

enumerator {, enumerator} (0) 

enumerator 

enumeration-constant (= constant-expression) 

declarator 

(pointer) direct-declarator 

direct-declarator 

identifier 

or ( declarator ) 

or direct-declarator [ (constant-expression ) ] 

or direct-declarator ( parameter-type-list ) 

or direct-declarator ( (identifier-list) ) 

pointer 

{* (type-specifier-list)} ( 1 ) 
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parameter- type-l is t 

parameter-list (, . . . ) 

parameter-list 

parameter-declaration {, parameter-declaration} (0) 

parameter-declaration 

declaration-specifiers declarator 
or declaration-specifiers (abstract-declarator) 

identifier-list 

identifier {, identifier} (0) 

type-name 

type-specifier-list (abstract-declarator) 

abstract-declarator 

pointer 

or (pointer) direct-abstract-declarator 

direct-abstract-declarator 

( abstract-declarator ) 

or (direct-abstract-declarator) [ (constant-expression ) ] 

or (direct-abstract-declarator) ( (parameter-type-list) ) 

typedef-name 

identifier 

initializer 

assignment-expression 
or {initializer-list (, )} 

initializer-list 

initializer {, initializer} (0) 

E.2.3 Statements 

statement 

labelled-statement 
or compound-statement 

or expression-statement 

or selection-statement 

or iteration-statement 

or jump-statement 
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labelled-statement 

identifier : statement 

or case constant-expression : statement 

or default : statement 

compound-statement 

{ (declaration-list) (statement-list)} 


declaration-list 

{ declaration} (1 > 

statement-list 

{statement} (1) 

expression-statement 

(expression) ; 

selection-statement 

if ( expression ) statement 
or if ( expression ) statement else statement 
or switch ( expression ) statement 

iteration-statement 

while ( expression ) statement 
or do statement while ( expression ) ; 

or for ((expression); (expression); (expression) ) statement 
jump-statement 

goto identifier; 
or continue; 

or break; 

or return (expression ); 

E.2.4 External Definitions 

file 

{external-definition} (1) 

external-definition 

function-definition 
or declaration 

function-definition 

(declaration-specifiers ) declarator (declaration-list) 
compound-statement 
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E.3 Preprocessing Directives Grammar 

preprocessing-file 

group 


group 



{group-part} <i) 

group-part 

or 

or 

(pp-token ) new-line 
if-section 

control-line 

if-section 

if-group {elif-group} (o) (else-group ) endif-line 

if-group 

# i f const-expression new-line (group ) 

# i f de f identifier new-line (group ) 

# i f nde f identifier new-line (group ) 

elif-group 

# e 1 i f constant-expression new-line (group ) 

else-group 

# e 1 s e new-line (group ) 

endif-line 

#endif new-line 

control-line 

#include pp-tokens new-line 

♦ define identifier (pp-tokens ) new-line 

♦ define identifier ((identifier-list) ) (pp-tokens ) new-line 

♦ undef identifier new-line 

♦ line pp-tokens new-line 

♦ error (pp-tokens) new-line 
♦pragma (pp-tokens ) new-line 

♦ new-line 

pp-tokens 

{preprocessing-token} ( 1 ) 

preprocessing- 

or 

or 

or 

or 

or 

or 

■token 

header-name (only within a ♦include directive) 

identifier (no keyword distinction) 

constant 

string-literal 

operator 

punctuator 

each non-white-space character that cannot be one of the above 
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header-name 

<{h-char} (0) > 

h-char 

any character in the source character set except new-line and > 

new-line 

the new-line character 
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F. Translation Limits 


All standard-conforming C compilers must be able to translate and execute a program that contains one 
instance of every one of the following limits. Each limit is the minimum limit (the smallest maximum) that 
the compiler may impose. 

The Open Watcom C 16 and C 32 compilers do not impose any arbitrary restrictions in any of these 
areas. Restrictions arise solely because of memory limitations. 

• 15 nesting levels of compound statements, iteration control structures (for, do/while, while), 
and selection control structures (if, switch), 

• 8 nesting levels of conditional inclusion (# i f), 

• 12 pointer, array and function declarators (in any order) modifying an arithmetic, structure, union or 
incomplete type in a declaration, 

• 31 nesting levels of parenthesized declarators within a full declarator, 

• 32 nesting levels of parenthesized expressions within a full expression, 

• 31 significant initial characters in an internal identifier or a macro name, 

• 6 significant initial characters in an external identifier, 

• 511 external identifiers in one translation unit (module), 

• 127 identifiers with block scope declared in one block, 

• 1024 macro identifiers simultaneously defined in one translation unit (module), 

• 31 parameters in one function definition, 

• 31 arguments in one function call, 

• 31 parameters in one macro definition, 

• 31 parameters in one macro invocation, 

• 509 characters in a logical (continued) source line, 

• 509 characters in a character string literal or wide string literal (after concatenation), 

• 32767 bytes in an object, 

• 8 nesting levels for ((included files. 
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• 257 case labels for a switch statement (excluding those for any nested switch statements), 
•127 members in a single structure or union, 

•127 enumeration constants in a single enumeration, 

•15 levels of nested structure or union definitions in a single struct-declaration-list (structure or union 
definition). 
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G. Macros for Numerical Limits 


Although the various numerical types may have different ranges depending on the implementation of the C 
compiler, it is still possible to write programs that can adapt to these changing ranges. In most 
circumstances, it is clear whether an integer object is sufficiently large to contain all necessary values for it, 
regardless of whether or not the integer is only 16 bits. 

However, a programmer may want to be able to conditionally compile code based on information about the 
range of certain types. The header <limits . h> defines a set of macros that describe the range of the 
various integer types. The header <f loat. h> defines another set of macros that describe the range and 
other characteristics of the various floating-point types. 

G. 1 Numerical Limits for Integer Types 

The following macros are replaced by constant expressions that may be used in # i f preprocessing 
directives. For a compiler to conform to the C language standard, the magnitude of the value of the 
expression provided by the compiler must equal or exceed the ISO value given below, and have the same 
sign. (Positive values must be greater than or equal to the ISO value. Negative values must be less than or 
equal to the ISO value.) The values for the actual compilers are shown following the ISO value. 


• the number of bits in the smallest object that is not a bit-field (byte) 


Macro: CHAR_ BIT 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 8 

8 


• the minimum value for an object of type signed char 


Macro: SCHAR_ MIN 

V alue 

ISO 

Open Watcom C 16 and C 32 

<= -127 

-128 


• the maximum value for an object of type signed char 
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Macro: SCHAR_ MAX 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 127 

127 


• the maximum value for an object of type unsigned char 


Macro: UCHAR_ MAX 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 255 

255 


• the minimum value for an object of type char 
If char is unsigned (the default case) 


Macro: CHAR_ MIN 

Value 

ISO 

0 

Open Watcom C 16 and C 32 

0 


If char is signed (by using the command-line switch to force it to be signed), then CHAR_ MIN is 
equivalent to SCHAR_ MIN 


Macro: CHAR_ MIN 

Value 

ISO 

Open Watcom C 16 and C 32 

<= -127 

-128 


• the maximum value for an object of type char 

If char is unsigned (the default case), then CHAR_ MAX is equivalent toUCHAR_ MAX 


Macro: CHAR_ MAX 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 255 

255 


If char is signed (by using the command-line switch to force it to be signed), then CHAR_ MAX is 
equivalent to SCHAR_ MAX 
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Macro: CHAR_ MAX 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 127 

127 


• the maximum number of bytes in a multibyte character, for any supported locale 


Macro: MB_ LEN_ MAX 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 1 

2 


• the minimum value for an object of type short int 


Macro: SHRT_ MIN 

Value 

ISO 

Open Watcom C 16 and C 32 

<= -32767 

-32768 


• the maximum value for an object of type short int 


Macro: SHRT_ MAX 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 32767 

32767 


• the maximum value for an object of type unsigned short int 


Macro: USHRT_ MAX 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 65535 

65535 


• the minimum value for an object of type int 


Macro: INT_ MIN 

Value 

ISO 

<= -32767 

Open Watcom C 16 

-32768 

Open Watcom C 32 

-2147483648 


Numerical Limits for Integer Types 183 







































Appendices 


• the maximum value for an object of type int 


Macro: INT_ MAX 

Value 

ISO 

>= 32767 

Open Watcom C 16 

32767 

Open Watcom C 32 

2147483647 


• the maximum value for an object of type unsigned int 


Macro: UINT_ MAX 

Value 

ISO 

>= 65535 

Open Watcom C 16 

65535 

Open Watcom C 32 

4294967295 


• the minimum value for an object of type long int 


Macro: LONG_ MIN 

Value 

ISO 

Open Watcom C 16 and C 32 

<= -2147483647 

-2147483648 

the maximum value for an object of type long int 

Macro: LONG_ MAX 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 2147483647 

2147483647 

the maximum value for an object of type unsigned long int 

Macro: ULONG_ MAX 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 4294967295 

4294967295 

the minimum value for an object of type long long int 

Macro: LLONG_ MIN 

Value 

ISO 

Open Watcom C 16 and C 32 

<= -9223372036854775807 

-9223372036854775808 
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• the maximum value for an object of type long long int 


Macro: LLONG_ MAX 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 9223372036854775807 

9223372036854775807 


• the maximum value for an object of type unsigned long long int 


Macro: ULLONG_ MAX 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 18446744073709551615 

18446744073709551615 


G.2 Numerical Limits for Floating-Point Types 

The following macros are replaced by expressions which are not necessarily constant. For a compiler to 
conform to the C language standard, the magnitude of the value of the expression provided by the compiler 
must equal or exceed the ISO value given below, and have the same sign. (Positive values must be greater 
than or equal to the ISO value. Negative values must be less than or equal to the ISO value.) The values for 
the actual compilers are shown following the ISO value. Most compilers will exceed some of these values. 

For those characteristics that have three different macros, the macros that start with FLT_ refer to type 
float, DBL_ refer to type double and LDBL_ refer to type long double. 


• the radix (base) of representation for the exponent 


Macro: FLT_ RADIX 

V alue 

ISO 

Open Watcom C 16 and C 32 

>= 2 

2 


• the precision, or number of digits in the floating-point mantissa, expressed in terms of the 
FLT_ RADIX 


Macro: FLT_ MANT_ DIG 

Value 

ISO 

Open Watcom C 16 and C 32 

no value specified 

23 
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Macro: DBL_ MANT_ DIG 

Value 

ISO 

Open Watcom C 16 and C 32 

no value specified 

52 


Macro: LDBL_ MANT_ DIG 

Value 

ISO 

Open Watcom C 16 and C 32 

no value specified 

52 


• the number of decimal digits of precision 


Macro: FLT_ DIG 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 6 

6 


Macro: DBL_ DIG 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 10 

15 


Macro: LDBL_ DIG 

V alue 

ISO 

Open Watcom C 16 and C 32 

>= 10 

15 


• the minimum negative integer n such that FLT_ RADIX raised to the power n, minus 1, is a 
normalized floating-point number, or, 

• the minimum exponent value in terms of FLT_ RADIX, or, 

• the base FLT_ RADIX exponent for the floating-point value that is closest, but not equal, to 
zero 


Macro: FLT_ MIN_ EXP 

Value 

ISO 

Open Watcom C 16 and C 32 

no value specified 
-127 
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Macro: DBL_ MIN_ EXP 

Value 

ISO 

Open Watcom C 16 and C 32 

no value specified 
-1023 


Macro: LDBL_ MIN_ EXP 

Value 

ISO 

Open Watcom C 16 and C 32 

no value specified 
-1023 


• the minimum negative integer n such that 10 raised to the power n is in the range of normalized 
floating-point numbers, or, 

• the base 10 exponent for the floating-point value that is closest, but not equal, to zero 


Macro: FLT_ MIN_ 10_ EXP 

Value 

ISO 

Open Watcom C 16 and C 32 

<= -37 

-38 


Macro: DBL_ MIN_ 10_ EXP 

Value 

ISO 

Open Watcom C 16 and C 32 

<= -37 

-307 


Macro: LDBL_ MIN_ 10_ EXP 

Value 

ISO 

Open Watcom C 16 and C 32 

<= -37 

-307 


• the maximum integer n such that FLT_ RADIX raised to the power n, minus 1, is a representable 
finite floating-point number, or, 


• the maximum exponent value in terms of FLT_ RADIX, or, 

• the base FLT_ RADIX exponent for the largest valid floating-point value 


Macro: FLT_ MAX_ EXP 

Value 

ISO 

Open Watcom C 16 and C 32 

no value specified 

127 
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Macro: DBL_ MAX_ EXP 

Value 

ISO 

Open Watcom C 16 and C 32 

no value specified 

1023 


Macro: LDBL_ MAX_ EXP 

Value 

ISO 

Open Watcom C 16 and C 32 

no value specified 

1023 


• the maximum integer n such that 10 raised to the power n is a representable finite floating-point 
number, or. 


• the base 10 exponent for the largest valid floating-point value 


Macro: FLT_ MAX_ 10_ EXP 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 37 

38 


Macro: DBL_ MAX_ 10_ EXP 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 37 

308 


Macro: LDBL_ MAX_ 10_ EXP 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 37 

308 


• the maximum representable finite floating-point number 


Macro: FLT_ MAX 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 1E+37 

3.402823466E+38 


Macro: DBL_ MAX 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 1E+37 

1.797693134 862 315 60E+308 
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Macro: LDBL_ MAX 

Value 

ISO 

Open Watcom C 16 and C 32 

>= 1E+37 

1.7 97 693134 8 62 315 60E+308 


• the difference between 1.0 and the least value greater than 1.0 that is representable in the given 
floating-point type, or. 


• the smallest number eps such that (1.0 + eps) != 1.0 


Macro: FLT_ EPSILON 

Value 

ISO 

Open Watcom C 16 and C 32 

<= IE-5 

1.192092896E-15 


Macro: DBL_ EPSILON 

Value 

ISO 

Open Watcom C 16 and C 32 

<= IE-9 

2.2204460492503131E-16 


Macro: LDBL_ EPSILON 

Value 

ISO 

Open Watcom C 16 and C 32 

<= IE-9 

2.2204460492503131E-16 


• the minimum positive normalized floating-point number 


Macro: FLT_ MIN 

Value 

ISO 

Open Watcom C 16 and C 32 

<= IE-37 

1.175494351E-38 


Macro: DBL_ MIN 

Value 

ISO 

Open Watcom C 16 and C 32 

<= IE-37 

2.22507385850720160E-308 


Macro: LDBL_ MIN 

Value 

ISO 

Open Watcom C 16 and C 32 

<= IE-37 

2.22507385850720160E-308 


As discussed in the section "Integer to Floating-Point Conversion", the macro FLT_ ROUNDS is replaced by 
a constant expression whose value indicates what kind of rounding occurs following a floating-point 
operation. The following table gives the value of FLT_ ROUNDS and its meaning: 
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FLT_ ROUNDS 

Technique 

-1 

indeterminable 

0 

toward zero 

1 

to nearest number 

2 

toward positive infinity 

3 

toward negative infinity 


If FLT_ ROUNDS has any other value, the rounding mechanism is implementation-defined. 

For the Open Watcom C 16 and C 32 compiler, the value of FLT_ ROUNDS is 1, meaning that 
floating-point values are rounded to the nearest representable number. 
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H. Implementation-Defined Behavior 


This appendix describes the behavior of Open Watcom C 16 and C 32 when the standard describes the 
behavior as implementation-defined. The term describing each behavior is taken directly from the 
ISO/ANSI C Language standard. The numbers in parentheses at the end of each term refers to the section 
of the standard that discusses the behavior. 


H.1 Translation 

How a diagnostic is identified (5.1.1.3). 

A diagnostic message appears as: 

file name (line-number): error-type\ msg-number: msgjtext 

where: 

filename is the name of the source file where the error was detected. If the error was found in 

a file included from the source file specified on the compiler command line, then the 
name of the included file will appear. 

line-number is the source line number in the named file where the error was detected. 

error-type is either the word Error for errors that prevent the compile from completing 

successfully (no code will be generated), or Warning for conditions detected by 
the compiler that may not do what the programmer expected, but are otherwise 
valid. Warnings will not prevent the compiler from generating code. The issuance 
of warnings may be controlled by a command-line switch. See the User’s Guide for 
details. 

msg-number is the letter E (for errors) followed by a four digit error number, or the letter W (for 
warnings) followed by a three digit warning number. Each message has its own 
unique message number. 

msg-text is a descriptive message indicating the problem. 

Example: 

test.c(35): Warning! W301: No prototype found for 'Getltem' 
test.c(57): Error! E1009: Expecting '}' but found 
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H.2 Environment 


The semantics of the arguments to main (5.1.2.2.1). 

Each blank-separated token, except within quoted strings, on the command line is made into a string 
that is an element of argv. Quoted strings are maintained as one element. 

For example, for the command line, 

pgm 2+ 1 tokens "one token" 

argc would have the value 5, and the five elements of argv would be, 

pgm 
2 + 

1 

tokens 
one token 

What constitutes an interactive device (5.1.2.3). 

For Open Watcom C 16 and C 32 , the keyboard and the video display are considered interactive 
devices. 


H.3 Identifiers 


The number of significant initial characters (beyond 31) in an identifier without external linkage 

( 6 . 1 . 2 ). 

Unlimited. 

The number of significant initial characters (beyond 6) in an identifier with external linkage (6.1.2). 

The Open Watcom C 16 and C 32 compilers do not impose a limit. The Open Watcom Linker limits 
significant characters to 40. 

Whether case distinctions are significant in an identifier with external linkage (6.1.2). 

The Open Watcom C 16 and C 32 compilers produce object names in mixed case. The Open Watcom 
Linker provides an option to respect or ignore case when resolving linkages. By default, the linker 
respects case. See the Open Watcom Linker User’s Guide for details. 


H.4 Characters 


The members of the source and execution character sets, except as explicitly specified in the standard 
(5.2.1). 

The full IBM PC character set is available in both the source and execution character sets. The set of 
values between 0x20 and 0x7F are the ASCII character set. 
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The shift states used for the encoding of multibyte characters (5.2.1.2). 

There are no shift states in the support for multibyte characters. 

The number of bits in a character in the execution character set (5.2.4.2.1). 


The mapping of members of the source character set (in character constants and string literals) to 
members of the execution character set (6.1.3.4). 

Both the source and execution character sets are the full IBM PC character set for whichever code 
page is in effect. In addition, the following table shows escape sequences available in the source 
character set, and what they translate to in the execution character set. 


Escape 

Sequence 

Hex 

Value 

Meaning 

\a 

07 

Bell or alert 

\b 

08 

Backspace 

\f 

OC 

Form feed 

\n 

0A 

New-line 

\r 

0D 

Carriage return 

\t 

09 

Horizontal tab 

\ v 

OB 

Vertical tab 

V 

27 

Apostrophe or single quote 

\" 

22 

Double quote 

\? 

3F 

Question mark 

w 

5C 

Backslash 

\ddd 


Octal value 

\xddd 


Hexadecimal value 


The value of an integer character constant that contains a character or escape sequence that is not 
represented in the execution character set or the extended character set for a wide character constant 
(6.1.3.4). 

Not possible. Both the source and execution character sets are the IBM PC character set. Thus, all 
characters in the source character set map directly to the execution character set. 

The value of an integer character constant that contains more than one character or a wide character 
constant that contains more than one multibyte character (6.1.3.4). 

A multi-character constant is stored with the right-most character in the lowest-older (least 
significant) byte, and subsequent characters (moving to the left) being placed in higher-order (more 
significant) bytes. Up to four characters may be placed in a character constant. 

The current locale used to convert multibyte characters into corresponding wide characters (codes) 
for a wide character constant (6.1.3.4). 

The Open Watcom C 16 and C 32 compilers currently support only the "C" locale, using North 
American English, and translates code page 437 to UNICODE. 
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To support multibyte characters, a command line switch can be used to indicate which multibyte 
character set to use. See the User’s Guide for details. 

Whether a plain char has the same range of values as signed char or unsigned char (6.2.1.1). 

Open Watcom C 16 and C 32 treat char as unsigned, although a compiler command line switch can 
be used to make it signed. 


H.5 Integers 

The representations and sets of values of the various types of integers (6.1.2.5). 

Integers are stored using 2’s complement form. The high bit of each signed integer is a sign bit. If the 
sign bit is 1, the value is negative. 

The ranges of the various integer types are described in the section "Integer Types". 

The result of converting an integer to a shorter signed integer, or the result of converting an 
unsigned integer to a signed integer of equal length, if the value cannot be represented (6.2.1.2). 

When converting to a shorter type, the high-order bits of the longer value are discarded, and the 
remaining bits are interpreted according to the new type. 

For example, converting the signed long integer -15584170 (hexadecimal 0xFF123456)toa 
signed short integer yields the result 13398 (hexadecimal 0x3456). 

When converting an unsigned integer to a signed integer of equal length, the bits are simply 
re-interpreted according to the new type. 

For example, converting the unsigned short integer 65535 (hexadecimal OxFFFF) to a signed short 
integer yields the result -1 (hexadecimal OxFFFF). 

The results of bitwise operations on signed integers (6.3). 

The sign bit is treated as any other bit during bitwise operations. At the completion of the operation, 
the new bit pattern is interpreted according to the result type. 

The sign of the remainder on integer division (6.3.5). 

The remainder has the same sign as the numerator (left operand). 

The result of a right shift of a negative-valued signed integral type (6.3.7). 

A right shift of a signed integer will leave the higher, vacated bits with the original value of the high 
bit. In other words, the sign bit is propogated to fill bits vacated by the shift. 

For example, the result of ((short) 0x0123) >> 4 would be 0x0012 . The result of 
((short) OxFEFE) >> 4 will be OxFFEF. 
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H.6 Floating Point 

The representations and sets of values of the various types of floating-point numbers (6.1.2.5). 

These are discussed in the section "Floating-Point Types". The floating-point format used is the IEEE 
Standard for Binary Floating-Point Arithmetic as defined in the ANSI/IEEE Standard 754-1985. 

The direction of truncation when an integral number is converted to a floating-point number that 
cannot exactly represent the original value (6.2.1.3). 

Truncation is only possible when converting a long int (signed or unsigned) to float. The 24 
most-significant bits (including sign bit) are used. The 25th is examined, and if it is 1, the value is 
rounded up by adding one to the 24-bit value. The remaining bits are ignored. 

The direction of truncation or rounding when a floating-point number is converted to a narrower 
floating-point number (6.2.1.4). 

The value is rounded to the nearest value in the smaller type. 


H.7 Arrays and Pointers 

The type of integer required to hold the maximum size of an array — that is, the type of the sizeof 
operator, size_ t (6.3.3.4, 7.1.1). 

unsigned int 

The result of casting an integer to a pointer or vice versa (6.3.4). 


Open Watcom C 16 conversion of pointer to integer: 


Pointer 

short int 


Type 

int 

long int 

near 

result is pointer value 

result is DS register in 
high-order 2 bytes, pointer 
value in low-order 2 bytes 

far 

segment is discarded, result 

result is segment in high- 

huge 

is pointer offset (low-order 

order 2 bytes, offset in 


2 bytes of pointer) 

low-order 2 bytes 
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Open Watcom C 16 conversion of integer to pointer: 


Integer 

Type 

near pointer 

far pointer 
huge pointer 

short int 

result is integer value 

result segment is DS 

int 


register, offset is 
integer value 

long int 

result is low-order 2 bytes 

result segment is high- 


of integer value 

order 2 bytes, offset is 
low-order 2 bytes 


Open Watcom C 32 

conversion of pointer to integer: 


Pointer 

Type 

short 

int 

long int 

near 

result is low-order 2 bytes 
of pointer value 

result is pointer value 


segment is discarded, result 
is low-order 2 bytes of 
pointer value 

segment is discarded, result 
is pointer offset 

Open Watcom C 32 

conversion of integer to pointer: 


Integer 

Type 

near pointer 

far pointer 
huge pointer 

short int 

result is integer value, 
with zeroes for high-order 

2 bytes 

result segment is DS 
register, offset is integer 
value, with zeroes for 
high-order 2 bytes 

int 
long int 

result is integer value 

result segment is DS 
register, offset is 
integer value 


The type of integer required to hold the difference between two pointers to elements of the same 
array, ptrdif f_ t (6.3.6,7.1.1). 

If the huge memory model is being used, ptrdif f_ t has typelong int. 

For all other memory models, ptrdif f_ t has typeint. 

If two huge pointers are subtracted and the huge memory model is not being used, then the result type 
will be long int even though ptrdif f_ t isint. 
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H.8 Registers 

The extent to which objects can actually be placed in registers by use of the register storage-class 
specifier (6.5.1). 

The Open Watcom C 16 and C 32 compilers may place any object that is sufficiently small, including a 
small structure, in one or more registers. 

The number of objects that can be placed in registers varies, and is decided by the compiler. The 
keyword register does not control the placement of objects in registers. 


H.9 Structures, Unions, Enumerations and Bit-Fields 

A member of a union object is accessed using a member of a different type (6.3.2.3). 

The behavior is undefined. Whatever bit values are present as were stored via one member will be 
extracted via another. 

The padding and alignment of members of structures (6.5.2.1). 

The Open Watcom C 16 and C 32 compilers align structure members by default. A command line 
switch, or the pack pragma, may be used to override the default. See the User’s Guide for default 
values and other details. 

Whether a "plain" int bit-field is treated as a signed int bit-field or as an unsigned int 
bit-field (6.5.2.1). 

signed int 

The order of allocation of bit-fields within a unit (6.5.2.1). 

Low-order (least significant) bit to high-order bit. 

Whether a bit-field can straddle a storage-unit boundary (6.5.2.1). 

Bit-fields may not straddle storage-unit boundaries. If there is insufficient room to store a subsequent 
bit-field in a storage-unit, then it will be placed in the next storage-unit. 

The integer type chosen to represent the values of an enumeration type (6.5.2.2). 

By default. Open Watcom C 16 and C 32 will use the smallest integer type that can accommodate all 
values in the enumeration. The first appropriate type will be chosen according to the following table: 
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Type 

Smallest Value 

Largest Value 

signed char 
unsigned char 
signed short 
unsigned short 
signed long 
unsigned long 
signed long long 
unsigned long long 

-128 

0 

-32768 

0 

-2147483648 

0 

-9223372036854775808 

0 

127 

255 

32767 

65535 

2147483647 

4294967295 

9223372036854775807 

18446744073709551615 


Both compilers have a command-line switch that force all enumerations to type int. See the User’s 
Guide for details. 


H.10 Qualifiers 


What constitutes an access to an object that has volatile-qualified type (6.5.5.3). 

Any reference to a volatile object is also an access to that object. 


H.11 Declarators 


The maximum number of declarators that may modify an arithmetic, structure or union type (6.5.4). 

Limited only by available memory. 


H.12 Statements 


The maximum number of case values in a switch statement (6.6.4.2). 

Limited only by available memory. 

H.13 Preprocessing Directives 

Whether the value of a single-character character constant in a constant expression that controls 
conditional inclusion matches the value of the same character constant in the execution character set. 
Whether such a character constant may have a negative value (6.8.1). 

The character sets are the same so characters will match. Character constants are unsigned quantities, 
so no character will be negative. 

The method for locating includable source files (6.8.2). 

See the User’s Guide for full details of how included files are located. 

The support of quoted names for includable source files (6.8.2). 
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See the User’s Guide for full details of how included files are located. 

The mapping of source file character sequences (6.8.2). 

The source and execution character sets are the same. Escape sequences are not supported in 
preprocessor directives. 

The behavior of each recognized #pragma directive (6.8.6). 

See the User’s Guide. 

The definitions for _ _ DATE _and_ TIME _when respectively, the date and time of translation 

are not available (6.8.8). 

The date and time are always available. 

H.14 Library Functions 

The null pointer constant to which the macro NULL expands (7.1.6). 

For Open Watcom C 16 , the NULL macro expands to 0 for the small and medium (small data) memory 
models, and to OL for the compact, large and huge (big data) memory models. 

For Open Watcom C 32 , the NULL macro expands to 0 . 

The implementation-defined behavior of the library functions is described in the Open Watcom C Library 
Reference manual. 
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I. Examples of Declarations 


This chapter presents a series of examples of declarations of objects and functions. Along with each 
example is a description that indicates how to read the declaration. 

This chapter may be used as a "cookbook" for declarations. Some complicated but commonly required 
declarations are given here. 

The first examples are very simple, and build in complexity. Some of the examples given near the end of 
each section are unlikely to ever be required in a real program, but hopefully they will provide an 
understanding of how to read and write C declarations. 

To reduce the complexity and to better illustrate how a small difference in the declaration can mean a big 
difference in the meaning, the following rules are followed: 

1. if an object is being declared, it is called x or X, 

2. if a function is being declared, it is called F, 

3. if an object is being declared, it usually has type int, although any other type may be 
substituted, 

4. if a function is being declared, it usually returns type int, although any other type may be 
substituted. 

Storage class specifiers (extern, static, auto or register) have purposely been omitted. 

1.1 Object Declarations 

Here are some examples of object (variable) declarations: 


int x; 

2 1 

(l) x is an ( 2 ) integer. 

int * x; 

3 2 1 

(l) x is a ( 2 ) pointer to an (3) integer. 
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int ** x; 

4 32 1 

(l)xisa (2)pointer to a (3)pointer to an (4) integer. 

const int x; 

2 3 1 

(l)xisa (2)constant (3)integer. 

int const x; 

3 2 1 

(l)xisa (2)constant (3)integer (same as above). 

const int * x; 

3 4 2 1 

(l) x is a ( 2 ) pointer to a (3) constant (4) integer. The value of x may change, but the integer that it 
points to may not be changed. In other words, *x cannot be modified. 

int * const x; 

4 3 2 1 

(l) x is a ( 2 ) constant (3) pointer to an (4) integer. The value of x may not change, but the integer 
that it points to may change. In other words, x will always point at the same location, but the 
contents of that location may vary. 

const int * const x; 

4 5 3 2 1 

(l)xisa ( 2 ) constant (3) pointer to a (4) constant (5) integer. The value of x may not change, and 
the integer that it points to may not change. In other words, x will always point at the same 
location, which cannot be modified via x . 

int x [ ]; 

3 12 

(l)xisan (2) array of (3) integers. 

int x[53]; 

4 123 

(l)xisan ( 2 )arrayof (3)53 (4)integers. 

int * x [ ]; 

4 3 12 

(l)xisan (2) array of (3)pointers to (4) integer. 

int (*x) [] ; 

4 213 

(l)xisa (2) pointer to an (3) array of (4) integers. 

int * (*x) [] ; 

5 4 21 3 

(l)xisa (2) pointer to an (3) array of (4) pointers to (5) integer. 
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int (*x) () ; 

4 213 

(l)xisa (2)pointer to a (3)function returning an (4(integer. 

int (*x[25]) 0 ; 

6 4123 5 

(l)xisan ( 2 ) array of (3)25 (4) pointers to (5) functions returning an (6) integer. 


1.2 Function Declarations 


Here are some examples of function declarations: 

int F (); 

3 12 

(l) F is a ( 2 ) function returning an (3) integer. 

int * F (); 

4 3 12 

(l)Fisa (2) function returning a (3) pointer to an (4) integer. 

int (*F() ) () ; 

5 312 4 

(l)Fisa (2) function returning a (3) pointer to a (4) function returning an (5) integer. 

int * (*F() ) () ; 

6 5 312 4 

(l)Fisa (2) function returning a (3) pointer to a (4) function returning a (5) pointer to an 
(6) integer. 

int (*F() ) []; 

5 312 4 

(l)Fisa (2) function returning a (3)pointer to an (4) array of (5) integers. 

int (*(*F() ) [] ) () ; 

7 5 312 4 6 

(l) F is a ( 2 ) function returning a (3) pointer to an (4) array of (5) pointers to (6) functions returning 
an (7) integer. 

int * (* (*F() ) [] ) () ; 

875 312 4 6 

(l) F is a ( 2 ) function returning a (3) pointer to an (4) array of (5) pointers to (6) functions returning 
a (7) pointer to an (8) integer. 

1.3 _ Jar, _ _near and _ _huge Declarations 

The following examples illustrate the use of the_ far and_ huge keywords. 

The use of the_ near keyword is symmetrical with the use of the_ far keyword, so no examples of 

_near are shown. 
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int_far X; 

3 2 1 

( 1 ) X is a ( 2 ) far (3) integer. 

int *_far x; 

4 3 2 1 

(l) x is ( 2 ) far, and is a (3) pointer to an (4) integer. 

int_far * x; 

4 2 3 1 

(l)xisa ( 2 )far (3)pointer to an (4(integer. 

int_far *_far x; 

5 3 4 2 1 

(l)xis (2) far, and is a (3) far (4) pointer to an (5) integer. 

int_far X [ ] ; 

4 2 13 

(l)Xisa (2)far (3) array of (4)integers. 

int_ huge X [ ] ; 

4 2 13 

(l) x is a ( 2 ) huge (3) array of (4) integers (X is an array that can exceed 64K in size.) 

int *_far X [ ] ; 

5 4 2 13 

(l)Xisa (2)far (3)arrayof (4)pointers to (5)integers. 

int_far * X [ ] ; 

5 3 4 12 

(l)Xisan (2) array of (3) far (4)pointers to (5) integers. 

int_far *_far X [ ] ; 

6 4 5 2 13 

(l)Xisa (2)far (3) array of (4)far (5)pointers to (6)integers. 

int_far F () ; 

4 2 13 

(l) F is a ( 2 ) far (3) function returning an (4) integer. 

int *_far F () ; 

5 4 2 13 

(l)Fisa (2) far (3) function returning a (4) pointer to an (5) integer. 

int_far * F () ; 

5 3 4 12 

(l)Fisa (2) function returning a (3) far (4)pointer to an (5) integer. 
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int_far *_far F () ; 

6 4 5 2 13 

(l) F is a ( 2 ) far (3) function returning a (4) far (5) pointer to an (6) integer. 

int (_far * x) () ; 

5 2 3 1 4 

(l) x is a ( 2 ) far (3) pointer to a (4) function returning an (5) integer. 

int_far * (* x) () ; 

6 4 5 2 1 3 

(l) x is a ( 2 ) pointer to a (3) function returning a (4) far (5) pointer to an (6) integer. 

int_far * (_far * x) () ; 

7 5 6 2 3 1 4 

(l) x is a ( 2 ) far (3) pointer to a (4) function returning a (5) far (6) pointer to an < 7) integer. 

1.4 _ _interrupt Declarations 

The following example illustrates the use of the_interrupt keyword. 

void_interrupt_far F () ; 

5 3 2 14 

(l)Fisa (2) far (3) interrupt (4) function returning (5) nothing. 
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J. A Sample Program 


This chapter presents an entire C program, to illustrate many of the features of the language, and to 
illustrate elements of programming style. 

This program implements a memo system suitable for maintaining a set of memos, and displaying them on 
the screen. The program allows the user to display memos relevant to today’s date, move through the 
memos adding new ones and replacing or deleting existing ones. The program displays help information 
whenever an invalid action is entered, or when the sole parameter to the program is a question mark. 

The program is in complete conformance to the ISO C standard. It should be able to run, without 
modification, on any system that provides an ISO-conforming C compiler. 


J.1 The memos.h File 

The source file memos . h contains the structures used for storing the memos: 

/* This structure is for an individual line in a memo. 

*/ 

typedef struct text_ line { 

struct text_ line * next; 
char text[1]; 

} TEXT_ LINE; 

/* This structure is the head of an individual memo. 

*/ 

typedef struct memo_ el { 

struct memo_ el * prev; 
struct memo_ el * next; 

TEXT_ LINE * text; 

char date[9]; 

} MEMO_ EL; 
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J.2 The memos.c File 

The source for the program follows: 

♦include <stdio.h> 

♦include <stdlib.h> 

♦include <string.h> 

♦include <ctype.h> 

♦include <time.h> 

♦include "memos.h" 

/* This program implements a simple memo facility. 

* Memos may be added to a memo file, displayed 

* on the screen, and deleted. 

* Modified by reason 

~k - == - 

* 87/10/02 Steve McDowell Initial implementation. 

* 88/09/20 Steve McDowell Fixed up some style issues, 

* introduced use of TRUE and 

* FALSE. 

*/ 

/* Define some constants to make the code more readable. 

*/ 

♦define TRUE 1 

♦define FALSE 0 

♦define NULLCHAR '\0' 

static const char FileName[] = { "memos.db" }; 
static const char TempName[] = { "tempmemo.db" }; 

static MEMO_ EL * MemoHead = NULL; 

static int MemosModified = FALSE; 

static int QuitFlag = TRUE; 

typedef enum { 

INVALID, 

HELP, 

ADD, 

DELETE, 

REPLACE, 

SHOW, 

UP, 

DOWN, 

TOP, 

TODAY, 

SAVE, 

QUIT 
} ACTION; 

/* This table maps action keywords onto the "actions" defined 

* above. The table also defines short forms for the keywords. 

*/ 

typedef struct { 

ACTION act; 
char * keyword; 

} ACTION_ MAP; 
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static ACTION_ MAP KeywordMap [ ] = { 

HELP, "help", 

HELP, "h", 

ADD, "add", 

ADD, "a", 

DELETE, "delete", 

DELETE, "del", 

REPLACE, "replace", 

REPLACE, "rep", 

SHOW, "show", 

SHOW, "sh", 

UP, "up", 

UP, "u", 

DOWN, "down", 

DOWN, "d", 

DOWN, "", 

TOP, "top", 

TODAY, "today", 

TODAY, "tod", 

SAVE, "save", 

SAVE, "sa", 

QUIT, "quit", 

QUIT, "q", 

INVALID, "" }; 

/* Maximum buffer length (maximum length of line of memo). 
*/ 

♦define MAXLEN 80 

/* Function prototypes. 

*/ 

static TEXT_ LINE * AddLine () ; 
static MEMO_ EL * AddMemo () ; 

static MEMO_ EL * DeleteMemo(); 

static MEMO_ EL * DoActionsO; 

static MEMO_ EL * DoDownAction(); 

static MEMO_ EL * DoUpAction(); 

static MEMO_ EL * EnterAMemo(); 

static ACTION GetActionO; 

static void * MemoMAlloc(); 

static ACTION PromptAction(); 

static ACTION ReadAction(); 

static MEMO_ EL * ReadAMemoO; 

static MEMO_ EL * ShowTodaysMemos() ; 

extern int main( int argc, char * argv[] ) 
/****************************************/ 

{ 

int index; 

MEMO_ EL * el; 

printf( "Memo facility\n" ) ; 

/* Check for a single argument that is a question mark, 

* If found, then display the usage notes. 

*/ 

if( argc == 2 && strcmp( argv[l], "?" ) == 0 ) { 

Usage(); 
exit ( 0 ); 

} 

ReadMemos (); 

MemosModified = FALSE; 

QuitFlag = FALSE; 


The memos.c File 209 




Appendices 


/* Use the command line parameters, if any, as the first 
* actions to be performed on the memos. 

*/ 

el = NULL; 

for( index = 1; index < argc; ++index ) { 

el = DoActions( el, GetAction( argv[index] ) ); 

if( QuitFlag ) { 

return( FALSE ) ; 

} 

} 

HandleMemoActions( el ) ; 
return( FALSE ) ; 


static void ReadMemos( void ) 

/***************************/ 

/* Read the memos file, building the structure to contain it. 
*/ 

{ 

FILE * fid; 

MEMO_ EL * new_ el; 

MEMO_ EL * prev_ el; 
int mcount; 

fid = fopen( FileName, "r" ); 
if( fid == NULL ) { 

printf( "Memos file not found." 

" Starting with no memos.\n" ); 

return; 

} 

/* Loop reading entire memos. 

*/ 

prev_ el = NULL; 
for( mcount = 0;; mcount++ ) { 

new_ el = ReadAMemo ( fid ); 
if ( new_ el == NULL ) { 

printf( "%d memo(s) found.\n", mcount ); 

fclose( fid ); 

return; 

} 

if ( prev_ el == NULL ) { 

MemoHead = new_ el; 
new_ el->prev = NULL; 

} else { 

prev_ el->next = new_ el; 
new_ el->prev = prev_ el; 

} 

new_ el->next = NULL; 
prev_ el = new_ el; 



static int ReadLine( char buffer[], int len, FILE * fid ) 
/*******************************************************/ 

/* Read a line from the memos file. Handle any I/O errors and 

* EOF. Return the length read, not counting the newline on 

* the end. 

*/ 

{ 

if( fgets( buffer, len, fid ) == NULL ) { 

if( feof( fid ) ) { 

return( EOF ) ; 

} 

perror( "Error reading memos file" ); 
abort() ; 

} 

return( strlen( buffer ) - 1 ); 

} 
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static MEMO_ EL * ReadAMemo ( FILE * fid ) 
/**************************************/ 

/* Read one memo, creating the memo structure and filling it 
* in. Return a pointer to the memo (NULL if none read). 

*/ 

{ 

MEMO_ EL * el; 
int len; 

TEXT_ LINE * line; 

char buffer[MAXLEN]; 

len = ReadLine( buffer, MAXLEN, fid ); 
if( len == EOF ) { 

return( NULL ) ; 

} 

/* First line must be of the form "Date:" or "Date:YY/MM/DD": 
*/ 

if( (len != 5 && len != 13) 

|| strncmp( buffer, "Date:", 5 ) != 0 ) { 

BadFormat(); 

} 

buffer[len] = NULLCHAR; 

el = MemoMAlloc ( sizeof ( MEMO_ EL ) ) ; 

el->text = NULL; 

strcpy( el->date, buffer + 5 ); 

line = NULL; 

for( ;; ) { 

len = ReadLine( buffer, MAXLEN, fid ); 
if( len == EOF ) { 

BadFormat() ; 

} 

buffer[len] = NULLCHAR; 
if( strcmp( buffer, "====" ) == 0 ) { 

return( el ) ; 

} 

line = AddLine( buffer, el, line ); 



static TEXT_ LINE * AddLine ( char buffer [], 

MEMO_ EL * el, 

TEXT_ LINE * prevline ) 

/************************************************/ 

/* Add a line of text to the memo, taking care of all the 
* details of modifying the structure. 

*/ 

{ 

TEXT_ LINE * line; 

line = MemoMAlloc ( sizeof ( TEXT_ LINE ) + strlen ( buffer ) ); 
strcpy( line->text, buffer ); 
line->next = NULL; 
if( prevline == NULL ) { 

el->text = line; 

} else { 

prevline->next = line; 

} 

return( line ); 

} 
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static ACTION PromptAction( void ) 
/********************************/ 

/* The user didn't specify an action on the command line, 
* so prompt for it. 

*/ 

{ 

ACTION act; 

for( ;; ) { 

printf( "\nEnter an action:\n" ); 
act = ReadAction() ; 
if( act != INVALID ) { 

return ( act ); 

} 

printf( "\nThat selection was not valid.\n" ); 
Help () ; 



static ACTION ReadAction( void ) 

/******************************/ 

/* Read an action from the terminal. 

* Return the action code. 

*/ 

{ 

char buffer [ 80]; 

if( gets ( buffer ) == NULL ) { 

perror ( "Error reading action" ); 
abort(); 

} 

return] GetAction( buffer ) ); 

} 

static ACTION GetAction] char buffer]] ) 
/**************************************/ 

/* Given the string in the buffer, return the action that 

* corresponds to it. 

* The string in the buffer is first zapped into lower case 

* so that mixed-case entries are recognized. 

*/ 

{ 

ACTION_ MAP * actmap; 
char * bufptr; 

for( bufptr = buffer; *bufptr != NULLCHAR; ++bufptr ) { 

*bufptr = tolower( *bufptr ) ; 

} 

for( actmap = KeywordMap; actmap->act != INVALID; ++actmap ) { 

if( strcmp( buffer, actmap->keyword ) == 0 ) break; 

} 

return( actmap->act ) ; 

} 


static void HandleMemoActions ( MEMO_ EL * el ) 
/*******************************************/ 


/* Handle all the actions entered from the keyboard. 
*/ 

{ 

for 

el = DoActions( el, PromptAction]) ); 
if( QuitFlag ) break; 
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static MEMO_ EL * DoActions ( MEMO_ EL * el, ACTION act ) 
/****************************************************/ 

/* Perform one action on the memos. 

*/ 

{ 

MEMO_ EL * new_ el; 

MEMO_ EL * prev_ el; 

switch( act ) { 

case HELP: 

Help () ; 
break; 
case ADD: 

new_ el = AddMemo ( el ) ; 
if ( new_ el != NULL ) { 

el = new_ el; 

MemosModified = TRUE; 

} 

break; 

case DELETE: 

el = DeleteMemo( el ); 

MemosModified = TRUE; 
break; 

case REPLACE: 
prev_ el = el; 
new_ el = AddMemo ( el ) ; 
if ( new_ el != NULL ) { 

DeleteMemo ( prev_ el ) ; 

MemosModified = TRUE; 

} 

break; 
case SHOW: 

DisplayMemo( el ); 
break; 
case UP: 

el = DoUpAction( el ); 
break; 
case DOWN: 

el = DoDownAction( el ); 
break; 
case TOP: 
el = NULL; 
break; 
case TODAY: 

el = ShowTodaysMemos(); 
break; 
case SAVE: 

if ( SaveMemosO ) { 

MemosModified = FALSE; 

} 

break; 
case QUIT: 

if ( WantToQuitO ) { 

QuitFlag = TRUE; 
el = NULL; 

} 

} 

return( el ); 

} 
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static MEMO_ EL * AddMemo ( MEMO_ EL * el ) 
/**************************************/ 

/* Add a memo following the current one. 
*/ 

{ 

MEMO_ EL * new_ el; 

MEMO_ EL * next; 

new_ el = EnterAMemo () ; 
if ( new_ el == NULL ) { 

return ( NULL ); 

} 

if( el == NULL ) { 

next = MemoHead; 

MemoHead = new_ el; 

} else { 

next = el->next; 
el->next = new_ el; 

} 

new_ el->prev = el; 
new_ el->next = next; 
if( next != NULL ) { 

next->prev = new_ el; 

} 

return ( new_ el ) ; 


static MEMO_ EL * EnterAMemo ( void ) 
/*********************************/ 

/* Read a memo from the keyboard, creating the memo structure 

* and filling it in. Return a pointer to the memo (NULL if 

* none read). 

*/ 

{ 

MEMO_ EL * el; 
int len; 

TEXT_ LINE * line; 

char buffer[MAXLEN]; 

printf( "What date do you want the memo displayed" 

" (YY/MM/DD)?\n" ); 
if( gets( buffer ) == NULL ) { 

printf( "Error reading from terminal.\n" ); 
return( NULL ) ; 

} 

len = strlen( buffer ); 
if( len != 0 

&& (len != 8 

buffer[2] != '/' 

j buffer[5] !='/') ) { 

printf( "Date is not valid.\n" ); 
return( NULL ) ; 

} 

el = MemoMAlloc ( sizeof ( MEMO_ EL ) ) ; 

el->text = NULL; 

strcpy( el->date, buffer ); 

line = NULL; 

printf( "\nEnter the text of the memo.\n" ); 
printf( "To terminate the memo," 

" enter a line starting with =\n" ) ; 

for( ;; ) { 

if( gets( buffer ) == NULL ) { 

printf( "Error reading from terminal.\n" ); 
return( NULL ); 

} 
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if( buffer[0] == '=' ) { 

return( el ) ; 

} 

line = AddLine( buffer, el, line ); 



static MEMO_ EL * DeleteMemo ( MEMO_ EL * el ) 
/*****************************************/ 

/* Delete the current memo. 

* Return a pointer to another memo, usually the following one. 
*/ 

{ 

MEMO_ EL * prev; 

MEMO_ EL * next; 

MEMO_ EL * ret_ el; 

if( el == NULL ) { 

return( MemoHead ); 

} 

prev = el->prev; 
next = el->next; 
ret_ el = next; 
if ( ret_ el == NULL ) { 

ret_ el = prev; 


/* If it's the first memo, set a new MemoHead value. 
*/ 

if( prev == NULL ) { 

MemoHead = next; 
if( next != NULL ) { 

next->prev = NULL; 


} else { 

prev->next = next; 
if( next != NULL ) { 

next->prev = prev; 


DisposeMemo( el ); 
return ( ret_ el ); 


static MEMO_ EL * DoUpAction ( MEMO_ EL * el ) 
/*****************************************/ 

/* Perform the UP action, including displaying the memo. 
*/ 

{ 

if( el == NULL ) { 

DisplayTop() ; 

} else { 

el = el->prev; 

DisplayMemo( el ); 

} 

return( el ) ; 

} 
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static MEMO_ EL * DoDownAction ( MEMO_ EL * el ) 
/*******************************************/ 

/* Perform the DOWN action, including displaying the memo. 
*/ 

{ 

MEMO_ EL * next_ el; 

next_ el = (el == NULL) ? MemoHead : el->next; 
if ( next_ el == NULL ) { 

printf( "No more memos.\n" ); 

} else { 

el = next_ el; 

DisplayMemo( el ); 

} 

return ( el ); 

} 


static MEMO_ EL * ShowTodaysMemos( void ) 
/**************************************/ 

/* Show all memos that either: 

* (1) match today's date 

* (2) don't have a date stored. 

* Return a pointer to the last displayed memo. 

*/ 

{ 

MEMO_ EL * el; 

MEMO_ EL * last_ el; 
time_ t timer; 

struct tm ltime; 
char date[9]; 

/* Get today's time in YY/MM/DD format. 

*/ 

time( &timer ); 

ltime = *localtime( &timer ); 

strftime( date, 9, "%y/%m/%d", Sltime ); 

last_ el = NULL; 

for( el = MemoHead; el != NULL; el = el->next ) { 

if( el->date[0] == NULLCHAR 

strcmp( date, el->date ) == 0 ) { 

DisplayMemo( el ) ; 
last_ el = el; 


return ( last_ el ) ; 

} 


static void DisplayMemo ( MEMO_ EL * el ) 
/*************************************/ 

/* Display a memo on the screen. 

*/ 

{ 

TEXT_ LINE * tline; 

iff el == NULL ) { 

DisplayTop(); 
return; 

} 

iff el->date[0] == NULLCHAR ) { 

printff "\nUndated memo\n" ); 

} else { 

printf( "\nDated: %s\n", el->date ); 

} 

for ( tline = el->text; tline != NULL; tline = tline->next ) { 

printf( " %s\n", tline->text ); 
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static int SaveMemos( void ) 

/**************************I 


/* Save the memos to the memos file. 
*/ 


FILE * fid; 

MEMO_ EL * el; 

TEXT_ LINE * tline; 
char buffer[20]; 


if( MemoHead == NULL ) { 

printf( "No memos to save.\n" ); 
return( FALSE ); 

} 


/* Open a temporary filename in case something goes wrong 

* during the save. 

*/ 

fid = fopen( TempName, "w" ); 
if( fid == NULL ) { 

printf( "Unable to open \"%s\" for writing.\n", TempName ); 
printf( "Save not performed.\n" ); 
return( FALSE ) ; 

} 

for( el = MemoHead; el != NULL; el = el->next ) { 

sprintf( buffer, "Date:%s", el->date ); 
if( !WriteLine( buffer, fid ) ) { 

return( FALSE ); 

} 

tline = el->text; 

for( ; tline != NULL; tline = tline->next ) { 

if( !WriteLine( tline->text, fid ) ) { 

return( FALSE ); 

} 

} 

if( !WriteLine( "====", fid ) ) { 

return( FALSE ); 

} 

} 

/* Now get rid of the old file, if it's there, then rename 

* the new one. 

*/ 

fclose ( fid ); 

fid = fopen ( FileName, "r" ); 
if( fid != NULL ) { 

fclose( fid ); 

if( remove) FileName ) != 0 ) { 

perror( "Can't remove old memos file" ); 
return( FALSE ); 

} 

} 

if( rename) TempName, FileName ) != 0 ) { 

perror) "Can't rename new memos file" ); 
return( FALSE ); 

} 

return ( TRUE ); 

} 

static int WriteLine( char * text, FILE * fid ) 
/*********************************************/ 

{ 

if) fprintf( fid, "%s\n", text ) < 0 ) { 

perror) "Error writing memos file" ); 
return( FALSE ); 

} 

return ( TRUE ); 

} 
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/* Routines for displaying HELP and other simple text. 
*/ 


static void Usage( void ) 

/***********************i 


{ 


printf( 
printf( 
printf( 
printf( 
printf( 
printf( 
printf( 
printf( 
printf( 
printf( 
printf( 


Usage:\n" ); 

memos ?\n" ); 

displays this text\n" ); 
or\n" ); 

memos\n" ); 

prompts for all actions.\n" 
or\n" ); 

memos action\n" ) ; 

performs the action.\n" ); 
More than one action may be 
action is one of:\n" ); 


ShowActions() ; 


) ; 


specified.\n" 


) ; 


static void ShowActions( void ) 
/*****************************/ 
{ 


printf( " 

Help 

printf( " 

Add 

printf( " 

DELete 

printf( " 

REPlace 

printf( " 

SHow 

printf( " 

Up 

printf( " 

Down 

printf( " 

TOP 

printf( " 

TODay 

printf( " 

SAve 


static void Help( void ) 

/**********************i 

{ 

printf( "Choose one of:\n" ); 
ShowActions() ; 

printf( " Quit\n" 

} 


(display this text)\n" ); 

(add new memo here)\n" ) ; 

(delete current memo)\n" ); 

(replace current memo)\n" ); 

(show the current memo again)\n" ); 
(move up one memo)\n" ); 

(move down one memo)\n" ); 

(move to the top of the list\n" ); 
(display today's memos)\n" ); 

(write the memos to disk)\n" ); 


static void DisplayTop( void ) 

/**************************** j 

{ 

printf( "Top of memos.\n" ); 

} 


static int WantToQuit( void ) 

/***************************/ 

/* Check to see if the memos have been modified, but not saved. 

* If so, query the user to make sure that he/she wants to quit 

* without saving the memos. 

*/ 

{ 

char buffer[MAXLEN]; 

if( IMemosModified || MemoHead == NULL ) { 

return( TRUE ); 

} 

printf( "\nThe memos have been modified but not saved.\n" ); 
printf( "Do you want to leave without saving them?\n" ); 
gets( buffer ); 

return( tolower( buffer[0] ) == 'y' ); 

} 
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static void BadFormat( void ) 

/***************************i 
{ 

printf( "Invalid format for memos file\n" ); 
abort(); 

} 

static void * MemoMAlloc( int size ) 
/**********************************/ 

/* Allocate the specified size of memory, dealing with the 
* case of a failure by displaying a message and quitting. 

*/ 

{ 

register char * mem; 

mem = malloc( size ) ; 
if( mem == NULL ) { 

printf( "Unable to allocate %d characters of memory\n", 
size ); 

abort (); 

} 

return ( mem ); 


static void DisposeMemo ( MEMO_ EL * el ) 
/*************************************/ 

/* Dispose of a memo, including its lines. 
*/ 

{ 

TEXT_ LINE * tline; 

TEXT_ LINE * next; 

tline = el->text; 
while( tline != NULL ) { 

next = tline->next; 
free( tline ); 
tline = next; 

} 

free( el ); 
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address An address is a location in a computer’s memory. Each storage location (byte) has an 

address by which it is referenced. A pointer is an address. 

aggregate An aggregate type is either an array or a structure. The term aggregate refers to the fact 
that arrays and structures are made up of other types. 

alignment On some computers, objects such as integers, pointers and floating-point numbers may be 
stored only at certain addresses (for example, only at even addresses). An attempt to 
reference an object that is not properly aligned may cause the program to fail. Other 
computers may not require alignment, but may suggest it in order to increase the speed of 
execution of programs. 

C compilers align all objects that require it, including putting padding characters within 
structures and arrays, if necessary. However, it is still possible for a program to attempt to 
reference an improperly-aligned object. 

The Open Watcom C 16 and C 32 compilers align structure members by default. A 

command line switch, or the pack pragma, may be used to control this behavior. 

Other objects may also be aligned by default. 

See the User’s Guide for default values and other details. 


argument An argument to a function call is an expression whose value is assigned to the parameter 
for the function. The function may modify the parameter, but the original argument is 
unaffected. This method of passing values to a function is often called call by value. 

The argument may be a pointer to an object, in which case the function may modify the 
object to which the pointer points, while the argument value (the pointer) is unaffected. 

array An array is a set of objects of the same type, grouped into adjacent memory locations. 

References to elements of the array are made by subscripts or indices. 

assignment Assignment is the storing of a value into an object, which is usually done with the = 
operator. 

automatic storage duration 

An object with automatic storage duration is created when the function in which it is 
defined is invoked, and is destroyed when the function returns to the caller. 

bit A bit is the smallest possible unit of information, representing one of two values, 0 or 1. If 

the bit is 0, it is said to be off. If the bit is 1, it is said to be on. 

A bit is not representable by an address, but is part of a byte, which does have an address. 


Glossary 221 






Appendices 


Most processors, including the Intel 80x86 family of processors, have 8 bits in a 
byte. 

bit-field A bit-field is a type that contains a specified number of bits. 

block A block is a part of a function that begins with { and ends with } and contains declarations 

of objects and statements that perform some action. A block is also called a compound 
statement. 

byte A byte is the smallest unit of storage representable by a unique address, usually capable of 

holding one character of information. 

Most processors, including the Intel 80x86 family of processors, have 8 bits in a 
byte. 

cast To cast an object is to explicitly convert it to another type. 

character constant 

A character constant is usually one character (possibly a trigraph or escape sequence) 
contained within single-quotes (for example, ' a' , ' ? ? (' and ' \n' ). 

The Open Watcom C 16 and C 32 compilers allow character constants with one, 
two, three or four characters. 

comment A comment is a sequence of characters, outside of a string literal or character constant, 

starting with / * and ending with * / . The comment is only examined to find the * / that 
terminates it. Hence, a comment may not contain another comment. 

compiler A compiler is a program which reads a file containing programming language statements 
and translates it into instructions that the computer can understand. 

For example, a C compiler translates statements described in this book. 

compound statement 

A compound statement is a part of a function that begins with { and ends with } and 
contains declarations of objects and statements that perform some action. A compound 
statement is also called a block. 

declaration A declaration describes the attributes of an object or function, such as the storage duration, 
linkage, and type. The space for an object is reserved when its definition is found. The 
declaration of a function describes the function arguments and type and is also called a 
function prototype. The declaration of a function does not include the statements to be 
executed when the function is called. 

decrement To decrement a number is to subtract (one) from it. To decrement a pointer is to decrease 
its value by the size of the object to which the pointer points. 

definition A definition of an object is the same as a declaration, except that the storage for the object 
is reserved when its definition is found. A function definition includes the statements to be 
executed when the function is called. 
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exception An exception occurs when an operand to an operator has an invalid value. Division by zero 
is a common exception. 

floating-point A floating-point number is a member of a subset of the mathematical set of real numbers, 
containing (possibly) a fraction and an exponent. The floating-point type is represented by 
one of the keywords float, double or long double. 

function A function is a collection of declarations and statements, preceded by a declaration of the 

name of the function and the parameters to it, as well as a possible return value. The 
statements describe a series of steps to be taken after the function is called, and before it 
finishes. 

header A header contains C source, usually function prototypes, structure and union definitions, 

linkages to externally-defined objects and macro definitions. A header is included using 
the #include preprocessor directive. 

identifier An identifier is a sequence of characters, starting with a letter or underscore, and consisting 
of letters, digits and underscores. An identifier is used as the name of an object, a tag, 
function, typedef, label, macro or member of a structure or union. 

implementation-defined behavior 

Behavior that is implementation-defined depends on how a particular C compiler handles a 
certain case. All C compilers must document their behavior in these cases. 

incomplete type 

An incomplete type is one which has been declared, but its size or structure has not yet 
been stated. An example is an array of items that was declared without specifying how 
many items. The void type is also an incomplete type, but it can never be completed. 

increment To increment a number is to add (one) to it. To increment a pointer is to increase its value 
by the size of the object to which the pointer points. 

index An index (or subscript) is a number used to reference an element of an array. It is an 

integral value. The first element of an array has the index zero. 

indirection Indirection occurs when an object that is a pointer to an object is actually used to point to it. 
The unary form of the * operator, or the -> operator are used for indirection. 

initialization The initialization of an object is the act of giving it its first (initial) value. This may be 

done by giving an initialization value when the object is declared, or by explicitly assigning 
it a value. 

integer An integer is a type that is a subset of the mathematical set of integers. It is represented by 

the keyword int, and has a number of variations including signed char, unsigned 
char, short signed int, short unsigned int, signed int, unsigned 
int, long signed int, long unsigned int, long long signed int and 
long long unsigned int. 

integral promotion 

An object or constant that is a char, short int, int bit-field, or of enum type, that is 
used in an expression, is promoted to an int (if int is large enough to contain all possible 
values of the smaller type) or unsigned int. 
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keyword A keyword is an identifier that is reserved for use by the compiler. No object name or other 

use of an identifier may use a keyword. 

label A label is an identifier that corresponds to a particular statement in a function. It may be 

used by the goto statement, default is a special label which is used with the switch 
statement. 

library function 

A library function is a function provided with the C compiler that performs some 
commonly needed action. The C language standard describes a set of functions that all C 
compilers must provide. Whether or not the function actually generates a function call is 
implementation-defined. 

line A line is conceptually similar to a line as seen in a text editor. The line in a text editor may 

be called a physical line. Several physical lines may be joined together into one logical line 
(or just "line") by ending all but the last line with a \ symbol. C does not normally require 
statements to fit onto one line, so using the \ symbol is usually only necessary when 
defining macros. 

linkage An object with external linkage may be referenced by any module in the program. An 

object with internal linkage may be referenced only within the module in which it is 
defined. An object with no linkage may only be referenced within the block in which it is 
defined. 

lint lint is a utility program, often provided with the compiler, which detects problems that the 

compiler will accept as syntactically valid, but likely are not what the programmer 
intended. 

lvalue An lvalue is an expression that designates an object. The term originally comes from the 

assignment expression, 

L = R 

in which the left operand L to the assignment operator must be a modifiable value. The 
most common form of lvalue is the identifier of an object. 

If an expression E evaluates to a pointer to an object, then *E is an lvalue that designates 
the object to which E points. In particular, if E is declared as a "pointer to int", then both 
E and *E are lvalues having the respective types "pointer to int" and int. 

macro There are two kinds of macros. An object-like macro is an identifier that is replaced by a 

sequence of tokens. A function-like macro is an apparent function call which is replaced by 
a sequence of tokens. 

module Referred to in the C language standard as a translation unit, a module is usually a file 

containing C source code. A module may include headers or other source files, and have 
conditional compilation (preprocessing directives), object declarations, and/or functions. A 
module is thus considered to be a C source file after the included files and conditional 
compilation have been processed. 

name space A name space is a category of identifiers. The same identifier may appear in different 
name spaces. For example, the identifier thing may be a label, object name, tag and 
member of a structure or union, all at the same time, since each of these has its own name 
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space. The syntax of the use of the identifier resolves which category the identifier falls 
into. 

nesting Nesting is placing something inside something else. For example, a for statement may, as 

part of its body, contain another for statement. The second for is said to be nested inside 
the first. Another form of nesting occurs when source files include other files. 

null pointer constant 

The value zero, when used in a place where a pointer type is expected, is considered to be a 
null pointer constant, which is a value that indicates that the pointer does not currently 
point to anything. The compiler interprets the zero as a special value, and does not 
guarantee that the actual value of the pointer will be zero. 

The macro NULL is often used to represent the null pointer constant. 

null character The character with all bits set to zero is used to terminate strings, and is called the null 
character. It is represented by the escape sequence \ 0 in a string, or as the character 
constant ' \ 0'. 

object An object is a collection of bytes in the storage of the computer, used to represent values. 

The size and meaning of the object is determined by its type. A scalar object is often 
referred to as a variable. 

parameter A parameter to a function is a "local copy" of the argument values determined in the call to 
the function. Any modification of a parameter value does not affect the argument to the 
function call. However, an argument (and hence a parameter) may be a pointer to an 
object, in which case the function may modify the object to which its parameter points. 

pointer An object that contains the address of another object is said to be a pointer to that object. 

portable Portable software is written in such a way that it is relatively easy to make the software run 

on different hardware or operating systems. 

precedence Precedence is the set of implicit rules for determining the order of execution of an 
expression in the absence of parentheses. 

preprocessor The preprocessor: 

• examines tokens for macros and does appropriate substitutions if necessary, 

• includes headers or other source files, and, 

• includes or excludes input lines based on #if directives 

before the compiler translates the source. 

recursion Recursion occurs when a. function calls itself either directly, or by calling another function 
which calls it. See recursion. (!) 

register A register is a special part of the computer, usually not part of the addressable storage. 

Registers may contain values and are generally faster to use than storage. 

The keyword register may be used when declaring an object with automatic storage 
duration, indicating to the compiler that this object will be heavily used, and the compiler 
should attempt to optimize the use of this object, possibly by placing it in a machine 
register. 
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return value A return value is the value returned by a function via the return statement. 

rounding A value is rounded when the representation used to store a value is not exact. The value 

may be increased or decreased to the nearest value that may be accurately represented. 

scalar A scalar is an object that is not a structure, union or array. Basically, it is a single item, 

with type such as character, any of the various integer types, or floating-point. 

scope The scope of an identifier identifies the part of the module that may refererence it. An 

object with block scope may only be referenced within the block in which it is defined. An 
object with file scope may be referred to anywhere within the file in which it is defined. 

sequence point A sequence point is a point at which all side-effects from previously executed statements 
will have been resolved, and no side-effects from statements not yet executed will have 
occurred. Normally, the programmer will not need to worry about sequence points, as it is 
the compiler’s job to ensure that side-effects are resolved at the proper time. 

side-effect A side-effect modifies a value of an object, causing a change in the state of the program. 

The most common side-effect is assignment, whereby the value of the left operand is 
changed. 

signed A signed value can represent both negative and positive values. 

The keyword signed may be used with the types char, short int, int, long int 
and long long int. 

statement A statement describes the actions that are to be taken by the program. (Statements are 
distinct from the declarations of objects.) 

static storage duration 

An object with static storage duration is created when the program is invoked, and 
destroyed when the program exits. Any value stored in the object will remain until 
explicitly modified. 

string A string is a sequence of characters terminated by a null character. A reference to a string 

is made with the address of the first character. 

string literal A string literal is a sequence of zero or more characters enclosed within double-quotes and 
is a constant. Adjacent string literals are concatenated into one string literal. The value of 
a string literal is the sequence of characters within the quotes, plus a null character (\0) 
placed at the end. 

structure A structure is a type which is a set of named members of (possibly different) types, which 
reside in memory starting at adjacent and sequentially increasing storage locations. 

subscript A subscript (or index ) is a number used to reference an element of an array. It is a 

non-negative integral value. The first element of an array has the subscript zero. 
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tag A tag is an identifier which names a structure, union or enumeration. In the declaration, 

enum nums { ZERO, ONE, TWO } value; 

nums is the tag of the enumeration, while value is an object declared with the 
enumeration type. 

token A token is the unit used by the preprocessor for scanning for macros, and by the compiler 

for scanning the input source lines. Each identifier, constant and comment is one token, 
while other characters are each, individually, one token. 

type The type of an object describes the size of the object, and what interpretation is to be used 

when using the value of the object. It may include information such as whether the value is 
signed or unsigned, and what range of values it may contain. 

undefined behavior 

Undefined behavior occurs when an erroneous program construct or bad data is used, and 
the standard does not impose a behavior. Possible actions of undefined behavior include 
ignoring the problem, behaving in a documented manner, terminating the compilation with 
an error, and terminating the execution with an error. 

union A union is a type which is a set of named members of (possibly different) types, which 

reside in memory starting at the same memory location. 

unsigned An unsigned value is one that can represent only non-negative values. 

The keyword unsigned may be used with the types char, short int, int, 
long int and long long int. 

variable A variable is generally the same thing as an object. It is most often used to refer to scalar 

objects. 

void The void type is a special type that really indicates "no particular type". An object that is 

a "pointer to void" may not be used to point at anything without it first being cast to the 
appropriate type. 

The keyword void is also used as the type of a function that has no return value, and as the 
parameter list of a function that requires no parameters. 
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1 Header Files 


The following header files are supplied with the Open Watcom C++ library. When a class or function from 
the library is used in a source file the related header file should be included in that source file. The header 
files can be included multiple times and in any order with no ill effect. 

The facilities of the C standard library can be used in C++ programs by including the appropriate "cname" 
header. In that case all of the C standard library functions are in namespace std. For example, to use 
function std: : print f one should include the header cstdio. Note that the cname headers declare in the 
global namespace any non-standard names they contain as extensions. It is also possible to include in a 
C++ program the same headers used by C programs. In that case, the standard functions are in both the 
global namespace as well as in namespace std. 

Some of C++ standard library headers described below come in a form with a .h extension and in a form 
without an extension. The extensionless headers declare their library classes and functions in namespace 
std . The headers with a .h extension declare their library classes and functions in both the global 
namespace and in namespace std . Such headers are provided as a convenience and for compatibility with 
legacy code. Programs that intend to conform to Standard C++ should use the extensionless headers to 
access the facilities of the C++ standard library. 

Certain headers defined by Standard C++ have names that are longer than the 8.3 limit imposed by the 
FAT16 filesystem. Such headers are provided with names that are truncated to eight characters so they can 
be used with the DOS host. However, one can still refer to them in #include directives using their full 
names as defined by the standard. If the Open Watcom C++ compiler is unable to open a header with the 
long name, it will truncate the name and try again. 

The Open Watcom C++ library contains some components that were developed before C++ was 
standardized. These legacy components continue to be supported and are described in this documentation. 

The header files are all located in the \WATCOM\H directory. 

algorithm (algorith) This header file defines the standard algorithm templates. 

complex This header file defines the std: : complex class template and related function templates. 

This template can be instantiated for the three different floating point types. It can be used 
to represent complex numbers and to perform complex arithmetic. 

complex.h This header file defines the legacy Complex class. This class is used to represent complex 
numbers and to perform complex arithmetic. The class defined in this header is not the 
Standard C++ std: : complex class template. 

exception/exception.h (exceptio/exceptio.h) This header file defines components to be used with the 
exception handling mechanism. It defines the base class of the standard exception 
hierarchy. 

functional (function) This header file defines the standard functional templates. This includes the functors 
and binders described by Standard C++. 
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fstream/fstream.h This header file defines the filebuf, fstreambase, if stream, of stream, and 
f stream classes. These classes are used to perform C++ file input and output operations. 
The various class members are declared and inline member functions for the classes are 
defined. 

generic.h This header file is part of the macro support required to implement generic containers prior 
to the introduction of templates in the C++ language. It is retained for backwards 
compatibility. 

iomanip/iomanip.h This header file defines the parameterized manipulators. 

ios/ios.h This header file defines the class ios that is used as a base of the other iostream classes. 

iosfwd/iosfwd.h This header file provides forward declarations of the iostream classes. It should be used in 
cases where the full class definitions are not needed but where one still wants to declare 
pointers or references to iostream related objects. Typically this occurs in a header for 
another class that wants to provide overloaded inserter or extractor operators. By including 
iosfwd instead of iostream (for example), compilation speed can be improved because 
less material must be processed by the compiler. 

Note that including iosfwd is the only appropriate way to forward declare the iostream 
classes. Manually writing forward declarations is not recommended. 

iostream/iostream.h This header file (indirectly) defines the ios, istream, ostream, and iostream 
classes. These classes form the basis of the C++ formatted input and output support. The 
various class members are declared and inline member functions for the classes are defined. 
The cin, cout, cerr, and clog predefined objects are declared along with the 
non-parameterized manipulators. 

istream/istream.h This header file defines class istream and class iostream. It also defines their 
associated parameterless manipulators. 

This header file defines several templates to facilitate the handling of iterators. In 
particular, it defines the std: : iterator_ traits template as well as several other 
supporting iterator related templates. 

This header file defines the std: : umeric_ limits template and provides 
specializations of that template for each of the built-in types. 

Note that this header is not directly related to the header limits.h from the C standard 
library (or to the C++ form of that header, climits). 

This header file defines the std: : list class template. It provides a way to make a 
sequence of objects with efficient insert and erase operations. 

This header file defines the std: :mapand std: :multimap class templates. They 
provide ways to associate keys to values. 

This header file defines the default allocator template, std: : allocator, as well as 
several function templates for manipulating raw (uninitialized) memory regions. In 
addition this header defines the std: : auto_ ptr template. 

Note that the header memory. h is part of the Open Watcom C library and is unrelated to 
memory. 


iterator 

limits 

list 

map 

memory 
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new/new.h This header file provides declarations to be used with the intrinsic operator new and 

operator delete memory management functions. 

numeric This header file defines several standard algorithm templates pertaining to numerical 

computation. 

ostream/ostream.h This header file defines class ostream. It also defines its associated parameterless 
manipulators. 

set This header file defines the std: :set and std: :multiset class templates. They 

provide ways to make ordered collections of objects with efficient insert, erase, and find 
operations. 

stdiobuf.h This header file defines the stdiobuf class which provides the support for the C++ input 
and output operations to standard input, standard output, and standard error streams. 

streambuf/streambuf.h (streambu/streambu.h) This header file defines the streambuf class which 
provides the support for buffering of input and output operations. This header file is 
automatically included by the iostreara. h header file. 

string This header file defines the std: :basic_ string class template. It also contains the 

type definitions for std: : string and std::wstring. In addition, this header 
contains specializations of the std: : char_ traits template for both characters and 
wide characters. 

string.hpp This header file defines the legacy String class. The String class is used to 

manipulate character strings. Note that the hpp extension is used to avoid colliding with 
the Standard C string. h header file. The class defined in this header is not the Standard 
C++ std: : string class. 

strstream.h (strstrea.h) This header files defines the strstreambuf, strstreambase, 

istrstream, ostrstream, and strstream classes. These classes are used to 
perform C++ in-memory formatting. The various class members are declared and inline 
member functions for the classes are defined. 

This header contains the std: : vector class template. 

This header file contains definitions used by the Open Watcom legacy container libraries. 

If a container class needs any of these definitions, the file is automatically included. 

Note that all headers having names that start with "wc" are related to the legacy container 
libraries. 

This header file defines the base classes which are used by the list containers. 

This header file defines the classes which are common to the list containers. 

This header file defines the base classes which are used by the list iterators. 

This header file defines the list container classes. The available list container classes are 
single and double linked versions of intrusive, value and pointer lists. 

This header file defines the iterator classes that correspond to the list containers. 


vector 

wcdefs.h 

wclbase.h 

wclcom.h 

wclibase.h 

wclist.h 

wclistit.h 
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wcqueue.h 


This header file defines the queue class. Entries in a queue class are accessed first in, first 
out. 


wcstack.h 


This header file defines the stack class. Entries in a stack class are accessed last in, first 
out. 


6 Header Files 




2 Common Types 


The set of classes that make up the C++ class library use several common typedefs and macros. They are 
declared in <iostream.h> and <fstream.h>. 

typedef long streampos; 
typedef long streamoff; 
typedef int filedesc; 

#def ine_NOT_ EOF 0 

#define EOF -1 

The streampos type represents an absolute position within the file. For Open Watcom C++, the file 
position can be represented by an integral type. For some file systems, or at a lower level within the file 
system, the stream position might be represented by an aggregate (structure) containing information such as 
cylinder, track, sector and offset. 

The streamoff type represents a relative position within the file. The offset can always be represented 
as a signed integer quantity since it is a number of characters before or after an absolute position within the 
file. 

The filedesc type represents the type of a C library file handle. It is used in places where the I/O stream 
library takes a C library file handle as an argument. 

The_NOT_ EOF macro is defined for cases where a function needs to return something other thaBOF to 

indicate success. 

The EOF macro is defined to be identical to the value provided by the <stdio . h> header file. 
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3 Predefined Objects 


Most programs interact in some manner with the keyboard and screen. The C programming language 
provides three values, stdin, stdout and stderr, that are used for communicating with these 
"standard" devices, which are opened before the user program starts execution at main (). These three 
values are FILE pointers and can be used in virtually any file operation supported by the C library. 

In a similar manner, C++ provides seven objects for communicating with the same "standard" devices. 

C++ provides the three C FILE pointers stdin, stdout and stderr, but they cannot be used with the 
extractors and inserters provided as part of the C++ library. C++ provides four new objects, called cin, 
cout, cerr and clog, which correspond to stdin, stdout, stderr and buffered stderr. 


3.1 cin 


cin is an istream object which is connected to "standard input" (usually the keyboard) prior to program 
execution. Values extracted using the istream operator >> class extractor operators are read from 
standard input and interpreted according to the type of the object being extracted. 

Extractions from standard input via cin skip whitespace characters by default because the ios : : skipws 
bit is on. The default behavior can be changed with the ios : : setf public member function or with the 
setiosflags manipulator. 


3.2 cout 


cout is an ostream object which is connected to "standard output" (usually the screen) prior to program 
execution. Values inserted using the ostream operator << class inserter operators are converted to 
characters and written to standard output according to the type of the object being inserted. 

Insertions to standard output via cout are buffered by default because the ios : : unitbuf bit is not on. 
The default behavior can be changed with the ios : : set f public member function or with the 
setiosflags manipulator. 


3.3 cerr 


cerr is an ostream object which is connected to "standard error" (the screen) prior to program 
execution. Values inserted using the ostream operator << class inserter operators are converted to 
characters and written to standard error according to the type of the object being inserted. 

Insertions to standard error via cerr are not buffered by default because the ios : : unitbuf bit is on. 
The default behavior can be changed with the ios : : set f public member function or with the 
setiosflags manipulator. 
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3.4 clog 

clog is an ostream object which is connected to "standard error" (the screen) prior to program 
execution. Values inserted using the ostream operator << class inserter operators are converted to 
characters and written to standard error according to the type of the object being inserted. 

Insertions to standard error via clog are buffered by default because the ios : : unitbuf bit is not on. 
The default behavior can be changed with the ios : : set f public member function or with the 
setiosf lags manipulator. 
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4 istream Input 


This chapter describes formatted and unformatted input. 

4.1 Formatted Input: Extractors 

The operator >> function is used to read formatted values from a stream. It is called an extractor. 
Characters are read and interpreted according to the type of object being extracted. 

All operator >> functions perform the same basic sequence of operations. First, the input prefix 
function ipf x is called with a parameter of zero, causing leading whitespace characters to be discarded if 
ios : : skipws is set in ios : : fmtf lags. If the input prefix function fails and returns zero, the 
operator >> function also fails and returns immediately. If the input prefix function succeeds, 
characters are read from the stream and interpreted in terms of the type of object being extracted and 
ios : : fmtf lags. Finally, the input suffix function isfx is called. 

The operator >> functions return a reference to the specified stream so that multiple extractions can be 
done in one statement. 

Errors are indicated via ios : : iostate. ios : : failbit is set if the characters read from the stream 
could not be interpreted for the required type, ios : : badbit is set if the extraction of characters from 
the stream failed in such a way as to make subsequent extractions impossible, ios : : eofbit is set if the 
stream was located at the end when the extraction was attempted. 

4.2 Unformatted Input 

The unformatted input functions are used to read characters from the stream without interpretation. 

Like the extractors, the unformatted input functions follow a pattern. First, they call ipfx, the input prefix 
function, with a parameter of one, causing no leading whitespace characters to be discarded. If the input 
prefix function fails and returns zero, the unformatted input function also fails and returns immediately. If 
the input prefix function succeeds, characters are read from the stream without interpretation. Finally, 
isfx, the input suffix function, is called. 

Errors are indicated via the iostate bits, ios : : failbit is set if the extraction of characters from the 
stream failed, ios : : eofbit is set if the stream was located at the end of input when the operation was 
attempted. 
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5 ostream Output 


This chapter describes formatted and unformatted output. 

5.1 Formatted Output: Inserters 

The operator << function is used to write formatted values to a stream. It is called an inserter. Values 
are formatted and written according to the type of object being inserted and ios : : fmt flags. 

All operator << functions perform the same basic sequence of operations. First, the output prefix 
function opf x is called. If it fails and returns zero, the operator << function also fails and returns 
immediately. If the output prefix function succeeds, the object is formatted according to its type and 
ios : : fmtf lags. The formatted sequence of characters is then written to the specified stream. Finally, 
the output suffix function osfx is called. 

The operator << functions return a reference to the specified stream so that multiple insertions can be 
done in one statement. 

For details on the interpretation of ios : : fmtf lags, see the ios : : fmtf lags section of the Library 
Functions and Types Chapter. 

Errors are indicated via ios : : iostate. ios : : failbit is set if the operator << function fails 
while writing the characters to the stream. 

5.2 Unformatted Output 

The unformatted output functions are used to write characters to the stream without conversion. 

Like the inserters, the unformatted output functions follow a pattern. First, they call the output prefix 
function opf x and fail if it fails. Then the characters are written without conversion. Finally, the output 
suffix function osfx is called. 

Errors are indicated via ios : : iostate. ios : : failbit is set if the function fails while writing the 
characters to the stream. 
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6 Library Functions and Types 


Each of the classes and functions in the Class Library is described in this chapter. Each description consists 
of a number of subsections: 

Declared: This optional subsection specifies which header file contains the declaration for a class. It is only found 

in sections describing class declarations. 

Derived From: 

This optional subsection shows the inheritance for a class. It is only found in sections describing class 
declarations. 

Derived By: This optional subsection shows which classes inherit from this class. It is only found in sections 
describing class declarations. 

Synopsis: This subsection gives the name of the header file that contains the declaration of the function. This 

header file must be included in order to reference the function. 

For class member functions, the protection associated with the function is indicated via the presence of 
one of the private, protected, or public keywords. 

The full function prototype is specified. Virtual class member functions are indicated via the presence 
of the virtual keyword in the function prototype. 

Semantics: This subsection is a description of the function. 

Derived Implementation Protocol: 

This optional subsection is present for virtual member functions. It describes how derived 
implementations of the virtual member function should behave. 

Default Implementation: 

This optional subsection is present for virtual member functions. It describes how the default 
implementation provided with the base class definition behaves. 

Results: This optional subsection describes the function’s return value, if any, and the impact of a member 

function on its object’s state. 

See Also: This optional subsection provides a list of related functions or classes. 


Functions and Types 15 




Open Watcom C++ Class Library Reference 


16 Functions and Types 




7 Complex Class 


This class is used for the storage and manipulation of complex numbers, which are often represented by 
real and imaginary components (Cartesian coordinates), or by magnitude and angle (polar coordinates). 
Each object stores exactly one complex number. An object may be used in expressions in the same manner 
as floating-point values. 

The class documented here is the Open Watcom legacy complex class. It is not the std: : complex class 
template specified by Standard C++. 


Complex Class 
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Complex 


Declared: 


complex.h 

The Complex class is used for the storage and manipulation of complex numbers, which are often 
represented by real and imaginary components (Cartesian coordinates), or by magnitude and angle 
(polar coordinates). Each Complex object stores exactly one complex number. A Complex object 
may be used in expressions in the same manner as floating-point values. 

Public Member Functions 


The following constructors and destructors are declared: 
Complex(); 

Complex( Complex const S ) ; 

Complex! double, double = 0.0 ); 
-Complex(); 


The following arithmetic member functions are declared: 


Complex 

Complex 

Complex 

Complex 

Complex 

Complex 

Complex 

Complex 

Complex 

Complex 

Complex 

Complex 

double 

double 


Soperator =( Complex const 
Soperator =( double ); 
Soperator +=( Complex const 
Soperator +=( double ); 
Soperator -=( Complex const 
Soperator -=( double ); 
Soperator *=( Complex const 
Soperator *=( double ); 
Soperator /=( Complex const 
Soperator /=( double ); 
operator +() const; 
operator -() const; 
imag() const; 
real() const; 


S 


S 

S 

S 

S 


) ; 
) ; 
) ; 
) ; 


Friend Functions 


The following I/O Stream inserter and extractor friend functions are declared: 

friend istream Soperator >>( istream S, Complex S ); 
friend ostream Soperator <<( ostream S, Complex const S ); 

Related Operators 


The following operators are declared: 


Complex 

operator 

+ ( 

Complex 

const 

&, 

Complex 

const 

S 

) ; 

Complex 

operator 

+ ( 

Complex 

const 

&, 

double 

r 



Complex 

operator 

+ ( 

double 


t 

Complex 

const 

S 

) ; 

Complex 

operator 

-( 

Complex 

const 

&, 

Complex 

const 

S 

) ; 

Complex 

operator 

-( 

Complex 

const 

&, 

double 

r 



Complex 

operator 

-( 

double 


t 

Complex 

const 

S 

) ; 

Complex 

operator 

* ( 

Complex 

const 

&, 

Complex 

const 

S 

) ; 

Complex 

operator 

* ( 

Complex 

const 

&, 

double 

r 



Complex 

operator 

* ( 

double 


t 

Complex 

const 

S 

) ; 

Complex 

operator 

/ ( 

Complex 

const 

&, 

Complex 

const 

S 

) ; 

Complex 

operator 

/ ( 

Complex 

const 

&, 

double 

r 



Complex 

operator 

/ ( 

double 


t 

Complex 

const 

S 

) ; 

int 

operator 

== ( 

Complex 

const 

&, 

Complex 

const 

S 

); 
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Complex 


int 

operator ==( 

Complex 

const 

&, 

double ) 

r 


int 

operator ==( 

double 


t 

Complex 

const 

& ) ; 

int 

operator !=( 

Complex 

const 

&, 

Complex 

const 

& ) ; 

int 

operator !=( 

Complex 

const 

&, 

double ) 

r 


int 

operator !=( 

double 


t 

Complex 

const 

& ); 


Related Functions 


The following related functions are declared: 


double 

abs ( 

Complex 

const 

& 

; 


Complex 

acos ( 

Complex 

const 

& 

; 


Complex 

acosh ( 

Complex 

const 

& 

; 


double 

arg ( 

Complex 

const 

& 

; 


Complex 

asin ( 

Complex 

const 

& 

; 


Complex 

asinh( 

Complex 

const 

& 

; 


Complex 

atan ( 

Complex 

const 

& 

; 


Complex 

atanh( 

Complex 

const 

& 

; 


Complex 

con j ( 

Complex 

const 

& 

; 


Complex 

cos ( 

Complex 

const 

& 

; 


Complex 

cosh ( 

Complex 

const 

& 

; 


Complex 

exp ( 

Complex 

const 

& 

; 


double 

imag ( 

Complex 

const 

& 

; 


Complex 

log ( 

Complex 

const 

& 

; 


Complex 

loglO ( 

Complex 

const 

& 

; 


double 

norm ( 

Complex 

const 

& 

; 


Complex 

polar ( 

double 


t 

double = 

o ) 

Complex 

pow ( 

Complex 

const 

&, 

Complex 

const 

Complex 

pow ( 

Complex 

const 

&, 

double ) 

r 

Complex 

pow ( 

double 


r 

Complex 

const 

Complex 

pow ( 

Complex 

const 

&, 

int ) ; 


double 

real ( 

Complex 

const 

& 

; 


Complex 

sin ( 

Complex 

const 

& 

; 


Complex 

sinh ( 

Complex 

const 

& 

; 


Complex 

sqrt ( 

Complex 

const 

& 

; 


Complex 

tan ( 

Complex 

const 

& 

; 


Complex 

tanh ( 

Complex 

const 

& 

; 
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Complex abs() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <complex.h> 

double abs( Complex const Snum ); 

The abs function computes the magnitude of num, which is equivalent to the length (magnitude) of the 
vector when the num is represented in polar coordinates. 

The abs function returns the magnitude of num. 

arg, norm, polar 
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Complex acos() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <complex.h> 

Complex acos ( Complex const Snum ); 
The acos function computes the arccosine of num. 
The acos function returns the arccosine of num. 
asin, atan, cos 
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Complex acosh() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <complex.h> 

Complex acosh( Complex const Snum ); 

The acosh function computes the inverse hyperbolic cosine of num. 
The acosh function returns the inverse hyperbolic cosine of num. 
asinh, atanh, cosh 
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Complex arg() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <complex.h> 

double arg( Complex const Snum ); 

The arg function computes the angle of the vector when the num is represented in polar coordinates. 
The angle has the same sign as the real component of the num. It is positive in the 1st and 2nd 
quadrants, and negative in the 3rd and 4th quadrants. 

The arg function returns the angle of the vector when the num is represented in polar coordinates, 
abs, norm, polar 


Complex Class 
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Complex asin() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <complex.h> 

Complex asin ( Complex const Snum ); 
The asin function computes the arcsine of num. 
The asin function returns the arcsine of num. 
acos, atan, sin 
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Complex asinhQ 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <complex.h> 

Complex asinh( Complex const Snum ); 

The asinh function computes the inverse hyperbolic sine of num. 
The asinh function returns the inverse hyperbolic sine of num. 
acosh, atanh, sinh 
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Complex atan() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <complex.h> 

Complex atan ( Complex const Snum ); 
The atan function computes the arctangent of num. 
The atan function returns the arctangent of num. 
acos, asin, tan 


26 Complex Class 




Complex atanhQ 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <complex.h> 

Complex atanh( Complex const Snum ); 

The atanh function computes the inverse hyperbolic tangent of mini. 
The atanh function returns the inverse hyperbolic tangent of mini. 
acosh, asinh, tanh 
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Complex::Complex() 


Synopsis: #include <complex.h> 

public: 

Complex::Complex(); 


Semantics: 

Results: 
See Also: 


This form of the public Complex constructor creates a default Complex object with value zero for 
both the real and imaginary components. 

This form of the public Complex constructor produces a default Complex object. 

-Complex, real, imag 
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Complex::Complex() 


Synopsis: 

Semantics: 
Results: 
See Also: 


#include <complex.h> 
public: 

Complex::Complex( Complex const Snum ); 

This form of the public Complex constructor creates a Complex object with the same value as num. 
This form of the public Complex constructor produces a Complex object. 

-Complex, real, imag 
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Complex::Complex() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <complex.h> 
public: 

Complex::Complex( double real, double imag = 0.0 ); 

This form of the public Complex constructor creates a Complex object with the real component set to 
real and the imaginary component set to imag. If no imaginary component is specified, imag takes the 
default value of zero. 

This form of the public Complex constructor produces a Complex object. 

-Complex, real, imag 
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Complex::~Complex() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <complex.h> 
public: 

Complex::~Complex() ; 

The public -Complex destructor destroys the Complex object. The call to the public -Complex 
destructor is inserted implicitly by the compiler at the point where the Complex object goes out of 
scope. 

The Complex object is destroyed. 

Complex 
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Complex conj() 


Synopsis: 

Semantics: 


Results: 


♦include <complex.h> 

Complex conj ( Complex const Snum ); 

The conj function computes the conjugate of num. The conjugate consists of the unchanged real 
component, and the negative of the imaginary component. 

The conj function returns the conjugate of num. 
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Complex cos() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <complex.h> 

Complex cos( Complex const Snum ); 

The cos function computes the cosine of num. 

The cos function returns the cosine of num. 

acos, sin, tan 
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Complex cosh() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <complex.h> 

Complex cosh( Complex const Snum ); 

The cosh function computes the hyperbolic cosine of num. 
The cosh function returns the hyperbolic cosine of num. 
acosh, sinh, tanh 
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Complex exp() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <complex.h> 

Complex exp( Complex const Snum ); 

The exp function computes the value of e raised to the power num. 

The exp function returns the value of e raised to the power num. 

log, loglO, pow, sqrt 
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Complex::imag() 


Synopsis: #include <complex.h> 

public: 

double Complex::imag(); 


Semantics: 
Results: 
See Also: 


The imag public member function extracts the imaginary component of the Complex object. 

The imag public member function returns the imaginary component of the Complex object. 

imag, real 
Complex::real 
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Complex imag() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <complex.h> 

double imag( Complex const Snum ); 

The imag function extracts the imaginary component of num. 

The imag function returns the imaginary component of num. 

real 

Complex::imag, real 
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Complex log() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <complex.h> 

Complex log( Complex const Snum ); 

The log function computes the natural, or base e, logarithm of num. 

The log function returns the natural, or base e, logarithm of num. 

exp, loglO, pow, sqrt 
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Complex loglOQ 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <complex.h> 

Complex loglO( Complex const Snum ); 

The loglO function computes the base 10 logarithm of man. 
The loglO function returns the base 10 logarithm of man. 
exp, log, pow, sqrt 
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Complex norm() 


Synopsis: #include <complex.h> 

double norm( Complex const Snum ); 

Semantics: The norm function computes the square of the magnitude of num, which is equivalent to the square of 

the length (magnitude) of the vector when num is represented in polar coordinates. 

Results: The norm function returns the square of the magnitude of num. 

See Also: arg, polar 
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Complex operator !=() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <complex.h> 

int operator !=( Complex const Snuml, Complex const &num2 ); 
int operator !=( Complex const Snuml, double num2 ); 
int operator !=( double numl. Complex const &num2 ); 

The operator ! = function compares numl and iiuni2 for inequality. At least one of the parameters 
must be a Complex object for this function to be called. 

Two Complex objects are not equal if either of their corresponding real or imaginary components are 
not equal. 

If the operator ! = function is used with a Complex object and an object of any other built-in 
numeric type, the non- Complex object is converted to a double and the second or third form of the 
operator ! = function is used. 

The operator ! = function returns a non-zero value if numl is not equal to num2, otherwise zero is 
returned. 

operator == 
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Complex operator *() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <complex.h> 

Complex operator *( Complex const Snuml, Complex const &num2 ); 
Complex operator *( Complex const Snuml, double num2 ); 

Complex operator *( double numl. Complex const &num2 ); 

The operator * function is used to multiply numl by num2 yielding a Complex object. 

The first operator * function multiplies two Complex objects. 

The second operator * function multiplies a Complex object and a floating-point value. In effect, 
the real and imaginary components of the Complex object are multiplied by the floating-point value. 

The third operator * function multiplies a floating-point value and a Complex object. In effect, 
the real and imaginary components of the Complex object are multiplied by the floating-point value. 

If the operator * function is used with a Complex object and an object of any other built-in 
numeric type, the non- Complex object is converted to a double and the second or third form of the 
operator * function is used. 

The operator * function returns a Complex object that is the product of numl and num2. 

operator +, operator -, operator / 

Complex::operator *= 
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Complex::operator *=() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <complex.h> 
public: 

Complex SComplex::operator *=( Complex const Snum ); 

Complex SComplex::operator *=( double num ); 

The operator *= public member function is used to multiply the num argument into the Complex 
object. 

The first form of the operator *= public member function multiplies the Complex object by the 
Complex parameter. 

The second form of the operator *= public member function multiplies the real and imaginary 
components of the Complex object by num. 

A call to the operator *= public member function where num is any of the other built-in numeric 
types, causes num to be promoted to double and the second form of the operator *= public 
member function to be used. 

The operator *= public member function returns a reference to the target of the assignment, 
operator * 

Complex::operator +=, operator -=, operator /=, operator = 
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Complex::operator +() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <complex.h> 
public: 

Complex Complex::operator +(); 

The unary operator + public member function is provided for completeness. It performs no 
operation on the Complex object. 

The unary operator + public member function returns a Complex object with the same value as 
the original Complex object. 

operator + 

Complex::operator +=, operator - 
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Complex operator +() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <complex.h> 

Complex operator +( Complex const Snuml, Complex const &num2 ); 
Complex operator +( Complex const Snuml, double num2 ); 

Complex operator +( double numl. Complex const &num2 ); 

The operator + function is used to add numl to num2 yielding a Complex object. 

The first operator + function adds two Complex objects. 

The second operator + function adds a Complex object and a floating-point value. In effect, the 
floating-point value is added to the real component of the Complex object. 

The third operator + function adds a floating-point value and a Complex object. In effect, the 
floating-point value is added to the real component of the Complex object. 

If the operator + function is used with a Complex object and an object of any other built-in 
numeric type, the non- Complex object is converted to a double and the second or third form of the 
operator + function is used. 

The operator + function returns a Complex object that is the sum of numl and num2. 

operator *,operator -, operator / 

Complex::operator +, operator += 
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Complex::operator +=() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <complex.h> 
public: 

Complex SComplex::operator +=( Complex const Snum ); 

Complex SComplex::operator +=( double num ); 

The operator += public member function is used to add num to the value of the Complex object. 
The second form of the operator += public member function adds num to the real component of the 
Complex object. 

A call to the operator += public member function where num is any of the other built-in numeric 
types, causes num to be promoted to double and the second form of the operator += public 
member function to be used. 

The operator += public member function returns a reference to the target of the assignment, 
operator + 

Complex::operator *=, operator +,operator /=, operator -=, operator = 
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Complex::operator -() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <complex.h> 
public: 

Complex Complex::operator -(); 

The unary operator - public member function yields a Complex object with the real and 
imaginary components having the same magnitude as those of the original object, but with opposite 
sign. 

The unary operator - public member function returns a Complex object with the same magnitude 
as the original Complex object and with opposite sign. 

operator - 

Complex::operator +, operator -= 
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Complex operator -() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <complex.h> 

Complex operator -( Complex const Snuml, Complex const &num2 ); 

Complex operator -( Complex const Snuml, double num2 ); 

Complex operator -( double numl. Complex const &num2 ); 

The operator - function is used to subtract num2 from numl yielding a Complex object. 

The first operator - function computes the difference between two Complex objects. 

The second operator - function computes the difference between a Complex object and a 
floating-point value. In effect, the floating-point value is subtracted from the real component of the 
Complex object. 

The third operator - function computes the difference between a floating-point value and a 
Complex object. In effect, the real component of the result is numl minus the real component of num2 
:CONT, and the imaginary component of the result is the negative of the imaginary component of 
num2. 

If the operator - function is used with a Complex object and an object of any other built-in 
numeric type, the non- Complex object is converted to a double and the second or third form of the 
operator - function is used. 

The operator - function returns a Complex object that is the difference between numl and num2. 

operator *,operator +, operator / 

Complex::operator -, operator -= 
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Complex-operator -=() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <complex.h> 
public: 

Complex SComplex::operator -=( Complex const Snum ); 

Complex SComplex::operator -=( double num ); 

The operator -= public member function is used to subtract num from the value of the Complex 
object. The second form of the operator -= public member function subtracts num from the real 
component of the *obj.. 

A call to the operator -= public member function where num is any of the other built-in numeric 
types, causes num to be promoted to double and the second form of the operator -= public 
member function to be used. 

The operator -= public member function returns a reference to the target of the assignment, 
operator - 

Complex::operator *=, operator +=, operator operator /=, operator = 
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Complex operator/() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <complex.h> 

Complex operator / ( Complex const Snuml, Complex const &num2 ); 
Complex operator /( Complex const Snuml, double num2 ); 

Complex operator /( double numl. Complex const &num2 ); 

The operator / function is used to divide numl by num2 yielding a Complex object. 

The first operator / function divides two Complex objects. 

The second operator / function divides a Complex object by a floating-point value. In effect, the 
real and imaginary components of the complex number are divided by the floating-point value. 

The third operator / function divides a floating-point value by a Complex object. Conceptually, 
the floating-point value is converted to a Complex object and then the division is done. 

If the operator / function is used with a Complex object and an object of any other built-in 
numeric type, the non- Complex object is converted to a double and the second or third form of the 
operator / function is used. 

The operator / function returns a Complex object that is the quotient of numl divided by num2. 

operator *,operator +, operator - 
Complex::operator /= 
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Complex::operator /=() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <complex.h> 
public: 

Complex SComplex::operator /=( Complex const Snum ); 

Complex &Complex::operator /=( double num ); 

The operator /= public member function is used to divide the Complex object by num. The 
second form of the operator /= public member function divides the real and imaginary components 
of the Complex object by num. 

A call to the operator /= public member function where num is any of the other built-in numeric 
types, causes num to be promoted to double and the second form of the operator /= public 
member function to be used. 

The operator / = public member function returns a reference to the target of the assignment, 
operator / 

Complex::operator *=, operator +=, operator -=, operator = 
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Complex operator «() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <complex.h> 

friend ostream Soperator <<( ostream Sstrm, Complex Snum ); 

The operator << function is used to write Complex objects to an I/O stream. The Complex 
object is always written in the form: 

(real,imag) 

The real and imaginary components are written using the normal rules for formatting floating-point 
numbers. Any formatting options specified prior to inserting the num apply to both the real and 
imaginary components. If the real and imaginary components are to be inserted using different formats, 
the real and imag member functions should be used to insert each component separately. 

The operator << function returns a reference to the strm object. 

istream 
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Complex::operator =() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <complex.h> 
public: 

Complex SComplex::operator =( Complex const Snum ); 

Complex SComplex::operator =( double num ); 

The operator = public member function is used to set the value of the Complex object to num. 
The first assignment operator copies the value of num into the Complex object. 

The second assignment operator sets the real component of the Complex object to num and the 
imaginary component to zero. 

A call to the operator = public member function where num is any of the other built-in numeric 
types, causes num to be promoted to double and the second form of the operator = public 
member function to be used. 

The operator = public member function returns a reference to the target of the assignment. 
Complex::operator *=, operator +=, operator -=, operator /= 


Complex Class 53 




Complex operator ==() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <complex.h> 

int operator ==( Complex const Snuml, Complex const &num2 ); 
int operator ==( Complex const Snuml, double num2 ); 
int operator ==( double numl. Complex const &num2 ); 

The operator == function compares numl and iiuni2 for equality. At least one of the arguments 
must be a Complex object for this function to be called. 

Two Complex objects are equal if their corresponding real and imaginary components are equal. 

If the operator == function is used with a Complex object and an object of any other built-in 
numeric type, the non- Complex object is converted to a double and the second or third form of the 
operator == function is used. 

The operator == function returns a non-zero value if numl is equal to mm2, otherwise zero is 
returned. 

operator != 
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Complex operator »() 


Synopsis: 

Semantics: 


Results: 


See Also: 


♦include <complex.h> 

friend istream Soperator >>( istream Sstrm, Complex Snum ); 

The operator >> function is used to read a Complex object from an I/O stream. A valid complex 
value is of one of the following forms: 

(real,imag) 
real,imag 
(real) 

If the imaginary portion is omitted, zero is assumed. 

While reading a Complex object, whitespace is ignored before and between the various components of 
the number if the ios : : skipws bit is set in ios : : fmtf lags. 

The operator >> function returns a reference to strm. num contains the value read from strm on 
success, otherwise it is unchanged. 

istream 
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Complex polarQ 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <complex.h> 

Complex polar( double mag, double angle = 0.0 ); 

The polar function converts mag and angle (polar coordinates) into a complex number. The angle is 
optional and defaults to zero if it is unspecified. 

The polar function returns a Complex object that is mag and angle interpreted as polar coordinates, 
abs, arg, norm 
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Complex pow() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <complex.h> 

Complex pow( Complex const Snum, Complex const &exp ); 

Complex pow( Complex const Snum, double exp ); 

Complex pow( double num. Complex const &exp ); 

Complex pow( Complex const Snum, int exp ); 

The pow function computes num raised to the power exp. The various forms are provided to minimize 
the amount of floating-point calculation performed. 

The pow function returns a Complex object that is num raised to the power a Complex object that is 
exp. 

exp, log, loglO, sqrt 
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Complex::reai() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <complex.h> 
public: 

double Complex::real() ; 

The real public member function extracts the real component of the Complex object. 

The real public member function returns the real component of the Complex object. 

imag, real 
Complex::imag 
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Complex real() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <complex.h> 

double real( Complex const Snum ); 

The real function extracts the real component of num. 

The real function returns the real component of num. 

imag 

Complex::imag, real 
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Complex sin() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <complex.h> 

Complex sin( Complex const Snum ); 

The sin function computes the sine of num. 

The sin function returns the sine of num. 

asin, cos, tan 
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Complex sinh() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <complex.h> 

Complex sinh( Complex const Snum ); 

The sinh function computes the hyperbolic sine of num. 
The sinh function returns the hyperbolic sine of num. 
asinh, cosh, tanh 
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Complex sqrt() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <complex.h> 

Complex sqrt( Complex const Snum ); 
The sqrt function computes the square root of num. 
The sqrt function returns the square root of num. 
exp, log, loglO, pow 
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Complex tan() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <complex.h> 

Complex tan( Complex const Snum ); 

The tan function computes the tangent of num. 

The tan function returns the tangent of num. 

atan, cos, sin 
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Complex tanh() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <complex.h> 

Complex tanh( Complex const Snum ); 

The tanh function computes the hyperbolic tangent of num. 
The tanh function returns the hyperbolic tangent of num. 
atanh, cosh, sinh 
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8 Container Exception Classes 


This chapter describes exception handling for the container classes. 
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WCExcept 


Declared: wcexcept. h 

The WCExcept class provides the exception handling for the container classes. If you have compiled 
your code with exception handling enabled, the C++ exception processing can be used to catch errors. 
Your source file must be compiled with the exception handling compile switch for C++ exception 
processing to occur. The container classes will attempt to set the container object into a reasonable state 
if there is an error and exception handling is not enabled, or if the trap for the specific error has not been 
enabled by your program. 

By default, no exception traps are enabled and no exceptions will be thrown. Exception traps are 
enabled by setting the exception state with the exceptions member function. 

The wcexcept. h header file is included by the header files for each of the container classes. There is 
normally no need to explicitly include the wcexcept. h header file, but no errors will result if it is 
included. This class is inherited as a base class for each of the containers. You do not need to derive 
from it directly. 

The WCListExcept class (formally used by the list container classes) has been replaced by the 
WCExcept class. A typedef of the WCListExcept class to the WCExcept class and the 
wclist_ state type to thewc_ state type provide backward compatability with previous versions 
of the list containers. 

Public Enumerations 

The following enumeration typedefs are declared in the public interface: 
typedef int wc_ state; 

Public Member Functions 

The following public member functions are declared: 

WCExcept (); 

virtual -WCExcept (); 

wc_ state exceptions() const; 

wc_ state exceptions ( wc_ state ) ; 
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WCExcept:: WCExceptQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcexcept.h> 
public: 

WCExcept(); 

This form of the public WCExcept constructor creates an WCExcept object. 

The public WCExcept constructor is used implicitly by the compiler when it generates a constructor 
for a derived class. It is automatically used by the list container classes, and should not be required in 
any user derived classes. 

The public WCExcept constructor produces an initialized WCExcept object with no exception traps 
enabled. 

~WCExcept 
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WCExcept::- WCExceptQ 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcexcept.h> 
public: 

virtual ~WCExcept(); 

The public -WCExcept destructor does not do anything explicit. The call to the public -WCExcept 
destructor is inserted implicitly by the compiler at the point where the object derived from WCExcept 
goes out of scope. 

The object derived from WCExcept is destroyed. 

WCExcept 
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WCExcept::exceptions() 


Synopsis: 


Semantics: 


Results: 


#include <wcexcept.h> 
public: 

wc_ state exceptions() const; 

wc_ state exceptions ( wc_ state set_ flags ); 

The exceptions public member function queries and/or sets the bits that control which exceptions 
are enabled for the list class. Each bit corresponds to an exception, and is set if the exception is 
enabled. The first form of the exceptions public member function returns the current settings of the 
exception bits. The second form of the function sets the exception bits to those specified by set_flags. 

The current exception bits are returned. If a new set of bits are being set, the returned value is the old 
set of exception bits. 
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WCExcept::wc_state 


Synopsis: #include <wcexcept.h> 

public: 

enum wcstate { 

all_ fine = 0x0000, // - no errors 
check_ none = all_fine,// - throw no exceptions 
not_ empty = 0x0001, // - container not empty 
index_ range = 0x0002, // - index is out of range 
empty_ container= 0x0004, // - empty container error 
out_ of_ memory = 0x0008, // - allocation failed 

resize_ required= 0x0010, // - request needs resize 
not_ unique = 0x0020, // - adding duplicate 
zero_ buckets = 0x0040, // - resizing hash to zero 
// value to use to check for all errors 
check_ all = (not_ empty | index_ range | empty_ container 
out_ of_ memory | resize_ required 
not_ unique | zero_ buckets) 

} ; 

typedef int wc_ state; 

Semantics: The type WCExcept: : wcstate is a set of bits representing the current state of the container object. 

The WCExcept: : wc_ state member typedef represents the same set of bits, but uses an int to 
represent the values, thereby avoiding problems made possible by the compiler’s ability to use smaller 
types for enumerations. All uses of these bits should use the WCExcept: : wc_ state member 
typedef. 

The bit values defined by the WCExcept: : wc_ state member typedef can be read and set by the 
exceptions member function, which is also used to control exception handling. 

The WCExcept: : not_ empty bit setting traps the destruction of a container when the container has 
at one or more entries. If this error is not trapped, memory may not be properly released back to the 
system. 

The WCExcept: : index_ range state setting traps an attempt to access a container item by an index 
value that is either not positive or is larger than the index of the last item in the container. 

The WCExcept: : empty_ container bit setting traps an attempt to perform and invalid operation 
on a container with no entries. 

The WCExcept: : out_ of_ memory bit setting traps any container class allocation failures. If this 
exception is not enabled, the operation in which the allocation failed will return a FALSE (zero) value. 
Container class copy constructors and assignment operators can also throw this exception, and if not 
enabled incomplete copies may result. 

The WCExcept: : resize_ required bit setting traps any vector operations which cannot be 
performed unless the vector is resized to a larger size. If this exception is not enabled, the vector class 
will attempt an appropriate resize when necessary for an operation. 

The WCExcept: : not_ unique bit setting traps an attempt to add a duplicate value to a set container, 
or a duplicate key to a dictionary container. The duplicate value is not added to the container object 
regardless of the exception trap state. 

The WCExcept: : zero_ buckets bit setting traps an attempt to resize of hash container to have zero 
buckets. No resize is performed whether or not the exception is enabled. 
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WCIterExcept 


Declared: 


wcexcept.h 

The WCIterExcept class provides the exception handling for the container iterators. If you have 
compiled your code with exception handling enabled, the C++ exception processing can be used to 
catch errors. Your source file must be compiled with the exception handling compile switch for C++ 
exception processing to occur. The iterators will attempt to set the class into a reasonable state if there 
is an error and exception handling is not enabled, or if the trap for the specific error has not been 
enabled by your program. 

By default, no exception traps are enabled and no exceptions will be thrown. Exception traps are 
enabled by setting the exception state with the exceptions member function. 

The wcexcept. h header file is included by the header files for each of the iterator classes. There is 
normally no need to explicitly include the wcexcept. h header file, but no errors will result if it is 
included. This class is inherited as part of the base construction for each of the iterators. You do not 
need to derive from it directly. 

Public Enumerations 

The following enumeration typedefs are declared in the public interface: 
typedef int wciter_ state; 

Public Member Functions 


The following public member functions are declared: 


WCIterExcept(); 
virtual ~WCIterExcept(); 
wciter_ state exceptions () 
wciter_ state exceptions ( 


const; 

wciter_ state ); 
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WCIterExcept:: WCIterExceptQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcexcept.h> 
public: 

WCIterExcept() ; 

This form of the public WCIterExcept constructor creates an WCIterExcept object. 

The public WCIterExcept constructor is used implicitly by the compiler when it generates a 
constructor for a derived class. 

The public WCIterExcept constructor produces an initialized WCIterExcept object with no 
exception traps enabled. 

~WCIterExcept 
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WCIterExcept::-WCIterExceptQ 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcexcept.h> 
public: 

virtual -WCIterExcept() ; 

The public -WCIterExcept destructor does not do anything explicit. The call to the public 
-WCIterExcept destructor is inserted implicitly by the compiler at the point where the object 
derived from WCIterExcept goes out of scope. 

The object derived from WCIterExcept is destroyed. 

WCIterExcept 
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WCIterExcept::exceptions() 


Synopsis: 


Semantics: 


Results: 


#include <wcexcept.h> 
public: 

wciter_ state exceptions () const; 

wciter_ state exceptions ( wciter_ state set_ flags ); 

The exceptions public member function queries and/or sets the bits that control which exceptions 
are enabled for the iterator class. Each bit corresponds to an exception, and is set if the exception is 
enabled. The first form of the exceptions public member function returns the current settings of the 
exception bits. The second form of the function sets the exception bits to those specified by set_flags. 

The current exception bits are returned. If a new set of bits are being set, the returned value is the old 
set of exception bits. 


74 


Container Exception Classes 




WCIterExcept: :wciter_state 


Synopsis: #include <wcexcept.h> 

public: 

enum wciterstate { 

all_ fine = 0x0000, // - no errors 

check_ none = all_fine,// - disable all exceptions 

undef_ iter = 0x0001, // - position is undefined 

undef_ item = 0x0002, // - iterator item is undefined 

iter_ range = 0x0004, // - advance value is bad 

// value to use to check for all errors 
check_ all= (undef_ iter|undef_ item|iter_ range) 

} ; 

typedef int wciter_ state; 

Semantics: The type WCIterExcept: : wciterstate is a set of bits representing the current state of the 

iterator. The WCIterExcept: : wciter_ state member typedef represents the same set of bits, but 
uses an int to represent the values, thereby avoiding problems made possible by the compiler’s ability 
to use smaller types for enumerations. All uses of these bits should use the 
WCIterExcept: :wciter_ state member typedef. 

The bit values defined by the WCIterExcept: : wciter_ state member typedef can be read and 
set by the member function exceptions, which is used to control exception handling. 

The WCIterExcept: : undef_ iter bit setting traps the use of the iterator when the position within 
the container object is undefined. Trying to operate on an iterator with no associated container object, 
increment an iterator which is after the last element, or decrement an iterator positioned before the first 
element is an undefined operation. 

The WCIterExcept: : undef_ item bit setting traps an attempt to obtain the current element of the 
iterator when the iterator has no associated container object, or is positioned either before or after the 
container elements. The undef_ item exception can be thrown only by thekey and value 
dictionary iterator member functions, and the current member function for non-dictionary iterators. 

The WCIterExcept: : iter_ range bit setting traps an attempt to use a iteration count value that 
would place the iterator more than one element past the end or before the beginning of the container 
elements. The iter_ range exception can be thrown only by theoperator += and operator 
-= operators. 
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WCIterExcept::wciter_state 
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9 Container Allocators and Deallocators 


Example 


#include 

#include 

#include 

#include 

#include 

#include 


<iostream.h> 
<wclist.h> 
<wclistit.h> 
<wcskip.h> 
<wcskipit.h> 
<stdlib.h> 


#pragma warning 549 9 
const int ElemsPerBlock = 50; 

// 

// Simple block allocation class. Allocate blocks for ElemsPerBlock 
// elements, and use part of the block for each of the next ElemsPerBlock 
// allocations, incrementing the number allocated elements. Repeat getting 
// more blocks as needed. 

// 

// Store the blocks in an intrusive single linked list. 

// 

// On a element deallocation, assume we allocated the memory and just 
// decrement the count of allocated elements. When the count gets to zero, 
// free all allocated blocks 
// 

// This implementation assumes sizeof( char ) == 1 

// 


class BlockAlloc { 
private: 

// the size of elements (in bytes) 
unsigned elem_ size; 

// number of elements allocated 
unsigned num_ allocated; 

// free space of this number of elements available in first block 
unsigned num_ free_ in_ block; 

// list of blocks used to store elements (block are chunks of memory, 
// pointed by (char *) pointers. 

WCPtrSList<char> block_ list; 

// pointer to the first block in the list 
char *curr_ block; 

public: 

inline BlockAlloc( unsigned size ) 

: elem_ size ( size ), num_ allocated ( 0 ) 

, num_ free_ in_ block ( 0 ) {}; 


inline BlockAlloc() { 

block_ list. clearAndDestroy () ; 

}; 


// get memory for an element using block allocation 
void *allocator( size_ t elem_ size ); 

// free memory for an element using block allocation and deallocation 
void deallocator ( void *old_ ptr, size_ t elem_ size ) ; 
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WCIterExcept::wciter_state 


void *BlockAlloc::allocator( size_ t size ) { 

// need a new block to perform allocation 
if ( num_ free_ in_ block == 0 ) { 

// allocate memory for ElemsPerBlock elements 
curr_ block = new chart size * ElemsPerBlock ]; 
if ( curr_ block == 0 ) { 

// allocation failed 
return( 0 ); 

} 

// add new block to beginning of list 
if ( ! block_ list. insert ( curr_ block ) ) { 

// allocation of list element failed 
delete ( curr_ block ) ; 
return ( 0 ); 

} 

num_ free_ in_ block = ElemsPerBlock; 


// curr block points to a block of memory with some free memory 
num_ allocated++; 
num_ free_ in_ block—; 

// return pointer to a free part of the block, starting at the end 
// of the block 

return ( curr_ block + num_ free_ in_ block * size ) ; 


void BlockAlloc::deallocator( void *, size_ t ) { 

// just decrement the count 

// don't free anything until all elements are deallocated 

num_ allocated—; 

if ( num_ allocated == 0 ) { 

// all the elements allocated BlockAlloc object have now been 
// deallocated, free all the blocks 
block_ list. clearAndDestroy () ; 
num_ free_ in_ block = 0; 



const unsigned NumTestElems = 200; 

// array with random elements 

static unsigned test_ elems [ NumTestElems ] ; 

static void fill_ test_ elems () { 

for ( int i = 0; i < NumTestElems; i++ ) { 

test_ elems [ i ] = rand () ; 



void test_ isv_ list () ; 
void test_ val_ list () ; 
void test_ val_ skip_ list () ; 


void main() { 

fill_ test_ elems () ; 


test_ isv_ list () ; 
test_ val_ list () ; 
test_ val_ skip_ list () ; 


// An intrusive list class 
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Container Allocators and Deallocators 


class isvlnt : public WCSLink { 
public: 

static BlockAlloc memory_ manage; 
int data; 

isvlnt( int datum ) : data( datum ) {}; 

void *operator new ( size_ t size ) { 

return ( memory_ manage. allocator ( size ) ); 

}; 


void operator delete( void *old, size_ t size ) { 

memory_ manage. deallocator ( old, size ); 

}; 


// define static member data 

BlockAlloc isvlnt: :memory_ manage ( sizeof ( isvlnt ) ); 


void test_ isv_ list () { 

WCIsvSList<isvInt> list; 

for( int i = 0; i < NumTestElems; i++ ) { 

list, insert ( new isvlnt ( test_ elems [ i ] ) ); 

} 


WCIsvSListIter<isvInt> iter( list ); 
while( ++iter ) { 

cout « iter.current()->data « 

} 

cout « "\n\n\n"; 
list.clearAndDestroy (); 


// WCValSList<int> memory allocator/dealloctor support 

static BlockAlloc val_ list_ manager( WCValSListltemSize( int ) ); 

static void *val_ list_ alloc ( size_ t size ) { 

return ( val_ list_ manager. allocator ( size ) ); 

} 


static void val_ list_ dealloc ( void *old, size_ t size ) { 

val_ list_ manager. deallocator ( old, size ); 

} 


// test WCValSList<int> 
void test_ val_ list () { 

WCValSList<int> list ( &val_ list_ alloc, &val_ list_ dealloc ) ; 

for ( int i = 0; i < NumTestElems; i++ ) { 

list.insert ( test_ elems[ i ] ); 

} 


WCValSListIter<int> iter( list ); 
while ( ++iter ) { 

cout « iter.current() « " " 

} 

cout « "\n\n\n"; 
list.clear(); 


// skip list allocator dealloctors: just use allocator and dealloctor 
// functions on skip list elements with one and two pointers 
// (this will handle 94% of the elements) 

const int one_ ptr_ size = WCValSkipListltemSize( int, 1 ); 
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WCIterExcept::wciter_state 


const int two_ ptr_ size = WCValSkipListltemSize ( int, 2 ); 

static BlockAlloc one_ ptr_ manager ( one_ ptr_ size ); 
static BlockAlloc two_ ptr_ manager ( two_ ptr_ size ); 

static void *val_ skip_ list_ alloc ( size_ t size ) { 

switch ( size ) { 

case one_ ptr_ size: 

return ( one_ ptr_ manager. allocator ( size ) ); 
case two_ ptr_ size: 

return ( two_ ptr_ manager. allocator ( size ) ); 
default: 

return( new chart size ] ); 



static void val_ skip_ list_ dealloc ( void *old, size_ t size ) { 

switch( size ) { 

case one_ ptr_ size: 

one_ ptr_ manager. deallocator ( old, size ); 
break; 

case two_ ptr_ size: 

two_ ptr_ manager. deallocator ( old, size ); 
break; 
default: 

delete old; 
break; 



// test WCValSkipList<int> 
void test_ val_ skip_ list () { 

WCValSkipList<int> skiplist ( WCSKIPLIST_ PROB_ QUARTER 

, WCDEFAULT_ SKIPLIST_ MAX_ PTRS 
, &val_ skip_ list_ alloc 
, &val_ skip_ list_ dealloc ) ; 

for( int i = 0; i < NumTestElems; i++ ) { 

skiplist. insert ( test_ elems [ i ] ); 

} 


WCValSkipListIter<int> iter( skiplist ); 
while( ++iter ) { 

cout « iter.current() « " "; 

} 

cout « "\n\n\n"; 
skiplist.clear(); 
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10 Hash Containers 


This chapter describes hash containers. 
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WCPtrHashDict<Key, Value> 


Declared: 


wchash.h 

The WCPtrHashDict<Key, Value> class is a templated class used to store objects in a dictionary. 
Dictionaries store values with an associated key, which may be of any type. One example of a 
dictionary used in everyday life is the phone book. The phone numbers are the data values, and the 
customer name is the key. An example of a specialized dictionary is a vector, where the key value is the 
integer index. 

As an element is looked up or inserted into the dictionary, the associated key is hashed. Hashing 
converts the key into a numeric index value which is used to locate the value. The storage area 
referenced by the hash value is usually called a bucket. If more than one key results in the same hash, 
the values associated with the keys are placed in a list stored in the bucket. The equality operator of the 
key’s type is used to locate the key-value pairs. 

In the description of each member function, the text Key is used to indicate the template parameter 
defining the type of the indices pointed to by the pointers stored in the dictionary. The text Value is 
used to indicate the template parameter defining the type of the data pointed to by the pointers stored in 
the dictionary. 

The constructor for the WCPtrHashDict<Key, Value> class requires a hashing function, which 
given a reference to Key, returns an unsigned value. The returned value modulo the number of 
buckets determines the bucket into which the key-value pair will be located. The return values of the 
hash function can be spread over the entire range of unsigned numbers. The hash function return value 
must be the same for values which are equivalent by the equivalence operator for Key. 

Note that pointers to the key values are stored in the dictionary. Destructors are not called on the keys 
pointed to. The key values pointed to in the dictionary should not be changed such that the equivalence 
to the old value is modified. 


The WCExcept class is a base class of the WCPtrHashDict<Key, Value> class and provides the 
exceptions member function. This member function controls the exceptions which can be thrown 
by the WCPtrHashDict<Key,Value> object. No exceptions are enabled unless they are set by the 
exceptions member function. 

Requirements of Key 

The WCPtrHashDict<Key, Value> class requires Key to have: 

A well defined equivalence operator with constant parameters 
( int operator == ( const Key & ) const ). 

Public Member Functions 


The following member functions are declared in the public interface: 


WCPtrHashDict! unsigned (*hash_ fn) ( const Key 
WC_ DEFAULT_ HASH_ SIZE ); 

WCPtrHashDict( unsigned (*hash_ fn) ( const Key 
WC_ DEFAULT_ HASH_ SIZE, void * (*user_ alloc) ( 

(*user_ dealloc) ( void *old, size_ t size ) ); 

WCPtrHashDict( const WCPtrHashDict & ); 
virtual ~WCPtrHashDict() ; 

static unsigned bitHash( const void *, size_ t 
unsigned buckets!) const; 
void clear (); 


& ), unsigned 

& ), unsigned 
size_ t size ) 


void 
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WCPtrHashDict<Key, Value> 


void clearAndDestroy(); 

int contains ( const Key * ) const; 

unsigned entries () const; 

Value * find( const Key * ) const; 

Value * findKeyAndValue( const Key *, Key * & ) const; 
void forAll( void (*user_ fn) ( Key *, Value *, void * ) 
int insert ( Key *, Value * ); 
int isEmptyO const; 

Value * remove( const Key * ) ; 
void resize( unsigned ) ; 

Public Member Operators 

The following member operators are declared in the public interface: 

Value * & operator []( const Key & ); 
const Value * & operator []( const Key & ) const; 
WCPtrHashDict & operator =( const WCPtrHashDict & ); 
int operator ==( const WCPtrHashDict & ) const; 


, void * ) ; 
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WCPtrHashDict<Key, Value>:: WCPtrHashDictQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCPtrHashDict( unsigned (*hash_ fn) ( const Key & ), 
unsigned = WC_ DEFAULT_ HASH_ SIZE ); 

The public WCPtrHashDict<Key, Value> constructor creates an 

WCPtrHashDict <Key, Value> object with no entries and with the number of buckets in the second 
optional parameter, which defaults to the constant WC_ DEFAULT_ HASH_ SIZE (currently defined as 
101). The number of buckets specified must be greater than zero, and will be forced to at least one. If 
the hash dictionary object can be created, but an allocation failure occurs when creating the buckets, the 
table will be created with zero buckets. If the out_ of_ memory exception is enabled, then attempting 
to insert into a hash table with zero buckets with throw an out_ of_ memory error. 

The hash function hash_ f n is used to determine which bucket each key-value pair will be assigned. If 
no hash function exists, the static member function bitHash is available to help create one. 

The public WCPtrHashDict<Key, Value> constructor creates an initialized 
WCPtrHashDict<Key, Value> object with the specified number of buckets and hash function. 

~WCPtrHashDict, bitHash, WCExcept: : out_ of_ memory 
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WCPtrHashDict<Key, Value>:: WCPtrHashDictQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCPtrHashDict ( unsigned (*hash_fn) ( const Key & ), 

unsigned = WC_ DEFAULT_ HASH_ SIZE, 

void * (*user_ alloc) ( size_ t ), 

void (*user_ dealloc) ( void *, size_ t ) ); 

Allocator and deallocator functions are specified for use when entries are inserted and removed from the 
hash dictionary. The semantics of this constructor are the same as the constructor without the memory 
management functions. 

The allocation function must return a zero if it cannot perform the allocation. The deallocation function 
is passed the size as well as the pointer to the data. Your allocation system may take advantage of the 
characteristic that the allocation function will always be called with the same size value for any 
particular instantiation of a hash dictionary. To determine the size of the objects that the memory 
management functions will be required to allocate and free, the following macro may be used: 
WCPtrHashDictltemSize( Key, Value ) 

The public WCPtrHashDict<Key, Value> constructor creates an initialized 
WCPtrHashDict<Key, Value> object with the specified number of buckets and hash function. 

~WCPtrHashDict, bitHash, WCExcept: : out_ of_ memory 
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WCPtrHashDict<Key, Value>:: WCPtrHashDictQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCPtrHashDict( const WCPtrHashDict & ) ; 

The public WCPtrHashDict<Key, Value> constructor is the copy constructor for the 
WCPtrHashDict<Key, Value> class. The new dictionary is created with the same number of 
buckets, hash function, all values or pointers stored in the dictionary, and the exception trap states. If 
the hash dictionary object can be created, but an allocation failure occurs when creating the buckets, the 
table will be created with zero buckets. If there is not enough memory to copy all of the values in the 
dictionary, then only some will be copied, and the number of entries will correctly reflect the number 
copied. If all of the elements cannot be copied, then the out_ of_ memory exception is thrown if it is 
enabled. 

The public WCPtrHashDict<Key, Value> constructor creates an 
WCPtrHashDict<Key, Value> object which is a copy of the passed dictionary. 

~WCPtrHashDict, operator =, WCExcept: : out_ of_ memory 
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WCPtrHashDict<Key, Value>::~ WCPtrHashDictQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wchash.h> 
public: 

virtual ~WCPtrHashDict() ; 

The public ~WCPtrHashDict<Key, Value> destructor is the destructor for the 
WCPtrHashDict<Key, Value> class. If the number of dictionary elements is not zero and the 
not_ empty exception is enabled, the exception is thrown. Otherwise, the dictionary elements are 
cleared using the clear member function. The objects which the dictionary elements point to are not 
deleted unless the clearAndDestroy member function is explicitly called before the destructor is 
called. The call to the public ~WCPtrHashDict<Key, Value> destructor is inserted implicitly by 
the compiler at the point where the WCPtrHashDict<Key, Value> object goes out of scope. 

The public ~WCPtrHashDict<Key, Value> destructor destroys an 
WCPtrHashDict<Key, Value> object. 

clear, clearAndDestroy, WCExcept::not_ empty 
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WCPtrHashDict<Key,Value>::bitHash() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

static unsigned bitHash( void *, size_ t ); 

The bitHash public member function can be used to implement a hashing function for any type. A 
hashing value is generated from the value stored for the number of specified bytes pointed to by the first 
parameter. 

The bitHash public member function returns an unsigned value which can be used as the basis of a 
user defined hash function. 

WCPtrHashDict 
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WCPtrHashDict<Key,Value>::buckets() 


Synopsis: #include <wchash.h> 

public: 

unsigned buckets const; 


Semantics: 

Results: 
See Also: 


The buckets public member function is used to find the number of buckets contained in the 
WCPtrHashDict<Key, Value> object. 

The buckets public member function returns the number of buckets in the dictionary, 
resize 
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WCPtrHashDict<Key,Value>::clear() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchash.h> 

public: 

void clear(); 

The clear public member function is used to clear the dictionary so that it has no entries. The number 
of buckets remain unaffected. Objects pointed to by the dictionary elements are not deleted. The 
dictionary object is not destroyed and re-created by this function, so the object destructor is not invoked. 

The clear public member function clears the dictionary to have no elements. 

~WCPtrHashDict, clearAndDestroy, operator = 
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WCPtrHashDict<Key,Value>::clearAndDestroy() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

void clearAndDestroy(); 

The clearAndDestroy public member function is used to clear the dictionary and delete the objects 
pointed to by the dictionary elements. The dictionary object is not destroyed and re-created by this 
function, so the dictionary object destructor is not invoked. 

The clearAndDestroy public member function clears the dictionary by deleting the objects pointed 
to by the dictionary elements. 

clear 
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WCPtrHashDict<Key,Value>::contains() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchash.h> 
public: 

int contains( const Key * ) const; 

The contains public member function returns non-zero if an element with the specified key is stored 
in the dictionary, or zero if there is no equivalent element. Note that equivalence is based on the 
equivalence operator of the Key type. 

The contains public member function returns a non-zero value if the Key is found in the dictionary, 
find, findKeyAndValue 
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WCPtrHashDict<Key,Value>::entries() 


Synopsis: #include <wchash.h> 

public: 

unsigned entries () const; 


Semantics: 

Results: 
See Also: 


The entries public member function is used to return the current number of elements stored in the 
dictionary. 

The entries public member function returns the number of elements in the dictionary, 
buckets, isEmpty 
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WCPtrHashDict<Key,Value>::find() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wchash.h> 
public: 

Value * find( const Key * ) const; 

The find public member function is used to find an element with an equivalent key in the dictionary. 
If an equivalent element is found, a pointer to the element Value is returned. Zero is returned if the 
element is not found. Note that equivalence is based on the equivalence operator of the Key type. 

The element equivalent to the passed key is located in the dictionary. 

findKeyAndValue 
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WCPtrHashDict<Key,Value>::findKeyAndValue() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchash.h> 
public: 

Value * findKeyAndValue( const Key *, 

Key &, Value & ) const; 

The f indKeyAndValue public member function is used to find an element in the dictionary with an 
key equivalent to the first parameter. If an equivalent element is found, a pointer to the element Value 
is returned. The reference to a Key passed as the second parameter is assigned the found element’s key. 
Zero is returned if the element is not found. Note that equivalence is based on the equivalence operator 
of the Key type. 

The element equivalent to the passed key is located in the dictionary, 
findKeyAndValue 
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WCPtrHashDict<Key, Value>::forA ll() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wchash.h> 
public: 
void forAll( 

void (*user_ fn) ( Key *, Value *, void * ), 
void * ); 

The forAll public member function causes the user supplied function to be invoked for every 
key-value pair in the dictionary. The user function has the prototype 

void user_ func ( Key * key. Value * value, void * data ); 

As the elements are visited, the user function is invoked with the Key and Value components of the 
element passed as the first two parameters. The second parameter of the forAll function is passed as 
the third parameter to the user function. This value can be used to pass any appropriate data from the 
main code to the user function. 

The elements in the dictionary are all visited, with the user function being invoked for each one. 
find, findKeyAndValue 
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WCPtrHashDict<Key,Value>::insert() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

int insert( Key *, Value * ); 

The insert public member function inserts a key and value into the dictionary, using the hash 
function on the key to determine to which bucket it should be stored. If allocation of the node to store 
the key-value pair fails, then the out_ of_ memory exception is thrown if it is enabled. If the 
exception is not enabled, the insert will not be completed. 

At some point, the number of buckets initially selected may be too small for the number of elements 
inserted. The resize of the dictionary can be controlled by the insertion mechanism by using 
WCPtrHashDict as a base class, and providing an insert member function to do a resize when 
appropriate. This insert could then call WCPtrHashDict: : insert to insert the element. Note that 
copy constructors and assignment operators are not inherited in your class, but you can provide the 
following inline definitions (assuming that the class inherited from WCPtrHashDict is named 
MyHashDict): 


inline MyHashDict( const MyHashDict &orig ) : WCPtrHashDict( orig ) {}; 

inline MyHashDict &operator=( const MyHashDict &orig ) { 

return( WCPtrHashDict::operator=( orig ) ); 

} 

The insert public member function inserts a key and value into the dictionary. If the insert is 
successful, a non-zero will returned. A zero will be returned if the insert fails. 

operator =, WCExcept::out_ of_ memory 
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WCPtrHashDict<Key,Value>::isEmpty() 


Synopsis: #include <wchash.h> 

public: 

int isEmptyO const; 


Semantics: 

Results: 

See Also: 


The is Empty public member function is used to determine if the dictionary is empty. 

The is Empty public member function returns zero if it contains at least one entry, non-zero if the 
dictionary is empty. 

buckets, entries 
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WCPtrHashDict<Key, Value>::operator []() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wchash.h> 
public: 

Value * & operator[]( const Key & ); 

operator [ ] is the dictionary index operator. A reference to the object stored in the dictionary with 
the given Key is returned. If no equivalent element is found, then a new key-value pair is created with 
the specified Key value, and initialized with the default constructor. The returned reference can then be 
assigned to, so that insertions can be made with the operator. If an allocation error occurs while 
inserting a new key-value pair, then the out_ of_ memory exception is thrown if it is enabled. If the 
exception is not enabled, then a reference to address zero will be returned. This will result in a run-time 
error on systems which trap address zero references. 

The operator [ ] public member function returns a reference to the element at the given key value. 
If the key does not exist, a reference to a created element is returned. The result of the operator may be 
assigned to. 

WCExcept: : out_ of_ memory 
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WCPtrHashDict<Key, Value>::operator []() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wchash.h> 
public: 

Value * const & operator!]( const Key * ) const; 

operator [] is the dictionary index operator. A constant reference to the object stored in the 
dictionary with the given Key is returned. If no equivalent element is found, then the index_ range 
exception is thrown if it is enabled. If the exception is not enabled, then a reference to address zero will 
be returned. This will result in a run-time error on systems which trap address zero references. 

The operator [ ] public member function returns a constant reference to the element at the given 
key value. The result of the operator may not be assigned to. 

WCExcept: : index_ range 
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WCPtrHashDict<Key, Value>::operator =() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCPtrHashDict & operator =( const WCPtrHashDict & ); 

The operator = public member function is the assignment operator for the 
WCPtrHashDict<Key, Value> class. The left hand side dictionary is first cleared using the 
clear member function, and then the right hand side dictionary is copied. The hash function, 
exception trap states, and all of the dictionary elements are copied. If an allocation failure occurs when 
creating the buckets, the table will be created with zero buckets, and the out_ of_ memory exception 
is thrown if it is enabled. If there is not enough memory to copy all of the values or pointers in the 
dictionary, then only some will be copied, and the out_ of_ memory exception is thrown if it is 
enabled. The number of entries will correctly reflect the number copied. 

The operator = public member function assigns the left hand side dictionary to be a copy of the 
right hand side. 

clear, WCExcept: : out_ of_ memory 
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WCPtrHashDict<Key, Value>::operator ==() 


Synopsis: 


Semantics: 


Results: 


#include <wchash.h> 
public: 

int operator ==( const WCPtrHashDict & ) const; 

The operator == public member function is the equivalence operator for the 
WCPtrHashDict<Key, Value> class. Two dictionary objects are equivalent if they are the same 
object and share the same address. 

A TRUE (non-zero) value is returned if the left hand side and right hand side dictionary are the same 
object. A FALSE (zero) value is returned otherwise. 
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WCPtrHashDict<Key,Value>::remove() 


Synopsis: 


Semantics: 


Results: 


♦include <wchash.h> 
public: 

Value * remove( const Key * ) ; 

The remove public member function is used to remove the specified element from the dictionary. If 
an equivalent element is found, the pointer value is returned. Zero is returned if the element is not 
found. Note that equivalence is based on the equivalence operator of the Key type. 

The element is removed from the dictionary if it found. 
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WCPtrHashDict<Key,Value>::resize() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wchash.h> 
public: 

void resize( unsigned ) ; 

The resize public member function is used to change the number of buckets contained in the 
dictionary. If the new number is larger than the previous dictionary size, then the hash function will be 
used on all of the stored elements to determine which bucket they should be stored into. Entries are not 
destroyed or created in the process of being moved. If there is not enough memory to resize the 
dictionary, the out_ of_ memory exception is thrown if it is enabled, and the dictionary will contain 
the number of buckets it contained before the resize. If the new number is zero, then the 
zero_ buckets exception is thrown if it is enabled, and no resize will be performed. The dictionary 
is guaranteed to contain the same number of entries after the resize. 

The dictionary is resized to the new number of buckets. 

WCExcept: : out_ of_ memory^CExcept: : zero_ buckets 
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WCPtrHashTable<Type>, WCPtrHashSet<Type> 


Declared: 


wchash.h 

WCPtrHashTable<Type> and WCPtrHashSet<Type> classes are templated classes used to store 
objects in a hash. A hash saves objects in such a way as to make it efficient to locate and retrieve an 
element. As an element is looked up or inserted into the hash, the value of the element is hashed. 
Hashing results in a numeric index which is used to locate the value. The storage area referenced by the 
hash value is usually called a bucket. If more than one element results in the same hash, the value 
associated with the hash is placed in a list stored in the bucket. A hash table allows more than one copy 
of an element that is equivalent, while the hash set allows only one copy. The equality operator of the 
element’s type is used to locate the value. 

In the description of each member function, the text Type is used to indicate the template parameter 
defining the type of the data pointed to by the pointers stored in the hash. 

The constructor for the WCPtrHashTable<Type> and WCPtrHashSet<Type> classes requires a 
hashing function, which given a reference to Type, returns an unsigned value. The returned value 
modulo the number of buckets determines the bucket into which the element will be located. The return 
values of the hash function can be spread over the entire range of unsigned numbers. The hash function 
return value must be the same for values which are equivalent by the equivalence operator for Type . 

Note that pointers to the elements are stored in the hash. Destructors are not called on the elements 
pointed to. The data values pointed to in the hash should not be changed such that the equivalence to 
the old value is modified. 


The WCExcept class is a base class of the WCPtrHashTable<Type> and 
WCPtrHashSet<Type> classes and provides the exceptions member function. This member 
function controls the exceptions which can be thrown by the WCPtrHashTable<Type> and 
WCPtrHashSet<Type> objects. No exceptions are enabled unless they are set by the exceptions 
member function. 

Requirements of Type 

The WCPtrHashTable<Type> and WCPtrHashSet<Type> classes requires Type to have: 

A well defined equivalence operator with constant parameters 
( int operator == ( const Type & ) const ). 

Public Member Functions 


The following member functions are declared in the public interface: 


WCPtrHashSet( unsigned 
WC_ DEFAULT_ HASH_ SIZE 

(*hash_ 
); 

fn 

) ( const Type 

& ) , 

WCPtrHashSet( unsigned 

(*hash_ 

fn 

) ( const Type 

& ) , 

WC_ DEFAULT_ HASH_ SIZE, 

void * 

(* 

user_ alloc) ( 

size. 


(*user_ dealloc) ( void *old, size_ t size ) ); 

WCPtrHashSet( const WCPtrHashSet & ) ; 
virtual -WCPtrHashSet() ; 

WCPtrHashTable( unsigned (*hash_ fn) ( const Type & 
WC_ DEFAULT_ HASH_ SIZE ); 

WCPtrHashTable! unsigned (*hash_ fn) ( const Type & 
WC_ DEFAULT_ HASH_ SIZE, void * (*user_ alloc) ( size. 

(*user_ dealloc) ( void *old, size_ t size ) ); 

WCPtrHashTable( const WCPtrHashTable & ); 
virtual -WCPtrHashTable(); 


unsigned = 

unsigned = 
t size ), 

, unsigned 

, unsigned 
t size ), 


void 


void 
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WCPtrHash Table<Type>, WCPtrHashSet<Type> 


static unsigned bitHash( const void *, size_t ); 

unsigned buckets() const; 

void clear(); 

void clearAndDestroy() ; 

int contains( const Type * ) const; 

unsigned entries() const; 

Type * find( const Type * ) const; 

void forAll( void (*user_ fn) ( Type *, void * ) , void * ); 

int insert ( Type * ); 
int isEmptyO const; 

Type * remove( const Type * ); 
void resize( unsigned ) ; 

The following public member functions are available for the WCPtrHashTable class only: 

unsigned occurrencesOf( const Type * ) const; 
unsigned removeAll( const Type * ) ; 

Public Member Operators 

The following member operators are declared in the public interface: 

WCPtrHashSet & operator =( const WCPtrHashSet & ); 
int operator ==( const WCPtrHashSet & ) const; 

WCPtrHashTable & operator =( const WCPtrHashTable & ); 
int operator ==( const WCPtrHashTable & ) const; 
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WCPtrHashSet<Type>::WCPtrHashSet() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCPtrHashSet ( unsigned (*hash_fn) ( const Type & ), 
unsigned = WC_ DEFAULT_ HASH_ SIZE ); 

The WCPtrHashSet<Type> constructor creates a WCPtrHashSet object with no entries and with 

the number of buckets in the second optional parameter, which defaults to the constant 

WC_ DEFAULT_ HASH_ SIZE (currently defined as 101). The number of buckets specified must be 

greater than zero, and will be forced to at least one. If the hash object can be created, but an allocation 

failure occurs when creating the buckets, the table will be created with zero buckets. If the 

out_ of_ memory exception is enabled, then attempting to insert into a hash table with zero buckets 

with throw an out_ of_ memory error. 

The hash function hash_ f n is used to determine which bucket each value will be assigned to. If no 
hash function exists, the static member function bitHash is available to help create one. 

The WCPtrHashSet<Type> constructor creates an initialized WCPtrHashSet object with the 
specified number of buckets and hash function. 

~WCPtrHashSet, bitHash, WCExcept: : out_ of_ memory 
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WCPtrHashSet<Type>::WCPtrHashSet() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCPtrHashSet ( unsigned (*hash_fn) ( const Type & ), 

unsigned = WC_ DEFAULT_ HASH_ SIZE, 

void * (*user_ alloc) ( size_ t ), 

void (*user_ dealloc) ( void *, size_ t ) ); 

Allocator and deallocator functions are specified for use when entries are inseited and removed from the 
hash. The semantics of this constructor are the same as the constructor without the memory 
management functions. 

The allocation function must return a zero if it cannot perform the allocation. The deallocation function 
is passed the size as well as the pointer to the data. Your allocation system may take advantage of the 
characteristic that the allocation function will always be called with the same size value for any 
particular instantiation of a hash. To determine the size of the objects that the memory management 
functions will be required to allocate and free, the following macro may be used: 
WCPtrHashSetltemSize( Type ) 

The WCPtrHashSet<Type> constructor creates an initialized WCPtrHashSet object with the 
specified number of buckets and hash function. 

~WCPtrHashSet, bitHash, WCExcept: : out_ of_ memory 
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WCPtrHashSet<Type>::WCPtrHashSet() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCPtrHashSet( const WCPtrHashSet & ); 

The WCPtrHashSet<Type> is the copy constructor for the WCPtrHashSet class. The new hash is 
created with the same number of buckets, hash function, all values or pointers stored in the hash, and 
the exception trap states. If the hash object can be created, but an allocation failure occurs when 
creating the buckets, the hash will be created with zero buckets. If there is not enough memory to copy 
all of the values, then only some will be copied, and the number of entries will correctly reflect the 
number copied. If all of the elements cannot be copied, then the out_ of_ memory exception is 
thrown if it is enabled. 

The WCPtrHashSet<Type> constructor creates a WCPtrHashSet object which is a copy of the 
passed hash. 

~WCPtrHashSet, operator =, WCExcept: : out_ of_ memory 
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WCPtrHashSet<Type>::~WCPtrHashSet() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wchash.h> 
public: 

virtual -WCPtrHashSet() ; 

The WCPtrHashSet<Type> destructor is the destructor for the WCPtrHashSet class. If the 
number of elements is not zero and the not_ empty exception is enabled, the exception is thrown. 
Otherwise, the hash elements are cleared using the clear member function. The objects which the 
hash elements point to are not deleted unless the clearAndDestroy member function is explicitly 
called before the destructor is called. The call to the WCPtrHashSet<Type> destructor is inserted 
implicitly by the compiler at the point where the WCPtrHashSet object goes out of scope. 

The call to the WCPtrHashSet<Type> destructor destroys a WCPtrHashSet object. 

clear, clearAndDestroy, WCExcept::not_ empty 
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WCPtrHash Table<Type>:: WCPtrHash Table() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCPtrHashTable( unsigned (*hash_ fn) ( const Type & ), 
unsigned = WC_ DEFAULT_ HASH_ SIZE ); 

The WCPtrHashTable<Type> constructor creates a WCPtrHashTable object with no entries and 

with the number of buckets in the second optional parameter, which defaults to the constant 

WC_ DEFAULT_ HASH_ SIZE (currently defined as 101). The number of buckets specified must be 

greater than zero, and will be forced to at least one. If the hash object can be created, but an allocation 

failure occurs when creating the buckets, the table will be created with zero buckets. If the 

out_ of_ memory exception is enabled, then attempting to insert into a hash table with zero buckets 

with throw an out_ of_ memory error. 

The hash function hash_ f n is used to determine which bucket each value will be assigned to. If no 
hash function exists, the static member function bitHash is available to help create one. 

The WCPtrHashTable<Type> constructor creates an initialized WCPtrHashTable object with 
the specified number of buckets and hash function. 

~WCPtrHashTable, bitHash, WCExcept: : out_ of_ memory 
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WCPtrHash Table<Type>:: WCPtrHash Table() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCPtrHashTable( unsigned (*hash_ fn) ( const Type & ), 

unsigned = WC_ DEFAULT_ HASH_ SIZE, 

void * (*user_ alloc) ( size_ t ), 

void (*user_ dealloc) ( void *, size_ t ) ); 

Allocator and deallocator functions are specified for use when entries are inseited and removed from the 
hash. The semantics of this constructor are the same as the constructor without the memory 
management functions. 

The allocation function must return a zero if it cannot perform the allocation. The deallocation function 
is passed the size as well as the pointer to the data. Your allocation system may take advantage of the 
characteristic that the allocation function will always be called with the same size value for any 
particular instantiation of a hash. To determine the size of the objects that the memory management 
functions will be required to allocate and free, the following macro may be used: 
WCPtrHashTableltemSize( Type ) 

The WCPtrHashTable<Type> constructor creates an initialized WCPtrHashTable object with 
the specified number of buckets and hash function. 

~WCPtrHashTable, bitHash, WCExcept: : out_ of_ memory 
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WCPtrHash Table<Type>:: WCPtrHash Table() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCPtrHashTable( const WCPtrHashTable & ) ; 

The WCPtrHashTable<Type> is the copy constructor for the WCPtrHashTable class. The new 
hash is created with the same number of buckets, hash function, all values or pointers stored in the hash, 
and the exception trap states. If the hash object can be created, but an allocation failure occurs when 
creating the buckets, the hash will be created with zero buckets. If there is not enough memory to copy 
all of the values, then only some will be copied, and the number of entries will correctly reflect the 
number copied. If all of the elements cannot be copied, then the out_ of_ memory exception is 
thrown if it is enabled. 

The WCPtrHashTable<Type> constructor creates a WCPtrHashTable object which is a copy of 
the passed hash. 

~WCPtrHashTable, operator =, WCExcept: : out_ of_ memory 
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WCPtrHashTable<Type>::~WCPtrHashTable() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wchash.h> 
public: 

virtual ~WCPtrHashTable() ; 

The WCPtrHashTable<Type> destructor is the destructor for the WCPtrHashTable class. If the 
number of elements is not zero and the not_ empty exception is enabled, the exception is thrown. 
Otherwise, the hash elements are cleared using the clear member function. The objects which the 
hash elements point to are not deleted unless the clearAndDestroy member function is explicitly 
called before the destructor is called. The call to the WCPtrHashTable<Type> destructor is inserted 
implicitly by the compiler at the point where the WCPtrHashTable object goes out of scope. 

The call to the WCPtrHashTable<Type> destructor destroys a WCPtrHashTable object. 

clear, clearAndDestroy, WCExcept::not_ empty 
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WCPtrHashTable<Type>::bitHash(), WCPtrHashSet<Type>::bitHash() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wchash.h> 
public: 

static unsigned bitHash( void *, size_ t ); 

The bitHash public member function can be used to implement a hashing function for any type. A 
hashing value is generated from the value stored for the number of specified bytes pointed to by the first 
parameter. 

The bitHash public member function returns an unsigned value which can be used as the basis of a 
user defined hash function. 

WCPtrHashSet, WCPtrHashTable 
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WCPtrHashTable<Type>::buckets(), WCPtrHashSet<Type>::buckets() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchash.h> 
public: 

unsigned buckets() const; 

The buckets public member function is used to find the number of buckets contained in the hash 
object. 

The buckets public member function returns the number of buckets in the hash, 
resize 
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WCPtrHashTable<Type>::clear(), WCPtrHashSet<Type>::clear() 


Synopsis: #include <wchash.h> 

public: 
void clear(); 


Semantics: 

Results: 
See Also: 


The clear public member function is used to clear the hash so that it has no entries. The number of 
buckets remain unaffected. Objects pointed to by the hash elements are not deleted. The hash object is 
not destroyed and re-created by this function, so the object destructor is not invoked. 

The clear public member function clears the hash to have no elements. 

~WCPtrHashSet, ~WCPtrHashTable, clearAndDestroy, operator = 
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WCPtrHash Table<Type>, WCPtrHashSet<Type>::clearAndDestroy() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

void clearAndDestroy(); 

The clearAndDestroy public member function is used to clear the hash and delete the objects 
pointed to by the hash elements. The hash object is not destroyed and re-created by this function, so the 
hash object destructor is not invoked. 

The clearAndDestroy public member function clears the hash by deleting the objects pointed to by 
the hash elements. 

clear 
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WCPtrHashTable<Type>::contains(), WCPtrHashSet<Type>::contains() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchash.h> 
public: 

int contains( const Type * ) const; 

The contains public member function returns non-zero if the element is stored in the hash, or zero if 
there is no equivalent element. Note that equivalence is based on the equivalence operator of the 
element type. 

The contains public member function returns a non-zero value if the element is found in the hash, 
find 
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WCPtrHashTable<Type>::entries(), WCPtrHashSet<Type>::entries() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchash.h> 
public: 

unsigned entries() const; 

The entries public member function is used to return the current number of elements stored in the 
hash. 

The entries public member function returns the number of elements in the hash, 
buckets, isEmpty 
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WCPtrHashTable<Type>::find(), WCPtrHashSet<Type>::find() 


Synopsis: 


Semantics: 


Results: 


#include <wchash.h> 
public: 

Type * find( const Type * ) const; 

The find public member function is used to find an element with an equivalent key in the hash. If an 
equivalent element is found, a pointer to the element is returned. Zero is returned if the element is not 
found. Note that equivalence is based on the equivalence operator of the element type. 

The element equivalent to the passed key is located in the hash. 
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WCPtrHashTable<Type>::forAII(), WCPtrHashSet<Type>::forAII() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wchash.h> 
public: 
void forAll( 

void (*user_ fn) ( Type *, void * ), 
void * ); 

The forAll public member function causes the user supplied function to be invoked for every value in 
the hash. The user function has the prototype 


void user_ func( Type * value, void * data ); 

As the elements are visited, the user function is invoked with the element passed as the first. The 
second parameter of the forAll function is passed as the second parameter to the user function. This 
value can be used to pass any appropriate data from the main code to the user function. 

The elements in the hash are all visited, with the user function being invoked for each one. 

find 
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WCPtrHashTable<Type>::insert(), WCPtrHashSet<Type>::insert() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wchash.h> 
public: 

int insert( Type * ) ; 

The insert public member function inserts a value into the hash, using the hash function to determine 
to which bucket it should be stored. If allocation of the node to store the value fails, then the 
out_ of_ memory exception is thrown if it is enabled. If the exception is not enabled, the insert will 
not be completed. 

With a WCPtrHashSet, there must be only one equivalent element in the set. If an element 
equivalent to the inserted element is already in the hash set, the hash set will remain unchanged, and the 
not_ unique exception is thrown if it is enabled. If the exception is not enabled, the insert will not be 
completed. 

At some point, the number of buckets initially selected may be too small for the number of elements 
inserted. The resize of the hash can be controlled by the insertion mechanism by using 
WCPtrHashSet (or WCPtrHashTable) as a base class, and providing an insert member function to 
do a resize when appropriate. This insert could then call WCPtrHashSet: : insert (or 
WCPtrHashTable : : insert) to insert the element. Note that copy constructors and assignment 
operators are not inherited in your class, but you can provide the following inline definitions (assuming 
that the class inherited from WCPtrHashTable is named MyHashTable): 


inline MyHashTable( const MyHashTable &orig ) 

: WCPtrHashTable( orig ) {}; 

inline MyHashTable &operator=( const MyHashTable &orig ) { 

return( WCPtrHashTable::operator=( orig ) ); 

} 

The insert public member function inserts a value into the hash. If the insert is successful, a 
non-zero will returned. A zero will be returned if the insert fails. 

operator =, WCExcept: : out_ of_ memory 
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WCPtrHashTable<Type>::isEmpty(), WCPtrHashSet<Type>::isEmpty() 


Synopsis: 

Semantics 

Results: 

See Also: 


#include <wchash.h> 
public: 

int isEmptyO const; 

The is Empty public member function is used to determine if the hash is empty. 

The is Empty public member function returns zero if it contains at least one entry, non-zero if the hash 
is empty. 

buckets, entries 
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WCPtrHashTable<Type>::occurencesOf() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchash.h> 
public: 

unsigned occurrencesOf( const Type * ) const; 

The occurencesOf public member function is used to return the current number of elements stored 
in the hash which are equivalent to the passed value. Note that equivalence is based on the equivalence 
operator of the element type. 

The occurencesOf public member function returns the number of elements in the hash, 
buckets, entries, find, isEmpty 
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WCPtrHashTable<Type>:-.operator =(), WCPtrHashSet<Type>:operator =() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCPtrHashSet & operator =( const WCPtrHashSet & ); 

WCPtrHashTable & operator =( const WCPtrHashTable & ); 

The operator = public member function is the assignment operator for the 

WCPtrHashTable<Type> and WCPtrHashSet<Type> classes. The left hand side hash is first 
cleared using the clear member function, and then the right hand side hash is copied. The hash 
function, exception trap states, and all of the hash elements are copied. If an allocation failure occurs 
when creating the buckets, the table will be created with zero buckets, and the out_ of_ memory 
exception is thrown if it is enabled. If there is not enough memory to copy all of the values or pointers 
in the hash, then only some will be copied, and the out_ of_ memory exception is thrown if it is 
enabled. The number of entries will correctly reflect the number copied. 

The operator = public member function assigns the left hand side hash to be a copy of the right 
hand side. 

clear, WCExcept: : out_ of_ memory 
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WCPtrHashTable<Type>::operator ==(), WCPtrHashSet<Type>:-.operator ==() 


Synopsis: 


Semantics: 


Results: 


#include <wchash.h> 
public: 

int operator ==( const WCPtrHashSet & ) const; 
int operator ==( const WCPtrHashTable & ) const; 

The operator == public member function is the equivalence operator for the 

WCPtrHashTable<Type> and WCPtrHashSet<Type> classes. Two hash objects are equivalent 
if they are the same object and share the same address. 

A TRUE (non-zero) value is returned if the left hand side and right hand side hash are the same object. 
A FALSE (zero) value is returned otherwise. 
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WCPtrHashTable<Type>::remove(), WCPtrHashSet<Type>::remove() 


Synopsis: 


Semantics: 


Results: 


#include <wchash.h> 
public: 

Type * remove( const Type * ) ; 

The remove public member function is used to remove the specified element from the hash. If an 
equivalent element is found, the pointer value is returned. Zero is returned if the element is not found. 
If the hash is a table and there is more than one element equivalent to the specified element, then the 
first equivalent element added to the table is removed. Note that equivalence is based on the 
equivalence operator of the element type. 

The element is removed from the hash if it found. 
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WCPtrHashTable<Type>::remo veAHQ 


Synopsis: 


Semantics: 


Results: 


#include <wchash.h> 
public: 

unsigned removeAll( const Type * ); 

The removeAll public member function is used to remove all elements equivalent to the specified 
element from the hash. Zero is returned if no equivalent elements are found. Note that equivalence is 
based on the equivalence operator of the element type. 

All equivalent elements are removed from the hash. 
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WCPtrHashTable<Type>::resize(), WCPtrHashSet<Type>::resize() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wchash.h> 
public: 

void resize( unsigned ) ; 

The resize public member function is used to change the number of buckets contained in the hash. If 
the new number is larger than the previous hash size, then the hash function will be used on all of the 
stored elements to determine which bucket they should be stored into. Entries are not destroyed or 
created in the process of being moved. If there is not enough memory to resize the hash, the 
out_ of_ memory exception is thrown if it is enabled, and the hash will contain the number of buckets 
it contained before the resize. If the new number is zero, then the zero_ buckets exception is 
thrown if it is enabled, and no resize will be performed. The hash is guaranteed to contain the same 
number of entries after the resize. 

The hash is resized to the new number of buckets. 

WCExcept: : out_ of_ memory^CExcept: : zero_ buckets 
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WCValHashDict<Key, Value> 


Declared: wchash.h 

The WCValHashDict<Key, Value> class is a templated class used to store objects in a dictionary. 
Dictionaries store values with an associated key, which may be of any type. One example of a 
dictionary used in everyday life is the phone book. The phone numbers are the data values, and the 
customer name is the key. An example of a specialized dictionary is a vector, where the key value is the 
integer index. 

As an element is looked up or inserted into the dictionary, the associated key is hashed. Hashing 
converts the key into a numeric index value which is used to locate the value. The storage area 
referenced by the hash value is usually called a bucket. If more than one key results in the same hash, 
the values associated with the keys are placed in a list stored in the bucket. The equality operator of the 
key’s type is used to locate the key-value pairs. 

In the description of each member function, the text Key is used to indicate the template parameter 
defining the type of the indices used to store data in the dictionary. The text Value is used to indicate 
the template parameter defining the type of the data stored in the dictionary. 

The constructor for the WCValHashDict<Key, Value> class requires a hashing function, which 
given a reference to Key, returns an unsigned value. The returned value modulo the number of 
buckets determines the bucket into which the key-value pair will be located. The return values of the 
hash function can be spread over the entire range of unsigned numbers. The hash function return value 
must be the same for values which are equivalent by the equivalence operator for Key. 

Values are copied into the dictionary, which could be undesirable if the stored objects are complicated 
and copying is expensive. Value dictionaries should not be used to store objects of a base class if any 
derived types of different sizes would be stored in the dictionary, or if the destructor for a derived class 
must be called. 

The WCExcept class is a base class of the WCValHashDict<Key, Value> class and provides the 
exceptions member function. This member function controls the exceptions which can be thrown 
by the WCValHashDict<Key, Value> object. No exceptions are enabled unless they are set by the 
exceptions member function. 

Requirements of Key and Value 

The WCValHashDict<Key, Value> class requires Key to have: 

A default constructor ( Key: : Key () ). 

A well defined copy constructor ( Key:: Key ( const Key & ) ). 

A well defined assignment operator ( Key & operator =( const Key & ) ). 

A well defined equivalence operator with constant parameters 
( int operator == ( const Key & ) const). 

The WCValHashDict<Key, Value> class requires Value to have: 

A default constructor ( Value : : Value () ). 

A well defined copy constructor ( Value :: Value ( const Value & ) ). 

A well defined assignment operator ( Value & operator =( const Value & ) ). 
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WCValHashDict<Key, Value> 


Public Member Functions 


The following member functions are declared in the public interface: 


WCValHashDict( unsigned (*hash_ fn) ( const Key & ), unsigned : 
WC_ DEFAULT^ HASH_ SIZE ); 

WCValHashDict( unsigned (*hash_fn) ( const Key & ), unsigned : 
WC_ DEFAULT_ HASH_ SIZE, void * (*user_ alloc) ( size_ t size ), 

(*user_ dealloc) ( void *old, size_ t size ) ); 

WCValHashDict( const WCValHashDict & ) ; 
virtual ~WCValHashDict(); 

static unsigned bitHash( const void *, size_ t ); 
unsigned buckets!) const; 
void clear (); 

int contains( const Key & ) const; 

unsigned entries!) const; 

int find! const Key &, Value & ) const; 

int findKeyAndValue( const Key &, Key &, Value & ) const; 

void forAll( void (*user_ fn) ( Key, Value, void * ), void * ) 

int insert! const Key &, const Value & ); 

int isEmpty!) const; 

int remove( const Key & ); 

void resize( unsigned ); 


Public Member Operators 

The following member operators are declared in the public interface: 

Value & operator []( const Key & ); 
const Value & operator []( const Key & ) const; 
WCValHashDict & operator =( const WCValHashDict & ); 
int operator ==( const WCValHashDict & ) const; 


void 
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WCValHashDict<Key, Value>:: WCValHashDictQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCValHashDict( unsigned (*hash_ fn) ( const Key & ), 
unsigned = WC_ DEFAULT_ HASH_ SIZE ); 

The public WCValHashDict<Key, Value> constructor creates an 

WCValHashDict <Key, Value> object with no entries and with the number of buckets in the second 
optional parameter, which defaults to the constant WC_ DEFAULT_ HASH_ SIZE (currently defined as 
101). The number of buckets specified must be greater than zero, and will be forced to at least one. If 
the hash dictionary object can be created, but an allocation failure occurs when creating the buckets, the 
table will be created with zero buckets. If the out_ of_ memory exception is enabled, then attempting 
to insert into a hash table with zero buckets with throw an out_ of_ memory error. 

The hash function hash_ f n is used to determine which bucket each key-value pair will be assigned. If 
no hash function exists, the static member function bitHash is available to help create one. 

The public WCValHashDict<Key, Value> constructor creates an initialized 
WCValHashDict<Key, Value> object with the specified number of buckets and hash function. 

~WCValHashDict, bitHash, WCExcept: : out_ of_ memory 
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WCValHashDict<Key, Value>:: WCValHashDictQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCValHashDict( unsigned (*hash_fn) ( const Key & ), 

unsigned = WC_ DEFAULT_ HASH_ SIZE, 

void * (*user_ alloc) ( size_ t ), 

void (*user_ dealloc) ( void *, size_ t ) ); 

Allocator and deallocator functions are specified for use when entries are inserted and removed from the 
hash dictionary. The semantics of this constructor are the same as the constructor without the memory 
management functions. 

The allocation function must return a zero if it cannot perform the allocation. The deallocation function 
is passed the size as well as the pointer to the data. Your allocation system may take advantage of the 
characteristic that the allocation function will always be called with the same size value for any 
particular instantiation of a hash dictionary. To determine the size of the objects that the memory 
management functions will be required to allocate and free, the following macro may be used: 
WCValHashDictltemSize( Key, Value ) 

The public WCValHashDict<Key, Value> constructor creates an initialized 
WCValHashDict <Key, Value> object with the specified number of buckets and hash function. 

~WCValHashDict, bitHash, WCExcept: : out_ of_ memory 
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WCValHashDict<Key, Value>:: WCValHashDictQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCValHashDict( const WCValHashDict & ); 

The public WCValHashDict<Key, Value> constructor is the copy constructor for the 
WCValHashDict<Key, Value> class. The new dictionary is created with the same number of 
buckets, hash function, all values or pointers stored in the dictionary, and the exception trap states. If 
the hash dictionary object can be created, but an allocation failure occurs when creating the buckets, the 
table will be created with zero buckets. If there is not enough memory to copy all of the values in the 
dictionary, then only some will be copied, and the number of entries will correctly reflect the number 
copied. If all of the elements cannot be copied, then the out_ of_ memory exception is thrown if it is 
enabled. 

The public WCValHashDict<Key, Value> constructor creates an 
WCValHashDict <Key, Value> object which is a copy of the passed dictionary. 

~WCValHashDict, operator =, WCExcept: : out_ of_ memory 


Hash Containers 135 




WCValHashDict<Key, Value>::~ WCValHashDictQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wchash.h> 
public: 

virtual ~WCValHashDict() ; 

The public ~WCValHashDict<Key, Value> destructor is the destructor for the 
WCValHashDict<Key, Value> class. If the number of dictionary elements is not zero and the 
not_ empty exception is enabled, the exception is thrown. Otherwise, the dictionary elements are 
cleared using the clear member function. The call to the public ~WCValHashDict<Key, Value> 
destructor is inserted implicitly by the compiler at the point where the 
WCValHashDict<Key, Value> object goes out of scope. 

The public ~WCValHashDict<Key, Value> destructor destroys an 
WCValHashDict<Key, Value> object. 

clear, WCExcept: : not_ empty 
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WC ValHashDict<Key, Value>::bitHash() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wchash.h> 
public: 

static unsigned bitHash( void *, size_ t ); 

The bitHash public member function can be used to implement a hashing function for any type. A 
hashing value is generated from the value stored for the number of specified bytes pointed to by the first 
parameter. For example: 


unsigned my_ hash_ fn ( const int & key ) { 

return( WCValHashDictcint,String>::bitHash( &key, sizeof( int ) ); 

} 

WCValHashDictcint, String> data_ object ( &my_ hash_ fn ) ; 

The bitHash public member function returns an unsigned value which can be used as the basis of a 
user defined hash function. 

WCValHashDict 
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WCValHashDict<Key,Value>::buckets() 


Synopsis: #include <wchash.h> 

public: 

unsigned buckets const; 


Semantics: 

Results: 
See Also: 


The buckets public member function is used to find the number of buckets contained in the 
WCValHashDict<Key, Value> object. 

The buckets public member function returns the number of buckets in the dictionary, 
resize 
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WCValHashDict<Key,Value>::clear() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchash.h> 

public: 

void clear(); 

The clear public member function is used to clear the dictionary so that it has no entries. The number 
of buckets remain unaffected. Elements stored in the dictionary are destroyed using the destructors of 
Key and of Value . The dictionary object is not destroyed and re-created by this function, so the 
object destructor is not invoked. 

The clear public member function clears the dictionary to have no elements. 

~WCValHashDict, operator = 
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WCValHashDict<Key,Value>::contains() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchash.h> 
public: 

int contains( const Key & ) const; 

The contains public member function returns non-zero if an element with the specified key is stored 
in the dictionary, or zero if there is no equivalent element. Note that equivalence is based on the 
equivalence operator of the Key type. 

The contains public member function returns a non-zero value if the Key is found in the dictionary, 
find, findKeyAndValue 
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WC ValHashDict<Key, Value>::entries() 


Synopsis: #include <wchash.h> 

public: 

unsigned entries () const; 


Semantics: 

Results: 
See Also: 


The entries public member function is used to return the current number of elements stored in the 
dictionary. 

The entries public member function returns the number of elements in the dictionary, 
buckets, isEmpty 


Hash Containers 141 




WCValHashDict<Key,Value>::find() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchash.h> 
public: 

int find( const Key &, Value & ) const; 

The find public member function is used to find an element with an equivalent key in the dictionary. 

If an equivalent element is found, a non-zero value is returned. The reference to a Value passed as the 
second argument is assigned the found element’s Value . Zero is returned if the element is not found. 
Note that equivalence is based on the equivalence operator of the Key type. 

The element equivalent to the passed key is located in the dictionary. 

findKeyAndValue 


142 Hash Containers 




WCValHashDict<Key,Value>::findKeyAndValue() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <wchash.h> 
public: 

int findKeyAndValue( const Key &, Key &, Value & ) const; 

The f indKeyAndValue public member function is used to find an element in the dictionary with an 
key equivalent to the first parameter. If an equivalent element is found, a non-zero value is returned. 
The reference to a Key passed as the second parameter is assigned the found element’s key. The 
reference to a Value passed as the third argument is assigned the found element’s Value . Zero is 
returned if the element is not found. Note that equivalence is based on the equivalence operator of the 
Key type. 

The element equivalent to the passed key is located in the dictionary, 
findKeyAndValue 
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WCValHashDict<Key, Value>::forAii() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wchash.h> 
public: 
void forAll( 

void (*user_ fn) ( Key, Value, void * ), 
void * ); 

The forAll public member function causes the user supplied function to be invoked for every 
key-value pair in the dictionary. The user function has the prototype 

void user_ func ( Key key. Value value, void * data ) ; 

As the elements are visited, the user function is invoked with the Key and Value components of the 
element passed as the first two parameters. The second parameter of the forAll function is passed as 
the third parameter to the user function. This value can be used to pass any appropriate data from the 
main code to the user function. 

The elements in the dictionary are all visited, with the user function being invoked for each one. 
find, findKeyAndValue 
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WC ValHashDict<Key, Value>::insert() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

int insert ( const Key &, const Value & ); 

The insert public member function inserts a key and value into the dictionary, using the hash 
function on the key to determine to which bucket it should be stored. If allocation of the node to store 
the key-value pair fails, then the out_ of_ memory exception is thrown if it is enabled. If the 
exception is not enabled, the insert will not be completed. 

At some point, the number of buckets initially selected may be too small for the number of elements 
inserted. The resize of the dictionary can be controlled by the insertion mechanism by using 
WCValHashDict as a base class, and providing an insert member function to do a resize when 
appropriate. This insert could then call WCValHashDict: : insert to insert the element. Note that 
copy constructors and assignment operators are not inherited in your class, but you can provide the 
following inline definitions (assuming that the class inherited from WCValHashDict is named 
MyHashDict): 


inline MyHashDict( const MyHashDict &orig ) : WCValHashDict( orig ) {}; 

inline MyHashDict &operator=( const MyHashDict &orig ) { 

return( WCValHashDict::operator=( orig ) ); 

} 

The insert public member function inserts a key and value into the dictionary. If the insert is 
successful, a non-zero will returned. A zero will be returned if the insert fails. 

operator =, WCExcept::out_ of_ memory 
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WCValHashDict<Key,Value>::isEmpty() 


Synopsis: #include <wchash.h> 

public: 

int isEmptyO const; 


Semantics: 

Results: 

See Also: 


The is Empty public member function is used to determine if the dictionary is empty. 

The is Empty public member function returns zero if it contains at least one entry, non-zero if the 
dictionary is empty. 

buckets, entries 
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WCValHashDict<Key, Value>::operator []() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

Value & operator[]( const Key & ); 

operator [ ] is the dictionary index operator. A reference to the object stored in the dictionary with 
the given Key is returned. If no equivalent element is found, then a new key-value pair is created with 
the specified Key value, and initialized with the default constructor. The returned reference can then be 
assigned to, so that insertions can be made with the operator. 

WCValHashDict<int, String> data_ object ( &my_ hash_ fn ) ; 
data_ object [ 5 ] = "Hello"; 

If an allocation error occurs while inserting a new key-value pair, then the out_ of_ memory 
exception is thrown if it is enabled. If the exception is not enabled, then a reference to address zero will 
be returned. This will result in a run-time error on systems which trap address zero references. 

The operator [ ] public member function returns a reference to the element at the given key value. 
If the key does not exist, a reference to a created element is returned. The result of the operator may be 
assigned to. 

WCExcept: : out_ of_ memory 
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WCValHashDict<Key, Value>::operator []() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wchash.h> 
public: 

const Value & operator[]( const Key & ) const; 

operator [] is the dictionary index operator. A constant reference to the object stored in the 
dictionary with the given Key is returned. If no equivalent element is found, then the index_ range 
exception is thrown if it is enabled. If the exception is not enabled, then a reference to address zero will 
be returned. This will result in a run-time error on systems which trap address zero references. 

The operator [ ] public member function returns a constant reference to the element at the given 
key value. The result of the operator may not be assigned to. 

WCExcept: : index_ range 
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WCValHashDict<Key, Value>::operator =() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCValHashDict & operator =( const WCValHashDict & ); 

The operator = public member function is the assignment operator for the 
WCValHashDict<Key, Value> class. The left hand side dictionary is first cleared using the 
clear member function, and then the right hand side dictionary is copied. The hash function, 
exception trap states, and all of the dictionary elements are copied. If an allocation failure occurs when 
creating the buckets, the table will be created with zero buckets, and the out_ of_ memory exception 
is thrown if it is enabled. If there is not enough memory to copy all of the values or pointers in the 
dictionary, then only some will be copied, and the out_ of_ memory exception is thrown if it is 
enabled. The number of entries will correctly reflect the number copied. 

The operator = public member function assigns the left hand side dictionary to be a copy of the 
right hand side. 

clear, WCExcept: : out_ of_ memory 
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WCValHashDict<Key, Value>::operator ==() 


Synopsis: 


Semantics: 


Results: 


#include <wchash.h> 
public: 

int operator ==( const WCValHashDict & ) const; 

The operator == public member function is the equivalence operator for the 
WCValHashDict <Key, Value> class. Two dictionary objects are equivalent if they are the same 
object and share the same address. 

A TRUE (non-zero) value is returned if the left hand side and right hand side dictionary are the same 
object. A FALSE (zero) value is returned otherwise. 
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WCValHashDict<Key,Value>::remove() 


Synopsis: 


Semantics: 


Results: 


#include <wchash.h> 
public: 

int remove( const Key & ) ; 

The remove public member function is used to remove the specified element from the dictionary. If 
an equivalent element is found, a non-zero value is returned. Zero is returned if the element is not 
found. Note that equivalence is based on the equivalence operator of the Key type. 

The element is removed from the dictionary if it found. 
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WCValHashDict<Key,Value>::resize() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wchash.h> 
public: 

void resize( unsigned ) ; 

The resize public member function is used to change the number of buckets contained in the 
dictionary. If the new number is larger than the previous dictionary size, then the hash function will be 
used on all of the stored elements to determine which bucket they should be stored into. Entries are not 
destroyed or created in the process of being moved. If there is not enough memory to resize the 
dictionary, the out_ of_ memory exception is thrown if it is enabled, and the dictionary will contain 
the number of buckets it contained before the resize. If the new number is zero, then the 
zero_ buckets exception is thrown if it is enabled, and no resize will be performed. The dictionary 
is guaranteed to contain the same number of entries after the resize. 

The dictionary is resized to the new number of buckets. 

WCExcept: : out_ of_ memory^CExcept: : zero_ buckets 
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WCValHashTable<Type>, WCValHashSet<Type> 


Declared: 


wchash.h 


WCValHashTable<Type> and WCValHashSet<Type> classes are templated classes used to store 
objects in a hash. A hash saves objects in such a way as to make it efficient to locate and retrieve an 
element. As an element is looked up or inserted into the hash, the value of the element is hashed. 
Hashing results in a numeric index which is used to locate the value. The storage area referenced by the 
hash value is usually called a bucket. If more than one element results in the same hash, the value 
associated with the hash is placed in a list stored in the bucket. A hash table allows more than one copy 
of an element that is equivalent, while the hash set allows only one copy. The equality operator of the 
element’s type is used to locate the value. 

In the description of each member function, the text Type is used to indicate the template parameter 
defining the type of the data to be stored in the hash. 

The constructor for the WCValHashTable<Type> and WCValHashSet<Type> classes requires a 
hashing function, which given a reference to Type, returns an unsigned value. The returned value 
modulo the number of buckets determines the bucket into which the element will be located. The return 
values of the hash function can be spread over the entire range of unsigned numbers. The hash function 
return value must be the same for values which are equivalent by the equivalence operator for Type . 

Values are copied into the hash, which could be undesirable if the stored objects are complicated and 
copying is expensive. Value hashes should not be used to store objects of a base class if any derived 
types of different sizes would be stored in the hash, or if the destructor for a derived class must be 
called. 

The WCExcept class is a base class of the WCValHashTable<Type> and 
WCValHashSet<Type> classes and provides the exceptions member function. This member 
function controls the exceptions which can be thrown by the WCValHashTable<Type> and 
WCValHashSet<Type> objects. No exceptions are enabled unless they are set by the exceptions 
member function. 

Requirements of Type 

The WCValHashTable<Type> and WCValHashSet<Type> classes requires Type to have: 

A default constructor ( Type : : Type () ). 

A well defined copy constructor ( Type : : Type ( const Type & ) ). 

A well defined assignment operator ( Type & operator =( const Type & ) ). 

A well defined equivalence operator with constant parameters 
( int operator == ( const Type & ) const ). 

Public Member Functions 


The following member functions are declared in the public interface: 


WCValHashSet! unsigned (*hash_fn) ( const Type 
WC_ DEFAULT_ HASH_ SIZE ) ; 

WCValHashSet( unsigned (*hash_fn) ( const Type 
WC_ DEFAULT_ HASH_ SIZE, void * (*user_ alloc) ( 

(*user_ dealloc) ( void *old, size_ t size ) ); 

WCValHashSet( const WCValHashSet & ) ; 
virtual ~WCValHashSet (); 


& ), unsigned 

& ), unsigned 
size_ t size ) 


void 
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WCValHashTable<Type>, WCValHashSet<Type> 


WCValHashTable( unsigned (*hash_ fn) ( const Type & ), unsigned = 
WC_ DEFAULT_ HASH_ SIZE ); 

WCValHashTable( unsigned (*hash_ fn) ( const Type & ), unsigned = 
WC_ DEFAULT_ HASH_ SIZE, void * (*user_ alloc) ( size_ t size ), void 

(*user_ dealloc) ( void *old, size_ t size ) ); 

WCValHashTable( const WCValHashTable & ); 
virtual ~WCValHashTable() ; 

static unsigned bitHash( const void *, size_t ); 
unsigned buckets() const; 
void clear (); 

int contains ( const Type & ) const; 

unsigned entries () const; 

int find( const Type &, Type & ) const; 

void forAll( void (*user_ fn) ( Type, void * ), void * ); 

int insert ( const Type & ); 

int isEmptyO const; 

int remove( const Type & ) ; 

void resize( unsigned ) ; 

The following public member functions are available for the WCValHashTable class only: 

unsigned occurrencesOf( const Type & ) const; 
unsigned removeAll( const Type & ); 

Public Member Operators 

The following member operators are declared in the public interface: 

WCValHashSet & operator =( const WCValHashSet & ); 
int operator ==( const WCValHashSet & ) const; 

WCValHashTable & operator =( const WCValHashTable & ); 
int operator == ( const WCValHashTable & ) const; 
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WC ValHashSet<Type>:: WCValHashSetQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCValHashSet( unsigned (*hash_fn) ( const Type & ), 
unsigned = WC_ DEFAULT_ HASH_ SIZE ); 

The WCValHashSet<Type> constructor creates a WCValHashSet object with no entries and with 

the number of buckets in the second optional parameter, which defaults to the constant 

WC_ DEFAULT_ HASH_ SIZE (currently defined as 101). The number of buckets specified must be 

greater than zero, and will be forced to at least one. If the hash object can be created, but an allocation 

failure occurs when creating the buckets, the table will be created with zero buckets. If the 

out_ of_ memory exception is enabled, then attempting to insert into a hash table with zero buckets 

with throw an out_ of_ memory error. 

The hash function hash_ f n is used to determine which bucket each value will be assigned to. If no 
hash function exists, the static member function bitHash is available to help create one. 

The WCValHashSet<Type> constructor creates an initialized WCValHashSet object with the 
specified number of buckets and hash function. 

~WCValHashSet, bitHash, WCExcept: : out_ of_ memory 
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WCValHashSet<Type>::WCValHashSet() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCValHashSet( unsigned (*hash_fn) ( const Type & ), 

unsigned = WC_ DEFAULT_ HASH_ SIZE, 

void * (*user_ alloc) ( size_ t ), 

void (*user_ dealloc) ( void *, size_ t ) ); 

Allocator and deallocator functions are specified for use when entries are inseited and removed from the 
hash. The semantics of this constructor are the same as the constructor without the memory 
management functions. 

The allocation function must return a zero if it cannot perform the allocation. The deallocation function 
is passed the size as well as the pointer to the data. Your allocation system may take advantage of the 
characteristic that the allocation function will always be called with the same size value for any 
particular instantiation of a hash. To determine the size of the objects that the memory management 
functions will be required to allocate and free, the following macro may be used: 
WCValHashSetltemSize( Type ) 

The WCValHashSet<Type> constructor creates an initialized WCValHashSet object with the 
specified number of buckets and hash function. 

~WCValHashSet, bitHash, WCExcept: : out_ of_ memory 
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WC ValHashSet<Type>:: WCValHashSetQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCValHashSet( const WCValHashSet & ); 

The WCValHashSet<Type> is the copy constructor for the WCValHashSet class. The new hash is 
created with the same number of buckets, hash function, all values or pointers stored in the hash, and 
the exception trap states. If the hash object can be created, but an allocation failure occurs when 
creating the buckets, the hash will be created with zero buckets. If there is not enough memory to copy 
all of the values, then only some will be copied, and the number of entries will correctly reflect the 
number copied. If all of the elements cannot be copied, then the out_ of_ memory exception is 
thrown if it is enabled. 

The WCValHashSet<Type> constructor creates a WCValHashSet object which is a copy of the 
passed hash. 

~WCValHashSet, operator =, WCExcept: : out_ of_ memory 
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WCValHashSet<Type>::~ WCValHashSetQ 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchash.h> 
public: 

virtual ~WCValHashSet() ; 

The WCValHashSet<Type> destructor is the destructor for the WCValHashSet class. If the 
number of elements is not zero and the not_ empty exception is enabled, the exception is thrown. 
Otherwise, the hash elements are cleared using the clear member function. The call to the 
WCValHashSet<Type> destructor is inserted implicitly by the compiler at the point where the 
WCValHashSet object goes out of scope. 

The call to the WCValHashSet<Type> destructor destroys a WCValHashSet object, 
clear, WCExcept: : not_ empty 
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WCValHashTable<Type>::WCValHashTable() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCValHashTable( unsigned (*hash_ fn) ( const Type & ), 
unsigned = WC_ DEFAULT_ HASH_ SIZE ); 

The WCValHashTable<Type> constructor creates a WCValHashTable object with no entries and 

with the number of buckets in the second optional parameter, which defaults to the constant 

WC_ DEFAULT_ HASH_ SIZE (currently defined as 101). The number of buckets specified must be 

greater than zero, and will be forced to at least one. If the hash object can be created, but an allocation 

failure occurs when creating the buckets, the table will be created with zero buckets. If the 

out_ of_ memory exception is enabled, then attempting to insert into a hash table with zero buckets 

with throw an out_ of_ memory error. 

The hash function hash_ f n is used to determine which bucket each value will be assigned to. If no 
hash function exists, the static member function bitHash is available to help create one. 

The WCValHashTable<Type> constructor creates an initialized WCValHashTable object with 
the specified number of buckets and hash function. 

~WCValHashTable, bitHash, WCExcept: : out_ of_ memory 
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WCValHash Table<Type>:: WC ValHash TableQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCValHashTable( unsigned (*hash_ fn) ( const Type & ), 

unsigned = WC_ DEFAULT_ HASH_ SIZE, 

void * (*user_ alloc) ( size_ t ), 

void (*user_ dealloc) ( void *, size_ t ) ); 

Allocator and deallocator functions are specified for use when entries are inseited and removed from the 
hash. The semantics of this constructor are the same as the constructor without the memory 
management functions. 

The allocation function must return a zero if it cannot perform the allocation. The deallocation function 
is passed the size as well as the pointer to the data. Your allocation system may take advantage of the 
characteristic that the allocation function will always be called with the same size value for any 
particular instantiation of a hash. To determine the size of the objects that the memory management 
functions will be required to allocate and free, the following macro may be used: 
WCValHashTableltemSize( Type ) 

The WCValHashTable<Type> constructor creates an initialized WCValHashTable object with 
the specified number of buckets and hash function. 

~WCValHashTable, bitHash, WCExcept: : out_ of_ memory 
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WCValHashTable<Type>::WCValHashTable() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCValHashTable( const WCValHashTable & ); 

The WCValHashTable<Type> is the copy constructor for the WCValHashTable class. The new 
hash is created with the same number of buckets, hash function, all values or pointers stored in the hash, 
and the exception trap states. If the hash object can be created, but an allocation failure occurs when 
creating the buckets, the hash will be created with zero buckets. If there is not enough memory to copy 
all of the values, then only some will be copied, and the number of entries will correctly reflect the 
number copied. If all of the elements cannot be copied, then the out_ of_ memory exception is 
thrown if it is enabled. 

The WCValHashTable<Type> constructor creates a WCValHashTable object which is a copy of 
the passed hash. 

~WCValHashTable, operator =, WCExcept: : out_ of_ memory 
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WCValHashTable<Type>::~WCValHashTable() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchash.h> 
public: 

virtual ~WCValHashTable() ; 

The WCValHashTable<Type> destructor is the destructor for the WCValHashTable class. If the 
number of elements is not zero and the not_ empty exception is enabled, the exception is thrown. 
Otherwise, the hash elements are cleared using the clear member function. The call to the 
WCValHashTable<Type> destructor is inserted implicitly by the compiler at the point where the 
WCValHashTable object goes out of scope. 

The call to the WCValHashTable<Type> destructor destroys a WCValHashTable object, 
clear, WCExcept: : not_ empty 
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WCValHashTable<Type>::bitHash(), WCValHashSet<Type>::bitHash() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wchash.h> 
public: 

static unsigned bitHash( void *, size_ t ); 

The bitHash public member function can be used to implement a hashing function for any type. A 
hashing value is generated from the value stored for the number of specified bytes pointed to by the first 
parameter. For example: 


unsigned my_ hash_ fn ( const int & elem ) { 

return( WCValHashSetcint,String>::bitHash(&elem, sizeof(int)); 

} 

WCValHashSet<int> data_ object ( &my_ hash_ fn ) ; 

The bitHash public member function returns an unsigned value which can be used as the basis of a 
user defined hash function. 

WCValHashSet, WCValHashTable 
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WCValHashTable<Type>::buckets(), WCValHashSet<Type>::buckets() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchash.h> 
public: 

unsigned buckets() const; 

The buckets public member function is used to find the number of buckets contained in the hash 
object. 

The buckets public member function returns the number of buckets in the hash, 
resize 
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WCValHashTable<Type>::clear(), WCValHashSet<Type>::clear() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchash.h> 

public: 

void clear(); 

The clear public member function is used to clear the hash so that it has no entries. The number of 
buckets remain unaffected. Elements stored in the hash are destroyed using the destructors of Type . 
The hash object is not destroyed and re-created by this function, so the object destructor is not invoked. 

The clear public member function clears the hash to have no elements. 

~WCValHashSet, ~WCValHashTable, operator = 
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WCValHashTable<Type>::contains(), WCValHashSet<Type>::contains() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchash.h> 
public: 

int contains( const Type & ) const; 

The contains public member function returns non-zero if the element is stored in the hash, or zero if 
there is no equivalent element. Note that equivalence is based on the equivalence operator of the 
element type. 

The contains public member function returns a non-zero value if the element is found in the hash, 
find 
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WCValHashTable<Type>::entries(), WCValHashSet<Type>::entries() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchash.h> 
public: 

unsigned entries() const; 

The entries public member function is used to return the current number of elements stored in the 
hash. 

The entries public member function returns the number of elements in the hash, 
buckets, isEmpty 
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WCValHashTable<Type>::find(), WCValHashSet<Type>::find() 


Synopsis: 


Semantics: 


Results: 


#include <wchash.h> 
public: 

int find( const Type &, Type & ) const; 

The find public member function is used to find an element with an equivalent key in the hash. If an 
equivalent element is found, a non-zero value is returned. The reference to the element passed as the 
second argument is assigned the found element’s value. Zero is returned if the element is not found. 
Note that equivalence is based on the equivalence operator of the element type. 

The element equivalent to the passed key is located in the hash. 
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WCValHashTable<Type>::forAII(), WCValHashSet<Type>::forAII() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wchash.h> 
public: 
void forAll( 

void (*user_ fn) ( Type, void * ), 
void * ); 

The forAll public member function causes the user supplied function to be invoked for every value in 
the hash. The user function has the prototype 


void user_ func( Type S value, void * data ); 

As the elements are visited, the user function is invoked with the element passed as the first. The 
second parameter of the forAll function is passed as the second parameter to the user function. This 
value can be used to pass any appropriate data from the main code to the user function. 

The elements in the hash are all visited, with the user function being invoked for each one. 

find 
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WCValHashTable<Type>::insert(), WCValHashSet<Type>::insert() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wchash.h> 
public: 

int insert( const Type & ) ; 

The insert public member function inserts a value into the hash, using the hash function to determine 
to which bucket it should be stored. If allocation of the node to store the value fails, then the 
out_ of_ memory exception is thrown if it is enabled. If the exception is not enabled, the insert will 
not be completed. 

With a WCValHashSet, there must be only one equivalent element in the set. If an element 
equivalent to the inserted element is already in the hash set, the hash set will remain unchanged, and the 
not_ unique exception is thrown if it is enabled. If the exception is not enabled, the insert will not be 
completed. 

At some point, the number of buckets initially selected may be too small for the number of elements 
inserted. The resize of the hash can be controlled by the insertion mechanism by using 
WCValHashSet (or WCValHashTable) as a base class, and providing an insert member function to 
do a resize when appropriate. This insert could then call WCValHashSet: : insert (or 
WCValHashTable : : insert) to insert the element. Note that copy constructors and assignment 
operators are not inherited in your class, but you can provide the following inline definitions (assuming 
that the class inherited from WCValHashTable is named MyHashTable): 


inline MyHashTable( const MyHashTable &orig ) 

: WCValHashTable( orig ) {}; 

inline MyHashTable &operator=( const MyHashTable &orig ) { 

return( WCValHashTable::operator=( orig ) ); 

} 

The insert public member function inserts a value into the hash. If the insert is successful, a 
non-zero will returned. A zero will be returned if the insert fails. 

operator =, WCExcept: : out_ of_ memory 
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WCValHashTable<Type>::isEmpty(), WCValHashSet<Type>::isEmpty() 


Synopsis: 

Semantics 

Results: 

See Also: 


#include <wchash.h> 
public: 

int isEmptyO const; 

The is Empty public member function is used to determine if the hash is empty. 

The is Empty public member function returns zero if it contains at least one entry, non-zero if the hash 
is empty. 

buckets, entries 
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WCValHashTable<Type>::occurencesOf() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchash.h> 
public: 

unsigned occurrencesOf( const Type & ) const; 

The occurencesOf public member function is used to return the current number of elements stored 
in the hash which are equivalent to the passed value. Note that equivalence is based on the equivalence 
operator of the element type. 

The occurencesOf public member function returns the number of elements in the hash, 
buckets, entries, find, isEmpty 
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WCValHashTable<Type>::operator =(), WCValHashSet<Type>::operator =() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchash.h> 
public: 

WCValHashSet & operator =( const WCValHashSet & ); 

WCValHashTable & operator =( const WCValHashTable & ); 

The operator = public member function is the assignment operator for the 

WCValHashTable<Type> and WCValHashSet<Type> classes. The left hand side hash is first 
cleared using the clear member function, and then the right hand side hash is copied. The hash 
function, exception trap states, and all of the hash elements are copied. If an allocation failure occurs 
when creating the buckets, the table will be created with zero buckets, and the out_ of_ memory 
exception is thrown if it is enabled. If there is not enough memory to copy all of the values or pointers 
in the hash, then only some will be copied, and the out_ of_ memory exception is thrown if it is 
enabled. The number of entries will correctly reflect the number copied. 

The operator = public member function assigns the left hand side hash to be a copy of the right 
hand side. 

clear, WCExcept: : out_ of_ memory 
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WCValHashTable<Type>::operator ==(), WCValHashSet<Type>:-.operator ==() 


Synopsis: 


Semantics: 


Results: 


#include <wchash.h> 
public: 

int operator ==( const WCValHashSet & ) const; 
int operator ==( const WCValHashTable & ) const; 

The operator == public member function is the equivalence operator for the 

WCValHashTable<Type> and WCValHashSet<Type> classes. Two hash objects are equivalent 
if they are the same object and share the same address. 

A TRUE (non-zero) value is returned if the left hand side and right hand side hash are the same object. 
A FALSE (zero) value is returned otherwise. 
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WCValHashTable<Type>::remove(), WCValHashSet<Type>::remove() 


Synopsis: 


Semantics: 


Results: 


#include <wchash.h> 
public: 

int remove( const Type & ) ; 

The remove public member function is used to remove the specified element from the hash. If an 
equivalent element is found, a non-zero value is returned. Zero is returned if the element is not found. 
If the hash is a table and there is more than one element equivalent to the specified element, then the 
first equivalent element added to the table is removed. Note that equivalence is based on the 
equivalence operator of the element type. 

The element is removed from the hash if it found. 
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WCValHashTable<Type>::removeAII() 


Synopsis: 


Semantics: 


Results: 


#include <wchash.h> 
public: 

unsigned removeAll( const Type & ); 

The removeAll public member function is used to remove all elements equivalent to the specified 
element from the hash. Zero is returned if no equivalent elements are found. Note that equivalence is 
based on the equivalence operator of the element type. 

All equivalent elements are removed from the hash. 
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WCValHashTable<Type>::resize(), WCValHashSet<Type>::resize() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wchash.h> 
public: 

void resize( unsigned ) ; 

The resize public member function is used to change the number of buckets contained in the hash. If 
the new number is larger than the previous hash size, then the hash function will be used on all of the 
stored elements to determine which bucket they should be stored into. Entries are not destroyed or 
created in the process of being moved. If there is not enough memory to resize the hash, the 
out_ of_ memory exception is thrown if it is enabled, and the hash will contain the number of buckets 
it contained before the resize. If the new number is zero, then the zero_ buckets exception is 
thrown if it is enabled, and no resize will be performed. The hash is guaranteed to contain the same 
number of entries after the resize. 

The hash is resized to the new number of buckets. 

WCExcept: : out_ of_ memory^CExcept: : zero_ buckets 
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WCValHashTable<Type>::resize(), WCValHashSet<Type>::resize() 
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11 Hash Iterators 


Hash iterators are used to step through a hash one or more elements at a time. Iterators which are newly 
constructed or reset are positioned before the first element in the hash. The hash may be traversed one 
element at a time using the pre-increment or call operator. An increment operation causing the iterator to 
be positioned after the end of the hash returns zero. Further increments will cause the undef_ iter 
exception to be thrown, if it is enabled. The WCIterExcept class provides the common exception 
handling control interface for all of the iterators. 

Since the iterator classes are all template classes, most of the functionality was derived from common base 
classes. In the listing of class member functions, those public member functions which appear to be in the 
iterator class but are actually defined in the common base class are identified as if they were explicitly 
specified in the iterator class. 
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WCPtrHashDictlter<Key, Value> 


Declared: 


wchiter.h 

The WCPtrHashDictIter<Key, Value> class is the templated class used to create iterator objects 
for WCPtrHashDict<Key, Value> objects. In the description of each member function, the text 
Key is used to indicate the template parameter defining the type of the indices pointed to by the pointers 
stored in the dictionary. The text Value is used to indicate the template parameter defining the type of 
the data pointed to by the pointers stored in the dictionary. The WCIterExcept class is a base class 
of the WCPtrHashDictIter<Key, Value> class and provides the exceptions member 
function. This member function controls the exceptions which can be thrown by the 
WCPtrHashDictIter<Key, Value> object. No exceptions are enabled unless they are set by the 
exceptions member function. 

Public Member Functions 

The following member functions are declared in the public interface: 

WCPtrHashDictlter (); 

WCPtrHashDictlter! const WCPtrHashDict<Key,Value> & ); 
~WCPtrHashDictIter(); 

const WCPtrHashDict<Key,Value> *container () const; 

Key *key(); 
void reset(); 

void reset( WCPtrHashDict<Key,Value> & ); 

Value * value(); 

Public Member Operators 

The following member operators are declared in the public interface: 

int operator () (); 
int operator ++(); 
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WCPtrHashDictlter<Key, Value>:: WCPtrHashDictlterQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

WCPtrHashDictlter(); 

The public WCPtrHashDictIter<Key, Value> constructor is the default constructor for the class 
and initializes the iterator with no hash to operate on. The reset member function must be called to 
provide the iterator with a hash to iterate over. 

The public WCPtrHashDictIter<Key, Value> constructor creates an initialized 
WCPtrHashDictlter hash iterator object. 

~WCPtrHashDictIter, reset 
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WCPtrHashDictlter<Key, Value>:: WCPtrHashDictlterQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

WCPtrHashDictlter( WCPtrHashDict<Key, Value> & ); 

The public WCPtrHashDictIter<Key, Value> constructor is a constructor for the class. The 
value passed as a parameter is a WCPtrHashDict hash object. The iterator will be initialized for that 
hash object and positioned before the first hash element. To position the iterator to a valid element 
within the hash, increment it using one of the operator ++or operator () operators. 

The public WCPtrHashDictIter<Key, Value> constructor creates an initialized 
WCPtrHashDictlter hash iterator object positioned before the first element in the hash. 

~WCPtrHashDictIter, operator (),operator ++, reset 
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WCPtrHashDictlter<Key, Value>::~ WCPtrHashDictlterQ 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wchiter.h> 
public: 

~WCPtrHashDictIter() ; 

The public ~WCPtrHashDictIter<Key, Value> destructor is the destructor for the class. The 
call to the destructor is inserted implicitly by the compiler at the point where the 
WCPtrHashDictlter hash iterator object goes out of scope. 

The WCPtrHashDictlter hash iterator object is destroyed. 

WCPtrHashDictlter 
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WCPtrHashDictlter<Key,Value>::container() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

WCPtrHashDict<Key,Value> *container() const; 

The container public member function returns a pointer to the hash container object. If the iterator 
has not been initialized with a hash object, and the undef_ iter exception is enabled, the exception is 
thrown. 

A pointer to the hash object associated with the iterator is returned, or NULL(O) if the iterator has not 
been initialized with a hash. 

WCPtrHashDictlter, reset, WCIterExcept::undef_ iter 
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WCPtrHashDictlter<Key,Value>::key() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

Key *key(); 

The key public member function returns a pointer to the Key value of the hash item at the current 
iterator position. 

If the iterator is not associated with a hash, or the iterator position is either before the first element or 
past the last element in the hash, the current iterator position is undefined. In this case the 
undef_ item exception is thrown, if enabled. 

A pointer to Key at the current iterator element is returned. If the current element is undefined, an 
undefined pointer is returned. 

operator (), operator ++, reset, WCIterExcept::undef_ item 
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WCPtrHashDictlter<Key, Value>::operator ()() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wchiter.h> 
public: 

int operator ()(); 

The operator () public member function is the call operator for the class. The hash element which 
follows the current item is set to be the new current item. If the previous current item was the last 
element in the hash, the iterator is positioned after the end of the hash. 

The operator () public member function has the same semantics as the pre-increment operator, 
operator ++. 

If the iterator was positioned before the first hash element, the current item will be set to the first 
element. If the hash is empty, the iterator will be positioned after the end of the hash. 

If the iterator is not associated with a hash or the iterator position before the increment was past the last 
element the hash, the undef_ iter exception is thrown, if enabled. 

The operator () public member function returns a non-zero value if the iterator is positioned on a 
hash item. Zero(O) is returned when the iterator is incremented past the end of the hash. 

operator ++,reset, WCIterExcept::undef_ iter 
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WCPtrHashDictlter<Key, Value>::operator ++() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

int operator ++(); 

The operator ++ public member function is the pre-increment operator for the class. The hash 
element which follows the current item is set to be the new current item. If the previous current item 
was the last element in the hash, the iterator is positioned after the end of the hash. 

The operator ++ public member function has the same semantics as the call operator, operator 
() - 

The current item will be set to the first hash element if the iterator was positioned before the first 
element in the hash. If the hash is empty, the iterator will be positioned after the end of the hash. 

If the iterator is not associated with a hash or the iterator position before the increment was past the last 
element the hash, the undef_ iter exception is thrown, if enabled. 

The operator ++ public member function returns a non-zero value if the iterator is positioned on a 
hash item. Zero(O) is returned when the iterator is incremented past the end of the hash. 

operator (), reset, WCIterExcept::undef_ iter 
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WCPtrHashDictlter<Key,Value>::reset() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wchiter.h> 

public: 

void reset(); 

The reset public member function resets the iterator to the initial state, positioning the iterator before 
the first element in the associated hash. 

The iterator is positioned before the first hash element. 

WCPtrHashDictlter, container 
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WCPtrHashDictlter<Key,Value>::reset() 


Synopsis: #include <wchiter.h> 

public: 

void reset( WCPtrHashDict<Key, Value> & ); 


Semantics: 

Results: 
See Also: 


The reset public member function resets the iterator to operate on the specified hash. The iterator is 
positioned before the first element in the hash. 

The iterator is positioned before the first element of the specified hash. 

WCPtrHashDictlter, container 
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WCPtrHashDictlter<Key,Value>::value() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wchiter.h> 
public: 

Value ‘value(); 

The value public member function returns a pointer to the Value the current iterator position. 

If the iterator is not associated with a hash, or the iterator position is either before the first element or 
past the last element in the hash, the current iterator position is undefined. In this case the 
undef_ item exception is thrown, if enabled. 

A pointer to the Value at the current iterator element is returned. If the current element is undefined, 
an undefined pointer is returned. 

operator (), operator ++, reset, WCIterExcept::undef_ item 
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WCValHashDictlter<Key, Value> 


Declared: 


wchiter.h 

The WCValHashDictIter<Key, Value> class is the templated class used to create iterator objects 
for WCValHashDict<Key, Value> objects. In the description of each member function, the text 
Key is used to indicate the template parameter defining the type of the indices used to store data in the 
dictionary. The text Value is used to indicate the template parameter defining the type of the data 
stored in the dictionary. The WCIterExcept class is a base class of the 

WCValHashDictIter<Key, Value> class and provides the exceptions member function. This 
member function controls the exceptions which can be thrown by the 

WCValHashDictIter<Key, Value> object. No exceptions are enabled unless they are set by the 
exceptions member function. 

Public Member Functions 

The following member functions are declared in the public interface: 

WCValHashDictlter (); 

WCValHashDictlter! const WCValHashDict<Key,Value> & ); 
~WCValHashDictIter(); 

const WCValHashDict<Key,Value> *container() const; 

Key key(); 
void reset(); 

void reset( WCValHashDict<Key, Value> & ); 

Value value(); 

Public Member Operators 

The following member operators are declared in the public interface: 

int operator () (); 
int operator ++(); 
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WCValHashDictlter<Key, Value>:: WC ValHashDictlterQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

WCValHashDictlter() ; 

The public WCValHashDictIter<Key, Value> constructor is the default constructor for the class 
and initializes the iterator with no hash to operate on. The reset member function must be called to 
provide the iterator with a hash to iterate over. 

The public WCValHashDictIter<Key, Value> constructor creates an initialized 
WCValHashDictlter hash iterator object. 

~WCValHashDictIter, reset 
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WCValHashDictlter<Key, Value>:: WCValHashDictlterQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

WCValHashDictlter( WCValHashDict<Key,Value> & ); 

The public WCValHashDictIter<Key, Value> constructor is a constructor for the class. The 
value passed as a parameter is a WCValHashDict hash object. The iterator will be initialized for that 
hash object and positioned before the first hash element. To position the iterator to a valid element 
within the hash, increment it using one of the operator ++or operator () operators. 

The public WCValHashDict Iter<Key, Value> constructor creates an initialized 
WCValHashDictlter hash iterator object positioned before the first element in the hash. 

~WCValHashDictIter, operator (),operator ++, reset 
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WCValHashDictlter<Key, Value>::~ WCValHashDictlterQ 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wchiter.h> 
public: 

~WCValHashDictIter() ; 

The public ~WCValHashDictIter<Key, Value> destructor is the destructor for the class. The 
call to the destructor is inserted implicitly by the compiler at the point where the 
WCValHashDictlter hash iterator object goes out of scope. 

The WCValHashDictlter hash iterator object is destroyed. 

WCValHashDictlter 
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WCValHashDictlter<Key,Value>::container() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

WCValHashDict<Key,Value> *container() const; 

The container public member function returns a pointer to the hash container object. If the iterator 
has not been initialized with a hash object, and the undef_ iter exception is enabled, the exception is 
thrown. 

A pointer to the hash object associated with the iterator is returned, or NULL(O) if the iterator has not 
been initialized with a hash. 

WCValHashDictlter, reset, WCIterExcept::undef_ iter 
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WCValHashDictlter<Key,Value>::key() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

Key key(); 

The key public member function returns the value of Key at the current iterator position. 

If the iterator is not associated with a hash, or the iterator position is either before the first element or 
past the last element in the hash, the current iterator position is undefined. In this case the 
undef_ item exception is thrown, if enabled. 

The value of Key at the current iterator element is returned. If the current element is undefined, a 
default initialized object is returned. 

operator (), operator ++, reset, WCIterExcept::undef_ item 
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WCValHashDictlter<Key, Value>::operator ()() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

int operator ()(); 

The operator () public member function is the call operator for the class. The hash element which 
follows the current item is set to be the new current item. If the previous current item was the last 
element in the hash, the iterator is positioned after the end of the hash. 

The operator () public member function has the same semantics as the pre-increment operator, 
operator ++. 

If the iterator was positioned before the first hash element, the current item will be set to the first 
element. If the hash is empty, the iterator will be positioned after the end of the hash. 

If the iterator is not associated with a hash or the iterator position before the increment was past the last 
element the hash, the undef_ iter exception is thrown, if enabled. 

The operator () public member function returns a non-zero value if the iterator is positioned on a 
hash item. Zero(O) is returned when the iterator is incremented past the end of the hash. 

operator ++,reset, WCIterExcept::undef_ iter 
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WCValHashDictlter<Key, Value>::operator ++() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wchiter.h> 
public: 

int operator ++(); 

The operator ++ public member function is the pre-increment operator for the class. The hash 
element which follows the current item is set to be the new current item. If the previous current item 
was the last element in the hash, the iterator is positioned after the end of the hash. 

The operator ++ public member function has the same semantics as the call operator, operator 
() - 

The current item will be set to the first hash element if the iterator was positioned before the first 
element in the hash. If the hash is empty, the iterator will be positioned after the end of the hash. 

If the iterator is not associated with a hash or the iterator position before the increment was past the last 
element the hash, the undef_ iter exception is thrown, if enabled. 

The operator ++ public member function returns a non-zero value if the iterator is positioned on a 
hash item. Zero(O) is returned when the iterator is incremented past the end of the hash. 

operator (), reset, WCIterExcept::undef_ iter 
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WC ValHashDictlter<Key, Value>::reset() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wchiter.h> 

public: 

void reset(); 

The reset public member function resets the iterator to the initial state, positioning the iterator before 
the first element in the associated hash. 

The iterator is positioned before the first hash element. 

WCValHashDictlter, container 
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WCValHashDictlter<Key,Value>::reset() 


Synopsis: #include <wchiter.h> 

public: 

void reset( WCValHashDict<Key, Value> & ); 


Semantics: 

Results: 
See Also: 


The reset public member function resets the iterator to operate on the specified hash. The iterator is 
positioned before the first element in the hash. 

The iterator is positioned before the first element of the specified hash. 

WCValHashDictlter, container 
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WCValHashDictlter<Key,Value>::value() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

Value value(); 

The value public member function returns the value of Value at the current iterator position. 

If the iterator is not associated with a hash, or the iterator position is either before the first element or 
past the last element in the hash, the current iterator position is undefined. In this case the 
undef_ item exception is thrown, if enabled. 

The value of the Value at the current iterator element is returned. If the current element is undefined, 
a default initialized object is returned. 

operator (), operator ++, reset, WCIterExcept::undef_ item 
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WCPtrHashSetlter<Type>, WCPtrHash Tablelter<Type> 


Declared: 


wchiter.h 

The WCPtrHashSetIter<Type> and WCPtrHashTableIter<Type> classes are the templated 
classes used to create iterator objects for WCPtrHashTable<Type> and WCPtrHashSet<Type> 
objects. In the description of each member function, the text Type is used to indicate the hash element 
type specified as the template parameter. The WCIterExcept class is a base class of the 
WCPtrHashSetIter<Type> and WCPtrHashTableIter<Type> classes and provides the 
exceptions member function. This member function controls the exceptions which can be thrown 
by the WCPtrHashSetIter<Type> and WCPtrHashTableIter<Type> objects. No 
exceptions are enabled unless they are set by the exceptions member function. 

Public Member Functions 

The following member functions are declared in the public interface: 

WCPtrHashSetlter (); 

WCPtrHashSetlter ( const WCPtrHashSet<Type> & ); 

-WCPtrHashSetlter(); 

WCPtrHashTablelter(); 

WCPtrHashTablelter( const WCPtrHashTable<Type> & ) ; 
-WCPtrHashTablelter() ; 

const WCPtrHashTable<Type> *container() const; 
const WCPtrHashSet<Type> *container() const; 

Type ‘current() const; 
void reset(); 

void WCPtrHashSetIter<Type>::reset( WCPtrHashSet<Type> & ); 
void WCPtrHashTableIter<Type>::reset( WCPtrHashTable<Type> & ); 

Public Member Operators 

The following member operators are declared in the public interface: 

int operator () (); 
int operator ++(); 
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WCPtrHashSetlter<Type>::WCPtrHashSetlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

WCPtrHashSetlter(); 

The public WCPtrHashSetIter<Type> constructor is the default constructor for the class and 
initializes the iterator with no hash to operate on. The reset member function must be called to 
provide the iterator with a hash to iterate over. 

The public WCPtrHashSetIter<Type> constructor creates an initialized WCPtrHashSetlter 
hash iterator object. 

~WCPtrHashSetIter, WCPtrHashTablelter, reset 
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WCPtrHashSetlter<Type>::WCPtrHashSetlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

WCPtrHashSetlter( WCPtrHashSet<Type> & ) ; 

The public WCPtrHashSetIter<Type> constructor is a constructor for the class. The value passed 
as a parameter is a WCPtrHashSet hash object. The iterator will be initialized for that hash object 
and positioned before the first hash element. To position the iterator to a valid element within the hash, 
increment it using one of the operator ++or operator () operators. 

The public WCPtrHashSetIter<Type> constructor creates an initialized WCPtrHashSetlter 
hash iterator object positioned before the first element in the hash. 

~WCPtrHashSetIter, operator (), operator ++, reset 
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WCPtrHashSetlter<Type>::~WCPtrHashSetlter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchiter.h> 
public: 

-WCPtrHashSetlter() ; 

The public ~WCPtrHashSetIter<Type> destructor is the destructor for the class. The call to the 
destructor is inserted implicitly by the compiler at the point where the WCPtrHashSetlter hash 
iterator object goes out of scope. 

The WCPtrHashSetlter hash iterator object is destroyed. 

WCPtrHashSetlter, WCPtrHashTablelter 
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WCPtrHash Tablelter<Type>:: WCPtrHashTablelterQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

WCPtrHashTablelter(); 

The public WCPtrHashTableIter<Type> constructor is the default constructor for the class and 
initializes the iterator with no hash to operate on. The reset member function must be called to 
provide the iterator with a hash to iterate over. 

The public WCPtrHashTableIter<Type> constructor creates an initialized 
WCPtrHashTablelter hash iterator object. 

~WCPtrHashTableIter, WCPtrHashSetlter, reset 
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WCPtrHash Tablelter<Type>:: WCPtrHashTablelterQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

WCPtrHashTablelter( WCPtrHashTable<Type> & ) ; 

The public WCPtrHashTableIter<Type> constructor is a constructor for the class. The value 
passed as a parameter is a WCPtrHashTable hash object. The iterator will be initialized for that hash 
object and positioned before the first hash element. To position the iterator to a valid element within the 
hash, increment it using one of the operator ++ or operator () operators. 

The public WCPtrHashTableIter<Type> constructor creates an initialized 
WCPtrHashTablelter hash iterator object positioned before the first element in the hash. 

~WCPtrHashTableIter, operator (), operator ++, reset 
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WCPtrHashTablelter<Type>::~WCPtrHashTablelter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchiter.h> 
public: 

~WCPtrHashTableIter() ; 

The WCPtrHashTableIter<Type> destructor is the destructor for the class. The call to the 
destructor is inserted implicitly by the compiler at the point where the WCPtrHashTablelter hash 
iterator object goes out of scope. 

The WCPtrHashTablelter hash iterator object is destroyed. 

WCPtrHashSetlter, WCPtrHashTablelter 
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WCPtrHashSetlter<Type>,WCPtrHashTablelter<Type>::container() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

WCPtrHashTable<Type> *WCPtrHashTableIter<Type>::container() const; 
WCPtrHashSet<Type> *WCPtrHashSetIter<Type>::container() const; 

The container public member function returns a pointer to the hash container object. If the iterator 
has not been initialized with a hash object, and the undef_ iter exception is enabled, the exception is 
thrown. 

A pointer to the hash object associated with the iterator is returned, or NULL(O) if the iterator has not 
been initialized with a hash. 

WCPtrHashSetlter, WCPtrHashTablelter, reset, WCIterExcept::undef_ iter 
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WCPtrHashSetlter<Type>::current(), WCPtrHashTablelter<Type>::current() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wchiter.h> 
public: 

Type *current(); 

The current public member function returns a pointer to the hash item at the current iterator position. 

If the iterator is not associated with a hash, or the iterator position is either before the first element or 
past the last element in the hash, the current iterator position is undefined. In this case the 
undef_ item exception is thrown, if enabled. 

A pointer to the current iterator element is returned. If the current element is undefined, NULL(O) is 
returned. 

operator (), operator ++, reset, WCIterExcept::undef_ item 
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WCPtrHashSetlter<Type>,WCPtrHashTablelter<Type>: operator ()() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wchiter.h> 
public: 

int operator ()(); 

The operator () public member function is the call operator for the class. The hash element which 
follows the current item is set to be the new current item. If the previous current item was the last 
element in the hash, the iterator is positioned after the end of the hash. 

The operator () public member function has the same semantics as the pre-increment operator, 
operator ++. 

If the iterator was positioned before the first hash element, the current item will be set to the first 
element. If the hash is empty, the iterator will be positioned after the end of the hash. 

If the iterator is not associated with a hash or the iterator position before the increment was past the last 
element the hash, the undef_ iter exception is thrown, if enabled. 

The operator () public member function returns a non-zero value if the iterator is positioned on a 
hash item. Zero(O) is returned when the iterator is incremented past the end of the hash. 

operator ++,reset, WCIterExcept::undef_ iter 
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WCPtrHashSetlter<Type>, WCPtrHashTablelter<Type>::operator ++() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wchiter.h> 
public: 

int operator ++(); 

The operator ++ public member function is the pre-increment operator for the class. The hash 
element which follows the current item is set to be the new current item. If the previous current item 
was the last element in the hash, the iterator is positioned after the end of the hash. 

The operator ++ public member function has the same semantics as the call operator, operator 
() - 

The current item will be set to the first hash element if the iterator was positioned before the first 
element in the hash. If the hash is empty, the iterator will be positioned after the end of the hash. 

If the iterator is not associated with a hash or the iterator position before the increment was past the last 
element the hash, the undef_ iter exception is thrown, if enabled. 

The operator ++ public member function returns a non-zero value if the iterator is positioned on a 
hash item. Zero(O) is returned when the iterator is incremented past the end of the hash. 

current, operator (), reset,WCIterExcept: :undef_ iter 
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WCPtrHashSetlter<Type>::reset(), WCPtrHashTablelter<Type>::reset() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchiter.h> 

public: 

void reset(); 

The reset public member function resets the iterator to the initial state, positioning the iterator before 
the first element in the associated hash. 

The iterator is positioned before the first hash element. 

WCPtrHashSetlter, WCPtrHashTablelter, container 
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WCPtrHashSetlter<Type>::reset(), WCPtrHashTablelter<Type>::reset() 


Synopsis: #include <wchiter.h> 

public: 

void WCPtrHashSetIter<Type>::reset ( WCPtrHashSet<Type> & ); 
void WCPtrHashTableIter<Type>::reset ( WCPtrHashTable<Type> & ); 


Semantics: 

Results: 
See Also: 


The reset public member function resets the iterator to operate on the specified hash. The iterator is 
positioned before the first element in the hash. 

The iterator is positioned before the first element of the specified hash. 

WCPtrHashSetlter, WCPtrHashTablelter, container 
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WCValHashSetlter<Type>, WCValHashTablelter<Type> 


Declared: 


wchiter.h 

The WCValHashSetIter<Type> and WCValHashTableIter<Type> classes are the templated 
classes used to create iterator objects for WCValHashTable<Type> and WCValHashSet<Type> 
objects. In the description of each member function, the text Type is used to indicate the hash element 
type specified as the template parameter. The WCIterExcept class is a base class of the 
WCValHashSetIter<Type> and WCValHashTableIter<Type> classes and provides the 
exceptions member function. This member function controls the exceptions which can be thrown 
by the WCValHashSetIter<Type> and WCValHashTableIter<Type> objects. No 
exceptions are enabled unless they are set by the exceptions member function. 

Public Member Functions 

The following member functions are declared in the public interface: 

WCValHashSetlter (); 

WCValHashSetlter( const WCValHashSet<Type> & ); 

-WCValHashSetlter(); 

WCValHashTablelter() ; 

WCValHashTablelter( const WCValHashTable<Type> & ) ; 
-WCValHashTablelter() ; 

const WCValHashTable<Type> *container() const; 
const WCValHashSet<Type> *container() const; 

Type current() const; 
void reset(); 

void WCValHashSetIter<Type>::reset( WCValHashSet<Type> & ); 
void WCValHashTableIter<Type>::reset( WCValHashTable<Type> & ); 

Public Member Operators 

The following member operators are declared in the public interface: 

int operator () (); 
int operator ++(); 
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WCValHashSetlter<Type>::WCValHashSetlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

WCValHashSetlter() ; 

The public WCValHashSetIter<Type> constructor is the default constructor for the class and 
initializes the iterator with no hash to operate on. The reset member function must be called to 
provide the iterator with a hash to iterate over. 

The public WCValHashSetIter<Type> constructor creates an initialized WCValHashSetlter 
hash iterator object. 

~WCValHashSetIter, WCValHashTablelter, reset 
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WCValHashSetlter<Type>::WCValHashSetlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

WCValHashSetlter( WCValHashSet<Type> & ); 

The public WCValHashSetIter<Type> constructor is a constructor for the class. The value passed 
as a parameter is a WCValHashSet hash object. The iterator will be initialized for that hash object 
and positioned before the first hash element. To position the iterator to a valid element within the hash, 
increment it using one of the operator ++or operator () operators. 

The public WCValHashSetIter<Type> constructor creates an initialized WCValHashSetlter 
hash iterator object positioned before the first element in the hash. 

~WCValHashSetIter, operator (), operator ++, reset 
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WCValHashSetlter<Type>::~WCValHashSetlter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchiter.h> 
public: 

-WCValHashSetlter() ; 

The public ~WCValHashSetIter<Type> destructor is the destructor for the class. The call to the 
destructor is inserted implicitly by the compiler at the point where the WCValHashSetlter hash 
iterator object goes out of scope. 

The WCValHashSetlter hash iterator object is destroyed. 

WCValHashSetlter, WCValHashTablelter 
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WCValHash Tablelter<Type>:: WC ValHashTablelterf) 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

WCValHashTablelter() ; 

The public WCValHashTableIter<Type> constructor is the default constructor for the class and 
initializes the iterator with no hash to operate on. The reset member function must be called to 
provide the iterator with a hash to iterate over. 

The public WCValHashTableIter<Type> constructor creates an initialized 
WCValHashTablelter hash iterator object. 

~WCValHashTableIter, WCValHashSetlter, reset 
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WCValHashTablelter<Type>::WCValHashTablelter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

WCValHashTablelter( WCValHashTable<Type> & ); 

The public WCValHashTableIter<Type> constructor is a constructor for the class. The value 
passed as a parameter is a WCValHashTable hash object. The iterator will be initialized for that hash 
object and positioned before the first hash element. To position the iterator to a valid element within the 
hash, increment it using one of the operator ++ or operator () operators. 

The public WCValHashTableIter<Type> constructor creates an initialized 
WCValHashTablelter hash iterator object positioned before the first element in the hash. 

~WCValHashTableIter, operator (), operator ++, reset 
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WCValHashTablelter<Type>::~WCValHashTablelter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchiter.h> 
public: 

~WCValHashTableIter() ; 

The WCValHashTableIter<Type> destructor is the destructor for the class. The call to the 
destructor is inserted implicitly by the compiler at the point where the WCValHashTablelter hash 
iterator object goes out of scope. 

The WCValHashTablelter hash iterator object is destroyed. 

WCValHashSetlter, WCValHashTablelter 
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WCValHashSetlter<Type>,WCValHashTablelter<Type>::container() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wchiter.h> 
public: 

WCValHashTable<Type> *WCValHashTableIter<Type>::container() const; 
WCValHashSet<Type> *WCValHashSetIter<Type>::container() const; 

The container public member function returns a pointer to the hash container object. If the iterator 
has not been initialized with a hash object, and the undef_ iter exception is enabled, the exception is 
thrown. 

A pointer to the hash object associated with the iterator is returned, or NULL(O) if the iterator has not 
been initialized with a hash. 

WCValHashSetlter, WCValHashTablelter, reset, WCIterExcept::undef_ iter 
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WCValHashSetlter<Type>::current(), WCValHashTablelter<Type>::current() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wchiter.h> 
public: 

Type current(); 

The current public member function returns the value of the hash element at the current iterator 
position. 

If the iterator is not associated with a hash, or the iterator position is either before the first element or 
past the last element in the hash, the current iterator position is undefined. In this case the 
undef_ item exception is thrown, if enabled. 

The value at the current iterator element is returned. If the current element is undefined, a default 
initialized object is returned. 

operator (), operator ++, reset, WCIterExcept::undef_ item 
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WCValHashSetlter<Type>,WCValHashTablelter<Type>::operator()() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wchiter.h> 
public: 

int operator ()(); 

The operator () public member function is the call operator for the class. The hash element which 
follows the current item is set to be the new current item. If the previous current item was the last 
element in the hash, the iterator is positioned after the end of the hash. 

The operator () public member function has the same semantics as the pre-increment operator, 
operator ++. 

If the iterator was positioned before the first hash element, the current item will be set to the first 
element. If the hash is empty, the iterator will be positioned after the end of the hash. 

If the iterator is not associated with a hash or the iterator position before the increment was past the last 
element the hash, the undef_ iter exception is thrown, if enabled. 

The operator () public member function returns a non-zero value if the iterator is positioned on a 
hash item. Zero(O) is returned when the iterator is incremented past the end of the hash. 

operator ++,reset, WCIterExcept::undef_ iter 
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WCValHashSetlter<Type>,WCValHashTablelter<Type>::operator ++() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wchiter.h> 
public: 

int operator ++(); 

The operator ++ public member function is the pre-increment operator for the class. The hash 
element which follows the current item is set to be the new current item. If the previous current item 
was the last element in the hash, the iterator is positioned after the end of the hash. 

The operator ++ public member function has the same semantics as the call operator, operator 
() - 

The current item will be set to the first hash element if the iterator was positioned before the first 
element in the hash. If the hash is empty, the iterator will be positioned after the end of the hash. 

If the iterator is not associated with a hash or the iterator position before the increment was past the last 
element the hash, the undef_ iter exception is thrown, if enabled. 

The operator ++ public member function returns a non-zero value if the iterator is positioned on a 
hash item. Zero(O) is returned when the iterator is incremented past the end of the hash. 

current, operator (), reset,WCIterExcept: :undef_ iter 
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WCValHashSetlter<Type>::reset(), WCValHashTablelter<Type>::reset() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchiter.h> 

public: 

void reset(); 

The reset public member function resets the iterator to the initial state, positioning the iterator before 
the first element in the associated hash. 

The iterator is positioned before the first hash element. 

WCValHashSetlter, WCValHashTablelter, container 
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WCValHashSetlter<Type>::reset(), WCValHashTablelter<Type>::reset() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wchiter.h> 
public: 

void WCValHashSetIter<Type>::reset( WCValHashSet<Type> & ); 
void WCValHashTableIter<Type>::reset( WCValHashTable<Type> & ); 

The reset public member function resets the iterator to operate on the specified hash. The iterator is 
positioned before the first element in the hash. 

The iterator is positioned before the first element of the specified hash. 

WCValHashSetlter, WCValHashTablelter, container 
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WCValHashSetlter<Type>::reset(), WCValHashTablelter<Type>::reset() 
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12 List Containers 


List containers are single or double linked lists. The choice of which type of list to use is determined by the 
direction in which the list is traversed and by what is stored in the list. A list to which items are just added 
and removed may be most efficiently implemented as a single linked list. If frequent retrievals of items at 
given indexes within the list are made, double linked lists can offer some improved search performance. 

There are three sets of list container classes: value, pointer and intrusive. 

Value lists are the simplest to use but have the most requirements on the type stored in the lists. Copies are 
made of the values stored in the list, which could be undesirable if the stored objects are complicated and 
copying is expensive. Value lists should not be used to store objects of a base class if any derived types of 
different sizes would be stored in the list, or if the destructor for the derived class must be called. The 
WCValSList<Type> container class implements single linked value lists, and the 
WCValDList<Type> class double linked value lists. 

Pointer list elements store pointers to objects. No creating, copying or destroying of objects stored in the 
list occurs. The only requirement of the type pointed to is that an equivalence operator is provided so that 
lookups can be performed. The WCPtrSList<Type> class implements single linked pointer lists, and 
the WCPtrDList<Type> class double linked pointer lists. 

Intrusive lists require that the list elements are objects derived from the WCSLink or WCDLink class, 
depending on whether a single or double linked list is used. The list classes require nothing else from the 
list elements. No creating, destroying or copying of any object is performed by the intrusive list classes, 
and must be done by the user of the class. One advantage of an intrusive list is a list element can be 
removed from one list and inserted into another list without creating new list element objects or deleting 
old objects. The WCIsvSList<Type> class implements single linked intrusive lists, and the 
WCIsvDList<Type> class double linked intrusive lists. 

A list may be traversed using the corresponding list iterator class. Iterators allow lists to be stepped 
through one or more elements at a time. The iterator classes which correspond to single linked list 
containers have some functionality inhibited. If backward traversal is required, the double linked 
containers and iterators must be used. 

The classes are presented in alphabetical order. The WCSLink and WCDLink class provide a common 
control interface for the list elements for the intrusive classes. 

Since the container classes are all template classes, deriving most of the functionality from common base 
classes was used. In the listing of class member functions, those public member functions which appear to 
be in the container class but are actually defined in the common base class are identified as if they were 
explicitly specified in the container class. 
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WCDLink 


Declared: wclcom.h 

Derived from: WCSLink 

The WCDLink class is the building block for all of the double linked list classes. It is implemented in 
terms of the WCSLink base class. Since no user data is stored directly with it, the WCDLink class 
should only be used as a base class to derive a user defined class. 

When creating a double linked intrusive list, the WCDLink class is used to derive the user defined class 
that holds the data to be inserted into the list. 

The wclcom. h header file is included by the wclist. h header file. There is no need to explicitly 
include the wclcom. h header file unless the wclist. h header file is not included. No errors will 
result if it is included. 

Note that the destructor is non-virtual so that list elements are of minimum size. Objects created as a 
class derived from the WCDLink class, but destroyed while typed as a WCDLink object will not invoke 
the destructor of the derived class. 

Public Member Functions 

The following public member functions are declared: 

WCDLink (); 

-WCDLink (); 

See Also: WCSLink 
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WCDLink:: WCDLinkf) 


Synopsis: #include <wclist.h> 

public: 

WCDLink(); 


Semantics: 

Results: 
See Also: 


The public WCDLink constructor creates an WCDLink object. The public WCDLink constructor is 
used implicitly by the compiler when it generates a constructor for a derived class. 

The public WCDLink constructor produces an initialized WCDLink object. 

-WCDLink 
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WCDLink::- WCDLinkQ 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wclist.h> 
public: 

-WCDLink() ; 

The public -WCDLink destructor does not do anything explicit. The call to the public -WCDLink 
destructor is inserted implicitly by the compiler at the point where the object derived from WCDLink 
goes out of scope. 

The object derived from WCDLink is destroyed. 

WCDLink 


232 List Containers 




WCIsvSList<Type>, WCIsvDList<Type> 


Declared: 


wclist.h 

The WCIsvSList<Type> and WCIsvDList<Type> classes are the templated classes used to 
create objects which are single or double linked lists. The created list is intrusive, which means that list 
elements which are inserted must be created with a library supplied base class. The class WCSLink 
provides the base class definition for single linked lists, and should be inherited by the definition of any 
list item for single linked lists. It provides the linkage that is used to traverse the list elements. 

Similarly, the class WCDLink provides the base class definition for double lists, and should be inherited 
by the definition of any list item for double lists. 

In the description of each member function, the text Type is used to indicate the type value specified as 
the template parameter. Type is the type of the list elements, derived from WCSLink or WCDLink. 

The WCExcept class is a base class of the WCIsvSList<Type> and WCIsvDList<Type> classes 
and provides the exceptions member function. This member function controls the exceptions which 
can be thrown by the WCIsvSList<Type> and WCIsvDList<Type> objects. No exceptions are 
enabled unless they are set by the exceptions member function. 

Requirements of Type 

The WCIsvSList<Type> class requires only that Type is derived from WCSLink . The 
WCIsvDList<Type> class requires only that Type is derived from WCDLink. 

Private Member Functions 

In an intrusive list, copying a list is undefined. Setting the copy constructor and assignment operator as 
private is the standard mechanism to ensure a copy cannot be made. The following member functions 
are declared private: 

void WCIsvSList( const WCIsvSList & ); 
void WCIsvDList( const WCIsvDList & ); 

WCIsvSList & WCIsvSList::operator =( const WCIsvSList & ); 

WCIsvDList & WCIsvDList::operator =( const WCIsvDList & ); 

Public Member Functions 

The following member functions are declared in the public interface: 

WCIsvSList (); 

-WCIsvSList (); 

WCIsvDList () ; 

-WCIsvDList () ; 

int append( Type * ); 

void clear (); 

void clearAndDestroy (); 

int contains! const Type * ) const; 

int entries!) const; 

Type * find! int = 0 ) const; 

Type * findLast!) const; 

void forAll( void (*)( Type *, void * ), void *); 

Type * get( int = 0 ) ; 

int index! const Type * ) const; 

int index! int (*)( const Type *, void * ), void * ) const; 
int insert( Type * ); 
int isEmpty!) const; 


List Containers 233 




WCIsvSList<Type>, WCIsvDList<Type> 


Public Member Operators 

The following member operators are declared in the public interface: 

int WCIsvSList::operator ==( const WCIsvSList & 
int WCIsvDList::operator ==( const WCIsvDList & 

Sample Program Using an Intrusive List 


#include <wclist.h> 

#include <iostream.h> 

class int_ ddata : public WCDLink { 
public: 

inline int_ ddata() {}; 

inline int_ ddata() {}; 

inline int_ ddata( int datum ) : info( datum ) {}; 

int info; 

}; 


static void testl( void ); 

void data_ isv_ prt ( int_ ddata * data, void * str ) { 

cout « (char *)str « "[" « data->info « "]\n"; 

} 

void main() { 

try { 

testl (); 

} catch (...) { 

cout << "we caught an unexpected exception\n"; 

} 

cout.flush (); 

} 


void testl ( void ) { 

WCIsvDList<int_ ddata> 

int_ ddata 

int_ ddata 

int_ ddata 

int_ ddata 

int_ ddata 


list; 
datal (1) ; 
data2 (2) ; 
data3 (3) ; 
data4 (4) ; 
data5 (5) ; 


list.exceptions ( WCExcept::check_ all ); 
list.append ( Sdata2 ); 
list.append( Sdata3 ); 
list.append ( Sdata4 ); 

list.insert( Sdatal ); 
list.append( &data5 ); 

cout << "kintrusive double list for int_ ddata>\n"; 
list.forAll( data_ isv_ prt, "" ); 

data_ isv_ prt( list.find( 3 ), "<the fourth element>" ) 
data_ isv_ prt( list.get( 2 ), "<the third element>" ); 
data_ isv_ prt( list.getO, "<the first element>" ); 
list.clear (); 
cout.flush (); 


) const; 
) const; 
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WCIsvSList<Type>::WCIsvSList() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <wclist.h> 
public: 

WCIsvSList(); 

The WCIsvSList public member function creates an empty WCIsvSList object. 

The WCIsvSList public member function produces an initialized WCIsvSList object. 
-WCIsvSList 
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WCIsvSList<Type>::WCIsvSList() 


Synopsis: #include <wclist.h> 

private: 

void WCIsvSList( const WCIsvSList & ); 


Semantics: The WCIsvSList private member function is the copy constructor for the single linked list class. 

Making a copy of the list object would result in a error condition, since intrusive lists cannot share data 
items with other lists. 
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WCIsvSList<Type>::~WCIsvSList() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wclist.h> 
public: 

-WCIsvSList(); 

The -WCIsvSList public member function destroys the WCIsvSList object. If the list is not 
empty and the not_ empty exception is enabled, the exception is thrown. If thenot_ empty 
exception is not enabled and the list is not empty, the list is cleared using the clear member function. 
The call to the -WCIsvSList public member function is inserted implicitly by the compiler at the 
point where the WCIsvSList object goes out of scope. 

The WCIsvSList object is destroyed. 

WCIsvSList, clear, clearAndDestroy, WCExcept::not_ empty 
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WCIsvDList<Type>::WCIsvDList() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <wclist.h> 
public: 

WCIsvDList(); 

The WCIsvDList public member function creates an empty WCIsvDList object. 

The WCIsvDList public member function produces an initialized WCIsvDList object. 
-WCIsvDList 
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WCIsvDList<Type>::WCIsvDList() 


Synopsis: #include <wclist.h> 

private: 

WCIsvDList( const WCIsvDList & ); 


Semantics: The WCIsvDList private member function is the copy constructor for the double linked list class. 

Making a copy of the list object would result in a error condition, since intrusive lists cannot share data 
items with other lists. 
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WCIsvDList<Type>::~WCIsvDList() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclist.h> 
public: 

-WCIsvDList(); 

The -WCIsvDList public member function destroys the WCIsvDList object. If the list is not 
empty and the not_ empty exception is enabled, the exception is thrown. If thenot_ empty 
exception is not enabled and the list is not empty, the list is cleared using the clear member function. 
The call to the -WCIsvDList public member function is inserted implicitly by the compiler at the 
point where the WCIsvDList object goes out of scope. 

The WCIsvDList object is destroyed. 

WCIsvDList, clear, clearAndDestroy, WCExcept::not_ empty 
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WCIsvSList<Type>::append(), WCIsvDList<Type>::append() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wclist.h> 
public: 

int append( Type * ) ; 

The append public member function is used to append the list element object to the end of the list. 
The address of (a pointer to) the list element object should be passed, not the value. Since the linkage 
information is stored in the list element, it is not possible for the element to be in more than one list, or 
in the same list more than once. 

The passed list element should be constructed using the appropriate link class as a base. WCSLink 
must be used as a list element base class for single linked lists, and WCDLink must be used as a list 
element base class for double linked lists. 

The list element is appended to the end of the list and a TRUE value (non-zero) is returned, 
insert 
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WCIsvSList<Type>::clear(), WCIsvDList<Type>::clear() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 

public: 

void clear (); 

The clear public member function is used to clear the list object and set it to the state of the object 
just after the initial construction. The list object is not destroyed and re-created by this operator, so the 
object destructor is not invoked. The list elements are not cleared. Any list items still in the list are lost 
unless pointed to by some pointer object in the program code. 

If any of the list elements are not allocated with new (local variable or global list elements), then the 
clear public member function must be used. When all list elements are allocated with new, the 
clearAndDestory member function should be used. 

The clear public member function resets the list object to the state of the object immediately after the 
initial construction. 

~WCIsvSList, ~WCIsvDList, clearAndDestroy, get, operator = 
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WCIsvSList<Type>,WCIsvDList<Type>::clearAndDestroy() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

void clearAndDestroy(); 

The clearAndDestroy public member function is used to clear the list object and set it to the state 
of the object just after the initial construction. The list object is not destroyed and re-created by this 
operator, so the object destructor is not invoked. The link elements are deleted before the list is 
re-initialized. 

If any elements in the list were not allocated by the new operator, the clearAndDestroy public 
member function must not be called. The clearAndDestroy public member function destroys each 
list element with the destructor for Type even if the list element was created as an object derived from 
Type, unless Type has a pure virtual destructor. 

The clearAndDestroy public member function resets the list object to the initial state of the object 
immediately after the initial construction and deletes the list elements. 

clear, get 
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WCIsvSList<Type>::contains(), WCIsvDList<Type>::contains() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

int contains ( const Type * ) const; 

The contains public member function is used to determine if a list element object is already 
contained in the list. The address of (a pointer to) the list element object should be passed, not the 
value. Each list element is compared to the passed element object to determine if it has the same 
address. Note that the comparison is of the addresses of the elements, not the contained values. 

Zero(O) is returned if the passed list element object is not found in the list. A non-zero result is returned 
if the element is found in the list. 

find, index 
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WCIsvSList<Type>::entries(), WCIsvDList<Type>::entries() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclist.h> 
public: 

int entries() const; 

The entries public member function is used to determine the number of list elements contained in 
the list object. 

The number of entries stored in the list is returned, zero(O) is returned if there are no list elements, 
isEmpty 
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WCIsvSList<Type>::find(), WCIsvDList<Type>::find() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

Type * find( int = 0 ) const; 

The find public member function returns a pointer to a list element in the list object. The list element 
is not removed from the list, so care must be taken not to delete the element returned to you. The 
optional parameter specifies which element to locate, and defaults to the first element. Since the first 
element of the list is the zero’th element, the last element will be the number of list entries minus one. 

If the list is empty and the empty_ container exception is enabled, the exception is thrown. If the 
index_ range exception is enabled, the exception is thrown if the index value is negative or is greater 
than the number of list entries minus one. 

A pointer to the selected list element or the closest list element is returned. If the index value is 
negative, the closest list element is the first element. The last element is the closest element if the index 
value is greater than the number of list entries minus one. A value of NULL(O) is returned if there are 
no elements in the list. 

findLast, get, index, isEmpty, WCExcept::empty_ container, 

WCExcept: :index_ range 
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WCIsvSList<Type>::findLast(), WCIsvDList<Type>::findLast() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

Type * findLastO const; 

The f indLast public member function returns a pointer to the last list element in the list object. The 
list element is not removed from the list, so care must be taken not to delete the element returned to you. 

If the list is empty, one of two exceptions can be thrown. If the empty_ container exception is 
enabled, it is thrown. The index_ range exception is thrown if it is enabled and the 
empty_ container exception is not enabled. 

A pointer to the last list element is returned. A value of NULL(O) is returned if there are no elements in 
the list. 

find, get, isEmpty, WCExcept: :empty_ container,WCExcept: :index_ range 
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WCIsvSList<Type>::forAII(), WCIsvDList<Type>::forAII() 


Synopsis: 


Semantics: 


See Also: 


#include <wclist.h> 
public: 

void forAll( void (*fn)( Type *, void * ), void *); 

The forAll public member function is used to cause the function^ to be invoked for each list 
element. The fn function should have the prototype 

void (*fn)( Type *, void * ) 

The first parameter of fn shall accept a pointer to the list element currently active. The second argument 
passed to fn is the second argument of the forAll function. This allows a callback function to be 
defined which can accept data appropriate for the point at which the forAll function is invoked. 

WCIsvConstSListlter, WCIsvConstDListlter, WCIsvSListlter, WCIsvDListlter 
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WCIsvSList<Type>::get(), WCIsvDList<Type>::get() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

Type * get( int = 0 ); 

The get public member function returns a pointer to a list element in the list object. The list element is 
also removed from the list. The optional parameter specifies which element to remove, and defaults to 
the first element. Since the first element of the list is the zero'th element, the last element will be the 
number of list entries minus one. 

If the list is empty and the empty_ container exception is enabled, the exception is thrown. If the 
index_ range exception trap is enabled, the exception is thrown if the index value is negative or is 
greater than the number of list entries minus one. 

A pointer to the selected list element or the closest list element is removed and returned. If the index 
value is negative, the closest list element is the first element. The last element is the closest element if 
the index value is greater than the number of list entries minus one. A value of NULL(O) is returned if 
there are no elements in the list. 

clear, clearAndDestroy, find, index, WCExcept: :empty_ container, 

WCExcept::index_ range 
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WCIsvSList<Type>::index(), WCIsvDList<Type>::index() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

int index( const Type * ) const; 

The index public member function is used to determine the index of the first list element equivalent to 
the passed element. The address of (a pointer to) the list element object should be passed, not the value. 
Each list element is compared to the passed element object to determine if it has the same address. Note 
that the comparison is of the addresses of the elements, not the contained values. 

The index of the first element equivalent to the passed element is returned. If the passed element is not 
in the list, negative one (-1) is returned. 

contains, find, get 
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WCIsvSList<Type>::index(), WCIsvDList<Type>::index() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclist.h> 
public: 

int index( int (*test_ fn) ( const Type *, void * ), 
void * ) const; 

The index public member function is used to determine the index of the first list element for which the 
supplied testjn function returns true. The testjn function must have the prototype: 

int (*test_ fn) ( const Type *, void * ); 

Each list element is passed in turn to the testjn function as the first argument. The second parameter 
passed is the second argument of the index function. This allows the testjn callback function to 
accept data appropriate for the point at which the index function is invoked. The supplied testjn 
shall return a TRUE (non-zero) value when the index of the passed element is desired. Otherwise, a 
FALSE (zero) value shall be returned. 

The index of the first list element for which the testjn function returns non-zero is returned. If the 
testjn function returns zero for all list elements, negative one (-1) is returned. 

contains, find, get 
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WCIsvSList<Type>::insert(), WCIsvDList<Type>::insert() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wclist.h> 
public: 

int insert( Type * ) ; 

The insert public member function is used to insert the list element object to the beginning of the 
list. The address of (a pointer to) the list element object should be passed, not the value. Since the 
linkage information is stored in the list element, it is not possible for the element to be in more than one 
list, or in the same list more than once. 

The passed list element should be constructed using the appropriate link class as a base. WCSLink 
must be used as a list element base class for single linked lists, and WCDLink must be used as a list 
element base class for double linked lists. 

The list element is inserted as the first element of the list and a TRUE value (non-zero) is returned, 
append 
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WCIsvSList<Type>::isEmpty(), WCIsvDList<Type>::isEmpty() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

int isEmptyO const; 

The isEmpty public member function is used to determine if a list object has any list elements 
contained in it. 

A TRUE value (non-zero) is returned if the list object does not have any list elements contained within 
it. A FALSE (zero) result is returned if the list contains at least one element. 

entries 
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WCIsvSList<Type>::operator =(), WCIsvDList<Type>::operator =() 


Synopsis: #include <wclist.h> 

private: 

WCIsvSList & WCIsvSList::operator =( const WCIsvSList & ); 

WCIsvDList & WCIsvDList::operator =( const WCIsvDList & ); 

Semantics: The operator = private member function is the assignment operator for the class. Since making a 

copy of the list object would result in a error condition, it is made inaccessible by making it a private 
operator. 
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WCIsvSList<Type>::operator ==(), WCIsvDList<Type>::operator ==() 


Synopsis: 


Semantics: 


Results: 


#include <wclist.h> 
public: 

int WCIsvSList::operator ==( const WCIsvSList & ) const; 
int WCIsvDList::operator ==( const WCIsvDList & ) const; 

The operator == public member function is the equivalence operator for the 

WCIsvSList<Type> and WCIsvDList<Type> classes. Two list objects are equivalent if they are 
the same object and share the same address. 

A TRUE (non-zero) value is returned if the left hand side object and the right hand side objects are the 
same object. A FALSE (zero) value is returned otherwise. 
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WCPtrSList<Type>, WCPtrDList<Type> 


Declared: 


wclist.h 

The WCPtrSList<Type> and WCPtrDList<Type> classes are the templated classes used to 
create objects which are single or double linked lists. 

In the description of each member function, the text Type is used to indicate the type value specified as 
the template parameter. The pointers stored in the list point to values of type Type . 

The WCExcept class is a base class of the WCPtrSList<Type> and WCPtrDList<Type> classes 
and provides the exceptions member function. This member function controls the exceptions which 
can be thrown by the WCPtrSList<Type> and WCPtrDList<Type> objects. No exceptions are 
enabled unless they are set by the exceptions member function. 

Requirements of Type 

The WCPtrSList<Type> and WCPtrDList<Type> classes requires Type to have: 

(1) an equivalence operator with constant parameters 

Type::operator ==( const Type & ) const 

Public Member Functions 

The following member functions are declared in the public interface: 

WCPtrSList (); 

WCPtrSList( void * (*) ( size_t ), void (*) ( void *, size_t )); 

WCPtrSList( const WCPtrSList & ); 

-WCPtrSList(); 

WCPtrDList(); 

WCPtrDList( void * (*)( size_t ), void (*)( void *, size_t )); 

WCPtrDList( const WCPtrDList & ); 

-WCPtrDList(); 

int append( Type * ); 

void clear (); 

void clearAndDestroy (); 

int contains! const Type * ) const; 

int entries!) const; 

Type * find! int = 0 ) const; 

Type * findLast!) const; 

void forAll( void (*)( Type *, void * ), void *) const; 

Type * get( int = 0 ); 
int index! const Type * ) const; 
int insert( Type * ); 
int isEmpty!) const; 

Public Member Operators 

The following member operators are declared in the public interface: 

WCPtrSList & WCPtrSList::operator =( const WCPtrSList & ); 

WCPtrDList & WCPtrDList::operator =( const WCPtrDList & ); 
int WCPtrSList::operator ==( const WCPtrSList & ) const; 
int WCPtrDList::operator ==( const WCPtrDList & ) const; 

Sample Program Using a Pointer List 
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WCPtrSList<Type>, WCPtrDList<Type> 


#include <wclist.h> 

#include <iostream.h> 

static void testl( void ) ; 

void data_ ptr_ prt ( int * data, void * str ) { 

cout « (char *)str « "[" « *data « "]\n"; 

} 

void main() { 

try { 

testl (); 

} catch ( ... ) { 

cout << "we caught an unexpected exception\n"; 

} 

cout.flush (); 

} 

void testl ( void ) { 

WCPtrDList<int> 
int 
int 
int 
int 
int 

list.append( &data2 ); 
list.append( &data3 ); 
list.append( &data4 ); 

list.insert( &datal ); 
list.append( &data5 ); 

cout << "<pointer double list for int>\n"; 
list.forAll( data_ ptr_ prt , "" ); 

data_ ptr_ prt( list.find( 3 ), "<the fourth element>" ); 
data_ ptr_ prt( list.get( 2 ), "<the third element>" ); 
data_ ptr_ prt ( list.getO, "<the first element>" ); 
list.clear (); 
cout.flush(); 

} 


list; 
datal (1); 
data2 (2); 
data3 (3); 
data4 (4); 
data5 (5); 
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WCPtrSList<Type>::WCPtrSList() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <wclist.h> 
public: 

WCPtrSList(); 

The WCPtrSList public member function creates an empty WCPtrSList object. 

The WCPtrSList public member function produces an initialized WCPtrSList object. 
WCPtrSList, ~WCPtrSList 
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WCPtrSList<Type>::WCPtrSList() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

WCPtrSList( void * (*allocator)( size_ t ), 
void (*deallocator)( void *, size_t ) ); 

The WCPtrSList public member function creates an empty WCPtrSList<Type> object. The 
allocator function is registered to perform all memory allocations of the list elements, and the 
deallocator function to perform all freeing of the list elements’ memory. These functions provide the 
ability to control how the allocation and freeing of memory is performed, allowing for more efficient 
memory handling than the general purpose global operator new () and operator deleted 
can provide. Memory management optimizations may potentially be made through the allocator and 
deallocator functions, but are not recommended before managing memory is understood and 
determined to be worth while. 

The allocator function shall return a pointer to allocated memory of size at least the argument, or 
zero(O) if the allocation cannot be performed. Initialization of the memory returned is performed by the 
WCPtrSList<Type> class. 

The WCPtrSList<Type> class calls the deallocator function only on memory allocated by the 
allocator function. The deallocator shall free the memory pointed to by the first argument which is of 
size the second argument. The size passed to the deallocator function is guaranteed to be the same size 
passed to the allocator function when the memory was allocated. 

The allocator and deallocator functions may assume that for a list object instance, the allocator is 
always called with the same first argument (the size of the memory to be allocated). The 
WCValSListltemSize (Type) macro returns the size of the elements which are allocated by the 
allocator function. 

The WCPtrSList public member function creates an initialized WCPtrSList<Type> object and 
registers the allocator and deallocator functions. 

WCPtrSList, ~WCPtrSList 
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WCPtrSList<Type>::WCPtrSList() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wclist.h> 
public: 

void WCPtrSList ( const WCPtrSList & ); 

The WCPtrSList public member function is the copy constructor for the single linked list class. All 
of the list elements are copied to the new list, as well as the exception trap states, and any registered 
allocator and deallocator functions. 

If all of the elements cannot be copied and the out_ of_ memory is enabled in the list being copied, 
the exception is thrown. The new list is created in a valid state, even if all of the list elements could not 
be copied. 

The WCPtrSList public member function produces a copy of the list. 

WCPtrSList, ~WCPtrSList, clear, WCExcept: : out_ of_ memory 
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WCPtrSList<Type>::~WCPtrSList() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclist.h> 
public: 

-WCPtrSList(); 

The -WCPtrSList public member function destroys the WCPtrSList object. If the list is not 
empty and the not_ empty exception is enabled, the exception is thrown. If thenot_ empty 
exception is not enabled and the list is not empty, the list is cleared using the clear member function. 
The call to the -WCPtrSList public member function is inserted implicitly by the compiler at the 
point where the WCPtrSList object goes out of scope. 

The WCPtrSList object is destroyed. 

WCPtrSList, clear, clearAndDestroy, WCExcept::not_ empty 
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WCPtrDList<Type>::WCPtrDList() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <wclist.h> 
public: 

WCPtrDList(); 

The WCPtrDList public member function creates an empty WCPtrDList object. 

The WCPtrDList public member function produces an initialized WCPtrDList object. 
WCPtrDList, ~WCPtrDList 
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WCPtrDList<Type>::WCPtrDList() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

WCPtrDList( void *(*allocator)( size_ t ), 
void (*deallocator)( void *, size_t ) ); 

The WCPtrDList public member function creates an empty WCPtrDList<Type> object. The 
allocator function is registered to perform all memory allocations of the list elements, and the 
deallocator function to perform all freeing of the list elements’ memory. These functions provide the 
ability to control how the allocation and freeing of memory is performed, allowing for more efficient 
memory handling than the general purpose global operator new () and operator deleted 
can provide. Memory management optimizations may potentially be made through the allocator and 
deallocator functions, but are not recommended before managing memory is understood and 
determined to be worth while. 

The allocator function shall return a pointer to allocated memory of size at least the argument, or 
zero(O) if the allocation cannot be performed. Initialization of the memory returned is performed by the 
WCPtrDList<Type> class. 

The WCPtrDList<Type> class calls the deallocator function only on memory allocated by the 
allocator function. The deallocator shall free the memory pointed to by the first argument which is of 
size the second argument. The size passed to the deallocator function is guaranteed to be the same size 
passed to the allocator function when the memory was allocated. 

The allocator and deallocator functions may assume that for a list object instance, the allocator is 
always called with the same first argument (the size of the memory to be allocated). The 
WCValDListltemSize (Type) macro returns the size of the elements which are allocated by the 
allocator function. 

The WCPtrDList public member function creates an initialized WCPtrDList<Type> object and 
registers the allocator and deallocator functions. 

WCPtrDList, ~WCPtrDList 
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WCPtrDList<Type>::WCPtrDList() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <wclist.h> 
public: 

WCPtrDList ( const WCPtrDList & ); 

The WCPtrDList public member function is the copy constructor for the double linked list class. All 
of the list elements are copied to the new list, as well as the exception trap states, and any registered 
allocator and deallocator functions. 

If all of the elements cannot be copied and the out_ of_ memory is enabled in the list being copied, 
the exception is thrown. The new list is created in a valid state, even if all of the list elements could not 
be copied. 

The WCPtrDList public member function produces a copy of the list. 

WCPtrDList, ~WCPtrDList, clear, WCExcept: : out_ of_ memory 
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WCPtrDList<Type>::~WCPtrDList() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclist.h> 
public: 

-WCPtrDList(); 

The -WCPtrDList public member function destroys the WCPtrDList object. If the list is not 
empty and the not_ empty exception is enabled, the exception is thrown. If thenot_ empty 
exception is not enabled and the list is not empty, the list is cleared using the clear member function. 
The call to the -WCPtrDList public member function is inserted implicitly by the compiler at the 
point where the WCPtrDList object goes out of scope. 

The WCPtrDList object is destroyed. 

WCPtrDList, clear, clearAndDestroy, WCExcept::not_ empty 
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WCPtrSList<Type>::append(), WCPtrDList<Type>::append() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

int append( Type * ) ; 

The append public member function is used to append the data to the end of the list. 

If the out_ of_ memory exception is enabled and the append fails, the exception is thrown. 

The data element is appended to the end of the list. A TRUE value (non-zero) is returned if the append 
is successful. A FALSE (zero) result is returned if the append fails. 

insert, WCExcept: : out_ of_ memory 
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WCPtrSList<Type>::clear(), WCPtrDList<Type>::clear() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 

public: 

void clear (); 

The clear public member function is used to clear the list object and set it to the state of the object 
just after the initial construction. The list object is not destroyed and re-created by this operator, so the 
object destructor is not invoked. 

The clear public member function resets the list object to the state of the object immediately after the 
initial construction. 

~WCPtrSList, ~WCPtrDList, clearAndDestroy, get, operator = 
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WCPtrSList<Type>,WCPtrDList<Type>::clearAndDestroy() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

void clearAndDestroy(); 

The clearAndDestroy public member function is used to clear the list object and set it to the state 
of the object just after the initial construction. The list object is not destroyed and re-created by this 
operator, so the object destructor is not invoked. Before the list object is re-initialized, the the values 
pointed to by the list elements are deleted. 

The clearAndDestroy public member function resets the list object to the initial state of the object 
immediately after the initial construction and deletes the list elements. 

clear, get 
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WCPtrSList<Type>::contains(), WCPtrDList<Type>::contains() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

int contains ( const Type * ) const; 

The contains public member function is used to determine if a list element object is already 
contained in the list. Each list element is compared to the passed element using Type ' s operator 
== to determine if the passed element is contained in the list. Note that the comparison is of the objects 
pointed to. 

Zero(O) is returned if the passed list element object is not found in the list. A non-zero result is returned 
if the element is found in the list. 

find, index 
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WCPtrSList<Type>::entries(), WCPtrDList<Type>::entries() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclist.h> 
public: 

int entries() const; 

The entries public member function is used to determine the number of list elements contained in 
the list object. 

The number of entries stored in the list is returned, zero(O) is returned if there are no list elements, 
isEmpty 
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WCPtrSList<Type>::find(), WCPtrDList<Type>::find() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

Type * find( int = 0 ) const; 

The find public member function returns the value of a list element in the list object. The optional 
parameter specifies which element to locate, and defaults to the first element. Since the first element of 
the list is the zero'th element, the last element will be the number of list entries minus one. 

If the list is empty and the empty_ container exception is enabled, the exception is thrown. If the 
index_ range exception is enabled, the exception is thrown if the index value is negative or is greater 
than the number of list entries minus one. 

The value of the selected list element or the closest element is returned. If the index value is negative, 
the closest list element is the first element. The last element is the closest element if the index value is 
greater than the number of list entries minus one. An uninitialized pointer is returned if there are no 
elements in the list. 

findLast, get, index, isEmpty, WCExcept: :empty_ container, 

WCExcept::index_ range 
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WCPtrSList<Type>::findLast(), WCPtrDList<Type>::findLast() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

Type * findLastO const; 

The f indLast public member function returns the value of the last list element in the list object. 

If the list is empty, one of two exceptions can be thrown. If the empty_ container exception is 
enabled, it is thrown. The index_ range exception is thrown if it is enabled and the 
empty_ container exception is not enabled. 

The value of the last list element is returned. An uninitialized pointer is returned if there are no 
elements in the list. 

find, get, isEmpty, WCExcept: :empty_ container,WCExcept: :index_ range 
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WCPtrSList<Type>::forAII(), WCPtrDList<Type>::forAII() 


Synopsis: 


Semantics: 


See Also: 


#include <wclist.h> 
public: 

void forAll( void (*)( Type *, void * ), void *) const; 

The forAll public member function is used to cause the function^ to be invoked for each list 
element. The fn function should have the prototype 

void (*fn)( Type *, void * ) 

The first parameter of fn shall accept the value of the list element currently active. The second 
argument passed to fn is the second argument of the forAll function. This allows a callback function 
to be defined which can accept data appropriate for the point at which the forAll function is invoked. 

WCPtrConstSListlter, WCPtrConstDListlter, WCPtrSListlter, WCPtrDListlter 
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WCPtrSList<Type>::get(), WCPtrDList<Type>::get() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

Type * get( int = 0 ); 

The get public member function returns the value of the list element in the list object. The list element 
is also removed from the list. The optional parameter specifies which element to remove, and defaults 
to the first element. Since the first element of the list is the zero’th element, the last element will be the 
number of list entries minus one. 

If the list is empty and the empty_ container exception is enabled, the exception is thrown. If the 
index_ range exception trap is enabled, the exception is thrown if the index value is negative or is 
greater than the number of list entries minus one. 

The value of the selected list element or the closest element is removed and returned. If the index value 
is negative, the closest list element is the first element. The last element is the closest element if the 
index value is greater than the number of list entries minus one. An uninitialized pointer is returned if 
there are no elements in the list. 

clear, clearAndDestroy, find, index, WCExcept: :empty_ container, 

WCExcept::index_ range 
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WCPtrSList<Type>::index(), WCPtrDList<Type>::index() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclist.h> 
public: 

int index( const Type * ) const; 

The index public member function is used to determine the index of the first list element equivalent to 
the passed element. Each list element is compared to the passed element using Type's operator 
== until the passed element is found, or all list elements have been checked. Note that the comparison 
is of the objects pointed to. 

The index of the first element equivalent to the passed element is returned. If the passed element is not 
in the list, negative one (-1) is returned. 

contains, find, get 
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WCPtrSList<Type>::insert(), WCPtrDList<Type>::insert() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

int insert( Type * ) ; 

The insert public member function is used to insert the data as the first element of the list. 

If the out_ of_ memory exception is enabled and the insert fails, the exception is thrown. 

The data element is inserted into the beginning of the list. A TRUE value (non-zero) is returned if the 
insert is successful. A FALSE (zero) result is returned if the insert fails. 

append, WCExcept: : out_ of_ memory 
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WCPtrSList<Type>::isEmpty(), WCPtrDList<Type>::isEmpty() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

int isEmptyO const; 

The isEmpty public member function is used to determine if a list object has any list elements 
contained in it. 

A TRUE value (non-zero) is returned if the list object does not have any list elements contained within 
it. A FALSE (zero) result is returned if the list contains at least one element. 

entries 
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WCPtrSList<Type>::operator =(), WCPtrDList<Type>:-.operator =() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclist.h> 
public: 

WCPtrSList & WCPtrSList::operator =( const WCPtrSList & ); 

WCPtrDList & WCPtrDList::operator =( const WCPtrDList & ); 

The operator = public member function is the assignment operator for the class. The left hand side 
of the assignment is first cleared with the clear member function. All elements in the right hand side 
list are then copied, as well as the exception trap states, and any registered allocator and deallocator 
functions. 

If all of the elements cannot be copied and the out_ of_ memory is enabled in the right hand side list, 
the exception is thrown. The new list is created in a valid state, even if all of the list elements could not 
be copied. 

The operator = public member function assigns the right hand side to the left hand side and returns 
a reference to the left hand side. 

WCPtrSList, WCPtrDList, clear, WCExcept: : out_ of_ memory 


278 List Containers 




WCPtrSList<Type>:.-operator ==(), WCPtrDList<Type>:operator ==() 


Synopsis: 


Semantics: 


Results: 


#include <wclist.h> 
public: 

int WCPtrSList::operator ==( const WCPtrSList & ) const; 
int WCPtrDList::operator ==( const WCPtrDList & ) const; 

The operator == public member function is the equivalence operator for the 

WCPtrSList<Type> and WCPtrDList<Type> classes. Two list objects are equivalent if they are 
the same object and share the same address. 

A TRUE (non-zero) value is returned if the left hand side object and the right hand side objects are the 
same object. A FALSE (zero) value is returned otherwise. 
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WCSLink 


Declared: 
Derived by: 


See Also: 


wclcom.h 

WCDLink 

The WCSLink class is the building block for all of the list classes. It provides the link that is used to 
traverse the list elements. The double link classes use the WCSLink class to implement both links. 
Since no user data is stored directly with it, the WCSLink class should only be used as a base class to 
derive a user defined class. 

When creating a single linked intrusive list, the WCSLink class is used to derive the user defined class 
that holds the data to be inserted into the list. 

The wclcom. h header file is included by the wclist. h header file. There is no need to explicitly 
include the wclcom. h header file unless the wclist. h header file is not included. No errors will 
result if it is included unnecessarily. 

Note that the destructor is non-virtual so that list elements are of minimum size. Objects created as a 
class derived from the WCSLink class, but destroyed while typed as a WCSLink object will not invoke 
the destructor of the derived class. 

Public Member Functions 

The following public member functions are declared: 

WCSLink (); 

-WCSLink (); 

WCDLink 
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WCSLink:: WCSLinkQ 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wclcom.h> 
public: 

WCSLink(); 

The public WCSLink constructor creates an WCSLink object. The public WCSLink constructor is 
used implicitly by the compiler when it generates a constructor for a derived class. 

The public WCSLink constructor produces an initialized WCSLink object. 

-WCSLink 
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WCSLink::- WCSLinkQ 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wclcom.h> 
public: 

-WCSLink(); 

The public -WCSLink destructor does not do anything explicit. The call to the public -WCSLink 
destructor is inserted implicitly by the compiler at the point where the object derived from WCSLink 
goes out of scope. 

The object derived from WCSLink is destroyed. 

WCSLink 
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WCValSList<Type>, WCValDList<Type> 


Declared: 


wclist.h 

The WCValSList<Type> and WCValDList<Type> classes are the templated classes used to 
create objects which are single or double linked lists. Values are copied into the list, which could be 
undesirable if the stored objects are complicated and copying is expensive. Value lists should not be 
used to store objects of a base class if any derived types of different sizes would be stored in the list, or 
if the destructor for a derived class must be called. 

In the description of each member function, the text Type is used to indicate the type value specified as 
the template parameter. Type is the type of the values stored in the list. 

The WCExcept class is a base class of the WCValSList<Type> and WCValDList<Type> classes 
and provides the exceptions member function. This member function controls the exceptions which 
can be thrown by the WCValSList<Type> and WCValDList<Type> objects. No exceptions are 
enabled unless they are set by the exceptions member function. 

Requirements of Type 

The WCValSList<Type> and WCValDList<Type> classes requires Type to have: 

(1) a default constructor ( Type : : Type () ). 

(2) a well defined copy constructor ( Type :: Type ( const Type & ) ). 

(3) an equivalence operator with constant parameters 

Type::operator ==( const Type & ) const 

Public Member Functions 

The following member functions are declared in the public interface: 

WCValSList (); 

WCValSList( void * (*) ( size_ t ), void (*) ( void *, size_t )); 
WCValSList( const WCValSList & ); 

-WCValSList(); 

WCValDList() ; 

WCValDList( void * (*) ( size_t ), void (*) ( void *, size_t )); 
WCValDList( const WCValDList & ); 

-WCValDList(); 

int append( const Type & ); 

void clear(); 

void clearAndDestroy (); 

int contains! const Type & ) const; 

int entries!) const; 

Type find! int = 0 ) const; 

Type findLast!) const; 

void forAll( void (*)( Type, void * ), void *) const; 

Type get( int = 0 ); 
int index! const Type & ) const; 
int insert( const Type & ); 
int isEmpty!) const; 

Public Member Operators 

The following member operators are declared in the public interface: 
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WCValSList<Type>, WC ValDList<Type> 


WCValSList & WCValSList::operator =( const WCValSList & ); 
WCValDList & WCValDList::operator =( const WCValDList & ); 
int WCValSList::operator ==( const WCValSList & ) const; 
int WCValDList::operator ==( const WCValDList & ) const; 

Sample Program Using a Value List 


♦include <wclist.h> 

♦include <iostream.h> 

static void testl( void ) ; 

void data_ val_ prt( int data, void * str ) { 

cout « (char *)str « "[" « data « "]\n"; 

} 


void main() { 

try { 

testl () ; 

} catch ( ... ) { 

cout << "we caught an unexpected exception\n"; 

} 

cout.flush (); 

} 


void testl ( void ) { 

WCValDList<int> list; 

list.append( 2 ); 
list.append( 3 ); 
list.append( 4 ); 

list.insert ( 1 ); 
list.append( 5 ); 

cout << "<value double list for int>\n"; 
list.forAllf data_ val_ prt, "" ); 

data_ val_ prt( list.find( 3 ), "<the fourth element>" ); 
data_ val_ prt( list.get( 2 ), "<the third element>" ); 
data_ val_ prt( list.getO, "<the first element>" ); 
list.clear (); 
cout.flush(); 
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WCValSList<Type>::WCValSList() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <wclist.h> 
public: 

WCValSList() ; 

The WCValSList public member function creates an empty WCValSList object. 

The WCValSList public member function produces an initialized WCValSList object. 
WCValSList, -WCValSList 
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WCValSList<Type>::WCVaiSList() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclist.h> 
public: 

WCValSList( void * (*allocator) ( size_ t ), 
void (*deallocator)( void *, size_t ) ); 

The WCValSList public member function creates an empty WCValSList<Type> object. The 
allocator function is registered to perform all memory allocations of the list elements, and the 
deallocator function to perform all freeing of the list elements’ memory. These functions provide the 
ability to control how the allocation and freeing of memory is performed, allowing for more efficient 
memory handling than the general purpose global operator new () and operator deleted 
can provide. Memory management optimizations may potentially be made through the allocator and 
deallocator functions, but are not recommended before managing memory is understood and 
determined to be worth while. 

The allocator function shall return a pointer to allocated memory of size at least the argument, or 
zero(O) if the allocation cannot be performed. Initialization of the memory returned is performed by the 
WCValSList<Type> class. 

The WCValSList<Type> class calls the deallocator function only on memory allocated by the 
allocator function. The deallocator shall free the memory pointed to by the first argument which is of 
size the second argument. The size passed to the deallocator function is guaranteed to be the same size 
passed to the allocator function when the memory was allocated. 

The allocator and deallocator functions may assume that for a list object instance, the allocator is 
always called with the same first argument (the size of the memory to be allocated). The 
WCValSListltemSize (Type) macro returns the size of the elements which are allocated by the 
allocator function. 

The WCValSList public member function creates an initialized WCValSList<Type> object and 
registers the allocator and deallocator functions. 

WCValSList, -WCValSList 
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WCValSList<Type>::WCValSList() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wclist.h> 
public: 

void WCValSList( const WCValSList & ); 

The WCValSList public member function is the copy constructor for the single linked list class. All 
of the list elements are copied to the new list, as well as the exception trap states, and any registered 
allocator and deallocator functions. Type ' s copy constructor is invoked to copy the values contained 
by the list elements. 

If all of the elements cannot be copied and the out_ of_ memory is enabled in the list being copied, 
the exception is thrown. The new list is created in a valid state, even if all of the list elements could not 
be copied. 

The WCValSList public member function produces a copy of the list. 

WCValSList, ~WCValSList, clear, WCExcept: : out_ of_ memory 
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WCValSList<Type>::~ WCValSListQ 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclist.h> 
public: 

-WCValSList(); 

The -WCValSList public member function destroys the WCValSList object. If the list is not 
empty and the not_ empty exception is enabled, the exception is thrown. If thenot_ empty 
exception is not enabled and the list is not empty, the list is cleared using the clear member function. 
The call to the -WCValSList public member function is inserted implicitly by the compiler at the 
point where the WCValSList object goes out of scope. 

The WCValSList object is destroyed. 

WCValSList, clear, clearAndDestroy, WCExcept::not_ empty 
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WCValDList<Type>::WCValDList() 


Synopsis: 

Semantics: 
Results: 
See Also: 


♦include <wclist.h> 
public: 

WCValDList() ; 

The WCValDList public member function creates an empty WCValDList object. 

The WCValDList public member function produces an initialized WCValDList object. 
WCValDList, -WCValDList 
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WCValDList<Type>::WCValDList() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclist.h> 
public: 

WCValDList( void * (*allocator) ( size_ t ), 
void (*deallocator)( void *, size_t ) ); 

The WCValDList public member function creates an empty WCValDList<Type> object. The 
allocator function is registered to perform all memory allocations of the list elements, and the 
deallocator function to perform all freeing of the list elements’ memory. These functions provide the 
ability to control how the allocation and freeing of memory is performed, allowing for more efficient 
memory handling than the general purpose global operator new () and operator deleted 
can provide. Memory management optimizations may potentially be made through the allocator and 
deallocator functions, but are not recommended before managing memory is understood and 
determined to be worth while. 

The allocator function shall return a pointer to allocated memory of size at least the argument, or 
zero(O) if the allocation cannot be performed. Initialization of the memory returned is performed by the 
WCValDList<Type> class. 

The WCValDList<Type> class calls the deallocator function only on memory allocated by the 
allocator function. The deallocator shall free the memory pointed to by the first argument which is of 
size the second argument. The size passed to the deallocator function is guaranteed to be the same size 
passed to the allocator function when the memory was allocated. 

The allocator and deallocator functions may assume that for a list object instance, the allocator is 
always called with the same first argument (the size of the memory to be allocated). The 
WCValDListltemSize (Type) macro returns the size of the elements which are allocated by the 
allocator function. 

The WCValDList public member function creates an initialized WCValDList<Type> object and 
registers the allocator and deallocator functions. 

WCValDList, -WCValDList 
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WCValDList<Type>::WCValDList() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <wclist.h> 
public: 

WCValDList( const WCValDList & ); 

The WCValDList public member function is the copy constructor for the double linked list class. All 
of the list elements are copied to the new list, as well as the exception trap states, and any registered 
allocator and deallocator functions. Type ' s copy constructor is invoked to copy the values contained 
by the list elements. 

If all of the elements cannot be copied and the out_ of_ memory is enabled in the list being copied, 
the exception is thrown. The new list is created in a valid state, even if all of the list elements could not 
be copied. 

The WCValDList public member function produces a copy of the list. 

WCValDList, ~WCValDList, clear, WCExcept: : out_ of_ memory 
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WCValDList<Type>::~ WCValDListQ 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclist.h> 
public: 

-WCValDList(); 

The -WCValDList public member function destroys the WCValDList object. If the list is not 
empty and the not_ empty exception is enabled, the exception is thrown. If thenot_ empty 
exception is not enabled and the list is not empty, the list is cleared using the clear member function. 
The call to the -WCValDList public member function is inserted implicitly by the compiler at the 
point where the WCValDList object goes out of scope. 

The WCValDList object is destroyed. 

WCValDList, clear, clearAndDestroy, WCExcept::not_ empty 


292 List Containers 




WCValSList<Type>::append(), WCValDList<Type>::append() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclist.h> 
public: 

int append( const Type & ); 

The append public member function is used to append the data to the end of the list. The data stored 
in the list is a copy of the data passed as a parameter. 

If the out_ of_ memory exception is enabled and the append fails, the exception is thrown. 

The data element is appended to the end of the list. A TRUE value (non-zero) is returned if the append 
is successful. A FALSE (zero) result is returned if the append fails. 

insert, WCExcept: : out_ of_ memory 
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WCValSList<Type>::clear(), WCValDList<Type>::clear() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 

public: 

void clear (); 

The clear public member function is used to clear the list object and set it to the state of the object 
just after the initial construction. The list object is not destroyed and re-created by this operator, so the 
object destructor is not invoked. 

The clear public member function has the same sematics as the clearAndDestroy member 
function. 

The clear public member function resets the list object to the state of the object immediately after the 
initial construction. 

~WCValSList, ~WCValDList, clearAndDestroy, get, operator = 
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WCValSList<Type>,WCValDList<Type>::clearAndDestroy() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

void clearAndDestroy() ; 

The clearAndDestroy public member function is used to clear the list object and set it to the state 
of the object just after the initial construction. The list object is not destroyed and re-created by this 
operator, so the object destructor is not invoked. 

Before the list object is re-initialized, the delete operator is called for each list element. 

The clearAndDestroy public member function resets the list object to the initial state of the object 
immediately after the initial construction. 

clear, get 
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WCValSList<Type>::contains(), WCValDList<Type>::contains() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

int contains ( const Type & ) const; 

The contains public member function is used to determine if a list element object is already 
contained in the list. Each list element is compared to the passed element using Type ' s operator 
== to determine if the passed element is contained in the list. 

Zero(O) is returned if the passed list element object is not found in the list. A non-zero result is returned 
if the element is found in the list. 

find, index 
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WCValSList<Type>::entries(), WCValDList<Type>::entries() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclist.h> 
public: 

int entries() const; 

The entries public member function is used to determine the number of list elements contained in 
the list object. 

The number of entries stored in the list is returned, zero(O) is returned if there are no list elements, 
isEmpty 
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WCValSList<Type>::find(), WCValDList<Type>::find() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

Type find( int = 0 ) const; 

The find public member function returns the value of a list element in the list object. The optional 
parameter specifies which element to locate, and defaults to the first element. Since the first element of 
the list is the zero'th element, the last element will be the number of list entries minus one. 

If the list is empty and the empty_ container exception is enabled, the exception is thrown. If the 
index_ range exception is enabled, the exception is thrown if the index value is negative or is greater 
than the number of list entries minus one. 

The value of the selected list element or the closest element is returned. If the index value is negative, 
the closest list element is the first element. The last element is the closest element if the index value is 
greater than the number of list entries minus one. A default initialized value is returned if there are no 
elements in the list. 

findLast, get, index, isEmpty, WCExcept: :empty_ container, 

WCExcept::index_ range 
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WCValSList<Type>::findLast(), WCValDList<Type>::findLast() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

Type findLastO const; 

The f indLast public member function returns the value of the last list element in the list object. 

If the list is empty, one of two exceptions can be thrown. If the empty_ container exception is 
enabled, it is thrown. The index_ range exception is thrown if it is enabled and the 
empty_ container exception is not enabled. 

The value of the last list element is returned. A default initialized value is returned if there are no 
elements in the list. 

find, get, isEmpty, WCExcept: :empty_ container,WCExcept: :index_ range 
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WCValSList<Type>::forAII(), WCValDList<Type>::forAII() 


Synopsis: 


Semantics: 


See Also: 


#include <wclist.h> 
public: 

void forAll( void (*)( Type, void * ), void *) const; 

The forAll public member function is used to cause the function^ to be invoked for each list 
element. The fn function should have the prototype 

void (*fn)( Type, void * ) 

The first parameter of fn shall accept the value of the list element currently active. The second 
argument passed to fn is the second argument of the forAll function. This allows a callback function 
to be defined which can accept data appropriate for the point at which the forAll function is invoked. 

WCValConstSListlter, WCValConstDListlter, WCValSListlter, WCValDListlter 
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WCValSList<Type>::get(), WCValDList<Type>::get() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

Type get( int = 0 ) ; 

The get public member function returns the value of the list element in the list object. The list element 
is also removed from the list. The optional parameter specifies which element to remove, and defaults 
to the first element. Since the first element of the list is the zero’th element, the last element will be the 
number of list entries minus one. 

If the list is empty and the empty_ container exception is enabled, the exception is thrown. If the 
index_ range exception trap is enabled, the exception is thrown if the index value is negative or is 
greater than the number of list entries minus one. 

The value of the selected list element or the closest element is removed and returned. If the index value 
is negative, the closest list element is the first element. The last element is the closest element if the 
index value is greater than the number of list entries minus one. A default initialized value is returned if 
there are no elements in the list. 

clear, clearAndDestroy, find, index, WCExcept: :empty_ container, 

WCExcept::index_ range 
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WCValSList<Type>::index(), WCValDList<Type>::index() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

int index( const Type & ) const; 

The index public member function is used to determine the index of the first list element equivalent to 
the passed element. Each list element is compared to the passed element using Type's operator 
== until the passed element is found, or all list elements have been checked. 

The index of the first element equivalent to the passed element is returned. If the passed element is not 
in the list, negative one (-1) is returned. 

contains, find, get 
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WCValSList<Type>::insert(), WCValDList<Type>::insert() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclist.h> 
public: 

int insert( const Type & ) ; 

The insert public member function is used to insert the data as the first element of the list. The data 
stored in the list is a copy of the data passed as a parameter. 

If the out_ of_ memory exception is enabled and the insert fails, the exception is thrown. 

The data element is inserted into the beginning of the list. A TRUE value (non-zero) is returned if the 
insert is successful. A FALSE (zero) result is returned if the insert fails. 

append, WCExcept: : out_ of_ memory 
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WCValSList<Type>::isEmpty(), WCValDList<Type>::isEmpty() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclist.h> 
public: 

int isEmptyO const; 

The isEmpty public member function is used to determine if a list object has any list elements 
contained in it. 

A TRUE value (non-zero) is returned if the list object does not have any list elements contained within 
it. A FALSE (zero) result is returned if the list contains at least one element. 

entries 
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WCValSList<Type>::operator =(), WCValDList<Type>:operator =() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclist.h> 
public: 

WCValSList & WCValSList::operator =( const WCValSList & ); 

WCValDList & WCValDList::operator =( const WCValDList & ); 

The operator = public member function is the assignment operator for the class. The left hand side 
of the assignment is first cleared with the clear member function. All elements in the right hand side 
list are then copied, as well as the exception trap states, and any registered allocator and deallocator 
functions. Type's copy constructor is invoked to copy the values contained by the list elements. 

If all of the elements cannot be copied and the out_ of_ memory is enabled in the right hand side list, 
the exception is thrown. The new list is created in a valid state, even if all of the list elements could not 
be copied. 

The operator = public member function assigns the right hand side to the left hand side and returns 
a reference to the left hand side. 

WCValSList, WCValDList, clear, WCExcept: : out_ of_ memory 
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WCValSList<Type>::operator ==(), WCValDList<Type>:operator ==() 


Synopsis: 


Semantics: 


Results: 


#include <wclist.h> 
public: 

int WCValSList::operator ==( const WCValSList & ) const; 
int WCValDList::operator ==( const WCValDList & ) const; 

The operator == public member function is the equivalence operator for the 

WCValSList<Type> and WCValDList<Type> classes. Two list objects are equivalent if they are 
the same object and share the same address. 

A TRUE (non-zero) value is returned if the left hand side object and the right hand side objects are the 
same object. A FALSE (zero) value is returned otherwise. 


306 List Containers 




13 List iterators 


List iterators operate on single or double linked lists. They are used to step through a list one or more 
elements at a time. The choice of which type of iterator to use is determined by the list you wish to iterate 
over. For example, to iterate over a non-constant WCIsvDList<Type> object, use the 
WCIsvDListIter<Type> class. A constant WCValSList<Type> object can be iterated using the 
WCValConstSListIter<Type> class. The iterators which correspond to the single link list containers 
have some functionality inhibited. If backward traversal is required, the double linked containers and 
corresponding iterators must be used. 

Like all WATCOM iterators, newly constructed and reset iterators are positioned before the first element in 
the list. The list may be traversed one element at a time using the pre-increment or call operator. An 
increment operation causing the iterator to be positioned after the end of the list returns zero. Further 
increments will cause the undef_ iter exception to be thrown, if it is enabled. This behaviour allows 
lists to be traversed simply using a while loop, and is demonstrated in the examples for the iterator classes. 

The classes are presented in alphabetical order. The WCIterExcept class provides the common 
exception handling control interface for all of the iterators. 

Since the iterator classes are all template classes, deriving most of the functionality from common base 
classes was used. In the listing of class member functions, those public member functions which appear to 
be in the iterator class but are actually defined in the common base class are identified as if they were 
explicitly specified in the iterator class. 
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WCIsvConstSListlter<Type>, WCIsvConstDListlter<Type> 


Declared: 


See Also: 


wclistit.h 

The WCIsvConstSListIter<Type> and WCIsvConstDListIter<Type> classes are the 
templated classes used to create iterator objects for constant single and double linked list objects. These 
classes may be used to iterate over non-constant lists, but the WCIsvDListIter<Type> and 
WCIsvSListIter<Type> classes provide additional functionality for only non-constant lists. 

In the description of each member function, the text Type is used to indicate the list element type 
specified as the template parameter. 

The WCIterExcept class is a base class of the WCIsvConstSListIter<Type> and 
WCIsvConstDListIter<Type> classes and provides the exceptions member function. This 
member function controls the exceptions which can be thrown by the 

WCIsvConstSListIter<Type> and WCIsvConstDListIter<Type> objects. No exceptions 
are enabled unless they are set by the exceptions member function. 

Private Member Functions 

Some functionality supported by base classes of the iterator are not appropriate for the constant list 
iterator classes. Setting those functions as private members in the derived class is the standard 
mechanism to prevent them from being invoked. 

int append( Type * ); 
int insert ( Type * ); 

Public Member Functions 

The following member functions are declared in the public interface: 

WCIsvConstSListlter (); 

WCIsvConstSListlter ( const WCIsvSList<Type> & ); 

-WCIsvConstSListlter(); 

WCIsvConstDListlter() ; 

WCIsvConstDListlter( const WCIsvDList<Type> & ); 

-WCIsvConstDListlter() ; 

const WCIsvSList<Type> *WCIsvConstSListIter<Type>::container() const; 
const WCIsvDList<Type> *WCIsvConstDListIter<Type>::container() const; 
Type * current!) const; 
void reset(); 

void WCIsvConstSListIter<Type>::reset( const WCIsvSList<Type> & ); 
void WCIsvConstDListIter<Type>::reset( const WCIsvDList<Type> & ); 

Public Member Operators 

The following member operators are declared in the public interface: 

Type * operator () (); 

Type * operator ++(); 

Type * operator +=( int ); 

In the iterators for double linked lists only: 

Type * operator —(); 

Type * operator -=( int ) ; 

WCIsvSList::forAll, WCIsvDList: :forAll 
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WCIsvConstSListlter<Type>::WCIsvConstSListlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

WCIsvConstSListlter() ; 

The WCIsvConstSListlter public member function is the default constructor for the class and 
initializes the iterator with no list to operate on. The reset member function must be called to provide 
the iterator with a list to iterate over. 

The WCIsvConstSListlter public member function creates an initialized 
WCIsvConstSListlter object. 

WCIsvConstSListlter, ~WCIsvConstSListIter, reset 
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WCIsvConstSListlter<Type>::WCIsvConstSListlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

WCIsvConstSListlter( const WCIsvSList<Type> & ); 

The WCIsvConstSListlter public member function is a constructor for the class. The value 
passed as a parameter is a WCIsvSList list object. The iterator will be initialized for that list object 
and positioned before the first list element. To position the iterator to a valid element within the list, 
increment it using any of the operator ++, operator (), or operator += operators. 

The WCIsvConstSListlter public member function creates an initialized 
WCIsvConstSListlter object positioned before the first element in the list. 

~WCIsvConstSListIter, operator (), operator ++, operator +=, reset 
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WCIsvConstSListlter<Type>::~WCIsvConstSListlter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wclistit.h> 
public: 

-WCIsvConstSListlter() ; 

The -WCIsvConstSListlter public member function is the destructor for the class. The call to 
the -WCIsvConstSListlter public member function is inserted implicitly by the compiler at the 
point where the WCIsvConstSListlter object goes out of scope. 

The WCIsvConstSListlter object is destroyed. 

WCIsvConstSListlter 
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WCIsvConstDListlter<Type>::WCIsvConstDListlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

WCIsvConstDListlter() ; 

The WCIsvConstDListlter public member function is the default constructor for the class and 
initializes the iterator with no list to operate on. The reset member function must be called to provide 
the iterator with a list to iterate over. 

The WCIsvConstDListlter public member function creates an initialized 
WCIsvConstDListlter object. 

WCIsvConstDListlter, ~WCIsvConstDListIter, reset 
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WCIsvConstDListlter<Type>::WCIsvConstDListlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

WCIsvConstDListlter( const WCIsvDList<Type> & ); 

The WCIsvConstDListlter public member function is a constructor for the class. The value 
passed as a parameter is the WCIsvDList list object. The iterator will be initialized for that list object 
and positioned before the first list element. To position the iterator to a valid element within the list, 
increment it using any of the operator ++, operator (), or operator += operators. 

The WCIsvConstDListlter public member function creates an initialized 
WCIsvConstDListlter object positioned before the first list element. 

WCIsvConstDListlter, ~WCIsvConstDListIter, operator (),operator ++, 
operator +=, reset 
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WCIsvConstDListlter<Type>::~WCIsvConstDListlter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclistit.h> 
public: 

-WCIsvConstDListlter() ; 

The -WCIsvConstDListlter public member function is the destructor for the class. The call to 
the -WCIsvConstDListlter public member function is inserted implicitly by the compiler at the 
point where the WCIsvConstDListlter object goes out of scope. 

The WCIsvConstDListlter object is destroyed. 

WCIsvConstDListlter 
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WCIsvConstSListlter<Type>,WCIsvConstDListlter<Type>::container() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

const WCIsvSList<Type> *WCIsvConstSListIter<Type>::container() const; 
const WCIsvDList<Type> *WCIsvConstDListIter<Type>::container() const; 

The container public member function returns a pointer to the list container object. If the iterator 
has not been initialized with a list object, and the undef_ iter exception is enabled, the exception is 
thrown. 

A pointer to the list object associated with the iterator is returned, or NULL(O) if the iterator has not 
been initialized with a list. 

WCIsvConstSListlter, WCIsvConstDListlter, reset, WCIterExcept: :undef_ iter 
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WCIsvConstSListlter<Type>::current(), WCIsvConstDListlter<Type>::current() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

Type * current(); 

The current public member function returns a pointer to the list item at the current iterator position. 

If the iterator is not associated with a list, or the iterator position is either before the first element or past 
the last element in the list, the current iterator position is undefined. In this case the undef_ item 
exception is thrown, if enabled. 

A pointer to the current list element is returned. If the current element is undefined, NULL(O) is 
returned. 

operator (), operator ++, operator +=, operator —, operator -=, reset, 
WCIterExcept::undef_ item 
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WCIsvConstSListlter<Type>,WCIsvConstDListlter<Type>::operator ()() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

Type * operator () (); 

The operator () public member function is the call operator for the class. The list element which 
follows the current item is set to be the new current item. If the previous current item was the last 
element in the list, the iterator is positioned after the end of the list. 

The operator () public member function has the same semantics as the pre-increment operator, 
operator ++. 

If the iterator was positioned before the first element in the list, the current item will be set to the first 
element in the list. If the list is empty, the iterator will be positioned after the end of the list. 

If the iterator is not associated with a list or the iterator position before the increment was past the last 
element the list, the undef_ iter exception is thrown, if enabled. 

The operator () public member function returns a pointer to the new current item. NULL(O) is 
returned when the iterator is incremented past the end of the list. 

operator ++, operator +=, operator —, operator -=, reset, 

WCIterExcept: :undef_ iter 
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WCIsvConstSListlter<Type>,WCIsvConstDListlter<Type>::operator ++() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

Type * operator ++(); 

The operator ++ public member function is the pre-increment operator for the class. The list 
element which follows the current item is set to be the new current item. If the previous current item 
was the last element in the list, the iterator is positioned after the end of the list. 

The operator ++ public member function has the same semantics as the call operator, operator 
() - 

If the iterator was positioned before the first element in the list, the current item will be set to the first 
element in the list. If the list is empty, the iterator will be positioned after the end of the list. 

If the iterator is not associated with a list or the iterator position before the increment was past the last 
element the list, the undef_ iter exception is thrown, if enabled. 

The operator ++ public member function returns a pointer to the new current item. NULL(O) is 
returned when the iterator is incremented past the end of the list. 

current, operator (), operator +=, operator —, operator -=, reset, 
WCIterExcept::undef_ iter 


318 List Iterators 




WCIsvConstSListlter<Type>,WCIsvConstDListlter<Type>::operator +=() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

Type * operator +=( int ) ; 

The operator += public member function accepts an integer value that causes the iterator to move 
that many elements after the current item. If the iterator was positioned before the first element in the 
list, the operation will set the current item to be the given element in the list. 

If the current item was after the last element in the list previous to the iteration, and the undef_ iter 
exception is enabled, the exception will be thrown. Attempting to increment the iterator position more 
than element after the end of the list, or by less than one element causes the iter_ range exception to 
be thrown, if enabled. 

The operator += public member function returns a pointer to the new current item. NULL(O) is 
returned when the iterator is incremented past the end of the list. 

current,operator (), operator ++, operator —, operator -=, reset, 
WCIterExcept::iter_ range,WCIterExcept::undef_ iter 
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WCIsvConstDListlter<Type>::operator --() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

Type * operator —(); 

The operator — public member function is the pre-decrement operator for the class. The list 
element previous to the current item is set to be the new current item. If the current item was the first 
element in the list, the iterator is positioned before the first element in the list. If the list is empty, the 
iterator will be positioned before the start of the list. 

If the iterator was positioned after the last element in the list, the current item will be set to the last 
element. 

If the iterator is not associated with a list or the iterator position previous to the decrement was before 
the first element the list, the undef_ iter exception is thrown, if enabled. 

The operator — public member function returns a pointer to the new current item. NULL(O) is 
returned when the iterator is decremented past the first element of the list. 

current, operator (), operator ++, operator +=, operator -=, reset, 
WCIterExcept: :undef_ iter 
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WCIsvConstDListlter<Type>::operator-=() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

Type * operator -=( int ) ; 

The operator -= public member function accepts an integer value that causes the iterator to move 
that many elements before the current item. If the iterator was positioned after the last element in the 
list, the operation will set the current item to be the given number of elements from the end of the list. 

If the current item was before the first element in the list previous to the iteration, and the 
undef_ iter exception is enabled, the exception will be thrown. Attempting to decrement the iterator 
position more than one element before the beginning of the list, or by less than one element causes the 
iter_ range exception to be thrown, if enabled. 

The operator -= public member function returns a pointer to the new current item. NULL(O) is 
returned when the iterator is decremented past the first element in the list. 

current,operator (), operator ++, operator +=, operator —,reset, 
WCIterExcept::iter_ range,WCIterExcept::undef_ iter 
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WCIsvConstSListlter<Type>::reset(), WCIsvConstDListlter<Type>::reset() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclistit.h> 

public: 

void reset(); 

The reset public member function resets the iterator to the initial state, positioning the iterator before 
the first element in the associated list. 

The iterator is positioned before the first list element. 

WCIsvConstSListlter, WCIsvConstDListlter, container 
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WCIsvConstSListlter<Type>::reset(), WCIsvConstDListlter<Type>::reset() 


Synopsis: #include <wclistit.h> 

public: 

void WCIsvConstSListIter<Type>::reset( const WCIsvSList<Type> & ); 
void WCIsvConstDListIter<Type>::reset ( const WCIsvDList<Type> & ); 


Semantics: 

Results: 
See Also: 


The reset public member function resets the iterator to operate on the specified list. The iterator is 
positioned before the first element in the list. 

The iterator is positioned before the first element of the specified list. 

WCIsvConstSListlter, WCIsvConstDListlter, container 


List Iterators 323 




WCIsvSListlter<Type>, WCIsvDListlter<Type> 


Declared: 


wclistit.h 


The WCIsvSListIter<Type> and WCIsvDListIter<Type> classes are the templated classes 
used to create iterator objects for single and double linked list objects. These classes can be used only 
for non-constant lists. The WCIsvDConstListIter<Type> and 
WCIsvSConstListIter<Type> classes are provided to iterate over constant lists. 

In the description of each member function, the text Type is used to indicate the list element type 
specified as the template parameter. 

The WCIterExcept class is a base class of the WCIsvSListIter<Type> and 
WCIsvDListIter<Type> classes and provides the exceptions member function. This member 
function controls the exceptions which can be thrown by the WCIsvSListIter<Type> and 
WCIsvDListIter<Type> objects. No exceptions are enabled unless they are set by the 
exceptions member function. 

Private Member Functions 

Some functionality supported by base classes of the iterator are not appropriate in the single linked list 
iterator classes. Setting those functions as private members in the derived class is the standard 
mechanism to prevent them from being invoked. The following member functions are declared in the 
single linked list iterator private interface: 

Type * operator —(); 

Type * operator -=( int ) ; 
int insert( Type * ) ; 

Public Member Functions 


The following member functions are declared in the public interface: 


WCIsvSListlter(); 

WCIsvSListlter! WCIsvSList<Type> 

-WCIsvSListlter(); 

WCIsvDListlter(); 

WCIsvDListlter( WCIsvDList<Type> 

-WCIsvDListlter(); 
int append( Type * ); 

WCIsvSList<Type> 

WCIsvDList<Type> 

Type * current() 
void reset (); 

void WCIsvSListIter<Type>::reset ( WCIsvSList<Type> 
void WCIsvDListIter<Type>::reset( WCIsvDList<Type> 


& ) ; 


& ) 


*WCIsvSListIter<Type>::container() 
*WCIsvDListIter<Type>::container() 


const; 


const; 

const; 


& ) ; 
& ) ; 


In the iterators for double linked lists only: 
int insert ( Type * ); 


Public Member Operators 

The following member operators are declared in the public interface: 


Type * 
Type * 
Type * 


operator () () ; 
operator ++ (); 
operator +=( int 


) ; 
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WCIsvSListlter<Type>, WCIsvDListlter<Type> 


See Also: 


In the iterators for double linked lists only: 

Type * operator —(); 

Type * operator -=( int ) ; 

WCIsvSList::forAll, WCIsvDList: :forAll 
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WCIsvSListlter<Type>::WCIsvSListlter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wclistit.h> 
public: 

WCIsvSListlter() ; 

The WCIsvSListlter public member function is the default constructor for the class and initializes 
the iterator with no list to operate on. The reset member function must be called to provide the 
iterator with a list to iterate over. 

The WCIsvSListlter public member function creates an initialized WCIsvSListlter object. 
WCIsvSListlter, ~WCIsvSListIter, reset 
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WCIsvSListlter<Type>::WCIsvSListlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

WCIsvSListlter! WCIsvSList<Type> & ); 

The WCIsvSListlter public member function is a constructor for the class. The value passed as a 
parameter is a WCIsvSList list object. The iterator will be initialized for that list object and 
positioned before the first list element. To position the iterator to a valid element within the list, 
increment it using any of the operator ++, operator (), or operator += operators. 

The WCIsvSListlter public member function creates an initialized WCIsvSListlter object 
positioned before the first element in the list. 

~WCIsvSListIter, operator (), operator ++, operator +=, reset 
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WCIsvSListlter<Type>::~WCIsvSListlter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wclistit.h> 
public: 

-WCIsvSListlter() ; 

The -WCIsvSListlter public member function is the destructor for the class. The call to the 
-WCIsvSListlter public member function is inserted implicitly by the compiler at the point where 
the WCIsvSListlter object goes out of scope. 

The WCIsvSListlter object is destroyed. 

WCIsvSListlter 
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WCIsvDListlter<Type>::WCIsvDListlter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclistit.h> 
public: 

WCIsvDListlter() ; 

The WCIsvDListlter public member function is the default constructor for the class and initializes 
the iterator with no list to operate on. The reset member function must be called to provide the 
iterator with a list to iterate over. 

The WCIsvDListlter public member function creates an initialized WCIsvDListlter object. 
WCIsvDListlter, ~WCIsvDListIter, reset 
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WCIsvDListlter<Type>::WCIsvDListlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

WCIsvDListlter( WCIsvDList<Type> & ); 

The WCIsvDListlter public member function is a constructor for the class. The value passed as a 
parameter is the WCIsvDList list object. The iterator will be initialized for that list object and 
positioned before the first list element. To position the iterator to a valid element within the list, 
increment it using any of the operator ++, operator (), or operator += operators. 

The WCIsvDListlter public member function creates an initialized WCIsvDListlter object 
positioned before the first list element. 

WCIsvDListlter, ~WCIsvDListIter, operator (), operator ++, operator +=, 
reset 
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WCIsvDListlter<Type>::~WCIsvDListlter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wclistit.h> 
public: 

~WCIsvDListIter() ; 

The -WCIsvDListlter public member function is the destructor for the class. The call to the 
-WCIsvDListlter public member function is inserted implicitly by the compiler at the point where 
the WCIsvDListlter object goes out of scope. 

The WCIsvDListlter object is destroyed. 

WCIsvDListlter 
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WCIsvSListlter<Type>::append(), WCIsvDListlter<Type>::append() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int append( Type * ) ; 

The append public member function inserts a new element into the list container object. The new 
element is inserted after the current iterator item. 

If the iterator is not associated with a list, or the iterator position is either before the first element or past 
the last element in the list, the current iterator position is undefined. The element is not appended. If 
the undef_ iter exception is enabled, it is thrown. 

The new element is inserted after the current iterator item. A TRUE value (non-zero) is returned if the 
append is successful. A FALSE (zero) result is returned if the append fails. 

insert, WCExcept: : out_ of_ memorytylCIterExcept: : undef_ iter 
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WCIsvSListlter<Type>,WCIsvDListlter<Type>::container() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

WCIsvSList<Type> *WCIsvSListIter<Type>::container() const; 
WCIsvDList<Type> *WCIsvDListIter<Type>::container() const; 

The container public member function returns a pointer to the list container object. If the iterator 
has not been initialized with a list object, and the undef_ iter exception is enabled, the exception is 
thrown. 

A pointer to the list object associated with the iterator is returned, or NULL(O) if the iterator has not 
been initialized with a list. 

WCIsvSListlter, WCIsvDListlter, reset,WCIterExcept: :undef_ iter 
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WCIsvSListlter<Type>::current(), WCIsvDListlter<Type>::current() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

Type * current(); 

The current public member function returns a pointer to the list item at the current iterator position. 

If the iterator is not associated with a list, or the iterator position is either before the first element or past 
the last element in the list, the current iterator position is undefined. In this case the undef_ item 
exception is thrown, if enabled. 

A pointer to the current list element is returned. If the current element is undefined, NULL(O) is 
returned. 

operator (), operator ++, operator +=, operator —, operator -=, reset, 
WCIterExcept::undef_ item 
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WCIsvDListlter<Type>::insert() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

int insert( Type * ) ; 

The insert public member function inserts a new element into the list container object. The new 
element is inserted before the current iterator item. This process uses the previous link in the double 
linked list, so the insert public member function is not allowed with single linked lists. 

If the iterator is not associated with a list, or the iterator position is either before the first element or past 
the last element in the list, the current iterator position is undefined. The element is not inserted. If the 
undef_ iter exception is enabled, the exception is thrown. 

The new element is inserted before the current iterator item. A TRUE value (non-zero) is returned if the 
insert is successful. A FALSE (zero) result is returned if the insert fails. 

append, WCExcept: : out_ of_ memorytylCIterExcept: : undef_ iter 
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WCIsvSListlter<Type>, WCIsvDListlter<Type>: operator ()() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

Type * operator () (); 

The operator () public member function is the call operator for the class. The list element which 
follows the current item is set to be the new current item. If the previous current item was the last 
element in the list, the iterator is positioned after the end of the list. 

The operator () public member function has the same semantics as the pre-increment operator, 
operator ++. 

If the iterator was positioned before the first element in the list, the current item will be set to the first 
element in the list. If the list is empty, the iterator will be positioned after the end of the list. 

If the iterator is not associated with a list or the iterator position before the increment was past the last 
element the list, the undef_ iter exception is thrown, if enabled. 

The operator () public member function returns a pointer to the new current item. NULL(O) is 
returned when the iterator is incremented past the end of the list. 

operator ++, operator +=, operator —, operator -=, reset, 

WCIterExcept: :undef_ iter 
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WCIsvSListlter<Type>, WCIsvDListlter<Type>::operator ++() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

Type * operator ++(); 

The operator ++ public member function is the pre-increment operator for the class. The list 
element which follows the current item is set to be the new current item. If the previous current item 
was the last element in the list, the iterator is positioned after the end of the list. 

The operator ++ public member function has the same semantics as the call operator, operator 
() - 

If the iterator was positioned before the first element in the list, the current item will be set to the first 
element in the list. If the list is empty, the iterator will be positioned after the end of the list. 

If the iterator is not associated with a list or the iterator position before the increment was past the last 
element the list, the undef_ iter exception is thrown, if enabled. 

The operator ++ public member function returns a pointer to the new current item. NULL(O) is 
returned when the iterator is incremented past the end of the list. 

current, operator (), operator +=, operator —, operator -=, reset, 
WCIterExcept::undef_ iter 
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WCIsvSListlter<Type>, WCIsvDListlter<Type>: operator +=() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

Type * operator +=( int ) ; 

The operator += public member function accepts an integer value that causes the iterator to move 
that many elements after the current item. If the iterator was positioned before the first element in the 
list, the operation will set the current item to be the given element in the list. 

If the current item was after the last element in the list previous to the iteration, and the undef_ iter 
exception is enabled, the exception will be thrown. Attempting to increment the iterator position more 
than element after the end of the list, or by less than one element causes the iter_ range exception to 
be thrown, if enabled. 

The operator += public member function returns a pointer to the new current item. NULL(O) is 
returned when the iterator is incremented past the end of the list. 

current,operator (), operator ++, operator —, operator -=, reset, 
WCIterExcept::iter_ range,WCIterExcept::undef_ iter 
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WCIsvDListlter<Type>::operator --() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

Type * operator —(); 

The operator — public member function is the pre-decrement operator for the class. The list 
element previous to the current item is set to be the new current item. If the current item was the first 
element in the list, the iterator is positioned before the first element in the list. If the list is empty, the 
iterator will be positioned before the start of the list. 

If the iterator was positioned after the last element in the list, the current item will be set to the last 
element. 

If the iterator is not associated with a list or the iterator position previous to the decrement was before 
the first element the list, the undef_ iter exception is thrown, if enabled. 

The operator — public member function returns a pointer to the new current item. NULL(O) is 
returned when the iterator is decremented past the first element of the list. 

current, operator (), operator ++, operator +=, operator -=, reset, 
WCIterExcept: :undef_ iter 
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WCIsvDListlter<Type>::operator-=() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

Type * operator -=( int ) ; 

The operator -= public member function accepts an integer value that causes the iterator to move 
that many elements before the current item. If the iterator was positioned after the last element in the 
list, the operation will set the current item to be the given number of elements from the end of the list. 

If the current item was before the first element in the list previous to the iteration, and the 
undef_ iter exception is enabled, the exception will be thrown. Attempting to decrement the iterator 
position more than one element before the beginning of the list, or by less than one element causes the 
iter_ range exception to be thrown, if enabled. 

The operator -= public member function returns a pointer to the new current item. NULL(O) is 
returned when the iterator is decremented past the first element in the list. 

current,operator (), operator ++, operator +=, operator —,reset, 
WCIterExcept::iter_ range,WCIterExcept::undef_ iter 
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WCIsvSListlter<Type>::reset(), WCIsvDListlter<Type>::reset() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wclistit.h> 

public: 

void reset(); 

The reset public member function resets the iterator to the initial state, positioning the iterator before 
the first element in the associated list. 

The iterator is positioned before the first list element. 

WCIsvSListlter, WCIsvDListlter, container 
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WCIsvSListlter<Type>::reset(), WCIsvDListlter<Type>::reset() 


Synopsis: #include <wclistit.h> 

public: 

void WCIsvSListIter<Type>::reset( WCIsvSList<Type> & ); 
void WCIsvDListIter<Type>::reset( WCIsvDList<Type> & ); 


Semantics: 

Results: 
See Also: 


The reset public member function resets the iterator to operate on the specified list. The iterator is 
positioned before the first element in the list. 

The iterator is positioned before the first element of the specified list. 

WCIsvSListlter, WCIsvDListlter, container 
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WCPtrConstSListlter<Type>, WCPtrConstDListlter<Type> 


Declared: 


See Also: 


wclistit.h 

The WCPtrConstSListIter<Type> and WCPtrConstDListIter<Type> classes are the 
templated classes used to create iterator objects for constant single and double linked list objects. These 
classes may be used to iterate over non-constant lists, but the WCPtrDListIter<Type> and 
WCPtrSListIter<Type> classes provide additional functionality for only non-constant lists. 

In the description of each member function, the text Type is used to indicate the list element type 
specified as the template parameter. 

The WCIterExcept class is a base class of the WCPtrConstSListIter<Type> and 
WCPtrConstDListIter<Type> classes and provides the exceptions member function. This 
member function controls the exceptions which can be thrown by the 

WCPtrConstSListIter<Type> and WCPtrConstDListIter<Type> objects. No exceptions 
are enabled unless they are set by the exceptions member function. 

Private Member Functions 

Some functionality supported by base classes of the iterator are not appropriate for the constant list 
iterator classes. Setting those functions as private members in the derived class is the standard 
mechanism to prevent them from being invoked. 

int append( Type * ); 
int insert ( Type * ); 

Public Member Functions 

The following member functions are declared in the public interface: 

WCPtrConstSListlter (); 

WCPtrConstSListlter ( const WCPtrSList<Type> & ); 

-WCPtrConstSListlter(); 

WCPtrConstDListlter(); 

WCPtrConstDListlter( const WCPtrDList<Type> & ); 

-WCPtrConstDListlter() ; 

const WCPtrSList<Type> *WCPtrConstSListIter<Type>::container() const; 
const WCPtrDList<Type> *WCPtrConstDListIter<Type>::container() const; 
Type * current!) const; 
void reset(); 

void WCPtrConstSListIter<Type>::reset( const WCPtrSList<Type> & ); 
void WCPtrConstDListIter<Type>::reset( const WCPtrDList<Type> & ); 

Public Member Operators 

The following member operators are declared in the public interface: 

int operator () (); 
int operator ++(); 
int operator +=( int ); 

In the iterators for double linked lists only: 

int operator —(); 
int operator -=( int ); 

WCPtrSList::forAll, WCPtrDList: :forAll 
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WCPtrConstSListlter<Type>::WCPtrConstSListlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

WCPtrConstSListlter() ; 

The WCPtrConstSListlter public member function is the default constructor for the class and 
initializes the iterator with no list to operate on. The reset member function must be called to provide 
the iterator with a list to iterate over. 

The WCPtrConstSListlter public member function creates an initialized 
WCPtrConstSListlter object. 

WCPtrConstSListlter, ~WCPtrConstSListIter, reset 
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WCPtrConstSListlter<Type>::WCPtrConstSListlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

WCPtrConstSListlter( const WCPtrSList<Type> & ); 

The WCPtrConstSListlter public member function is a constructor for the class. The value 
passed as a parameter is a WCPtrSList list object. The iterator will be initialized for that list object 
and positioned before the first list element. To position the iterator to a valid element within the list, 
increment it using any of the operator ++, operator (), or operator += operators. 

The WCPtrConstSListlter public member function creates an initialized 
WCPtrConstSListlter object positioned before the first element in the list. 

~WCPtrConstSListIter, operator (), operator ++, operator +=, reset 
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WCPtrConstSListlter<Type>::~WCPtrConstSListlter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclistit.h> 
public: 

-WCPtrConstSListlter() ; 

The -WCPtrConstSListlter public member function is the destructor for the class. The call to 
the -WCPtrConstSListlter public member function is inserted implicitly by the compiler at the 
point where the WCPtrConstSListlter object goes out of scope. 

The WCPtrConstSListlter object is destroyed. 

WCPtrConstSListlter 
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WCPtrConstDListlter<Type>::WCPtrConstDListlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

WCPtrConstDListlter() ; 

The WCPtrConstDListlter public member function is the default constructor for the class and 
initializes the iterator with no list to operate on. The reset member function must be called to provide 
the iterator with a list to iterate over. 

The WCPtrConstDListlter public member function creates an initialized 
WCPtrConstDListlter object. 

WCPtrConstDListlter, ~WCPtrConstDListIter, reset 
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WCPtrConstDListlter<Type>::WCPtrConstDListlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

WCPtrConstDListlter( const WCPtrDList<Type> & ); 

The WCPtrConstDListlter public member function is a constructor for the class. The value 
passed as a parameter is the WCPtrDList list object. The iterator will be initialized for that list object 
and positioned before the first list element. To position the iterator to a valid element within the list, 
increment it using any of the operator ++, operator (), or operator += operators. 

The WCPtrConstDListlter public member function creates an initialized 
WCPtrConstDListlter object positioned before the first list element. 

WCPtrConstDListlter, ~WCPtrConstDListIter, operator (),operator ++, 
operator +=, reset 
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WCPtrConstDListlter<Type>::~WCPtrConstDListlter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclistit.h> 
public: 

-WCPtrConstDListlter() ; 

The -WCPtrConstDListlter public member function is the destructor for the class. The call to 
the -WCPtrConstDListlter public member function is inserted implicitly by the compiler at the 
point where the WCPtrConstDListlter object goes out of scope. 

The WCPtrConstDListlter object is destroyed. 

WCPtrConstDListlter 
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WCPtrConstSListlter<Type>,WCPtrConstDListlter<Type>::container() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

const WCPtrSList<Type> *WCPtrConstSListIter<Type>::container() const; 
const WCPtrDList<Type> *WCPtrConstDListIter<Type>::container() const; 

The container public member function returns a pointer to the list container object. If the iterator 
has not been initialized with a list object, and the undef_ iter exception is enabled, the exception is 
thrown. 

A pointer to the list object associated with the iterator is returned, or NULL(O) if the iterator has not 
been initialized with a list. 

WCPtrConstSListlter, WCPtrConstDListlter, reset, WCIterExcept: :undef_ iter 
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WCPtrConstSListlter<Type>::current(), WCPtrConstDListlter<Type>::current() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

Type * current(); 

The current public member function returns a pointer to the list item at the current iterator position. 

If the iterator is not associated with a list, or the iterator position is either before the first element or past 
the last element in the list, the current iterator position is undefined. In this case the undef_ item 
exception is thrown, if enabled. 

A pointer to the current list element is returned. If the current element is undefined, an uninitialized 
pointer is returned. 

operator (), operator ++, operator +=, operator —, operator -=, reset, 
WCIterExcept::undef_ item 
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WCPtrConstSListlter<Type>,WCPtrConstDListlter<Type>::operator ()() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int operator ()(); 

The operator () public member function is the call operator for the class. The list element which 
follows the current item is set to be the new current item. If the previous current item was the last 
element in the list, the iterator is positioned after the end of the list. 

The operator () public member function has the same semantics as the pre-increment operator, 
operator ++. 

If the iterator was positioned before the first element in the list, the current item will be set to the first 
element in the list. If the list is empty, the iterator will be positioned after the end of the list. 

If the iterator is not associated with a list or the iterator position before the increment was past the last 
element the list, the undef_ iter exception is thrown, if enabled. 

The operator () public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is incremented past the end of the list. 

operator ++, operator +=, operator —, operator -=, reset, 

WCIterExcept: :undef_ iter 
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WCPtrConstSListlter<Type>,WCPtrConstDListlter<Type>::opemtor ++() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int operator ++(); 

The operator ++ public member function is the pre-increment operator for the class. The list 
element which follows the current item is set to be the new current item. If the previous current item 
was the last element in the list, the iterator is positioned after the end of the list. 

The operator ++ public member function has the same semantics as the call operator, operator 
() - 

If the iterator was positioned before the first element in the list, the current item will be set to the first 
element in the list. If the list is empty, the iterator will be positioned after the end of the list. 

If the iterator is not associated with a list or the iterator position before the increment was past the last 
element the list, the undef_ iter exception is thrown, if enabled. 

The operator ++ public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is incremented past the end of the list. 

current, operator (), operator +=, operator —, operator -=, reset, 
WCIterExcept: :undef_ iter 
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WCPtrConstSListlter<Type>,WCPtrConstDListlter<Type>::operator +=() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int operator +=( int ) ; 

The operator += public member function accepts an integer value that causes the iterator to move 
that many elements after the current item. If the iterator was positioned before the first element in the 
list, the operation will set the current item to be the given element in the list. 

If the current item was after the last element in the list previous to the iteration, and the undef_ iter 
exception is enabled, the exception will be thrown. Attempting to increment the iterator position more 
than element after the end of the list, or by less than one element causes the iter_ range exception to 
be thrown, if enabled. 

The operator += public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is incremented past the end of the list. 

current,operator (), operator ++, operator —, operator -=, reset, 
WCIterExcept::iter_ range,WCIterExcept::undef_ iter 
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WCPtrConstDListlter<Type>::operator --() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int operator —(); 

The operator — public member function is the pre-decrement operator for the class. The list 
element previous to the current item is set to be the new current item. If the current item was the first 
element in the list, the iterator is positioned before the first element in the list. If the list is empty, the 
iterator will be positioned before the start of the list. 

If the iterator was positioned after the last element in the list, the current item will be set to the last 
element. 

If the iterator is not associated with a list or the iterator position previous to the decrement was before 
the first element the list, the undef_ iter exception is thrown, if enabled. 

The operator — public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is decremented past the first element of the list. 

current, operator (), operator ++, operator +=, operator -=, reset, 
WCIterExcept: :undef_ iter 
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WCPtrConstDListlter<Type>: -.operator -=() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int operator -=( int ) ; 

The operator -= public member function accepts an integer value that causes the iterator to move 
that many elements before the current item. If the iterator was positioned after the last element in the 
list, the operation will set the current item to be the given number of elements from the end of the list. 

If the current item was before the first element in the list previous to the iteration, and the 
undef_ iter exception is enabled, the exception will be thrown. Attempting to decrement the iterator 
position more than one element before the beginning of the list, or by less than one element causes the 
iter_ range exception to be thrown, if enabled. 

The operator -= public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is decremented past the first element in the list. 

current,operator (), operator ++, operator +=, operator —,reset, 
WCIterExcept::iter_ range,WCIterExcept::undef_ iter 
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WCPtrConstSListlter<Type>::reset(), WCPtrConstDListlter<Type>::reset() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclistit.h> 

public: 

void reset(); 

The reset public member function resets the iterator to the initial state, positioning the iterator before 
the first element in the associated list. 

The iterator is positioned before the first list element. 

WCPtrConstSListlter, WCPtrConstDListlter, container 
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WCPtrConstSListlter<Type>::reset(), WCPtrConstDListlter<Type>::reset() 


Synopsis: #include <wclistit.h> 

public: 

void WCPtrConstSListIter<Type>::reset ( const WCPtrSList<Type> & ); 
void WCPtrConstDListIter<Type>::reset ( const WCPtrDList<Type> & ); 


Semantics: 

Results: 
See Also: 


The reset public member function resets the iterator to operate on the specified list. The iterator is 
positioned before the first element in the list. 

The iterator is positioned before the first element of the specified list. 

WCPtrConstSListlter, WCPtrConstDListlter, container 
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WCPtrSListlter<Type>, WCPtrDListlter<Type> 


Declared: 


wclistit.h 

The WCPtrSListIter<Type> and WCPtrDListIter<Type> classes are the templated classes 
used to create iterator objects for single and double linked list objects. These classes can be used only 
for non-constant lists. The WCPtrDConstListIter<Type> and 
WCPtrSConstListIter<Type> classes are provided to iterate over constant lists. 

In the description of each member function, the text Type is used to indicate the list element type 
specified as the template parameter. 

The WCIterExcept class is a base class of the WCPtrSListIter<Type> and 
WCPtrDListIter<Type> classes and provides the exceptions member function. This member 
function controls the exceptions which can be thrown by the WCPtrSListIter<Type> and 
WCPtrDListIter<Type> objects. No exceptions are enabled unless they are set by the 
exceptions member function. 

Private Member Functions 

Some functionality supported by base classes of the iterator are not appropriate in the single linked list 
iterator classes. Setting those functions as private members in the derived class is the standard 
mechanism to prevent them from being invoked. The following member functions are declared in the 
single linked list iterator private interface: 

int operator —(); 
int operator -=( int ); 
int insert ( Type * ); 

Public Member Functions 

The following member functions are declared in the public interface: 

WCPtrSListlter (); 

WCPtrSListlter ( WCPtrSList<Type> & ); 

-WCPtrSListlter(); 

WCPtrDListlter(); 

WCPtrDListlter( WCPtrDList<Type> & ) ; 

-WCPtrDListlter() ; 
int append( Type * ) ; 

WCPtrSList<Type> *WCPtrSListIter<Type>::container() const; 
WCPtrDList<Type> *WCPtrDListIter<Type>::container() const; 

Type * current() const; 
void reset(); 

void WCPtrSListIter<Type>::reset( WCPtrSList<Type> & ); 
void WCPtrDListIter<Type>::reset( WCPtrDList<Type> & ); 

In the iterators for double linked lists only: 

int insert ( Type * ); 

Public Member Operators 

The following member operators are declared in the public interface: 

int operator () (); 
int operator ++(); 
int operator +=( int ); 
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WCPtrSListlter<Type>, WCPtrDListlter<Type> 


See Also: 


In the iterators for double linked lists only: 

int operator —(); 
int operator -=( int ); 

WCPtrSList::forAll, WCPtrDList: :forAll 
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WCPtrSListlter<Type>::WCPtrSListlter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wclistit.h> 
public: 

WCPtrSListlter() ; 

The WCPtrSListlter public member function is the default constructor for the class and initializes 
the iterator with no list to operate on. The reset member function must be called to provide the 
iterator with a list to iterate over. 

The WCPtrSListlter public member function creates an initialized WCPtrSListlter object. 
WCPtrSListlter, ~WCPtrSListIter, reset 
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WCPtrSListlter<Type>::WCPtrSListlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

WCPtrSListlter ( WCPtrSList<Type> & ); 

The WCPtrSListlter public member function is a constructor for the class. The value passed as a 
parameter is a WCPtrSList list object. The iterator will be initialized for that list object and 
positioned before the first list element. To position the iterator to a valid element within the list, 
increment it using any of the operator ++, operator (), or operator += operators. 

The WCPtrSListlter public member function creates an initialized WCPtrSListlter object 
positioned before the first element in the list. 

~WCPtrSListIter, operator (), operator ++, operator +=, reset 
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WCPtrSListlter<Type>::~WCPtrSListlter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wclistit.h> 
public: 

-WCPtrSListlter!) ; 

The -WCPtrSListlter public member function is the destructor for the class. The call to the 
-WCPtrSListlter public member function is inserted implicitly by the compiler at the point where 
the WCPtrSListlter object goes out of scope. 

The WCPtrSListlter object is destroyed. 

WCPtrSListlter 
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WCPtrDListlter<Type>::WCPtrDListlter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wclistit.h> 
public: 

WCPtrDListlter() ; 

The WCPtrDListlter public member function is the default constructor for the class and initializes 
the iterator with no list to operate on. The reset member function must be called to provide the 
iterator with a list to iterate over. 

The WCPtrDListlter public member function creates an initialized WCPtrDListlter object. 
WCPtrDListlter, ~WCPtrDListIter, reset 
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WCPtrDListlter<Type>::WCPtrDListlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

WCPtrDListlter ( WCPtrDList<Type> & ); 

The WCPtrDListlter public member function is a constructor for the class. The value passed as a 
parameter is the WCPtrDList list object. The iterator will be initialized for that list object and 
positioned before the first list element. To position the iterator to a valid element within the list, 
increment it using any of the operator ++, operator (), or operator += operators. 

The WCPtrDListlter public member function creates an initialized WCPtrDListlter object 
positioned before the first list element. 

WCPtrDListlter, ~WCPtrDListIter, operator (), operator ++, operator +=, 
reset 
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WCPtrDListlter<Type>::~WCPtrDListlter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wclistit.h> 
public: 

-WCPtrDListlter() ; 

The -WCPtrDListlter public member function is the destructor for the class. The call to the 
-WCPtrDListlter public member function is inserted implicitly by the compiler at the point where 
the WCPtrDListlter object goes out of scope. 

The WCPtrDListlter object is destroyed. 

WCPtrDListlter 
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WCPtrSListlter<Type>::append(), WCPtrDListlter<Type>::append() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int append( Type * ) ; 

The append public member function inserts a new element into the list container object. The new 
element is inserted after the current iterator item. 

If the iterator is not associated with a list, or the iterator position is either before the first element or past 
the last element in the list, the current iterator position is undefined. The element is not appended. If 
the undef_ iter exception is enabled, it is thrown. 

If the append fails, the out_ of_ memory exception is thrown, if enabled in the list being iterated over. 
The list remains unchanged. 

The new element is inserted after the current iterator item. A TRUE value (non-zero) is returned if the 
append is successful. A FALSE (zero) result is returned if the append fails. 

insert, WCExcept: : out_ of_ memorytylCIterExcept: : undef_ iter 
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WCPtrSListlter<Type>,WCPtrDListlter<Type>::container() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

WCPtrSList<Type> *WCPtrSListIter<Type>::container() const; 
WCPtrDList<Type> *WCPtrDListIter<Type>::container () const; 

The container public member function returns a pointer to the list container object. If the iterator 
has not been initialized with a list object, and the undef_ iter exception is enabled, the exception is 
thrown. 

A pointer to the list object associated with the iterator is returned, or NULL(O) if the iterator has not 
been initialized with a list. 

WCPtrSListlter, WCPtrDListlter, reset,WCIterExcept: :undef_ iter 
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WCPtrSListlter<Type>::current(), WCPtrDListlter<Type>::current() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

Type * current(); 

The current public member function returns a pointer to the list item at the current iterator position. 

If the iterator is not associated with a list, or the iterator position is either before the first element or past 
the last element in the list, the current iterator position is undefined. In this case the undef_ item 
exception is thrown, if enabled. 

A pointer to the current list element is returned. If the current element is undefined, an uninitialized 
pointer is returned. 

operator (), operator ++, operator +=, operator —, operator -=, reset, 
WCIterExcept::undef_ item 
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WCPtrDListlter<Type>::insert() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int insert( Type * ) ; 

The insert public member function inserts a new element into the list container object. The new 
element is inserted before the current iterator item. This process uses the previous link in the double 
linked list, so the insert public member function is not allowed with single linked lists. 

If the iterator is not associated with a list, or the iterator position is either before the first element or past 
the last element in the list, the current iterator position is undefined. The element is not inserted. If the 
undef_ iter exception is enabled, the exception is thrown. 

If the insert fails and the out_ of_ memory exception is enabled in the list being iterated over, the 
exception is thrown. The list remains unchanged. 

The new element is inserted before the current iterator item. A TRUE value (non-zero) is returned if the 
insert is successful. A FALSE (zero) result is returned if the insert fails. 

append, WCExcept: : out_ of_ memorytyJCIterExcept: : undef_ iter 
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WCPtrSListlter<Type>, WCPtrDListlter<Type>: operator ()() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int operator ()(); 

The operator () public member function is the call operator for the class. The list element which 
follows the current item is set to be the new current item. If the previous current item was the last 
element in the list, the iterator is positioned after the end of the list. 

The operator () public member function has the same semantics as the pre-increment operator, 
operator ++. 

If the iterator was positioned before the first element in the list, the current item will be set to the first 
element in the list. If the list is empty, the iterator will be positioned after the end of the list. 

If the iterator is not associated with a list or the iterator position before the increment was past the last 
element the list, the undef_ iter exception is thrown, if enabled. 

The operator () public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is incremented past the end of the list. 

operator ++, operator +=, operator —, operator -=, reset, 

WCIterExcept: :undef_ iter 
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WCPtrSListlter<Type>, WCPtrDListlter<Type>::operator ++() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int operator ++(); 

The operator ++ public member function is the pre-increment operator for the class. The list 
element which follows the current item is set to be the new current item. If the previous current item 
was the last element in the list, the iterator is positioned after the end of the list. 

The operator ++ public member function has the same semantics as the call operator, operator 
() - 

If the iterator was positioned before the first element in the list, the current item will be set to the first 
element in the list. If the list is empty, the iterator will be positioned after the end of the list. 

If the iterator is not associated with a list or the iterator position before the increment was past the last 
element the list, the undef_ iter exception is thrown, if enabled. 

The operator ++ public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is incremented past the end of the list. 

current, operator (), operator +=, operator —, operator -=, reset, 
WCIterExcept: :undef_ iter 
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WCPtrSListlter<Type>, WCPtrDListlter<Type>: operator +=() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

int operator +=( int ) ; 

The operator += public member function accepts an integer value that causes the iterator to move 
that many elements after the current item. If the iterator was positioned before the first element in the 
list, the operation will set the current item to be the given element in the list. 

If the current item was after the last element in the list previous to the iteration, and the undef_ iter 
exception is enabled, the exception will be thrown. Attempting to increment the iterator position more 
than element after the end of the list, or by less than one element causes the iter_ range exception to 
be thrown, if enabled. 

The operator += public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is incremented past the end of the list. 

current,operator (), operator ++, operator —, operator -=, reset, 
WCIterExcept::iter_ range,WCIterExcept::undef_ iter 
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WCPtrDListlter<Type>: operator --() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int operator —(); 

The operator — public member function is the pre-decrement operator for the class. The list 
element previous to the current item is set to be the new current item. If the current item was the first 
element in the list, the iterator is positioned before the first element in the list. If the list is empty, the 
iterator will be positioned before the start of the list. 

If the iterator was positioned after the last element in the list, the current item will be set to the last 
element. 

If the iterator is not associated with a list or the iterator position previous to the decrement was before 
the first element the list, the undef_ iter exception is thrown, if enabled. 

The operator — public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is decremented past the first element of the list. 

current, operator (), operator ++, operator +=, operator -=, reset, 
WCIterExcept: :undef_ iter 
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WCPtrDListlter<Type>::operator-=() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

int operator -=( int ) ; 

The operator -= public member function accepts an integer value that causes the iterator to move 
that many elements before the current item. If the iterator was positioned after the last element in the 
list, the operation will set the current item to be the given number of elements from the end of the list. 

If the current item was before the first element in the list previous to the iteration, and the 
undef_ iter exception is enabled, the exception will be thrown. Attempting to decrement the iterator 
position more than one element before the beginning of the list, or by less than one element causes the 
iter_ range exception to be thrown, if enabled. 

The operator -= public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is decremented past the first element in the list. 

current,operator (), operator ++, operator +=, operator —,reset, 
WCIterExcept::iter_ range,WCIterExcept::undef_ iter 


List Iterators 375 




WCPtrSListlter<Type>::reset(), WCPtrDListlter<Type>::reset() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclistit.h> 

public: 

void reset(); 

The reset public member function resets the iterator to the initial state, positioning the iterator before 
the first element in the associated list. 

The iterator is positioned before the first list element. 

WCPtrSListlter, WCPtrDListlter, container 
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WCPtrSListlter<Type>::reset(), WCPtrDListlter<Type>::reset() 


Synopsis: #include <wclistit.h> 

public: 

void WCPtrSListIter<Type>::reset( WCPtrSList<Type> & ); 
void WCPtrDListIter<Type>::reset( WCPtrDList<Type> & ); 


Semantics: 

Results: 
See Also: 


The reset public member function resets the iterator to operate on the specified list. The iterator is 
positioned before the first element in the list. 

The iterator is positioned before the first element of the specified list. 

WCPtrSListlter, WCPtrDListlter, container 
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WCValConstSListlter<Type>, WCValConstDListlter<Type> 


Declared: wclistit.h 

The WCValConstSListIter<Type> and WCValConstDListIter<Type> classes are the 
templated classes used to create iterator objects for constant single and double linked list objects. These 
classes may be used to iterate over non-constant lists, but the WCValDListIter<Type> and 
WCValSListIter<Type> classes provide additional functionality for only non-constant lists. 

In the description of each member function, the text Type is used to indicate the list element type 
specified as the template parameter. 

The WCIterExcept class is a base class of the WCValConstSListIter<Type> and 
WCValConstDListIter<Type> classes and provides the exceptions member function. This 
member function controls the exceptions which can be thrown by the 

WCValConstSListIter<Type> and WCValConstDListIter<Type> objects. No exceptions 
are enabled unless they are set by the exceptions member function. 

Private Member Functions 

Some functionality supported by base classes of the iterator are not appropriate for the constant list 
iterator classes. Setting those functions as private members in the derived class is the standard 
mechanism to prevent them from being invoked. 

int append( Type & ) ; 
int insert( Type & ) ; 

Public Member Functions 

The following member functions are declared in the public interface: 

WCValConstSListlter() ; 

WCValConstSListlter( const WCValSList<Type> & ) ; 

-WCValConstSListlter() ; 

WCValConstDListlter() ; 

WCValConstDListlter( const WCValDList<Type> & ); 

-WCValConstDListlter() ; 

const WCValSList<Type> *WCValConstSListIter<Type>::container() const; 
const WCValDList<Type> *WCValConstDListIter<Type>::container() const; 
Type current!) const; 
void reset(); 

void WCValConstSListIter<Type>::reset( const WCValSList<Type> & ); 
void WCValConstDListIter<Type>::reset( const WCValDList<Type> & ); 

Public Member Operators 

The following member operators are declared in the public interface: 

int operator ()(); 
int operator ++() ; 
int operator +=( int ) ; 

In the iterators for double linked lists only: 

int operator —(); 
int operator -=( int ); 

See Also: WCValSList: : forAll, WCValDList: : forAll 
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WCValConstSListlter<Type>::WCValConstSListlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

WCValConstSListlter() ; 

The WCValConstSListlter public member function is the default constructor for the class and 
initializes the iterator with no list to operate on. The reset member function must be called to provide 
the iterator with a list to iterate over. 

The WCValConstSListlter public member function creates an initialized 
WCValConstSListlter object. 

WCValConstSListlter, ~WCValConstSListIter, reset 
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WCValConstSListlter<Type>::WCValConstSListlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

WCValConstSListlter( const WCValSList<Type> & ); 

The WCValConstSListlter public member function is a constructor for the class. The value 
passed as a parameter is a WCValSList list object. The iterator will be initialized for that list object 
and positioned before the first list element. To position the iterator to a valid element within the list, 
increment it using any of the operator ++, operator (), or operator += operators. 

The WCValConstSListlter public member function creates an initialized 
WCValConstSListlter object positioned before the first element in the list. 

~WCValConstSListIter, operator (), operator ++, operator +=, reset 
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WCValConstSListlter<Type>::~WCValConstSListlter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclistit.h> 
public: 

-WCValConstSListlter() ; 

The -WCValConstSListlter public member function is the destructor for the class. The call to 
the -WCValConstSListlter public member function is inserted implicitly by the compiler at the 
point where the WCValConstSListlter object goes out of scope. 

The WCValConstSListlter object is destroyed. 

WCValConstSListlter 
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WCValConstDListlter<Type>::WCValConstDListlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

WCValConstDListlter() ; 

The WCValConstDListlter public member function is the default constructor for the class and 
initializes the iterator with no list to operate on. The reset member function must be called to provide 
the iterator with a list to iterate over. 

The WCValConstDListlter public member function creates an initialized 
WCValConstDListlter object. 

WCValConstDListlter, ~WCValConstDListIter, reset 
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WCValConstDListlter<Type>::WCValConstDListlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

WCValConstDListlter( const WCValDList<Type> & ); 

The WCValConstDListlter public member function is a constructor for the class. The value 
passed as a parameter is the WCValDList list object. The iterator will be initialized for that list object 
and positioned before the first list element. To position the iterator to a valid element within the list, 
increment it using any of the operator ++, operator (), or operator += operators. 

The WCValConstDListlter public member function creates an initialized 
WCValConstDListlter object positioned before the first list element. 

WCValConstDListlter, ~WCValConstDListIter, operator (),operator ++, 
operator +=, reset 
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WCValConstDListlter<Type>::~WCValConstDListlter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclistit.h> 
public: 

-WCValConstDListlter() ; 

The -WCValConstDListlter public member function is the destructor for the class. The call to 
the -WCValConstDListlter public member function is inserted implicitly by the compiler at the 
point where the WCValConstDListlter object goes out of scope. 

The WCValConstDListlter object is destroyed. 

WCValConstDListlter 


384 List Iterators 




WC ValConstSListlter<Type>, WC ValConstDListlter<Type>::container() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

const WCValSList<Type> *WCValConstSListIter<Type>::container() const; 
const WCValDList<Type> *WCValConstDListIter<Type>::container() const; 

The container public member function returns a pointer to the list container object. If the iterator 
has not been initialized with a list object, and the undef_ iter exception is enabled, the exception is 
thrown. 

A pointer to the list object associated with the iterator is returned, or NULL(O) if the iterator has not 
been initialized with a list. 

WCValConstSListlter, WCValConstDListlter, reset, WCIterExcept: :undef_ iter 
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WCValConstSListlter<Type>::current(), WCValConstDListlter<Type>::current() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

Type current(); 

The current public member function returns the value of the list element at the current iterator 
position. 

If the iterator is not associated with a list, or the iterator position is either before the first element or past 
the last element in the list, the current iterator position is undefined. In this case the undef_ item 
exception is thrown, if enabled. 

The value at the current iterator element is returned. If the current element is undefined, a default 
initialized object is returned. 

operator (), operator ++, operator +=, operator —, operator -=, reset, 
WCIterExcept::undef_ item 


386 List Iterators 




WCValConstSListlter<Type>,WCValConstDListlter<Type>::operator()() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int operator ()(); 

The operator () public member function is the call operator for the class. The list element which 
follows the current item is set to be the new current item. If the previous current item was the last 
element in the list, the iterator is positioned after the end of the list. 

The operator () public member function has the same semantics as the pre-increment operator, 
operator ++. 

If the iterator was positioned before the first element in the list, the current item will be set to the first 
element in the list. If the list is empty, the iterator will be positioned after the end of the list. 

If the iterator is not associated with a list or the iterator position before the increment was past the last 
element the list, the undef_ iter exception is thrown, if enabled. 

The operator () public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is incremented past the end of the list. 

operator ++, operator +=, operator —, operator -=, reset, 

WCIterExcept: :undef_ iter 
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WCValConstSListlter<Type>,WCValConstDListlter<Type>::operator ++() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int operator ++(); 

The operator ++ public member function is the pre-increment operator for the class. The list 
element which follows the current item is set to be the new current item. If the previous current item 
was the last element in the list, the iterator is positioned after the end of the list. 

The operator ++ public member function has the same semantics as the call operator, operator 
() - 

If the iterator was positioned before the first element in the list, the current item will be set to the first 
element in the list. If the list is empty, the iterator will be positioned after the end of the list. 

If the iterator is not associated with a list or the iterator position before the increment was past the last 
element the list, the undef_ iter exception is thrown, if enabled. 

The operator ++ public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is incremented past the end of the list. 

current, operator (), operator +=, operator —, operator -=, reset, 
WCIterExcept: :undef_ iter 
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WCValConstSListlter<Type>,WCValConstDListlter<Type>::operator +=() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int operator +=( int ) ; 

The operator += public member function accepts an integer value that causes the iterator to move 
that many elements after the current item. If the iterator was positioned before the first element in the 
list, the operation will set the current item to be the given element in the list. 

If the current item was after the last element in the list previous to the iteration, and the undef_ iter 
exception is enabled, the exception will be thrown. Attempting to increment the iterator position more 
than element after the end of the list, or by less than one element causes the iter_ range exception to 
be thrown, if enabled. 

The operator += public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is incremented past the end of the list. 

current,operator (), operator ++, operator —, operator -=, reset, 
WCIterExcept::iter_ range,WCIterExcept::undef_ iter 
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WCValConstDListlter<Type>::operator --() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int operator —(); 

The operator — public member function is the pre-decrement operator for the class. The list 
element previous to the current item is set to be the new current item. If the current item was the first 
element in the list, the iterator is positioned before the first element in the list. If the list is empty, the 
iterator will be positioned before the start of the list. 

If the iterator was positioned after the last element in the list, the current item will be set to the last 
element. 

If the iterator is not associated with a list or the iterator position previous to the decrement was before 
the first element the list, the undef_ iter exception is thrown, if enabled. 

The operator — public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is decremented past the first element of the list. 

current, operator (), operator ++, operator +=, operator -=, reset, 
WCIterExcept: :undef_ iter 
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WCValConstDListlter<Type>: operator -=() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

int operator -=( int ) ; 

The operator -= public member function accepts an integer value that causes the iterator to move 
that many elements before the current item. If the iterator was positioned after the last element in the 
list, the operation will set the current item to be the given number of elements from the end of the list. 

If the current item was before the first element in the list previous to the iteration, and the 
undef_ iter exception is enabled, the exception will be thrown. Attempting to decrement the iterator 
position more than one element before the beginning of the list, or by less than one element causes the 
iter_ range exception to be thrown, if enabled. 

The operator -= public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is decremented past the first element in the list. 

current,operator (), operator ++, operator +=, operator —,reset, 
WCIterExcept::iter_ range,WCIterExcept::undef_ iter 
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WCValConstSListlter<Type>::reset(), WCValConstDListlter<Type>::reset() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclistit.h> 

public: 

void reset(); 

The reset public member function resets the iterator to the initial state, positioning the iterator before 
the first element in the associated list. 

The iterator is positioned before the first list element. 

WCValConstSListlter, WCValConstDListlter, container 
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WCValConstSListlter<Type>::reset(), WCValConstDListlter<Type>::reset() 


Synopsis: #include <wclistit.h> 

public: 

void WCValConstSListIter<Type>::reset( const WCValSList<Type> & ); 
void WCValConstDListIter<Type>::reset ( const WCValDList<Type> & ); 


Semantics: 

Results: 
See Also: 


The reset public member function resets the iterator to operate on the specified list. The iterator is 
positioned before the first element in the list. 

The iterator is positioned before the first element of the specified list. 

WCValConstSListlter, WCValConstDListlter, container 
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WCValSListlter<Type>, WCValDListlter<Type> 


Declared: 


wclistit.h 

The WCValSListIter<Type> and WCValDListIter<Type> classes are the templated classes 
used to create iterator objects for single and double linked list objects. These classes can be used only 
for non-constant lists. The WCValDConstListIter<Type> and 
WCValSConstListIter<Type> classes are provided to iterate over constant lists. 

In the description of each member function, the text Type is used to indicate the list element type 
specified as the template parameter. 

The WCIterExcept class is a base class of the WCValSListIter<Type> and 
WCValDListIter<Type> classes and provides the exceptions member function. This member 
function controls the exceptions which can be thrown by the WCValSListIter<Type> and 
WCValDListIter<Type> objects. No exceptions are enabled unless they are set by the 
exceptions member function. 

Private Member Functions 

Some functionality supported by base classes of the iterator are not appropriate in the single linked list 
iterator classes. Setting those functions as private members in the derived class is the standard 
mechanism to prevent them from being invoked. The following member functions are declared in the 
single linked list iterator private interface: 

int operator —(); 
int operator -=( int ); 
int insert ( Type & ); 

Public Member Functions 

The following member functions are declared in the public interface: 

WCValSListlter(); 

WCValSListlter! WCValSList<Type> & ); 

-WCValSListlter() ; 

WCValDListlter() ; 

WCValDListlter( WCValDList<Type> & ); 

-WCValDListlter() ; 
int append( Type & ) ; 

WCValSList<Type> *WCValSListIter<Type>::container() const; 
WCValDList<Type> *WCValDListIter<Type>::container() const; 

Type current() const; 
void reset(); 

void WCValSListIter<Type>::reset( WCValSList<Type> & ); 
void WCValDListIter<Type>::reset( WCValDList<Type> & ); 

In the iterators for double linked lists only: 

int insert ( Type & ); 

Public Member Operators 

The following member operators are declared in the public interface: 

int operator () (); 
int operator ++(); 
int operator +=( int ); 
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WCValSListlter<Type>, WCValDListlter<Type> 


See Also: 


In the iterators for double linked lists only: 

int operator —(); 
int operator -=( int ); 

WCValSList::forAll, WCValDList: :forAll 

Sample Program Using Value List Iterators 


#include <wclistit.h> 
#include <iostream.h> 


// 

// insert elem after all elements in the list less than or equal to 
// elem 
// 

void insert_ in_ order ( WCValDList<int> &list, int elem ) { 

if( list.entries () == 0 ) { 

// cannot insert in an empty list using a iterator 
list.insert ( elem ); 

} else { 

WCValDListIter<int> iter( list ); 
while ( ++iter ) { 

if( iter.current() > elem ) { 

// insert elem before first element in list greater 

// than elem 

iter.insert( elem ); 

return; 



// iterated past the end of the list 
// append elem to the end of the list 
list.append( elem ); 



void main() { 

WCValDList<int> list; 

insert_ in_ order ( list, 5 ); 
insert_ in_ order ( list, 20 ); 
insert_ in_ order ( list, 1 ); 
insert_ in_ order ( list, 25 ); 

cout << "List elements in ascending order:\n"; 

WCValDListIter<int> iter( list ); 
while ( ++iter ) { 

cout << iter.current() << "\n"; 

} 


cout << "List elements in descending order\n"; 

// iterator is past the end of the list 
while( —iter ) { 

cout << iter.current() << "\n"; 

} 
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WCValSListlter<Type>::WCValSListlter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wclistit.h> 
public: 

WCValSListlter() ; 

The WCValSListlter public member function is the default constructor for the class and initializes 
the iterator with no list to operate on. The reset member function must be called to provide the 
iterator with a list to iterate over. 

The WCValSListlter public member function creates an initialized WCValSListlter object. 
WCValSListlter, ~WCValSListIter, reset 
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WCValSListlter<Type>::WCValSListlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

WCValSListlter( WCValSList<Type> & ); 

The WCValSListlter public member function is a constructor for the class. The value passed as a 
parameter is a WCValSList list object. The iterator will be initialized for that list object and 
positioned before the first list element. To position the iterator to a valid element within the list, 
increment it using any of the operator ++, operator (), or operator += operators. 

The WCValSListlter public member function creates an initialized WCValSListlter object 
positioned before the first element in the list. 

~WCValSListIter, operator (), operator ++, operator +=, reset 
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WCValSListlter<Type>::~WCValSListlter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wclistit.h> 
public: 

-WCValSListlter!) ; 

The -WCValSListlter public member function is the destructor for the class. The call to the 
-WCValSListlter public member function is inserted implicitly by the compiler at the point where 
the WCValSListlter object goes out of scope. 

The WCValSListlter object is destroyed. 

WCValSListlter 
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WC ValDListlter<Type>:: WC ValDListlterQ 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wclistit.h> 
public: 

WCValDListlter() ; 

The WCValDListlter public member function is the default constructor for the class and initializes 
the iterator with no list to operate on. The reset member function must be called to provide the 
iterator with a list to iterate over. 

The WCValDListlter public member function creates an initialized WCValDListlter object. 
WCValDListlter, ~WCValDListIter, reset 
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WCValDListlter<Type>::WCValDListlter() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

WCValDListlter( WCValDList<Type> & ); 

The WCValDListlter public member function is a constructor for the class. The value passed as a 
parameter is the WCValDList list object. The iterator will be initialized for that list object and 
positioned before the first list element. To position the iterator to a valid element within the list, 
increment it using any of the operator ++, operator (), or operator += operators. 

The WCValDListlter public member function creates an initialized WCValDListlter object 
positioned before the first list element. 

WCValDListlter, ~WCValDListIter, operator (), operator ++, operator +=, 
reset 
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WCValDListlter<Type>::~WCValDListlter() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <wclistit.h> 
public: 

-WCValDListlter() ; 

The -WCValDListlter public member function is the destructor for the class. The call to the 
-WCValDListlter public member function is inserted implicitly by the compiler at the point where 
the WCValDListlter object goes out of scope. 

The WCValDListlter object is destroyed. 

WCValDListlter 
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WCValSListlter<Type>::append(), WCValDListlter<Type>::append() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int append( Type & ) ; 

The append public member function inserts a new element into the list container object. The new 
element is inserted after the current iterator item. 

If the iterator is not associated with a list, or the iterator position is either before the first element or past 
the last element in the list, the current iterator position is undefined. The element is not appended. If 
the undef_ iter exception is enabled, it is thrown. 

If the append fails, the out_ of_ memory exception is thrown, if enabled in the list being iterated over. 
The list remains unchanged. 

The new element is inserted after the current iterator item. A TRUE value (non-zero) is returned if the 
append is successful. A FALSE (zero) result is returned if the append fails. 

insert, WCExcept: : out_ of_ memorytylCIterExcept: : undef_ iter 
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WCValSListlter<Type>,WCValDListlter<Type>::container() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

WCValSList<Type> *WCValSListIter<Type>::container() const; 
WCValDList<Type> *WCValDListIter<Type>::container() const; 

The container public member function returns a pointer to the list container object. If the iterator 
has not been initialized with a list object, and the undef_ iter exception is enabled, the exception is 
thrown. 

A pointer to the list object associated with the iterator is returned, or NULL(O) if the iterator has not 
been initialized with a list. 

WCValSListlter, WCValDListlter, reset,WCIterExcept: :undef_ iter 
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WCValSListlter<Type>::current(), WCValDListlter<Type>::current() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

Type current(); 

The current public member function returns the value of the list element at the current iterator 
position. 

If the iterator is not associated with a list, or the iterator position is either before the first element or past 
the last element in the list, the current iterator position is undefined. In this case the undef_ item 
exception is thrown, if enabled. 

The value at the current iterator element is returned. If the current element is undefined, a default 
initialized object is returned. 

operator (), operator ++, operator +=, operator —, operator -=, reset, 
WCIterExcept::undef_ item 
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WCValDListlter<Type>::insert() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wclistit.h> 
public: 

int insert( Type & ) ; 

The insert public member function inserts a new element into the list container object. The new 
element is inserted before the current iterator item. This process uses the previous link in the double 
linked list, so the insert public member function is not allowed with single linked lists. 

If the iterator is not associated with a list, or the iterator position is either before the first element or past 
the last element in the list, the current iterator position is undefined. The element is not inserted. If the 
undef_ iter exception is enabled, the exception is thrown. 

If the insert fails and the out_ of_ memory exception is enabled in the list being iterated over, the 
exception is thrown. The list remains unchanged. 

The new element is inserted before the current iterator item. A TRUE value (non-zero) is returned if the 
insert is successful. A FALSE (zero) result is returned if the insert fails. 

append, WCExcept: : out_ of_ memorytyJCIterExcept: : undef_ iter 
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WCValSListlter<Type>, WCValDListlter<Type>: -.operator ()() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int operator ()(); 

The operator () public member function is the call operator for the class. The list element which 
follows the current item is set to be the new current item. If the previous current item was the last 
element in the list, the iterator is positioned after the end of the list. 

The operator () public member function has the same semantics as the pre-increment operator, 
operator ++. 

If the iterator was positioned before the first element in the list, the current item will be set to the first 
element in the list. If the list is empty, the iterator will be positioned after the end of the list. 

If the iterator is not associated with a list or the iterator position before the increment was past the last 
element the list, the undef_ iter exception is thrown, if enabled. 

The operator () public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is incremented past the end of the list. 

operator ++, operator +=, operator —, operator -=, reset, 

WCIterExcept: :undef_ iter 
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WCValSListlter<Type>, WCValDListlter<Type>::operator ++() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int operator ++(); 

The operator ++ public member function is the pre-increment operator for the class. The list 
element which follows the current item is set to be the new current item. If the previous current item 
was the last element in the list, the iterator is positioned after the end of the list. 

The operator ++ public member function has the same semantics as the call operator, operator 
() - 

If the iterator was positioned before the first element in the list, the current item will be set to the first 
element in the list. If the list is empty, the iterator will be positioned after the end of the list. 

If the iterator is not associated with a list or the iterator position before the increment was past the last 
element the list, the undef_ iter exception is thrown, if enabled. 

The operator ++ public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is incremented past the end of the list. 

current, operator (), operator +=, operator —, operator -=, reset, 
WCIterExcept: :undef_ iter 
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WCValSListlter<Type>, WCValDListlter<Type>: -.operator +=() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int operator +=( int ) ; 

The operator += public member function accepts an integer value that causes the iterator to move 
that many elements after the current item. If the iterator was positioned before the first element in the 
list, the operation will set the current item to be the given element in the list. 

If the current item was after the last element in the list previous to the iteration, and the undef_ iter 
exception is enabled, the exception will be thrown. Attempting to increment the iterator position more 
than element after the end of the list, or by less than one element causes the iter_ range exception to 
be thrown, if enabled. 

The operator += public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is incremented past the end of the list. 

current,operator (), operator ++, operator —, operator -=, reset, 
WCIterExcept::iter_ range,WCIterExcept::undef_ iter 
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I/I !C ValDListlter<Type>::operator --() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int operator —(); 

The operator — public member function is the pre-decrement operator for the class. The list 
element previous to the current item is set to be the new current item. If the current item was the first 
element in the list, the iterator is positioned before the first element in the list. If the list is empty, the 
iterator will be positioned before the start of the list. 

If the iterator was positioned after the last element in the list, the current item will be set to the last 
element. 

If the iterator is not associated with a list or the iterator position previous to the decrement was before 
the first element the list, the undef_ iter exception is thrown, if enabled. 

The operator — public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is decremented past the first element of the list. 

current, operator (), operator ++, operator +=, operator -=, reset, 
WCIterExcept: :undef_ iter 
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WCValDListlter<Type>::operator-=() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wclistit.h> 
public: 

int operator -=( int ) ; 

The operator -= public member function accepts an integer value that causes the iterator to move 
that many elements before the current item. If the iterator was positioned after the last element in the 
list, the operation will set the current item to be the given number of elements from the end of the list. 

If the current item was before the first element in the list previous to the iteration, and the 
undef_ iter exception is enabled, the exception will be thrown. Attempting to decrement the iterator 
position more than one element before the beginning of the list, or by less than one element causes the 
iter_ range exception to be thrown, if enabled. 

The operator -= public member function returns a non-zero value if the iterator is positioned on a 
list item. Zero(O) is returned when the iterator is decremented past the first element in the list. 

current,operator (), operator ++, operator +=, operator —,reset, 
WCIterExcept::iter_ range,WCIterExcept::undef_ iter 
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WCValSListlter<Type>::reset(), WCValDListlter<Type>::reset() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclistit.h> 

public: 

void reset(); 

The reset public member function resets the iterator to the initial state, positioning the iterator before 
the first element in the associated list. 

The iterator is positioned before the first list element. 

WCValSListlter, WCValDListlter, container 
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WCValSListlter<Type>::reset(), WCValDListlter<Type>::reset() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wclistit.h> 
public: 

void WCValSListIter<Type>::reset( WCValSList<Type> & ); 
void WCValDListIter<Type>::reset( WCValDList<Type> & ); 

The reset public member function resets the iterator to operate on the specified list. The iterator is 
positioned before the first element in the list. 

The iterator is positioned before the first element of the specified list. 

WCValSListlter, WCValDListlter, container 
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14 Queue Container 


Queue containers maintain an ordered collection of data which is retrieved in the order in which the data 
was entered into the queue. The queue class is implemented as a templated class, allowing the use of any 
data type as the queue data. 

A second template parameter specifies the storage class used to implement the queue. The WCValSList, 
WCIsvSList and WCPtrSList classes are appropriate storage classes. 
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WCQueue<Type,FType> 


Declared: 


wcqueue.h 

The WCQueue<Type, FType> class is a templated class used to create objects which maintain data in 
a queue. 

In the description of each member function, the text Type is used to indicate the template parameter 
defining the type of the elements stored in the queue. The text FType is used to indicate the template 
parameter defining the storage class used to maintain the queue. 

For example, to create a queue of integers, the WCQueue<int,WCValSList<int> > class can be 
used. The WCQueue<int *, WCPtrSList<int> > class will create a queue of pointers to 
integers. To create an intrusive queue of objects of type isv_link (derived from the WCSLink class), the 
WCQueue< isv_link *, WCIsvSList< isv_link > > class can be used. 

The WCExcept class is a base class of the WCQueue<Type, FType> class and provides the 
exceptions member function. This member function controls the exceptions which can be thrown 
by the WCQueue<Type, FType> object. No exceptions are enabled unless they are set by the 
exceptions member function. 

Requirements of Type 

Type must provide any constructors and/or operators required by the FType class. 

Public Member Functions 

The following member functions are declared in the public interface: 

WCQueue (); 

WCQueue( void *(*) ( size_t ), void (*) ( void *, size_t ) ); 

-WCQueue(); 

void clear(); 

int entries() const; 

Type first () const; 

Type get (); 

int insert ( const Type & ); 
int isEmptyO const; 

Type last() const; 

Sample Program Using a Queue 


♦include <wcqueue.h> 
♦include <iostream.h> 


main() { 

WCQueue<int,WCValSList<int> > queue; 

queue.insert( 7 ); 
queue.insert( 8 ); 
queue.insert ( 9 ); 
queue.insert( 10 ); 

cout << "\nNumber of queue entries: " << queue.entries() << "\n"; 
cout « "First entry = [" « queue.first() « "]\n"; 
cout « "Last entry = [" « queue.last() « "]\n"; 
while ( !queue.isEmpty() ) { 

cout « queue.get() « "\n"; 

} ; 

cout.flush (); 
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WCQueue<Type,FType>::WCQueue() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcqueue.h> 
public: 

WCQueue (); 

The public WCQueue<Type, FType> constructor creates an empty WCQueue<Type, FType> 
object. The FType storage class constructor performs the initialization. 

The public WCQueue<Type, FType> constructor creates an initialized WCQueue<Type, FType> 
object. 

~WCQueue<Type,FType> 
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WCQueue<Type,FType>::WCQueue() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcqueue.h> 
public: 

WCQueue( void *(*allocator)( size_t ), 
void (*deallocator)( void *, size_t ) ); 

The public WCQueue<Type, FType> constructor creates an empty WCQueue<Type, FType> 
object. If FType is either the WCValSList or WCPtrSList class, then the allocator function is 
registered to perform all memory allocations of the queue elements, and the deallocator function to 
perform all freeing of the queue elements’ memory. The allocator and deallocator functions are 
ignored if FType is the WCIsvSList class. These functions provide the ability to control how the 
allocation and freeing of memory is performed, allowing for more efficient memory handling than the 
general purpose global operator new () and operator deleted can provide. Memory 
management optimizations may potentially be made through the allocator and deallocator functions, 
but are not recommended before managing memory is understood and determined to be worth while. 

The allocator function shall return a pointer to allocated memory of size at least the argument, or 
zero(O) if the allocation cannot be performed. Initialization of the memory returned is performed by the 
WCQueue<Type, FType> class. 

The WCQueue<Type, FType> class calls the deallocator function only on memory allocated by the 
allocator function. The deallocator shall free the memory pointed to by the first argument which is of 
size the second argument. The size passed to the deallocator function is guaranteed to be the same size 
passed to the allocator function when the memory was allocated. 

The allocator and deallocator functions may assume that for a list object instance, the allocator is 
always called with the same first argument (the size of the memory to be allocated). If FType is the 
WCValSList<Type> class, then the WCValSListltemSize ( Type ) macro returns the size of 
the elements which are allocated by the allocator function. Similarly, the WCPtrSList It emSize ( 
Type ) macro returns the size of WCPtrSList<Type> elements. 

The FType storage class constructor performs the initialization of the queue. 

The public WCQueue<Type, FType> constructor creates an initialized WCQueue<Type, FType> 
object and registers the allocator and deallocator functions. 

WCQueue<Type,FType>, ~WCQueue<Type,FType> 
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WCQueue<Type,FType>::~WCQueue() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wcqueue.h> 
public: 

virtual ~WCQueue() ; 

The public ~WCQueue<Type, FType> destructor destroys the WCQueue<Type, FType> object. 
The FType storage class destructor performs the destruction. The call to the public 
~WCQueue<Type, FType> destructor is inserted implicitly by the compiler at the point where the 
WCQueue<Type, FType> object goes out of scope. 

If the not_ empty exception is enabled, the exception is thrown if the queue is not empty of queue 
elements. 

The WCQueue<Type, FType> object is destroyed. 

WCQueue<Type,FType>, clear,WCExcept::not_ empty 
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WCQueue<Type,FType>::clear() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcqueue.h> 

public: 

void clear (); 

The clear public member function is used to clear the queue object and set it to the state of the object 
just after the initial construction. The queue object is not destroyed and re-created by this operator, so 
the object destructor is not invoked. The queue elements are not cleared by the queue class. However, 
the class used to maintain the queue, FType, may clear the items as part of the clear function for that 
class. If it does not clear the items, any queue items still in the list are lost unless pointed to by some 
pointer object in the program code. 

The clear public member function resets the queue object to the state of the object immediately after 
the initial construction. 

~WCQueue<Type,FType>, isEmpty 
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WCQueue<Type,FType>::entries() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcqueue.h> 
public: 

int entries () const; 

The entries public member function is used to determine the number of queue elements contained in 
the list object. 

The number of elements in the queue is returned. Zero(O) is returned if there are no queue elements, 
isEmpty 
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WCQueue<Type,FType>::first() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcqueue.h> 
public: 

Type first() const; 

The first public member function returns a queue element from the beginning of the queue object. 
The queue element is not removed from the queue. 

If the queue is empty, one of two exceptions can be thrown. If the empty_ container exception is 
enabled, then it will be thrown. Otherwise, the index_ range exception will be thrown, if enabled. 

The first queue element is returned. If there are no elements in the queue, the return value is determined 
by the find member function of the FType class. 

get, isEmpty, last, WCExcept: :empty_ container,WCExcept: :index_ range, 

FType::find 
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WCQueue<Type, FType>::get() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcqueue.h> 
public: 

Type get (); 

The get public member function returns the queue element which was first inserted into the queue 
object. The queue element is also removed from the queue. 

If the queue is empty, one of two exceptions can be thrown. If the empty_ container exception is 
enabled, then it will be thrown. Otherwise, the index_ range exception will be thrown, if enabled. 

The first element in the queue is removed and returned. If there are no elements in the queue, the return 
value is determined by the get member function of the FType class. 

first, insert, isEmpty, WCExcept: :empty_ container,WCExcept: : index_ range, 
FType::get 
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WCQueue<Type,FType>::insert() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcqueue.h> 
public: 

int insert( const Type & ) ; 

The insert public member function is used to insert the data into the queue. It will be the last 
element in the queue, and the last to be retrieved. 

If the insert fails, the out_ of_ memory exception will be thrown, if enabled. The queue will remain 
unchanged. 

The queue element is inserted at the end of the queue. A TRUE value (non-zero) is returned if the insert 
is successful. A FALSE (zero) result is returned if the insert fails. 

get, WCExcept: : out_ of_ memory 
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WCQueue<Type,FType>::isEmpty() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcqueue.h> 
public: 

int isEmptyO const; 

The is Empty public member function is used to determine if a queue object has any queue elements 
contained in it. 

A TRUE value (non-zero) is returned if the queue object does not have any queue elements contained 
within it. A FALSE (zero) result is returned if the queue contains at least one element. 

entries 
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WCQueue<Type,FType>::last() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcqueue.h> 
public: 

Type last() const; 

The last public member function returns a queue element from the end of the queue object. The 
queue element is not removed from the queue. 

If the queue is empty, one of two exceptions can be thrown. If the empty_ container exception is 
enabled, then it will be thrown. Otherwise, the index_ range exception will be thrown, if enabled. 

The last queue element is returned. If there are no elements in the queue, the return value is determined 
by the find member function of the FType class. 

first, get, isEmpty, WCExcept: :empty_ container,WCExcept: : index_ range, 
FType::find 
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15 Skip List Containers 


This chapter describes skip list containers. 
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WCPtrSkipListDict<Key, Value> 


Declared: 


wcskip.h 

The WCPtrSkipListDict<Key, Value> class is a templated class used to store objects in a 
dictionary. Dictionaries store values with an associated key, which may be of any type. One example 
of a dictionary used in everyday life is the phone book. The phone numbers are the data values, and the 
customer name is the key. The equality operator of the key’s type is used to locate the key-value pairs. 

In the description of each member function, the text Key is used to indicate the template parameter 
defining the type of the indices pointed to by the pointers stored in the dictionary. The text Value is 
used to indicate the template parameter defining the type of the data pointed to by the pointers stored in 
the dictionary. 

Note that pointers to the key values are stored in the dictionary. Destructors are not called on the keys 
pointed to. The key values pointed to in the dictionary should not be changed such that the equivalence 
to the old value is modified. 

The iterator classes for skip lists have the same function and operator interface as the hash iterators 
classes. See the chapter on hash iterators for more information. 

The WCExcept class is a base class of the WCPtrSkipListDict<Key, Value> class and provides 
the exceptions member function. This member function controls the exceptions which can be 
thrown by the WCPtrSkipListDict<Key, Value> object. No exceptions are enabled unless they 
are set by the exceptions member function. 

Requirements of Key 

The WCPtrSkipListDict<Key, Value> class requires Key to have: 

A well defined equivalence operator with constant parameters 
( int operator == ( const Key & ) const ). 

A well defined operator less than with constant parameters 
( int operator < ( const Key & ) const ). 

Public Member Functions 

The following member functions are declared in the public interface: 

WCPtrSkipListDict( unsigned = WCSkipListDict_ PROB_ QUARTER, unsigned = 
WCDEFAULT_ SKIPLIST_ MAX_ PTRS ) ; 

WCPtrSkipListDict( unsigned = WCSkipListDict_ PROB_ QUARTER, unsigned = 
WCDEFAULT_ SKIPLIST_ MAX_ PTRS, void * (*user_ alloc) ( size_ t size ), 

void (*user_ dealloc)( void *old, size_t size ) ); 

WCPtrSkipListDict ( const WCPtrSkipListDict & ); 

virtual ~WCPtrSkipListDict (); 

void clear (); 

void clearAndDestroy(); 

int contains ( const Key * ) const; 

unsigned entries() const; 

Value * find( const Key * ) const; 

Value * findKeyAndValue( const Key *, Key * & ) const; 
void forAll( void (*user_ fn) ( Key *, Value *, void * ), void * ); 
int insert! Key *, Value * ); 
int isEmptyO const; 

Value * remove( const Key * ); 
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WCPtrSkipListDict<Key, Value> 


Public Member Operators 

The following member operators are declared in the public interface: 

Value * & operator []( const Key * ); 

Value * const & operator []( const Key * ) const; 
WCPtrSkipListDict & operator =( const WCPtrSkipListDict & ); 
int operator ==( const WCPtrSkipListDict & ) const; 
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WCPtrSkipListDict<Key, Value>:: WCPtrSkipListDictQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcskip.h> 
public: 

WCPtrSkipListDict( unsigned = WCSKIPLIST_ PROB_ QUARTER, 
unsigned = WCDEFAULT_ SKIPLIST_ MAX_ PTRS ) ; 

The public WCPtrSkipListDict<Key, Value> constructor creates an 

WCPtrSkipListDict<Key, Value> object with no entries. The first optional parameter, which 
defaults to the constant WCSKIPLIST_ PROB_ QUARTER, determines the probability of having a 
certain number of pointers in each skip list node. The second optional parameter, which defaults to the 
constant WCDEFAULT_ SKIPLIST_ MAX_ PTRS, determines the maximum number of pointers that 
are allowed in any skip list node. WCDEFAULT_ SKIPLIST_ MAX_ PTRS is the maximum effective 
value of the second parameter. If an allocation failure occurs while creating the skip list, the 
out_ of_ memory exception is thrown if th©ut_ of_ memory exception is enabled. 

The public WCPtrSkipListDict<Key, Value> constructor creates an initialized 
WCPtrSkipListDict<Key, Value> object. 

~WCPtrSkipListDict<Key,Value>, WCExcept::out_ of_ memory 
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WCPtrSkipListDict<Key, Value>:: WCPtrSkipListDictQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcskip.h> 
public: 

WCPtrSkipListDict( unsigned = WCSKIPLIST_ PROB_ QUARTER, 

unsigned = WCDEFAULT_ SKIPLIST_ MAX_ PTRS, 

void * (*user_ alloc) ( size_ t ), 

void (*user_ dealloc) ( void *, size_ t ) ); 

Allocator and deallocator functions are specified for use when entries are inseited and removed from the 
list dictionary. The semantics of this constructor are the same as the constructor without the memory 
management functions. 

The allocation function must return a zero if it cannot perform the allocation. The deallocation function 
is passed the size as well as the pointer to the data. Your allocation system may take advantage of the 
characteristic that the allocation function will always be called with the same size value for any 
particular instantiation of a list dictionary. To determine the size of the objects that the memory 
management functions will be required to allocate and free, the following macro may be used: 
WCPtrSkipListDictltemSize( Key, Value, num_ of_ pointers ) 

The public WCPtrSkipListDict<Key, Value> constructor creates an initialized 
WCPtrSkipListDict<Key, Value> object. 

~WCPtrSkipListDict<Key,Value>, WCExcept::out_ of_ memory 
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WCPtrSkipListDict<Key, Value>:: WCPtrSkipListDictQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcskip.h> 
public: 

WCPtrSkipListDict( const WCPtrSkipListDict & ); 

The public WCPtrSkipListDict<Key, Value> constructor is the copy constructor for the 
WCPtrSkipListDict<Key, Value> class. The new skip list is created with the same probability 
and maximum pointers, all values or pointers stored in the list, and the exception trap states. If there is 
not enough memory to copy all of the values, then only some will be copied, and the number of entries 
will correctly reflect the number copied. If all of the elements cannot be copied, then the 
out_ of_ memory exception is thrown if it is enabled. 

The public WCPtrSkipListDict<Key, Value> constructor creates an 
WCPtrSkipListDict<Key, Value> object which is a copy of the passed dictionary. 

operator =, WCExcept: : out_ of_ memory 
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WCPtrSkipListDict<Key, Value>::~ WCPtrSkipListDictQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcskip.h> 
public: 

virtual ~WCPtrSkipListDict() ; 

The public ~WCPtrSkipListDict<Key, Value> destructor is the destructor for the 
WCPtrSkipListDict<Key, Value> class. If the number of dictionary elements is not zero and 
the not_ empty exception is enabled, the exception is thrown. Otherwise, the dictionary elements are 
cleared using the clear member function. The objects which the dictionary elements point to are not 
deleted unless the clearAndDestroy member function is explicitly called before the destructor is 
called. The call to the public ~WCPtrSkipListDict<Key, Value> destructor is inserted 
implicitly by the compiler at the point where the WCPtrSkipListDict<Key, Value> object goes 
out of scope. 

The public ~WCPtrSkipListDict<Key,Value> destructor destroys an 
WCPtrSkipListDict<Key, Value> object. 

clear, clearAndDestroy, WCExcept::not_ empty 
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WCPtrSkipListDict<Key,Value>::clear() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcskip.h> 

public: 

void clear(); 

The clear public member function is used to clear the dictionary so that it has no entries. Objects 
pointed to by the dictionary elements are not deleted. The dictionary object is not destroyed and 
re-created by this function, so the object destructor is not invoked. 

The clear public member function clears the dictionary to have no elements. 

~WCPtrSkipListDict<Key,Value>, clearAndDestroy, operator = 
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WCPtrSkipListDict<Key,Value>::clearAndDestroy() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcskip.h> 
public: 

void clearAndDestroy(); 

The clearAndDestroy public member function is used to clear the dictionary and delete the objects 
pointed to by the dictionary elements. The dictionary object is not destroyed and re-created by this 
function, so the dictionary object destructor is not invoked. 

The clearAndDestroy public member function clears the dictionary by deleting the objects pointed 
to by the dictionary elements. 

clear 
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WCPtrSkipListDict<Key,Value>::contains() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcskip.h> 
public: 

int contains( const Key * ) const; 

The contains public member function returns non-zero if an element with the specified key is stored 
in the dictionary, or zero if there is no equivalent element. Note that equivalence is based on the 
equivalence operator of the Key type. 

The contains public member function returns a non-zero value if the Key is found in the dictionary, 
find, findKeyAndValue 
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WCPtrSkipListDict<Key,Value>::entries() 


Synopsis: #include <wcskip.h> 

public: 

unsigned entries () const; 


Semantics: 

Results: 
See Also: 


The entries public member function is used to return the current number of elements stored in the 
dictionary. 

The entries public member function returns the number of elements in the dictionary, 
isEmpty 


Skip List Containers 435 




WCPtrSkipListDict<Key,Value>::find() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcskip.h> 
public: 

Value * find( const Key * ) const; 

The find public member function is used to find an element with an equivalent key in the dictionary. 
If an equivalent element is found, a pointer to the element Value is returned. Zero is returned if the 
element is not found. Note that equivalence is based on the equivalence operator of the Key type. 

The element equivalent to the passed key is located in the dictionary. 

findKeyAndValue 
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WCPtrSkipListDict<Key,Value>::findKeyAndValue() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcskip.h> 
public: 

Value * findKeyAndValue( const Key *, Key * & ) const; 

The findKeyAndValue public member function is used to find an element in the dictionary with an 
key equivalent to the first parameter. If an equivalent element is found, a pointer to the element Value 
is returned. The reference to a Key passed as the second parameter is assigned the found element’s key. 
Zero is returned if the element is not found. Note that equivalence is based on the equivalence operator 
of the Key type. 

The element equivalent to the passed key is located in the dictionary. 
findKeyAndValue 
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WCPtrSkipListDict<Key, Value>::forA ll() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wcskip.h> 
public: 
void forAll( 

void (*user_ fn) ( Key *, Value *, void * ), 
void * ); 

The forAll public member function causes the user supplied function to be invoked for every 
key-value pair in the dictionary. The user function has the prototype 

void user_ func ( Key * key. Value * value, void * data ); 

As the elements are visited, the user function is invoked with the Key and Value components of the 
element passed as the first two parameters. The second parameter of the forAll function is passed as 
the third parameter to the user function. This value can be used to pass any appropriate data from the 
main code to the user function. 

The elements in the dictionary are all visited, with the user function being invoked for each one. 
find, findKeyAndValue 
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WCPtrSkipListDict<Key,Value>::insert() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcskip.h> 
public: 

int insert( Key *, Value * ); 

The insert public member function inserts a key and value into the dictionary. If allocation of the 
node to store the key-value pair fails, then the out_ of_ memory exception is thrown if it is enabled. 
If the exception is not enabled, the insert will not be completed. 

The insert public member function inserts a key and value into the dictionary. If the insert is 
successful, a non-zero will returned. A zero will be returned if the insert fails. 

operator =, WCExcept::out_ of_ memory 
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WCPtrSkipListDict<Key,Value>::isEmpty() 


Synopsis: #include <wcskip.h> 

public: 

int isEmptyO const; 


Semantics: 

Results: 

See Also: 


The is Empty public member function is used to determine if the dictionary is empty. 

The is Empty public member function returns zero if it contains at least one entry, non-zero if the 
dictionary is empty. 

entries 
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WCPtrSkipListDict<Key, Value>: -.operator []() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcskip.h> 
public: 

Value * & operator[]( const Key * ); 

operator [ ] is the dictionary index operator. A reference to the object stored in the dictionary with 
the given Key is returned. If no equivalent element is found, then a new key-value pair is created with 
the specified Key value, and initialized with the default constructor. The returned reference can then be 
assigned to, so that insertions can be made with the operator. If an allocation error occurs while 
inserting a new key-value pair, then the out_ of_ memory exception is thrown if it is enabled. If the 
exception is not enabled, then a reference to address zero will be returned. This will result in a run-time 
error on systems which trap address zero references. 

The operator [ ] public member function returns a reference to the element at the given key value. 
If the key does not exist, a reference to a created element is returned. The result of the operator may be 
assigned to. 

WCExcept: : out_ of_ memory 
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WCPtrSkipListDict<Key, Value>::operator []() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcskip.h> 
public: 

Value * const & operator!] ( const Key * ) const; 

operator [] is the dictionary index operator. A constant reference to the object stored in the 
dictionary with the given Key is returned. If no equivalent element is found, then the index_ range 
exception is thrown if it is enabled. If the exception is not enabled, then a reference to address zero will 
be returned. This will result in a run-time error on systems which trap address zero references. 

The operator [ ] public member function returns a constant reference to the element at the given 
key value. The result of the operator may not be assigned to. 

WCExcept: : index_ range 
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WCPtrSkipListDict<Key, Value>::operator =() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcskip.h> 
public: 

WCPtrSkipListDict & operator =( const WCPtrSkipListDict & ); 

The operator = public member function is the assignment operator for the 

WCPtrSkipListDict<Key, Value> class. The left hand side dictionary is first cleared using the 
clear member function, and then the right hand side dictionary is copied. The new skip list is created 
with the same probability and maximum pointers, all values or pointers stored in the list, and the 
exception trap states. If there is not enough memory to copy all of the values or pointers in the 
dictionary, then only some will be copied, and the out_ of_ memory exception is thrown if it is 
enabled. The number of entries will correctly reflect the number copied. 

The operator = public member function assigns the left hand side dictionary to be a copy of the 
right hand side. 

clear, WCExcept: : out_ of_ memory 
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WCPtrSkipListDict<Key, Value>::operator ==() 


Synopsis: 


Semantics: 


Results: 


#include <wcskip.h> 
public: 

int operator ==( const WCPtrSkipListDict & ) const; 

The operator == public member function is the equivalence operator for the 
WCPtrSkipListDict<Key, Value> class. Two dictionary objects are equivalent if they are the 
same object and share the same address. 

A TRUE (non-zero) value is returned if the left hand side and right hand side dictionary are the same 
object. A FALSE (zero) value is returned otherwise. 
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WCPtrSkipListDict<Key,Value>::remove() 


Synopsis: 


Semantics: 


Results: 


♦include <wcskip.h> 
public: 

Value * remove( const Key * ) ; 

The remove public member function is used to remove the specified element from the dictionary. If 
an equivalent element is found, the pointer value is returned. Zero is returned if the element is not 
found. Note that equivalence is based on the equivalence operator of the Key type. 

The element is removed from the dictionary if it found. 
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WCPtrSkipList<Type>, WCPtrSkipListSet<Type> 


Declared: 


wcskip.h 

WCPtrSkipList<Type> and WCPtrSkipListSet<Type> classes are templated classes used to 
store objects in a skip list. A skip list is a probabilistic alternative to balanced trees, and provides a 
reasonable performance balance to insertion, search, and deletion. A skip list allows more than one 
copy of an element that is equivalent, while the skip list set allows only one copy. The equality operator 
of the element’s type is used to locate the value. 

In the description of each member function, the text Type is used to indicate the template parameter 
defining the type of the data pointed to by the pointers stored in the list. 

Note that pointers to the elements are stored in the list. Destructors are not called on the elements 
pointed to. The data values pointed to in the list should not be changed such that the equivalence to the 
old value is modified. 

The iterator classes for skip lists have the same function and operator interface as the hash iterators 
classes. See the chapter on hash iterators for more information. 

The WCExcept class is a base class of the WCPtrSkipList<Type> and 
WCPtrSkipListSet<Type> classes and provides the exceptions member function. This 
member function controls the exceptions which can be thrown by the WCPtrSkipList<Type> and 
WCPtrSkipListSet<Type> objects. No exceptions are enabled unless they are set by the 
exceptions member function. 

Requirements of Type 

The WCPtrSkipList<Type> and WCPtrSkipListSet<Type> classes requires Type to have: 

A well defined equivalence operator 
( int operator == ( const Type & ) const ). 

A well defined less than operator 

( int operator < ( const Type & ) const ). 

Public Member Functions 

The following member functions are declared in the public interface: 

WCPtrSkipList( unsigned = WCSKIPLIST_ PROB_ QUARTER, unsigned = 
WCDEFAULT_ SKIPLIST_ MAX_ PTRS ) ; 

WCPtrSkipList( unsigned = WCSKIPLIST_ PROB_ QUARTER, unsigned = 
WCDEFAULT_ SKIPLIST_ MAX_ PTRS, void * (*user_ alloc) ( size_ t size ), 

void (*user_ dealloc)( void *old, size_t size ) ); 

WCPtrSkipList( const WCPtrSkipList & ); 
virtual -WCPtrSkipList (); 

WCPtrSkipListSet( unsigned = WCSKIPLIST_ PROB_ QUARTER, unsigned = 
WCDEFAULT_ SKIPLIST_ MAX_ PTRS ) ; 

WCPtrSkipListSet( unsigned = WCSKIPLIST_ PROB_ QUARTER, unsigned = 
WCDEFAULT_ SKIPLIST_ MAX_ PTRS, void * (*user_ alloc) ( size_ t size ), 

void (*user_ dealloc)( void *old, size_t size ) ); 

WCPtrSkipListSet ( const WCPtrSkipListSet & ); 

virtual -WCPtrSkipListSet (); 

void clear (); 

void clearAndDestroy(); 

int contains ( const Type * ) const; 


446 Skip List Containers 




WCPtrSkipList<Type>, WCPtrSkipListSet<Type> 


unsigned entries () const; 

Type * find( const Type * ) const; 

void forAll( void (*user_ fn) ( Type *, void * ) , void * ); 

int insert ( Type * ); 
int isEmptyO const; 

Type * remove( const Type * ); 

The following public member functions are available for the WCPtrSkipList class only: 

unsigned occurrencesOf( const Type * ) const; 
unsigned removeAll( const Type * ); 

Public Member Operators 

The following member operators are declared in the public interface: 

WCPtrSkipList & operator =( const WCPtrSkipList & ); 
int operator ==( const WCPtrSkipList & ) const; 
WCPtrSkipListSet & operator =( const WCPtrSkipListSet & ); 
int operator ==( const WCPtrSkipListSet & ) const; 
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WCPtrSkipListSet<Type>::WCPtrSkipListSet() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <wcskip.h> 
public: 

WCPtrSkipListSet( unsigned = WCSKIPLIST_ PROB_ QUARTER, 
unsigned = WCDEFAULT_ SKIPLIST_ MAX_ PTRS ) ; 

The WCPtrSkipListSet<Type> constructor creates a WCPtrSkipListSet object with no 
entries. The first optional parameter, which defaults to the constant WCSKIPLIST_ PROB_ QUARTER, 
determines the probability of having a certain number of pointers in each skip list node. The second 
optional parameter, which defaults to the constant WCDEFAULT_ SKIPLIST_ MAX_ PTRS, determines 
the maximum number of pointers that are allowed in any skip list node. 

WCDEFAULT_ SKIPLIST_ MAX_ PTRS is the maximum effective value of the second parameter. If an 
allocation failure occurs while creating the skip list, the out_ of_ memory exception is thrown if the 
out_ of_ memory exception is enabled. 

The WCPtrSkipListSet<Type> constructor creates an initialized WCPtrSkipListSet object. 
~WCPtrSkipList<Type>, WCExcept::out_ of_ memory 


448 Skip List Containers 



WCPtrSkipListSet<Type>::WCPtrSkipListSet() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <wcskip.h> 
public: 

WCPtrSkipListSet( unsigned = WCSKIPLIST_ PROB_ QUARTER, 

unsigned = WCDEFAULT_ SKIPLIST_ MAX_ PTRS, 

void * (*user_ alloc) ( size_ t ), 

void (*user_ dealloc) ( void *, size_ t ) ); 

Allocator and deallocator functions are specified for use when entries are inseited and removed from the 
list. The semantics of this constructor are the same as the constructor without the memory management 
functions. 

The allocation function must return a zero if it cannot perform the allocation. The deallocation function 
is passed the size as well as the pointer to the data. Your allocation system may take advantage of the 
characteristic that the allocation function will always be called with the same size value for any 
particular instantiation of a skip list. To determine the size of the objects that the memory management 
functions will be required to allocate and free, the following macro may be used: 
WCPtrSkipListSetltemSize( Type, num_ of_ pointers ) 

The WCPtrSkipListSet<Type> constructor creates an initialized WCPtrSkipListSet object. 
~WCPtrSkipList<Type>, WCExcept::out_ of_ memory 


Skip List Containers 449 




WCPtrSkipListSet<Type>::WCPtrSkipListSet() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcskip.h> 
public: 

WCPtrSkipListSet ( const WCPtrSkipListSet & ); 

The WCPtrSkipListSet<Type> constructor is the copy constructor for the 
WCPtrSkipListSet class. The new skip list is created with the same probability and maximum 
pointers, all values or pointers stored in the list, and the exception trap states. If there is not enough 
memory to copy all of the values, then only some will be copied, and the number of entries will 
correctly reflect the number copied. If all of the elements cannot be copied, then the 
out_ of_ memory exception is thrown if it is enabled. 

The WCPtrSkipListSet<Type> constructor creates a WCPtrSkipListSet object which is a 
copy of the passed list. 

operator =, WCExcept: : out_ of_ memory 
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WCPtrSkipListSet<Type>::~WCPtrSkipListSet() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wcskip.h> 
public: 

virtual ~WCPtrSkipListSet() ; 

The WCPtrSkipListSet<Type> destructor is the destructor for the WCPtrSkipListSet class. 
If the number of elements is not zero and the not_ empty exception is enabled, the exception is 
thrown. Otherwise, the list elements are cleared using the clear member function. The objects which 
the list elements point to are not deleted unless the clearAndDestroy member function is explicitly 
called before the destructor is called. The call to the WCPtrSkipListSet<Type> destructor is 
inserted implicitly by the compiler at the point where the WCPtrSkipListSet object goes out of 
scope. 

The call to the WCPtrSkipListSet<Type> destructor destroys a WCPtrSkipListSet object, 
clear, clearAndDestroy, WCExcept::not_ empty 
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WCPtrSkipList<Type>::WCPtrSkipList() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <wcskip.h> 
public: 

WCPtrSkipList( unsigned = WCSKIPLIST_ PROB_ QUARTER, 
unsigned = WCDEFAULT_ SKIPLIST_ MAX_ PTRS ) ; 

The WCPtrSkipList<Type> constructor creates a WCPtrSkipList object with no entries. The 
first optional parameter, which defaults to the constant WCSKIPLIST_ PROB_ QUARTER, determines 
the probability of having a certain number of pointers in each skip list node. The second optional 
parameter, which defaults to the constant WCDEFAULT_ SKIPLIST_ MAX_ PTRS, determines the 
maximum number of pointers that are allowed in any skip list node. 

WCDEFAULT_ SKIPLIST_ MAX_ PTRS is the maximum effective value of the second parameter. If an 
allocation failure occurs while creating the skip list, the out_ of_ memory exception is thrown if the 
out_ of_ memory exception is enabled. 

The WCPtrSkipList<Type> constructor creates an initialized WCPtrSkipList object. 
~WCPtrSkipList<Type>, WCExcept::out_ of_ memory 
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WCPtrSkipList<Type>::WCPtrSkipList() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <wcskip.h> 
public: 

WCPtrSkipList( unsigned = WCSKIPLIST_ PROB_ QUARTER, 

unsigned = WCDEFAULT_ SKIPLIST_ MAX_ PTRS, 

void * (*user_ alloc) ( size_ t ), 

void (*user_ dealloc) ( void *, size_ t ) ); 

Allocator and deallocator functions are specified for use when entries are inseited and removed from the 
list. The semantics of this constructor are the same as the constructor without the memory management 
functions. 

The allocation function must return a zero if it cannot perform the allocation. The deallocation function 
is passed the size as well as the pointer to the data. Your allocation system may take advantage of the 
characteristic that the allocation function will always be called with the same size value for any 
particular instantiation of a skip list. To determine the size of the objects that the memory management 
functions will be required to allocate and free, the following macro may be used: 
WCPtrSkipListltemSize( Type, num_ of_ pointers ) 

The WCPtrSkipList<Type> constructor creates an initialized WCPtrSkipList object. 
~WCPtrSkipList<Type>, WCExcept::out_ of_ memory 
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WCPtrSkipList<Type>::WCPtrSkipList() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcskip.h> 
public: 

WCPtrSkipList( const WCPtrSkipList & ); 

The WCPtrSkipList<Type> constructor is the copy constructor for the WCPtrSkipList class. 
The new skip list is created with the same probability and maximum pointers, all values or pointers 
stored in the list, and the exception trap states. If there is not enough memory to copy all of the values, 
then only some will be copied, and the number of entries will correctly reflect the number copied. If all 
of the elements cannot be copied, then the out_ of_ memory exception is thrown if it is enabled. 

The WCPtrSkipList<Type> constructor creates a WCPtrSkipList object which is a copy of the 
passed list. 

operator =, WCExcept::out_ of_ memory 
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WCPtrSkipList<Type>::~WCPtrSkipList() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wcskip.h> 
public: 

virtual ~WCPtrSkipList() ; 

The WCPtrSkipList<Type> destructor is the destructor for the WCPtrSkipList class. If the 
number of elements is not zero and the not_ empty exception is enabled, the exception is thrown. 
Otherwise, the list elements are cleared using the clear member function. The objects which the list 
elements point to are not deleted unless the clearAndDestroy member function is explicitly called 
before the destructor is called. The call to the WCPtrSkipList<Type> destructor is inserted 
implicitly by the compiler at the point where the WCPtrSkipList object goes out of scope. 

The call to the WCPtrSkipList<Type> destructor destroys a WCPtrSkipList object. 

clear, clearAndDestroy, WCExcept::not_ empty 
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WCPtrSkipList<Type>::clear(), WCPtrSkipListSet<Type>::clear() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcskip.h> 

public: 

void clear(); 

The clear public member function is used to clear the list so that it has no entries. Objects pointed to 
by the list elements are not deleted. The list object is not destroyed and re-created by this function, so 
the object destructor is not invoked. 

The clear public member function clears the list to have no elements. 

~WCPtrSkipList<Type>, clearAndDestroy, operator = 
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WCPtrSkipList<Type>,WCPtrSkipListSet<Type>::clearAndDestroy() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcskip.h> 
public: 

void clearAndDestroy(); 

The clearAndDestroy public member function is used to clear the list and delete the objects 
pointed to by the list elements. The list object is not destroyed and re-created by this function, so the 
list object destructor is not invoked. 

The clearAndDestroy public member function clears the list by deleting the objects pointed to by 
the list elements, and then removing the list elements from the list. 

clear 
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WCPtrSkipList<Type>::contains(), WCPtrSkipListSet<Type>::contains() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcskip.h> 
public: 

int contains( const Type * ) const; 

The contains public member function returns non-zero if the element is stored in the list, or zero if 
there is no equivalent element. Note that equivalence is based on the equivalence operator of the 
element type. 

The contains public member function returns a non-zero value if the element is found in the list, 
find 
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WCPtrSkipList<Type>::entries(), WCPtrSkipListSet<Type>::entries() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcskip.h> 
public: 

unsigned entries() const; 

The entries public member function is used to return the current number of elements stored in the 
list. 

The entries public member function returns the number of elements in the list, 
isEmpty 
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WCPtrSkipList<Type>::find(), WCPtrSkipListSet<Type>::find() 


Synopsis: 


Semantics: 


Results: 


#include <wcskip.h> 
public: 

Type * find( const Type * ) const; 

The find public member function is used to find an element with an equivalent value in the list. If an 
equivalent element is found, a pointer to the element is returned. Zero is returned if the element is not 
found. Note that equivalence is based on the equivalence operator of the element type. 

The element equivalent to the passed value is located in the list. 
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WCPtrSkipList<Type>::forA ll(), WCPtrSkipListSet<Type>::forA ll() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wcskip.h> 
public: 
void forAll( 

void (*user_ fn) ( Type *, void * ), 
void * ); 

The forAll public member function causes the user supplied function to be invoked for every value in 
the list. The user function has the prototype 


void user_ func( Type * value, void * data ); 

As the elements are visited, the user function is invoked with the element passed as the first. The 
second parameter of the forAll function is passed as the second parameter to the user function. This 
value can be used to pass any appropriate data from the main code to the user function. 

The elements in the list are all visited, with the user function being invoked for each one. 

find 
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WCPtrSkipList<Type>::insert(), WCPtrSkipListSet<Type>::insert() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcskip.h> 
public: 

int insert( Type * ) ; 

The insert public member function inserts a value into the list. If allocation of the node to store the 
value fails, then the out_ of_ memory exception is thrown if it is enabled. If the exception is not 
enabled, the insert will not be completed. 

With a WCPtrSkipListSet, there must be only one equivalent element in the set. If an element 
equivalent to the inserted element is already in the list set, the list set will remain unchanged, and the 
not_ unique exception is thrown if it is enabled. If the exception is not enabled, the insert will not be 
completed. 

The insert public member function inserts a value into the list. If the insert is successful, a non-zero 
will returned. A zero will be returned if the insert fails. 

operator =, WCExcept: : out_ of_ memoryfyJCExcept: : not_ unique 
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WCPtrSkipList<Type>::isEmpty(), WCPtrSkipListSet<Type>::isEmpty() 


Synopsis: #include <wcskip.h> 

public: 

int isEmptyO const; 


Semantics: 

Results: 

See Also: 


The is Empty public member function is used to determine if the list is empty. 

The is Empty public member function returns zero if it contains at least one entry, non-zero if the list 
is empty. 

entries 
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WCPtrSkipList<Type>::occurrencesOf() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcskip.h> 
public: 

unsigned occurrencesOf( const Type * ) const; 

The occurrencesOf public member function is used to return the current number of elements stored 
in the list which are equivalent to the passed value. Note that equivalence is based on the equivalence 
operator of the element type. 

The occurrencesOf public member function returns the number of elements in the list which are 
equivalent to the passed value. 

entries, find, isEmpty 
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WCPtrSkipList<Type>::operator =(), WCPtrSkipListSet<Type>::operator =() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcskip.h> 
public: 

WCPtrSkipList & operator =( const WCPtrSkipList & ); 

WCPtrSkipListSet & operator =( const WCPtrSkipListSet & ); 

The operator = public member function is the assignment operator for the 

WCPtrSkipList<Type> and WCPtrSkipListSet<Type> classes. The left hand side list is first 
cleared using the clear member function, and then the right hand side list is copied. The list function, 
exception trap states, and all of the list elements are copied. If there is not enough memory to copy all 
of the values or pointers in the list, then only some will be copied, and the out_ of_ memory exception 
is thrown if it is enabled. The number of entries will correctly reflect the number copied. 

The operator = public member function assigns the left hand side list to be a copy of the right hand 
side. 

clear, WCExcept: : out_ of_ memory 
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WCPtrSkipList<Type>::operator ==(), WCPtrSkipListSet<Type>::operator ==() 


Synopsis: 


Semantics: 


Results: 


#include <wcskip.h> 
public: 

int operator ==( const WCPtrSkipList & ) const; 
int operator ==( const WCPtrSkipListSet & ) const; 

The operator == public member function is the equivalence operator for the 
WCPtrSkipList<Type> and WCPtrSkipListSet<Type> classes. Two list objects are 
equivalent if they are the same object and share the same address. 

A TRUE (non-zero) value is returned if the left hand side and right hand side list are the same object. A 
FALSE (zero) value is returned otherwise. 
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WCPtrSkipList<Type>::remove(), WCPtrSkipListSet<Type>::remove() 


Synopsis: 


Semantics: 


Results: 


#include <wcskip.h> 
public: 

Type * remove( const Type * ) ; 

The remove public member function is used to remove the specified element from the list. If an 
equivalent element is found, the pointer value is returned. Zero is returned if the element is not found. 
If the list is a WCPtrSkipList and there is more than one element equivalent to the specified 
element, then the last equivalent element added to the WCPtrSkipList is removed. Note that 
equivalence is based on the equivalence operator of the element type. 

The element is removed from the list. 
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WCPtrSkipList<Type>::removeAII() 


Synopsis: 


Semantics: 


Results: 


#include <wcskip.h> 
public: 

unsigned removeAll( const Type * ); 

The removeAll public member function is used to remove all elements equivalent to the specified 
element from the list. Zero is returned if no equivalent elements are found. Note that equivalence is 
based on the equivalence operator of the element type. 

All equivalent elements are removed from the list. 
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WCValSkipListDict<Key, Value> 


Declared: 


wcskip.h 

The WCValSkipListDict<Key, Value> class is a templated class used to store objects in a 
dictionary. Dictionaries store values with an associated key, which may be of any type. One example 
of a dictionary used in everyday life is the phone book. The phone numbers are the data values, and the 
customer name is the key. The equality operator of the key’s type is used to locate the key-value pairs. 

In the description of each member function, the text Key is used to indicate the template parameter 
defining the type of the indices used to store data in the dictionary. The text Value is used to indicate 
the template parameter defining the type of the data stored in the dictionary. 

Values are copied into the dictionary, which could be undesirable if the stored objects are complicated 
and copying is expensive. Value dictionaries should not be used to store objects of a base class if any 
derived types of different sizes would be stored in the dictionary, or if the destructor for a derived class 
must be called. 

The iterator classes for skip lists have the same function and operator interface as the hash iterators 
classes. See the chapter on hash iterators for more information. 

The WCExcept class is a base class of the WCValSkipListDict<Key, Value> class and provides 
the exceptions member function. This member function controls the exceptions which can be 
thrown by the WCValSkipListDict<Key, Value> object. No exceptions are enabled unless they 
are set by the exceptions member function. 

Requirements of Key and Value 

The WCValSkipListDict<Key, Value> class requires Key to have: 

A default constructor ( Key: : Key () ). 

A well defined copy constructor ( Key:: Key ( const Key & ) ). 

A well defined assignment operator ( Key & operator =( const Key & ) ). 

A well defined equivalence operator with constant parameters 
( int operator == ( const Key & ) const ). 

A well defined operator less than with constant parameters 
( int operator < ( const Key & ) const ). 

The WCValSkipListDict<Key, Value> class requires Value to have: 

A default constructor ( Value : : Value () ). 

A well defined copy constructor ( Value :: Value ( const Value & ) ). 

A well defined assignment operator ( Value & operator =( const Value & ) ). 

Public Member Functions 

The following member functions are declared in the public interface: 

WCValSkipListDict( unsigned = WCSkipListDict_ PROB_ QUARTER, unsigned = 
WCDEFAULT_ SKIPLIST_ MAX_ PTRS ) ; 
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WCValSkipListDict<Key, Value> 


WCValSkipListDict( unsigned = WCSkipListDict_ PROB_ QUARTER, unsigned = 
WCDEFAULT_ SKIPLIST_ MAX_ PTRS, void * (*user_ alloc) ( size_ t size ), 

void (*user_ dealloc)( void *old, size_t size ) ); 

WCValSkipListDict ( const WCValSkipListDict & ); 
virtual ~WCValSkipListDict (); 
void clear (); 

int contains ( const Key & ) const; 

unsigned entries() const; 

int find( const Key &, Value & ) const; 

int findKeyAndValue( const Key &, Key &, Value & ) const; 

void forAll( void (*user_fn) ( Key, Value, void * ), void * ); 

int insert ( const Key &, const Value & ); 

int isEmptyO const; 

int remove( const Key & ); 

Public Member Operators 

The following member operators are declared in the public interface: 

Value & operator []( const Key & ); 

const Value & operator []( const Key & ) const; 

WCValSkipListDict & operator =( const WCValSkipListDict & ); 
int operator ==( const WCValSkipListDict & ) const; 
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WCValSkipListDict<Key, Value>:: WCValSkipListDictQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcskip.h> 
public: 

WCValSkipListDict( unsigned = WCSKIPLIST_ PROB_ QUARTER, 
unsigned = WCDEFAULT_ SKIPLIST_ MAX_ PTRS ) ; 

The public WCValSkipListDict<Key, Value> constructor creates an 

WCValSkipListDict<Key, Value> object with no entries. The first optional parameter, which 
defaults to the constant WCSKIPLIST_ PROB_ QUARTER, determines the probability of having a 
certain number of pointers in each skip list node. The second optional parameter, which defaults to the 
constant WCDEFAULT_ SKIPLIST_ MAX_ PTRS, determines the maximum number of pointers that 
are allowed in any skip list node. WCDEFAULT_ SKIPLIST_ MAX_ PTRS is the maximum effective 
value of the second parameter. If an allocation failure occurs while creating the skip list, the 
out_ of_ memory exception is thrown if th©ut_ of_ memory exception is enabled. 

The public WCValSkipListDict<Key, Value> constructor creates an initialized 
WCValSkipListDict<Key, Value> object. 

~WCValSkipListDict<Key, Value>, WCExcept::out_ of_ memory 
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WCValSkipListDict<Key, Value>:: WCVaiSkipListDictQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcskip.h> 
public: 

WCValSkipListDict( unsigned = WCSKIPLIST_ PROB_ QUARTER, 

unsigned = WCDEFAULT_ SKIPLIST_ MAX_ PTRS, 

void * (*user_ alloc) ( size_ t ), 

void (*user_ dealloc) ( void *, size_ t ) ); 

Allocator and deallocator functions are specified for use when entries are inseited and removed from the 
list dictionary. The semantics of this constructor are the same as the constructor without the memory 
management functions. 

The allocation function must return a zero if it cannot perform the allocation. The deallocation function 
is passed the size as well as the pointer to the data. Your allocation system may take advantage of the 
characteristic that the allocation function will always be called with the same size value for any 
particular instantiation of a list dictionary. To determine the size of the objects that the memory 
management functions will be required to allocate and free, the following macro may be used: 
WCValSkipListDictltemSize( Key, Value, num_ of_ pointers ) 

The public WCValSkipListDict<Key, Value> constructor creates an initialized 
WCValSkipListDict<Key, Value> object. 

~WCValSkipListDict<Key,Value>, WCExcept::out_ of_ memory 
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WCValSkipListDict<Key, Value>:: WCValSkipListDictQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcskip.h> 
public: 

WCValSkipListDict( const WCValSkipListDict & ); 

The public WCValSkipListDict<Key, Value> constructor is the copy constructor for the 
WCValSkipListDict<Key, Value> class. The new skip list is created with the same probability 
and maximum pointers, all values or pointers stored in the list, and the exception trap states. If there is 
not enough memory to copy all of the values, then only some will be copied, and the number of entries 
will correctly reflect the number copied. If all of the elements cannot be copied, then the 
out_ of_ memory exception is thrown if it is enabled. 

The public WCValSkipListDict<Key, Value> constructor creates an 
WCValSkipListDict<Key, Value> object which is a copy of the passed dictionary. 

operator =, WCExcept: : out_ of_ memory 
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WCValSkipListDict<Key, Value>::~ WCValSkipListDictQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcskip.h> 
public: 

virtual ~WCValSkipListDict() ; 

The public ~WCValSkipListDict<Key, Value> destructor is the destructor for the 
WCValSkipListDict<Key, Value> class. If the number of dictionary elements is not zero and 
the not_ empty exception is enabled, the exception is thrown. Otherwise, the dictionary elements are 
cleared using the clear member function. The call to the public 

~WCValSkipListDict<Key, Value> destructor is inserted implicitly by the compiler at the point 
where the WCValSkipListDict<Key, Value> object goes out of scope. 

The public ~WCValSkipListDict<Key, Value> destructor destroys an 
WCValSkipListDict<Key, Value> object. 

clear, WCExcept: : not_ empty 
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WCValSkipListDict<Key,Value>::clear() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcskip.h> 

public: 

void clear(); 

The clear public member function is used to clear the dictionary so that it has no entries. Elements 
stored in the dictionary are destroyed using the destructors of Key and of Value . The dictionary 
object is not destroyed and re-created by this function, so the object destructor is not invoked. 

The clear public member function clears the dictionary to have no elements. 

~WCValSkipListDict<Key,Value>, operator = 
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WCValSkipListDict<Key,Value>::contains() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcskip.h> 
public: 

int contains( const Key & ) const; 

The contains public member function returns non-zero if an element with the specified key is stored 
in the dictionary, or zero if there is no equivalent element. Note that equivalence is based on the 
equivalence operator of the Key type. 

The contains public member function returns a non-zero value if the Key is found in the dictionary, 
find, findKeyAndValue 
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I/I !C ValSkipListDict<Key, Value>::entries() 


Synopsis: #include <wcskip.h> 

public: 

unsigned entries () const; 


Semantics: 

Results: 
See Also: 


The entries public member function is used to return the current number of elements stored in the 
dictionary. 

The entries public member function returns the number of elements in the dictionary, 
isEmpty 
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WCValSkipListDict<Key,Value>::find() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcskip.h> 
public: 

int find( const Key &, Value & ) const; 

The find public member function is used to find an element with an equivalent key in the dictionary. 

If an equivalent element is found, a non-zero value is returned. The reference to a Value passed as the 
second argument is assigned the found element’s Value . Zero is returned if the element is not found. 
Note that equivalence is based on the equivalence operator of the Key type. 

The element equivalent to the passed key is located in the dictionary. 

findKeyAndValue 
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WCValSkipListDict<Key,Value>::findKeyAndValue() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wcskip.h> 
public: 

int findKeyAndValue( const Key &, 

Key &, Value & ) const; 

The findKeyAndValue public member function is used to find an element in the dictionary with an 
key equivalent to the first parameter. If an equivalent element is found, a non-zero value is returned. 
The reference to a Key passed as the second parameter is assigned the found element's key. The 
reference to a Value passed as the third argument is assigned the found element’s Value . Zero is 
returned if the element is not found. Note that equivalence is based on the equivalence operator of the 
Key type. 

The element equivalent to the passed key is located in the dictionary. 
findKeyAndValue 
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WCValSkipListDict<Key,Value>::forAII() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wcskip.h> 
public: 
void forAll( 

void (*user_ fn) ( Key, Value, void * ), 
void * ); 

The forAll public member function causes the user supplied function to be invoked for every 
key-value pair in the dictionary. The user function has the prototype 

void user_ func ( Key key. Value value, void * data ) ; 

As the elements are visited, the user function is invoked with the Key and Value components of the 
element passed as the first two parameters. The second parameter of the forAll function is passed as 
the third parameter to the user function. This value can be used to pass any appropriate data from the 
main code to the user function. 

The elements in the dictionary are all visited, with the user function being invoked for each one. 
find, findKeyAndValue 
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WC ValSkipListDict<Key, Value>::insert() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcskip.h> 
public: 

int insert ( const Key &, const Value & ); 

The insert public member function inserts a key and value into the dictionary. If allocation of the 
node to store the key-value pair fails, then the out_ of_ memory exception is thrown if it is enabled. 
If the exception is not enabled, the insert will not be completed. 

The insert public member function inserts a key and value into the dictionary. If the insert is 
successful, a non-zero will returned. A zero will be returned if the insert fails. 

operator =, WCExcept::out_ of_ memory 
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WCValSkipListDict<Key,Value>::isEmpty() 


Synopsis: #include <wcskip.h> 

public: 

int isEmptyO const; 


Semantics: 

Results: 

See Also: 


The is Empty public member function is used to determine if the dictionary is empty. 

The is Empty public member function returns zero if it contains at least one entry, non-zero if the 
dictionary is empty. 

entries 
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WCValSkipListDict<Key, Value>::operator []() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcskip.h> 
public: 

Value & operator[]( const Key & ); 

operator [ ] is the dictionary index operator. A reference to the object stored in the dictionary with 
the given Key is returned. If no equivalent element is found, then a new key-value pair is created with 
the specified Key value, and initialized with the default constructor. The returned reference can then be 
assigned to, so that insertions can be made with the operator. If an allocation error occurs while 
inserting a new key-value pair, then the out_ of_ memory exception is thrown if it is enabled. If the 
exception is not enabled, then a reference to address zero will be returned. This will result in a run-time 
error on systems which trap address zero references. 

The operator [ ] public member function returns a reference to the element at the given key value. 
If the key does not exist, a reference to a created element is returned. The result of the operator may be 
assigned to. 

WCExcept: : out_ of_ memory 
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WCValSkipListDict<Key, Value>::operator []() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcskip.h> 
public: 

const Value & operator[]( const Key & ) const; 

operator [] is the dictionary index operator. A constant reference to the object stored in the 
dictionary with the given Key is returned. If no equivalent element is found, then the index_ range 
exception is thrown if it is enabled. If the exception is not enabled, then a reference to address zero will 
be returned. This will result in a run-time error on systems which trap address zero references. 

The operator [ ] public member function returns a constant reference to the element at the given 
key value. The result of the operator may not be assigned to. 

WCExcept: : index_ range 
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WCValSkipListDict<Key, Value>::operator =() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcskip.h> 
public: 

WCValSkipListDict & operator =( const WCValSkipListDict & ); 

The operator = public member function is the assignment operator for the 

WCValSkipListDict<Key, Value> class. The left hand side dictionary is first cleared using the 
clear member function, and then the right hand side dictionary is copied. The new skip list is created 
with the same probability and maximum pointers, all values or pointers stored in the list, and the 
exception trap states. If there is not enough memory to copy all of the values or pointers in the 
dictionary, then only some will be copied, and the out_ of_ memory exception is thrown if it is 
enabled. The number of entries will correctly reflect the number copied. 

The operator = public member function assigns the left hand side dictionary to be a copy of the 
right hand side. 

clear, WCExcept: : out_ of_ memory 
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WCValSkipListDict<Key, Value>::operator ==() 


Synopsis: 


Semantics: 


Results: 


#include <wcskip.h> 
public: 

int operator ==( const WCValSkipListDict & ) const; 

The operator == public member function is the equivalence operator for the 
WCValSkipListDict<Key, Value> class. Two dictionary objects are equivalent if they are the 
same object and share the same address. 

A TRUE (non-zero) value is returned if the left hand side and right hand side dictionary are the same 
object. A FALSE (zero) value is returned otherwise. 
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WCValSkipListDict<Key,Value>::remove() 


Synopsis: 


Semantics: 


Results: 


#include <wcskip.h> 
public: 

int remove( const Key & ) ; 

The remove public member function is used to remove the specified element from the dictionary. If 
an equivalent element is found, a non-zero value is returned. Zero is returned if the element is not 
found. Note that equivalence is based on the equivalence operator of the Key type. 

The element is removed from the dictionary if it found. 
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WCValSkipList<Type>, WCValSkipListSet<Type> 


Declared: 


wcskip.h 

WCValSkipList<Type> and WCValSkipListSet<Type> classes are templated classes used to 
store objects in a skip list. A skip list is a probabilistic alternative to balanced trees, and provides a 
reasonable performance balance to insertion, search, and deletion. A skip list allows more than one 
copy of an element that is equivalent, while the skip list set allows only one copy. The equality operator 
of the element’s type is used to locate the value. 

In the description of each member function, the text Type is used to indicate the template parameter 
defining the type of the data to be stored in the list. 

Values are copied into the list, which could be undesirable if the stored objects are complicated and 
copying is expensive. Value skip lists should not be used to store objects of a base class if any derived 
types of different sizes would be stored in the list, or if the destructor for a derived class must be called. 

The iterator classes for skip lists have the same function and operator interface as the hash iterators 
classes. See the chapter on hash iterators for more information. 

The WCExcept class is a base class of the WCValSkipList<Type> and 
WCValSkipListSet<Type> classes and provides the exceptions member function. This 
member function controls the exceptions which can be thrown by the WCValSkipList<Type> and 
WCValSkipListSet<Type> objects. No exceptions are enabled unless they are set by the 
exceptions member function. 

Requirements of Type 

The WCValSkipList<Type> and WCValSkipListSet<Type> classes requires Type to have: 
A default constructor ( Type : : Type () ). 

A well defined copy constructor (Type::Type( const Type & )). 

A well defined equivalence operator 
( int operator == ( const Type & ) const ). 

A well defined less than operator 

( int operator < ( const Type & ) const ). 

Public Member Functions 

The following member functions are declared in the public interface: 

WCValSkipList( unsigned = WCSKIPLIST_ PROB_ QUARTER, unsigned = 
WCDEFAULT_ SKIPLIST_ MAX_ PTRS ) ; 

WCValSkipList( unsigned = WCSKIPLIST_ PROB_ QUARTER, unsigned = 
WCDEFAULT_ SKIPLIST_ MAX_ PTRS, void * (*user_ alloc) ( size_ t size ), 

void (*user_ dealloc) ( void *old, size_ t size ) ); 

WCValSkipList( const WCValSkipList & ); 
virtual ~WCValSkipList() ; 

WCValSkipListSet( unsigned = WCSKIPLIST_ PROB_ QUARTER, unsigned = 
WCDEFAULT_ SKIPLIST_ MAX_ PTRS ) ; 

WCValSkipListSet( unsigned = WCSKIPLIST_ PROB_ QUARTER, unsigned = 
WCDEFAULT_ SKIPLIST_ MAX_ PTRS, void * (*user_ alloc) ( size_ t size ), 

void (*user_ dealloc) ( void *old, size_ t size ) ); 

WCValSkipListSet( const WCValSkipListSet & ); 
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WCValSkipList<Type>, WCValSkipListSet<Type> 


virtual ~WCValSkipListSet() ; 
void clear(); 

int contains( const Type & ) const; 

unsigned entries () const; 

int find( const Type &, Type & ) const; 

void forAll( void (*user_ fn) ( Type, void * ), void * ); 

int insert ( const Type & ); 

int isEmptyO const; 

int remove( const Type & ) ; 

The following public member functions are available for the WCValSkipList class only: 

unsigned occurrencesOf( const Type & ) const; 
unsigned removeAll( const Type & ) ; 

Public Member Operators 

The following member operators are declared in the public interface: 

WCValSkipList & operator =( const WCValSkipList & ); 
int operator ==( const WCValSkipList & ) const; 
WCValSkipListSet & operator =( const WCValSkipListSet & ); 
int operator == ( const WCValSkipListSet & ) const; 
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WCValSkipListSet<Type>::WCValSkipListSet() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <wcskip.h> 
public: 

WCValSkipListSet( unsigned = WCSKIPLIST_ PROB_ QUARTER, 
unsigned = WCDEFAULT_ SKIPLIST_ MAX_ PTRS ) ; 

The WCValSkipListSet<Type> constructor creates a WCValSkipListSet object with no 
entries. The first optional parameter, which defaults to the constant WCSKIPLIST_ PROB_ QUARTER, 
determines the probability of having a certain number of pointers in each skip list node. The second 
optional parameter, which defaults to the constant WCDEFAULT_ SKIPLIST_ MAX_ PTRS, determines 
the maximum number of pointers that are allowed in any skip list node. 

WCDEFAULT_ SKIPLIST_ MAX_ PTRS is the maximum effective value of the second parameter. If an 
allocation failure occurs while creating the skip list, the out_ of_ memory exception is thrown if the 
out_ of_ memory exception is enabled. 

The WCValSkipListSet<Type> constructor creates an initialized WCValSkipListSet object. 
~WCValSkipList<Type>, WCExcept::out_ of_ memory 
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WCValSkipListSet<Type>::WCValSkipListSet() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <wcskip.h> 
public: 

WCValSkipListSet( unsigned = WCSKIPLIST_ PROB_ QUARTER, 

unsigned = WCDEFAULT_ SKIPLIST_ MAX_ PTRS, 

void * (*user_ alloc) ( size_ t ), 

void (*user_ dealloc) ( void *, size_ t ) ); 

Allocator and deallocator functions are specified for use when entries are inseited and removed from the 
list. The semantics of this constructor are the same as the constructor without the memory management 
functions. 

The allocation function must return a zero if it cannot perform the allocation. The deallocation function 
is passed the size as well as the pointer to the data. Your allocation system may take advantage of the 
characteristic that the allocation function will always be called with the same size value for any 
particular instantiation of a skip list. To determine the size of the objects that the memory management 
functions will be required to allocate and free, the following macro may be used: 
WCValSkipListSetltemSize( Type, num_ of_ pointers ) 

The WCValSkipListSet<Type> constructor creates an initialized WCValSkipListSet object. 
~WCValSkipList<Type>, WCExcept::out_ of_ memory 
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WCValSkipListSet<Type>::WCValSkipListSet() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcskip.h> 
public: 

WCValSkipListSet( const WCValSkipListSet & ); 

The WCValSkipListSet<Type> constructor is the copy constructor for the 
WCValSkipListSet class. The new skip list is created with the same probability and maximum 
pointers, all values or pointers stored in the list, and the exception trap states. If there is not enough 
memory to copy all of the values, then only some will be copied, and the number of entries will 
correctly reflect the number copied. If all of the elements cannot be copied, then the 
out_ of_ memory exception is thrown if it is enabled. 

The WCValSkipListSet<Type> constructor creates a WCValSkipListSet object which is a 
copy of the passed list. 

operator =, WCExcept: : out_ of_ memory 
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WCValSkipListSet<Type>::~WCValSkipListSet() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcskip.h> 
public: 

virtual ~WCValSkipListSet() ; 

The WCValSkipListSet<Type> destructor is the destructor for the WCValSkipListSet class. 
If the number of elements is not zero and the not_ empty exception is enabled, the exception is 
thrown. Otherwise, the list elements are cleared using the clear member function. The call to the 
WCValSkipListSet<Type> destructor is inserted implicitly by the compiler at the point where the 
WCValSkipListSet object goes out of scope. 

The call to the WCValSkipListSet<Type> destructor destroys a WCValSkipListSet object, 
clear, WCExcept: : not_ empty 
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WCValSkipList<Type>::WCValSkipList() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <wcskip.h> 
public: 

WCValSkipList( unsigned = WCSKIPLIST_ PROB_ QUARTER, 
unsigned = WCDEFAULT_ SKIPLIST_ MAX_ PTRS ) ; 

The WCValSkipList<Type> constructor creates a WCValSkipList object with no entries. The 
first optional parameter, which defaults to the constant WCSKIPLIST_ PROB_ QUARTER, determines 
the probability of having a certain number of pointers in each skip list node. The second optional 
parameter, which defaults to the constant WCDEFAULT_ SKIPLIST_ MAX_ PTRS, determines the 
maximum number of pointers that are allowed in any skip list node. 

WCDEFAULT_ SKIPLIST_ MAX_ PTRS is the maximum effective value of the second parameter. If an 
allocation failure occurs while creating the skip list, the out_ of_ memory exception is thrown if the 
out_ of_ memory exception is enabled. 

The WCValSkipList<Type> constructor creates an initialized WCValSkipList object. 
~WCValSkipList<Type>, WCExcept::out_ of_ memory 
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WC ValSkipList<Type>:: WC ValSkipListQ 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <wcskip.h> 
public: 

WCValSkipList( unsigned = WCSKIPLIST_ PROB_ QUARTER, 

unsigned = WCDEFAULT_ SKIPLIST_ MAX_ PTRS, 

void * (*user_ alloc) ( size_ t ), 

void (*user_ dealloc) ( void *, size_ t ) ); 

Allocator and deallocator functions are specified for use when entries are inseited and removed from the 
list. The semantics of this constructor are the same as the constructor without the memory management 
functions. 

The allocation function must return a zero if it cannot perform the allocation. The deallocation function 
is passed the size as well as the pointer to the data. Your allocation system may take advantage of the 
characteristic that the allocation function will always be called with the same size value for any 
particular instantiation of a skip list. To determine the size of the objects that the memory management 
functions will be required to allocate and free, the following macro may be used: 
WCValSkipListltemSize( Type, num_ of_ pointers ) 

The WCValSkipList<Type> constructor creates an initialized WCValSkipList object. 
~WCValSkipList<Type>, WCExcept::out_ of_ memory 
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WCValSkipList<Type>::WCValSkipList() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcskip.h> 
public: 

WCValSkipList( const WCValSkipList & ); 

The WCValSkipList<Type> constructor is the copy constructor for the WCValSkipList class. 
The new skip list is created with the same probability and maximum pointers, all values or pointers 
stored in the list, and the exception trap states. If there is not enough memory to copy all of the values, 
then only some will be copied, and the number of entries will correctly reflect the number copied. If all 
of the elements cannot be copied, then the out_ of_ memory exception is thrown if it is enabled. 

The WCValSkipList<Type> constructor creates a WCValSkipList object which is a copy of the 
passed list. 

operator =, WCExcept::out_ of_ memory 
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WCValSkipList<Type>::~WCVaiSkipList() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcskip.h> 
public: 

virtual ~WCValSkipList() ; 

The WCValSkipList<Type> destructor is the destructor for the WCValSkipList class. If the 
number of elements is not zero and the not_ empty exception is enabled, the exception is thrown. 
Otherwise, the list elements are cleared using the clear member function. The call to the 
WCValSkipList<Type> destructor is inserted implicitly by the compiler at the point where the 
WCValSkipList object goes out of scope. 

The call to the WCValSkipList<Type> destructor destroys a WCValSkipList object, 
clear, WCExcept: : not_ empty 
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WCValSkipList<Type>::clear(), WCValSkipListSet<Type>::clear() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcskip.h> 

public: 

void clear(); 

The clear public member function is used to clear the list so that it has no entries. Elements stored in 
the list are destroyed using the destructors of Type . The list object is not destroyed and re-created by 
this function, so the object destructor is not invoked. 

The clear public member function clears the list to have no elements. 

~WCValSkipList<Type>, operator = 
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WCValSkipList<Type>::contains(), WCValSkipListSet<Type>::contains() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcskip.h> 
public: 

int contains( const Type & ) const; 

The contains public member function returns non-zero if the element is stored in the list, or zero if 
there is no equivalent element. Note that equivalence is based on the equivalence operator of the 
element type. 

The contains public member function returns a non-zero value if the element is found in the list, 
find 
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WCValSkipList<Type>::entries(), WCValSkipListSet<Type>::entries() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcskip.h> 
public: 

unsigned entries() const; 

The entries public member function is used to return the current number of elements stored in the 
list. 

The entries public member function returns the number of elements in the list, 
isEmpty 
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WCValSkipList<Type>::find(), WCValSkipListSet<Type>::find() 


Synopsis: 


Semantics: 


Results: 


#include <wcskip.h> 
public: 

int find( const Type &, Type & ) const; 

The find public member function is used to find an element with an equivalent value in the list. If an 
equivalent element is found, a non-zero value is returned. The reference to the element passed as the 
second argument is assigned the found element’s value. Zero is returned if the element is not found. 
Note that equivalence is based on the equivalence operator of the element type. 

The element equivalent to the passed value is located in the list. 
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WCValSkipList<Type>::forAII(), WCValSkipListSet<Type>::forAII() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wcskip.h> 
public: 
void forAll( 

void (*user_ fn) ( Type, void * ), 
void * ); 

The forAll public member function causes the user supplied function to be invoked for every value in 
the list. The user function has the prototype 


void user_ func ( Type & value, void * data ) ; 

As the elements are visited, the user function is invoked with the element passed as the first. The 
second parameter of the forAll function is passed as the second parameter to the user function. This 
value can be used to pass any appropriate data from the main code to the user function. 

The elements in the list are all visited, with the user function being invoked for each one. 

find 
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WCValSkipList<Type>::insert(), WCValSkipListSet<Type>::insert() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcskip.h> 
public: 

int insert( const Type & ) ; 

The insert public member function inserts a value into the list. If allocation of the node to store the 
value fails, then the out_ of_ memory exception is thrown if it is enabled. If the exception is not 
enabled, the insert will not be completed. 

With a WCValSkipListSet, there must be only one equivalent element in the set. If an element 
equivalent to the inserted element is already in the list set, the list set will remain unchanged, and the 
not_ unique exception is thrown if it is enabled. If the exception is not enabled, the insert will not be 
completed. 

The insert public member function inserts a value into the list. If the insert is successful, a non-zero 
will returned. A zero will be returned if the insert fails. 

operator =, WCExcept: : out_ of_ memoryfyJCExcept: : not_ unique 
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WCValSkipList<Type>::isEmpty(), WCValSkipListSet<Type>::isEmpty() 


Synopsis: 

Semantics 

Results: 

See Also: 


#include <wcskip.h> 
public: 

int isEmptyO const; 

The is Empty public member function is used to determine if the list is empty. 

The is Empty public member function returns zero if it contains at least one entry, non-zero if the list 
is empty. 

entries 
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WCValSkipList<Type>::occurrencesOf() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcskip.h> 
public: 

unsigned occurrencesOf( const Type & ) const; 

The occurrencesOf public member function is used to return the current number of elements stored 
in the list which are equivalent to the passed value. Note that equivalence is based on the equivalence 
operator of the element type. 

The occurrencesOf public member function returns the number of elements in the list which are 
equivalent to the passed value. 

entries, find, isEmpty 
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WCValSkipList<Type>:-.operator =(), WCValSkipListSet<Type>::operator =() 


Synopsis: #include <wcskip.h> 

public: 

WCValSkipList & operator =( const WCValSkipList & ); 

WCValSkipListSet & operator =( const WCValSkipListSet & ); 

Semantics: The operator = public member function is the assignment operator for the 

WCValSkipList<Type> and WCValSkipListSet<Type> classes. The left hand side list is first 
cleared using the clear member function, and then the right hand side list is copied. The list function, 
exception trap states, and all of the list elements are copied. If there is not enough memory to copy all 
of the values or pointers in the list, then only some will be copied, and the out_ of_ memory exception 
is thrown if it is enabled. The number of entries will correctly reflect the number copied. 

Results: The operator = public member function assigns the left hand side list to be a copy of the right hand 

side. 

See Also: clear, WCExcept: : out_ of_ memory 
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WCValSkipList<Type>:-.operator ==(), WCValSkipListSet<Type>::operator ==() 


Synopsis: 


Semantics: 


Results: 


#include <wcskip.h> 
public: 

int operator ==( const WCValSkipList & ) const; 
int operator ==( const WCValSkipListSet & ) const; 

The operator == public member function is the equivalence operator for the 
WCValSkipList<Type> and WCValSkipListSet<Type> classes. Two list objects are 
equivalent if they are the same object and share the same address. 

A TRUE (non-zero) value is returned if the left hand side and right hand side list are the same object. A 
FALSE (zero) value is returned otherwise. 
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WCValSkipList<Type>::remove(), WCValSkipListSet<Type>::remove() 


Synopsis: 


Semantics: 


Results: 


#include <wcskip.h> 
public: 

int remove( const Type & ) ; 

The remove public member function is used to remove the specified element from the list. If an 
equivalent element is found, a non-zero value is returned. Zero is returned if the element is not found. 
If the list is a WCValSkipList and there is more than one element equivalent to the specified 
element, then the last equivalent element added to the WCValSkipList is removed. Note that 
equivalence is based on the equivalence operator of the element type. 

The element is removed from the list. 
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WCValSkipUst<Type>::removeAII() 


Synopsis: 


Semantics: 


Results: 


#include <wcskip.h> 
public: 

unsigned removeAll( const Type & ); 

The removeAll public member function is used to remove all elements equivalent to the specified 
element from the list. Zero is returned if no equivalent elements are found. Note that equivalence is 
based on the equivalence operator of the element type. 

All equivalent elements are removed from the list. 


Skip List Containers 509 




WCValSkipList<Type>::removeAII() 
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16 Stack Container 


Stack containers maintain an ordered collection of data which is retrieved in the reverse order to which the 
data was entered into the stack. The stack class is implemented as a templated class, allowing the stacking 
of any data type. 

A second template parameter specifies the storage class used to implement the stack. The WCValSList, 
WCIsvSList and WCPtrSList classes are appropriate storage classes. 
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WCStack<Type, FType> 


Declared: 


wcstack.h 

The WCStack<Type, FType> class is a templated class used to create objects which maintain data in 
a stack. 

In the description of each member function, the text Type is used to indicate the template parameter 
defining the type of the elements stored in the stack. The text FType is used to indicate the template 
parameter defining the storage class used to maintain the stack. 

For example, to create a stack of integers, the WCStack<int,WCValSList<int> > class can be 
used. The WCStack<int *,WCPtrSList<int> > class will create a stack of pointers to 
integers. To create an intrusive stack of objects of type isv_link (derived from the WCSLink class), the 
WCStack< isv_link *, WCIsvSList< isv_link > > class can be used. 

The WCExcept class is a base class of the WCStack<Type, FType> class and provides the 
exceptions member function. This member function controls the exceptions which can be thrown 
by the WCStack<Type, FType> object. No exceptions are enabled unless they are set by the 
exceptions member function. 

Requirements of Type 

Type must provide any constructors and/or operators required by the FType class. 

Public Member Functions 

The following member functions are declared in the public interface: 

WCStack (); 

WCStack ( void *(*) ( size_t ), void (*) ( void *, size_t ) ); 

-WCStack(); 
void clear (); 
int entries () const; 
int isEmptyO const; 

Type pop (); 

int push( const Type & ) ; 

Type top() const; 

Sample Program Using a Stack 


♦include <wcstack.h> 
♦include <iostream.h> 


void main() { 

WCStack<int,WCValSList<int> > stack; 


stack.push( 7 ); 
stack.push( 8 ) ; 
stack.push( 9 ) ; 
stack.push( 10 ) ; 


cout << "\nNumber of stack 
cout « "Top entry = [" « 
while ( !stack.isEmpty() ) 
cout « stack.pop () « 


entries: " 
stack.top ( 

" \n" ; 


« stack.entries () 
« "]\n"; 


« "\n"; 


cout.flush(); 

} 
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WCStack<Type,FType>::WCStack() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcstack.h> 
public: 

WCStack(); 

The public WCStack<Type, FType> constructor creates an empty WCStack<Type, FType> 
object. The FType storage class constructor performs the initialization. 

The public WCStack<Type, FType> constructor creates an initialized WCStack<Type, FType> 
object. 

~WCStack<Type,FType> 
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WCStack<Type, FType>:: WCStackQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcstack.h> 
public: 

WCStack( void * (*allocator)( size_t ), 
void (*deallocator)( void *, size_t ) ); 

The public WCStack<Type, FType> constructor creates an empty WCStack<Type, FType> 
object. If FType is either the WCValSList or WCPtrSList class, then the allocator function is 
registered to perform all memory allocations of the stack elements, and the deallocator function to 
perform all freeing of the stack elements’ memory. The allocator and deallocator functions are ignored 
if FType is the WCIsvSList class. These functions provide the ability to control how the allocation 
and freeing of memory is performed, allowing for more efficient memory handling than the general 
purpose global operator new () and operator deleted can provide. Memory management 
optimizations may potentially be made through the allocator and deallocator functions, but are not 
recommended before managing memory is understood and determined to be worth while. 

The allocator function shall return a pointer to allocated memory of size at least the argument, or 
zero(O) if the allocation cannot be performed. Initialization of the memory returned is performed by the 
WCStack<Type, FType> class. 

The WCStack<Type, FType> class calls the deallocator function only on memory allocated by the 
allocator function. The deallocator shall free the memory pointed to by the first argument which is of 
size the second argument. The size passed to the deallocator function is guaranteed to be the same size 
passed to the allocator function when the memory was allocated. 

The allocator and deallocator functions may assume that for a list object instance, the allocator is 
always called with the same first argument (the size of the memory to be allocated). If FType is the 
WCValSList<Type> class, then the WCValSListltemSize (Type) macro returns the size of the 
elements which are allocated by the allocator function. Similarly, the WCPtrSListltemSize ( 
Type ) macro returns the size of WCPtrSList<Type> elements. 

The FType storage class constructor performs the initialization of the stack. 

The public WCStack<Type, FType> constructor creates an initialized WCStack<Type, FType> 
object and registers the allocator and deallocator functions. 

WCStack<Type,FType>, ~WCStack<Type,FType> 
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WCStack<Type,FType>::~WCStack() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wcstack.h> 
public: 

virtual ~WCStack(); 

The public ~WCStack<Type, FType> destructor destroys the WCStack<Type, FType> object. 
The FType storage class destructor performs the destruction. The call to the public 
~WCStack<Type, FType> destructor is inserted implicitly by the compiler at the point where the 
WCStack<Type, FType> object goes out of scope. 

If the not_ empty exception is enabled, the exception is thrown if the stack is not empty of stack 
elements. 

The WCStack<Type, FType> object is destroyed. 

WCStack<Type,FType>, clear,WCExcept::not_ empty 
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WCStack<Type, FType>::clear() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcstack.h> 

public: 

void clear (); 

The clear public member function is used to clear the stack object and set it to the state of the object 
just after the initial construction. The stack object is not destroyed and re-created by this operator, so 
the object destructor is not invoked. The stack elements are not cleared by the stack class. However, 
the class used to maintain the stack, FType, may clear the items as part of the clear member 
function for that class. If it does not clear the items, any stack items still in the list are lost unless 
pointed to by some pointer object in the program code. 

The clear public member function resets the stack object to the state of the object immediately after 
the initial construction. 

~WCStack<Type,FType>, isEmpty 
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WCStack<Type,FType>::entries() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcstack.h> 
public: 

int entries() const; 

The entries public member function is used to determine the number of stack elements contained in 
the list object. 

The number of elements on the stack is returned. Zero(O) is returned if there are no stack elements, 
isEmpty 
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WCStack<Type,FType>::isEmpty() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcstack.h> 
public: 

int isEmptyO const; 

The is Empty public member function is used to determine if a stack object has any stack elements 
contained in it. 

A TRUE value (non-zero) is returned if the stack object does not have any stack elements contained 
within it. A FALSE (zero) result is returned if the stack contains at least one element. 

entries 
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WCStack<Type, FType>::pop() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcstack.h> 
public: 

Type pop (); 

The pop public member function returns the top stack element from the stack object. The top stack 
element is the last element pushed onto the stack. The stack element is also removed from the stack. 

If the stack is empty, one of two exceptions can be thrown. If the empty_ container exception is 
enabled, then it will be thrown. Otherwise, the index_ range exception will be thrown, if enabled. 

The top stack element is removed and returned. The return value is determined by the get member 
function of the FType class if there are no elements on the stack. 

isEmpty, push, top, WCExcept: : empty_ container,WCExcept: : index_ range, 
FType::get 
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WCStack<Type, FType>::push() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcstack.h> 
public: 

int push( const Type & ) ; 

The push public member function is used to push the data onto the top of the stack. It will be the first 
element on the stack to be popped. 

If the push fails, the out_ of_ memory exception will be thrown, if enabled, and the stack will remain 
unchanged. 

The stack element is pushed onto the top of the stack. A TRUE value (non-zero) is returned if the push 
is successful. A FALSE (zero) result is returned if the push fails. 

pop, WCExcept: : out_ of_ memory 
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WCStack<Type, FType>::top() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcstack.h> 
public: 

Type top() const; 

The top public member function returns the top stack element from the stack object. The top stack 
element is the last element pushed onto the stack. The stack element is not removed from the stack. 

If the stack is empty, one of two exceptions can be thrown. If the empty_ container exception is 
enabled, then it will be thrown. Otherwise, the index_ range exception will be thrown, if enabled. 

The top stack element is returned. The return value is determined by the find member function of the 
FType class if there are no elements on the stack. 

isEmpty, pop, WCExcept: :empty_ container,WCExcept: :index_ range, 

FType::find 
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WCStack<Type, FType>::top() 
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17 Vector Containers 


This chapter describes vector containers. 
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WCPtrSortedVector<Type>, WCPtrOrderedVector<Type> 


Declared: 


wcvector.h 

The WCPtrSortedVector<Type> and WCPtrOrderedVector<Type> classes are templated 
classes used to store objects in a vector. Ordered and Sorted vectors are powerful arrays which can be 
resized and provide an abstract interface to insert, find and remove elements. An ordered vector 
maintains the order in which elements are added, and allows more than one copy of an element that is 
equivalent. The sorted vector allow only one copy of an equivalent element, and inserts them in a 
sorted order. The sorted vector is less efficient when inserting elements, but can provide a faster 
retrieval time. 

Elements cannot be inserted into these vectors by assigning to a vector index. Vectors automatically 
grow when necessary to insert an element if the resize_ required exception is not enabled. 

In the description of each member function, the text Type is used to indicate the template parameter 
defining the type pointed to by the pointers stored in the vector. 

Note that lookups are performed on the types pointed to, not just by comparing pointers. Two pointer 
elements are equivalent if the values they point to are equivalent. The values pointed to do not need to 
be the same object. 

The WCPtrOrderedVector class stores elements in the order which they are inserted using the 
insert, append, prepend and insertAt member functions. Linear searches are performed 
to locate entries, and the less than operator is not required. 

The WCPtrSortedVector class stores elements in ascending order. This requires that Type 
provides a less than operator. Insertions are more expensive than inserting or appending into an ordered 
vector, since entries must be moved to make room for the new element. A binary search is used to 
locate elements in a sorted vector, making searches quicker than in the ordered vector. 

Care must be taken when using the WCPtrSortedVector class not to change the ordering of the 
vector elements. An object pointed to by a vector element must not be changed so that it is not 
equivalent to the value when the pointer was inserted into the vector. The index operator and the 
member functions find, first, and last all return pointers the elements pointed to by the vector 
elements. Lookups assume elements are in sorted order, so you should not use the returned pointers to 
change the ordering of the value pointed to. 

The WCPtrVector class is also available. It provides a resizable and boundary safe vector similar to 
standard arrays. 

The WCExcept class is a base class of the WCPtrSortedVector<Type> and 
WCPtrOrderedVector<Type> classes and provides the exceptions member function. This 
member function controls the exceptions which can be thrown by the WCPtrSortedVector<Type> 
and WCPtrOrderedVector<Type> objects. No exceptions are enabled unless they are set by the 
exceptions member function. 

Requirements of Type 

Both the WCPtrSortedVector<Type> and WCPtrOrderedVector<Type> classes require 
Type to have: 

A well defined equivalence operator with constant parameters 
( int operator == ( const Type & ) const ). 

Additionally the WCPtrSortedVector class requires Type to have: 
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WCPtrSortedVector<Type>, WCPtrOrderedVector<Type> 


A well defined less than operator with constant parameters 
( int operator < ( const Type & ) const ). 

Public Member Functions 

The following member functions are declared in the public interface: 

WCPtrOrderedVector ( size_ t = WCDEFAULT_ VECTOR_ LENGTH, unsigned = 
WCDEFAULT_ VECTOR_ RESIZE_ GROW ); 

WCPtrOrderedVector( const WCPtrOrderedVector & ); 
virtual ~WCPtrOrderedVector() ; 

WCPtrSortedVector ( size_ t = WCDEFAULT_ VECTOR_ LENGTH, unsigned = 
WCDEFAULT_ VECTOR_ RESIZE_ GROW ); 

WCPtrSortedVector( const WCPtrSortedVector & ); 

virtual ~WCPtrSortedVector() ; 

void clear (); 

void clearAndDestroy (); 

int contains ( const Type * ) const; 

unsigned entries!) const; 

Type * find( const Type * ) const; 

Type * first!) const; 
int index! const Type * ) const; 
int insert( Type * ); 
int isEmpty!) const; 

Type * last!) const; 

int occurrencesOf( const Type * ) const; 

Type * remove( const Type * ) ; 
unsigned removeAll( const Type * ) ; 

Type * removeAt( int ); 

Type * removeFirst (); 

Type * removeLast(); 
int resize ( size_ t ) ; 

The following public member functions are available for the WCPtrOrderedVector class only: 

int append( Type * ); 

int insertAt( int. Type * ); 

int prepend( Type * ); 

Public Member Operators 

The following member operators are declared in the public interface: 

Type * & operator []( int ); 

Type * const & operator []( int ) const; 

WCPtrOrderedVector & WCPtrOrderedVector::operator =( const 
WCPtrOrderedVector & ); 

WCPtrSortedVector & WCPtrSortedVector::operator =( const 
WCPtrSortedVector & ); 

int WCPtrOrderedVector::operator ==( const WCPtrOrderedVector & ) 
const; 

int WCPtrSortedVector::operator ==( const WCPtrSortedVector & ) 
const; 
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WCPtrOrderedVector<Type>::WCPtrOrderedVector() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

WCPtrOrderedVector ( size_ t = WCDEFAULT_ VECTOR_ LENGTH, 
unsigned = WCDEFAULT_ VECTOR_ RESIZE_ GROW ); 

The WCPtrOrderedVector<Type> constructor creates an empty WCPtrOrderedVector object 
able to store the number of elements specified in the first optional parameter, which defaults to the 
constant WCDEFAULT_ VECTOR_ LENGTH (currently defined as 10). If tha:esize_ required 
exception is not enabled, then the second optional parameter is used to specify the value to increase the 
vector size when an element is inserted into a full vector. If zero(0) is specified as the second 
parameter, any attempt to insert into a full vector fails. This parameter defaults to the constant 
WCDEFAULT_ VECTOR_ RESIZE_ GROW (currently defined as 5). 

If the vector object cannot be fully initialized, the vector is created with length zero. 

The WCPtrOrderedVector<Type> constructor creates an empty initialized 
WCPtrOrderedVector object. 

WCExcept::resize_ required 
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WCPtrOrderedVector<Type>::WCPtrOrderedVector() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

WCPtrOrderedVector( const WCPtrOrderedVector & ) ; 

The WCPtrOrderedVector<Type> constructor is the copy constructor for the 
WCPtrOrderedVector class. The new vector is created with the same length and resize value as the 
passed vector. All of the vector elements and exception trap states are copied. 

If the new vector cannot be fully created, it will have length zero. The out_ of_ memory exception is 
thrown if enabled in the vector being copied. 

The WCPtrOrderedVector<Type> creates a WCPtrOrderedVector object which is a copy of 
the passed vector. 

operator =, WCExcept::out_ of_ memory 
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WCPtrOrderedVector<Type>::~WCPtrOrderedVector() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wcvector.h> 
public: 

virtual ~WCPtrOrderedVector() ; 

The WCPtrOrderedVector<Type> destructor is the destructor for the WCPtrOrderedVector 
class. If the vector is not length zero and the not_ empty exception is enabled, the exception is 
thrown. Otherwise, the vector entries are cleared using the clear member function. The objects 
which the vector entries point to are not deleted unless the clearAndDestroy member function is 
explicitly called before the destructor is called. The call to the WCPtrOrderedVector<Type> 
destructor is inserted implicitly by the compiler at the point where the WCPtrOrderedVector object 
goes out of scope. 

The WCPtrOrderedVector<Type> destructor destroys an WCPtrOrderedVector object, 
clear, clearAndDestroy, WCExcept::not_ empty 
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WCPtrSortedVector<Type>::WCPtrSortedVector() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

WCPtrSortedVector ( size_ t = WCDEFAULT_ VECTOR_ LENGTH, 
unsigned = WCDEFAULT_ VECTOR_ RESIZE_ GROW ); 

The WCPtrSortedVector<Type> constructor creates an empty WCPtrSortedVector object 
able to store the number of elements specified in the first optional parameter, which defaults to the 
constant WCDEFAULT_ VECTOR_ LENGTH (currently defined as 10). If tha:esize_ required 
exception is not enabled, then the second optional parameter is used to specify the value to increase the 
vector size when an element is inserted into a full vector. If zero(0) is specified as the second 
parameter, any attempt to insert into a full vector fails. This parameter defaults to the constant 
WCDEFAULT_ VECTOR_ RESIZE_ GROW (currently defined as 5). 

If the vector object cannot be fully initialized, the vector is created with length zero. 

The WCPtrSortedVector<Type> constructor creates an empty initialized 
WCPtrSortedVector object. 

WCExcept::resize_ required 
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WCPtrSortedVector<Type>::WCPtrSortedVector() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

WCPtrSortedVector( const WCPtrSortedVector & ) ; 

The WCPtrSortedVector<Type> constructor is the copy constructor for the 
WCPtrSortedVector class. The new vector is created with the same length and resize value as the 
passed vector. All of the vector elements and exception trap states are copied. 

If the new vector cannot be fully created, it will have length zero. The out_ of_ memory exception is 
thrown if enabled in the vector being copied. 

The WCPtrSortedVector<Type> constructor creates a WCPtrSortedVector object which is a 
copy of the passed vector. 

operator =, WCExcept: : out_ of_ memory 
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WCPtrSortedVector<Type>::~WCPtrSortedVector() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wcvector.h> 
public: 

virtual ~WCPtrSortedVector() ; 

The WCPtrSortedVector<Type> destructor is the destructor for the WCPtrSortedVector 
class. If the vector is not length zero and the not_ empty exception is enabled, the exception is 
thrown. Otherwise, the vector entries are cleared using the clear member function. The objects 
which the vector entries point to are not deleted unless the clearAndDestroy member function is 
explicitly called before the destructor is called. The call to the WCPtrSortedVector<Type> 
destructor is inserted implicitly by the compiler at the point where the WCPtrSortedVector object 
goes out of scope. 

The WCPtrSortedVector<Type> destructor destroys an WCPtrSortedVector object, 
clear, clearAndDestroy, WCExcept::not_ empty 
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WCPtrOrderedVector<Type>::append() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int append( Type * ) ; 

The append public member function appends the passed element to be the last element in the vector. 
This member function has the same semantics as the WCPtrOrderedVector: : insert member 
function. 

This function is not provided by the WCPtrSortedVector class, since all elements must be inserted 
in sorted order by the insert member function. 

Several different results can occur if the vector is not large enough for the new element. If the 
resize_ required exception is enabled, the exception is thrown. If the exception is not enabled, 
the append fails if the amount the vector is to be grown (the second parameter to the constructor) is 
zero(O). Otherwise, the vector is automatically grown by the number of elements specified to the 
constructor, using the resize member function. If resize fails, the element is not appended to the 
vector and the out_ of_ memory exception is thrown, if enabled. 

The append public member function appends an element to the WCPtrOrderedVector object. A 
TRUE (non-zero) value is returned if the append is successful. If the append fails, a FALSE (zero) 
value is returned. 

insert, insertAt, prepend, WCExcept: : out_ of_ memory, 

WCExcept::resize_ required 


532 Vector Containers 




WCPtrSortedVector<Type>::clear(), WCPtrOrderedVector<Type>::clear() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcvector.h> 

public: 

void clear(); 

The clear public member function is used to clear the vector so that it contains no entries, and is zero 
size. Objects pointed to by the vector elements are not deleted. The vector object is not destroyed and 
re-created by this function, so the object destructor is not invoked. 

The clear public member function clears the vector to have zero length and no entries. 

~WCPtrOrderedVector, clearAndDestroy, operator = 
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WCPtrSortedVector<Type>,WCPtrOrderedVector<Type>::clearAndDestroy() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

void clearAndDestroy(); 

The clearAndDestroy public member function is used to clear the vector to have zero length and 
delete the objects pointed to by the vector elements. The vector object is not destroyed and re-created 
by this function, so the vector object destructor is not invoked. 

The clearAndDestroy public member function clears the vector by deleting the objects pointed to 
by the vector elements and makes the vector zero length. 

clear 
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WCPtrSortedVector<Type>,WCPtrOrderedVector<Type>::contains() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int contains( const Type * ) const; 

The contains public member function is used to determine if a value is contained by a vector. Note 
that comparisons are done on the objects pointed to, not the pointers themselves. A linear search is used 
by the WCPtrOrderedVector class to find the value. The WCPtrSortedVector class uses a 
binary search. 

The contains public member function returns a TRUE (non-zero) value if the element is found in the 
vector. A FALSE (zero) value is returned if the vector does not contain the element. 

index, find 
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WCPtrSortedVector<Type>::entries(), WCPtrOrderedVector<Type>::entries() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcvector.h> 
public: 

unsigned entries() const; 

The entries public member function is used to find the number of elements which are stored in the 
vector. 

The entries public member function returns the number of elements in the vector, 
isEmpty 
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WCPtrSortedVector<Type>::find(), WCPtrOrderedVector<Type>::find() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

Type * find( const Type * ) const; 

The find public member function is used to find an element equivalent to the element passed. Note 
that comparisons are done on the objects pointed to, not the pointers themselves. The 
WCPtrOrderedVector class uses a linear search to find the element, and the 
WCPtrSortedVector class uses a binary search. 

A pointer to the first equivalent element is returned. NULL(O) is returned if the element is not in the 
vector. 

contains, first, index, last, occurrencesOf, remove 
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WCPtrSortedVector<Type>::first(), WCPtrOrderedVector<Type>::first() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wcvector.h> 
public: 

Type * first() const; 

The first public member function returns the first element in the vector. The element is not removed 
from the vector. 

If the vector is empty, one of two exceptions can be thrown. The empty_ container exception is 
thrown if it is enabled. Otherwise, if the index_ range exception is enabled, it is thrown. If neither 
exception is enabled, a first element of the vector is added with a NULL value. 

The first public member function returns the value of the first element in the vector. 

last, removeFirst, WCExcept: :index_ range,WCExcept: :resize_ required 
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WCPtrSortedVector<Type>::index(), WCPtrOrderedVector<Type>::index() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int index( const Type * ) const; 

The index public member function is used find the index of the first element equivalent to the passed 
element. Note that comparisons are done on the objects pointed to, not the pointers themselves. A 
linear search is used by the WCPtrOrderedVector class to find the element. The 
WCPtrSortedVector class uses a binary search. 

The index public member function returns the index of the first element equivalent to the parameter. 
If the passed value is not contained in the vector, negative one (-1) is returned. 

contains, find, insertAt, operator [], removeAt 


Vector Containers 539 




WCPtrSortedVector<Type>::insert(), WCPtrOrderedVector<Type>::insert() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int insert( Type * ) ; 

The insert public member function inserts the value into the vector. 

The WCPtrOrderedVector : : insert function inserts the value as the last element of the vector, 
and has the same semantics as the WCPtrOrderedVector: : append member function. 

A binary search is performed to determine where the value should be inserted for the 
WCPtrSortedVector : : insert function. Note that comparisons are done on the objects pointed 
to, not the pointers themselves. Any elements greater than the inserted value are copied up one index so 
that the new element is after all elements with value less than or equal to it. 

Several different results can occur if the vector is not large enough for the new element. If the 
resize_ required exception is enabled, the exception is thrown. If the exception is not enabled, 
the insert fails if the amount the vector is to be grown (the second parameter to the constructor) is 
zero(O). Otherwise, the vector is automatically grown by the number of elements specified to the 
constructor, using the resize member function. If resize fails, the element is not inserted to the 
vector and the out_ of_ memory exception is thrown, if enabled. 

The insert public member function inserts an element in to the vector. A TRUE (non-zero) value is 
returned if the insert is successful. If the insert fails, a FALSE (zero) value is returned. 

append, insertAt, prepend, WCExcept: : out_ of_ memory, 

WCExcept::resize_ required 
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WCPtrOrderedVector<Type>::insertAt() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

int insertAt( int. Type * ) ; 

The insertAt public member function inserts the second argument into the vector before the element 
at index given by the first argument. If the passed index is equal to the number of entries in the vector, 
the new value is appended to the vector as the last element. All vector elements with indexes greater 
than or equal to the first parameter are copied up one index. 

This function is not provided by the WCPtrSortedVector class, since all elements must be inserted 
in sorted order by the insert member function. 

If the passed index is negative or greater than the number of entries in the vector and the 
index_ range exception is enabled, the exception is thrown. If the exception is not enabled, the new 
element is inserted as the first element when the index is negative, or as the last element when the index 
is too large. 

Several different results can occur if the vector is not large enough for the new element. If the 
resize_ required exception is enabled, the exception is thrown. If the exception is not enabled, 
the insert fails if the amount the vector is to be grown (the second parameter to the constructor) is 
zero(O). Otherwise, the vector is automatically grown by the number of elements specified to the 
constructor, using the resize member function. If resize fails, the element is not inserted into the 
vector and the out_ of_ memory exception is thrown, if enabled. 

The insertAt public member function inserts an element into the WCPtrOrderedVector object 
before the element at the given index. A TRUE (non-zero) value is returned if the insert is successful. 

If the insert fails, a FALSE (zero) value is returned. 

append, insert, prepend, operator [], removeAt, WCExcept: :index_ range, 
WCExcept: : out_ of_ memorytylCExcept: : resize_ required 
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WCPtrSortedVector<Type>,WCPtrOrderedVector<Type>::isEmpty() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int isEmptyO const; 

The isEmpty public member function is used to determine if a vector object has any entries contained 
in it. 

A TRUE value (non-zero) is returned if the vector object does not have any vector elements contained 
within it. A FALSE (zero) result is returned if the vector contains at least one element. 

entries 
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WCPtrSortedVector<Type>::last(), WCPtrOrderedVector<Type>::last() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wcvector.h> 
public: 

Type * last() const; 

The last public member function returns the last element in the vector. The element is not removed 
from the vector. 

If the vector is empty, one of two exceptions can be thrown. The empty_ container exception is 
thrown if it is enabled. Otherwise, if the index_ range exception is enabled, it is thrown. If neither 
exception is enabled, a first element of the vector is added with a NULL value. 

The last public member function returns the value of the last element in the vector. 

first, removeLast, WCExcept: : index_ range,WCExcept: : resize_ required 
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WCPtrSortedVector<Type>,WCPtrOrderedVector<Type>::occurrencesOf() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int occurrencesOf( const Type * ) const; 

The occurrencesOf public member function returns the number of elements contained in the vector 
that are equivalent to the passed value. Note that comparisons are done on the objects pointed to, not 
the pointers themselves. A linear search is used by the WCPtrOrderedVector class to find the 
value. The WCPtrSortedVector class uses a binary search. 

The occurrencesOf public member function returns the number of elements equivalent to the 
passed value. 

contains, find, index, operator [], removeAll 
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WCPtrSortedVector<Type>,WCPtrOrderedVector<Type>::operator []() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

Type * & operator [] ( int ) ; 

Type * const & operator [] ( int ) const; 

operator [] is the vector index operator. A reference to the object stored in the vector at the given 
index is returned. If a constant vector is indexed, a reference to a constant element is returned. 

The append, insert, insert At and prepend member functions are used to insert a new 
element into a vector, and the remove, removeAll, removeAt, removeFirst and 
removeLast member functions remove elements. The index operator cannot be used to change the 
number of entries in the vector. Searches may be performed using the find and index member 
functions. 

If the vector is empty, one of two exceptions can be thrown. The empty_ container exception is 
thrown if it is enabled. Otherwise, if the index_ range exception is enabled, it is thrown. If neither 
exception is enabled, a first element of the vector is added with a NULL value. This element is added 
so that a reference to a valid vector element can be returned. 

If the index value is negative and the index_ range exception is enabled, the exception is thrown. 

An attempt to index an element with index greater than or equal to the number of entries in the vector 
will also cause the index_ range exception to be thrown if enabled. If the exception is not enabled, 
attempting to index a negative element will index the first element in the vector, and attempting to index 
an element after the last entry will index the last element. 

Care must be taken when using the WCPtrSortedVector class not to change the ordering of the 
vector elements. The result returned by the index operator must not be assigned to or modified in such 
a way that it is no longer equivalent (by Type's equivalence operator) to the value inserted into the 
vector. Failure to comply may cause lookups to work incorrectly, since the binary search algorithm 
assumes elements are in sorted order. 

The operator [] public member function returns a reference to the element at the given index. If 
the index is invalid, a reference to the closest valid element is returned. The result of the non-constant 
index operator may be assigned to. 

append, find, first, index, insert, insertAt, isEmpty, last, prepend, remove, 
removeAt, removeAll, removeFirst, removeLast, WCExcept: :empty_ container, 
WCExcept::index_ range 
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WCPtrSortedVector<Type>,WCPtrOrderedVector<Type>::operator =() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

WCPtrOrderedVector & WCPtrOrderedVector::operator =( const 
WCPtrOrderedVector & ) ; 

WCPtrSortedVector & WCPtrSortedVector::operator =( const 
WCPtrSortedVector & ); 

The operator = public member function is the assignment operator for the class. The left hand side 
vector is first cleared using the clear member function, and then the right hand side vector is copied. 
The left hand side vector is made to have the same length and growth amount as the right hand side (the 
growth amount is the second argument passed to the right hand side vector constructor). All of the 
vector elements and exception trap states are copied. 

If the left hand side vector cannot be fully created, it will have zero length. The out_ of_ memory 
exception is thrown if enabled in the right hand side vector. 

The operator = public member function assigns the left hand side vector to be a copy of the right 
hand side. 

clear, clearAndDestroy, WCExcept: : out_ of_ memory 
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WCPtrSortedVector<Type>,WCPtrOrderedVector<Type>::operator ==() 


Synopsis: 


Semantics: 


Results: 


#include <wcvector.h> 
public: 

int WCPtrOrderedVector::operator ==( const WCPtrOrderedVector & ) 
const; 

int WCPtrSortedVector::operator ==( const WCPtrSortedVector & ) 
const; 

The operator == public member function is the equivalence operator for the class. Two vector 
objects are equivalent if they are the same object and share the same address. 

A TRUE (non-zero) value is returned if the left hand side and right hand side vectors are the same 
object. A FALSE (zero) value is returned otherwise. 
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WCPtrOrderedVector<Type>::prepend() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int prepend( Type * ) ; 

The prepend public member function inserts the passed element to be the first element in the vector. 
All vector elements contained in the vector are copied up one index. 

This function is not provided by the WCPtrSortedVector class, since all elements must be inserted 
in sorted order by the insert member function. 

Several different results can occur if the vector is not large enough for the new element. If the 
resize_ required exception is enabled, the exception is thrown. If the exception is not enabled, 
the prepend fails if the amount the vector is to be grown (the second parameter to the constructor) is 
zero(O). Otherwise, the vector is automatically grown by the number of elements specified to the 
constructor, using the resize member function. If resize fails, the element is not inserted to the 
vector and the out_ of_ memory exception is thrown, if enabled. 

The prepend public member function prepends an element to the WCPtrOrderedVector object. 

A TRUE (non-zero) value is returned if the insert is successful. If the insert fails, a FALSE (zero) value 
is returned. 

append, insert, insertAt, WCExcept: : out_ of_ memory, 

WCExcept::resize_ required 
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WCPtrSortedVector<Type>::remove(), WCPtrOrderedVector<Type>::remove() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

Type * remove( const Type * ) ; 

The remove public member function removes the first element in the vector which is equivalent to the 
passed value. Note that comparisons are done on the objects pointed to, not the pointers themselves. 
All vector elements stored after the removed elements are copied down one index. 

A linear search is used by the WCPtrOrderedVector class to find the element being removed. The 
WCPtrSortedVector class uses a binary search. 

The remove public member function removes the first element in the vector which is equivalent to the 
passed value. The removed pointer is returned. If the vector did not contain an equivalent value, 
NULL(O) is returned. 

clear, clearAndDestroy, find, removeAll, removeAt, removeFirst, removeLast 
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WCPtrSortedVector<Type>,WCPtrOrderedVector<Type>::removeAII() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

unsigned removeAll( const Type * ) ; 

The removeAll public member function removes all elements in the vector which are equivalent to 
the passed value. Note that comparisons are done on the objects pointed to, not the pointers themselves. 
All vector elements stored after the removed elements are copied down one or more indexes to take the 
place of the removed elements. 

A linear search is used by the WCPtrOrderedVector class to find the elements being removed. The 
WCPtrSortedVector class uses a binary search. 

The removeAll public member function removes all elements in the vector which are equivalent to 
the passed value. The number of elements removed is returned. 

clear, clearAndDestroy, find, occurrencesOf, remove, removeAt, removeFirst, 
removeLast 
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WCPtrSortedVector<Type>,WCPtrOrderedVector<Type>::removeAt() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

Type * removeAt( int ); 

The removeAt public member function removes the element at the given index. All vector elements 
stored after the removed elements are copied down one index. 

If the vector is empty and the empty_ container exception is enabled, the exception is thrown. 

If an attempt to remove an element with a negative index is made and the index_ range exception is 
enabled, the exception is thrown. If the exception is not enabled, the first element is removed from the 
vector. Attempting to remove an element with index greater or equal to the number of entries in the 
vector also causes the index_ range exception to be thrown if enabled. The last element in the vector 
is removed if the exception is not enabled. 

The removeAt public member function removes the element with the given index. If the index is 
invalid, the closest element to the given index is removed. The removed pointer is returned. If the 
vector was empty, NULL(O) is returned. 

clear, clearAndDestroy, insertAt, operator [], remove, removeAll, 
removeFirst, removeLast 
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WCPtrSortedVector<Type>,WCPtrOrderedVector<Type>::removeFirst() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

Type * removeFirst() ; 

The removeFirst public member function removes the first element from a vector. All other vector 
elements are copied down one index. 

If the vector is empty and the empty_ container exception is enabled, the exception is thrown. 

The removeFirst public member function removes the first element from the vector. The removed 
pointer is returned. If the vector was empty, NULL(O) is returned. 

clear, clearAndDestroy, first, remove, removeAt, removeAll, removeLast 
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WCPtrSortedVector<Type>,WCPtrOrderedVector<Type>::removeLast() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

Type * removeLast() ; 

The removeLast public member function removes the last element from a vector. If the vector is 
empty and the empty_ container exception is enabled, the exception is thrown. 

The removeLast public member function removes the last element from the vector. The removed 
pointer is returned. If the vector was empty, NULL(O) is returned. 

clear, clearAndDestroy, last, remove, removeAt, removeAll, removeFirst 
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WCPtrSortedVector<Type>::resize(), WCPtrOrderedVector<Type>::resize() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int resize ( size_ t new_ size ) ; 

The resize public member function is used to change the vector size to be able to store new_size 
elements. If new_size is larger than the previous vector size, all elements are copied into the newly 
sized vector, and new elements can be added using the append, insert, insert At, and 
prepend member functions. If the vector is resized to a smaller size, the first new_size elements are 
copied (all vector elements if the vector contained new_size or fewer elements). The objects pointed to 
by the remaining elements are not deleted. 

If the resize cannot be performed and the out_ of_ memory exception is enabled, the exception is 
thrown. 

The vector is resized to new_size. A TRUE value (non-zero) is returned if the resize is successful. A 
FALSE (zero) result is returned if the resize fails. 

WCExcept: : out_ of_ memory 
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WCPtrVector<Type> 


Declared: 


wcvector.h 

The WCPtrVector<Type> class is a templated class used to store objects in a vector. Vectors are 
similar to arrays, but vectors perform bounds checking and can be resized. Elements are inserted into 
the vector by assigning to a vector index. 

The WCPtrOrderedVector and WCPtrSortedVector classes are also available. They provide a 
more abstract view of the vector and additional functionality, including finding and removing elements. 

In the description of each member function, the text Type is used to indicate the template parameter 
defining the type pointed to by the pointers stored in the vector. 

The WCExcept class is a base class of the WCPtrVector<Type> class and provides the 
exceptions member function. This member function controls the exceptions which can be thrown 
by the WCPtrVector<Type> object. No exceptions are enabled unless they are set by the 
exceptions member function. 

Requirements of Type 

The WCPtrVector<Type> class requires nothing from Type . 

Public Member Functions 

The following member functions are declared in the public interface: 

WCPtrVector( size_ t = 0 ); 

WCPtrVector ( size_t, const Type * ); 

WCPtrVector( const WCPtrVector & ) ; 

virtual ~WCPtrVector() ; 

void clear(); 

void clearAndDestroy() ; 

size_t length() const; 

int resize! size_t ); 

Public Member Operators 

The following member operators are declared in the public interface: 

Type * & operator [] ( int ); 

Type * const & operator []( int ) const; 

WCPtrVector & operator =( const WCPtrVector & ); 
int operator ==( const WCPtrVector & ) const; 
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WCPtrVector<Type>::WCPtrVector() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

WCPtrVector ( size_ t = 0 ); 

The public WCPtrVector<Type> constructor creates a WCPtrVector<Type> object able to store 
the number of elements specified in the optional parameter, which defaults to zero. All vector elements 
are initialized to NULL(O). 

If the vector object cannot be fully initialized, the vector is created with length zero. 

The public WCPtrVector<Type> constructor creates an initialized WCPtrVector<Type> object 
with the specified length. 

WCPtrVector<Type>, ~WCPtrVector<Type> 
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WCPtrVector<Type>::WCPtrVector() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

WCPtrVector ( size_t, const Type * ); 

The public WCPtrVector<Type> constructor creates a WCPtrVector<Type> object able to store 
the number of elements specified by the first parameter. All vector elements are initialized to the 
pointer value given by the second parameter. 

If the vector object cannot be fully initialized, the vector is created with length zero. 

The public WCPtrVector<Type> constructor creates an initialized WCPtrVector<Type> object 
with the specified length and elements set to the given value. 

WCPtrVector<Type>, ~WCPtrVector<Type> 
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WCPtrVector<Type>::WCPtrVector() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

WCPtrVector( const WCPtrVector & ) ; 

The public WCPtrVector<Type> constructor is the copy constructor for the 

WCPtrVector<Type> class. The new vector is created with the same length as the given vector. All 
of the vector elements and exception trap states are copied. 

If the new vector cannot be fully created, it will have length zero. The out_ of_ memory exception is 
thrown if enabled in the vector being copied. 

The public WCPtrVector<Type> constructor creates a WCPtrVector<Type> object which is a 
copy of the passed vector. 

operator =, WCExcept: : out_ of_ memory 
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WCPtrVector<Type>::~WCPtrVector() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wcvector.h> 
public: 

virtual ~WCPtrVector() ; 

The public ~WCPtrVector<Type> destructor is the destructor for the WCPtrVector<Type> 
class. If the vector is not length zero and the not_ empty exception is enabled, the exception is 
thrown. Otherwise, the vector elements are cleared using the clear member function. The objects 
which the vector elements point to are not deleted unless the clearAndDestroy member function is 
explicitly called before the destructor is called. The call to the public ~WCPtrVector<Type> 
destructor is inserted implicitly by the compiler at the point where the WCPtrVector<Type> object 
goes out of scope. 

The public ~WCPtrVector<Type> destructor destroys an WCPtrVector<Type> object, 
clear, clearAndDestroy, WCExcept::not_ empty 
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WCPtrVector<Type>::clear() 


Synopsis: #include <wcvector.h> 

public: 
void clear(); 


Semantics: 

Results: 
See Also: 


The clear public member function is used to clear the vector so that it is of zero length. Objects 
pointed to by the vector elements are not deleted. The vector object is not destroyed and re-created by 
this function, so the object destructor is not invoked. 

The clear public member function clears the vector to have zero length and no vector elements. 
~WCPtrVector<Type>, clearAndDestroy, operator = 
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WCPtrVector<Type>::clearAndDestroy() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

void clearAndDestroy(); 

The clearAndDestroy public member function is used to clear the vector to have zero length and 
delete the objects pointed to by the vector elements. The vector object is not destroyed and re-created 
by this function, so the vector object destructor is not invoked. 

The clearAndDestroy public member function clears the vector by deleting the objects pointed to 
by the vector elements and makes the vector zero length. 

clear 
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WCPtrVector<Type>::length() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcvector.h> 
public: 

size_t length() const; 

The length public member function is used to find the number of elements which can be stored in the 
WCPtrVector<Type> object. 

The length public member function returns the length of the vector, 
resize 
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WCPtrVector<Type>:-.operator []() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

Type * & operator [] ( int ) ; 

Type * const & operator [] ( int ) const; 

operator [] is the vector index operator. A reference to the object stored in the vector at the given 
index is returned. If a constant vector is indexed, a reference to a constant element is returned. The 
index operator of a non-constant vector is the only way to insert an element into the vector. 

If an attempt to access an element with index greater than or equal to the length of a non-constant vector 
is made and the resize_ required exception is enabled, the exception is thrown. If the exception is 
not enabled, the vector is automatically resized using the resize member function to have length the 
index value plus one. New vector elements are initialized to NULL(O). If the resize failed, and the 
out_ of_ memory exception is enabled, the exception is thrown. If the exception is not enabled and 
the resize failed, the last element is indexed (a new element if the vector was zero length). If a negative 
value is used to index the non-constant vector and the index_ range exception is enabled, the 
exception is thrown. If the exception is not enabled and the vector is empty, the resize_ required 
exception may be thrown. 

An attempt to index an empty constant vector may cause one of two exceptions to be thrown. If the 
empty_ container exception is enabled, it is thrown. Otherwise, theindex_ range exception is 
thrown, if enabled. If neither exception is enabled, a first vector element is added and indexed (so that a 
reference to a valid element can be returned). 

Indexing with a negative value or a value greater than or equal to the length of a constant vector causes 
the index_ range exception to be thrown, if enabled. 

The operator [] public member function returns a reference to the element at the given index. If 
the index is invalid, a reference to the closest valid element is returned. The result of the non-constant 
index operator may be assigned to. 

resize, WCExcept: :empty_ container,WCExcept: : index_ range, 

WCExcept: : out_ of_ memorytyJCExcept: : resize_ required 
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WCPtrVector<Type>:-.operator =() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

WCPtrVector & operator =( const WCPtrVector & ); 

The operator = public member function is the assignment operator for the WCPtrVector<Type> 
class. The left hand side vector is first cleared using the clear member function, and then the right 
hand side vector is copied. The left hand side vector is made to have the same length as the right hand 
side. All of the vector elements and exception trap states are copied. 

If the left hand side vector cannot be fully created, it will have zero length. The out_ of_ memory 
exception is thrown if enabled in the right hand side vector. 

The operator = public member function assigns the left hand side vector to be a copy of the right 
hand side. 

clear, clearAndDestroy, WCExcept: : out_ of_ memory 
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WCPtrVector<Type>:’.operator ==() 


Synopsis: 


Semantics: 


Results: 


#include <wcvector.h> 
public: 

int operator ==( const WCPtrVector & ) const; 

The operator == public member function is the equivalence operator for the 

WCPtrVector<Type> class. Two vector objects are equivalent if they are the same object and share 
the same address. 

A TRUE (non-zero) value is returned if the left hand side and right hand side vectors are the same 
object. A FALSE (zero) value is returned otherwise. 
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WCPtrVector<Type>::resize() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int resize ( size_ t new_ size ) ; 

The resize public member function is used to change the vector size to be able to store new_size 
elements. If new_size is larger than the previous vector size, all elements will be copied into the newly 
sized vector, and new elements are initialized to NULL(O). If the vector is resized to a smaller size, the 
first new_size elements are copied. The objects pointed to by the remaining elements are not deleted. 

If the resize cannot be performed and the out_ of_ memory exception is enabled, the exception is 
thrown. 

The vector is resized to new_size. A TRUE value (non-zero) is returned if the resize is successful. A 
FALSE (zero) result is returned if the resize fails. 

WCExcept: : out_ of_ memory 
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WCValSortedVector<Type>, WCValOrderedVector<Type> 


Declared: 


wcvector.h 

The WCValSortedVector<Type> and WCValOrderedVector<Type> classes are templated 
classes used to store objects in a vector. Ordered and Sorted vectors are powerful arrays which can be 
resized and provide an abstract interface to insert, find and remove elements. An ordered vector 
maintains the order in which elements are added, and allows more than one copy of an element that is 
equivalent. The sorted vector allow only one copy of an equivalent element, and inserts them in a 
sorted order. The sorted vector is less efficient when inserting elements, but can provide a faster 
retrieval time. 

Elements cannot be inserted into these vectors by assigning to a vector index. Vectors automatically 
grow when necessary to insert an element if the resize_ required exception is not enabled. 

In the description of each member function, the text Type is used to indicate the template parameter 
defining the type of the elements stored in the vector. 

Values are copied into the vector, which could be undesirable if the stored objects are complicated and 
copying is expensive. Value vectors should not be used to store objects of a base class if any derived 
types of different sizes would be stored in the vector, or if the destructor for a derived class must be 
called. 

The WCValOrderedVector class stores elements in the order which they are inserted using the 
insert, append, prepend and insertAt member functions. Linear searches are performed 
to locate entries, and the less than operator is not required. 

The WCValSortedVector class stores elements in ascending order. This requires that Type 
provides a less than operator. Insertions are more expensive than inserting or appending into an ordered 
vector, since entries must be moved to make room for the new element. A binary search is used to 
locate elements in a sorted vector, making searches quicker than in the ordered vector. 

Care must be taken when using the WCValSortedVector class not to change the ordering of the 
vector elements. The result returned by the index operator must not be assigned to or modified in such 
a way that it is no longer equivalent to the value inserted into the vector. Lookups assume elements are 
in sorted order. 

The WCValVector class is also available. It provides a resizable and boundary safe vector similar to 
standard arrays. 

The WCExcept class is a base class of the WCValSortedVector<Type> and 
WCValOrderedVector<Type> classes and provides the exceptions member function. This 
member function controls the exceptions which can be thrown by the WCValSortedVector<Type> 
and WCValOrderedVector<Type> objects. No exceptions are enabled unless they are set by the 
exceptions member function. 

Requirements of Type 

Both the WCValSortedVector<Type> and WCValOrderedVector<Type> classes require 
Type to have: 

A default constructor ( Type : : Type () ). 

A well defined copy constructor ( Type : : Type ( const Type & ) ). 

A well defined assignment operator 
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WCValSortedVector<Type>, WCValOrderedVector<Type> 


(Type & operator =( const Type & ) ). 

The following override of operator new () if Type overrides the global operator new () : 

void * operator new ( size_ t, void *ptr ) { return ( ptr ); } 

A well defined equivalence operator with constant parameters 
( int operator == ( const Type & ) const ). 

Additionally the WCValSortedVector class requires Type to have: 

A well defined less than operator with constant parameters 
( int operator < ( const Type & ) const ). 

Public Member Functions 

The following member functions are declared in the public interface: 

WCValOrderedVector ( size_ t = WCDEFAULT_ VECTOR_ LENGTH, unsigned = 
WCDEFAULT_ VECTOR_ RESIZE_ GROW ); 

WCValOrderedVector( const WCValOrderedVector & ); 
virtual -WCValOrderedVector() ; 

WCValSortedVector ( size_ t = WCDEFAULT_ VECTOR_ LENGTH, unsigned = 
WCDEFAULT_ VECTOR_ RESIZE_ GROW ); 

WCValSortedVector( const WCValSortedVector & ); 
virtual -WCValSortedVector() ; 
void clear(); 

int contains( const Type & ) const; 

unsigned entries!) const; 

int find( const Type &, Type & ) const; 

Type first!) const; 
int index! const Type & ) const; 
int insert( const Type & ); 
int isEmpty!) const; 

Type last!) const; 

int occurrencesOf( const Type & ) const; 

int remove( const Type & ); 

unsigned removeAll( const Type & ); 

int removeAt ( int ); 

int removeFirst(); 

int removeLast(); 

int resize ( size_ t ) ; 

The following public member functions are available for the WCValOrderedVector class only: 

int append! const Type & ); 

int insertAt( int, const Type & ) ; 

int prepend! const Type & ); 

Public Member Operators 

The following member operators are declared in the public interface: 

Type & operator [] ( int ) ; 

const Type & operator []( int ) const; 

WCValOrderedVector & WCValOrderedVector::operator =( const 
WCValOrderedVector & ); 
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WCValSortedVector<Type>, WCValOrderedVector<Type> 


WCValSortedVector & WCValSortedVector::operator =( const 
WCValSortedVector & ) ; 

int WCValOrderedVector::operator ==( const WCValOrderedVector & ) 
const; 

int WCValSortedVector::operator ==( const WCValSortedVector & ) 
const; 
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WCValOrderedVector<Type>:: WC ValOrderedVectorQ 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

WCValOrderedVector ( size_ t = WCDEFAULT_ VECTOR_ LENGTH, 
unsigned = WCDEFAULT_ VECTOR_ RESIZE_ GROW ); 

The WCValOrderedVector<Type> constructor creates an empty WCValOrderedVector object 
able to store the number of elements specified in the first optional parameter, which defaults to the 
constant WCDEFAULT_ VECTOR_ LENGTH (currently defined as 10). If tha:esize_ required 
exception is not enabled, then the second optional parameter is used to specify the value to increase the 
vector size when an element is inserted into a full vector. If zero(0) is specified as the second 
parameter, any attempt to insert into a full vector fails. This parameter defaults to the constant 
WCDEFAULT_ VECTOR_ RESIZE_ GROW (currently defined as 5). 

If the vector object cannot be fully initialized, the vector is created with length zero. 

The WCValOrderedVector<Type> constructor creates an empty initialized 
WCValOrderedVector object. 

WCExcept::resize_ required 
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WCValOrderedVector<Type>::WCValOrderedVector() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

WCValOrderedVector( const WCValOrderedVector & ) ; 

The WCValOrderedVector<Type> constructor is the copy constructor for the 
WCValOrderedVector class. The new vector is created with the same length and resize value as the 
passed vector. All of the vector elements and exception trap states are copied. 

If the new vector cannot be fully created, it will have length zero. The out_ of_ memory exception is 
thrown if enabled in the vector being copied. 

The WCValOrderedVector<Type> creates a WCValOrderedVector object which is a copy of 
the passed vector. 

operator =, WCExcept::out_ of_ memory 
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WCValOrderedVector<Type>::~WCValOrderedVector() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcvector.h> 
public: 

virtual ~WCValOrderedVector() ; 

The WCValOrderedVector<Type> destructor is the destructor for the WCValOrderedVector 
class. If the vector is not length zero and the not_ empty exception is enabled, the exception is 
thrown. Otherwise, the vector entries are cleared using the clear member function. The call to the 
WCValOrderedVector<Type> destructor is inserted implicitly by the compiler at the point where 
the WCValOrderedVector object goes out of scope. 

The WCValOrderedVector<Type> destructor destroys an WCValOrderedVector object, 
clear, WCExcept: : not_ empty 
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WCValSortedVector<Type>::WCValSortedVector() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

WCValSortedVector ( size_ t = WCDEFAULT_ VECTOR_ LENGTH, 
unsigned = WCDEFAULT_ VECTOR_ RESIZE_ GROW ); 

The WCValSortedVector<Type> constructor creates an empty WCValSortedVector object 
able to store the number of elements specified in the first optional parameter, which defaults to the 
constant WCDEFAULT_ VECTOR_ LENGTH (currently defined as 10). If tha:esize_ required 
exception is not enabled, then the second optional parameter is used to specify the value to increase the 
vector size when an element is inserted into a full vector. If zero(0) is specified as the second 
parameter, any attempt to insert into a full vector fails. This parameter defaults to the constant 
WCDEFAULT_ VECTOR_ RESIZE_ GROW (currently defined as 5). 

If the vector object cannot be fully initialized, the vector is created with length zero. 

The WCValSortedVector<Type> constructor creates an empty initialized 
WCValSortedVector object. 

WCExcept::resize_ required 
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WCValSortedVector<Type>::WCValSortedVector() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

WCValSortedVector( const WCValSortedVector & ) ; 

The WCValSortedVector<Type> constructor is the copy constructor for the 
WCValSortedVector class. The new vector is created with the same length and resize value as the 
passed vector. All of the vector elements and exception trap states are copied. 

If the new vector cannot be fully created, it will have length zero. The out_ of_ memory exception is 
thrown if enabled in the vector being copied. 

The WCValSortedVector<Type> constructor creates a WCValSortedVector object which is a 
copy of the passed vector. 

operator =, WCExcept: : out_ of_ memory 
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WCValSortedVector<Type>::~WCValSortedVector() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcvector.h> 
public: 

virtual ~WCValSortedVector() ; 

The WCValSortedVector<Type> destructor is the destructor for the WCValSortedVector 
class. If the vector is not length zero and the not_ empty exception is enabled, the exception is 
thrown. Otherwise, the vector entries are cleared using the clear member function. The call to the 
WCValSortedVector<Type> destructor is inserted implicitly by the compiler at the point where 
the WCValSortedVector object goes out of scope. 

The WCValSortedVector<Type> destructor destroys an WCValSortedVector object, 
clear, WCExcept: : not_ empty 
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WCValOrderedVector<Type>::append() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int append( const Type & ); 

The append public member function appends the passed element to be the last element in the vector. 
The data stored in the vector is a copy of the data passed as a parameter. This member function has the 
same semantics as the WCValOrderedVector : : insert member function. 

This function is not provided by the WCValSortedVector class, since all elements must be inserted 
in sorted order by the insert member function. 

Several different results can occur if the vector is not large enough for the new element. If the 
resize_ required exception is enabled, the exception is thrown. If the exception is not enabled, 
the append fails if the amount the vector is to be grown (the second parameter to the constructor) is 
zero(O). Otherwise, the vector is automatically grown by the number of elements specified to the 
constructor, using the resize member function. If resize fails, the element is not appended to the 
vector and the out_ of_ memory exception is thrown, if enabled. 

The append public member function appends an element to the WCValOrderedVector object. A 
TRUE (non-zero) value is returned if the append is successful. If the append fails, a FALSE (zero) 
value is returned. 

insert, insertAt, prepend, WCExcept: : out_ of_ memory, 

WCExcept::resize_ required 
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WCValSortedVector<Type>::clear(), WCValOrderedVector<Type>::clear() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcvector.h> 

public: 

void clear(); 

The clear public member function is used to clear the vector so that it contains no entries, and is zero 
size. Elements stored in the vector are destroyed using Type's destructor. The vector object is not 
destroyed and re-created by this function, so the object destructor is not invoked. 

The clear public member function clears the vector to have zero length and no entries. 

~WCValOrderedVector, operator = 
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WCValSortedVector<Type>,WCValOrderedVector<Type>::contains() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int contains( const Type & ) const; 

The contains public member function is used to determine if a value is contained by a vector. A 
linear search is used by the WCValOrderedVector class to find the value. The 
WCValSortedVector class uses a binary search. 

The contains public member function returns a TRUE (non-zero) value if the element is found in the 
vector. A FALSE (zero) value is returned if the vector does not contain the element. 

index, find 
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WCValSortedVector<Type>::entries(), WCValOrderedVector<Type>::entries() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcvector.h> 
public: 

unsigned entries() const; 

The entries public member function is used to find the number of elements which are stored in the 
vector. 

The entries public member function returns the number of elements in the vector, 
isEmpty 
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WCValSortedVector<Type>::find(), WCValOrderedVector<Type>::find() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int find( const Type &, Type & ) const; 

The find public member function is used to find an element equivalent to the first argument. The 
WCValOrderedVector class uses a linear search to find the element, and the 
WCValSortedVector class uses a binary search. 

If an equivalent element is found, a TRUE (non-zero) value is returned, and the second parameter is 
assigned the first equivalent value. A FALSE (zero) value is returned and the second parameter is 
unchanged if the element is not in the vector. 

contains, first, index, last, occurrencesOf, remove 
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WCValSortedVector<Type>::first(), WCValOrderedVector<Type>::first() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wcvector.h> 
public: 

Type first() const; 

The first public member function returns the first element in the vector. The element is not removed 
from the vector. 

If the vector is empty, one of two exceptions can be thrown. The empty_ container exception is 
thrown if it is enabled. Otherwise, if the index_ range exception is enabled, it is thrown. If neither 
exception is enabled, a first element of the vector is added with a default value. 

The first public member function returns the value of the first element in the vector. 

last, removeFirst, WCExcept: :index_ range,WCExcept: :resize_ required 
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WCValSortedVector<Type>::index(), WCValOrderedVector<Type>::index() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int index( const Type & ) const; 

The index public member function is used find the index of the first element equivalent to the passed 
element. A linear search is used by the WCValOrderedVector class to find the element. The 
WCValSortedVector class uses a binary search. 

The index public member function returns the index of the first element equivalent to the parameter. 
If the passed value is not contained in the vector, negative one (-1) is returned. 

contains, find, insertAt, operator [], removeAt 
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WCValSortedVector<Type>::insert(), WCValOrderedVector<Type>::insert() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int insert( const Type & ) ; 

The insert public member function inserts the value into the vector. The data stored in the vector is a 
copy of the data passed as a parameter. 

The WCValOrderedVector : : insert function inserts the value as the last element of the vector, 
and has the same semantics as the WCValOrderedVector: : append member function. 

A binary search is performed to determine where the value should be inserted for the 
WCValSortedVector : : insert function. Any elements greater than the inserted value are copied 
up one index (using Type's assignment operator), so that the new element is after all elements with 
value less than or equal to it. 

Several different results can occur if the vector is not large enough for the new element. If the 
resize_ required exception is enabled, the exception is thrown. If the exception is not enabled, 
the insert fails if the amount the vector is to be grown (the second parameter to the constructor) is 
zero(O). Otherwise, the vector is automatically grown by the number of elements specified to the 
constructor, using the resize member function. If resize fails, the element is not inserted to the 
vector and the out_ of_ memory exception is thrown, if enabled. 

The insert public member function inserts an element in to the vector. A TRUE (non-zero) value is 
returned if the insert is successful. If the insert fails, a FALSE (zero) value is returned. 

append, insertAt, prepend, WCExcept: : out_ of_ memory, 

WCExcept::resize_ required 
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WCValOrderedVector<Type>::insertAt() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int insertAt( int, const Type & ) ; 

The insertAt public member function inserts the second argument into the vector before the element 
at index given by the first argument. If the passed index is equal to the number of entries in the vector, 
the new value is appended to the vector as the last element. The data stored in the vector is a copy of 
the data passed as a parameter. All vector elements with indexes greater than or equal to the first 
parameter are copied (using Type's assignment operator) up one index. 

This function is not provided by the WCValSortedVector class, since all elements must be inserted 
in sorted order by the insert member function. 

If the passed index is negative or greater than the number of entries in the vector and the 
index_ range exception is enabled, the exception is thrown. If the exception is not enabled, the new 
element is inserted as the first element when the index is negative, or as the last element when the index 
is too large. 

Several different results can occur if the vector is not large enough for the new element. If the 
resize_ required exception is enabled, the exception is thrown. If the exception is not enabled, 
the insert fails if the amount the vector is to be grown (the second parameter to the constructor) is 
zero(O). Otherwise, the vector is automatically grown by the number of elements specified to the 
constructor, using the resize member function. If resize fails, the element is not inserted into the 
vector and the out_ of_ memory exception is thrown, if enabled. 

The insertAt public member function inserts an element into the WCValOrderedVector object 
before the element at the given index. A TRUE (non-zero) value is returned if the insert is successful. 

If the insert fails, a FALSE (zero) value is returned. 

append, insert, prepend, operator [], removeAt, WCExcept: :index_ range, 
WCExcept: : out_ of_ memoryljtfCExcept: : resize_ required 
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WCValSortedVector<Type>,WCValOrderedVector<Type>::isEmpty() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int isEmptyO const; 

The isEmpty public member function is used to determine if a vector object has any entries contained 
in it. 

A TRUE value (non-zero) is returned if the vector object does not have any vector elements contained 
within it. A FALSE (zero) result is returned if the vector contains at least one element. 

entries 
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WCValSortedVector<Type>::last(), WCValOrderedVector<Type>::last() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <wcvector.h> 
public: 

Type last() const; 

The last public member function returns the last element in the vector. The element is not removed 
from the vector. 

If the vector is empty, one of two exceptions can be thrown. The empty_ container exception is 
thrown if it is enabled. Otherwise, if the index_ range exception is enabled, it is thrown. If neither 
exception is enabled, a first element of the vector is added with a default value. 

The last public member function returns the value of the last element in the vector. 

first, removeLast, WCExcept: : index_ range,WCExcept: : resize_ required 
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WCValSortedVector<Type>,WCValOrderedVector<Type>::occurrencesOf() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int occurrencesOf( const Type & ) const; 

The occurrencesOf public member function returns the number of elements contained in the vector 
that are equivalent to the passed value. A linear search is used by the WCValOrderedVector class 
to find the value. The WCValSortedVector class uses a binary search. 

The occurrencesOf public member function returns the number of elements equivalent to the 
passed value. 

contains, find, index, operator [], removeAll 
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WCValSortedVector<Type>,WCValOrderedVector<Type>::operator []() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

Type & operator [] ( int ) ; 

const Type & operator []( int ) const; 

operator [] is the vector index operator. A reference to the object stored in the vector at the given 
index is returned. If a constant vector is indexed, a reference to a constant element is returned. 

The append, insert, insert At and prepend member functions are used to insert a new 
element into a vector, and the remove, removeAll, removeAt, removeFirst and 
removeLast member functions remove elements. The index operator cannot be used to change the 
number of entries in the vector. Searches may be performed using the find and index member 
functions. 

If the vector is empty, one of two exceptions can be thrown. The empty_ container exception is 
thrown if it is enabled. Otherwise, if the index_ range exception is enabled, it is thrown. If neither 
exception is enabled, a first element of the vector is added with a default value. This element is added 
so that a reference to a valid vector element can be returned. 

If the index value is negative and the index_ range exception is enabled, the exception is thrown. 

An attempt to index an element with index greater than or equal to the number of entries in the vector 
will also cause the index_ range exception to be thrown if enabled. If the exception is not enabled, 
attempting to index a negative element will index the first element in the vector, and attempting to index 
an element after the last entry will index the last element. 

Care must be taken when using the WCValSortedVector class not to change the ordering of the 
vector elements. The result returned by the index operator must not be assigned to or modified in such 
a way that it is no longer equivalent (by Type's equivalence operator) to the value inserted into the 
vector. Failure to comply may cause lookups to work incorrectly, since the binary search algorithm 
assumes elements are in sorted order. 

The operator [] public member function returns a reference to the element at the given index. If 
the index is invalid, a reference to the closest valid element is returned. The result of the non-constant 
index operator may be assigned to. 

append, find, first, index, insert, insertAt, isEmpty, last, prepend, remove, 
removeAt, removeAll, removeFirst, removeLast, WCExcept: :empty_ container, 
WCExcept::index_ range 


588 Vector Containers 




WCValSortedVector<Type>,WCValOrderedVector<Type>::operator =() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

WCValOrderedVector & WCValOrderedVector::operator =( const 
WCValOrderedVector & ) ; 

WCValSortedVector & WCValSortedVector::operator =( const 
WCValSortedVector & ) ; 

The operator = public member function is the assignment operator for the class. The left hand side 
vector is first cleared using the clear member function, and then the right hand side vector is copied. 
The left hand side vector is made to have the same length and growth amount as the right hand side (the 
growth amount is the second argument passed to the right hand side vector constructor). All of the 
vector elements and exception trap states are copied. 

If the left hand side vector cannot be fully created, it will have zero length. The out_ of_ memory 
exception is thrown if enabled in the right hand side vector. 

The operator = public member function assigns the left hand side vector to be a copy of the right 
hand side. 

clear, WCExcept: : out_ of_ memory 
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WCValSortedVector<Type>,WCValOrderedVector<Type>::operator ==() 


Synopsis: 


Semantics: 


Results: 


#include <wcvector.h> 
public: 

int WCValOrderedVector::operator ==( const WCValOrderedVector & ) 
const; 

int WCValSortedVector::operator ==( const WCValSortedVector & ) 
const; 

The operator == public member function is the equivalence operator for the class. Two vector 
objects are equivalent if they are the same object and share the same address. 

A TRUE (non-zero) value is returned if the left hand side and right hand side vectors are the same 
object. A FALSE (zero) value is returned otherwise. 
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WCValOrderedVector<Type>::prepend() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

int prepend( const Type & ); 

The prepend public member function inserts the passed element to be the first element in the vector. 
The data stored in the vector is a copy of the data passed as a parameter. All vector elements contained 
in the vector are copied (using Type's assignment operator) up one index. 

This function is not provided by the WCValSortedVector class, since all elements must be inserted 
in sorted order by the insert member function. 

Several different results can occur if the vector is not large enough for the new element. If the 
resize_ required exception is enabled, the exception is thrown. If the exception is not enabled, 
the prepend fails if the amount the vector is to be grown (the second parameter to the constructor) is 
zero(O). Otherwise, the vector is automatically grown by the number of elements specified to the 
constructor, using the resize member function. If resize fails, the element is not inserted to the 
vector and the out_ of_ memory exception is thrown, if enabled. 

The prepend public member function prepends an element to the WCValOrderedVector object. 

A TRUE (non-zero) value is returned if the insert is successful. If the insert fails, a FALSE (zero) value 
is returned. 

append, insert, insertAt, WCExcept: : out_ of_ memory, 

WCExcept::resize_ required 
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WCValSortedVector<Type>::remove(), WCValOrderedVector<Type>::remove() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int remove( const Type & ); 

The remove public member function removes the first element in the vector which is equivalent to the 
passed value. All vector elements stored after the removed elements are copied (using Type's 
assignment operator) down one index. 

A linear search is used by the WCValOrderedVector class to find the element being removed. The 
WCValSortedVector class uses a binary search. 

The remove public member function removes the first element in the vector which is equivalent to the 
passed value. A TRUE (non-zero) value is returned if an equivalent element was contained in the 
vector and removed. If the vector did not contain an equivalent value, a FALSE (zero) value is 
returned. 

clear, find, removeAll, removeAt, removeFirst, removeLast 
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WCValSortedVector<Type>,WCValOrderedVector<Type>::removeAII() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

unsigned removeAll( const Type & ) ; 

The removeAll public member function removes all elements in the vector which are equivalent to 
the passed value. All vector elements stored after the removed elements are copied (using Type's 
assignment operator) down one or more indexes to take the place of the removed elements. 

A linear search is used by the WCValOrderedVector class to find the elements being removed. The 
WCValSortedVector class uses a binary search. 

The removeAll public member function removes all elements in the vector which are equivalent to 
the passed value. The number of elements removed is returned. 

clear, find, occurrencesOf, remove, removeAt, removeFirst, removeLast 
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WCValSortedVector<Type>,WCValOrderedVector<Type>::removeAt() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int removeAt( int ) ; 

The removeAt public member function removes the element at the given index. All vector elements 
stored after the removed elements are copied (using Type's assignment operator) down one index. 

If the vector is empty and the empty_ container exception is enabled, the exception is thrown. 

If an attempt to remove an element with a negative index is made and the index_ range exception is 
enabled, the exception is thrown. If the exception is not enabled, the first element is removed from the 
vector. Attempting to remove an element with index greater or equal to the number of entries in the 
vector also causes the index_ range exception to be thrown if enabled. The last element in the vector 
is removed if the exception is not enabled. 

The removeAt public member function removes the element with the given index. If the index is 
invalid, the closest element to the given index is removed. A TRUE (non-zero) value is returned if an 
element was removed. If the vector was empty, FALSE (zero) value is returned. 

clear, insertAt, operator [], remove, removeAll, removeFirst, removeLast 
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WCValSortedVector<Type>,WCValOrderedVector<Type>::removeFirst() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int removeFirst() ; 

The removeFirst public member function removes the first element from a vector. All other vector 
elements are copied (using Type's assignment operator) down one index. 

If the vector is empty and the empty_ container exception is enabled, the exception is thrown. 

The removeFirst public member function removes the first element from the vector. A TRUE 
(non-zero) value is returned if an element was removed. If the vector was empty, FALSE (zero) value 
is returned. 

clear,first, remove, removeAt, removeAll, removeLast 
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WCValSortedVector<Type>,WCValOrderedVector<Type>::removeLast() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int removeLast() ; 

The removeLast public member function removes the last element from a vector. If the vector is 
empty and the empty_ container exception is enabled, the exception is thrown. 

The removeLast public member function removes the last element from the vector. A TRUE 
(non-zero) value is returned if an element was removed. If the vector was empty, FALSE (zero) value 
is returned. 

clear,last, remove, removeAt, removeAll, removeFirst 
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WCValSortedVector<Type>::resize(), WCValOrderedVector<Type>::resize() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int resize ( size_ t new_ size ) ; 

The resize public member function is used to change the vector size to be able to store new_size 
elements. If new_size is larger than the previous vector size, all elements are copied (using Type's 
copy constructor) into the newly sized vector, and new elements can be added using the append, 
insert, insertAt, and prepend member functions. If the vector is resized to a smaller size, 
the first new_size elements are copied (all vector elements if the vector contained new_size or fewer 
elements). The remaining elements are destroyed using Type's destructor. 

If the resize cannot be performed and the out_ of_ memory exception is enabled, the exception is 
thrown. 

The vector is resized to new_size. A TRUE value (non-zero) is returned if the resize is successful. A 
FALSE (zero) result is returned if the resize fails. 

WCExcept: : out_ of_ memory 
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WCValVector<Type> 


Declared: 


wcvector.h 

The WCValVector<Type> class is a templated class used to store objects in a vector. Vectors are 
similar to arrays, but vectors perform bounds checking and can be resized. Elements are inserted into 
the vector by assigning to a vector index. 

The WCValOrderedVector and WCValSortedVector classes are also available. They provide a 
more abstract view of the vector and additional functionality, including finding and removing elements. 

Values are copied into the vector, which could be undesirable if the stored objects are complicated and 
copying is expensive. Value vectors should not be used to store objects of a base class if any derived 
types of different sizes would be stored in the vector, or if the destructor for a derived class must be 
called. 

In the description of each member function, the text Type is used to indicate the template parameter 
defining the type of the elements stored in the vector. 

The WCExcept class is a base class of the WCValVector<Type> class and provides the 
exceptions member function. This member function controls the exceptions which can be thrown 
by the WCValVector<Type> object. No exceptions are enabled unless they are set by the 
exceptions member function. 

Requirements of Type 

The WCValVector<Type> class requires Type to have: 

A default constructor ( Type : : Type () ). 

A well defined copy constructor ( Type : : Type ( const Type & ) ). 

The following override of operator new () only if Type overrides the global operator 
new () : 

void * operator new ( size_ t, void *ptr ) { return ( ptr ); } 


Public Member Functions 

The following member functions are declared in the public interface: 

WCValVector ( size_ t = 0 ); 

WCValVector( size_t, const Type & ); 

WCValVector( const WCValVector & ); 

virtual ~WCValVector() ; 

void clear (); 

size_ t length () const; 

int resize ( size_ t ) ; 

Public Member Operators 

The following member operators are declared in the public interface: 

Type & operator [] ( int ) ; 
const Type & operator []( int ) const; 
WCValVector & operator =( const WCValVector & ); 
int operator ==( const WCValVector & ) const; 
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WCValVector<Type>::WCValVector() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

WCValVector ( size_ t = 0 ); 

The public WCValVector<Type> constructor creates a WCValVector<Type> object able to store 
the number of elements specified in the optional parameter, which defaults to zero. All vector elements 
are initialized with Type's default constructor. 

If the vector object cannot be fully initialized, the vector is created with length zero. 

The public WCValVector<Type> constructor creates an initialized WCValVector<Type> object 
with the specified length. 

WCValVector<Type>, ~WCValVector<Type> 
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WCValVector<Type>::WCValVector() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

WCValVector ( size_t, const Type & ); 

The public WCValVector<Type> constructor creates a WCValVector<Type> object able to store 
the number of elements specified by the first parameter. All vector elements are initialized to the value 
of the second parameter using Type's copy constructor. 

If the vector object cannot be fully initialized, the vector is created with length zero. 

The public WCValVector<Type> constructor creates an initialized WCValVector<Type> object 
with the specified length and elements set to the given value. 

WCValVector<Type>, ~WCValVector<Type> 
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WCValVector<Type>::WCValVector() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

WCValVector( const WCValVector & ); 

The public WCValVector<Type> constructor is the copy constructor for the 

WCValVector<Type> class. The new vector is created with the same length as the given vector. All 
of the vector elements and exception trap states are copied. 

If the new vector cannot be fully created, it will have length zero. The out_ of_ memory exception is 
thrown if enabled in the vector being copied. 

The public WCValVector<Type> constructor creates a WCValVector<Type> object which is a 
copy of the passed vector. 

operator =, WCExcept: : out_ of_ memory 
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WCValVector<Type>::~WCValVector() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcvector.h> 
public: 

virtual ~WCValVector() ; 

The public ~WCValVector<Type> destructor is the destructor for the WCValVector<Type> 
class. If the vector is not length zero and the not_ empty exception is enabled, the exception is 
thrown. Otherwise, the vector elements are cleared using the clear member function. The call to the 
public ~WCValVector<Type> destructor is inserted implicitly by the compiler at the point where the 
WCValVector<Type> object goes out of scope. 

The public ~WCValVector<Type> destructor destroys an WCValVector<Type> object, 
clear, WCExcept: : not_ empty 
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WCValVector<Type>::clear() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcvector.h> 

public: 

void clear(); 

The clear public member function is used to clear the vector so that it is of zero length. Elements 
stored in the vector are destroyed using Type's destructor. The vector object is not destroyed and 
re-created by this function, so the object destructor is not invoked. 

The clear public member function clears the vector to have zero length and no vector elements. 
~WCValVector<Type>, operator = 
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WCValVector<Type>::length() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <wcvector.h> 
public: 

size_t length() const; 

The length public member function is used to find the number of elements which can be stored in the 
WCValVector<Type> object. 

The length public member function returns the length of the vector, 
resize 
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WCValVector<Type>::operator []() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

Type & operator [] ( int ) ; 

const Type & operator []( int ) const; 

operator [] is the vector index operator. A reference to the object stored in the vector at the given 
index is returned. If a constant vector is indexed, a reference to a constant element is returned. The 
index operator of a non-constant vector is the only way to insert an element into the vector. 

If an attempt to access an element with index greater than or equal to the length of a non-constant vector 
is made and the resize_ required exception is enabled, the exception is thrown. If the exception is 
not enabled, the vector is automatically resized using the resize member function to have length the 
index value plus one. New vector elements are initialized using Type's default constructor. If the 
resize failed, and the out_ of_ memory exception is enabled, the exception is thrown. If the exception 
is not enabled and the resize failed, the last element is indexed (a new element if the vector was zero 
length). If a negative value is used to index the non-constant vector and the index_ range exception 
is enabled, the exception is thrown. If the exception is not enabled and the vector is empty, the 
resize_ required exception may be thrown. 

An attempt to index an empty constant vector may cause one of two exceptions to be thrown. If the 
empty_ container exception is enabled, it is thrown. Otherwise, theindex_ range exception is 
thrown, if enabled. If neither exception is enabled, a first vector element is added and indexed (so that a 
reference to a valid element can be returned). 

Indexing with a negative value or a value greater than or equal to the length of a constant vector causes 
the index_ range exception to be thrown, if enabled. 

The operator [] public member function returns a reference to the element at the given index. If 
the index is invalid, a reference to the closest valid element is returned. The result of the non-constant 
index operator may be assigned to. 

resize, WCExcept: :empty_ container,WCExcept: : index_ range, 

WCExcept: : out_ of_ memorytyJCExcept: : resize_ required 
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WCValVector<Type>::operator =() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <wcvector.h> 
public: 

WCValVector & operator =( const WCValVector & ); 

The operator = public member function is the assignment operator for the WCValVector<Type> 
class. The left hand side vector is first cleared using the clear member function, and then the right 
hand side vector is copied. The left hand side vector is made to have the same length as the right hand 
side. All of the vector elements and exception trap states are copied. 

If the left hand side vector cannot be fully created, it will have zero length. The out_ of_ memory 
exception is thrown if enabled in the right hand side vector. 

The operator = public member function assigns the left hand side vector to be a copy of the right 
hand side. 

clear, WCExcept: : out_ of_ memory 
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WCValVector<Type>: operator ==() 


Synopsis: 


Semantics: 


Results: 


#include <wcvector.h> 
public: 

int operator ==( const WCValVector & ) const; 

The operator == public member function is the equivalence operator for the 

WCValVector<Type> class. Two vector objects are equivalent if they are the same object and share 
the same address. 

A TRUE (non-zero) value is returned if the left hand side and right hand side vectors are the same 
object. A FALSE (zero) value is returned otherwise. 
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WCValVector<Type>::resize() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <wcvector.h> 
public: 

int resize ( size_ t new_ size ) ; 

The resize public member function is used to change the vector size to be able to store new_size 
elements. If new_size is larger than the previous vector size, all elements will be copied (using 
Type's copy constructor) into the newly sized vector, and new elements are initialized with Type's 
default constructor. If the vector is resized to a smaller size, the first new_size elements are copied. The 
remaining elements are destroyed using Type's destructor. 

If the resize cannot be performed and the out_ of_ memory exception is enabled, the exception is 
thrown. 

The vector is resized to new_size. A TRUE value (non-zero) is returned if the resize is successful. A 
FALSE (zero) result is returned if the resize fails. 

WCExcept: : out_ of_ memory 
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18 Input/Output Classes 


The input/output stream classes provide program access to the file system. In addition, various options for 
formatting of output and reading of input are provided. 
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filebuf 


Declared: fstream.h 

Derived from: streambuf 

The filebuf class is derived from the streambuf class, and provides additional functionality 
required to communicate with external files. Seek operations are supported when the underlying file 
supports seeking. Both input and output operations may be performed using a filebuf object, again 
when the underlying file supports read/write access. 

filebuf objects are buffered by default, so the reserve area is allocated automatically unless one is 
specified when the filebuf object is created. The get area and put area pointers operate as if they 
were tied together. There is only one current position in a filebuf object. 

The filebuf class allows only the get area or the put area , but not both, to be active at a time. This 
follows from the capability of files opened for both reading and writing to have operations of each type 
performed at arbitrary locations in the file. When writing is occurring, the characters are buffered in the 
put area. If a seek or read operation is done, the put area must be flushed before the next operation in 
order to ensure that the characters are written to the proper location in the file. Similarly, if reading is 
occurring, characters are buffered in the get area. If a write operation is done, the get area must be 
flushed and synchronized before the write operation in order to ensure the write occurs at the proper 
location in the file. If a seek operation is done, the get area does not have to be synchronized, but is 
discarded. When the get area is empty and a read is done, the underflow virtual member function 
reads more characters and fills the get area again. When the put area is full and a write is done, the 
overflow virtual member function writes the characters and makes the put area empty again. 

C++ programmers who wish to use files without deriving new objects do not need to explicitly create or 
use a filebuf object. 

Public Data Members 

The following data member is declared in the public interface. Its value is the default file protection 
that is used when creating new files. It is primarily referenced as a default argument in member 
functions. 

static int const openprot; 

Public Member Functions 

The following member functions are declared in the public interface: 
filebuf(); 

filebuf( filedesc ) ; 

filebuf( filedesc, char *, int ); 

-filebuf(); 

int is_open() const; 

filedesc fd() const; 

filebuf *attach( filedesc ); 

filebuf *open( char const *, 

ios::openmode, 

int = filebuf::openprot ); 

filebuf *close(); 

virtual int pbackfail( int ) ; 

virtual int overflow! int = EOF ); 

virtual int underflow!); 

virtual streambuf *setbuf( char *, int ); 
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filebuf 


See Also: 


virtual streampos seekoff( streamoff, 
ios::seekdir, 
ios::openmode ); 
virtual int sync() ; 

fstreambase, streambuf 
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filebuf::attach() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <fstream.h> 
public: 

filebuf *filebuf::attach( filedesc hdl ); 

The attach public member function connects an existing filebuf object to an open file via the 
file’s descriptor or handle specified by hdl. If the filebuf object is already connected to a file, the 
attach public member function fails. Otherwise, the attach public member function extracts 
information from the file system to determine the capabilities of the file and hence the filebuf 
object. 

The attach public member function returns a pointer to the filebuf object on success, otherwise 
NULL is returned. 

filebuf, fd, open 
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filebuf::close() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <fstream.h> 
public: 

filebuf *filebuf::close() ; 

The close public member function disconnects the filebuf object from a connected file and closes 
the file. Any buffered output is flushed before the file is closed. 

The close public member function returns a pointer to the filebuf object on success, otherwise 
NULL is returned. 

filebuf, fd, is_ open 
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filebuf::fd() 


Synopsis: 

Semantics 

Results: 

See Also: 


♦include <fstream.h> 
public: 

filedesc filebuf::fd() const; 

The f d public member function queries the state of the f ilebuf object file handle. 

The f d public member function returns the file descriptor or handle of the file to which the f ilebuf 
object is currently connected. If the f ilebuf object is not currently connected to a file, EOF is 
returned. 

filebuf::attach, is_ open 
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filebuf::filebuf() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <fstream.h> 
public: 

filebuf::filebuf() ; 

This form of the public f ilebuf constructor creates a f ilebuf object that is not currently connected 
to any file. A call to the f d member function for this created f ilebuf object returns EOF, unless a 
file is connected using the attach member function. 

The public f ilebuf constructor produces a f ilebuf object that is not currently connected to any 
file. 


-filebuf, attach, open 
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filebuf::filebuf() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <fstream.h> 
public: 

filebuf::filebuf( filedesc hdl ); 

This form of the public f ilebuf constructor creates a f ilebuf object that is connected to an open 
file. The file is specified via the hdl parameter, which is a file descriptor or handle. 

This form of the public f ilebuf constructor is similar to using the default constructor, and calling the 
attach member function. A call to the fd member function for this created f ilebuf object returns 
hdl. 

The public f ilebuf constructor produces a f ilebuf object that is connected to hdl. 

-filebuf, attach, open 
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filebuf::filebuf() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <fstream.h> 
public: 

filebuf::filebuf( filedesc hdl, char *buf, int len ); 

This form of the public f ilebuf constructor creates a f ilebuf object that is connected to an open 
file and that uses the buffer specified by buf and len. The file is specified via the hdl parameter, which 
is a file descriptor or handle. If buf is NULL and/or len is less than or equal to zero, the f ilebuf 
object is unbuffered, so that reading and/or writing take place one character at a time. 

This form of the public f ilebuf constructor is similar to using the default constructor, and calling the 
attach and setbuf member functions. 

The public f ilebuf constructor constructor produces a f ilebuf object that is connected to hdl. 
-filebuf, attach, open, setbuf 
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filebuf::~filebuf() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <fstream.h> 
public: 

filebuf::~filebuf() ; 

The public ~f ilebuf destructor closes the file if it was explicitly opened using the open member 
function. Otherwise, the destructor takes no explicit action. The streambuf destructor is called to 
destroy that portion of the f ilebuf object. The call to the public ~f ilebuf destructor is inserted 
implicitly by the compiler at the point where the f ilebuf object goes out of scope. 

The f ilebuf object is destroyed. 

-filebuf, close 
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filebuf::is_open() 


Synopsis: 

Semantics 

Results: 

See Also: 


#include <fstream.h> 
public: 

int filebuf::is_ open(); 

The is_ open public member function queries thef ilebuf object state. 

The is_ open public member function returns a non-zero value if the f ilebuf object is currently 
connected to a file. Otherwise, zero is returned. 

f ilebuf : : attach, close, fd, open 
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filebuf::open() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <fstream.h> 
public: 

filebuf *filebuf::open( const char *name, 

ios::openmode mode, 

int prot = filebuf::openprot ); 

The open public member function is used to connect the filebuf object to a file specified by the 
name parameter. The file is opened using the specified mode. For details about the mode parameter, 
see the description of ios : : openmode. The prot parameter specifies the file protection attributes to 
use when creating a file. 

The open public member function returns a pointer to the filebuf object on success, otherwise 
NULL is returned. 

filebuf, close, is_ open,openprot 
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filebuf::openprot 


Synopsis: #include <fstream.h> 

public: 

static int const filebuf::openprot; 

Semantics: The openprot public member data is used to specify the default file protection to be used when 

creating new files. This value is used as the default if no user specified value is provided. 

The default value is octal 0644. This is generally interpreted as follows: 

• Owner: read/write 

• Group: read 

• World: read 

Note that not all operating systems support all bits. 

See Also: f ilebuf, open 
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filebuf::overflow() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <fstream.h> 
public: 

virtual int filebuf::overflow( int ch = EOF ); 

The overflow public virtual member function provides the output communication to the file to which 
the f ilebuf object is connected. Member functions in the streambuf class call the overflow 
public virtual member function for the derived class when the put area is full. 

The overflow public virtual member function performs the following steps: 

1. If no buffer is present, a buffer is allocated with the streambuf: : allocate member 
function, which may call the doal locate virtual member function. The put area is then 
setup. If, after calling streambuf:: allocate, no buffer is present, the f ilebuf 
object is unbuffered and ch (if not EOF) is written directly to the file without buffering, and 
no further action is taken. 

2. If the get area is present, it is flushed with a call to the sync virtual member function. Note 
that the get area won’t be present if a buffer was set up in step 1. 

3. If ch is not EOF, it is added to the put area, if possible. 

4. Any characters in the put area are written to the file. 

5. The put area pointers are updated to reflect the new state of the put area. If the write did not 
complete, the unwritten portion of the put area is still present. If the put area was full before 
the write, ch (if not EOF) is placed at the start of the put area. Otherwise, the put area is 
empty. 

The overflow public virtual member function returns_NOT_ EOF on success, otherwifiOF is 

returned. 

streambuf::overflow 
filebuf::underflow 
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filebuf::pbackfail() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <fstream.h> 
public: 

virtual int filebuf::pbackfail( int ch ); 

The pbackfail public virtual member function handles an attempt to put back a character when there 
is no room at the beginning of the get area. The pbackfail public virtual member function first calls 
the sync virtual member function to flush the put area and then it attempts to seek backwards over ch 
in the associated file. 

The pbackfail public virtual member function returns ch on success, otherwise EOF is returned, 
streambuf::pbackfail 
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filebuf::seekoff() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <fstream.h> 
public: 

virtual streampos filebuf::seekoff( streamoff offset, 
ios::seekdir dir, 
ios::openmode mode ); 

The seekof f public virtual member function is used to position the f ilebuf object (and hence the 
file) to a particular offset so that subsequent input or output operations commence from that point. The 
offset is specified by the offset and dir parameters. 

Since the get area and put area pointers are tied together for the f ilebuf object, the mode parameter 
is ignored. 

Before the actual seek occurs, the get area and put area of the f ilebuf object are flushed via the 
sync virtual member function. Then, the new position in the file is calculated and the seek takes place. 

The dir parameter may be ios : : beg, ios : : cur, or ios : : end and is interpreted in conjunction 
with the offset parameter as follows: 

ios : : beg the offset is relative to the start and should be a positive value, 
ios : : cur the offset is relative to the current position and may be positive 
(seek towards end) or negative (seek towards start), 
ios : : end the offset is relative to the end and should be a negative value. 

If the dir parameter has any other value, or the offset parameter does not have an appropriate sign, the 
seekof f public virtual member function fails. 

The seekof f public virtual member function returns the new position in the file on success, otherwise 
EOF is returned. 

streambuf::seekoff 
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filebuf::setbuf() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <fstream.h> 
public: 

virtual streambuf *filebuf::setbuf( char *buf, int len ); 

The setbuf public virtual member function is used to offer a buffer, specified by buf and len to the 
f ilebuf object. If the bn/parameter is NULL or the len is less than or equal to zero, the request is to 
make the f ilebuf object unbuffered. 

If the f ilebuf object is already connected to a file and has a buffer, the offer is rejected. In other 
words, a call to the setbuf public virtual member function after the f ilebuf object has started to be 
used usually fails because the f ilebuf object has set up a buffer. 

If the request is to make the f ilebuf object unbuffered, the offer succeeds. 

If the buf is too small (less than five characters), the offer is rejected. Five characters are required to 
support the default putback area. 

Otherwise, the buf is acceptable and the offer succeeds. 

If the offer succeeds, the streambuf : : setb member function is called to set up the pointers to the 
buffer. The streambuf: : setb member function releases the old buffer (if present), depending on 
how that buffer was allocated. 

Calls to the setbuf public virtual member function are usually made by a class derived from the 
f stream class, not directly by a user program. 

The setbuf public virtual member function returns a pointer to the f ilebuf object on success, 
otherwise NULL is returned. 

streambuf::setbuf 
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filebuf::sync() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <fstream.h> 
public: 

virtual int filebuf::sync() ; 

The sync public virtual member function synchronizes the f ilebuf object with the external file or 
device. If the put area contains characters it is flushed. This leaves the file positioned after the last 
written character. If the get area contains buffered (unread) characters, file is backed up to be 
positioned after the last read character. 

Note that the get area and put area never both contain characters. 

The sync public virtual member function returns_NOT_ EOF on success, otherwiffiOF is returned. 

streambuf::sync 
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filebuf::underflo w() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <fstream.h> 
public: 

virtual int filebuf::underflow() ; 

The underflow public virtual member function provides the input communication from the file to 
which the f ilebuf object is connected. Member functions in the streambuf class call the 
underflow public virtual member function for the derived class when the get area is empty. 

The underflow public virtual member function performs the following steps: 

1. If no reserve area is present, a buffer is allocated with the streambuf : : allocate 
member function, which may call the doallocate virtual member function. If, after 
calling allocate, no reserve area is present, the f ilebuf object is unbuffered and a 
one-character reserve area (plus putback area) is set up to do unbuffered input. This buffer is 
embedded in the f ilebuf object. The get area is set up as empty. 

2. If the put area is present, it is flushed using the sync virtual member function. 

3. The unused part of the get area is used to read characters from the file connected to the 
f ilebuf object. The get area pointers are then set up to reflect the new get area. 

The underflow public virtual member function returns the first unread character of the get area, on 
success, otherwise EOF is returned. Note that the get pointer is not advanced on success. 

streambuf::underflow 
filebuf::overflow 
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fstream 


Declared: 
Derived from: 


See Also: 


fstream.h 

fstreambase, iostream 

The fstream class is used to access files for reading and writing. The file can be opened and closed, 
and read, write and seek operations can be performed. 

The fstream class provides very little of its own functionality. It is derived from both the 
fstreambase and iostream classes. The fstream constructors, destructor and member function 
provide simplified access to the appropriate equivalents in the base classes. 

Of the available I/O stream classes, creating an fstream object is the preferred method of accessing a 
file for both input and output. 

Public Member Functions 

The following public member functions are declared: 
fstream(); 

fstream( char const *, 

ios::openmode = ios::in|ios::out, 

int = filebuf::openprot ); 

fstream( filedesc ); 

fstream) filedesc, char *, int ); 

-fstream(); 

void open) char const *, 

ios::openmode = ios::in|ios::out, 

int = filebuf::openprot ); 

fstreambase, ifstream, iostream, ofstream 
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fstream::fstream() 


Synopsis: #include <fstream.h> 

public: 

fstream::fstream(); 


Semantics: 

Results: 
See Also: 


This form of the public f stream constructor creates an f stream object that is not connected to a 
file. The open or attach member functions should be used to connect the f stream object to a file. 

The public f stream constructor produces an f stream object that is not connected to a file. 

~fstream, open, fstreambase::attach 
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fstream::fstream() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <fstream.h> 
public: 

fstream::fstream( const char *name, 
ios::openmode mode = ios::in|ios::out, 
int prot = filebuf::openprot ); 

This form of the public f stream constructor creates an f stream object that is connected to the file 
specified by the name parameter, using the specified mode and prot parameters. The connection is 
made via the C library open function. 

The public f stream constructor produces an f stream object that is connected to the file specified 
by name. If the open fails, ios : : f ailbit and ios : : badbit are set in the error state in the 
inherited ios object. 

~fstream, open, openmode, openprot 
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fstream::fstream() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <fstream.h> 
public: 

fstream::fstream( filedesc hdl ); 

This form of the public f stream constructor creates an f stream object that is attached to the file 
specified by the hdl parameter. 

The public f stream constructor produces an f stream object that is attached to hdl. If the attach 
fails, ios: : f ailbit and ios: :badbit are set in the error state in the inherited ios object. 

~fstream, fstreambase::attach, fstreambase::fd 
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fstream::fstream() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <fstream.h> 
public: 

fstream::fstream( filedesc hdl, char *buf, int len ); 

This form of the public f stream constructor creates an f stream object that is connected to the file 
specified by the hdl parameter. The buffer specified by the buf and len parameters is offered to the 
associated f ilebuf object via the setbuf member function. If the Z?n/parameter is NULL or the len 
is less than or equal to zero, the f ilebuf is unbuffered, so that each read or write operation reads or 
writes a single character at a time. 

The public f stream constructor produces an f stream object that is attached to hdl. If the 
connection to hdl fails, ios : : f ailbit and ios : : badbit are set in the error state in the inherited 
ios object. If the setbuf fails, ios : : f ailbit is set in the error state in the inherited ios object. 

~fstream, filebuf::setbuf, fstreambase::attach 
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fstream::~fstream() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <fstream.h> 
public: 

fstream::~fstream(); 

The public ~f stream destructor does not do anything explicit. The call to the public ~f stream 
destructor is inserted implicitly by the compiler at the point where the f stream object goes out of 
scope. 

The public ~f stream destructor destroys the f stream object, 
fstream 


Input/Output Classes 633 




fstream::open() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <fstream.h> 
public: 

void fstream::open( const char *name, 
ios::openmode mode = ios::in|ios::out, 
int prot = filebuf::openprot ); 

The open public member function connects the f stream object to the file specified by the name 
parameter, using the specified mode and prot parameters. The mode parameter is optional and usually 
is not specified unless additional bits (such as ios : : binary or ios : : text) are to be specified. 
The connection is made via the C library open function. 

If the open fails, ios : : f ailbit is set in the error state in the inherited ios object. 

fstreambase::attach, fstreambase::close, fstreambase::fd, 
fstreambase::is_ open 
fstream::openmode, openprot 
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fstreambase 


Declared: 
Derived from: 
Derived by: 


See Also: 


fstream.h 
ios 

ifstream, ofstream, fstream 

The fstreambase class is a base class that provides common functionality for the three file-based 
classes, ifstream, ofstream and fstream. The fstreambase class is derived from the ios 
class, providing the stream state information, plus it provides member functions for opening and closing 
files. The actual file manipulation work is performed by the f ilebuf class. 

It is not intended that fstreambase objects be created. Instead, the user should create an 
ifstream, ofstream or fstream object. 

Protected Member Functions 

The following member functions are declared in the protected interface: 

fstreambase (); 

fstreambase! char const *, 

ios::openmode, 

int = filebuf::openprot ); 

fstreambase( filedesc ) ; 

fstreambase! filedesc, char *, int ); 

-fstreambase(); 

Public Member Functions 

The following member functions are declared in the public interface: 

void attach! filedesc ); 
void close (); 
filedesc fd() const; 
int is_open() const; 
void open! char const *, 
ios::openmode, 
int = filebuf::openprot ); 
filebuf *rdbuf() const; 
void setbuf( char *, int ); 

filebuf, fstream, ifstream, ofstream 
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fstreambase::attach() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <fstream.h> 
public: 

void fstreambase::attach( filedesc hdl ); 

The attach public member function connects the fstreambase object to the file specified by the 
hdl parameter. 

If the attach public member function fails, ios : : f ailbit bit is set in the error state in the 
inherited ios object. The error state in the inherited ios object is cleared on success. 

fstreambase: : fd, is_ open,open 


636 Input/Output Classes 




fstreambase::close() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <fstream.h> 
public: 

void fstreambase::close() ; 

The close public member function disconnects the f streambase object from the file with which it 
is associated. If the f streambase object is not associated with a file, the close public member 
function fails. 

If the close public member function fails, ios : : failbit is set in the error state in the inherited 
ios object. 

fstreambase: : fd, is_ open,open 
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fstreambase::fstreambase() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <fstream.h> 
protected: 

fstreambase::fstreambase() ; 

The protected f streambase constructor creates an f streambase object that is initialized, but not 
connected to anything. The open or attach member function should be used to connect the 
f streambase object to a file. 

The protected f streambase constructor produces an f streambase object. 

~fstreambase, attach, open 
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fstreambase::fstreambase() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <fstream.h> 
protected: 

fstreambase::fstreambase( char const *name, 

ios::openmode mode, 

int prot = filebuf::openprot ); 

This protected f streambase constructor creates an f streambase object that is initialized and 
connected to the file indicated by name using the specified mode and prot. The f streambase object 
is connected to the specified file via the open C library function. 

The protected f streambase constructor produces an f streambase object. If the call to open for 
the file fails, ios : : f ailbit and ios : : badbit are set in the error state in the inherited ios 
object. 

~fstreambase, open, openmode, openprot 
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fstreambase::fstreambase() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <fstream.h> 
protected: 

fstreambase::fstreambase( filedesc hdl ); 

This protected f streambase constructor creates an f streambase object that is initialized and 
connected to the open file specified by the hdl parameter. 

The protected f streambase constructor produces an f streambase object. If the attach to the file 
fails, ios: : f ailbit and ios: :badbit are set in the error state in the inherited ios object. 

~fstreambase, attach 
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fstreambase::fstreambase() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <fstream.h> 
protected: 

fstreambase::fstreambase( filedesc hdl, char *buf, int len ); 

This protected f streambase constructor creates an f streambase object that is initialized and 
connected to the open file specified by the hdl parameter. The buffer, specified by the buf and len 
parameters, is offered via the setbuf virtual member function to be used as the reserve area for the 
f ilebuf associated with the f streambase object. 

The protected f streambase constructor produces an f streambase object. If the attach to the file 
fails, ios : : f ailbit and ios : : badbit are set in the error state in the inherited ios object. 

~fstreambase, attach, setbuf 
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fstreambase::~fstreambase() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <fstream.h> 
protected: 

fstreambase::~fstreambase(); 

The protected ~f streambase destructor does not do anything explicit. The filebuf object 
associated with the f streambase object is embedded within the f streambase object, so the 
filebuf destructor is called. The ios destructor is called for that portion of the f streambase 
object. The call to the protected ~f streambase destructor is inserted implicitly by the compiler at 
the point where the f streambase object goes out of scope. 

The f streambase object is destroyed. 

fstreambase, close 
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fstreambase::is_open() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <fstream.h> 
public: 

int fstreambase::is_ open() const; 

The is_ open public member function queries the current state of the file associated with the 
f streambase object. Calling the is_ open public member function is equivalent to calling thefd 
member function and testing for EOF. 

The is_ open public member function returns a non-zero value if the f streambase object is 
currently connected to a file, otherwise zero is returned. 

fstreambase: :attach, fd, open 
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fstreambase::fd() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <fstream.h> 
public: 

filedesc fstreambase::fd() const; 

The f d public member function returns the file descriptor for the file to which the f streambase 
object is connected. 

The f d public member function returns the file descriptor for the file to which the f streambase 
object is connected. If the f streambase object is not currently connected to a file, EOF is returned. 

fstreambase: :attach, is_ open,open 
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fstreambase::open() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <fstream.h> 
public: 

void fstreambase::open( const char *name, 

ios::openmode mode, 

int prot = filebuf::openprot ); 

The open public member function connects the f streambase object to the file specified by name, 
using the specified mode and prot. The connection is made via the C library open function. 

If the open fails, ios : : f ailbit is set in the error state in the inherited ios object. The error state in 
the inherited ios object is cleared on success. 

fstreambase: :attach, close, fd, is_ open.openmode, openprot 
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fstreambase::rdbuf() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <fstream.h> 
public: 

filebuf *fstreambase::rdbuf() const; 

The rdbuf public member function returns the address of the filebuf object currently associated 
with the f streambase object. 

The rdbuf public member function returns a pointer to the filebuf object currently associated with 
the f streambase object If there is no associated filebuf, NULL is returned. 

ios::rdbuf 
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fstreambase::setbuf() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <fstream.h> 
public: 

void fstreambase::setbuf( char *buf, int len ); 

The setbuf public member function offers the specified buffer to the f ilebuf object associated 
with the f streambase object. The f ilebuf may or may not reject the offer, depending upon its 
state. 

If the offer is rejected, ios : : f ailbit is set in the error state in the inherited ios object, 
filebuf::setbuf 
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ifstream 


Declared: 
Derived from: 


See Also: 


fstream.h 

fstreambase, istream 

The ifstream class is used to access existing files for reading. Such files can be opened and closed, 
and read and seek operations can be performed. 

The ifstream class provides very little of its own functionality. Derived from both the 
fstreambase and istream classes, its constructors, destructor and member functions provide 
simplified access to the appropriate equivalents in those base classes. 

Of the available I/O stream classes, creating an ifstream object is the preferred method of accessing 
a file for input only operations. 

Public Member Functions 

The following public member functions are declared: 
ifstream(); 

ifstream( char const *, 

ios::openmode = ios::in, 

int = filebuf::openprot ); 

ifstream! filedesc ); 

ifstream! filedesc, char *, int ); 

~ifstream(); 

void open! char const *, 
ios::openmode = ios::in, 
int = filebuf::openprot ); 

fstream, fstreambase, istream, ofstream 
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ifstream::ifstream() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <fstream.h> 
public: 

ifstream::ifstream() ; 

This form of the public if stream constructor creates an if stream object that is not connected to a 
file. The open or attach member functions should be used to connect the if stream object to a 
file. 

The public if stream constructor produces an if stream object that is not connected to a file. 

-ifstream, open, fstreambase::attach 
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ifstream::ifstream() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <fstream.h> 
public: 

ifstream::ifstream( const char *name, 
ios::openmode mode = ios::in, 
int prot = filebuf::openprot ); 

This form of the public if stream constructor creates an if stream object that is connected to the 
file specified by the name parameter, using the specified mode and prot parameters. The connection is 
made via the C library open function. 

The public if stream constructor produces an if stream object that is connected to the file 
specified by name. If the open fails, ios : : f ailbit and ios : : badbit are set in the error state in 
the inherited ios object. 

~if stream, open, openmode, openprot, fstreambase: : attach, fstreambase: : fd, 
fstreambase::is_ open 
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ifstream::ifstream() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <fstream.h> 
public: 

ifstream::ifstream( filedesc hdl ); 

This form of the public if stream constructor creates an if stream object that is attached to the file 
specified by the hdl parameter. 

The public if stream constructor produces an if stream object that is attached to hdl. If the attach 
fails, ios: : f ailbit and ios: :badbit are set in the error state in the inherited ios object. 

fstreambase::attach 
~ifstream, open 
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ifstream::ifstream() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <fstream.h> 
public: 

ifstream::ifstream( filedesc hdl, char *buf, int len ); 

This form of the public if stream constructor creates an if stream object that is connected to the 
file specified by the hdl parameter. The buffer specified by the buf and len parameters is offered to the 
associated f ilebuf object via the setbuf member function. If the bw/parameter is NULL or the len 
is less than or equal to zero, the f ilebuf is unbuffered, so that each read or write operation reads or 
writes a single character at a time. 

The public if stream constructor produces an if stream object that is attached to hdl. If the 
connection to hdl fails, ios : : f ailbit and ios : : badbit are set in the error state in the inherited 
ios object. If the setbuf fails, ios : : f ailbit is set in the error state in the inherited ios object. 

fstreambase::attach, fstreambase::setbuf 
~ifstream, open 


652 Input/Output Classes 




ifstream::~ifstream() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <fstream.h> 
public: 

ifstream::~ifstream(); 

The public ~if stream destructor does not do anything explicit. The call to the public -if stream 
destructor is inserted implicitly by the compiler at the point where the if stream object goes out of 
scope. 

The public -if stream destructor destroys the if stream object, 
ifstream 
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ifstream::open() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <fstream.h> 
public: 

void ifstream::open( const char *name, 
ios::openmode mode = ios::in, 
int prot = filebuf::openprot ); 

The open public member function connects the if stream object to the file specified by the name 
parameter, using the specified mode and prot parameters. The mode parameter is optional and usually 
is not specified unless additional bits (such as ios : : binary or ios : : text) are to be specified. 
The connection is made via the C library open function. 

If the open fails, ios : : f ailbit is set in the error state in the inherited ios object. 

fstreambase::attach, fstreambase::close, fstreambase::fd, 
fstreambase::is_ open 
ifstream::openmode, openprot 
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Declared: 


iostream.h 


Derived by: 


istream, ostream 

The ios class is used to group together common functionality needed for other derived stream classes. 

It is not intended that objects of type ios be created. 

This class maintains state information about the stream, (the ios name can be thought of as a 
short-form for I/O State). Error flags, formatting flags, and values and the connection to the buffers 
used for the input and output are all maintained by the ios class. No information about the buffer itself 
is stored in an ios object, merely the pointer to the buffer information. 

Protected Member Functions 

The following member functions are declared in the protected interface: 
ios () ; 

void init( streambuf * ) ; 
void setstate( ios::iostate ); 

Public Enumerations 

The following enumeration typedefs are declared in the public interface: 

typedef int iostate; 

typedef long fmtflags; 

typedef int openmode; 

typedef int seekdir; 

Public Member Functions 

The following member functions are declared in the public interface: 

ios( streambuf * ); 

virtual -ios (); 

ostream *tie() const; 

ostream *tie ( ostream * ); 

streambuf *rdbuf() const; 

ios:: iostate rdstateO const; 

ios::iostate clear( ios::iostate = 0 ); 

int good() const; 

int bad() const; 

int fail() const; 

int eof() const; 

ios::iostate exceptions ( ios::iostate ); 
ios::iostate exceptions() const; 

ios::fmtflags setf( ios::fmtflags, ios::fmtflags ); 

ios::fmtflags setf( ios::fmtflags ); 

ios::fmtflags unsetf( ios::fmtflags ); 

ios::fmtflags flags( ios::fmtflags ); 

ios::fmtflags flags() const; 

char fill ( char ); 

char fill() const; 

int precision ( int ); 

int precision () const; 

int width( int ); 

int width() const; 
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See Also: 


long &iword( int ); 
void *&pword( int ); 
static void sync_ with_ stdio () ; 
static ios : : fmtflags bitallocO; 
static int xalloc() ; 

Public Member Operators 

The following member operators are declared in the public interface 

operator void *() const; 
int operator !() const; 

iostream, istream, ostream, streambuf 
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ios::bad() 


Synopsis: 

Semantics 

Results: 

See Also: 


♦include <iostream.h> 
public: 

int ios::bad() const; 

The bad public member function queries the state of the ios object. 

The bad public member function returns a non-zero value if ios : : badbit is set in the error state in 
the inherited ios object, otherwise zero is returned. 

ios :: clear, eof, fail, good, iostate, operator !, operator void *, rdstate, 
setstate 
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ios::bitalloc() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <iostream.h> 
public: 

static ios::fmtflags ios::bitalloc (); 

The bitalloc public static member function is used to allocate a new ios : : fmtf lags bit for use 
by user derived classes. 

Because the bitalloc public static member function manipulates static member data, its behavior 
is not tied to any one object but affects the entire class of objects. The value that is returned by the 
bitalloc public static member function is valid for all objects of all classes derived from the ios 
class. No subsequent call to the bitalloc public static member function will return the same value as 
a previous call. 

The bit value allocated may be used with the member functions that query and affect 
ios : : fmtf lags. In particular, the bit can be set with the setf or flags member functions or the 
setiosf lags manipulator, and reset with the unsetf or flags member functions or the 
resetiosf lags manipulator. 

There are two constants defined in <io stream. h> which indicate the number of bits available when 
a program starts. _ LAST_ FORMAT_ FLAG indicates the last bit used by the built-in format flags 
described by ios : : fmtf lags. _ LAST_ FLAG_ BIT indicates the last bit that is available for the 
bitalloc public static member function to allocate. The difference between the bit positions 
indicates how many bits are available. 

The bitalloc public static member function returns the next available ios : : fmtf lags bit for use 
by user derived classes. If no more bits are available, zero is returned. 

ios::fmtflags 
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ios::clear() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <iostream.h> 
public: 

iostate ios::clear( ios::iostate flags = 0 ); 

The clear public member function is used to change the current value of ios : : iostate in the 
ios object, ios : : iostate is cleared, all bits specified in flags are set. 

The clear public member function returns the previous value of ios : : iostate. 

ios::bad, eof, fail, good, iostate, operator !, operator void *, rdstate, 
setstate 
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ios::eof() 


Synopsis: 

Semantics 

Results: 

See Also: 


♦include <iostream.h> 
public: 

int ios::eof() const; 

The eof public member function queries the state of the ios object. 

The eof public member function returns a non-zero value if ios : : eof bit is set in the error state in 
the inherited ios object, otherwise zero is returned. 

ios: :bad, clear, fail, good, iostate, rdstate, setstate 
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ios::exceptions() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <iostream.h> 
public: 

ios::iostate ios::exceptions() const; 
ios::iostate ios::exceptions( int enable ); 

The exceptions public member function queries and/or sets the bits that control which exceptions 
are enabled, ios : : iostate within the ios object is used to enable and disable exceptions. 

When a condition arises that sets a bit in ios : : iostate, a check is made to see if the same bit is also 
set in the exception bits. If so, an exception is thrown. Otherwise, no exception is thrown. 

The first form of the exceptions public member function looks up the current setting of the 
exception bits. The bit values are those described by ios: : iostate. 

The second form of the exceptions public member function sets the exceptions bits to those 
specified in the enable parameter, and returns the current settings. 

The exceptions public member function returns the previous setting of the exception bits, 
ios::clear, iostate, rdstate, setstate 
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ios::fail() 


Synopsis: 

Semantics 

Results: 

See Also: 


♦include <iostream.h> 
public: 

int ios::fail() const; 

The fail public member function queries the state of the ios object. 

The fail public member function returns a non-zero value if ios : : failbit or ios : : badbit is 
set in the error state in the inherited ios object, otherwise zero is returned. 

ios ::bad, clear, eof, good, iostate, operator !, operator void *, rdstate, 
setstate 
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ios::fill() 


Synopsis: #include <iostream.h> 

public: 

char ios::fill() const; 

char ios::fill( char fillchar ); 


Semantics: 


Results: 
See Also: 


The fill public member function queries and/or sets the fill character used when the size of a 
formatted object is smaller than the, format width specified. 

The first form of the fill public member function looks up the current value of the fill character. 
The second form of the fill public member function sets the fill character to fillchar. 

By default, the fill character is a space. 

The fill public member function returns the previous value of the fill character. 
ios: : fmtf lags, manipulator setfill 
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ios::flags() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <iostream.h> 
public: 

ios::fmtflags ios::flags() const; 

ios::fmtflags ios::flags( ios::fmtflags setbits ); 

The flags public member function is used to query and/or set the value of ios : : fmtf lags in the 
ios object. 

The first form of the flags public member function looks up the current ios : : fmtf lags value. 

The second form of the flags public member function sets ios: : fmtf lags to the value specified 
in the setbits parameter. 

Note that the setf public member function only turns bits on, while the flags public member 
function turns some bits on and some bits off. 

The flags public member function returns the previous ios : : fmtf lags value. 

ios : : fmtflags, setf, unsetf, manipulator dec, manipulator hex, manipulator oct, 
manipulator resetiosflags, manipulator setbase, manipulator setiosflags 
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ios::fmtflags 


Synopsis: #include <iostream.h> 

public: 

enum fmt_ flags { 

skipws = 0x0001, // skip whitespace 

left = 0x0002, // align field to left edge 

right = 0x0004, // align field to right edge 

internal = 0x0008, // sign at left, value at right 

dec = 0x0010, // decimal conversion for integers 

oct = 0x0020, // octal conversion for integers 

hex = 0x0040, // hexadecimal conversion for integers 

showbase = 0x0080, // show dec/octal/hex base on output 

showpoint = 0x0100, // show decimal and digits on output 

uppercase = 0x0200, // use uppercase for format characters 

showpos = 0x0400, // use + for output positive numbers 

scientific = 0x0800, // use scientific notation for output 

fixed = 0x1000, // use floating notation for output 

unitbuf = 0x2000, // flush stream after output 

stdio = 0x4000, // flush stdout/stderr after output 

basefield = dec | oct | hex, 
adjustfield= left | right | internal, 
floatfield = scientific | fixed 
} ; 

typedef long fmtflags; 

Semantics: The type ios : : fmt_ flags is a set of bits representing methods of formatting objects written to the 

stream and interpreting objects read from the stream. The ios : : fmtflags member typedef 
represents the same set of bits, but uses a long to represent the values, thereby avoiding problems 
made possible by the compiler’s ability to use smaller types for enumerations. All uses of these bits 
should use the ios: : fmtflags member typedef. 

The bit values defined by the ios : : fmtflags member typedef are set and read by the member 
functions setf, unsetf and flags, as well as the manipulators setiosflags and 
resetiosflags. 

Because one field is used to store all of these bits, there are three special values used to mask various 
groups of bits. These values are named ios: : basefield, ios: : ad justf ield and 
ios : : floatfield, and are discussed with the bits that they are used to mask. 

ios : : skipws controls whether or not whitespace characters are automatically skipped when using an 
operator >> extractor. If ios : : skipws is on, any use of the operator >> extractor skips 
whitespace characters before inputting the next item. Otherwise, skipping of whitespace characters 
must be handled by the program. 

ios : : left, ios : : right and ios : : internal control the alignment of items written using an 
operator << inserter. These bits are usually used in conjunction with the format width and fill 
character. 

ios : : ad justf ield can be used to mask the alignment bits returned by the setf, unsetf and 
flags member functions, and for setting new values to ensure that no other bits are accidentally 
affected. 

When the item to be written is smaller than the format width specified,//// characters are written to 
occupy the additional space. If ios : : left is in effect, the item is written in the left portion of the 
available space, and fill characters are written in the right portion. If ios : : right is in effect, the 
item is written in the right portion of the available space, and fill characters are written in the left 
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ios::fmtflags 


portion. If ios : : internal is in effect, any sign character or base indicator is written in the left 
portion, the digits are written in the right portion, and fill characters are written in between. 

If no alignment is specified, ios : : right is assumed. 

If the item to be written is as big as or bigger than the format width specified, no fill characters are 
written and the alignment is ignored. 

ios : : dec, ios : : oct and ios : : hex control the base used to format integers being written to the 
stream, and also control the interpretation of integers being read from the stream. 

ios: :basefield can be used to mask the base bits returned by the member functions set f, 
unsetf and flags, and for setting new values to ensure that no other bits are accidentally affected. 

When an integer is being read from the stream, these bits control the base used for the interpretation of 
the digits. If none of these bits is set, a number that starts with Ox or OX is interpreted as hexadecimal 
(digits 012 3456789, plus the letters abcdef or ABCDEF), a number that starts with 0 (zero) is 
interpreted as octal (digits 01234567), otherwise the number is interpreted as decimal (digits 
012 34 5 67 89). If one of the bits is set, then the prefix is not necessary and the number is interpreted 
according to the bit. 

When any one of the integer types is being written to the stream, it can be written in decimal, octal or 
hexadecimal. If none of these bits is set, ios : : dec is assumed. 

If ios : : dec is set (or assumed), the integer is written in decimal (digits 0123456789). No prefix is 
included. 

If ios : : oct is set, the integer is written in octal (digits 012 34 5 67). No sign character is written, as 
the number is treated as an unsigned quantity upon conversion to octal. 

If ios : : hex is set, the integer is written in hexadecimal (digits 0123456789, plus the letters 
abcdef or ABCDEF, depending on the setting of ios : : uppercase). No sign character is written, 
as the number is treated as an unsigned quantity upon conversion to hexadecimal. 

ios : : showbase controls whether or not integers written to the stream in octal or hexadecimal form 
have a prefix that indicates the base of the number. If the bit is set, decimal numbers are written 
without a prefix, octal numbers are written with the prefix 0 (zero) and hexadecimal numbers are 
written with the prefix Ox or OX depending on the setting of ios : : uppercase. If the 
ios : : showbase is not set, no prefixes are written. 

ios : : showpoint is used to control whether or not the decimal point and trailing zeroes are trimmed 
when floating-point numbers are written to the stream. If the bit is set, no trimming is done, causing the 
number to appear with the specified/ormaf precision. If the bit is not set, any trailing zeroes after the 
decimal point are trimmed, and if not followed by any digits, the decimal point is removed as well. 

ios : : uppercase is used to force to upper-case all letters used in formatting numbers, including the 
letter-digits abcdef, the x hexadecimal prefix, and the e used for the exponents in floating-point 
numbers. 

ios : : showpos controls whether or not a + is added to the front of positive integers being written to 
the stream. If the bit is set, the number is positive and the number is being written in decimal, a + is 
written before the first digit. 
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ios::fmtflags 


ios : : scientific and ios : : fixed controls the form used for writing floating-point numbers to 
the stream. Floating-point numbers can be written in scientific notation (also called exponential 
notation) or in fixed-point notation. 

ios : : f loatf ield can be used to mask the floating-format bits returned by the member functions 
setf, unsetf and flags, and for setting new values to ensure that no other bits are accidentally 
affected. 

If ios: :scientificis set, the floating-point number is written with a leading - sign (for negative 
numbers), a digit, a decimal point, more digits, an e (or E if ios : : uppercase is set), a + or - sign, 
and two or three digits representing the exponent. The digit before the decimal is not zero unless the 
number is zero. The total number of digits before and after the decimal is equal to the specified format 
precision. If ios : : showpoint is not set, trimming of the decimal and digits following the decimal 
may occur. 

If ios : : fixed is set, the floating-point number is written with a - sign (for negative numbers), at 
least one digit, the decimal point, and as many digits following the decimal as specified by the format 
precision. If ios : : showpoint is not set, trimming of the decimal and digits following the decimal 
may occur. 

If neither ios : : scientific nor ios : : fixed is specified, the floating-point number is formatted 
using scientific notation provided one or both of the following conditions are met: 

• the exponent is less than -4, or, 

• the exponent is greater than the format precision. 

Otherwise, fixed-point notation is used. 

ios : : unitbuf controls whether or not the stream is flushed after each item is written. If the bit is 
set, every item that is written to the stream is followed by a flush operation, which ensures that the I/O 
stream buffer associated with the stream is kept empty, immediately transferring the data to its final 
destination. 

ios : : stdio controls whether or not the stream is synchronized after each item is written. If the bit is 
set, every item that is written to the stream causes the stream to be synchronized, which means any input 
or output buffers are flushed so that an I/O operation performed using C (not C++) I/O behaves in an 
understandable way. If the output buffer was not flushed, writing using C++ and then C I/O functions 
could cause the output from the C functions to appear before the output from the C++ functions, since 
the characters might be sitting in the C++ output buffer. Similarly, after the C output operations are 
done, a call should be made to the C library f flush function on the appropriate stream before 
resuming C++ output operations. 

See Also: ios : : flags, setf, unsetf, manipulator dec, manipulator hex, manipulator oct, manipulator 

resetiosf lags, manipulator setbase, manipulator setiosflags 


Input/Output Classes 667 




ios::good() 


Synopsis: 

Semantics 

Results: 

See Also: 


♦include <iostream.h> 
public: 

int ios::good() const; 

The good public member function queries the state of the ios object. 

The good public member function returns a non-zero value if none of ios : : iostate is clear, 
otherwise zero is returned. 

ios: :bad, clear, eof, fail, iostate, rdstate, setstate 
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Synopsis: 

Semantics: 


Results: 
See Also: 


ios::init() 


♦include <iostream.h> 
protected: 

void ios::init( streambuf *sb ); 

The init public protected member function is used by derived classes to explicitly initialize the ios 
portion of the derived object, and to associate a streambuf with the ios object. The init public 
protected member function performs the following steps: 

1. The default/;// character is set to a space. 

2. The format precision is set to six. 

3. The streambuf pointer (returned by the rdbuf member function) is set to sb. 

4. The remaining fields of the ios object are initialized to zero. 

If sb is NULL the ios : : badbit is set in the error state in the inherited ios object, 
ios, rdbuf 
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ios::ios() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
protected: 
ios::ios(); 

This form of the protected ios constructor creates a default ios object that is initialized, but does not 
have an associated streambuf. Initialization of an ios object is handled by the init protected 
member function. 

This protected ios constructor creates an ios object and sets ios : : badbit in the error state in the 
inherited ios object. 

~ios, init 
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ios::ios() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

ios::ios( streambuf *sb ); 

This form of the public ios constructor creates an ios object that is initialized and has an associated 
streambuf. Initialization of an ios object is handled by the init protected member function. 

Once the init protected member function is completed, the ios object’s streambuf pointer is set 
to sb. If sb is not NULL, ios : : badbit is cleared from the error state in the inherited ios object. 

This public ios constructor creates an ios object and, if sb is NULL, sets ios : : badbit in the error 
state in the inherited ios object. 

~ios, init 
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ios::~ios() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <iostream.h> 
public: 

virtual ios::~ios(); 

The public virtual ~ios destructor destroys an ios object. The call to the public virtual ~ios 
destructor is inserted implicitly by the compiler at the point where the ios object goes out of scope. 

The ios object is destroyed. 

ios 
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ios::iostate 


Synopsis: 


Semantics: 


See Also: 


#include <iostream.h> 
public: 

enum io_ state { 

goodbit = 0x00, // no errors 

badbit = 0x01, // operation failed, may not proceed 
failbit = 0x02, // operation failed, may proceed 
eofbit = 0x04 // end of file encountered 
} ; 

typedef int iostate; 

The type ios : : io_ state is a set of bits representing the current state of the stream. The 
ios: :iostate member typedef represents the same set of bits, but uses an int to represent the 
values, thereby avoiding problems made possible by the compiler’s ability to use smaller types for 
enumerations. All uses of these bits should use the ios : : iostate member typedef. 

The bit values defined by the ios : : iostate member typedef can be read and set by the member 
functions rdstate and clear, and can be used to control exception handling with the member 
function exceptions. 

ios : : badbit represents the state where the stream is no longer usable because of some error 
condition. 

ios : : failbit represents the state where the previous operation on the stream failed, but the stream 
is still usable. Subsequent operations on the stream are possible, but the state must be cleared using the 
clear member function. 

ios : : eofbit represents the state where the end-of-file condition has been encountered. The stream 
may still be used, but the state must be cleared using the clear member function. 

Even though ios : : goodbit is not a bit value (because its value is zero, which has no bits on), it is 
provided for completeness. 

ios ::bad, clear, eof, fail, good, operator !, operator void *, rdstate, 
setstate 
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ios::iword() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <iostream.h> 
public: 

long &ios::iword( int index ); 

The iword public member function creates a reference to a long int, which may be used to store 
and retrieve any suitable integer value. The index parameter specifies which long int is to be 
referenced and must be obtained from a call to the xalloc static member function. 

Note that the iword and pword public member functions return references to the same storage with a 
different type. Therefore, each index obtained from the xalloc static member function can be used 
only for an integer or a pointer, not both. 

Since the iword public member function returns a reference and the ios class cannot predict how 
many such items will be required by a program, it should be assumed that each call to the xalloc 
static member function invalidates all previous references returned by the iword public member 
function. Therefore, the iword public member function should be called each time the reference is 
needed. 

The iword public member function returns a reference to a long int. 
ios::pword, xalloc 
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iosr.openmode 


Synopsis: #include <iostream.h> 

public: 

enum open_ mode { 

in = 0x0001, // open for input 

out = 0x0002, // open for output 

atend = 0x0004, // seek to end after opening 

append = 0x0008, // open for output, append to the end 

truncate = 0x0010, // discard contents after opening 

nocreate = 0x0020, // open only an existing file 

noreplace = 0x0040, // open only a new file 

text = 0x0080, // open as text file 

binary = 0x0100, // open as binary file 

app = append, // synonym 
ate = atend, // synonym 
trunc = truncate // synonym 
} ; 

typedef int openmode; 

Semantics: The type ios : : open_ mode is a set of bits representing ways of opening a stream. The 

ios : : openmode member typedef represents the same set of bits, but uses an int to represent the 
values, thereby avoiding problems made possible by the compiler’s ability to use smaller types for 
enumerations. All uses of these bits should use the ios : : openmode member typedef. 

The bit values defined by ios : : openmode member typedef can be specified in the constructors for 
stream objects, as well as in various member functions. 

ios : : in is specified in a stream for which input operations may be performed, ios : : out is 
specified in a stream for which output operations may be performed. A stream for which only 
ios : : in is specified is referred to as an input stream. A stream for which only ios : : out is 
specified is referred to as an output stream. A stream where both ios : : in and ios : : out are 
specified is referred to as an input/output stream. 

ios : : atend and ios : : ate are equivalent, and either one is specified for streams that are to be 
positioned to the end before the first operation takes place, ios : ate is provided for historical 
purposes and compatibility with other implementations of I/O streams. Note that this bit positions the 
stream to the end exactly once, when the stream is opened. 

ios : : append and ios : : app are equivalent, and either one is specified for streams that are to be 
positioned to the end before any and all output operations take place, ios : : app is provided for 
historical purposes and compatibility with other implementations of I/O streams. Note that this bit 
causes the stream to be positioned to the end before each output operation, while ios : : atend causes 
the stream to be positioned to the end only when first opened. 

ios : : truncate and ios : : trunc are equivalent, and either one is specified for streams that are to 
be truncated to zero length before the first operation takes place, ios : : trunc is provided for 
historical purposes and compatibility with other implementations of I/O streams. 

ios : : nocreate is specified if the file must exist before it is opened. If the file does not exist, an 
error occurs. 

ios : : noreplace is specified if the file must not exist before it is opened. That is, the file must be a 
new file. If the file exists, an error occurs. 
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ios::openmode 


ios : : text is specified if the file is to be treated as a text file. A text file is divided into records, and 
each record is terminated by a new-line character, usually represented as ' \n' . The new-line 
character is translated into a form that is compatible with the underlying file system’s concept of text 
files. This conversion happens automatically whenever the new-line is written to the file, and the 
inverse conversion (to the new-line character) happens automatically whenever the end of a record is 
read from the file system. 

ios : : binary is specified if the file is to be treated as a binary file. Binary files are streams of 
characters. No character has a special meaning. No grouping of characters into records is apparent to 
the program, although the underlying file system may cause such a grouping to occur. 

The following default behaviors are defined: 

If ios : : out is specified and none of ios : : in, ios : : append or ios : : atend are specified, 
ios : : truncate is assumed. 

If ios : : append is specified, ios : : out is assumed. 

If ios : : truncate is specified, ios : : out is assumed. 

If neither ios : :text nor ios : : binary is specified, ios : :text is assumed. 
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ios::operator!() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

int ios::operator !() const; 

The operator ! public member function tests the error state in the inherited ios object of the ios 
object. 

The operator ! public member function returns a non-zero value if either of ios : : f ailbit or 
ios : : badbit bits are set in the error state in the inherited ios object, otherwise zero is returned. 

ios: :bad, clear, fail, good, iostate, operator void *, rdstate, setstate 
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ios::operator void *() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

ios::operator void *() const; 

The operator void * public member function converts the ios object into a pointer to void. 
The actual pointer value returned is meaningless and intended only for comparison with NULL to 
determine the error state in the inherited ios object of the ios object. 

The operator void * public member function returns a NULL pointer if either of 

ios : : f ailbit or ios : : badbit bits are set in the error state in the inherited ios object, 

otherwise a non- NULL pointer is returned. 

ios: :bad, clear, fail, good, iostate, operator !, rdstate, setstate 
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ios::precision() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <iostream.h> 
public: 

int ios::precision() const; 
int ios::precision ( int prec ); 

The precision public member function is used to query and/or set the format precision. The format 
precision is used to control the number of digits of precision used when formatting floating-point 
numbers. For scientific notation, th e format precision describes the total number of digits before and 
after the decimal point, but not including the exponent. For fixed-point notation, the format precision 
describes the number of digits after the decimal point. 

The first form of the precision public member function looks up the current format precision. 

The second form of the precision public member function sets the format precision to prec. 

By default, the format precision is six. If prec is specified to be less than zero, the format precision is 
set to six. Otherwise, the specified/ormaf precision is used. For scientific notation, a format precision 
of zero is treated as a precision of one. 

The precision public member function returns the previous format precision setting, 
ios : : fmtf lags, manipulator setprec 
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ios::pword() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <iostream.h> 
public: 

void * &ios::pword( int index ); 

The pword public member function creates a reference to a void pointer, which may be used to store 
and retrieve any suitable pointer value. The index parameter specifies which void pointer is to be 
referenced and must be obtained from a call to the xalloc static member function. 

Note that the iword and pword public member functions return references to the same storage with a 
different type. Therefore, each index obtained from the xalloc static member function can be used 
only for an integer or a pointer, not both. 

Since the pword public member function returns a reference and the ios class cannot predict how 
many such items will be required by a program, it should be assumed that each call to the xalloc 
static member function invalidates all previous references returned by the pword public member 
function. Therefore, the pword public member function should be called each time the reference is 
needed. 

The pword public member function returns a reference to a void pointer, 
ios::iword, xalloc 
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ios::rdbuf() 


Synopsis: 


Semantics: 


Results: 


♦include <iostream.h> 
public: 

streambuf *ios::rdbuf() const; 

The rdbuf public member function looks up the pointer to the streambuf object which maintains 
the buffer associated with the ios object. 

The rdbuf public member function returns the pointer to the streambuf object associated with the 
ios object. If there is no associated streambuf object, NULL is returned. 
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ios::rdstate() 


Synopsis: #include <iostream.h> 

public: 

iostate ios::rdstate() const; 


Semantics: 

Results: 
See Also: 


The rdstate public member function is used to query the current value of ios : : iostate in the 
ios object without modifying it. 

The rdstate public member function returns the current value of ios : : iostate. 

ios ::bad, clear, eof, fail, good, iostate, operator !, operator void *, 
setstate 
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ios::seekdir 


Synopsis: #include <iostream.h> 

public: 

enum seek_ dir { 
beg, // seek from beginning 
cur, // seek from current position 
end // seek from end 
} ; 

typedef int seekdir; 

Semantics: The type ios : : seek_ dir is a set of bits representing different methods of seeking within a stream. 

The ios : : seekdir member typedef represents the same set of bits, but uses an int to represent the 
values, thereby avoiding problems made possible by the compiler’s ability to use smaller types for 
enumerations. All uses of these bits should use the ios: :seekdir member typedef. 

The bit values defined by ios : : seekdir member typedef are used by the member functions seekg 
and seekp, as well the seekof f and seekpos member functions in classes derived from the 
streambuf class. 

ios : : beg causes the seek offset to be interpreted as an offset from the beginning of the stream. The 
offset is specified as a positive value. 

ios : : cur causes the seek offset to be interpreted as an offset from the current position of the stream. 
If the offset is a negative value, the seek is towards the start of the stream. Otherwise, the seek is 
towards the end of the stream. 

ios : : end causes the seek offset to be interpreted as an offset from the end of the stream. The offset 
is specified as a negative value. 
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ios::setf() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <iostream.h> 
public: 

ios::fmtflags ios::setf( ios::fmtflags onbits ); 
ios::fmtflags ios::setf( ios::fmtflags setbits, 
ios::fmtflags mask ); 

The setf public member function is used to set bits in ios : : fmtf lags in the ios object. 

The first form is used to turn on the bits that are on in the onbits parameter. ( onbits is or'ed into 
ios : : fmtf lags). 

The second form is used to turn off the bits specified in the mask parameter and turn on the bits 
specified in the setbits parameter. This form is particularly useful for setting the bits described by the 
ios: :basefield, ios: : ad justf ield and ios: : floatfield values, where only one bit 
should be on at a time. 

Both forms of the setf public member function return the previous ios : : fmtf lags value. 

ios : : fmtflags, setf, unsetf, manipulator dec, manipulator hex, manipulator oct, 
manipulator setbase, manipulator setiosflags, manipulator resetiosflags 
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ios::setstate() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
protected: 

void ios::setstate ( int or_ bits ); 

The setstate protected member function is provided as a convenience for classes derived from the 
ios class. It turns on the error state in the inherited ios object bits that are set in the or_bits 
parameter, and leaves the other error state in the inherited ios object bits unchanged. 

The setstate protected member function sets the bits specified by or_bi1s in the error state in the 
inherited ios object. 

ios ::bad, clear, eof, fail, good, iostate, operator !, operator void *, 
rdstate 
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ios::sync_ with_stdio() 


Synopsis: 

Semantics: 

Results: 


♦include <iostream.h> 
public: 

static void ios : : sync_ with_ stdio () ; 

The sync_ with_ stdio public static member function is obsolete. It is provided for compatibility. 
The sync_ with_ stdio public static member function has no return value. 
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ios::tie() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <iostream.h> 
public: 

ostream *ios::tie() const; 

ostream *ios::tie( ostream *ostrm ); 

The tie public member function is used to query and/or set up a connection between the ios object 
and another stream. The connection causes the output stream specified by ostrm to be flushed whenever 
the ios object is about to read characters from a device or is about to write characters to an output 
buffer or device. 

The first form of the tie public member function is used to query the current tie. 

The second form of the tie public member function is used to set the tied stream to ostrm. 

Normally, the predefined streams cin and cerr set up ties to cout so that any input from the 
terminal flushes any buffered output, and any writes to cerr flush cout before the characters are 
written, cout does not set up a tie to cerr because cerr has the flag ios : : unitbuf set, so it 
flushes itself after every write operation. 

Both forms of the tie public member function return the previous tie value, 
ios::fmtflags 
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ios::unsetf() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <iostream.h> 
public: 

ios::fmtflags ios::unsetf( ios::fmtflags offbits ); 

The unset f public member function is used to turn offbits in ios : : fmtf lags that are set in the 
offbits parameter. All other bits in ios : : fmtf lags are unchanged. 

The unsetf public member function returns the old ios : : fmtf lags value. 

ios : : fmtf lags, setf, unsetf, manipulator dec, manipulator hex, manipulator oct, 
manipulator setbase, manipulator setiosflags, manipulator resetiosflags 
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ios::width() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <iostream.h> 
public: 

int ios::width() const; 
int ios::width( int wid ); 

The width public member function is used to query and/or set th e format width used to format the next 
item. A format width of zero indicates that the item is to be written using exactly the number of 
positions required. Other values indicate that the item must occupy at least that many positions. If the 
formatted item is larger than the specified format width , the. formal width is ignored and the item is 
formatted using the required number of positions. 

The first form of the width public member function is used to query th e format width that is to be used 
for the next item. 

The second form of the width public member function is used to set the format width to wid for the 
next item to be formatted. 

After an item has been formatted, the format width is reset to zero. Therefore, any non-zero format 
width must be set before each item that is to be formatted. 

The width public member function returns the previous format width. 

ios : : fmtf lags, manipulator setw, manipulator setwidth 
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ios::xalloc() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <iostream.h> 
public: 

static int ios::xalloc() ; 

The xalloc public static member function returns an index into an array of items that the program 
may use for any purpose. Each item can be either a long int or a pointer to void. The index can 
be used with the iword and pword member functions. 

Because the xalloc public static member function manipulates static member data, its behavior is 
not tied to any one object but affects the entire class of objects. The value that is returned by the 
xalloc public static member function is valid for all objects of all classes derived from the ios class. 
No subsequent call to the xalloc public static member function will return the same value as a 
previous call. 

The xalloc public static member function returns an index for use with the iword and pword 
member functions. 

ios::iword, pword 
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iostream 


Declared: 
Derived from: 
Derived by: 


See Also: 


iostream.h 
istream, ostream 
fstream, strstream 

The iostream class supports reading and writing of characters from and to the standard input/output 
devices, usually the keyboard and screen. The iostream class provides formatted conversion of 
characters to and from other types (e.g. integers and floating-point numbers). The associated 
streambuf class provides the methods for communicating with the actual device, while the 
iostream class provides the interpretation of the characters. 

Generally, an iostream object won’t be created by a program, since there is no mechanism at this 
level to "open" a device. No instance of an iostream object is created by default, since it is usually 
not possible to perform both input and output on the standard input/output devices. The iostream 
class is provided as a base class for other derived classes that can provide both input and output 
capabilities through the same object. The fstream and strstream classes are examples of classes 
derived from the iostream class. 

Protected Member Functions 

The following protected member functions are declared: 
iostream(); 

Public Member Functions 

The following public member functions are declared: 

iostream( ios const & ); 
iostream( streambuf * ); 
virtual ~iostream(); 

Public Member Operators 

The following public member operators are declared: 

iostream & operator =( streambuf * ); 
iostream & operator =( ios const & ); 

ios, istream, ostream 
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iostream::iostream() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
protected: 

iostream::iostream(); 

This form of the protected iostream constructor creates an iostream object without an attached 
streambuf object. 

This form of the protected iostream constructor is only used implicitly by the compiler when it 
generates a constructor for a derived class. 

The protected iostream constructor produces an initialized iostream object, ios : : badbit is 
set in the error state in the inherited ios object. 

-iostream 
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iostream::iostream() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

iostream::iostream( ios const Sstrm ); 

This form of the public iostream constructor creates an iostream object associated with the 
streambuf object currently associated with the strm parameter. The iostream object is initialized 
and will use the strm streambuf object for subsequent operations, strm will continue to use the 
streambuf object. 

The public iostream constructor produces an initialized iostream object. If there is no 
streambuf object currently associated with the strm parameter, ios : : badbit is set in the error 
state in the inherited ios object. 

'iostream 
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iostream::iostream() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

iostream::iostream( streambuf *sb ); 

This form of the public iostream constructor creates an iostream object with an attached 
streambuf object. 

Since a user program usually will not create an iostream object, this form of the public iostream 
constructor is unlikely to be explicitly used, except in the member initializer list for the constructor of a 
derived class. The sb parameter is a pointer to a streambuf object, which should be connected to the 
source and sink of characters for the stream. 

The public iostream constructor produces an initialized iostream object. If the sb parameter is 
NULL, ios : : badbit is set in the error state in the inherited ios object. 

-iostream 
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iostream::~iostream() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <iostream.h> 
public: 

virtual iostream::-iostream(); 

The public -iostream destructor does not do anything explicit. The ios destructor is called for that 
portion of the iostream object. The call to the public -iostream destructor is inserted implicitly 
by the compiler at the point where the iostream object goes out of scope. 

The iostream object is destroyed. 

iostream 
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iostream::operator =() 


Synopsis: 


Semantics: 


Results: 


♦include <iostream.h> 
public: 

iostream Siostream::operator =( streambuf *sb ); 

This form of the operator = public member function initializes the target iostream object and 
sets up an association between the iostream object and the streambuf object specified by the sb 
parameter. 

The operator = public member function returns a reference to the iostream object that is the 
target of the assignment. If the sb parameter is NULL, ios : : badbit is set in the error state in the 
inherited ios object. 
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iostream::operator =() 


Synopsis: 


Semantics: 


Results: 


♦include <iostream.h> 
public: 

iostream Siostream::operator =( const ios Sstrm ); 

This form of the operator = public member function initializes the iostream object and sets up 
an association between the iostream object and the streambuf object currently associated with the 
strm parameter. 

The operator = public member function returns a reference to the iostream object that is the 
target of the assignment. If there is no streambuf object currently associated with the strm 
parameter, ios : : badbit is set in the error state in the inherited ios object. 
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istream 


Declared: iostream.h 

Derived from: ios 

Derived by: iostream, if stream, istrstream 

The istream class supports reading characters from a class derived from streambuf, and provides 
formatted conversion of characters into other types (such as integers and floating-point numbers). The 
streambuf class provides the methods for communicating with the external device (keyboard, disk), 
while the istream class provides the interpretation of the resulting characters. 

Generally, an istream object won’t be explicitly created by a program, since there is no mechanism at 
this level to open a device. The only default istream object in a program is cin, which reads from 
standard input (usually the keyboard). 

The istream class supports two basic concepts of input: formatted and unformatted. The overloaded 
operator >> member functions are called extractors and they provide the support for formatted 
input. The rest of the member functions deal with unformatted input, managing the state of the ios 
object and providing a friendlier interface to the associated streambuf object. 

Protected Member Functions 

The following protected member functions are declared: 

istream(); 
eatwhite() ; 

Public Member Functions 

The following public member functions are declared: 

istream( istream const S ); 
istream( streambuf * ); 
virtual -istream)); 
int ipfx( int = 0 ) ; 
void isfx(); 
int get (); 

istream &get( char *, int, char = ' \n' ); 

istream &get( signed char *, int, char = ' \n' ); 

istream &get( unsigned char *, int, char = ' \n' ); 

istream &get( char S ) ; 

istream Sget( signed char S ) ; 

istream &get( unsigned char S ) ; 

istream &get( streambuf S, char = ' \n' ); 

istream &getline( char *, int, char = ' \n' ); 

istream Sgetline( signed char *, int, char = ' \n' ); 

istream &getline( unsigned char *, int, char = ' \n' ); 

istream Signore) int = 1, int = EOF ); 

istream Sread) char *, int ); 

istream Sread) signed char *, int ); 

istream Sread) unsigned char *, int ); 

istream Sseekg) streampos ); 

istream Sseekg) streamoff, ios::seekdir ); 

istream Sputback( char ) ; 

streampos tellg)); 

int gcount () const; 
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istream 


int peek(); 
int sync (); 

Public Member Operators 

The following public member operators are declared: 

istream Soperator =( streambuf * ); 

istream Soperator =( istream const S ); 

istream Soperator >>( char * ) ; 

istream Soperator >>( signed char * ) ; 

istream Soperator >>( unsigned char * ) ; 

istream Soperator >>( char S ) ; 

istream Soperator >>( signed char S ) ; 

istream Soperator >>( unsigned char S ) ; 

istream Soperator >>( signed short S ) ; 

istream Soperator >>( unsigned short S ); 

istream Soperator >>( signed int S ) ; 

istream Soperator >>( unsigned int S ) ; 

istream Soperator >>( signed long S ) ; 

istream Soperator >>( unsigned long S ) ; 

istream Soperator >>( float S ); 

istream Soperator >>( double S ); 

istream Soperator >>( long double S ); 

istream Soperator >>( streambuf S ) ; 

istream Soperator >>( istream S(*)( istream S ) ); 

istream Soperator >>( ios S(*)( ios S ) ); 

See Also: ios, iostream, ostream 
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istream::eatwhite() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
protected: 

void istream::eatwhite(); 

The eatwhite protected member function extracts and discards whitespace characters from the 
istream object, until a non-whitespace character is found. The non-whitespace character is not 
extracted. 

The eatwhite protected member function sets ios : : eofbit in the error state in the inherited ios 
object if end-of-file is encountered as the first character while extracting whitespace characters. 

istream::ignore, ios::fmtflags 
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istream::gcount() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

int istream::gcount() const; 

The gcount public member function determines the number of characters extracted by the last 
unformatted input member function. 

The gcount public member function returns the number of characters extracted by the last 
unformatted input member function. 

istream::get, getline, read 
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istream::get() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

int istream::get() ; 

This form of the get public member function performs an unformatted read of a single character from 
the istream object. 

This form of the get public member function returns the character read from the istream object. If 
the istream object is positioned at end-of-file before the read, EOF is returned and ios : : eofbit 
bit is set in the error state in the inherited ios object, ios : : f ailbit bit is not set by this form of 
the get public member function. 

istream::putback 
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istream::get() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

istream Sistream::get( char &ch ); 
istream &istream::get( signed char &ch ); 
istream Sistream::get( unsigned char &ch ); 

These forms of the get public member function perform an unformatted read of a single character from 
the istream object and store the character in the ch parameter. 

These forms of the get public member function return a reference to the istream object, 
ios : : eofbit is set in the error state in the inherited ios object if the istream object is positioned 
at end-of-file before the attempt to read the character, ios : : f ailbit is set in the error state in the 
inherited ios object if no character is read. 

istream::read, operator >> 
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istream::get() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

istream Sistream::get( char *buf, int len, 
char delim = '\n' ); 

istream Sistream::get( signed char *buf, int len, 
char delim = '\n' ); 

istream Sistream::get( unsigned char *buf, int len, 
char delim = '\n' ); 

These forms of the get public member function perform an unformatted read of at most len -1 
characters from the istream object and store them starting at the memory location specified by the 
bn/parameter. If the character specified by the delim parameter is encountered in the istream object 
before len -1 characters have been read, the read terminates without extracting the delimiting character. 

After the read terminates, whether or not an error occurred, a null character is stored in buf following 
the last character read from the istream object. 

If the delim parameter is not specified, the new-line character is assumed. 

These forms of the get public member function return a reference to the istream object. If 
end-of-file is encountered as the first character, ios : : eofbit is set in the error state in the inherited 
ios object. If no characters are stored into buf, ios : : f ailbit is set in the error state in the 
inherited ios object. 

istream::getline, read, operator >> 
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istream::get() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

istream &istream::get( streambuf &sb, char delim = '\n' ); 

This form of the get public member function performs an unformatted read of characters from the 
istream object and transfers them to the streambuf object specified in the sb parameter. The 
transfer stops if end-of-file is encountered, the delimiting character specified in the delim parameter is 
found, or if the store into the sb parameter fails. If the delim character is found, it is not extracted from 
the istream object and is not transferred to the sb object. 

If the delim parameter is not specified, the new-line character is assumed. 

The get public member function returns a reference to the istream object, ios : : f ailbit is set 
in the error state in the inherited ios object if the store into the streambuf object fails. 

istream::getline, read, operator >> 
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istream::getline() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

istream Sistream::getline( char *buf, int len, 
char delim = '\n' ); 

istream Sistream::getline( signed char *buf, int len, 
char delim = '\n' ); 

istream Sistream::getline( unsigned char *buf, int len, 
char delim = '\n' ); 

The getline public member function performs an unformatted read of at most len -1 characters from 
the istream object and stores them starting at the memory location specified by the /?«/parameter. If 
the delimiting character, specified by the delim parameter, is encountered in the istream object before 
len -1 characters have been read, the read terminates after extracting the delim character. 

If len -1 characters have been read and the next character is the delim character, it is not extracted. 

After the read terminates, whether or not an error occurred, a null character is stored in the buffer 
following the last character read from the istream object. 

If the delim parameter is not specified, the new-line character is assumed. 

The getline public member function returns a reference to the istream object. If end-of-file is 
encountered as the first character, ios : : eofbit is set in the error state in the inherited ios object. 

If end-of-file is encountered before len characters are transferred or the delim character is reached, 
ios : : failbit is set in the error state in the inherited ios object. 

istream::get, read, operator >> 
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istream::ignore() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

istream &istream::ignore( int num = 1, int delim = EOF ); 

The ignore public member function extracts and discards up to num characters from the istream 
object. If the num parameter is not specified, the ignore public member function extracts and 
discards one character. If the delim parameter is not EOF and it is encountered before num characters 
have been extracted, the extraction ceases after discarding the delimiting character. The extraction 
stops if end-of-file is encountered. 

If the num parameter is specified as a negative number, no limit is imposed on the number of characters 
extracted and discarded. The operation continues until the delimiting character is found and discarded, 
or until end-of-file. This behavior is a WATCOM extension. 

The ignore public member function returns a reference to the istream object. If end-of-file is 
encountered as the first character, ios : : eofbit is set in the error state in the inherited ios object. 

istream::eatwhite 
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istream ::ipfx() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

int istream::ipfx( int noskipws = 0 ); 

The ipfx public member function is a prefix function executed before each of the formatted and 
unformatted read operations. If any bits are set in ios : : iostate, the ipfx public member function 
immediately returns 0, indicating that the prefix function failed. Failure in the prefix function causes 
the input operation to fail. 

If the noskipws parameter is 0 or unspecified and the ios : : skipws bit is on in ios : : fmtf lags, 
whitespace characters are discarded and the istream object is positioned so that the next character 
read is the first character after the discarded whitespace. Otherwise, no whitespace skipping takes 
place. 

The formatted input functions that read specific types of objects (such as integers and floating-point 
numbers) call the ipfx public member function with the noskipws parameter set to zero, allowing 
leading whitespaces to be discarded if the ios : : skipws bit is on in ios : : fmtf lags. The 
unformatted input functions that read characters without interpretation call the ipfx public member 
function with a the noskipws parameter set to 1 so that no whitespace characters are discarded. 

If the istream object is tied to an output stream, the output stream is flushed. 

If the istream object is not in an error state in the inherited ios object when the above processing is 
completed, the ipfx public member function returns a non-zero value to indicate success. Otherwise, 
zero is returned to indicate failure. 

istream::isfx 
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istream::isfx() 


Synopsis: 


Semantics: 


See Also: 


♦include <iostream.h> 
public: 

void istream::isfx() ; 

The isfx public member function is a suffix function executed just before the end of each of the 
formatted and unformatted read operations. 

As currently implemented, the isfx public member function does not do anything, 
istream::ipfx 
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istream::istream() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
protected: 
istream::istream() ; 

This form of the protected istream constructor creates an istream object without an associated 
streambuf object. 

This form of the protected istream constructor is only used implicitly by the compiler when it 
generates a constructor for a derived class. 

This form of the protected istream constructor creates an initialized istream object, 
ios : : badbit is set in the error state in the inherited ios object. 

'istream 
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istream::istream() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

istream::istream( istream const &istrm ); 

This form of the public istream constructor creates an istream object associated with the 
streambuf object currently associated with the istrm parameter. The istream object is initialized 
and will use the istrm streambuf object for subsequent operations, istrm will continue to use the 
streambuf object. 

This form of the public istream constructor creates an initialized istream object. If there is no 
streambuf object currently associated with the istrm parameter, ios : : badbit is set in the error 
state in the inherited ios object. 

'istream 
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istream::istream() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

istream::istream( streambuf *sb ); 

This form of the public istream constructor creates an istream object with an associated 
streambuf object specified by the sb parameter. 

This function is likely to be used for the creation of an istream object that is associated with the same 
streambuf object as another istream object. 

This form of the public istream constructor creates an initialized istream object. If the sb 
parameter is NULL, ios : : badbit is set in the error state in the inherited ios object. 

'istream 
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istream ::~istream() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <iostream.h> 
public: 

virtual istream::-istream(); 

The public virtual -istream destructor does not do anything explicit. The ios destructor is called 
for that portion of the istream object. The call to the public virtual -istream destructor is inserted 
implicitly by the compiler at the point where the istream object goes out of scope. 

The istream object is destroyed. 

istream 
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istream: operator =() 


Synopsis: 


Semantics: 


Results: 


♦include <iostream.h> 
public: 

istream Sistream::operator =( streambuf *sb ); 

This form of the operator = public member function is used to associate a streambuf object, 
specified by the sb parameter, with an existing istream object. The istream object is initialized 
and will use the specified streambuf object for subsequent operations. 

This form of the operator = public member function returns a reference to the istream object that 
is the target of the assignment. If the sb parameter is NULL, ios : : badbit is set in the error state in 
the inherited ios object. 
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istream:-.operator =() 


Synopsis: 


Semantics: 


Results: 


♦include <iostream.h> 
public: 

istream Sistream::operator =( istream const &istrm ); 

This form of the operator = public member function is used to associate the istream object with 
the streambuf object currently associated with the istrm parameter. The istream object is 
initialized and will use the istrm ’s streambuf object for subsequent operations. The istrm object will 
continue to use the streambuf object. 

This form of the operator = public member function returns a reference to the istream object that 
is the target of the assignment. If there is no streambuf object currently associated with the istrm 
parameter, ios : : badbit is set in the error state in the inherited ios object. 
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istream: operator »() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

istream &istream::operator >>( char *buf ); 
istream &istream::operator >>( signed char *buf ); 
istream &istream::operator >> ( unsigned char *buf ); 

These forms of the operator >> public member function perform a formatted read of characters 
from the istream object and place them in the buffer specified by the /?:// parameter. Characters are 
read until a whitespace character is found or the maximum size has been read. If a whitespace character 
is found, it is not transferred to the buffer and remains in the istream object. 

If a non-zero format width has been specified, it is interpreted as the maximum number of characters 
that may be placed in buf. No more than format width-1 characters are read from the istream object 
and transferred to buf. If format width is zero, characters are transferred until a whitespace character is 
found. 

Since these forms of the operator >> public member function us e format width, it is reset to zero 
after each use. It must be set before each input operation that requires a non-zero format width. 

A null character is added following the last transferred character, even if the transfer fails because of an 
error. 

These forms of the operator >> public member function return a reference to the istream object 
so that further extraction operations may be specified in the same statement. If no characters are 
transferred to buf ios : : failbit is set in the error state in the inherited ios object. If the first 
character read yielded end-of-file, ios : : eofbit is set in the error state in the inherited ios object. 

istream::get, getline, read 
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istream:: operator »() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

istream Sistream::operator >>( char &ch ); 
istream &istream::operator >>( signed char &ch ); 
istream Sistream::operator >>( unsigned char &ch ); 

These forms of the operator >> public member function perform a formatted read of a single 
character from the istream object and place it in the ch parameter. 

These forms of the operator >> public member function return a reference to the istream object 
so that further extraction operations may be specified in the same statement. If the character read 
yielded end-of-file, ios : : eofbit is set in the error state in the inherited ios object. 

istream::get 
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istream: operator »() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

istream &istream::operator 
istream &istream::operator 
istream Sistream::operator 
istream Sistream::operator 
istream Sistream::operator 
istream Sistream::operator 


>>( signed int Snum ); 

>>( unsigned int Snum ) ; 

>>( signed long Snum ) ; 

>>( unsigned long Snum ) ; 
>>( signed short Snum ) ; 

>>( unsigned short Snum ) ; 


These forms the operator >> public member function perform a formatted read of an integral value 
from the istream object and place it in the num parameter. 

The number may be preceded by a + or - sign. 

If ios : : dec is the only bit set in the ios : : basef ield bits of ios : : fmtf lags, the number is 
interpreted as a decimal (base 10) integer, composed of the digits 0123456789. 

If ios : : oct is the only bit set in the ios : : basef ield bits of ios : : fmtf lags, the number is 
interpreted as an octal (base 8) integer, composed of the digits 01234567. 

If ios : : hex is the only bit set in the ios : : basef ield bits of ios : : fmtf lags, the number is 
interpreted as a hexadecimal (base 16) integer, composed of the digits 0123456789 and the letters 
abcdef or ABCDEF. 


If no bits are set in the ios : : basef ield bits of ios : : fmtf lags, the operator looks for a prefix 
to determine the base of the number. If the first two characters are Ox or OX, the number is interpreted 
as a hexadecimal number. If the first character is a 0 (and the second is not an x or X), the number is 
interpreted as an octal integer. Otherwise, no prefix is expected and the number is interpreted as a 
decimal integer. 

If more than one bit is set in the ios: : basef ield bits of ios: : fmtf lags, the number is 
interpreted as a decimal integer. 

These forms of the operator >> public member function return a reference to the istream object 
so that further extraction operations may be specified in the same statement. If end-of-file is 
encountered as the first character, ios : : eofbit is set in the error state in the inherited ios object. 
If an overflow occurs while converting to the required integer type, the ios : : f a i lb it is set in the 
error state in the inherited ios object. 

ios::fmtflags 
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istream:: operator »() 


Synopsis: 


Semantics: 


Results: 


♦include <iostream.h> 
public: 

istream Sistream::operator >>( float Snum ); 
istream &istream::operator >>( double Snum ); 
istream Sistream::operator >>( long double Snum ); 

These forms of the operator >> public member function perform a formatted read of a 
floating-point value from the istream object and place it in the num parameter. 

The floating-point value may be specified in any form that is acceptable to the C++ compiler. 

These forms of the operator >> public member function return a reference to the istream object 
so that further extraction operations may be specified in the same statement. If end-of-file is 
encountered as the first character, ios : : eofbit is set in the error state in the inherited ios object. 
If an overflow occurs while converting to the required type, the ios : : f a i lb it is set in the error 
state in the inherited ios object. 
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istream: operator »() 


Synopsis: 


Semantics: 


Results: 


♦include <iostream.h> 
public: 

istream Sistream::operator >>( streambuf &sb ); 

This form of the operator >> public member function transfers all the characters from the 
istream object into the sb parameter. Reading continues until end-of-file is encountered. 

This form of the operator >> public member function return a reference to the istream object so 
that further extraction operations may be specified in the same statement. 
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istream:: operator »() 


Synopsis: 


Semantics: 


Results: 


♦include <iostream.h> 
public: 

istream Sistream::operator >>( istream &(*fn) ( istream & ) ); 

istream &istream::operator >>( ios &(*fn)( ios & ) ); 

These forms of the operator >> public member function are used to implement the 
non-parameterized manipulators for the istream class. The function specified by the fn parameter is 
called with the istream object as its parameter. 

These forms of the operator >> public member function return a reference to the istream object 
so that further extraction operations may be specified in the same statement. 
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istream::peek() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

int istream::peek() ; 

The peek public member function looks up the next character to be extracted from the istream 
object, without extracting the character. 

The peek public member function returns the next character to be extracted from the istream object. 
If the istream object is positioned at end-of-file, EOF is returned. 

istream::get 
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istream::putback() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

istream &istream::putback( char ch ); 

The putback public member function attempts to put the extracted character specified by the ch 
parameter back into the istream object. The ch character must be the same as the character before 
the current position of the istream object, usually the last character extracted from the stream. If it is 
not the same character, the result of the next character extraction is undefined. 

The number of characters that can be put back is defined by the istream object, but is usually at least 
4. Depending on the status of the buffers used for input, it may be possible to put back more than 4 
characters. 

The putback public member function returns a reference to the istream object. If the putback 
public member function is unable to put back the ch parameter, ios : : f ailbit is set in the error state 
in the inherited ios object. 

istream::get 
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istream ::read() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

istream &istream::read( char *buf, int len ); 
istream &istream::read( signed char *buf, int len ); 
istream Sistream::read( unsigned char *buf, int len ); 

The read public member function performs an unformatted read of at most len characters from the 
istream object and stores them in the memory locations starting at buf. If end-of-file is encountered 
before len characters have been transferred, the transfer stops and ios : : failbit is set in the error 
state in the inherited ios object. 

The number of characters extracted can be determined with the gcount member function. 

The read public member function returns a reference to the istream object. If end-of-file is 
encountered as the first character, ios : : eofbit is set in the error state in the inherited ios object. 
If end-of-file is encountered before len characters are transferred, ios : : failbit is set in the error 
state in the inherited ios object. 

istream::gcount, get, getline 
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istream::seekg() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

istream &istream::seekg( streampos pos ); 

The seekg public member function positions the istream object to the position specified by the pos 
parameter so that the next input operation commences from that position. 

The seekg public member function returns a reference to the istream object. If the seek operation 
fails, ios : : failbit is set in the error state in the inherited ios object. 

istream::tellg, ostream::tellp, ostream: :seekp 
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istream::seekg() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

istream Sistream::seekg( streamoff offset, ios::seekdir dir ); 

The seekg public member function positions the istream object to the specified position so that the 
next input operation commences from that position. 

The dir parameter may be ios : : beg, ios : : cur, or ios : : end and is interpreted in conjunction 
with the offset parameter as follows: 

ios : : beg the offset is relative to the start and should be a positive value, 
ios : : cur the offset is relative to the current position and may be positive 
(seek towards end) or negative (seek towards start), 
ios : : end the offset is relative to the end and should be a negative value. 

If the dir parameter has any other value, or the offset parameter does not have an appropriate sign, the 
seekg public member function fails. 

The seekg public member function returns a reference to the istream object. If the seek operation 
fails, ios : : failbit is set in the error state in the inherited ios object. 

ostream::tellp, ostream::seekp 
istream::tellg 
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istream::sync() 


Synopsis: 


Semantics: 


Results: 


♦include <iostream.h> 
public: 

int istream::sync() ; 

The sync public member function synchronizes the input buffer and the istream object with 
whatever source of characters is being used. The sync public member function uses the streambuf 
class’s sync virtual member function to carry out the synchronization. The specific behavior is 
dependent on what type of streambuf derived object is associated with the istream object. 

The sync public member function returns_NOT_ EOF on success, otherwiSOF is returned. 
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istream::tellg() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <iostream.h> 
public: 

streampos istream::tellg() ; 

The tellg public member function determines the position in the istream object of the next 
character available for reading. The first character in an istream object is at offset zero. 

The tellg public member function returns the position of the next character available for reading. 

ostream::tellp, ostream::seekp 
istream::seekg 
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istrstream 


Declared: 
Derived from: 


See Also: 


strstrea.h 

strstreambase, istream 

The istrstream class is used to create and read from string stream objects. 

The istrstream class provides little of its own functionality. Derived from the strstreambase 
and istream classes, its constructors and destructor provide simplified access to the appropriate 
equivalents in those base classes. 

Of the available I/O stream classes, creating an istrstream object is the preferred method of 
performing read operations from a string stream. 

Public Member Functions 

The following member functions are declared in the public interface: 

istrstream! char * ); 
istrstream! signed char * ); 

istrstream! unsigned char * ); 

istrstream! char *, int ); 

istrstream! signed char *, int ); 

istrstream! unsigned char *, int ); 

-istrstream(); 

istream, ostrstream, strstream, strstreambase 
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istrstream::istrstream() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <strstrea.h> 
public: 

istrstream::istrstream( char *str ); 
istrstream::istrstream( signed char *str ); 
istrstream::istrstream( unsigned char *str ); 

This form of the public istrstream constructor creates an istrstream object consisting of the 
null terminated C string specified by the str parameter. The inherited istream member functions can 
be used to read from the istrstream object. 

This form of the public istrstream constructor creates an initialized istrstream object, 
'istrstream 
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istrstream::istrstream() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <strstrea.h> 
public: 

istrstream::istrstream( char *str, int len ); 
istrstream::istrstream( signed char *str, int len ); 
istrstream::istrstream( unsigned char *str, int len ); 

This form of the public istrstream constructor creates an istrstream object consisting of the 
characters starting at sir and ending at sir + len - 1. The inherited istream member functions can be 
used to read from the istrstream object. 

This form of the public istrstream constructor creates an initialized istrstream object, 
'istrstream 
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istrstream::~istrstream() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <strstrea.h> 
public: 

istrstream::-istrstream() ; 

The public -istrstream destructor does not do anything explicit. The call to the public 
-istrstream destructor is inserted implicitly by the compiler at the point where the istrstream 
object goes out of scope. 

The istrstream object is destroyed. 

istrstream 
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Manipulators 


Declared: 


iostream.h and iomanip.h 

Manipulators are designed to be inserted into or extracted from a stream. Manipulators come in two 
forms, non-parameterized and parameterized. The non-parameterized manipulators are simpler and are 
declared in <iostream. h>. The parameterized manipulators require more complexity and are 
declared in <iomanip. h>. 

<iomanip. h> defines two macros SMANIP_ define andSMANIP_ make to implement 
parameterized manipulators. The workings of the SMANIP_ define andSMANIP_ make macros are 
disclosed in the header file and are not discussed here. 


Non-parameterized Manipulators 

The following non-parameterized manipulators are declared in <iostream. h>: 

ios &dec( ios & ); 
ios &hex( ios & ); 
ios &oct( ios & ); 
istream &ws( istream & ); 
ostream &endl( ostream & ); 
ostream Sends( ostream S ) ; 
ostream Sflush( ostream S ); 


Parameterized Manipulators 


The following parameterized manipulators are declared in <iomanip. h>: 


SMANIP_ 

define( 

long 

SMANIP_ 

define( 

int 

SMANIP_ 

define( 

int 

SMANIP_ 

define( 

long 

SMANIP_ 

define( 

int 

SMANIP_ 

define( 

int 

SMANIP_ 

define( 

int 


resetiosflags( long ) ; 
setbase( int ) ; 
setfill( int ) ; 
setiosflags( long ) ; 
setprecision( int ); 
setw( int ) ; 
setwidth( int ) ; 
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manipulator dec() 


Synopsis: 

Semantics: 


See Also: 


♦include <iostream.h> 
ios &dec( ios Sstrm ); 

The dec manipulator sets the ios : : basef ield bits for decimal formatting in ios : : fmtf lags in 
the strm ios object. 

ios::fmtflags 
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manipulator endlQ 


Synopsis: 

Semantics: 


See Also: 


♦include <iostream.h> 

ostream &endl( ostream Sostrm ) ; 

The endl manipulator writes a new-line character to the stream specified by the ostrm parameter and 
performs a flush. 

ostream::flush 
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manipulator ends() 


Synopsis: 

Semantics: 


♦include <iostream.h> 

ostream Sends( ostream Sostrm ) ; 

The ends manipulator writes a null character to the stream specified by the ostrm parameter. 
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manipulator fiush() 


Synopsis: 

Semantics: 


See Also: 


♦include <iostream.h> 

ostream &flush( ostream Sostrm ); 

The flush manipulator flushes the stream specified by the ostrm parameter. The flush is performed in 
the same manner as the flush member function. 

ostream::flush 
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manipulator hex() 


Synopsis: 

Semantics: 


See Also: 


♦include <iostream.h> 
ios &hex ( ios Sstrm ); 

The hex manipulator sets the ios : : basef ield bits for hexadecimal formatting in 
ios : : fmtf lags in the strm ios object. 

ios::fmtflags 
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manipulator oct() 


Synopsis: 

Semantics: 


See Also: 


♦include <iostream.h> 
ios &oct ( ios Sstrm ); 

The oct manipulator sets the ios : : basef ield bits for octal formatting in ios : : fmtflags in 
the strm ios object. 

ios::fmtflags 
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manipulator resetiosflags() 


Synopsis: 

Semantics: 


See Also: 


♦include <iomanip.h> 

SMANIP_ define( long ) resetiosflags( long flags ) 

The resetiosf lags manipulator turns off the bits in ios : : fmtf lags that correspond to the bits 
that are on in the flags parameter. No other bits are affected. 

ios: : flags, ios: : fmtf lags, ios : : setf, ios : : unset f 
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manipulator setbaseQ 


Synopsis: 

Semantics: 


See Also: 


♦include <iomanip.h> 

SMANIP_ define( int ) setbase( int base ); 

The setbase manipulator sets the ios: : basef ield bits in ios: :fmtflags to the value 
specified by the base parameter within the stream that the setbase manipulator is operating upon. 

ios::fmtflags 
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manipulator setfillQ 


Synopsis: 

Semantics: 


See Also: 


♦include <iomanip.h> 

SMANIP_ define ( int ) setfill( int fill ) 

The setf ill manipulator sets the fill character to the value specified by the fill parameter within the 
stream that the setf ill manipulator is operating upon. 

ios::fill 
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manipulator setiosflags() 


Synopsis: 

Semantics: 


See Also: 


♦include <iomanip.h> 

SMANIP_ define( long ) setiosflags( long flags ); 

The setiosflags manipulator turns on the bits in ios : : fmt flags that correspond to the bits that 
are on in the flags parameter. No other bits are affected. 

ios : : flags, ios : : fmt flags, ios : : setf, ios : : unset f 
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manipulator setprecisionQ 


Synopsis: 

Semantics: 


See Also: 


♦include <iomanip.h> 

SMANIP_ define( int ) setprecision ( int prec ); 

The setprecision manipulator sets the format precision to the value specified by the prec 
parameter within the stream that the setprecision manipulator is operating upon. 

ios::precision 
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manipulator setw() 


Synopsis: 

Semantics: 


See Also: 


♦include <iomanip.h> 

SMANIP_ define ( int ) setw( int wid ); 

The setw manipulator sets the format width to the value specified by the wid parameter within the 
stream that the setw manipulator is operating upon. 

ios : : width, manipulator setwidth 
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manipulator setwidthQ 


Synopsis: 

Semantics: 


See Also: 


♦include <iomanip.h> 

SMANIP_ define( int ) setwidth( int wid ); 

The setwidth manipulator sets the format width to the value specified by the wid parameter within 
the stream that the setwidth manipulator is operating upon. 

This function is a WATCOM extension. 

ios : : width, manipulator setw 


746 Input/Output Classes 




manipulator ws() 


Synopsis: 

Semantics: 


See Also: 


#include <iostream.h> 
istream &ws( istream &istrm ) ; 

The ws manipulator extracts and discards whitespace characters from the istrm parameter, leaving the 
stream positioned at the next non-whitespace character. 

The ws manipulator is needed particularly when the ios : : skipws bit is not set in 

ios : : fmtf lags in the istrm object. In this case, whitespace characters must be explicitly removed 

from the stream, since the formatted input operations will not automatically remove them. 

istream::eatwhite, istream::ignore 
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ofstream 


Declared: 
Derived from: 


See Also: 


fstream.h 

fstreambase, ostream 

The ofstream class is used to create new files or access existing files for writing. The file can be 
opened and closed, and write and seek operations can be performed. 

The ofstream class provides very little of its own functionality. Derived from both the 
fstreambase and ostream classes, its constructors, destructor and member function provide 
simplified access to the appropriate equivalents in those base classes. 

Of the available I/O stream classes, creating an ofstream object is the preferred method of accessing 
a file for output operations. 

Public Member Functions 

The following public member functions are declared: 
ofstream(); 

ofstream( char const *, 

ios::openmode = ios::out, 

int = filebuf::openprot ); 

ofstream! filedesc ); 

ofstream! filedesc, char *, int ); 

~ofstream(); 

void open! char const *, 
ios::openmode = ios::out, 
int = filebuf::openprot ); 

fstream, fstreambase, ifstream, ostream 
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ofstream::ofstream() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <fstream.h> 
public: 

ofstream::ofstream(); 

This form of the public ofstream constructor creates an ofstream object that is not connected to a 
file. The open or attach member functions should be used to connect the ofstream object to a 
file. 

The public ofstream constructor produces an ofstream object that is not connected to a file, 
-ofstream 
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ofstream::ofstream() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <fstream.h> 
public: 

ofstream::ofstream( const char *name, 
ios::openmode mode = ios::out, 
int prot = filebuf::openprot ); 

This form of the public of stream constructor creates an of stream object that is connected to the 
file specified by the name parameter, using the specified mode and prot parameters. The connection is 
made via the C library open function. 

The public of stream constructor produces an of stream object that is connected to the file 
specified by name. If the open fails, ios : : f ailbit and ios : : badbit are set in the error state in 
the inherited ios object. 

-ofstream, open, fstreambase::close, openmode, openprot 
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ofstream::ofstream() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <fstream.h> 
public: 

ofstream::ofstream( filedesc hdl ); 

This form of the public of stream constructor creates an of stream object that is attached to the file 
specified by the hdl parameter. 

The public of stream constructor produces an of stream object that is attached to hdl. If the attach 
fails, ios: : f ailbit and ios: :badbit are set in the error state in the inherited ios object. 

-ofstream, fstreambase::attach, fstreambase::fd 
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ofstream::ofstream() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <fstream.h> 
public: 

ofstream::ofstream( filedesc hdl, char *buf, int len ); 

This form of the public of stream constructor creates an of stream object that is connected to the 
file specified by the hdl parameter. The buffer specified by the buf and len parameters is offered to the 
associated f ilebuf object via the setbuf member function. If the bw/parameter is NULL or the len 
is less than or equal to zero, the f ilebuf is unbuffered, so that each read or write operation reads or 
writes a single character at a time. 

The public of stream constructor produces an of stream object that is attached to hdl. If the 
connection to hdl fails, ios : : f ailbit and ios : : badbit are set in the error state in the inherited 
ios object. If the setbuf fails, ios : : f ailbit is set in the error state in the inherited ios object. 

-ofstream, fstreambase::attach, fstreambase::fd, fstreambase::setbuf 
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ofstream::~ofstream() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <fstream.h> 
public: 

ofstream::-ofstream() ; 

The public -of stream destructor does not do anything explicit. The call to the public -of stream 
destructor is inserted implicitly by the compiler at the point where the of stream object goes out of 
scope. 

The public -of stream destructor destroys the of stream object, 
ofstream 
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ofstream::open() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <fstream.h> 
public: 

void ofstream::open( const char *name, 
ios::openmode mode = ios::out, 
int prot = filebuf::openprot ); 

The open public member function connects the of stream object to the file specified by the name 
parameter, using the specified mode and prot parameters. The mode parameter is optional and usually 
is not specified unless additional bits (such as ios : : binary or ios : : text) are to be specified. 
The connection is made via the C library open function. 

If the open fails, ios : : f ailbit is set in the error state in the inherited ios object. 

ofstream, openmode, openprot, fstreambase::attach, fstreambase::close, 
fstreambase::fd, fstreambase::is_ open 
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ostream 


Declared: iostream.h 

Derived from: ios 

Derived by: iostream, of stream, ostrstream 

The ostream class supports writing characters to a class derived from the streambuf class, and 
provides formatted conversion of types (such as integers and floating-point numbers) into characters. 
The class derived from the streambuf class provides the methods for communicating with the 
external device (screen, disk), while the ostream class provides the conversion of the types into 
characters. 

Generally, ostream objects won't be explicitly created by a program, since there is no mechanism at 
this level to open a device. The only default ostream objects in a program are cout, cerr, and 
clog which write to the standard output and error devices (usually the screen). 

The ostream class supports two basic concepts of output: formatted and unformatted. The 
overloaded operator << member functions are called inserters and they provide the support for 
formatted output. The rest of the member functions deal with unformatted output, managing the state of 
the ios object and providing a friendlier interface to the associated streambuf object. 

Protected Member Functions 

The following protected member functions are declared: 
ostream(); 

Public Member Functions 

The following public member functions are declared: 

ostream( ostream const S ); 

ostream! streambuf * ); 

virtual -ostream!); 

ostream &flush(); 

int opfx(); 

void osfx(); 

ostream Sput( char ); 

ostream Sput( signed char ) ; 

ostream &put( unsigned char ) ; 

ostream Sseekp! streampos ); 

ostream Sseekp! streamoff, ios::seekdir ); 

streampos tellpO; 

ostream Swrite( char const *, int ); 
ostream Swrite! signed char const *, int ); 
ostream Swrite! unsigned char const *, int ); 

Public Member Operators 

The following public member operators are declared: 

ostream Soperator =( streambuf * ); 
ostream Soperator =( ostream const S ); 
ostream Soperator <<( char ) ; 
ostream Soperator <<( signed char ) ; 
ostream Soperator <<( unsigned char ) ; 
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ostream 


ostream Soperator << 
ostream Soperator << 
ostream Soperator << 
ostream Soperator << 
ostream Soperator << 
ostream Soperator << 
ostream Soperator << 
ostream Soperator << 
ostream Soperator << 
ostream Soperator << 
ostream Soperator << 
ostream Soperator << 
ostream Soperator << 
ostream Soperator << 
ostream Soperator << 
ostream Soperator << 

See Also: ios, iostream, istream 


( signed short ); 

( unsigned short ); 

( signed int ); 

( unsigned int ); 

( signed long ); 

( unsigned long ); 

( float ); 

( double ); 

( long double ); 

( void * ); 

( streambuf S ); 

( char const * ); 

( signed char const * ); 

( unsigned char const * ) ; 

( ostream S(*) ( ostream s ) ); 

( ios S(*)( ios S ) ); 
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ostream::flush() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

ostream Sostream::flush(); 

The flush public member function causes the ostream object’s buffers to be flushed, forcing the 
contents to be written to the actual device connected to the ostream object. 

The flush public member function returns a reference to the ostream object. On failure, 
ios : : f ailbit is set in the error state in the inherited ios object. 

ostream::osfx 
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ostream-operator «() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

ostream Sostream::operator <<( char ch ); 
ostream Sostream::operator <<( signed char ch ); 
ostream Sostream::operator <<( unsigned char ch ); 

These forms of the operator << public member function write the ch character into the ostream 
object. 

These forms of the operator << public member function return a reference to the ostream object 
so that further insertion operations may be specified in the same statement, ios : : f ailbit is set in 
the error state in the inherited ios object if an error occurs. 

ostream::put 
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ostream:: operator«() 


Synopsis: 


Semantics: 


Results: 


♦include <iostream.h> 
public: 

ostream Sostream::operator <<( char const *str ); 
ostream Sostream::operator <<( signed char const *str ); 
ostream Sostream::operator <<( unsigned char const *str ); 

These forms of the operator << public member function perform a formatted write of the contents 
of the C string specified by the str parameter to the ostream object. The characters from sir are 
transferred up to, but not including the terminating null character. 

These forms of the operator << public member function return a reference to the ostream object 
so that further insertion operations may be specified in the same statement, ios : : f ailbit is set in 
the error state in the inherited ios object if an error occurs. 
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ostream-operator «() 


Synopsis: 


Semantics: 


Results: 


♦include <iostream.h> 
public: 


ostream 

Sostream: 

:operator 

«( 

signed int num ) ; 

ostream 

Sostream: 

:operator 

«( 

unsigned int num ) ; 

ostream 

Sostream: 

:operator 

«( 

signed long num ) ; 

ostream 

Sostream: 

:operator 

«( 

unsigned long num ) ; 

ostream 

Sostream: 

:operator 

«( 

signed short num ) ; 

ostream 

Sostream: 

:operator 

«< 

unsigned short num ) ; 


These forms of the operator << public member function perform a formatted write of the integral 
value specified by the num parameter to the ostream object. The integer value is converted to a string 
of characters which are written to the ostream object, num is converted to a base representation 
depending on the setting of the ios : : basef ield bits in ios : : fmt flags. If the ios : : oct bit 
is the only bit on, the conversion is to an octal (base 8) representation. If the ios : : hex bit is the only 
bit on, the conversion is to a hexadecimal (base 16) representation. Otherwise, the conversion is to a 
decimal (base 10) representation. 

For decimal conversions only, a sign may be written in front of the number. If the number is negative, a 
- minus sign is written. If the number is positive and the ios : : showpos bit is on in 
ios : : fmtf lags, a + plus sign is written. No sign is written for a value of zero. 

If the ios : : showbase bit is on in ios : : fmtf lags, and the conversion is to octal or hexadecimal, 
the base indicator is written next. The base indicator for a conversion to octal is a zero. The base 
indicator for a conversion to hexadecimal is Ox or OX, depending on the setting of the 
ios : uppercase bit in ios : : fmtflags. 

If the value being written is zero, the conversion is to octal, and the ios : : showbase bit is on, 
nothing further is written since a single zero is sufficient. 

The value of num is then converted to characters. For conversions to decimal, the magnitude of the 
number is converted to a string of decimal digits 0123456789. For conversions to octal, the number 
is treated as an unsigned quantity and converted to a string of octal digits 01234567. For conversions 
to hexadecimal, the number is treated as an unsigned quantity and converted to a string of hexadecimal 
digits 0123456789 and the letters abcde f or ABCDEF, depending on the setting of the 
ios: :uppercasein ios: : fmtflags. The string resulting from the conversion is then written to 
the ostream object. 

If the ios : : internal bit is set in ios : : fmtflags and padding is required, the padding 
characters are written after the sign and/or base indicator (if present) and before the digits. 

These forms of the operator << public member function return a reference to the ostream object 
so that further insertion operations may be specified in the same statement, ios : : f ailbit is set in 
the error state in the inherited ios object if an error occurs. 
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ostream:: operator «() 


Synopsis: 


Semantics: 


Results: 


♦include <iostream.h> 
public: 

ostream Sostream::operator <<( float num ); 
ostream Sostream::operator <<( double num ); 
ostream Sostream::operator <<( long double num ); 

These forms of the operator << public member function perform a formatted write of the 
floating-point value specified by the num parameter to the ostream object. The number is converted 
to either scientific (exponential) form or fixed-point form, depending on the setting of the 
ios : : f loatf ield bits in ios : : fmtf lags. If ios : : scientific is the only bit set, the 
conversion is to scientific form. If ios : : fixed is the only bit set, the conversion is to fixed-point 
form. Otherwise (neither or both bits set), the value of the number determines the conversion used. If 
the exponent is less than -4 or is greater than or equal to the format precision , the scientific form is 
used. Otherwise, the fixed-point form is used. 

Scientific form consists of a minus sign (for negative numbers), one digit, a decimal point, format 
precision-1 digits, an e or E (depending on the setting of the ios : : uppercase bit), a minus sign (for 
negative exponents) or a plus sign (for zero or positive exponents), and two or three digits for the 
exponent. The digit before the decimal is not zero, unless the number is zero. If the format precision is 
zero (or one), no digits are written following the decimal point. 

Fixed-point form consists of a minus sign (for negative numbers), one or more digits, a decimal point, 
and format precision digits. 

If the ios : : showpoint bit is not set in ios : : fmtf lags, trailing zeroes are trimmed after the 
decimal point (and before the exponent for scientific form), and if no digits remain after the decimal 
point, the decimal point is discarded as well. 

If the ios : : internal bit is set in ios : : fmtf lags and padding is required, the padding 
characters are written after the sign (if present) and before the digits. 

These forms of the operator << public member function return a reference to the ostream object 
so that further insertion operations may be specified in the same statement, ios : : f ailbit is set in 
the error state in the inherited ios object if an error occurs. 
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ostream-operator «() 


Synopsis: 


Semantics: 


Results: 


♦include <iostream.h> 
public: 

ostream Sostream::operator <<( void *ptr ); 

This form of the operator << public member function performs a formatted write of the pointer 
value specified by the ptr parameter to the ostream object. The ptr parameter is converted to an 
implementation-defined string of characters and written to the ostream object. With the Open 
Watcom C++ implementation, the string starts with Ox or OX (depending on the setting of the 
ios : : uppercase bit), followed by 4 hexadecimal digits for 16-bit pointers and 8 hexadecimal digits 
for 32-bit pointers. Leading zeroes are added to ensure the correct number of digits are written. For far 
pointers, 4 additional hexadecimal digits and a colon are inserted immediately after the Ox prefix. 

This form of the operator << public member function returns a reference to the ostream object so 
that further insertion operations may be specified in the same statement, ios : : f ailbit is set in the 
error state in the inherited ios object if an error occurs during the write. 


762 Input/Output Classes 




ostream:: operator«() 


Synopsis: 


Semantics: 


Results: 


♦include <iostream.h> 
public: 

ostream Sostream::operator <<( streambuf &sb ); 

This form of the operator << public member function transfers the contents of the sb streambuf 
object to the ostream object. Reading from the streambuf object stops when the read fails. No 
padding with the fill character takes place on output to the ostream object. 

This form of the operator << public member function returns a reference to the ostream object so 
that further insertion operations may be specified in the same statement, ios : : f ailbit is set in the 
error state in the inherited ios object if an error occurs. 
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ostream-operator «() 


Synopsis: 


Semantics: 


Results: 


♦include <iostream.h> 
public: 

ostream Sostream::operator <<( ostream &(*fn) ( ostream &) ); 

ostream Sostream::operator <<( ios &(*fn)( ios & ) ); 

These forms of the operator << public member function are used to implement the 
non-parameterized manipulators for the ostream class. The function specified by the fn parameter is 
called with the ostream object as its parameter. 

These forms of the operator << public member function return a reference to the ostream object 
so that further insertions operations may be specified in the same statement. 
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ostream: -.operator =() 


Synopsis: 


Semantics: 


Results: 


♦include <iostream.h> 
public: 

ostream Sostream::operator =( streambuf *sb ); 

This form of the operator = public member function is used to associate a streambuf object, 
specified by the sb parameter, with an existing ostream object. The ostream object is initialized 
and will use the specified streambuf object for subsequent operations. 

This form of the operator = public member function returns a reference to the ostream object that 
is the target of the assignment. If the sb parameter is NULL, ios : : badbit is set in the error state in 
the inherited ios object. 
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ostream: operator =() 


Synopsis: 


Semantics: 


Results: 


♦include <iostream.h> 
public: 

ostream Sostream::operator =( const ostream Sostrm ); 

This form of the operator = public member function is used to associate the ostream object with 
the streambuf object currently associated with the ostrm parameter. The ostream object is 
initialized and will use the ostrm s streambuf object for subsequent operations. The ostrm object 
will continue to use the streambuf object. 

This form of the operator = public member function returns a reference to the ostream object that 
is the target of the assignment. If there is no streambuf object currently associated with the ostrm 
parameter, ios : : badbit is set in the error state in the inherited ios object. 
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ostream: :opfx() 


Synopsis: #include <iostream.h> 

public: 

int ostream::opfx(); 


Semantics: 


Results: 
See Also: 


If opfx public member function is a prefix function executed before each of the formatted and 
unformatted output operations. If any bits are set in ios : : iostate, the opfx public member 
function immediately returns zero, indicating that the prefix function failed. Failure in the prefix 
function causes the output operation to fail. 

If the ostream object is tied to another ostream object, the other ostream object is flushed. 
The opfx public member function returns a non-zero value on success, otherwise zero is returned, 
ostream::osfx, flush, ios: :tie 
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ostream::osfx() 


Synopsis: 


Semantics: 


See Also: 


♦include <iostream.h> 
public: 

void ostream::osfx() ; 

The os f x public member function is a suffix function executed at the end of each of the formatted and 
unformatted output operations. 

If the ios : : unitbuf bit is set in ios : : fmtf lags, the flush member function is called. If the 
ios : : stdio bit is set in ios : : fmtf lags, the C library f flush function is invoked on the 
stdout and stderr file streams. 

ostream::osfx, flush 
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ostream::ostream() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 

protected: 

ostream::ostream() ; 

This form of the protected ostream constructor creates an ostream object without an attached 
streambuf object. 

This form of the protected ostream constructor is only used implicitly by the compiler when it 
generates a constructor for a derived class. 

This form of the protected ostream constructor creates an initialized ostream object, 
ios : : badbit is set in the error state in the inherited ios object. 

-ostream 
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ostream::ostream() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

ostream::ostream( ostream const Sostrm ); 

This form of the public ostream constructor creates an ostream object associated with the 
streambuf object currently associated with the ostrm parameter. The ostream object is initialized 
and will use the ostrm’s streambuf object for subsequent operations. The ostrm object will continue 
to use the streambuf object. 

This form of the public ostream constructor creates an initialized ostream object. If there is no 
streambuf object currently associated with the ostrm parameter, ios : : badbit is set in the error 
state in the inherited ios object. 

-ostream 
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ostream::ostream() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

ostream::ostream( streambuf *sb ); 

This form of the public ostream constructor creates an ostream object with an associated 
streambuf object specified by the sb parameter. 

This function is likely to be used for the creation of an ostream object that is associated with the same 
streambuf object as another ostream object. 

This form of the public ostream constructor creates an initialized ostream object. If the sb 
parameter is NULL, ios : : badbit is set in the error state in the inherited ios object. 

-ostream 
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ostream::~ostream() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <iostream.h> 
public: 

virtual ostream::-ostream() ; 

The public virtual -ostream destructor does not do anything explicit. The ios destructor is called 
for that portion of the ostream object. The call to the public virtual -ostream destructor is inserted 
implicitly by the compiler at the point where the ostream object goes out of scope. 

The ostream object is destroyed. 

ostream 
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ostream::put() 


Synopsis: 

Semantics: 

Results: 

See Also: 


♦include <iostream.h> 
public: 

ostream Sostream::put( char ch ); 
ostream Sostream::put( signed char ch ) ; 
ostream Sostream::put( unsigned char ch ); 

These forms of the put public member function write the ch character to the ostream object. 

These forms of the put public member function return a reference to the ostream object. If an error 
occurs, ios : : f ailbit is set in the error state in the inherited ios object. 

ostream::operator «, write 
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ostream::seekp() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

ostream Sostream::seekp( streampos pos ); 

This from of the seekp public member function positions the ostream object to the position 
specified by the pos parameter so that the next output operation commences from that position. 

The pos value is an absolute position within the stream. It may be obtained via a call to the tellp 
member function. 

This from of the seekp public member function returns a reference to the ostream object. If the 
seek operation fails, ios : : f ailbit is set in the error state in the inherited ios object. 

ostream::tellp, istream::tellg, istream: :seekg 
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ostream::seekp() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <iostream.h> 
public: 

ostream Sostream::seekp( streamoff offset, ios::seekdir dir ); 

This from of the seekp public member function positions the ostream object to the specified 
position so that the next output operation commences from that position. 

The dir parameter may be ios : : beg, ios : : cur, or ios : : end and is interpreted in conjunction 
with the offset parameter as follows: 

ios : : beg the offset is relative to the start and should be a positive value, 
ios : : cur the offset is relative to the current position and may be positive 
(seek towards end) or negative (seek towards start), 
ios : : end the offset is relative to the end and should be a negative value. 

If the dir parameter has any other value, or the offset parameter does not have an appropriate sign, the 
seekp public member function fails. 

This from of the seekp public member function returns a reference to the ostream object. If the 
seek operation fails, ios : : f ailbit is set in the error state in the inherited ios object. 

ostream::tellp, istream::tellg, istream: :seekg 
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ostream::tellp() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <iostream.h> 
public: 

streampos ostream::tellp() ; 

The tellp public member function returns the position in the ostream object at which the next 
character will be written. The first character in an ostream object is at offset zero. 

The tellp public member function returns the position in the ostream object at which the next 
character will be written. 

ostream::seekp, istream::tellg, istream: :seekg 
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ostream::write() 


Synopsis: 


Semantics: 


Results: 


♦include <iostream.h> 
public: 

ostream Sostream::write( char const *buf, int len ); 
ostream Sostream::write( signed char const *buf, int len ); 
ostream Sostream::write( unsigned char const *buf, int len ); 

The write public member function performs an unformatted write of the characters specified by the 
buf and len parameters into the ostream object. 

These member functions return a reference to the ostream object. If an error occurs, 
ios : : f ailbit is set in the error state in the inherited ios object. 
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ostrstream 


Declared: 
Derived from: 


See Also: 


strstrea.h 

strstreambase, ostream 

The ostrstream class is used to create and write to string stream objects. 

The ostrstream class provides little of its own functionality. Derived from the strstreambase 
and ostream classes, its constructors and destructor provide simplified access to the appropriate 
equivalents in those base classes. The member functions provide specialized access to the string stream 
object. 

Of the available I/O stream classes, creating an ostrstream object is the preferred method of 
performing write operations to a string stream. 

Public Member Functions 

The following member functions are declared in the public interface: 
ostrstream() ; 

ostrstream! char *, int, ios::openmode = ios::out ); 

ostrstream! signed char *, int, ios::openmode = ios::out ); 

ostrstream! unsigned char *, int, ios::openmode = ios::out ); 

-ostrstream(); 

int pcount() const; 

char *str(); 

istrstream, ostream, ostrstream, strstreambase 
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ostrstream::ostrstream() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <strstrea.h> 
public: 

ostrstream::ostrstream() ; 

This form of the public ostrstream constructor creates an empty ostrstream object. Dynamic 
allocation is used. The inherited stream member functions can be used to access the ostrstream 
object. 

This form of the public ostrstream constructor creates an initialized, empty ostrstream object. 
~ostrstream 
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ostrstream::ostrstream() 


Synopsis: 


Semantics: 

Results: 
See Also: 


#include <strstrea.h> 
public: 

ostrstream::ostrstream( char *str, 
int len, 

ios::openmode mode = ios::out ); 
ostrstream::ostrstream( signed char *str, 
int len, 

ios::openmode mode = ios::out ); 
ostrstream::ostrstream( unsigned char *str, 
int len, 

ios::openmode mode = ios::out ); 

These forms of the public ostrstream constructor create an initialized ostrstream object. 
Dynamic allocation is not used. The buffer is specified by the str and len parameters. If the 
ios : : append or ios : : atend bits are set in the mode parameter, the str parameter is assumed to 
contain a C string terminated by a null character, and writing commences at the null character. 
Otherwise, writing commences at str. 

This form of the public ostrstream constructor creates an initialized ostrstream object. 
~ostrstream 


780 Input/Output Classes 




ostrstream::~ostrstream() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <strstrea.h> 
public: 

ostrstream::-ostrstream() ; 

The public -ostrstream destructor does not do anything explicit. The call to the public 
-ostrstream destructor is inserted implicitly by the compiler at the point where the ostrstream 
object goes out of scope. 

The ostrstream object is destroyed. 

ostrstream 


Input/Output Classes 781 




ostrstream::pcount() 


Synopsis: 


Semantics: 


Results: 


#include <strstrea.h> 
public: 

int ostrstream::pcount() const; 

The pcount public member function computes the number of characters that have been written to the 
ostrstream object. This value is particularly useful if the ostrstream object does not contain a C 
string (terminated by a null character), so that the number of characters cannot be determined with the C 
library strlen function. If the ostrstream object was created by appending to a C string in a static 
buffer, the length of the original string is included in the character count. 

The pcount public member function returns the number of characters contained in the ostrstream 
object. 
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ostrstream::str() 


Synopsis: 


Semantics: 


Results: 


#include <strstrea.h> 
public: 

char *ostrstream::str(); 

The str public member function creates a pointer to the buffer being used by the ostrstream 
object. If the ostrstream object was created without dynamic allocation (static mode), the pointer is 
the same as the buffer pointer passed in the constructor. 

For ostrstream objects using dynamic allocation, the str public member function makes an 
implicit call to the strstreambuf: : freeze member function. If nothing has been written to the 
ostrstream object, the returned pointer will be NULL. 

Note that the buffer does not necessarily end with a null character. If the pointer returned by the str 
public member function is to be interpreted as a C string, it is the program’s responsibility to ensure that 
the null character is present. 

The str public member function returns a pointer to the buffer being used by the ostrstream 
object. 
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stdiobuf 


Declared: 
Derived from: 


See Also: 


stdiobuf.h 
streambuf 

The stdiobuf class specializes the streambuf class and is used to implement the standard 
input/output buffering required for the cin, cout, cerr and clog predefined objects. 

The stdiobuf class behaves in a similar way to the f ilebuf class, but does not need to switch 
between the get area and put area, since no stdiobuf object can be created for both reading and 
writing. When the get area is empty and a read is done, the underflow virtual member function 
reads more characters and fills the get area again. When the put area is full and a write is done, the 
overflow virtual member function writes the characters and makes the put area empty again. 

C++ programmers who wish to use the standard input/output streams without deriving new objects do 
not need to explicitly create or use a stdiobuf object. 

Public Member Functions 

The following member functions are declared in the public interface: 

stdiobuf (); 
stdiobuf( FILE * ); 

~stdiobuf(); 

virtual int overflow! int = EOF ); 
virtual int underflow!); 
virtual int sync(); 

streambuf, ios 
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stdiobuf::overflow() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <stdiobuf.h> 
public: 

virtual int stdiobuf::overflow( int ch = EOF ); 

The overflow public virtual member function provides the output communication to the standard 
output and standard error devices to which the stdiobuf object is connected. Member functions in 
the streambuf class call the overflow public virtual member function for the derived class when 
the put area is full. 

The overflow public virtual member function performs the following steps: 

1. If no buffer is present, a buffer is allocated with the streambuf: : allocate member 
function, which may call the doal locate virtual member function. The put area is then 
setup. If, after calling streambuf:: allocate, no buffer is present, the stdiobuf 
object is unbuffered and ch (if not EOF) is written directly to the file without buffering, and 
no further action is taken. 

2. If the get area is present, it is flushed with a call to the sync virtual member function. Note 
that the get area won’t be present if a buffer was set up in step 1. 

3. If ch is not EOF, it is added to the put area , if possible. 

4. Any characters in the put area are written to the file. 

5. The put area pointers are updated to reflect the new state of the put area. If the write did not 
complete, the unwritten portion of the put area is still present. If the put area was full before 
the write, ch (if not EOF) is placed at the start of the put area. Otherwise, the put area is 
empty. 

The overflow public virtual member function returns_NOT_ EOF on success, otherwifiOF is 

returned. 

stdiobuf::underflow, streambuf::overflow 
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stdiobuf::stdiobuf() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <stdiobuf.h> 
public: 

stdiobuf::stdiobuf() ; 

This form of the public stdiobuf constructor creates a stdiobuf object that is initialized but not 
yet connected to a file. 

This form of the public stdiobuf constructor creates a stdiobuf object. 

-stdiobuf 


786 Input/Output Classes 





stdiobuf::stdiobuf() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <stdiobuf.h> 
public: 

stdiobuf::stdiobuf( FILE *fptr ); 

This form of the public stdiobuf constructor creates a stdiobuf object that is initialized and 
connected to a C library FILE stream. Usually, one of stdin, stdout or stderr is specified for the 
fptr parameter. 

This form of the public stdiobuf constructor creates a stdiobuf object that is initialized and 
connected to a C library FILE stream. 

-stdiobuf 
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stdiobuf::-stdiobuf() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <stdiobuf.h> 
public: 

stdiobuf::-stdiobuf() ; 

The public -stdiobuf destructor does not do anything explicit. The streambuf destructor is 
called for that portion of the stdiobuf object. The call to the public -stdiobuf destructor is 
inserted implicitly by the compiler at the point where the stdiobuf object goes out of scope. 

The stdiobuf object is destroyed. 

stdiobuf 
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stdiobuf::sync() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <stdiobuf.h> 
public: 

virtual int stdiobuf::sync() ; 

The sync public virtual member function synchronizes the stdiobuf object with the associated 
device. If the put area contains characters, it is flushed. If the get area contains buffered characters, 
the sync public virtual member function fails. 

The sync public virtual member function returns_NOT_ EOF on success, otherwisE,OF is returned. 

streambuf::sync 
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stdiobuf::underflow() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <stdiobuf.h> 
public: 

virtual int stdiobuf::underflow() ; 

The underflow public virtual member function provides the input communication from the standard 
input device to which the stdiobuf object is connected. Member functions in the streambuf class 
call the underflow public virtual member function for the derived class when the get area is empty. 

The underflow public virtual member function performs the following steps: 

1. If no reserve area is present, a buffer is allocated with the streambuf : : allocate 
member function, which may call the doallocate virtual member function. If, after 
calling allocate, no reserve area is present, the stdiobuf object is unbuffered and a 
one-character reserve area (plus putback area) is set up to do unbuffered input. This buffer is 
embedded in the stdiobuf object. The get area is set up as empty. 

2. The unused part of the get area is used to read characters from the file connected to the 
stdiobuf object. The get area pointers are then set up to reflect the new get area. 

The underflow public virtual member function returns the first unread character of the get area, on 
success, otherwise EOF is returned. Note that the get pointer is not advanced on success. 

stdiobuf::overflow, streambuf::underflow 
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streambuf 


Declared: 
Derived by: 


streambu.h 

filebuf, stdiobuf, strstreambuf 

The streambuf class is responsible for maintaining the buffer used to create an efficient 
implementation of the stream classes. Through its pure virtual functions, it is also responsible for the 
actual communication with the device associated with the stream. 

The streambuf class is abstract, due to the presence of pure virtual member functions. Abstract 
classes may not be instantiated, only inherited. Hence, streambuf objects will not be created by user 
programs. 

Stream objects maintain a pointer to an associated streambuf object and present the interface that the 
user deals with most often. Whenever a stream member function wishes to read or write characters, it 
uses the rdbuf member function to access the associated streambuf object and its member 
functions. Through judicious use of inline functions, most reads and writes of characters access the 
buffer directly without even doing a function call. Whenever the buffer gets filled ( writing) or 
exhausted (reading), these inline functions invoke the function required to rectify the situation so that 
the proper action can take place. 

A streambuf object can be unbuffered, but most often has one buffer which can be used for both 
input and output operations. The buffer (called the reserve area) is divided into two areas, called the 
get area and the put area. For a streambuf object being used exclusively to write, the get area is 
empty or not present. Likewise, a streambuf object being used exclusively for reading has an empty 
or non-existent put area. 

The use of the get area and put area differs among the various classes derived from the streambuf 
class. 

The filebuf class allows only the get area or the put area , but not both, to be active at a time. This 
follows from the capability of files opened for both reading and writing to have operations of each type 
performed at arbitrary locations in the file. When writing is occurring, the characters are buffered in the 
put area. If a seek or read operation is done, the put area must be flushed before the next operation in 
order to ensure that the characters are written to the proper location in the file. Similarly, if reading is 
occurring, characters are buffered in the get area. If a write operation is done, the get area must be 
flushed and synchronized before the write operation in order to ensure the write occurs at the proper 
location in the file. If a seek operation is done, the get area does not have to be synchronized, but is 
discarded. When the get area is empty and a read is done, the underflow virtual member function 
reads more characters and fills the get area again. When the put area is full and a write is done, the 
overflow virtual member function writes the characters and makes the put area empty again. 

The stdiobuf class behaves in a similar way to the filebuf class, but does not need to switch 
between the get area and put area , since no stdiobuf object can be created for both reading and 
writing. When the get area is empty and a read is done, the underflow virtual member function 
reads more characters and fills the get area again. When the put area is full and a write is done, the 
overflow virtual member function writes the characters and makes the put area empty again. 

The strstreambuf class differs quite markedly from the filebuf and stdiobuf classes. Since 
there is no actual source or destination for the characters in strstream objects, the buffer itself takes 
on that role. When writing is occurring and the put area is full, the overflow virtual member 
function reallocates the buffer to a larger size (if possible), the put area is extended and the writing 
continues. If reading is occurring and the get area is empty, the underflow virtual member function 
checks to see if the put area is present and not empty. If so, the get area is extended to overlap the put 
area. 
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streambuf 


The resen’e area is marked by two pointer values. The base member function returns the pointer to 
the start of the buffer. The ebuf member function returns the pointer to the end of the buffer (last 
character + 1). The setb protected member function is used to set both pointers. 

Within the reserve area , the get area is marked by three pointer values. The eback member function 
returns a pointer to the start of the get area. The egptr member function returns a pointer to the end 
of the get area (last character + 1). The gptr member function returns the get pointer. The get pointer 
is a pointer to the next character to be extracted from the get area. Characters before the get pointer 
have already been consumed by the program, while characters at and after the get pointer have been 
read from their source and are buffered and waiting to be read by the program. The setg member 
function is used to set all three pointer values. If any of these pointers are NULL, there is no get area. 

Also within the reserve area, the put area is marked by three pointer values. The pbase member 
function returns a pointer to the start of the put area. The epptr member function returns a pointer to 
the end of the put area (last character + 1 ). The pptr member function returns the put pointer. The 
put pointer is a pointer to the next available position into which a character may be stored. Characters 
before the put pointer are buffered and waiting to be written to their final destination, while character 
positions at and after the put pointer have yet to be written by the program. The setp member 
function is used to set all three pointer values. If any of these pointers are NULL, there is no put area. 

Unbuffered I/O is also possible. If unbuffered, the overflow virtual member function is used to write 
single characters directly to their final destination without using the put area. Similarly, the 
underflow virtual member function is used to read single characters directly from their source 
without using the get area. 

Protected Member Functions 

The following member functions are declared in the protected interface: 
streambuf(); 

streambuf( char *, int ); 
virtual -streambuf(); 
int allocate (); 
char *base() const; 
char *ebuf() const; 
int blen() const; 

void setb( char *, char *, int ); 

char *eback() const; 

char *gptr() const; 

char *egptr() const; 

void gbump( streamoff ); 

void setg( char *, char *, char *); 

char *pbase() const; 

char *pptr() const; 

char *epptr() const; 

void pbump( streamoff ); 

void setp( char *, char *); 

int unbuffered( int ); 

int unbuffered() const; 

virtual int doallocate() ; 

Public Member Functions 

The following member functions are declared in the public interface: 
int in_ avail() const; 
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streambuf 


int out_ waiting() const; 

int snextc (); 

int sgetn ( char *, int ); 

int speekc (); 

int sgetc (); 

int sgetchar(); 

int sbumpc(); 

void stossc (); 

int sputbackc ( char ); 

int sputc ( int ); 

int sputn ( char const *, int ); 

void dbp(); 

virtual int do_ sgetn( char *, int ); 

virtual int do_ sputn( char const *, int ); 

virtual int pbackfail ( int ); 

virtual int overflow( int = EOF ) = 0; 

virtual int underflow() = 0; 

virtual streambuf *setbuf( char *, int ); 

virtual streampos seekoff ( streamoff, ios::seekdir, 

ios::openmode = ios::in|ios::out ); 

virtual streampos seekpos( streampos, 

ios::openmode = ios::in|ios::out ); 

virtual int sync(); 

See Also: filebuf, stdiobuf, strstreambuf 
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streambuf::allocate() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <streambu.h> 
protected: 

int streambuf::allocate() ; 

The allocate protected member function works in tandem with the doallocate protected virtual 
member function to manage allocation of the streambuf object reserve area. Classes derived from 
the streambuf class should call the allocate protected member function, rather than the 
doallocate protected virtual member function. The allocate protected member function 
determines whether or not the streambuf object is allowed to allocate a buffer for use as the reserve 
area. If a reserve area already exists or if the streambuf object unbuffering state is non-zero, the 
allocate protected member function fails. Otherwise, it calls the doallocate protected virtual 
member function. 

The allocate protected member function returns_NOT_ EOF on success, otherwifiOF is 

returned. 

streambuf::doallocate, underflow, overflow 
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streambuf::base() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <streambu.h> 
protected: 

char *streambuf::base() const; 

The base protected member function returns a pointer to the start of the reserve area that the 
streambuf object is using. 

The reserve area, get area , and put area pointer functions return the following values: 


base() 

start of the reserve area. 

ebuf () 

end of the reserve area. 

blen () 

length of the reser\’e area. 

eback() 

start of the get area. 

gptr () 

the get pointer. 

egptr() 

end of the get area. 

pbase () 

start of the put area. 

pptr () 

the put pointer. 

epptr () 

end of the put area. 


From eback to gptr are characters buffered and read. From gptr to egptr are characters buffered 
but not yet read. From pbase to pptr are characters buffered and not yet written. From pptr to 
epptr is unused buffer area. 

The base protected member function returns a pointer to the start of the reserve area that the 
streambuf object is using. If the streambuf object currently does not have a reserve area, NULL 
is returned. 

streambuf: :blen, ebuf, setb 
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streambuf::blen() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <streambu.h> 
protected: 

int streambuf::blen() const; 

The blen protected member function reports the length of the reserx’e area that the streambuf 
object is using. 

The reserve area, get area , and put area pointer functions return the following values: 


base () 

start of the reserx’e area. 

ebuf () 

end of the reserve area. 

blen () 

length of the reserx’e area. 

eback() 

start of the get area. 

gptr() 

the get pointer. 

egptr() 

end of the get area. 

pbase () 

start of the put area. 

pptr() 

the put pointer. 

epptr () 

end of the put area. 


From eback to gptr are characters buffered and read. From gptr to egptr are characters buffered 
but not yet read. From pbase to pptr are characters buffered and not yet written. From pptr to 
epptr is unused buffer area. 

The blen protected member function returns the length of the reserx’e area that the streambuf 
object is using. If the streambuf object currently does not have a reserve area, zero is returned. 

streambuf::base, ebuf, setb 
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streambuf::dbp() 


Synopsis: #include <streambu.h> 

public: 

void streambuf::dbp (); 

Semantics: The dbp public member function dumps information about the streambuf object directly to 

stdout, and is used for debugging classes derived from the streambuf class. 

The following is an example of what the dbp public member function dumps: 

STREAMBUF Debug Info: 

this = 00030679, unbuffered = 0, delete_ reserve = 1 
base = 00070010, ebuf = 00070094 

eback = 00000000, gptr = 00000000, egptr = 00000000 
pbase = 00070010, pptr = 00070010, epptr = 00070094 
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streambuf::do_sgetn() 


Synopsis: #include <streambu.h> 

public: 

virtual int do_ sgetn( char *buf, int len ); 

Semantics: The do_ sgetn public virtual member function works in tandem with the sgetn member function to 

transfer len characters from the gel area into buf. 

Classes derived from the streambuf class should call the sgetn member function, rather than the 
do_ sgetn public virtual member function. 

Derived Implementation Protocol: 

Classes derived from the streambuf class that implement the do_ sgetn public virtual member 
function should support copying up to len characters from the source through the get area and into buf 

Default Implementation: 

The default do_ sgetn public virtual member function provided with the streambuf class calls the 
underflow virtual member function to fetch more characters and then copies the characters from the 
get area into buf. 

Results: The do_ sgetn public virtual member function returns the number of characters successfully 

transferred. 

See Also: streambuf:: sgetn 
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streambuf::do_sputn() 


Synopsis: #include <streambu.h> 

public: 

virtual int do_ sputn( char const *buf, int len ); 

Semantics: The do_ sputn public virtual member function works in tandem with the sputn member function to 

transfer len characters from buf to the end of the put area and advances the put pointer. 

Classes derived from the streambuf class should call the sputn member function, rather than the 
do_ sputn public virtual member function. 

Derived Implementation Protocol: 

Classes derived from the streambuf class that implement the do_ sputn public virtual member 
function should support copying up to len characters from buf through the put area and out to the 
destination device. 

Default Implementation: 

The default do_ sputn public virtual member function provided with the streambuf class calls the 
overflow virtual member function to flush the put area and then copies the rest of the characters 
from buf into the put area. 

Results: The do_ sputn public virtual member function returns the number of characters successfully written. 

If an error occurs, this number may be less than len. 

See Also: streambuf:: sputn 
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streambuf::doallocate() 


Synopsis: #include <streambu.h> 

protected: 

virtual int streambuf::doallocate() ; 

Semantics: The doallocate protected virtual member function manages allocation of the streambuf object’s 

reserve area in tandem with the allocate protected member function. 

Classes derived from the streambuf class should call the allocate protected member function 
rather than the doallocate protected virtual member function. 

The doallocate protected virtual member function does the actual memory allocation, and can be 
defined for each class derived from the streambuf class. 

Derived Implementation Protocol: 

Classes derived from the streambuf class should implement the doallocate protected virtual 
member function such that it does the following: 

1. attempts to allocate an area of memory, 

2. calls the setb protected member function to initialize the reserve area pointers, 

3. performs any class specific operations required. 

Default Implementation: 

The default doallocate protected virtual member function provided with the streambuf class 
attempts to allocate a buffer area with the operator new intrinsic function. It then calls the setb 
protected member function to set up the pointers to the reserve area. 

Results: The doallocate protected virtual member function returns_ NOT_ EOF on success, otherwiSOF 

is returned. 

See Also: streambuf :: allocate 
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streambuf::eback() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <streambu.h> 
protected: 

char *streambuf::eback() const; 

The eback protected member function returns a pointer to the start of the get area within the reserve 
area used by the streambuf object. 

The reserve area, get area, and put area pointer functions return the following values: 


base () 

start of the reserve area. 

ebuf () 

end of the reserve area. 

blen () 

length of the reser\’e area. 

eback() 

start of the get area. 

gptr() 

the get pointer. 

egptr() 

end of the get area. 

pbase () 

start of the put area. 

pptr() 

the put pointer. 

epptr () 

end of the put area. 


From eback to gptr are characters buffered and read. From gptr to egptr are characters buffered 
but not yet read. From pbase to pptr are characters buffered and not yet written. From pptr to 
epptr is unused buffer area. 

The eback protected member function returns a pointer to the start of the get area. If the 
streambuf object currently does not have a get area, NULL is returned. 

streambuf: :egptr, gptr, setg 
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streambuf::ebuf() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <streambu.h> 
protected: 

char *streambuf::ebuf() const; 

The ebuf protected member function returns a pointer to the end of the reserve area that the 
streambuf object is using. The character pointed at is actually the first character past the end of the 
reserve area. 

The reserve area, get area , and put area pointer functions return the following values: 


base() 

start of the resen’e area. 

ebuf () 

end of the resen’e area. 

blen () 

length of the resen’e area. 

eback() 

start of the get area. 

gptr () 

the get pointer. 

egptr() 

end of the get area. 

pbase () 

start of the put area. 

pptr () 

the put pointer. 

epptr () 

end of the put area. 


From eback to gptr are characters buffered and read. From gptr to egptr are characters buffered 
but not yet read. From pbase to pptr are characters buffered and not yet written. From pptr to 
epptr is unused buffer area. 

The ebuf protected member function returns a pointer to the end of the reserve area. If the 
streambuf object currently does not have a reserve area, NULL is returned. 

streambuf::base, blen, setb 


802 Input/Output Classes 




streambuf::egptr() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <streambu.h> 
protected: 

char *streambuf::egptr() const; 

The egptr protected member function returns a pointer to the end of the get area within the reserve 
area used by the streambuf object. The character pointed at is actually the first character past the 
end of the get area. 

The reserve area, get area, and put area pointer functions return the following values: 


base () 

start of the resen’e area. 

ebuf () 

end of the resen’e area. 

blen () 

length of the resen’e area. 

eback() 

start of the get area. 

gptr() 

the get pointer. 

egptr() 

end of the get area. 

pbase () 

start of the put area. 

pptr() 

the put pointer. 

epptr () 

end of the put area. 


From eback to gptr are characters buffered and read. From gptr to egptr are characters buffered 
but not yet read. From pbase to pptr are characters buffered and not yet written. From pptr to 
epptr is unused buffer area. 

The egptr protected member function returns a pointer to the end of the get area. If the streambuf 
object currently does not have a get area, NULL is returned. 

streambuf::eback, gptr, setg 
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streambuf: :epptr() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <streambu.h> 
protected: 

char *streambuf::epptr() const; 

The eppt r protected member function returns a pointer to the end of the put area within the reserve 
area used by the streambuf object. The character pointed at is actually the first character past the 
end of the put area. 

The reserve area, get area, and put area pointer functions return the following values: 


base() 

start of the resen’e area. 

ebuf () 

end of the resen’e area. 

blen () 

length of the resen’e area. 

eback() 

start of the get area. 

gptr () 

the get pointer. 

egptr() 

end of the get area. 

pbase () 

start of the put area. 

pptr () 

the put pointer. 

epptr () 

end of the put area. 


From eback to gptr are characters buffered and read. From gptr to egptr are characters buffered 
but not yet read. From pbase to pptr are characters buffered and not yet written. From pptr to 
epptr is unused buffer area. 

The epptr protected member function returns a pointer to the end of the put area. If the streambuf 
object currently does not have a put area, NULL is returned. 

streambuf::pbase, pptr, setp 
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streambuf::gbump() 


Synopsis: #include <streambu.h> 

protected: 

void streambuf::gbump( streamoff offset ); 


Semantics: 

Results: 
See Also: 


The gbump protected member function increments the get pointer by the specified offset, without 
regard for the boundaries of the get area. The offset parameter may be positive or negative. 

The gbump protected member function returns nothing. 

streambuf: :gptr, pbump, sbumpc, sputbackc 
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streambuf::gptr() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <streambu.h> 
protected: 

char *streambuf::gptr() const; 

The gpt r protected member function returns a pointer to the next available character in the get area 
within the reserve area used by the streambuf object. This pointer is called the get pointer. 

If the get pointer points beyond the end of the get area, all characters in the get area have been read by 
the program and a subsequent read causes the underflow virtual member function to be called to 
fetch more characters from the source to which the streambuf object is attached. 

The reserve area, get area, and put area pointer functions return the following values: 


base() 

start of the reserve area. 

ebuf () 

end of the reserve area. 

blen () 

length of the reserve area. 

eback() 

start of the get area. 

gptr () 

the get pointer. 

egptr() 

end of the get area. 

pbase () 

start of the put area. 

pptr () 

the put pointer. 

epptr () 

end of the put area. 


From eback to gptr are characters buffered and read. From gptr to egptr are characters buffered 
but not yet read. From pbase to pptr are characters buffered and not yet written. From pptr to 
epptr is unused buffer area. 

The gptr protected member function returns a pointer to the next available character in the get area. 

If the streambuf object currently does not have a get area, NULL is returned. 

streambuf::eback, egptr, setg 
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streambuf::in_avail() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <streambu.h> 
public: 

int streambuf::in_ avail() const; 

The in_ avail public member function computes the number of input characters buffered in the get 
area that have not yet been read by the program. These characters can be read with a guarantee that no 
errors will occur. 

The in_ avail public member function returns the number of buffered input characters, 
streambuf::egptr, gptr 
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streambuf::out_ waitingQ 


Synopsis: #include <streambu.h> 

public: 

int streambuf::out_ waiting() const; 


Semantics: 

Results: 
See Also: 


The out_ waiting public member function computes the number of characters that have been 
buffered in the put area and not yet been written to the output device. 

The out_ waiting public member function returns the number of buffered output characters, 
streambuf::pbase, pptr 
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streambuf::overflow() 


Synopsis: #include <streambu.h> 

public: 

virtual int streambuf::overflow( int ch = EOF ) = 0; 

Semantics: The overflow public virtual member function is used to flush the put area when it is full. 

Derived Implementation Protocol: 

Classes derived from the streambuf class should implement the overflow public virtual member 
function so that it performs the following: 

1. if no reserve area is present and the streambuf object is not unbuffered, allocate a reserve 
area using the allocate member function and set up the reserve area pointers using the 
setb protected member function, 

2. flush any other uses of the reserve area , 

3. write any characters in the put area to the streambuf object’s destination, 

4. set up the put area pointers to reflect the characters that were written, 

5. return_NOT_ EOF on success, otherwise retiuEOF. 

Default Implementation: 

There is no default streambuf class implementation of the overflow public virtual member 
function. The overflow public virtual member function must be defined for all classes derived from 
the streambuf class. 

Results: The overflow public virtual member function returns_NOT_ EOF on success, otherwifiOF is 

returned. 

See Also: filebuf: : overflow, stdiobuf: : overflow, strstreambuf: : overflow 
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streambuf::pbackfail() 


Synopsis: #include <streambu.h> 

public: 

virtual int streambuf::pbackfail( int ch ); 

Semantics: The pbackf ail public virtual member function is called by the sputbackc member function when 

the get pointer is at the beginning of the get area, and so there is no place to put the ch parameter. 

Derived Implementation Protocol: 

Classes derived from the streambuf class should implement the pbackfail public virtual member 
function such that it attempts to put ch back into the source of the stream. 

Default Implementation: 

The default streambuf class implementation of the pbackfail public virtual member function is 
to return EOF. 

Results: If the pbackfail public virtual member function succeeds, it returns ch. Otherwise, EOF is returned. 
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streambuf::pbase() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <streambu.h> 
protected: 

char *streambuf::pbase() const; 

The pbase protected member function returns a pointer to the start of the put area within the reserve 
area used by the streambuf object. 

The reserve area, get area, and put area pointer functions return the following values: 


base() 

start of the reser\’e area. 

ebuf () 

end of the reserve area. 

blen () 

length of the reser\’e area. 

eback() 

start of the get area. 

gptr () 

the get pointer. 

egptr() 

end of the get area. 

pbase () 

start of the put area. 

pptr () 

the put pointer. 

epptr () 

end of the put area. 


From eback to gptr are characters buffered and read. From gptr to egptr are characters buffered 
but not yet read. From pbase to pptr are characters buffered and not yet written. From pptr to 
epptr is unused buffer area. 

The pbase protected member function returns a pointer to the start of the put area. If the 
streambuf object currently does not have a put area, NULL is returned. 

streambuf::epptr, pptr, setp 
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streambuf::pbump() 


Synopsis: #include <streambu.h> 

protected: 

void streambuf::pbump( streamoff offset ); 


Semantics: 

Results: 
See Also: 


The pbump protected member function increments the put pointer by the specified offset, without 
regard for the boundaries of the put area. The offset parameter may be positive or negative. 

The pbump protected member function returns nothing. 

streambuf::gbump, pbase, pptr 
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streambuf: :pptr() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <streambu.h> 
protected: 

char *streambuf::pptr() const; 

The ppt r protected member function returns a pointer to the next available space in the put area within 
the reserve area used by the streambuf object. This pointer is called the put pointer. 

If the put pointer points beyond the end of the put area , the put area is full and a subsequent write 
causes the overflow virtual member function to be called to empty the put area to the device to 
which the streambuf object is attached. 

The reserve area , get area , and put area pointer functions return the following values: 


base() 

start of the reserve area. 

ebuf () 

end of the reserve area. 

blen () 

length of the reserve area. 

eback() 

start of the get area. 

gptr () 

the get pointer. 

egptr() 

end of the get area. 

pbase () 

start of the put area. 

pptr () 

the put pointer. 

epptr () 

end of the put area. 


From eback to gptr are characters buffered and read. From gptr to egptr are characters buffered 
but not yet read. From pbase to pptr are characters buffered and not yet written. From pptr to 
epptr is unused buffer area. 

The pptr protected member function returns a pointer to the next available space in the put area. If 
the streambuf object currently does not have a put area , NULL is returned. 

streambuf::epptr, pbase, setp 
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streambuf::sbumpc() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <streambu.h> 
public: 

int streambuf::sbumpc() ; 

The sbumpc public member function extracts the next available character from the get area and 
advances the get pointer. If no character is available, it calls the underflow virtual member function 
to fetch more characters from the source into the get area. 

Due to the sbumpc member functions’s awkward name, the sgetchar member function was added 
to take its place in the WATCOM implementation. 

The sbumpc public member function returns the next available character in the get area. If no 
character is available, EOF is returned. 

streambuf: :gbump, sgetc, sgetchar, sgetn, snextc, sputbackc 


814 Input/Output Classes 




streambuf::seekoff() 


Synopsis: #include <streambu.h> 

public: 

virtual streampos streambuf::seekoff( streamoff offset, 
ios::seekdir dir, 
ios::openmode mode ); 

Semantics: The seekof f public virtual member function is used for positioning to a relative location within the 

streambuf object, and hence within the device that is connected to the streambuf object. The 
offset and dir parameters specify the relative change in position. The mode parameter controls whether 
the get pointer and/or the put pointer are repositioned. 

Derived Implementation Protocol: 

Classes derived from the streambuf class should implement the seekof f virtual member function 
so that it uses its parameters in the following way. 

The mode parameter may be ios : : in, ios : : out, or ios : : in | ios : : out and should be 
interpreted as follows, provided the interpretation is meaningful: 

ios : : in the get pointer should be moved, 

ios : : out the put pointer should be moved. 

ios : : in | ios : : out both the get pointer and the put pointer should be moved. 

If mode has any other value, the seekof f public virtual member function fails. 

The dir parameter may be ios : : beg, ios : : cur, or ios : : end and is interpreted in conjunction 
with the offset parameter as follows: 

ios : : beg the offset is relative to the start and should be a positive value, 
ios : : cur the offset is relative to the current position and may be positive 
(seek towards end) or negative (seek towards start), 
ios : : end the offset is relative to the end and should be a negative value. 

If the dir parameter has any other value, or the offset parameter does not have an appropriate sign, the 
seekof f public virtual member function fails. 

Default Implementation: 

The default implementation of the seekof f public virtual member function provided by the 
streambuf class returns EOF. 

Results: The seekof f public virtual member function returns the new position in the stream on success, 

otherwise EOF is returned. 

See Also: streambuf:: seekpos 
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streambuf::seekpos() 


Synopsis: #include <streambu.h> 

public: 

virtual streampos streambuf::seekpos( streampos pos, 
ios::openmode mode = ios::in|ios::out ); 

Semantics: The seekpos public virtual member function is used for positioning to an absolute location within the 

streambuf object, and hence within the device that is connected to the streambuf object. The pos 
parameter specifies the absolute position. The mode parameter controls whether the get pointer and/or 
the put pointer are repositioned. 

Derived Implementation Protocol: 

Classes derived from the streambuf class should implement the seekpos public virtual member 
function so that it uses its parameters in the following way. 

The mode parameter may be ios : : in, ios : : out, or ios : : in | ios : : out and should be 
interpreted as follows, provided the interpretation is meaningful: 

ios : : in the get pointer should be moved, 

ios : : out the put pointer should be moved. 

ios : : in | ios : : out both the get pointer and the put pointer should be moved. 

If mode has any other value, the seekpos public virtual member function fails. 

In general the seekpos public virtual member function is equivalent to calling the seekof f virtual 
member function with the offset set to pos, the direction set to ios : : beg and the mode set to mode. 

Default Implementation: 

The default implementation of the seekpos public virtual member function provided by the 
streambuf class calls the seekof f virtual member function with the offset set to pos, the direction 
set to ios : : beg, and the mode set to mode. 

Results: The seekpos public virtual member function returns the new position in the stream on success, 

otherwise EOF is returned. 

See Also: streambuf :: seekof f 
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streambuf::setb() 


Synopsis: 


Semantics: 


See Also: 


♦include <streambu.h> 
protected: 

void streambuf::setb( char *base, char *ebuf, int autodel ); 

The setb protected member function is used to set the pointers to the reserve area that the 
streambuf object is using. 

The base parameter is a pointer to the start of the reserve area and corresponds to the value that the 
base member function returns. 

The chi//' parameter is a pointer to the end of the reserve area and corresponds to the value that the 
ebuf member function returns. 

The autodel parameter indicates whether or not the streambuf object can free the reserx’e area when 
the streambuf object is destroyed or when a new reserve area is set up in a subsequent call to the 
setb protected member function. If the autodel parameter is non-zero, the streambuf object can 
delete the reserve area , using the operator delete intrinsic function. Otherwise, a zero value 
indicates that the buffer will be deleted elsewhere. 

If either of the base or e£w/parameters are NULL or if ebuf<= base , the streambuf object does not 
have a buffer and input/output operations are unbuffered, unless another buffer is set up. 

Note that the setb protected member function is used to set the reserve area pointers, while the 
setbuf protected member function is used to offer a buffer to the streambuf object. 

streambuf: :base, blen, ebuf, setbuf 
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streambuf::setbuf() 


Synopsis: #include <streambu.h> 

public: 

virtual streambuf *streambuf::setbuf( char *buf, int len ); 

Semantics: The setbuf public virtual member function is used to offer a buffer specified by the buf and len 

parameters to the streambuf object for use as its reserve area. Note that the setbuf public virtual 
member function is used to offer a buffer, while the setb protected member function is used to set the 
reserve area pointers once a buffer has been accepted. 

Derived Implementation Protocol: 

Classes derived from the streambuf class may implement the setbuf public virtual member 
function if the default behavior is not suitable. 

Derived classes that provide their own implementations of the setbuf public virtual member function 
may accept or reject the offered buffer. Often, if a buffer is already allocated, the offered buffer is 
rejected, as it may be difficult to transfer the information from the current buffer. 

Default Implementation: 

The default setbuf public virtual member function provided by the streambuf class rejects the 
buffer if one is already present. 

If no buffer is present and either buf is NULL or len is zero, the offer is accepted and the streambuf 
object is unbuffered. 

Otherwise, no buffer is present and one is specified. If len is less than five characters the buffer is too 
small and it is rejected. Otherwise, the buffer is accepted. 

Results: The setbuf public virtual member function returns the address of the streambuf object if the 

offered buffer is accepted, otherwise NULL is returned. 

See Also: streambuf:: setb 
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streambuf::setg() 


Synopsis: 


Semantics: 


See Also: 


♦include <streambu.h> 
protected: 

void streambuf::setg( char *eback, char *gptr, char *egptr ); 

The setg protected member function is used to set the three get area pointers. 

The eback parameter is a pointer to the start of the get area and corresponds to the value that the 
eback member function returns. 

The gptr parameter is a pointer to the first available character in the get area , that is, the get pointer , and 
usually is greater than the eback parameter in order to accommodate a putback area. The gptr 
parameter corresponds to the value that the gptr member function returns. 

The egptr parameter is a pointer to the end of the get area and corresponds to the value that the egptr 
member function returns. 

If any of the three parameters are NULL, there is no get area. 
streambuf::eback, egptr, gptr 
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streambuf::setp() 


Synopsis: 


Semantics: 


See Also: 


♦include <streambu.h> 
protected: 

void streambuf::setp( char *pbase, char *epptr ); 

The setp protected member function is used to set the three put area pointers. 

The phase parameter is a pointer to the start of the put area and corresponds to the value that the 
pbase member function returns. 

The epptr parameter is a pointer to the end of the put area and corresponds to the value that the epptr 
member function returns. 

The put pointer is set to the pbase parameter value and corresponds to the value that the pptr member 
function returns. 

If either parameter is NULL, there is no put area. 
streambuf::epptr, pbase, pptr 
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streambuf::sgetc() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <streambu.h> 
public: 

int streambuf::sgetc(); 

The sgetc public member function returns the next available character in the get area. The get 
pointer is not advanced. If the get area is empty, the underflow virtual member function is called to 
fetch more characters from the source into the get area. 

Due to the sgetc member function’s confusing name (the C library getc function does advance the 
pointer), the speekc member function was added to take its place in the WATCOM implementation. 

The sgetc public member function returns the next available character in the get area. If no character 
is available, EOF is returned. 

streambuf: : sbumpc, sgetchar, sgetn, snextc, speekc 
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streambuf::sgetchar() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <streambu.h> 
public: 

int streambuf::sgetchar() ; 

The sgetchar public member function extracts the next available character from the get area and 
advances the get pointer. If no character is available, it calls the underflow virtual member function 
to fetch more characters from the source into the get area. 

Due to the sbumpc member functions’s awkward name, the sgetchar member function was added 
to take its place in the WATCOM implementation. 

The sgetchar public member function returns the next available character in the get area. If no 
character is available, EOF is returned. 

streambuf: :gbump, sgetc, sgetchar, sgetn, snextc, speekc, sputbackc 
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streambuf::sgetn() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <streambu.h> 
public: 

int streambuf::sgetn( char *buf, int len ); 

The sgetn public member function transfers up to len characters from the get area into buf. If there 
are not enough characters in the get area , the do_ sgetn virtual member function is called to fetch 
more. 

Classes derived from the streambuf class should call the sgetn public member function, rather than 
the do_ sgetn virtual member function. 

The sgetn public member function returns the number of characters transferred from the get area into 
buf. 

streambuf: :do_ sgetn,sbumpc, sgetc, sgetchar, speekc 
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streambuf::snextc() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <streambu.h> 
public: 

int streambuf::snextc() ; 

The snextc public member function advances the get pointer and then returns the character following 
the get pointer. The get pointer is left pointing at the returned character. 

If the get pointer cannot be advanced, the underflow virtual member function is called to fetch more 
characters from the source into the get area. 

The snextc public member function advances the get pointer and returns the next available character 
in the get area. If there is no next available character, EOF is returned. 

streambuf: : sbumpc, sgetc, sgetchar, sgetn, speekc 
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streambuf::speekc() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <streambu.h> 
public: 

int streambuf::speekc(); 

The speekc public member function returns the next available character in the get area. The get 
pointer is not advanced. If the get area is empty, the underflow virtual member function is called to 
fetch more characters from the source into the get area. 

Due to the sgetc member function’s confusing name (the C library getc function does advance the 
pointer), the speekc member function was added to take its place in the WATCOM implementation. 

The speekc public member function returns the next available character in the get area. If no 
character is available, EOF is returned. 

streambuf: : sbumpc, sgetc, sgetchar, sgetn, snextc 


Input/Output Classes 825 




streambuf::sputbackc() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <streambu.h> 
public: 

int streambuf::sputbackc( char ch ); 

The sputbackc public member function is used to put a character back into the get area. The ch 
character specified must be the same as the character before the get pointer, otherwise the behavior is 
undefined. The get pointer is backed up by one position. At least four characters may be put back 
without any intervening reads. 

The sputbackc public member function returns ch on success, otherwise EOF is returned, 
streambuf::gbump, sbumpc, sgetchar 
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streambuf::sputc() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <streambu.h> 
public: 

int streambuf::sputc( int ch ); 

The sputc public member function adds the character ch to the end of the put area and advances the 
put pointer. If the put area is full before the character is added, the overflow virtual member 
function is called to empty the put area and write the character. 

The sputc public member function returns ch on success, otherwise EOF is returned, 
streambuf::sgetc, sputn 
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streambuf::sputn() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <streambu.h> 
public: 

int streambuf::sputn( char const *buf, int len ); 

The sputn public member function transfers up to len characters from buf to the end of the put area 
and advance the put pointer. If the put area is full or becomes full and more characters are to be 
written, the do_ sputn virtual member function is called to empty the put area and finish writing the 
characters. 

Classes derived from the streambuf class should call the sputn public member function, rather than 
the do_ sputn virtual member function. 

The sputn public member function returns the number of characters successfully written. If an error 
occurs, this number may be less than len. 

streambuf: : do_ sputn,sputc 
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streambuf::stossc() 


Synopsis: 


Semantics: 


See Also: 


♦include <streambu.h> 
public: 

void streambuf::stossc() ; 

The stossc public member function advances the get pointer by one without returning a character. If 
the get area is empty, the underflow virtual member function is called to fetch more characters and 
then the get pointer is advanced. 

streambuf::gbump, sbumpc, sgetchar, snextc 
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streambuf::streambuf() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <streambu.h> 
protected: 

streambuf::streambuf() ; 

This form of the protected streambuf constructor creates an empty streambuf object with all 
fields initialized to zero. No reserve area is yet allocated, but the streambuf object is buffered 
unless a subsequent call to the setbuf or unbuffered member functions dictate otherwise. 

This form of the protected streambuf constructor creates an initialized streambuf object with no 
associated reserve area. 

~streambuf 
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streambuf::streamhuf() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <streambu.h> 
protected: 

streambuf::streambuf( char *buf, int len ); 

This form of the protected streambuf constructor creates an empty streambuf object with all 
fields initialized to zero. The buf and len parameters are passed to the setbuf member function, 
which sets up the buffer (if specified), or makes the streambuf object unbuffered (if the buf 
parameter is NULL or the len parameter is not positive). 

This form of the protected streambuf constructor creates an initialized streambuf object with an 
associated reserve area. 

-streambuf, setbuf 
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streambuf::~streambuf() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <streambu.h> 
protected: 

virtual streambuf::-streambuf() ; 

The streambuf object is destroyed. If the buffer was allocated by the streambuf object, it is freed. 
Otherwise, the buffer is not freed and must be freed by the user of the streambuf object. The call to 
the protected -streambuf destructor is inserted implicitly by the compiler at the point where the 
streambuf object goes out of scope. 

The streambuf object is destroyed. 

streambuf 
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streambuf::sync() 


Synopsis: #include <streambu.h> 

public: 

virtual int streambuf::sync (); 

Semantics: The sync public virtual member function is used to synchronize the streambuf object’s get area 

and put area with the associated device. 

Derived Implementation Protocol: 

Classes derived from the streambuf class should implement the sync public virtual member 
function such that it attempts to perform the following: 

1. flush the put area, 

2. discard the contents of the get area and reposition the stream device so that the discarded 
characters may be read again. 

Default Implementation: 

The default implementation of the sync public virtual member function provided by the streambuf 
class takes no action. It succeeds if the get area and the put area are empty, otherwise it fails. 

Results: The sync public virtual member function returns_NOT_ EOF on success, otherwifiOF is returned. 
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streambuf:: unbuffered) 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <streambu.h> 
protected: 

int ios::unbuffered() const; 
int ios::unbuffered( int unbuf ); 

The unbuffered protected member function is used to query and/or set the unbuffering state of the 
streambuf object. A non-zero unbuffered state indicates that the streambuf object is unbuffered. 
An unbuffered state of zero indicates that the streambuf object is buffered. 

The first form of the unbuffered protected member function is used to query the current unbuffering 
state. 

The second form of the unbuffered protected member function is used to set the unbuffering state to 
unbuf. 

Note that the unbuffering state only affects the allocate protected member function, which does 
nothing if the unbuffering state is non-zero. Setting the unbuffering state to a non-zero value does not 
mean that future I/O operations will be unbuffered. 

To determine if current I/O operations are unbuffered, use the base protected member function. A 
return value of NULL from the base protected member function indicates that unbuffered I/O 
operations will be used. 

The unbuffered protected member function returns the previous unbuffered state, 
streambuf::allocate, pbase, setbuf 
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streambuf::underflow() 


Synopsis: #include <streambu.h> 

public: 

virtual int streambuf::underflow() = 0; 

Semantics: The underflow public virtual member function is used to fill the get area when it is empty. 

Derived Implementation Protocol: 

Classes derived from the streambuf class should implement the underflow public virtual member 
function so that it performs the following: 

1. if no reserx’e area is present and the streambuf object is buffered, allocate the reserve 
area using the allocate member function and set up the reserx’e area pointers using the 
setb protected member function, 

2. flush any other uses of the reserve area, 

3. read some characters from the streambuf object’s source into the get area, 

4. set up the get area pointers to reflect the characters that were read, 

5. return the first character of the get area, or EOF if no characters could be read. 

Default Implementation: 

There is no default streambuf class implementation of the underflow public virtual member 
function. The underflow public virtual member function must be defined for all classes derived from 
the streambuf class. 

The underflow public virtual member function returns the first character read into the get area, or 
EOF if no characters could be read. 

filebuf::underflow, stdiobuf::underflow, strstreambuf::underflow 


Results: 

See Also: 
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strstream 


Declared: 
Derived from: 


See Also: 


strstrea.h 

strstreambase, iostream 

The strstream class is used to create and write to string stream objects. 

The strstream class provides little of its own functionality. Derived from the strstreambase 
and iostream classes, its constructors and destructor provide simplified access to the appropriate 
equivalents in those base classes. The member functions provide specialized access to the string stream 
object. 

Of the available I/O stream classes, creating a strstream object is the preferred method of 
performing read and write operations on a string stream. 

Public Member Functions 

The following member functions are declared in the public interface: 

strstream(); 
strstream( char *, 
int, 

ios::openmode = ios::in|ios::out ); 

strstream! signed char *, 

int, 

ios::openmode = ios::in|ios::out ); 

strstream! unsigned char *, 

int, 

ios::openmode = ios::in|ios::out ); 

-strstream(); 
char *str (); 

istrstream, ostrstream, strstreambase 
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strstream::str() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <strstrea.h> 
public: 

char *strstream::str(); 

The str public member function creates a pointer to the buffer being used by the strstream object. 
If the strstream object was created without dynamic allocation (static mode), the pointer is the same 
as the buffer pointer passed in the constructor. 

For strstream objects using dynamic allocation, the str public member function makes an implicit 
call to the strstreambuf: : freeze member function. If nothing has been written to the 
strstream object, the returned pointer will be NULL. 

Note that the buffer does not necessarily end with a null character. If the pointer returned by the str 
public member function is to be interpreted as a C string, it is the program’s responsibility to ensure that 
the null character is present. 

The str public member function returns a pointer to the buffer being used by the strstream object, 
strstreambuf::str, strstreambuf::freeze 
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strstream::strstream() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <strstrea.h> 
public: 

strstream::strstream() ; 

This form of the public strstream constructor creates an empty strstream object. Dynamic 
allocation is used. The inherited stream member functions can be used to access the strstream 
object. Note that the get pointer and put pointer are not necessarily pointing at the same location, so 
moving one pointer (e.g. by doing a write) does not affect the location of the other pointer. 

This form of the public strstream constructor creates an initialized, empty strstream object. 

~strstream 


838 Input/Output Classes 




strstream::strstream() 


Synopsis: 


Semantics: 

Results: 
See Also: 


#include <strstrea.h> 
public: 

strstream::strstream( char *str, 
int len, 

ios::openmode mode ); 

strstream::strstream( signed char *str, 
int len, 

ios::openmode mode ); 

strstream::strstream( unsigned char *str, 
int len, 

ios::openmode mode ); 

These forms of the public strstream constructor create an initialized strstream object. Dynamic 
allocation is not used. The buffer is specified by the str and len parameters. If the ios : : append or 
ios : : atend bits are set in the mode parameter, the str parameter is assumed to contain a C string 
terminated by a null character, and writing commences at the null character. Otherwise, writing 
commences at str. Reading commences at str. 

This form of the public strstream constructor creates an initialized strstream object. 
~strstream 
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strstream: :~strstream() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <strstrea.h> 
public: 

strstream::-strstream(); 

The public -strstream destructor does not do anything explicit. The call to the public 
-strstream destructor is inserted implicitly by the compiler at the point where the strstream 
object goes out of scope. 

The strstream object is destroyed. 

strstream 
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strstreambase 


Declared: 
Derived from: 
Derived by: 


See Also: 


strstrea. h 
ios 

istrstream, ostrstream, strstream 

The strstreambase class is a base class that provides common functionality for the three string 
stream-based classes, istrstream, ostrstream and strstream. The strstreambase class 
is derived from the ios class which provides the stream state information. The strstreambase 
class provides constructors for string stream objects and one member function. 

Protected Member Functions 

The following member functions are declared in the protected interface: 
strstreambase() ; 

strstreambase! char *, int, char * = 0 ); 

-strstreambase(); 

Public Member Functions 

The following member function is declared in the public interface: 
strstreambuf *rdbuf() const; 

istrstream, ostrstream, strstream, strstreambuf 
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strstreambase::rdbuf() 


Synopsis: 


Semantics: 


Results: 


#include <strstrea.h> 
public: 

strstreambuf *strstreambase::rdbuf() const; 

The rdbuf public member function creates a pointer to the strstreambuf associated with the 
strstreambase object. Since the strstreambuf object is embedded within the 
strstreambase object, this function never returns NULL. 

The rdbuf public member function returns a pointer to the strstreambuf associated with the 
strstreambase object. 


842 Input/Output Classes 




strstreambase::strstreambase() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <strstrea.h> 
protected: 

strstreambase::strstreambase(); 

This form of the protected strstreambase constructor creates a strstreambase object that is 
initialized, but empty. Dynamic allocation is used to store characters. No buffer is allocated. A buffer 
is be allocated when data is first written to the strstreambase object. 

This form of the protected strstreambase constructor is only used implicitly by the compiler when 
it generates a constructor for a derived class. 

The protected strstreambase constructor creates an initialized strstreambase object, 
-strstreambase 
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strstreambase::strstreambase() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <strstrea.h> 
protected: 

strstreambase::strstreambase( char *str, 

int len, 

char *pstart ) ; 

This form of the protected strstreambase constructor creates a strstreambase object that is 
initialized and uses the buffer specified by the str and len parameters as its reserve area within the 
associated strstreambuf object. Dynamic allocation is not used. 

This form of the protected strstreambase constructor is unlikely to be explicitly used, except in the 
member initializer list for the constructor of a derived class. 

The str, len and pstart parameters are interpreted as follows: 

1. The buffer starts at str. 

2. If len is positive, the buffer is len characters long. 

3. If len is zero, str is a pointer to a C string which is terminated by a null character, and the 
length of the buffer is the length of the string. 

4. If len is negative, the buffer is unbounded. This last form should be used with extreme 
caution, since no buffer is truly unlimited in size and it would be easy to write beyond the 
available space. 

5. If the pstart parameter is NULL, the strstreambase object is read-only. 

6. Otherwise, pstart divides the buffer into two regions. The get area starts at str and ends at 
pstart- 1. The put area starts at pstart and goes to the end of the buffer. 

The protected strstreambase constructor creates an initialized strstreambase object. 

~strstreambase 


844 Input/Output Classes 




strstreambase: :~strstreambase() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <strstrea.h> 
protected: 

strstreambase::-strstreambase() ; 

The protected -strstreambase destructor does not do anything explicit. The call to the protected 
-strstreambase destructor is inserted implicitly by the compiler at the point where the 
strstreambase object goes out of scope. 

The strstreambase object is destroyed. 

strstreambase 
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strstreambuf 


Declared: strstrea.h 

Derived from: streambuf 

The strstreambuf class is derived from the streambuf class and provides additional 
functionality required to write characters to and read characters from a string buffer. Read and write 
operations can occur at different positions in the string buffer, since the get pointer and put pointer are 
not necessarily connected. Seek operations are also supported. 

The reserve area used by the strstreambuf object may be either fixed in size or dynamic. 
Generally, input strings are of a fixed size, while output streams are dynamic, since the final size may 
not be predictable. For dynamic buffers, the strstreambuf object automatically grows the buffer 
when necessary. 

The strstreambuf class differs quite markedly from the f ilebuf and stdiobuf classes. Since 
there is no actual source or destination for the characters in strstream objects, the buffer itself takes 
on that role. When writing is occurring and the put area is full, the overflow virtual member 
function reallocates the buffer to a larger size (if possible), the put area is extended and the writing 
continues. If reading is occurring and the get area is empty, the underflow virtual member function 
checks to see if the put area is present and not empty. If so, the get area is extended to overlap the put 
area. 

C++ programmers who wish to use string streams without deriving new objects will probably never 
explicitly create or use a strstreambuf object. 

Protected Member Functions 

The following member function is declared in the protected interface: 
virtual int doallocate(); 

Public Member Functions 

The following member functions are declared in the public interface: 

strstreambuf() ; 
strstreambuf( int ) ; 

strstreambuf( void *(*) ( long ), void (*) ( void * ) ); 

strstreambuf( char *, int, char * = 0 ); 

-strstreambuf(); 

int alloc_ size_ increment ( int ) ; 
void freeze ( int = 1 ); 
char *str(); 

virtual int overflow( int = EOF ); 
virtual int underflow(); 

virtual streambuf *setbuf( char *, int ); 
virtual streampos seekoff( streamoff, 
ios::seekdir, 
ios::openmode ); 
virtual int sync(); 

See Also: streambuf, strstreambase 
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strstreambuf::alloc_size_increment() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <strstrea.h> 
public: 

int strstreambuf::alloc_ size_ increment( int increment ); 

The alloc_ size_ increment public member function modifies the allocation size used when the 
buffer is first allocated or reallocated by dynamic allocation. The increment parameter is added to the 
previous allocation size for future use. 

This function is a WATCOM extension. 

The alloc_ size_ increment public member function returns the previous value of the allocation 
size. 

strstreambuf::deallocate, setbuf 
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strstreambuf::doallocate() 


Synopsis: #include <strstrea.h> 

protected: 

virtual int strstreambuf::doallocate(); 

Semantics: The doallocate protected virtual member function is called by the allocate member function 

when it is determined that the put area is full and needs to be extended. 

The doallocate protected virtual member function performs the following steps: 

1. If dynamic allocation is not being used, the doallocate protected virtual member function 
fails. 

2. A new size for the buffer is determined. If the allocation size is bigger than the current size, 
the allocation size is used. Otherwise, the buffer size is increased by 

DEFAULT_ MAINBUF_ SIZE, which is 512. 

3. A new buffer is allocated. If an allocation function was specified in the constructor for the 
strstreambuf object, that allocation function is used, otherwise the operator new 
intrinsic function is used. If the allocation fails, the doallocate protected virtual member 
function fails. 

4. If necessary, the contents of the get area are copied to the newly allocated buffer and the get 
area pointers are adjusted accordingly. 

5. The contents of the put area are copied to the newly allocated buffer and the put area 
pointers are adjusted accordingly, extending the put area to the end of the new buffer. 

6. The old buffer is freed. If a free function was specified in the constructor for the 
strstreambuf object, that free function is used, otherwise the operator delete 
intrinsic function is used. 

Results: The doallocate protected virtual member function returns_NOT_ EOF on success, otherwiSOF 

is returned. 

See Also: strstreambuf: :alloc_ size_ incrementgetbuf 
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strstreambuf::freeze() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <strstrea.h> 
public: 

void strstreambuf::freeze( int frozen = 1 ); 

The freeze public member function enables and disables automatic deletion of the reserx’e area. If 
the freeze public member function is called with no parameter or a non-zero parameter, the 
strstreambuf object is frozen. If the freeze public member function is called with a zero 
parameter, the strstreambuf object is unfrozen. 

A frozen strstreambuf object does not free the reserx’e area in the destructor. If the 
strstreambuf object is destroyed while it is frozen, it is the program’s responsibility to also free the 
reserx’e area. 

If characters are written to the strstreambuf object while it is frozen, the effect is undefined since 
the reserx’e area may be reallocated and therefore may move. However, if the strstreambuf object 
is frozen and then unfrozen, characters may be written to it. 

The freeze public member function returns the previous frozen state. 

strstreambuf::str, -strstreambuf 
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strstreambuf::overflow() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <strstrea.h> 
public: 

virtual int strstreambuf::overflow( int ch = EOF ); 

The overflow public virtual member function provides the output communication between the 
streambuf member functions and the strstreambuf object. Member functions in the 
streambuf class call the overflow public virtual member function when the put area is full. The 
overflow public virtual member function attempts to grow the put area so that writing may continue. 

The overflow public virtual member function performs the following steps: 

1. If dynamic allocation is not being used, the put area cannot be extended, so the overflow 
public virtual member function fails. 

2. If dynamic allocation is being used, a new buffer is allocated using the doallocate 
member function. It handles copying the contents of the old buffer to the new buffer and 
discarding the old buffer. 

3. If the ch parameter is not EOF, it is added to the end of the extended put area and the put 
pointer is advanced. 

The overflow public virtual member function returns_ NOT_ EOF when it successfully extends the 

put area, otherwise EOF is returned. 

streambuf::overflow 
strstreambuf::underflow 
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strstreambuf::seekoff() 


Synopsis: 


Semantics: 


Results: 


#include <strstrea.h> 
public: 

virtual streampos strstreambuf::seekoff( streamoff offset, 
ios::seekdir dir, 
ios::openmode mode ); 

The seekof f public virtual member function positions the get pointer and/or put pointer to the 
specified position in the reserve area. If the get pointer is moved, it is moved to a position relative to 
the start of the reserve area (which is also the start of the get area). If a position is specified that is 
beyond the end of the get area but is in the put area, the get area is extended to include the put area. If 
the put pointer is moved, it is moved to a position relative to the start of the put area, not relative to the 
start of the reserve area. 

The seekof f public virtual member function seeks offset bytes from the position specified by the dir 
parameter. 

The mode parameter may be ios : : in, ios : : out, or ios : : in | ios : : out and should be 
interpreted as follows, provided the interpretation is meaningful: 

ios : : in the get pointer should be moved, 

ios : : out the put pointer should be moved. 

ios : : in | ios : : out both the get pointer and the put pointer should be moved. 

If mode has any other value, the seekof f public virtual member function fails, 
ios : : in | ios : : out is not valid if the dir parameter is ios : : cur. 

The dir parameter may be ios : : beg, ios : : cur, or ios : : end and is interpreted in conjunction 
with the offset parameter as follows: 

ios : : beg the offset is relative to the start and should be a positive value, 
ios : : cur the offset is relative to the current position and may be positive 
(seek towards end) or negative (seek towards start), 
ios : : end the offset is relative to the end and should be a negative value. 

If the dir parameter has any other value, or the offset parameter does not have an appropriate sign, the 
seekof f public virtual member function fails. 

The seekof f public virtual member function returns the new position in the file on success, otherwise 
EOF is returned. If both or ios : : in | ios : : out are specified and the dir parameter is ios : : cur 
the returned position refers to the put pointer. 
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strstreambuf::setbuf() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <strstrea.h> 
public: 

virtual streambuf *strstreambuf::setbuf( char *, int size ); 

The setbuf public virtual member function is used to control the size of the allocations when the 
strstreambuf object is using dynamic allocation. The first parameter is ignored. The next time an 
allocation is required, at least the number of characters specified in the size parameter is allocated. If 
the specified size is not sufficient, the allocation reverts to its default behavior, which is to extend the 
buffer by DEFAULT_ MAINBUF_ SIZE, which is 512 characters. 

If a program is going to write a large number of characters to the strstreambuf object, it should call 
the setbuf public virtual member function to indicate the size of the next allocation, to prevent 
multiple allocations as the buffer gets larger. 

The setbuf public virtual member function returns a pointer to the strstreambuf object, 
strstreambuf: :alloc_ size_ incrementdoallocate 
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strstreambuf::str() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <strstrea.h> 
public: 

char *strstreambuf::str(); 

The str public member function freezes the strstreambuf object and returns a pointer to the 
reserve area. This pointer remains valid after the strstreambuf object is destroyed provided the 
strstreambuf object remains frozen, since the destructor does not free the reserve area if it is 
frozen. 

The returned pointer may be NULL if the strstreambuf object is using dynamic allocation but has 
not yet had anything written to it. 

If the strstreambuf object is not using dynamic allocation, the pointer returned by the str public 
member function is the same buffer pointer provided to the constructor. For a strstreambuf object 
using dynamic allocation, the pointer points to a dynamically allocated area. 

Note that the reserx’e area does not necessarily end with a null character. If the pointer returned by the 
str public member function is to be interpreted as a C string, it is the program’s responsibility to 
ensure that the null character is present. 

The str public member function returns a pointer to the reserve area and freezes the strstreambuf 
object. 

strstreambuf::freeze 
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strstreambuf::strstreambuf() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <strstrea.h> 
public: 

strstreambuf::strstreambuf() ; 

This form of the public strstreambuf constructor creates an empty strstreambuf object that 
uses dynamic allocation. No reserx’e area is allocated to start. Whenever characters are written to 
extend the strstreambuf object, the reserx’e area is reallocated and copied as required. The size of 
allocation is determined by the strstreambuf object unless the setbuf or 

alloc_ size_ increment member functions are called to change the allocation size. The default 
allocation size is determined by the constant DEFAULT_ MAINBUF_ SIZE, which is 512. 

This form of the public strstreambuf constructor creates a strstreambuf object. 

strstreambuf::deallocate, -strstreambuf 
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strstreambuf::strstreambuf() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <strstrea.h> 
public: 

strstreambuf::strstreambuf( int alloc_ size ); 

This form of the public strstreambuf constructor creates an empty strstreambuf object that 
uses dynamic allocation. No buffer is allocated to start. Whenever characters are written to extend the 
strstreambuf object, the reserve area is reallocated and copied as required. The size of the first 
allocation is determined by the alloc_size parameter, unless changed by a call to the setbuf or 
alloc_ size_ increment member functions. 

Note that the alloc_size parameter is the starting reserve area size. When the reserve area is 
reallocated, the strstreambuf object uses DEFAULT_ MAINBUF_ SIZE to increase the reserve area 
size, unless the setbuf or alloc_ size_ increment member functions have been called to specify 
a new allocation size. 

This form of the public strstreambuf constructor creates a strstreambuf object, 
strstreambuf::alloc_ size_ incrementdoallocate, setbuf, 'Strstreambuf 
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strstreambuf::strstreambuf() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <strstrea.h> 
public: 

strstreambuf::strstreambuf( void * (*alloc_fn) ( long ), 
void (*free_ fn)( void * ) ); 

This form of the public strstreambuf constructor creates an empty strstreambuf object that 
uses dynamic allocation. No buffer is allocated to start. Whenever characters are written to extend the 
strstreambuf object, the reserve area is reallocated and copied as required, using the specified 
alloc _fn and free_fn functions. The size of allocation is determined by the class unless the setbuf or 
alloc_ size_ increment member functions are called to change the allocation size. The default 
allocation size is determined by the constant DEFAULT_ MAINBUF_ SIZE, which is 512. 

When a new reserx’e area is allocated, the function specified by the alloc Jk parameter is called with a 
long integer value indicating the number of bytes to allocate. If allocjn is NULL, the 
operator new intrinsic function is used. Likewise, when the reserve area is freed, the function 
specified by the free _fn parameter is called with the pointer returned by the alloc_fn function as the 
parameter. If free_fn is NULL, the operator delete intrinsic function is used. 

This form of the public strstreambuf constructor creates a strstreambuf object. 

strstreambuf::alloc_ size_ incrementdoallocate, setbuf, 'Strstreambuf 
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strstreambuf::strstreambuf() 


Synopsis: 


Semantics: 


Results: 
See Also: 


#include <strstrea.h> 
public: 

strstreambuf::strstreambuf( char *str, 
int len, 

char *pstart = NULL ) ; 

strstreambuf::strstreambuf( signed char *str, 
int len, 

signed char *pstart = NULL ) ; 

strstreambuf::strstreambuf( unsigned char *str, 
int len, 

unsigned char *pstart = NULL ) ; 

This form of the public strstreambuf constructor creates a strstreambuf object that does not 
use dynamic allocation (unless str is NULL). The strstreambuf object is said to be using static 
allocation. The str and len parameters specify the bounds of the reserve area. 

The str, len and pstart parameters are interpreted as follows: 

1. The buffer starts at str. 

2. If len is positive, the buffer is len characters long. 

3. If len is zero, str is a pointer to a C string which is terminated by a null character, and the 
length of the buffer is the length of the string. 

4. If len is negative, the buffer is unbounded. This last form should be used with extreme 
caution, since no buffer is truly unlimited in size and it would be easy to write beyond the 
available space. 

5. If the pstart parameter is NULL, the strstreambuf object is read-only. 

6. Otherwise, pstart divides the buffer into two regions. The get area starts at sir and ends at 
pstart- 1. The put area starts at pstart and goes to the end of the buffer. 

If the get area is exhausted and characters have been written to the put area, the get area is extended to 
include the put area. 

The get pointer and put pointer do not necessarily point at the same position in the reserve area, so a 
read followed by a write does not imply that the write stores following the last character read. The get 
pointer is positioned following the last read operation, and the put pointer is positioned following the 
last write operation, unless the seekof f member function has been used to reposition the pointer(s). 

Note that if str is NULL the effect is to create an empty dynamic strstreambuf object. 

This form of the public strstreambuf constructor creates a strstreambuf object. 

~strstreambuf 
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strstreambuf::~strstreambuf() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <strstrea.h> 
public: 

strstreambuf::-strstreambuf() ; 

The public -strstreambuf destructor destroys the strstreambuf object after discarding the 
reserve area. The reserve area is discarded only if the strstreambuf object is using dynamic 
allocation and is not frozen. The reserve area is freed using the free function specified by the form of 
the constructor that allows specification of the allocate and free functions, or using the 
operator delete intrinsic function. If the strstreambuf object is frozen or using static 
allocation, the user of the strstreambuf object must have a pointer to the reserve area and is 
responsible for freeing it. The call to the public -strstreambuf destructor is inserted implicitly by 
the compiler at the point where the strstreambuf object goes out of scope. 

The strstreambuf object is destroyed. 

strstreambuf 
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strstreambuf::sync() 


Synopsis: 


Semantics: 


Results: 


#include <strstrea.h> 
public: 

virtual int strstreambuf::sync() ; 

The sync public virtual member function does nothing because there is no external device with which 
to synchronize. 

The sync public virtual member function returns_ NOT_ EOF. 
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strstreambuf::underflow() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <strstrea.h> 
public: 

virtual int strstreambuf::underflow() ; 

The underflow public virtual member function provides the input communication between the 
streambuf member functions and the strstreambuf object. Member functions in the 
streambuf class call the underflow public virtual member function when the get area is empty. 

If there is a non-empty put area present following the get area , the get area is extended to include the 
put area, allowing the input operation to continue using the put area. Otherwise the get area cannot be 
extended. 

The underflow public virtual member function returns the first available character in the get area on 
successful extension, otherwise EOF is returned. 

streambuf::underflow 
strstreambuf::overflow 
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19 String Class 


This class is used to store arbitrarily long sequences of characters in memory. Objects of this type may be 
concatenated, substringed, compared and searched without the need for memory management by the user. 
Unlike a C string, this object has no delimiting character, so any character in the collating sequence, or 
character set, may be stored in an object. 

The class documented here is the Open Watcom legacy string class. It is not related to the 
std: :basic_ string class template nor to its corresponding specializationstd: : string. 
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String 


Declared: 


string.hpp 

The String class is used to store arbitrarily long sequences of characters in memory. Objects of this 
type may be concatenated, substringed, compared and searched without the need for memory 
management by the user. Unlike a C string, a String object has no delimiting character, so any 
character in the collating sequence, or character set, may be stored in a String object. 

Public Functions 

The following constructors and destructors are declared: 

String (); 

String! size_t, capacity ); 

String! String const &, size_ t = 0, size_ t = NPOS ); 

String! char const *, size_ t = NPOS ); 

String! char, size_ t = 1 ); 

-String (); 

The following member functions are declared: 

operator char const *(); 
operator char() const; 

String Soperator =( String const & ); 

String Soperator =( char const * ); 

String Soperator +=( String const S ); 

String Soperator +=( char const * ); 

String operator () ( size_t, size_ t ) const; 

char Soperator ()( size_ t ); 

char const Soperator [] ( size_t ) const; 

char Soperator []( size_ t ); 

int operator !() const; 

size_ t length!) const; 

char const Sget_ at( size_ t ) const; 

void put_ at ( size_t, char ); 

int match! String const S ) const; 

int match! char const * ) const; 

int index! String const S, size_t = 0 ) const; 

int index! char const *, size_t = 0 ) const; 

String upper!) const; 

String lower!) const; 
int valid!) const; 
int alloc_ mult_ size () const; 
int alloc_ mult_ size( int ); 


The following friend functions are declared: 


friend 

int 

operator 

== ( 

String 

const 
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String 
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int 

operator 

<( 

String 

const 

&, 

String 

const 

& 

); 


862 String Class 






String 
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friend int valid( String const & ); 

The following I/O Stream inserter and extractor functions are declared: 


friend istream 
friend ostream 


Soperator 

^operator 


»( 

«( 


istream &, 
ostream &, 


String & ); 

String const & ); 


) ; 
) ; 
) ; 
) ; 
) ; 
) ; 
) ; 
) ; 
) ; 
) ; 
) ; 
) ; 
) ; 
) ; 
) ; 
) ; 
) ; 
) ; 
) ; 
) ; 
) ; 
) ; 
) ; 
) ; 
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String::alloc_mult_size() 


Synopsis: 


Semantics: 


Results: 


#include <string.hpp> 
public: 

int String::alloc_ mult_ size () const; 
int String::alloc_ mult_ size ( int mult ); 

The alloc_ mult_ size public member function is used to query and/or change the allocation 
multiple size. 

The first form of the alloc_ mult_ size public member function queries the current setting. 

The second form of the alloc_ mult_ size public member function sets the value to a multiple of 8 
based on the mult parameter. The value of mult is rounded down to a multiple of 8 characters. If mult 
is less than 8, the new multiple size is 1 and allocation sizes are exact. 

The scheme used to store a String object allocates the memory for the characters in multiples of some 
size. By default, this size is 8 characters. A String object with a length of 10 actually has 16 
characters of storage allocated for it. Concatenating more characters on the end of the String object 
only allocates a new storage block if more than 6 (16-10) characters are appended. This scheme tries to 
find a balance between reallocating frequently (multiples of a small value) and creating a large amount 
of unused space (multiples of a large value). 

The alloc_ mult_ size public member function returns the previous allocation multiple size. 
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String ::get_at() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <string.hpp> 
public: 

char const SString: : get_ at ( size_ t pos ); 

The get_ at public member function creates a const reference to the character at offset pos within the 
String object. This reference may not be used to modify that character. The first character of a 
String object is at position zero. 

If pos is greater than or equal to the length of the String object, and the resulting reference is used, 
the behavior is undefined. 

The reference is associated with the String object, and therefore has meaning only as long as the 
String object is not modified (or destroyed). If the String object has been modified and an old 
reference is used, the behavior is undefined. 

The get_ at public member function returns a const reference to a character. 

String :: put_ at,operator [], operator () 
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String::index() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <string.hpp> 
public: 

int String::index( String const &str, size_t pos = 0 ) const; 
int String::index( char const *pch, size_ t pos = 0 ) const; 

The index public member function computes the offset at which a sequence of characters in the 
String object is found. 

The first form searches the String object for the contents of the str String object. 

The second form searches the String object for the sequence of characters pointed at by pch. 

If pos is specified, the search begins at that offset from the start of the String object. Otherwise, the 
search begins at offset zero (the first character). 

The index public member function treats upper and lower case letters as not equal. 

The index public member function returns the offset at which the sequence of characters is found. If 
the substring is not found, -1 is returned. 

String: : lower, operator ! =, operator ==, match, upper 
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String: :length() 


Synopsis: 


Semantics: 


Results: 


#include <string.hpp> 
public: 

size_ t String::length() const; 

The length public member function computes the number of characters contained in the String 
object. 

The length public member function returns the number of characters contained in the String 
object. 
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String::lower() 


Synopsis: #include <string.hpp> 

public: 

String String::lower() const; 


Semantics: 

Results: 
See Also: 


The lower public member function creates a String object whose value is the same as the original 
object’s value, except that all upper-case letters have been converted to lower-case. 

The lower public member function returns a lower-case String object. 

String::upper 
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String: :match() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <string.hpp> 
public: 

int String::match( String const Sstr ) const; 
int String::match( char const *pch ) const; 

The mat ch public member function compares two character sequences to find the offset where they 
differ. 

The first form compares the String object to the str String object. 

The second form compares the String object to the pch C string. 

The first character is at offset zero. The match public member function treats upper and lower case 
letters as not equal. 

The mat ch public member function returns the offset at which the two character sequences differ. If 
the character sequences are equal, -1 is returned. 

String: : index, lower, operator ! =, operator ==, upper 
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String-operator!() 


Synopsis: 

Semantics 

Results: 

See Also: 


#include <string.hpp> 
public: 

int String::operator !() const; 

The operator ! public member function tests the validity of the String object. 

The operator ! public member function returns a non-zero value if the String object is invalid, 
otherwise zero is returned. 

String::valid, valid 
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String operator !=() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <string.hpp> 
public: 

friend int operator !=( String const Sift, String const &rht ); 
friend int operator !=( String const &lft, char const *rht ); 

friend int operator !=( char const *lft. String const &rht ); 

friend int operator !=( String const &lft, char rht ); 

friend int operator !=( char 1ft, String const &rht ); 

The operator ! = function compares two sequences of characters in terms of an inequality 
relationship. 

A String object is different from another String object if the lengths are different or they contain 
different sequences of characters. A String object and a C string are different if their lengths are 
different or they contain a different sequence of characters. A C string is terminated by a null character. 
A String object and a character are different if the String object does not contain only the 
character. Upper-case and lower-case characters are considered different. 

The operator ! = function returns a non-zero value if the lengths or sequences of characters in the Ift 
and rht parameter are different, otherwise zero is returned. 

String::operator ==, operator <, operator <=, operator >, operator >= 


String Class 871 





String-operator ()() 


Synopsis: 

Semantics: 


Results: 
See Also: 


#include <string.hpp> 
public: 

char SString::operator ()( size_ t pos ); 

The operator () public member function creates a reference to the character at offset pos within the 
String object. This reference may be used to modify that character. The first character of a String 
object is at position zero. 

If pos is greater than or equal to the length of the String object, and the resulting reference is used, 
the behavior is undefined. 

If the reference is used to modify other characters within the String object, the behavior is undefined. 

The reference is associated with the String object, and therefore has meaning only as long as the 
String object is not modified (or destroyed). If the String object has been modified and an old 
reference is used, the behavior is undefined. 

The operator () public member function returns a reference to a character. 

String::operator [], operator char, operator char const * 
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String-operator ()() 


Synopsis: 


Semantics: 


Results: 
See Also: 


♦include <string.hpp> 
public: 

String String:: operator () ( size_ t pos, size_ t len ) const; 

This form of the operator () public member function extracts a sub-sequence of characters from 
the String object. A new String object is created that contains the sub-sequence of characters. 

The sub-sequence begins at offset pos within the String object and continues for len characters. The 
first character of a String object is at position zero. 

If pos is greater than or equal to the length of the String object, the result is empty. 

If len is such that pos + len exceeds the length of the object, the result is the sub-sequence of characters 
from the String object starting at offset pos and running to the end of the String object. 

The operator () public member function returns a String object. 

String::operator [], operator char, operator char const * 
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String operator +() 


Synopsis: #include <string.hpp> 

public: 

friend String operator +( String &lft. String const &rht ); 
friend String operator +( String &lft, char const *rht ); 
friend String operator +( char const *lft. String const &rht ); 
friend String operator +( String &lft, char rht ); 
friend String operator +( char 1ft, String const &rht ); 

Semantics: The operator + function concatenates two sequences of characters into a new String object. The 

new String object contains the sequence of characters from the Ift parameter followed by the 
sequence of characters from the rht parameter. 

A NULL pointer to a C string is treated as a pointer to an empty C string. 

Results: The operator + function returns a new String object that contains the characters from the Ift 

parameter followed by the characters from the rht parameter. 

See Also: String: :operator += 
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String-operator +=() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <string.hpp> 
public: 

String SString::operator +=( String const Sstr ); 

String SString::operator +=( char const *pch ); 

The operator += public member function appends the contents of the parameter to the end of the 
String object. 

The first form of the operator += public member function appends the contents of the str String 
object to the String object. 

The second form appends the null-terminated sequence of characters stored at pch to the String 
object. If the pch parameter is NULL, nothing is appended. 

The operator += public member function returns a reference to the String object that was the 
target of the assignment. 

String::operator = 
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String operator <() 


Synopsis: #include <string.hpp> 

public: 

friend int operator <( String const Sift, String const &rht ); 
friend int operator <( String const Sift, char const *rht ); 

friend int operator <( char const *lft. String const &rht ); 

friend int operator <( String const Sift, char rht ); 

friend int operator <( char 1ft, String const &rht ); 

Semantics: The operator < function compares two sequences of characters in terms of a less-thcm relationship. 

Ift is less-than rht if Ift if the characters of Ift occur before the characters of rht in the collating sequence. 
Upper-case and lower-case characters are considered different. 

Results: The operator < function returns a non-zero value if the Ift sequence of characters is less than the rht 

sequence, otherwise zero is returned. 

See Also: String:: operator !=, operator ==, operator <=, operator >, operator >= 
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String operator «() 


Synopsis: 

Semantics: 


Results: 
See Also: 


♦include <string.hpp> 
public: 

friend ostream Soperator <<( ostream Sstrm, String const Sstr ); 

The operator << function is used to write the sequence of characters in the str String object to 
the strm ostream object. Like C strings, the value of the str String object is written to strm without 
the addition of any characters. No special processing occurs for any characters in the String object 
that have special meaning for the strm object, such as carriage-returns. 

The underlying implementation of the operator << function uses the ostream write method, which 
writes unformatted characters to the output stream. If formatted output is required, then the 
programmer should make use of the classes accessor methods, such as c_str(), and pass the resulting 
data item to the stream using the appropriate insert operator. 

The operator << function returns a reference to the strm parameter. 

ostream 
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String operator <=() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <string.hpp> 
public: 

friend int operator <=( String const Sift, String const &rht ); 
friend int operator <=( String const &lft, char const *rht ); 

friend int operator <=( char const *lft. String const &rht ); 

friend int operator <=( String const &lft, char rht ); 

friend int operator <=( char 1ft, String const &rht ); 

The operator <= function compares two sequences of characters in terms of a less-than or equal 
relationship. 

Ift is less-than or equal to rht if the characters of Ift are equal to or occur before the characters of rht in 
the collating sequence. Upper-case and lower-case characters are considered different. 

The operator <= function returns a non-zero value if the Ift sequence of characters is less than or 
equal to the rht sequence, otherwise zero is returned. 

String::operator !=, operator ==, operator <, operator >, operator >= 
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String-operator =() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <string.hpp> 
public: 

String SString::operator =( String const Sstr ); 

String SString::operator =( char const *pch ); 

The operator = public member function sets the contents of the String object to be the same as 
the parameter. 

The first form of the operator = public member function sets the value of the String object to be 
the same as the value of the str String object. 

The second form sets the value of the String object to the null-terminated sequence of characters 
stored at pch. If the pch parameter is NULL, the String object is empty. 

The operator = public member function returns a reference to the String object that was the 
target of the assignment. 

String::operator +=, String 
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String operator ==() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <string.hpp> 
public: 

friend int operator ==( String const Sift, String const &rht ); 
friend int operator ==( String const &lft, char const *rht ); 

friend int operator ==( char const *lft. String const &rht ); 

friend int operator ==( String const &lft, char rht ); 

friend int operator ==( char 1ft, String const &rht ); 

The operator == function compares two sequences of characters in terms of an equality 
relationship. 

A String object is equal to another String object if they have the same length and they contain the 
same sequence of characters. A String object and a C string are equal if their lengths are the same 
and they contain the same sequence of characters. The C string is terminated by a null character. A 
String object and a character are equal if the String object contains only that character. 
Upper-case and lower-case characters are considered different. 

The operator == function returns a non-zero value if the lengths and sequences of characters in the 
Ift and rht parameter are identical, otherwise zero is returned. 

String::operator !=, operator <, operator <=, operator >, operator >= 
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String operator >() 


Synopsis: #include <string.hpp> 

public: 

friend int operator >( String const Sift, String const &rht ); 
friend int operator >( String const Sift, char const *rht ); 

friend int operator >( char const *lft. String const &rht ); 

friend int operator >( String const Sift, char rht ); 

friend int operator >( char 1ft, String const &rht ); 

Semantics: The operator > function compares two sequences of characters in terms of a greater-than 

relationship. 

Ift is greater-than rht if the characters of Ift occur after the characters of rht in the collating sequence. 
Upper-case and lower-case characters are considered different. 

Results: The operator > function returns a non-zero value if the Ift sequence of characters is greater than the 

rht sequence, otherwise zero is returned. 

See Also: String: :operator !=, operator ==, operator <, operator <=, operator >= 
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String operator >=() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <string.hpp> 
public: 

friend int operator >=( String const Sift, String const &rht ); 
friend int operator >=( String const &lft, char const *rht ); 

friend int operator >=( char const *lft. String const &rht ); 

friend int operator >=( String const &lft, char rht ); 

friend int operator >=( char 1ft, String const &rht ); 

The operator >= function compares two sequences of characters in terms of a greater-than or equal 
relationship. 

Ift is greater-than or equal to rht if the characters of Ift are equal to or occur after the characters of rht in 
the collating sequence. Upper-case and lower-case characters are considered different. 

The operator >= function returns a non-zero value if the Ift sequence of characters is greater than or 
equal to the rht sequence, otherwise zero is returned. 

String::operator !=, operator ==, operator <, operator <=, operator > 
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String operator »() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <string.hpp> 
public: 

friend istream Soperator >>( istream Sstrm, String Sstr ); 

The operator >> function is used to read a sequence of characters from the strm istream object 
into the str String object. Like C strings, the gathering of characters for a sir String object ends at 
the first whitespace encountered, so that the last character placed in str is the character before the 
whitespace. 

The operator >> function returns a reference to the strm parameter, 
istream 
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String::operator []() 


Synopsis: 


Semantics: 


Results: 


See Also: 


#include <string.hpp> 
public: 

char const SString::operator []( size_ t pos ) const; 
char SString::operator [] ( size_ t pos ); 

The operator [ ] public member function creates either a const or a non-const reference to the 
character at offset pos within the String object. The non-const reference may be used to modify that 
character. The first character of a String object is at position zero. 

If pos is greater than or equal to the length of the String object, and the resulting reference is used, 
the behavior is undefined. 

If the non-const reference is used to modify other characters within the String object, the behavior is 
undefined. 

The reference is associated with the String object, and therefore has meaning only as long as the 
String object is not modified (or destroyed). If the String object has been modified and an old 
reference is used, the behavior is undefined. 

The operator [ ] public member function returns either a const or a non-const reference to a 
character. 

String::operator (), operator char, operator char const * 
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String-operator char() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <string.hpp> 
public: 

String::operator char() ; 

The operator char public member function converts a String object into the first character it 
contains. If the String object is empty, the result is the null character. 

The operator char public member function returns the first character contained in the String 
object. If the String object is empty, the null character is returned. 

String::operator (), operator [], operator char const * 
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String-operator char const *() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <string.hpp> 
public: 

String::operator char const *(); 

The operator char const * public member function converts a String object into a C string 
containing the same length and sequence of characters, terminated by a null character. If the String 
object contains a null character the resulting C string is terminated by that null character. 

The returned pointer is associated with the String object, and therefore has meaning only as long as 
the String object is not modified. If the intention is to be able to refer to the C string after the 
String object has been modified, a copy of the string should be made, perhaps by using the C library 
strdup function. 

The returned pointer is a pointer to a constant C string. If the pointer is used in some way to modify the 
C string, the behavior is undefined. 

The operator char const * public member function returns a pointer to a null-terminated 
constant C string that contains the same characters as the String object. 

String::operator (), operator [],operator char 
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String: :put_at() 


Synopsis: 

Semantics: 

Results: 
See Also: 


#include <string.hpp> 
public: 

void String: :put_ at ( size_ t pos, char chr ); 

The put_ at public member function modifies the character at offset pos within the String object. 
The character at the specified offset is set to the value of chr. If pos is greater than the number of 
characters within the String object, chr is appended to the String object. 

The put_ at public member function has no return value. 

String::get_ at,operator [], operator (), operator +=, operator + 


String Class 887 




String::String() 


Synopsis: #include <string.hpp> 

public: 

String::String(); 


Semantics: 

Results: 
See Also: 


This form of the public String constructor creates a default String object containing no characters. 
The created String object has length zero. 

This form of the public String constructor produces a String object. 

String::operator =, operator +=, ~String 
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String::String() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <string.hpp> 
public: 

String::String( size_t size, String::capacity cap ); 

This form of the public String constructor creates a String object. The function constructs a 
String object of length size if cap is equal to the enumerated default_size. The function reserves size 
bytes of memory and sets the length of the String object to be zero if cap is equal to the enumerated 
resen’e. 

This form of the public String constructor produces a String object of size size. 

String::operator =, ~String 
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String::String() 


Synopsis: #include <string.hpp> 

public: 

String:: String ( String const Sstr, size_ t pos = 0, size_ t num = NPOS 

) ; 


Semantics: 

Results: 
See Also: 


This form of the public String constructor creates a String object which contains a sub-string of 
the str parameter. The sub-string starts at position pos within str and continues for num characters or 
until the end of the str parameter, whichever comes first. 

This form of the public String constructor produces a sub-string or duplicate of the str parameter. 
String::operator =, operator (), operator [], -String 
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String::String() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <string.hpp> 
public: 

String::String( char const *pch, size_ t num = NPOS ); 

This form of the public String constructor creates a String object from a C string. The String 
object contains the sequence of characters located at the pch parameter. Characters are included up to 
num or the end of the C string pointed at by pch. Note that C strings are terminated by a null character 
and that the value of the created String object does not contain that character, nor any following it. 

This form of the public String constructor produces a String object of at most length n containing 
the characters in the C string starting at the pch parameter. 

String::operator =, operator char const *, operator (),operator [], 
~String 
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String::String() 


Synopsis: 


Semantics: 


Results: 


See Also: 


♦include <string.hpp> 
public: 

String::String( char ch, size_t rep = 1 ); 

This form of the public String constructor creates a String object containing rep copies of the ch 
parameter. 

This form of the public String constructor produces a String object of length rep containing only 
the character specified by the ch parameter. 

String::operator =, operator char, ~String 
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String::~String() 


Synopsis: 

Semantics: 

Results: 
See Also: 


♦include <string.hpp> 
public: 

String::-String() ; 

The public -String destructor destroys the String object. The call to the public -String 
destructor is inserted implicitly by the compiler at the point where the String object goes out of 
scope. 

The String object is destroyed. 

String 
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String::upper() 


Synopsis: #include <string.hpp> 

public: 

String String::upper () const; 


Semantics: 

Results: 
See Also: 


The upper public member function creates a new String object whose value is the same as the 
original String object, except that all lower-case letters have been converted to upper-case. 

The upper public member function returns a new upper-case String object. 

String::lower 
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String valid() 


Synopsis: 

Semantics 

Results: 

See Also: 


♦include <string.hpp> 
public: 

friend int valid( String const Sstr ); 

The valid function tests the validity of the str String object. 

The valid function returns a non-zero value if the str String object is valid, otherwise zero is 
returned. 

String::operator !, valid 
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String::valid() 


Synopsis: 

Semantics 

Results: 

See Also: 


#include <string.hpp> 
public: 

int String::valid() const; 

The valid public member function tests the validity of the String object. 

The valid public member function returns a non-zero value if the String object is valid, otherwise 
zero is returned. 

String::operator !, valid 
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NOT_EOF 7 


A 


abs, related function 
Complex 19-20 
acos, related function 
Complex 19, 21 
acosh, related function 
Complex 19, 22 
adjustfield, member enumeration 
ios 665 

all_fine, member enumeration 
WCExcept 70 
WCIterExcept 75 
alloc_mult_size, member function 
String 862,864 

alloc_size_increment, member function 
strstreambuf 846-847 
allocate, member function 
streambuf 792, 794 
allocator 

function 259, 263, 286, 290, 416, 514 
app, member enumeration 
ios 675 

append, member enumeration 
ios 675 

append, member function 

WCIsvConstDListIter<Type> 308 
WCIsvConstSListIter<Type> 308 
WCIsvDList<Type> 233, 241 
WCIsvDListIter<Type> 324, 332 
WCIsvSList<Type> 233, 241 
WCIsvSListIter<Type> 324, 332 
WCPtrConstDListIter<Type> 343 
WCPtrConstSListIter<Type> 343 
WCPtrDList<Type> 256, 266 
WCPtrDListIter<Type> 359, 367 
WCPtrOrderedVector<Type> 525, 532 
WCPtrSList<Type> 256, 266 
WCPtrSListIter<Type> 359, 367 
WCPtrSortedVector<Type> 525, 532 
WCValConstDListIter<Type> 378 
WCValConstSListIter<Type> 378 
WCValDList<Type> 283, 293 


WCValDListIter<Type> 394, 402 
WCValOrderedVector<Type> 568, 576 
WCValSList<Type> 283, 293 
WCValSListIter<Type> 394, 402 
WCValSortedVector<Type> 568, 576 
arg, related function 
Complex 19, 23 
asin, related function 
Complex 19, 24 
asinh, related function 
Complex 19, 25 
atan, related function 
Complex 19, 26 
atanh, related function 
Complex 19, 27 
ate, member enumeration 
ios 675 

atend, member enumeration 
ios 675 

attach, member function 
filebuf 610, 612 
fstreambase 635-636 


B 


bad, member function 
ios 655, 657 

badbit, member enumeration 
ios 673 

base, member function 
streambuf 792, 795 
basefield, member enumeration 
ios 665 

beg, member enumeration 
ios 683 

binary, member enumeration 
ios 675 

bitalloc, member function 
ios 656, 658 

bitHash, member function 

WCPtrHashDict<Key,Value> 82, 88 
WCPtrHashSet<Type> 106,115 
WCPtrHashT able<T ype> 106,115 
W C V alHashDict<Key, V alue> 132, 137 
WCValHashSet<Type> 154, 163 
W C V alHashT able<Type> 154, 163 
blen, member function 
streambuf 792, 796 
buckets, member function 

WCPtrHashDict<Key,Value> 82, 89 
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WCPtrHashSet<Type> 106,116 
WCPtrHashTable<Type> 106,116 
WC V alHashDict<Key, V alue> 132, 138 
WCV alHashSet<Type> 154, 164 
WC V alHashT able<T ype> 154, 164 


c 


cerr 9 

check_all, member enumeration 
WCExcept 70 
WCIterExcept 75 
check_none, member enumeration 
WCExcept 70 
WCIterExcept 75 
cin 9 

clear, member function 
ios 655, 659 

WCIsvDList<Type> 233, 242 
WCIsvSList<Type> 233, 242 
WCPtrDList<Type> 256, 267 
WCPtrHashDict<Key,Value> 83, 90 
WCPtrHashSet<Type> 106,117 
W CPtrHashT able<Type> 106,117 
WCPtrOrderedVector<Type> 525, 533 
WCPtrSkipList<Type> 446, 456 
WCPtrSkipListDict<Key,Value> 426, 432 
WCPtrSkipListSet<Type> 446, 456 
WCPtrSList<Type> 256, 267 
WCPtrSortedVector<Type> 525, 533 
WCPtrVector<Type> 555, 560 
WCQueue<Type,FType> 414, 418 
WCStack<Type,FType> 512,516 
WCValDList<Type> 283, 294 
WC ValHashDict<Key, Value> 132, 139 
WCValHashSet<Type> 154, 165 
WCValHashTable<Type> 154, 165 
WCValOrderedVector<Type> 568, 577 
WCValSkipList<Type> 489, 498 
WCValSkipListDict<Key,Value> 470, 475 
WCValSkipListSet<Type> 489, 498 
WCValSList<Type> 283, 294 
WCValSortedVector<Type> 568, 577 
WCValVector<Type> 598, 603 
clearAndDestroy, member function 
WCIsvDList<Type> 233, 243 
WCIsvSList<Type> 233, 243 
WCPtrDList<Type> 256, 268 
WCPtrHashDict<Key,Value> 83, 91 
WCPtrHashSet<Type> 106,118 


WCPtrHashT able<T ype> 106,118 
WCPtrOrderedVector<Type> 525, 534 
WCPtrSkipList<Type> 446, 457 
WCPtrSkipListDict<Key,Value> 426, 433 
WCPtrSkipListSet<Type> 446, 457 
WCPtrSList<Type> 256, 268 
WCPtrSortedVector<Type> 525, 534 
WCPtrVector<Type> 555, 561 
WCValDList<Type> 283, 295 
WCValSList<Type> 283, 295 
clog 9 

close, member function 
filebuf 610, 613 
fstreambase 635, 637 
common types 7 
Complex class 17 
Complex related functions 
abs 19-20 
acos 19, 21 
acosh 19, 22 
arg 19, 23 
asin 19, 24 
asinh 19, 25 
atan 19, 26 
atanh 19, 27 
conj 19, 32 
cos 19, 33 
cosh 19, 34 
exp 19, 35 
imag 19, 37 
log 19 
log 10 19,39 
norm 19, 40 
num 38 

operator != 19, 41 
operator* 18,42 
operator + 18,45 
operator- 18,48 
operator/ 18,50 
operator « 18,52 
operator == 18-19, 54 
operator » 18,55 
polar 19, 56 
pow 19, 57 
real 19, 59 
sin 19, 60 
sinh 19, 61 
sqrt 19, 62 
tan 19, 63 
tanh 19, 64 

Complex::Complex 18, 28-30 
Complex::imag 18, 36 
Complex::operator *= 18,43 
Complex::operator + 18, 44 


898 




Index 


Complex: :operator += 18,46 
Complex:roperator - 18,47 
Complex::operator-= 18,49 
Complex: :operator/= 18,51 
Complex: :operator = 18, 53 
Complex::real 18, 58 
Complex::~Complex 18, 31 
conj, related function 
Complex 19, 32 
constructor 

Complex 18, 28-30 
filebuf 610, 615-617 
fstream 628-632 
fstreambase 635, 638-641 
ifstream 648-652 
ios 655,670-671 
iostream 691-694 
istream 698,710-712 
istrstream 729-731 
ofstream 748-752 
ostream 755,769-771 
ostrstream 778-780 


stdiobuf 784, 786-787 
streambuf 792, 830-831 
String 862,888-892 
strstream 836, 838-839 
strstreambase 841, 843-844 
strstreambuf 846, 854-857 
WCDLink 230-231 


WCExcept 66-67 
WCIsvConstSListIter<Type> 308 
WCIsvSList<Type> 233 
WCIsvSListIter<Type> 324 
WCIterExcept 71-72 
WCPtrConstSListIter<Type> 343 
WCPtrHashDict<Key,Value> 84-86 
WCPtrHashDictIter<Key, V alue> 180 
WCPtrHashSetIter<Type> 202 
WCPtrHashT able<Type> 107-109, 111-113 
WCPtrSkipList<Type> 448-450, 452-454 
WCPtrSkipListDict<Key,Value> 428-430 
WCPtrSList<Type> 256 
WCPtrSListIter<Type> 359 
WCPtrSortedVector<Type> 526-527, 529-530 
WCPtrVector<Type> 555-558 
WCQueue<Type,FType> 414-416 
WCSLink 280-281 


WCStack<Type,FType> 512-514 
WCValConstSListIter<Type> 378 
WC ValHashDict<Key, V alue> 133-135 
WC V alHashDictIter<Key, V alue> 191 
WCValHashSetIter<Type> 215 
WC V alHashT able<T ype> 155-157, 159-161 
WCValSkipList<Type> 490-492, 494-496 


WCValSkipListDict<Key,Value> 471 -473 
WCValSList<Type> 283 
WCValSListIter<Type> 394 
WCValSortedVector<Type> 570-571, 
573-574 

WCValVector<Type> 598-601 
container, member function 

WCIsvConstDListIter<Type> 308, 315 
WCIsvConstSListIter<Type> 308, 315 
WCIsvDListIter<Type> 324, 333 
WCIsvSListIter<Type> 324, 333 
WCPtrConstDListIter<Type> 343, 350 
WCPtrConstSListIter<Type> 343, 350 
WCPtrDListIter<Type> 359, 368 
WCPtrHashDictIter<Key,Value> 180, 184 
WCPtrHashSetIter<Type> 202, 209 
WCPtrHashTableIter<Type> 202, 209 
WCPtrSListIter<Type> 359, 368 
WCValConstDListIter<Type> 378, 385 
WCValConstSListIter<Type> 378, 385 
WCValDListIter<Type> 394, 403 
WC V alHashDictIter<Key, V alue> 191, 195 
WCValHashSetIter<Type> 215, 222 
WCValHashTableIter<Type> 215, 222 
WCValSListIter<Type> 394, 403 
contains, member function 

WCIsvDList<Type> 233, 244 
WCIsvSList<Type> 233, 244 
WCPtrDList<Type> 256, 269 
WCPtrHashDict<Key,Value> 83, 92 
WCPtrHashSet<Type> 106,119 
WCPtrHashT able<T ype> 106,119 
WCPtrOrderedVector<Type> 525, 535 
WCPtrSkipList<Type> 447, 458 
WCPtrSkipListDict<Key,Value> 426, 434 
WCPtrSkipListSet<Type> 447, 458 
WCPtrSList<Type> 256, 269 
WCPtrSortedVector<Type> 525, 535 
WCValDList<Type> 283, 296 
W C V alHashDict<Key, V alue> 132, 140 
WC V alHashSet<T ype> 154, 166 
W C V alHashT able<Type> 154, 166 
WCValOrderedVector<Type> 568, 578 
WCValSkipList<Type> 489, 499 
WCValSkipListDict<Key,Value> 470, 476 
WCValSkipListSet<Type> 489, 499 
WCValSList<Type> 283, 296 
WCValSortedVector<Type> 568, 578 
cos, related function 
Complex 19, 33 
cosh, related function 
Complex 19, 34 
cout 9 

cur, member enumeration 
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ios 683 

current, member function 

WCIsvConstDListIter<Type> 308, 316 
WCIsvConstSListIter<Type> 308, 316 
WCIsvDListIter<Type> 324, 334 
WCIsvSListIter<Type> 324, 334 
WCPtrConstDListIter<Type> 343, 351 
WCPtrConstSListIter<Type> 343, 351 
WCPtrDListIter<Type> 359, 369 
WCPtrHashSetIter<Type> 202, 210 
WCPtrHashTableIter<Type> 202, 210 
WCPtrSListIter<Type> 359, 369 
WCValConstDListIter<Type> 378, 386 
WCValConstSListIter<Type> 378, 386 
WCValDListIter<Type> 394, 404 
WCValHashSetIter<Type> 215, 223 
WCValHashTableIter<Type> 215, 223 
WCValSListIter<Type> 394, 404 


D 


dbp, member function 
streambuf 793, 797 
dealloctor 

function 259, 263, 286, 290, 416, 514 
dec, manipulator 733-734 
dec, member enumeration 
ios 665 
destructor 

Complex 18, 31 

filebuf 610, 618 

fstream 628, 633 

fstreambase 635, 642 

ifstream 648, 653 

ios 655, 672 

iostream 691, 695 

istream 698,713 

istrstream 729, 732 

ofstream 748, 753 

ostream 755, 772 

ostrstream 778, 781 

stdiobuf 784, 788 

streambuf 792, 832 

String 862,893 

strstream 836, 840 

strstreambase 841, 845 

strstreambuf 846, 858 

WCDLink 230, 232 

WCExcept 66, 68 

WCIsvConstSListIter<Type> 308 


WCIsvSList<Type> 233 
WCIsvSListIter<Type> 324 
WCIterExcept 71,73 
WCPtrConstSListIter<Type> 343 
WCPtrHashDict<Key,Value> 87 
WCPtrHashDictIter<Key,Value> 180 
WCPtrHashSetIter<Type> 202 
WCPtrHashT able<T ype> 110,114 
WCPtrSkipList<Type> 451,455 
WCPtrSkipListDict<Key,Value> 431 
WCPtrSList<Type> 256 
WCPtrSListIter<Type> 359 
WCPtrSortedVector<Type> 528,531 
WCPtrVector<Type> 555, 559 
WCQueue<Type,FType> 414, 417 
WCSLink 280, 282 
WCStack<Type,FType> 512,515 
WCValConstSListIter<Type> 378 
W C V alHashDict<Key, V alue> 136 
WC V alHashDictIter<Key, V alue> 191 
WCValHashSetIter<Type> 215 
W C V alHashT able<Type> 158, 162 
WCValSkipList<Type> 493, 497 
WCValSkipListDict<Key,Value> 474 
WCValSList<Type> 283 
WCValSListIter<Type> 394 
WCValSortedVector<Type> 572, 575 
WCValVector<Type> 598, 602 
do_sgetn, member function 
streambuf 793, 798 
do_sputn, member function 
streambuf 793, 799 
doallocate, member function 
streambuf 792, 800 
strstreambuf 846, 848 


E 


eatwhite, member function 
istream 698, 700 
eback, member function 
streambuf 792, 801 
ebuf, member function 
streambuf 792, 802 
egptr, member function 
streambuf 792, 803 
empty _container 

exception 70, 246-247, 249, 271-272, 274, 
298-299, 301, 420-421, 424, 519, 521, 
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538, 543, 545, 551-553, 563, 581, 586, 
588, 594-596, 605 

empty_container, member enumeration 
WCExcept 70 
end, member enumeration 
ios 683 

endl, manipulator 733, 735 
ends, manipulator 733, 736 
entries, member function 

WCIsvDList<Type> 233, 245 
WCIsvSList<Type> 233, 245 
WCPtrDList<Type> 256, 270 
WCPtrHashDict<Key,Value> 83, 93 
WCPtrHashSet<Type> 106, 120 
WCPtrHashTable<Type> 106, 120 
WCPtrOrderedVector<Type> 525, 536 
WCPtrSkipList<Type> 447, 459 
WCPtrSkipListDict<Key,Value> 426, 435 
WCPtrSkipListSet<Type> 447, 459 
WCPtrSList<Type> 256, 270 
WCPtrSortedVector<Type> 525, 536 
WCQueue<Type,FType> 414, 419 
WCStack<Type,FType> 512,517 
WCValDList<Type> 283, 297 
WCV alHashDict<Key, V alue> 132, 141 
WCValHashSet<Type> 154, 167 
WCV alHashT able<T ype> 154, 167 
WCValOrderedVector<Type> 568, 579 
WCValSkipList<Type> 489, 500 
WCValSkipListDict<Key,Value> 470, 477 
WCValSkipListSet<Type> 489, 500 
WCValSList<Type> 283, 297 
WCValSortedVectorcType> 568, 579 
EOF 7 

eof, member function 
ios 655, 660 

eofbit, member enumeration 
ios 673 

epptr, member function 
streambuf 792, 804 
exception handling 3 
exceptions 70 
function 75 

exceptions, member function 
ios 655, 661 
WCExcept 66, 69 
WCIterExcept 71,74 
exp, related function 
Complex 19, 35 
extractor 11,698 


F 


fail, member function 
ios 655, 662 

failbit, member enumeration 
ios 673 

fd, member function 
filebuf 610, 614 
fstreambase 635, 644 
filebuf 791 

filebuf::attach 610, 612 
filebuf: :close 610,613 
filebuf: :fd 610,614 
filebuf::filebuf 610,615-617 
filebuf: :is_open 610, 619 
filebuf::open 610,620 
filebuf: :openprot 610, 621 
filebuf: :overflow 610, 622 
filebuf: :pbackfail 610,623 
filebuf: :seekoff 611,624 
filebuf: :setbuf 611,625 
filebuf:: sync 611, 626 
filebuf: underflow 610,627 
filebuf::-filebuf 610, 618 
filedesc 7 
fill character 663 
fill, member function 
ios 655, 663 
find, member function 

WCIsvDList<Type> 233, 246 
WCIsvSList<Type> 233, 246 
WCPtrDList<Type> 256, 271 
WCPtrHashDict<Key,Value> 83, 94 
WCPtrHashSet<Type> 106, 121 
WCPtrHashT able<T ype> 106, 121 
WCPtrOrderedVector<Type> 525, 537 
WCPtrSkipList<Type> 447, 460 
WCPtrSkipListDict<Key,Value> 426, 436 
WCPtrSkipListSet<Type> 447, 460 
WCPtrSList<Type> 256, 271 
WCPtrSortedVector<Type> 525, 537 
WCValDList<Type> 283, 298 
WCV alHashDict<Key, V alue> 132, 142 
WCV alHashSet<T ype> 154, 168 
WC ValHashT able<Type> 154, 168 
WCValOrderedVector<Type> 568, 580 
WCValSkipList<Type> 489, 501 
WCValSkipListDict<Key,Value> 470, 478 
WCValSkipListSet<Type> 489, 501 
WCValSList<Type> 283, 298 
WCValSortedVector<Type> 568, 580 
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findKey And Value, member function 
WCPtrHashDict<Key,Value> 83, 95 
WCPtrSkipListDict<Key,Value> 426, 437 
WCValHashDict<Key,Value> 132, 143 
WCValSkipListDict<Key,Value> 470, 479 
findLast, member function 

WCIsvDList<Type> 233, 247 
WCIsvSList<Type> 233, 247 
WCPtrDList<Type> 256, 272 
WCPtrSList<Type> 256, 272 
WCValDList<Type> 283, 299 
WCValSList<Type> 283, 299 
first, member function 

WCPtrOrderedVector<Type> 525, 538 
WCPtrSortedVector<Type> 525, 538 
WCQueue<Type,FType> 414, 420 
WCValOrderedVector<Type> 568, 581 
WCValSortedVector<Type> 568, 581 
fixed, member enumeration 
ios 665 

flags, member function 
ios 655, 664 

floatfield, member enumeration 
ios 665 

flush, manipulator 733, 737 
flush, member function 
ostream 755, 757 
fmtflags, member enumeration 
ios 655, 665 
forall, member function 

WCIsvDList<Type> 233, 248 
WCIsvSList<Type> 233, 248 
WCPtrDList<Type> 256, 273 
WCPtrHashDict<Key,Value> 83, 96 
WCPtrHashSet<Type> 106, 122 
WCPtrHashTable<Type> 106, 122 
WCPtrSkipList<Type> 447, 461 
WCPtrSkipListDict<Key,Value> 426, 438 
WCPtrSkipListSet<Type> 447,461 
WCPtrSList<Type> 256, 273 
WCValDList<Type> 283, 300 
WC V alHashDict<Key, Value> 132, 144 
WCValHashSet<Type> 154, 169 
WC V alHashT able<T ype> 154, 169 
WCValSkipList<Type> 489, 502 
WCValSkipListDict<Key,Value> 470, 480 
WCValSkipListSet<Type> 489, 502 
WCValSList<Type> 283, 300 
format precision 679 
format width 689 
formatted input 11 
formatted output 13 
freeze, member function 
strstreambuf 846, 849 


fstream 635, 691 
fstream::fstream 628-632 
fstream: :open 628, 634 
fstream::~fstream 628, 633 
fstreambase 628, 648, 748 
fstreambase::attach 635-636 
fstreambase::close 635, 637 
fstreambase::fd 635, 644 
fstreambase::fstreambase 635, 638-641 
fstreambase::is_open 635, 643 
fstreambase::open 635, 645 
fstreambase::rdbuf 635, 646 
fstreambase ::setbuf 635, 647 
fstreambase::~fstreambase 635, 642 
functions and types 15 


G 


gbump, member function 
streambuf 792, 805 
gcount, member function 
istream 699, 701 
get area 791 
get pointer 806 
get, member function 
istream 698, 702-705 
WCIsvDList<Type> 233, 249 
WCIsvSList<Type> 233, 249 
WCPtrDList<Type> 256, 274 
WCPtrSList<Type> 256, 274 
WCQueue<Type,FType> 414,421 
WCValDList<Type> 283, 301 
WCValSList<Type> 283, 301 
get_at, member function 
String 862, 865 
getline, member function 
istream 698, 706 
good, member function 
ios 655, 668 

goodbit, member enumeration 
ios 673 

gptr, member function 
streambuf 792, 806 


H 


header files 
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algorithm 3 
complex 3 
exception 3 
fstream 4 
functional 3 
generic 4 
iomanip 4 
ios 4 
iosfwd 4 
iostream 4 
istream 4 
iterator 4 
limits 4 
list 4 
map 4 
memory 4 
new 5 
numeric 5 
ostream 5 
set 5 

stdiobuf 5 
streambuf 5 
string 5 
strstream 5 
vector 5 
wcdefs 5 
wclbase 5 
wclcom 5 
wclibase 5 
wclist 5 
wclistit 5 
wcqueue 6 
wcstack 6 

hex, manipulator 733, 738 

hex, member enumeration 
ios 665 



ifstream 635, 698 
ifstream::ifstream 648-652 
ifstream: :open 648,654 
ifstream::~ifstream 648,653 
ignore, member function 
istream 698, 707 
imag, member function 
Complex 18, 36 
imag, related function 
Complex 19, 37 
in, member enumeration 


ios 675 

in_avail, member function 
streambuf 793, 807 
index, member function 
String 862, 866 

WCIsvDList<Type> 233,250-251 
WCIsvSList<Type> 233,250-251 
WCPtrDList<Type> 256, 275 
WCPtrOrderedVector<Type> 525, 539 
WCPtrSList<Type> 256, 275 
WCPtrSortedVector<Type> 525, 539 
WCValDList<Type> 283, 302 
WCValOrderedVector<Type> 568, 582 
WCValSList<Type> 283, 302 
WCValSortedVector<Type> 568, 582 
index_range 

exception 70, 100, 148, 247, 272, 299, 

420-421, 424, 442, 484, 519, 521, 538, 
541, 543, 545, 563, 581, 584, 586, 588, 
605 

index_range, member enumeration 
WCExcept 70 
init, member function 
ios 655, 669 
insert, member function 

WCIsvConstDListIter<Type> 308 
WCIsvConstSListIter<Type> 308 
WCIsvDList<Type> 233, 252 
WCIsvDListIter<Type> 324, 335 
WCIsvSList<Type> 233, 252 
WCIsvSListIter<Type> 324, 335 
WCPtrConstDListIter<Type> 343 
WCPtrConstSListIter<Type> 343 
WCPtrDList<Type> 256, 276 
WCPtrDListIter<Type> 359, 370 
WCPtrHashDict<Key,Value> 83, 97 
WCPtrHashSet<Type> 106, 123 
WCPtrHashT able<T ype> 106, 123 
WCPtrOrderedVector<Type> 525, 540 
WCPtrSkipList<Type> 447, 462 
WCPtrSkipListDict<Key,Value> 426, 439 
WCPtrSkipListSet<Type> 447, 462 
WCPtrSList<Type> 256, 276 
WCPtrSListIter<Type> 359, 370 
WCPtrSortedVector<Type> 525, 540 
WCQueue<Type,FType> 414, 422 
WCValConstDListIter<Type> 378 
WCValConstSListIter<Type> 378 
WCValDList<Type> 283, 303 
WCValDListIter<Type> 394, 405 
W C V alHashDict<Key, V alue> 132, 145 
WC ValHashSet<Type> 154, 170 
W C V alHashT able<Type> 154, 170 
WCValOrderedVector<Type> 568, 583 
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WCValSkipList<Type> 489, 503 
WCValSkipListDict<Key,Value> 470, 481 
WCValSkipListSet<Type> 489, 503 
WCValSList<Type> 283, 303 
WCValSListIter<Type> 394, 405 
WCValSortedVector<Type> 568, 583 
insertAt, member function 

WCPtrOrderedVector<Type> 525, 541 
WCPtrSortedVector<Type> 525, 541 
WCValOrderedVector<Type> 568, 584 
WCValSortedVector<Type> 568, 584 
inserter 13, 755 
internal, member enumeration 
ios 665 
intrusive 
classes 233 
ios 635, 698, 755, 841 
ios::adjustfield 665 
ios::app 675 
ios::append 675 
ios::ate 675 
ios::atend 675 
ios::bad 655, 657 
ios::badbit 673 
ios::basefield 665 
ios::beg 683 
ios::binary 675 
ios::bitalloc 656,658 
ios::clear 655,659 
ios::cur 683 
ios::dec 665 
ios::end 683 
ios::eof 655, 660 
ios::eofbit 673 
ios:exceptions 655, 661 
ios::fail 655, 662 
ios::failbit 673 
ios::fill 655,663 
ios::fixed 665 
ios::flags 655,664 
ios: :floatfield 665 
ios::fmtflags 655,665 
ios::good 655, 668 
ios::goodbit 673 
ios::hex 665 
ios::in 675 
ios::init 655, 669 
ios: internal 665 
ios::ios 655,670-671 
ios::iostate 655, 673 
ios::iword 656, 674 
ios:deft 665 
ios: :nocreate 675 
ios::noreplace 675 


ios::oct 665 

ios::openmode 655, 675 
ios::operator ! 656, 677 
ios::operator void * 656,678 
ios::out 675 
ios:precision 655, 679 
ios::pword 656,680 
ios::rdbuf 655, 681 
ios::rdstate 655, 682 
ios::right 665 
ios:scientific 665 
ios::seekdir 655, 683 
ios::setf 655, 684 
ios::setstate 655, 685 
ios::showbase 665 
ios::showpoint 665 
ios::showpos 665 
ios::skipws 665 
ios::stdio 665 

ios::sync_with_stdio 656, 686 
ios::text 675 
ios::tie 655, 687 
ios::trunc 675 
ios:truncate 675 
ios::unitbuf 665 
ios::unsetf 655, 688 
ios:uppercase 665 
ios::width 655-656, 689 
ios::xalloc 656, 690 
ios::~ios 655, 672 
iostate, member enumeration 
ios 655, 673 

iostream 628, 698, 755, 836 
iostream::iostream 691-694 
iostream: :operator = 691,696-697 
iostream::-iostream 691, 695 
ipfx, member function 
istream 698, 708 
is_open, member function 
filebuf 610, 619 
fstreambase 635, 643 
isEmpty, member function 
WCIsvDList<Type> 233, 253 
WCIsvSList<Type> 233, 253 
WCPtrDList<Type> 256, 277 
WCPtrHashDict<Key,Value> 83, 98 
WCPtrHashSet<Type> 106, 124 
WCPtrHashT able<T ype> 106, 124 
WCPtrOrderedVector<Type> 525, 542 
WCPtrSkipList<Type> 447, 463 
WCPtrSkipListDict<Key,Value> 426, 440 
WCPtrSkipListSet<Type> 447, 463 
WCPtrSList<Type> 256, 277 
WCPtrSortedVector<Type> 525, 542 
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WCQueue<Type,FType> 414, 423 
WCStack<Type,FType> 512,518 
WCValDList<Type> 283, 304 
WCValHashDict<Key,Value> 132, 146 
WCValHashSet<Type> 154, 171 
WC V alHashT able<T ype> 154, 171 
WCValOrderedVector<Type> 568, 585 
WCValSkipList<Type> 489, 504 
WCValSkipListDict<Key,Value> 470, 482 
WCValSkipListSet<Type> 489, 504 
WCValSList<Type> 283, 304 
WCValSortedVector<Type> 568, 585 
isfx, member function 
istream 698, 709 
istream 648, 655, 691, 729 
istream input 11 
istream: :eatwhite 698, 700 
istream: :gcount 699, 701 
istream::get 698,702-705 
istream: :getline 698, 706 
istream::ignore 698, 707 
istream: :ipfx 698, 708 
istream::isfx 698, 709 
istream: :istream 698,710-712 
istream: :operator = 699, 714-715 
istream: :operator » 699, 716-721 
istream: :peek 699, 722 
istream::putback 698,723 
istream: :read 698, 724 
istream::seekg 698,725-726 
istream::sync 699, 727 
istream: :tellg 698, 728 
istream::~istream 698,713 
istrstream 698, 841 
istrstream::istrstream 729-731 
istrstream::-istrstream 729, 732 
iter_range 

exception 75, 319, 321, 338, 340, 354, 356, 
373, 375, 389, 391,408,410 
iter_range, member enumeration 
WCIterExcept 75 
iterator classes 5 
iword, member function 
ios 656, 674 


K 


key, member function 

WCPtrHashDictIter<Key,V alue> 180, 185 
WC V alHashDictltercKey, V alue> 191, 196 


L 


last, member function 

WCPtrOrderedVector<Type> 525, 543 
WCPtrSortedVector<Type> 525, 543 
WCQueue<Type,FType> 414, 424 
WCValOrderedVector<Type> 568, 586 
WCValSortedVectorcType> 568, 586 
left, member enumeration 
ios 665 

length, member function 
String 862,867 
WCPtrVector<Type> 555, 562 
WCValVector<Type> 598, 604 
list containers 5 
log, related function 
Complex 19 
log 10, related function 
Complex 19, 39 
lower, member function 
String 862, 868 


M 


manipulator manipulators 
dec 733-734 
endl 733, 735 
ends 733,736 
flush 733, 737 
hex 733, 738 
oct 733, 739 
resetiosflags 733, 740 
setbase 733, 741 
setfill 733,742 
setiosflags 733, 743 
setprecision 733, 744 
setw 733, 745 
setwidth 733, 746 
ws 733,747 
manipulators 
dec 733-734 
endl 733, 735 
ends 733,736 
flush 733, 737 
hex 733, 738 
oct 733, 739 
resetiosflags 733, 740 
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setbase 733, 741 
setfill 733,742 
setiosflags 733, 743 
setprecision 733, 744 
setw 733, 745 
setwidth 733, 746 
ws 733,747 
match, member function 
String 862,869 


N 


nocreate, member enumeration 
ios 675 

noreplace, member enumeration 
ios 675 

norm, related function 
Complex 19, 40 
not_empty 

exception 70, 87, 110, 114, 136, 158, 162, 237, 
240, 261, 265, 288, 292, 417, 431, 451, 
455, 474, 493, 497, 515, 528, 531, 559, 
572, 575, 602 

not_empty, member enumeration 
WCExcept 70 
not_unique 

exception 70, 123, 170, 462, 503 
not_unique, member enumeration 
WCExcept 70 
num, related function 
Complex 38 


0 


occurrencesOf, member function 
WCPtrHashSet<Type> 106, 125 
WCPtrHashTable<Type> 106, 125 
WCPtrOrderedVector<Type> 525, 544 
WCPtrSkipList<Type> 447, 464 
WCPtrSkipListSet<Type> 447, 464 
WCPtrSortedVector<Type> 525, 544 
WCV alHashSet<Type> 154, 172 
WC V alHashT able<T ype> 154, 172 
WCValOrderedVector<Type> 568, 587 
WCValSkipList<Type> 489, 505 
WCValSkipListSet<Type> 489, 505 
WCValSortedVector<Type> 568, 587 


oct, manipulator 733, 739 
oct, member enumeration 
ios 665 

ofstream 635, 755 
ofstream::ofstream 748-752 
ofstream::open 748, 754 
ofstream::-ofstream 748, 753 
open, member function 
filebuf 610, 620 
fstream 628, 634 
fstreambase 635, 645 
ifstream 648, 654 
ofstream 748, 754 
openmode, member enumeration 
ios 655, 675 
openprot, member data 
filebuf 621 

openprot, member function 
filebuf 610 

operator !, member function 
ios 656, 677 
String 862,870 
operator !=, related function 
Complex 19, 41 
String 862,871 
operator (), member function 
String 862,872-873 
WCIsvConstDListIter<Type> 308, 317 
WCIsvConstSListIter<Type> 308, 317 
WCIsvDListIter<Type> 324, 336 
WCIsvSListIter<Type> 324, 336 
WCPtrConstDListIter<Type> 343, 352 
WCPtrConstSListIter<Type> 343, 352 
WCPtrDListIter<Type> 359, 371 
WCPtrHashDictIter<Key, Value> 180, 186 
WCPtrHashSetIter<Type> 202,211 
WCPtrHashTableIter<Type> 202,211 
WCPtrSListIter<Type> 359, 371 
WCValConstDListIter<Type> 378, 387 
WCValConstSListIter<Type> 378, 387 
WCValDListIter<Type> 394, 406 
WCV alHashDictIter<Key, V alue> 191, 197 
WCValHashSetIter<Type> 215, 224 
WCValHashTableIter<Type> 215, 224 
WCValSListIter<Type> 394, 406 
operator *, related function 
Complex 18,42 
operator *=, member function 
Complex 18,43 
operator ++, member function 

WCIsvConstDListIter<Type> 308, 318 
WCIsvConstSListIter<Type> 308, 318 
WCIsvDListIter<Type> 324, 337 
WCIsvSListIter<Type> 324, 337 
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WCPtrConstDListIter<Type> 343, 353 
WCPtrConstSListIter<Type> 343, 353 
WCPtrDListIter<Type> 359, 372 
WCPtrHashDictIter<Key, V alue> 180, 187 
WCPtrHashSetIter<Type> 202, 212 
WCPtrHashTableIter<Type> 202, 212 
WCPtrSListIter<Type> 359, 372 
WCValConstDListIter<Type> 378, 388 
WCValConstSListIter<Type> 378, 388 
WCValDListIter<Type> 394, 407 
WC V alHashDictIter<Key, V alue> 191, 198 
WCValHashSetIter<Type> 215, 225 
WCValHashTableIter<Type> 215, 225 
WCValSListIter<Type> 394, 407 
operator +, member function 
Complex 18, 44 
operator +, related function 
Complex 18, 45 
String 863,874 
operator +=, member function 
Complex 18, 46 
String 862,875 

WCIsvConstDListIter<Type> 308, 319 
WCIsvConstSListIter<Type> 308, 319 
WCIsvDListIter<Type> 324, 338 
WCIsvSListIter<Type> 324, 338 
WCPtrConstDListIter<Type> 343, 354 
WCPtrConstSListIter<Type> 343, 354 
WCPtrDListIter<Type> 359, 373 
WCPtrSListIter<Type> 359, 373 
WCValConstDListIter<Type> 378, 389 
WCValConstSListIter<Type> 378, 389 
WCValDListIter<Type> 394, 408 
WCValSListIter<Type> 394, 408 
operator -, member function 
Complex 18, 47 
operator -, related function 
Complex 18, 48 
operator —, member function 

WCIsvConstDListIter<Type> 308, 320 
WCIsvConstSListIter<Type> 308, 320 
WCIsvDListIter<Type> 324-325, 339 
WCIsvSListIter<Type> 324-325, 339 
WCPtrConstDListIter<Type> 343, 355 
WCPtrConstSListIter<Type> 343, 355 
WCPtrDListIter<Type> 359-360, 374 
WCPtrSListIter<Type> 359-360, 374 
WCValConstDListIter<Type> 378, 390 
WCValConstSListIter<Type> 378, 390 
WCValDListIter<Type> 394-395, 409 
WCValSListIter<Type> 394-395, 409 
operator -=, member function 
Complex 18, 49 

WCIsvConstDListIter<Type> 308, 321 


WCIsvConstSListIter<Type> 308, 321 
WCIsvDListIter<Type> 324-325, 340 
WCIsvSListIter<Type> 324-325, 340 
WCPtrConstDListIter<Type> 343, 356 
WCPtrConstSListIter<Type> 343, 356 
WCPtrDListIter<Type> 359-360, 375 
WCPtrSListIter<Type> 359-360, 375 
WCValConstDListIter<Type> 378, 391 
WCValConstSListIter<Type> 378, 391 
WCValDListIter<Type> 394-395, 410 
WCValSListIter<Type> 394-395, 410 
operator /, related function 
Complex 18, 50 
operator /=, member function 
Complex 18, 51 
operator <, related function 
String 862-863,876 
operator «, member function 
ostream 755-756, 758-764 
operator «, related function 
Complex 18, 52 
String 863,877 
operator <=, related function 
String 863,878 
operator =, member function 
Complex 18, 53 
iostream 691, 696-697 
istream 699,714-715 
ostream 755, 765-766 
String 862,879 
WCIsvDList<Type> 233, 254 
WCIsvSList<Type> 233, 254 
WCPtrDList<Type> 256, 278 
WCPtrHashDict<Key,Value> 83, 101 
WCPtrHashSet<Type> 106, 126 
WCPtrHashT able<T ype> 106, 126 
WCPtrOrderedVector<Type> 525, 546 
WCPtrSkipList<Type> 447, 465 
WCPtrSkipListDict<Key,Value> 427, 443 
WCPtrSkipListSet<Type> 447, 465 
WCPtrSList<Type> 256, 278 
WCPtrSortedVector<Type> 525, 546 
WCPtrVector<Type> 555, 564 
WCValDList<Type> 284, 305 
WCValHashDict<Key,Value> 132, 149 
WC V alHashSet<T ype> 154, 173 
W C V alHashT able<Type> 154, 173 
WCValOrderedVector<Type> 569, 589 
WCValSkipList<Type> 489, 506 
WCValSkipListDict<Key,Value> 470, 485 
WCValSkipListSet<Type> 489, 506 
WCValSList<Type> 284, 305 
WCValSortedVector<Type> 569, 589 
WCValVector<Type> 598, 606 
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operator ==, member function 
WCIsvDList<Type> 234, 255 
WCIsvSList<Type> 234, 255 
WCPtrDList<Type> 256, 279 
WCPtrHashDict<Key,Value> 83, 102 
WCPtrHashSet<Type> 106, 127 
WCPtrHashT able<Type> 106, 127 
WCPtrOrderedVector<Type> 525, 547 
WCPtrSkipList<Type> 447, 466 
WCPtrSkipListDict<Key,Value> 427, 444 
WCPtrSkipListSet<Type> 447, 466 
WCPtrSList<Type> 256, 279 
WCPtrSortedVector<Type> 525, 547 
WCPtrVector<Type> 555, 565 
WCValDList<Type> 284, 306 
WCValHashDict<Key,Value> 132, 150 
WCValHashSet<Type> 154, 174 
WCValHashTable<Type> 154, 174 
WCValOrderedVector<Type> 569, 590 
WCValSkipList<Type> 489, 507 
WCValSkipListDict<Key,Value> 470, 486 
WCValSkipListSet<Type> 489, 507 
WCValSList<Type> 284, 306 
WCValSortedVector<Type> 569, 590 
WCValVector<Type> 598, 607 
operator ==, related function 
Complex 18-19,54 
String 862, 880 
operator >, related function 
String 863,881 
operator >=, related function 
String 863,882 
operator », member function 
istream 699,716-721 
operator », related function 
Complex 18, 55 
String 863, 883 
operator [], member function 
String 862,884 

WCPtrHashDict<Key,Value> 83, 99-100 
WCPtrOrderedVector<Type> 525, 545 
WCPtrSkipListDict<Key,Value> 427, 441-442 
WCPtrSortedVector<Type> 525, 545 
WCPtrVector<Type> 555, 563 
WC V alHashDict<Key, Value> 132, 147-148 
WCValOrderedVector<Type> 568, 588 
WCValSkipListDict<Key,Value> 470, 

483-484 

WCValSortedVector<Type> 568, 588 
WCValVector<Type> 598, 605 
operator char const *, member function 
String 862, 886 
operator char, member function 
String 862,885 


operator void *, member function 
ios 656, 678 
opfx, member function 
ostream 755, 767 
osfx, member function 
ostream 755, 768 
ostream 655,691,748,778 
ostream output 13 
ostream::flush 755, 757 
ostream::operator « 755-756, 758-764 
ostream::operator = 755,765-766 
ostream::opfx 755, 767 
ostream::osfx 755, 768 
ostream::ostream 755,769-771 
ostream::put 755, 773 
ostream::seekp 755, 774-775 
ostream::tellp 755, 776 
ostream::write 755, 777 
ostream::-ostream 755, 772 
ostrstream 755, 841 
ostrstream::ostrstream 778-780 
ostrstream: :pcount 778, 782 
ostrstream::str 778, 783 
ostrstream::-ostrstream 778,781 
out, member enumeration 
ios 675 

out_of_memory 367, 370, 402, 405 

exception 70, 84, 86, 97, 99, 101, 104, 107, 
109, 111, 113, 123, 126, 130, 133, 135, 
145, 147, 149, 152, 155, 157, 159, 161, 
170, 173, 177, 260, 264, 266, 276, 278, 
287, 291, 293, 303, 305, 422,428, 430, 
439, 441, 443, 448, 450, 452, 454, 462, 
465, 471, 473, 481, 483, 485, 490, 492, 
494, 496, 503, 506, 520, 527, 530, 532, 
540-541, 546, 548, 554, 558, 563-564, 
566, 571, 574, 576, 583-584, 589, 591, 
597, 601, 605-606, 608 
out_of_memory, member enumeration 
WCExcept 70 

out_waiting, member function 
streambuf 793, 808 
overflow, member function 
filebuf 610, 622 
stdiobuf 784-785 
streambuf 793, 809 
strstreambuf 846, 850 
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pbackfail, member function 
filebuf 610, 623 
streambuf 793, 810 
pbase, member function 
streambuf 792, 811 
pbump, member function 
streambuf 792, 812 
pcount, member function 
ostrstream 778, 782 
peek, member function 
istream 699, 722 
pointer 
lists 229 

polar, related function 
Complex 19, 56 
pop, member function 

WCStack<Type,FType> 512, 519 
pow, related function 
Complex 19, 57 
pptr, member function 
streambuf 792, 813 
precision, member function 
ios 655, 679 
predefined objects 9 
prepend, member function 

WCPtrOrderedVector<Type> 525, 548 
WCPtrSortedVector<Type> 525, 548 
WCValOrderedVector<Type> 568, 591 
WCValSortedVector<Type> 568, 591 
push, member function 

WCStack<Type,FType> 512, 520 
put area 791 
put pointer 813 
put, member function 
ostream 755, 773 
put_at, member function 
String 862,887 
putback, member function 
istream 698, 723 
pword, member function 
ios 656, 680 


R 


rdbuf, member function 


fstreambase 635, 646 
ios 655, 681 
strstreambase 841-842 
rdstate, member function 
ios 655, 682 
read, member function 
istream 698, 724 
real, member function 
Complex 18, 58 
real, related function 
Complex 19, 59 
remove, member function 

WCPtrHashDict<Key,Value> 83, 103 
WCPtrHashSet<Type> 106, 128 
WCPtrHashT able<T ype> 106, 128 
WCPtrOrderedVector<Type> 525, 549 
WCPtrSkipList<Type> 447, 467 
WCPtrSkipListDict<Key,Value> 426, 445 
WCPtrSkipListSet<Type> 447, 467 
WCPtrSortedVector<Type> 525, 549 
W C V alHashDict<Key, V alue> 132, 151 
WCValHashSet<Type> 154, 175 
W C V alHashT able<Type> 154, 175 
WCValOrderedVector<Type> 568, 592 
WCValSkipList<Type> 489, 508 
WCValSkipListDictcKey,Value> 470, 487 
WCValSkipListSet<Type> 489, 508 
WCValSortedVector<Type> 568, 592 
removeAll, member function 

W CPtrHashSet<Type> 106, 129 
WCPtrHashT able<T ype> 106, 129 
WCPtrOrderedVector<Type> 525, 550 
WCPtrSkipList<Type> 447, 468 
WCPtrSkipListSet<Type> 447, 468 
WCPtrSortedVector<Type> 525, 550 
WC V alHashSet<T ype> 154, 176 
WC ValHashT able<Type> 154, 176 
WCValOrderedVector<Type> 568, 593 
WCValSkipList<Type> 489, 509 
WCValSkipListSet<Type> 489, 509 
WCValSortedVector<Type> 568, 593 
removeAt, member function 

WCPtrOrderedVector<Type> 525, 551 
WCPtrSortedVector<Type> 525,551 
WCValOrderedVector<Type> 568, 594 
WCValSortedVector<Type> 568, 594 
removeFirst, member function 

WCPtrOrderedVector<Type> 525, 552 
WCPtrSortedVector<Type> 525, 552 
WCValOrderedVector<Type> 568, 595 
WCValSortedVector<Type> 568, 595 
removeLast, member function 

WCPtrOrderedVector<Type> 525, 553 
WCPtrSortedVector<Type> 525, 553 
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WCValOrderedVector<Type> 568, 596 
WCValSortedVector<Type> 568, 596 
reserve area 791 
reset, member function 

WCIsvConstDListIter<Type> 308, 322-323 
WCIsvConstSListIter<Type> 308, 322-323 
WCIsvDListIter<Type> 324, 341-342 
WCIsvSListIter<Type> 324, 341-342 
WCPtrConstDListIter<Type> 343, 357-358 
WCPtrConstSListIter<Type> 343, 357-358 
WCPtrDListIter<Type> 359, 376-377 
WCPtrHashDictIter<Key, V alue> 180, 188-189 
WCPtrHashSetIter<Type> 202, 213-214 
WCPtrHashTableIter<Type> 202, 213-214 
WCPtrSListIter<Type> 359, 376-377 
WCValConstDListIter<Type> 378, 392-393 
WCValConstSListIter<Type> 378, 392-393 
WCValDListIter<Type> 394, 411 -412 
WC ValHashDictIter<Key, Value> 191, 

199-200 
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resetiosflags, manipulator 733, 740 
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WCValOrderedVector<Type> 568, 597 
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WCValVector<Type> 598, 608 
resize_required 

exception 70, 524, 526, 529, 532, 540-541, 

548, 563, 567, 570, 573, 576, 583-584, 
591, 605 

resize_required, member enumeration 
WCExcept 70 
right, member enumeration 
ios 665 
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sbumpc, member function 
streambuf 793, 814 


scientific, member enumeration 
ios 665 

seekdir, member enumeration 
ios 655, 683 
seekg, member function 
istream 698, 725-726 
seekoff, member function 
filebuf 611,624 
streambuf 793, 815 
strstreambuf 846, 851 
seekp, member function 
ostream 755, 774-775 
seekpos, member function 
streambuf 793, 816 
setb, member function 
streambuf 792, 817 
setbase, manipulator 733, 741 
setbuf, member function 
filebuf 611,625 
fstreambase 635, 647 
streambuf 793, 818 
strstreambuf 846, 852 

setf, member function 
ios 655, 684 

setfill, manipulator 733, 742 

setg, member function 
streambuf 792, 819 

setiosflags, manipulator 733, 743 
setp, member function 
streambuf 792, 820 
setprecision, manipulator 733, 744 
setstate, member function 
ios 655, 685 

setw, manipulator 733, 745 
setwidth, manipulator 733, 746 
sgetc, member function 
streambuf 793, 821 
sgetchar, member function 
streambuf 793, 822 
sgetn, member function 
streambuf 793, 823 
showbase, member enumeration 
ios 665 

showpoint, member enumeration 
ios 665 

showpos, member enumeration 
ios 665 

sin, related function 
Complex 19, 60 
sinh, related function 
Complex 19, 61 
skipws, member enumeration 
ios 665 

snextc, member function 
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streambuf 793, 827 
sputn, member function 
streambuf 793, 828 
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Complex 19, 62 
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ios 665 
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stdiobuf::overflow 784-785 
stdiobuf::stdiobuf 784,786-787 
stdiobuf::sync 784,789 
stdiobuf: underflow 784,790 
stdiobuf: :~stdiobuf 784,788 
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streambuf 793, 829 
str, member function 
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strstream 836-837 
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streambuf 610, 784, 846 
streambuf: allocate 792,794 
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streambuf: :sbumpc 793, 814 
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streambuf: :seekpos 793,816 
streambuf: :setb 792, 817 
streambuf: :setbuf 793, 818 
streambuf: :setg 792, 819 
streambuf: :setp 792, 820 
streambuf: :sgetc 793, 821 


streambuf::sgetchar 793, 822 
streambuf::sgetn 793, 823 
streambuf::snextc 793, 824 
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streambuf::stossc 793, 829 
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streambuf::sync 793, 833 
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operator < 862-863, 876 
operator « 863, 877 
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operator > 863,881 
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operator » 863, 883 
valid 863, 895 

String::alloc_mult_size 862, 864 

String::get_at 862, 865 

String::index 862, 866 

String::length 862, 867 

String::lower 862, 868 

String::match 862, 869 

String "operator ! 862, 870 

String "operator () 862, 872-873 

String "operator += 862,875 

S tring:: operator = 862,879 

String "operator [] 862, 884 

String "operator char 862,885 

String "operator char const * 862, 886 

String::put_at 862, 887 

String::String 862, 888-892 

String::upper 862, 894 

String::valid 862, 896 

String::-String 862, 893 

strstream 691, 841 

strstream::str 836-837 

strstream::strstream 836, 838-839 

strstream::-strstream 836, 840 

strstreambase 729, 778, 836 

strstreambase::rdbuf 841-842 

strstreambase::strstreambase 841, 843-844 

strstreambase::~strstreambase 841, 845 

strstreambuf 791 

strstreambuf::alloc_size_increment 846-847 
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strstreambuf::str 846, 853 
strstreambuf::strstreambuf 846, 854-857 
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strstreambuf::underflow 846, 860 
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sync, member function 
filebuf 611, 626 
istream 699, 727 
stdiobuf 784, 789 
streambuf 793, 833 
strstreambuf 846, 859 
sync_with_stdio, member function 
ios 656, 686 
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tan, related function 
Complex 19, 63 
tanh, related function 
Complex 19, 64 
tellg, member function 
istream 698, 728 
tellp, member function 
ostream 755, 776 
text, member enumeration 
ios 675 

tie, member function 
ios 655, 687 
top, member function 

WCStack<Type,FType> 512,521 
trunc, member enumeration 
ios 675 

truncate, member enumeration 
ios 675 
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unbuffered, member function 
streambuf 792, 834 

undefjtem 185, 190, 196, 201, 210, 223, 316, 
334, 351,369, 386, 404 
exception 75 


undefjtem, member enumeration 
WCIterExcept 75 
undefjter 

exception 75, 184, 186-187, 195, 197-198, 
209, 211-212, 222, 224-225, 315, 
317-321, 332-333, 335-340, 350, 
352-356, 367-368, 370-375, 385, 
387-391,402-403,405-410 
undefjter, member enumeration 
WCIterExcept 75 
underflow, member function 
filebuf 610, 627 
stdiobuf 784, 790 
streambuf 793, 835 
strstreambuf 846, 860 
undex_iter 

exception 179, 307 
unformatted input 11 
unformatted output 13 
unitbuf, member enumeration 
ios 665 

unsetf, member function 
ios 655, 688 
upper, member function 
String 862,894 

uppercase, member enumeration 
ios 665 
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valid, member function 
String 862,896 
valid, related function 
String 863,895 
value 
lists 229 

value, member function 

WCPtrHashDictIter<Key,Value> 180, 190 
WCValHashDict!ter<Key,Value> 191, 201 
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wc_state, member enumeration 
WCExcept 66, 70 
WCDLink 280 

WCDLink::WCDLink 230-231 
WCDLink::-WCDLink 230, 232 
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WCExcept::not_unique 70 
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WCIsvConstDListIter<Type>::append 308 
WCIsvConstDListIter<Type>::container 308, 315 
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319 


WCIsvConstSListIter<Type>::operator — 308, 

320 

WCIsvConstSListIter<Type>::operator -= 308, 

321 

WCIsvConstSListIter<Type>::reset 308, 322-323 
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WCIsvSListIter<Type>::WCIsvSListIter<Type> 
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1 Overview 


CauseWay is a 386 DOS extender package for use with Open Watcom C/C++ programs. It is provided as a 
stub executable for which can be easily linked into DOS extended applications. 


1.1 Introduction 


Within the standard DOS, Windows and OS/2 DOS box environments, CauseWay supports 32-bit memory 
models for applications on PC compatibles with an 80386SX processor or above without the need to use 
overlays or crude stopgap measures such as EMS/XMS swapping. To do this, the DOS extender runs 
applications in protected mode, rather than the real mode normally used in the DOS environments. 
CauseWay supports both 16-bit and 32-bit protected mode applications operating under a DOS 
environment. It makes full use of 386-level chip capabilities including demand paging of code and data, 
variable-sized segments up to 4GB in length, mixing 16- and 32-bit segments as well as support for flat 
(non-segmented) memory addressing models. The CauseWay implementation of these powerful 
capabilities provides all their benefits while being transparent to the application user. 

Applications created using CauseWay are compatible with the VCPI and DPMI standards and run equally 
well on systems with no protected mode drivers or programs. CauseWay applications work with such 
diverse environments as normal DOS, DesqView, Windows 3.0 and above in both standard and enhanced 
modes, as well as DOS windows within OS/2 2.0 and above, Windows 95 and above and Windows NT and 
later. CauseWay allocates memory from DPMI, VCPI, XMS, and INT 15H services, in addition to 
conventional DOS memory. This allows CauseWay applications to allocate memory through the 
CauseWay DOS extender without the need to detect or manipulate the various memory handling schemes. 

A primary objective of CauseWay development was to ensure minimal effort would be needed by 
programmers to adapt their code to work with the CauseWay DOS e tender. As a result, most Open 
Watcom C/C++ and many realmode assembly language programs need no or minor changes to produce a 
fully operational CauseWay protected mode application. 

1.2 Minimum System Requirements 

CauseWay for Open Watcom C/C++ requires a 386SX based computer or better. The required operating 
environment is MS-DOS or PC-DOS 3.3 or higher, Windows 3.0 or higher, OS/2 2.0 and above, Windows 
95 and above, Windows NT or higher or a compatible operating system that provides a DPMI or VCPI 
DOS environment. 

CauseWay is to a large extent compatible with Tenberry Software’s DOS/4GW. Most applications built for 
DOS/4GW will run with CauseWay without any changes. 
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1.3 CauseWay Memory Requirements 

The recommended minimum amount of total free physical memory for CauseWay applications is 500KB 
total. 100-150KB of this memory must be conventional DOS memory, the remainder may be extended 
memory. CauseWay applications can run in less memory, down to the 300KB range, provided sufficient 
virtual (disk-based) memory is available, but application performance will decline significantly. More 
physical memory improves a program’s performance, reducing virtual memory disk access overhead. 

1.4 Operating CauseWay 

When using CauseWay, simply follow the standard edit-compile/assemble-link programming cycle familiar 
to C and assembly language programmers. 

Users compiling with WCL386 need to add the switch -l=CauseWay to the command line. 

Example: 

WCL386 -l=CauseWay myprog.c 

This switch can be automated by adding -l#CauseWay to the WCL386 environment variable, making 
CauseWay the default when compiling via WCL386. 

Open Watcom users linking with WLINK should add the statement system CauseWay to the link 
command. 

Example: 

WLINK system CauseWay file myprog.obj 

When running the DOS-extended application, DOS first loads the CauseWay DOS extender in 
conventional memory. CauseWay establishes the protected mode environment, retrieves the application 
from the executable file — loading it first into extended memory, then conventional memory if extended is 
exhausted, then virtual (disk-based) memory if conventional is exhausted — sets up the application for 
execution, and finally passes control to the application to begin operation. No additional files are required 
to make your application run in 386 protected mode using the CauseWay DOS extender. 

CWSTUB. EXE will execute stand-alone LE-format files in the same way as DOS4GW.EXE does if the full 
file name, including extension, is listed after CWSTUB, e.g. CWSTUB RUNME . EXE . CWSTUB will 
override the extender bound to the application EXE, if any, with the CauseWay DOS extender version in 
CWSTUB.EXE. 


1.5 Debugging Using WD 

To debug CauseWay programs with the Open Watcom debugger after installing the CauseWay files, simply 
use the -tr=cw command line option. 
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Example: 

WD -tr=cw myprog 

This process can be automated by adding -tr#cw to your WD environment variable. Use the set 
WD=tr#cw command. 

By default, CauseWay uses a Ctrl-Alt keypress to interrupt the WD debugger, rather than the Print-Screen 
key. This can be changed to any two, three, or four keypress value by modifying the ASCII file 
CWHELP . CFG at the BreakKeys line. See comments in this file for further detail. Note that a single 
keypress value will not work properly. 

1.6 Operational Considerations When Using CauseWay 

The TEMP , TMP and CAUSEWAY=SWAP environment variables are used by CauseWay to determine 
where to build its virtual memory swap file when an application is not operating under Windows or OS/2 
(Windows and OS/2 provide their own virtual memory management). Since CauseWay has integrated 
virtual memory, disk space is considered part of total memory. If you use the TEMP , TMP or SWAP 
environment variable to point to a small RAM sk or almost full disk, free memory will be affected 
accordingly. If virtual (disk-based) memory is less than physical (installed on machine) memory. Cause 
Way turns off virtual memory. On the other hand, if you have a disk 300MB free, CauseWay will have no 
problem reporting 300MB free memory to your program, provided that virtual memory is not inhibited or 
limited by the CAUSEWAY environment variable memory settings. 

Memory operates differently under Windows and OS/2. With OS/2, the DPMI setting for the session 
determines available memory. With Windows, available memory is the total of physical memory plus the 
swap file size less any memory already in use by Windows or another Windows application. 

When creating a VMM swap file at application startup under DOS, CauseWay builds a list of possible 
paths in order of priority. CauseWay then works through the list until one of the entries provides both a 
valid drive and path specification and sufficient free space to being operation. The first entry to succeed 
becomes the swap file drive with no further processing of the list. If CauseWay reaches the end of the list 
without finding a valid drive, it disables the virtual memory manager. The order of priority is 
CAUSEWAY=SWAP , TEMP , TMP and application execution path. 

If end users reboot the system or turn off power while executing a CauseWay application under DOS, a 
temporary file will be left on the system by CauseWay. This will usually be a zero length file unless the 
application was large enough to exceed physical memory and CauseWay had started using its virtual 
memory manager. The temporary file name is requested using standard DOS functions, meaning the name 
will vary with different versions of DOS. It typically is a mixture of letters and numbers with no extension, 
although .$$$ extension may be presented when operating under a network. Make sure you do not delete 
this temporary file while the CauseWay application is still active, as improper or erratic program operation, 
including lock-ups, may occur. 

Application startup times may increase significantly if the free physical memory is less than the executable 
size. In such cases, not only must the executable be loaded into physical memory, but a virtual memory file 
of the executable file size must also be built. This file holds the portions of the executable that do not fit 
into physical memory and which have not been recently requested. After startup is complete, the program 
will operate normally, paging to and from virtual memory as necessary. 

CauseWay automatically sets aside 32KB of low DOS memory for allocation and use by developer routines 
via the GetMemDOS API function. The 32K memory block is available even if CauseWay needs to use 
virtual memory just to load an application. The set-aside amount can be increased by using the 
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CAUSEWAY environment variable LOWMEM option, although the additional set-aside goal is not 
guaranteed to be reached if too little conventional memory is left for CauseWay’s operating requirements. 


1.7 Environment Variables 

CauseWay can make use of three environment variables at runtime: TEMP , TMP and CAUSEWAY 

1.7.1 TEMP and TMP Environment Variables 

The TEMP and TMP environment variables specify the directory and drive where a swap file is built by 
CauseWay’s virtual memory manager (VMM) when operating under DOS. Windows and OS/2 provide 
their own memory management functions which override CauseWay’s use of the TEMP and TMP 
environment variables. The path indicated by TEMP will be used under DOS if both TEMP and TMP 
environment variables exist. Both settings are superseded by the CAUSEWAY=SWAP environment 
variable setting. 

SET TMP=C:\SWAP 

The example above directs the CauseWay DOS extender to create its swap file, if any, in the C:\SWAP 
directory. 

If no TEMP , TMP and CAUSEWAY=SWAP settings are present or are invalid, the current drive is used 
when creating a swap file. If free drive space is less than physical memory (extended and conventional) 
available at startup, then the DOS extender VMM is disabled, no swap file is created, and virtual memory is 
not available to the application. 

1.7.2 CAUSEWAY Environment Variable 

The CAUSEWAY environment variable controls operation of the DOS extender at application runtime. 
Eleven (11) options are supported, although they are ignored in a Windows or OS/2 DPMI environment. 
Use any combination of the options in the following format: 

SET CAUSEWAY=[ <setting_ 1>; ] [<setting_ 2>; ] [<setting_ n>; ] 

Items in square brackets ([ ]) are optional. Do not actually type the brackets if you use the optional items. 
Items in brackets (< >) should be replaced with actual values, separated by semicolons. Following is a 
description of the valid settings: 

BIG1 

Force CauseWay to use an alternate method to determine available extended memory under 
RAW memory environments (no DPMI host, no HIMEM.SYS loaded), allowing 
CauseWay to see more than 64MB of memory on machines which do not support more 
than 64MB under original INT 15h method. This method uses INT 15h function 0e801h to 
determine available extended memory, falling back to the original function if 0e801h fails. 
Note that old machines may not support this function and there is a slight chance that some 
older machines may not work if this setting is used. 

DPMI 

Force DPMI rather than default VCPI usage whenever possible (recommended for 386Max 
and BlueMax users). The memory manager must support DPMI or else this setting is 
ignored. 
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EXTALL 

Force CauseWay to use all extended memory and sub-allocate memory from the bottom up 
instead of the default top-down approach. This setting is most useful for processor 
intensive environments which have a small hardware cache that does not cover the entire 
physical address range. Use of this setting means that no extended memory will be 
available for other programs while the application is loaded (including shelling to DOS). 

HIMEM:<nnn> 

Set maximum physical (conventional plus extended) memory that can be consumed by 
CauseWay where <nnn> is the decimal number of kilobytes that can be consumed. If 
memory allocation requests exceed this figure, CauseWay will use virtual memory, even if 
additional physical memory is present. If the HIMEM memory value exceeds available 
physical memory, then memory allocations operate normally. For example, HIMEM:2048 
on a 4MB machine would force virtual memory use after 2MB of memory allocations 
(including loading the executable file). The remaining 2MB of memory could be used by 
other applications while the CauseWay application is active. 

LOWMEM:<nnn> 

Set DOS (conventional) memory to restrict it from use by CauseWay. This memory is in 
addition to the default 32KB low DOS memory block reserved by CauseWay for use by 
any applications which need to allocate DOS memory. <nnn> is the decimal number of 
kilobytes to reserve. If there is not enough conventional memory to satisfy the <nnn> 
request value, then CauseWay will leave all conventional memory free that is not required 
by the extender to operate. Note that this option does not guarantee the amount of free 
DOS memory, just how much needs to be free before CauseWay will consume DOS 
memory after exhausting all extended memory. For example, LOWMEM:200 will attempt 
to reserve 200KB of DOS memory, even if CauseWay has exhausted all extended memory 
and is using conventional memory to fill memory allocation requests. 

MAXMEM:<nn> 

Set maximum linear address space provided by CauseWay where <nn> is the decimal 
number of megabytes of linear address space. This setting is similar to HIMEM except that 
it includes any virtual memory. For example, MAXMEM:32 on a 16MB memory system 
restricts VMM disk space usage to 32MB, even if more disk space is present. 

MAXMEM:8 on the same system would restrict the application to 8MB of memory (all 
physical). Note that the setting is in megabytes, rather than kilobytes used in the 
LOWMEM and HIMEM options. 

NAME:<filename> 

Set a name, without a pathspec, to use the virtual memory temporary swap file. To set a 
path for the swap file, use the CAUSEWAY=SWAP , TEMP , or TMP environment 
variable. The filename must be valid, 12 characters or less. Additional characters are 
truncated or invalidate the filename, depending upon how DOS handles it (e.g., multiple 
periods make an invalid file name whereas a five-character extension is truncated to three). 
If the filename specified is invalid, CauseWay shuts off virtual memory. It makes no 
further attempts for a temporary file name. If a pre-existing file name is specified, 
CauseWay overwrites the file. 

In conjunction with the PRE setting, the NAME setting can be a very powerful tool. Not 
only can no clusters be lost due to reset/reboot, but the leftover temporary file can be forced 
to a known name and location. Erase the swap file prior to running the application or leave 
it as a "permanent" swap file for CauseWay. 
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Note: In a multi-user or muti-CauseWay application situation, do not use the NAME 
setting unless it generates a unique file for each user and application. Otherwise, 
applications will be stepping on others’ temporary files. 


NOEX 

Force CauseWay to not patch the INT 21h, function 4bh (EXEC) vector to turn off 
CauseWay’s INT 3lh extensions when the EXEC function is called. CauseWay normally 
turns off support of its INT 3 lh extensions with an EXEC call to be well behaved and avoid 
conflicts with other extenders or programs which may add their own extensions to INT 3lh. 
However, if your CauseWay extended application shells out to DOS and passes the 
shelled-to application a callback address pointing to a routine within the parent CauseWay 
application, the callback will not work properly if the protected mode code uses the 
CauseWay extensions. With the NOEX setting present, CauseWay still supports its INT 
3lh extensions for those users who need to operate with callbacks in this fashion. Be aware 
that when the NOEX setting is present, CauseWay is less "well-behaved" about other 
programs which might add their own INT 3lh extensions. 

NOVM 

Disable all virtual memory use by CauseWay. If physical memory is exhausted, CauseWay 
will fail further memory allocation requests. 


PRE:<nnn> 

Pre-allocates a swap file size, under non-DPMI environments, at start-up, where <nnn> is 
file size in megabytes, not kilobytes (same as MAXMEM). 

There are at least two uses for this feature. First, to pre-allocate a virtual memory file size 
for applications with a total memory allocation (including EXE image) that does not exceed 
the set size. For example: 

SET CAUSEWAY=PRE:4 

pre-allocates a virtual memory file of 4MB. If an enduser resets or powers off the 
computer while the application is running and virtual memory is in use, the enduser’s 
machine will not have lost clusters. There is only a 4MB temporary file to find and erase. 

If virtual memory usage exceeds 4MB, then SCANDISK must be used to recover lost 
clusters above and beyond what was pre-allocated. 

Secondly, PRE can be used to allow your application to stake a claim to disk space before it 
needs it. 

PRE may be used in conjunction with MAXMEM to ensure that virtual memory does not 
exceed the pre-allocation setting. 


SWAP:<path> 

Set CauseWay’s virtual memory manager swap file path. This path takes precedence for 
choosing the location of a swap file over the TEMP and TMP environment variables. 
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2 Using the flat memory model 


Flat model is a non-segmented memory model that allows accessing data and executing code anywhere 
within the 4GB linear address region via a 32-bit offset without the need to use segment registers to point to 
the memory. In many respects, the memory model is identical to the tiny memory model well-known to 
DOS C and assembly language programmers, but supporting a memory region of 4GB rather than 64KB. 

When using flat model, all linear addresses directly map to the physical address specified when an 
application is running in pure DOS environment. For example, writing to memory location 0B8000h will 
address video memory. Reading from memory locations in the OFFFOOh range will access ROM code. 
Under DPMI there is usually no direct relationship between linear and physical addresses, the DPMI host 
will however emulate access to memory below 1MB as appropriate without requiring any special 
considerations on the part of the application writer. 

Generally speaking, flat is an improved version of the older near memory model supported in previous 
versions of CauseWay. Unlike near, flat model supports multiple segments, mixing 16- and 32-bit 
segments, and direct linear memory addresses without translation. Flat model supports all near memory 
model code without translation, including automatic handling of near-specific API functions. 


Using the flat memory model 


11 




Programmer’s Guide 


12 Using the flat memory model 




3 Using DLLs with Open Watcom C/C++ 


It is recommended that you understand and familiarize yourself with the basic operation of DLLs (Dynamic 
Link Libraries) under Windows or OS/2 before using them with CauseWay under DOS. No attempt is 
made here to explain the fundamentals of DLL architecture and operation. You should also study the 
provided DLL example code. 

DLL code should be compiled with the -s option to disable stack checking and the -bd option to generate 
DLL-suitable code. Specify a system type of CWDLLR for register-based parameter passing or CWDLLS for 
stack-based parameter passing. 

A DLL file is a standard EXE file with the following requirement: The program start address should be an 
initialization and termination function, rather than a main program entry point. The entry address will be 
called twice: Once after loading to allow the DLL to perform initialization and once just prior to the DLL 
being unloaded from memory to allow it to clean up for termination. Entry conditions are: register EAX=0 
for initialization and register EAX=1 for termination. An initialization code return value of EAX=0 
indicates no errors. A code of any other value indicates an error has occurred and loading should be 
terminated. If an error condition is returned, it is up to the DLL to display an error message, CauseWay 
will simply report a load error. The entry address is a FAR call, so the initialization code should use a 
RETF to return control to the calling program. 

A minimal DLL startup system is provided in the DLLSTRTR. OBJ (register-based) and the 
DLLSTRTS . OBJ (stack-based) files. 

CauseWay loads DLLs when the program being loaded has references to external modules in the DLL. 
CauseWay searches the execution path for any DLL or EXE file (in that order) which has the proper 
internal module name. The module name is not used when searching. For example, a file named 
USEME . DLL contains a module named Spelling_Checker. The name of the module (Spelling_Checker) is 
set by the NAME option in your link file. If no NAME is specified, then the module’s name will default to 
its file name without an extension. In this example, the module name would become USEME if no NAME 
is specified. 

Following is an overview of the standard link file commands used to create DLLs. You may also refer to 
the Open Watcom Linker documentation for a description of these commands. 


EXPORT function _name 


where description: 

function jiame allows you to make a symbol (function name) available to other modules. It must be 
declared as a public symbol so that the linker can export it. 
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IMPORT [local_name] module jiame.function jiame 
IMPORT [localjiame] module jiame.ordinal 


where description: 

local jiame is an optional parameter. It is the symbol which the importing program references the 

function by, i.e. the symbol declared as external. If no local name is specified, then 
function jiame is used. 

module jiame is the name of the module that contains the function. It is not the file name. IMPORT 

module names are resolved by searching DLL and EXE files for the correct module name. 

function jiame is the symbol by which the function is known in the EXPORTing module, i.e. the symbol 
that is declared as public. 

ordinaljiumber functions can also be imported by number. This is the entry number in decimal, starting at 
1, in the EXPORTing module’s export table to link to. local jiame must be specified when 
using ordinals, otherwise there is no symbolic reference to internally resolve. 

In the DLL calling code, local jiame and functionjiame need to be declared as external. 


NAME module jiame 


where description: 

module jiame is a symbol by which the module should be identified when resolving IMPORT records in a 
calling program. 

IMPORTed module names can contain a partial path. For example, DLL\spelling_checker 
would instruct the loader to look in <execution path>\DLL for a module with a name of 
spelling_checker. 

Notes: 

You must take the responsibility to make sure that the IMPORTed function or module 
calling conventions match the calling code. For example, the loader will load a 16-bit 
module to resolve an IMPORT in a 32-bit program without complaint. In this case, if the 
IMPORTing program does a 16-bit far call, then everything will work correctly, but a 
32-bit call will fail unless the 16-bit DLL module ends with a 32-bit RET instruction. 

Importing by function name may slow program performance if the symbols are frequently 
referenced. In such cases, consider using the ordinal command to speed up the access times 
because module name references are automatically converted to ordinals in an internal list 
which will only be processed once at load time. 
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4 Performance Considerations 


There are a few ways to increase the operational efficiency of your CauseWay applications. 

4.1 Memory Size 

Almost without exception, the best way to increase runtime performance of all CauseWay applications is to 
ensure that physical memory is large enough to meet all of the program’s needs. Performance suffers 
considerably when CauseWay creates a temporary file for virtual memory, swapping 4KB blocks of the 
program’s code and data to and from disk. Naturally this may not be possible in all cases, but it is a worthy 
goal. Generally the more physical memory, even when virtual memory is being used, the better an 
application’s performance. 

When using a disk cache program, be sure not to use too much extended memory. Although a disk cache 
program is beneficial, allocating it too much memory can deprive CauseWay of required extended memory 
and can degrade application performance. However completely disabling disk cache will usually 
noticeably decrease performance as well. The optimal cache size depends on the particular application and 
computer system (amount of physical memory, disk I/O speed etc.) and there are no generally applicable 
"best" settings. 

If your program uses virtual memory, CauseWay’s VMM creates a temporary swap file. If you have more 
than one disk drive, then you may wish to direct creation of the swap file to the faster disk drive on your 
system using the CAUSEWAY=SWAP , TEMP or TMP environment variables. Do not create a RAM 
disk if this will lower your physical memory because this is less efficient than allowing CauseWay to use 
physical memory itself. 

Remember that virtual memory is part of total memory when using CauseWay. If your default drive, or the 
drive pointed to by the TEMP or TMP environment variables has little free space, this will be reflected in 
total memory available to the CauseWay application. If disk free space is less than physical memory, then 
CauseWay shuts off all use of virtual memory. Windows and OS/2 handle virtual memory internally and 
supply it through the swap file and DPMI settings for the application. 

4.2 Open Watcom C/C++ kbhitf) replacement 

Two optimized replacement versions of the Open Watcom C++ runtime library kbhit() function are 
provided. The files are KBHITR.OBI and KB HITS.OBI for, respectively, register-based and stack-based 
calling conventions. Simply link in the kbhit() replacement file appropriate for your compile options. 

These replacement routines bypass the normal INT checking of the keyboard and directly inspect the 
keyboard buffer to see if a keypress is pending. These routines significantly reduce the overhead in tight 
processing loops, which perform many kbhit()’s per second, by avoiding the interrupt call associated with 
checking for keystrokes. 

Be aware that linking in the kbhitr or kbhits module means that the INT 28h idle call will not be made on 
kbhit() as normally occurs with the standard runtime library kbhit(). This may impact background 
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processing in applications which depend on INT 28h idle calls, such as the DOS PRINT utility which 
performs printing in the background, as well as operation under multitatsking environments. 


4.3 DOS API Buffer Size 


If your CauseWay application reads and writes files using large amounts of data on one read or write pass, 
you may wish to consider increasing the size of the internal DOS memory transfer buffer used by 
CauseWay. Refer to the SetDOSTrans and GetDOSTrans functions in the CauseWay API chapter for more 
information. 

Note that the internal 8KB buffer is optimized for file transfers. Average file transfers of greater than 8KB 
will not necessarily improve performance with an increase in the buffer size. Generally speaking, the 
average file transfer must be 32KB or larger to gain any efficiency with an increased buffer size. Also, if 
you are using virtual memory, increasing the buffer size may actually slow down performance due to the 
decreased available physical memory. Test your application with both the default buffer and the desired 
new buffer size before permanently increasing the buffer size beyond the default. 

4.4 API Memory Allocation 

Inveterate tweakers may try out the SetMCBMax and GetMCBSize functions in the CauseWay API. These 
functions allow fine-tuning of the threshold used by CauseWay to allocate memory via a memory pool 
using memory control blocks (MCBs) rather than via normal DPMI functions. Since DPMI allocates 
memory in multiples of 4KB, setting the MCB threshold too low may result in a good deal of wasted 
memory and subsequent performance degradation. 
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5 Rules For Protected Mode Operation 


The following information covers additional restrictions for protected mode compatible code that are not 
present when writing real mode compatible code. 

Using protected mode rather than real mode requires following a few new programming rules to prevent 
processor faults from being generated, terminating the CauseWay application. These processor faults occur 
when an application breaks a protected mode programming rule. 

Use the following rules for programming in protected mode: 

1. A selector value (referred to as a segment value in real mode) loaded into a segment register 
references an area of memory that may occur anywhere within the machine’s physical address 
space. The operating system can dynamically move this area of memory. Therefore, when 
dealing with selector values: 

• Never use segment registers as general purpose registers that can be loaded with arbitrary 
values. Every time a segment register is loaded with a value the processor checks the 
validity of the selector value and generates a fault if it is invalid. 

• Never perform segment arithmetic on a selector value. Segment arithmetic is usually 
performed in real mode code to either normalize a pointer, access a new paragraph of 
memory without changing an offset, or to access a single area of memory that is greater 
than 64KB in size. Since a selector value is an index into a table which contains the actual 
memory addresses, addition or subtraction of different selector values is meaningless and 
gives no useful results. (There exist special cases where contiguous selector values can be 
added or subtracted from for useful effect, but detailing these cases exceed the scope of 
this manual.) 

• Do not access data at an offset greater than the size of the associated selector. Attempts to 
do so result in a fault. This is one of the greatest strengths of protected mode because most 
obscure bugs in real mode code occur when a bad pointer value accesses the wrong area of 
memory, or when a buffer overflows and memory beyond the buffer is overwritten. 

• Do not attempt to write to or read from the NULL (zero value) segment. Attempts to do 
so results in a fault. In addition to valid selector values, segment registers can be safely 
loaded with a value of 0 but this selector value cannot be used to access memory or 
execute code. 

2. Do not execute code in a data segment and do not write to data in the code segment. Use the 
CauseWay AliasSel function to map a data selector to the same physical memory area shared by 
a code selector when necessary. Even in this case, however, never write to memory using a CS: 
code segment override because it always causes a processor fault. 

3. CauseWay handles most of the standard DOS interrupts transparently. When passing pointers to 
buffers for software interrupt calls not handled by CauseWay, create the buffers in low 
(conventional) DOS memory using the GetMemDOS function of the CauseWay API. In 
addition, convert the pointers from protected mode selector:offset pairs to real mode 
segment:offset pairs prior to the interrupt, and back upon your return from the interrupt. 
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6 CW.ERR File Information Format 


The following information describes the format of the CW.ERR file that CauseWay creates if an exception 
occurs in a CauseWay application. This information can be very useful in tracking down exactly where and 
why an exception occurred. 


6.1 Quick Reference Guide 

If you do not know how to interpret assembly language or CPU instructions, and you want better detail on 
the location of an exception, you can frequently identify which routine caused the exception by 
cross-referencing the MAP file with the CW.ERR file. Following is a short guide to determine the 
offending routine. 

Look at the value after the dash (-) listed for the CS segment register at the beginning of the ninth line in 
CW.ERR. This should be an eight digit number starting with several zeros. Now look at the MAP file of 
your application. Following the program, creation date and time lines in the MAP file is a listing of 
program segments showing their start, stop, length, name, class and count. Find the segment which has a 
start address equal to the eight digit number listed above. This is the entry for the program segment where 
the exception occurred. 

Locate the public symbols listed by address in the MAP file. Each symbol in the program is listed in 
ascending address order. The address is composed of two values separated by a colon (:). Find the address 
group which begins with the eight digit number given above for CS segment register without the last digit. 
For example, if the CS eight digit number was 000205E0, look for an address beginning with 0000205E. If 
you cannot find any addresses beginning with the number, either no routines in the segment were declared 
public or else you have a version of the MAP file that was created at a different time than the application 
EXE file which generated the CW.ERR file. 

If there is only one address beginning with the number, you have located the offending routine. If there is 
more than one address, examine the EIP value in CW.ERR. The EIP value is located in the middle of the 
seventh line immediately following the "EIP=" text. This value is the offset in the segment where the 
exception occurred. Find the symbol in the address group which has an address value following the that 
is closest to the EIP but does not exceed the EIP value. This name of the symbol is the name of the routine 
which generated the exception. To continue our example, if you have the following four symbols of 
address 0000205E in the first half of the address line in the map file : 

0000205E:000008DC _ DBFGOHOT 

0000205E:00000944 _ DBFGOCOLD 

0000205E:00000986 _ DBFGOTOID 

0000205E:0000 0AEE _ DBFGOTOP 

and the EIP value is 00000953, the closest routine name that does not exceed the EIP value in the second 

half of the address line is_ DBFGOCOLD . Therefore, the exception occurred in the_ DBFGOCOLD 

routine. 
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This method of locating the exception is not foolproof since it requires that the routine creating the 
exception in the program segment be declared public, but it should work for the majority of cases. 

6.2 Sequence 

The first line in CW.ERR is the CauseWay copyright message including the version of CauseWay used in 
the program. The version number may prove useful in tracking down problems that have been addressed in 
later versions of CauseWay. 

The version is followed by the exception number and error code. These numbers, as well as all others in 
the CW.ERR file, are in hexadecimal. The values listed are those reported by the processor when the 
exception occurred. Detailed information about the significance of the values can be obtained in most 386 
and above reference books. Typically the exception value will be ODH, a General Protection Fault; OCH, a 
stack fault usually due to stack overflow or underflow; or OEH, a page fault due to improper memory 
reference. The error code is generally of little use for debugging purposes. 

Next comes the general register values which indicate the state of the program when the exception 
occurred. The significance of register values is entirely dependent on the program being run at the time. 
CS:EIP register values can help track down the problem area by pinpointing exactly where in the code the 
exception occurred. Other register values may help determine why the exception occurred. In particular, 
look for use of registers as memory indices with values beyond the limit of the associated selector. 

Next, the segment register values are displayed as a real selector value followed by the program relative 
value in bytes. If the second value is non-numeric (xxxxxxxx) then the segment register didn’t contain a 
selector value allocated to the program at load time, although the value may be valid if it was dynamically 
allocated by the operating program. If there is a second value, it also appears in the program’s .MAP file as 
the segment start address. This shows which segment a segment register is pointing to at the time of the 
exception. The CS (Code Segment) register points to the segment containing the code which is executing. 
The EIP register value indicates the offset within the CS segment where the exception occurred. With these 
two values, you can not only determine the segment, but the routine within the segment closest to where the 
exception occurred. 

Segment register values are also useful in determining why an exception occurred. One common error is 
using an invalid selector value in DS, ES, FS, or GS. A segment register value of zero does not 
automatically indicate problem, but will cause a GPF if used to read or write to memory. In particular, be 
highly suspicious of DS and ES segment register values of 0000-xxxxxxxx since they are almost constantly 
used to to access memory. A zero value in DS or ES usually indicates a bad (NULL) memory pointer 
passed to a routine. 

Next, the processor control register values are listed. These registers are unlikely to be of much use for 
debugging and will only be filled in when not running under a true DPMI host. For an exception OEh (page 
fault), CR2 is the linear address that was accessed for which no memory was mapped in. This may help 
track down the problem area. 

Info Flags comes next. This value is returned by CauseWay’s Info API function. Check it against the 
documentation for Info in the CauseWay API chapter to determine some aspects of the environment in 
which the program was running when the exception occurred, e.g. whether a DPMI host was being used. 

Program Linear Load Address follows Info Flags. This value is th executable’s load address in linear 
memory. It corresponds to one of the linear memory block entries described later. 
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In flat models, the EIP value minus the program linear load address is the address offset of the faulting 
location relative to the start of the program. 

Following Program Linear Load Address is a display of the next 128 byte values at the CS:EIP location 
when the exception occurred. These are the hexadecimal byte values of the CPU instructions at the time of 
the exception. 386 reference books or some debuggers can be used to reconstruct the instruction operation 
codes that correspond to these hexadecimal byte values. 

The SS:ESP displays follows CS:EIP. This display shows the last 128 bytes values stored on the CPU 
stack. 

SS:EBP is next. It shows 128 byte values of the current stack frame negatively and positively offset from 
the current EBP value. C and other high level language routines use the EBP register to reference 
parameters passed on the stack and this display can show which parameters were passed. 

The resource tracking details come next. Selectors are listed with the following headings: 

sel base limit type D mem count 

where description: 

sel Selector value. 

base Linear base address of selector. 

limit Limit of selector. 

type CODE or DATA. 

D 16 or 32 to signify segment D bit. 

mem Y or N to indicate if the selector has a memory block associated with it. 

count segment count in MAP file, xxxx if dynamically allocated. 

The selector list is finished off with a display of the total number of selectors allocated to the program. For 
example: 

Total selectors: 0107 

Linear memory blocks are listed following the selector list, and contain the following headings: 
handle base length 

where description: 

handle Linear memory [de]allocation uses handles to control the blocks. This field is the block's 

handle. 

base Linear base address of the memory block. 

length Length of the block in bytes. 
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The linear memory list ends with a display of the total linear memory allocated to the program, the real 
(rounded to 4KB pages) memory allocated in parentheses, and finally the total number of memory blocks. 
For example: 

Total Linear memory: 000FEAC9 (001AA000) in 00000103 blocks 

Entries in the selector list that have Y under "mem" should have a corresponding entry in the linear memory 
list. 

Linear memory locks are listed after the linear memory block list and contain the following headings: 


base 

length 

where 

description: 

base 

Linear base of the locked region. 

limit 

Length of the locked region. 


Note: These values are passed by the program but the actual values have the base rounded down a page 
and the length rounded up a page to match 4KB boundary restrictions on locking. The values are reported 
in CW.ERR without using a rounded format to make it easier to cross reference this list to the other lists in 
CW.ERR. 

Next, protected mode interrupt vectors are listed with the following headings: 

No sel offset 


where 

description: 

No 

Vector number. 

sel 

Selector value for handler. 

offset 

Offset value for handler. 


This information allows a cross-reference with the other lists to ensure CauseWay application installed 
handlers have been properly made. 

Next, protected mode exception vectors are listed using the same format as protected mode interrupts. 

After the protected mode exception vector list, real mode interrupt vectors are listed. They are shown in the 
same format as protected mode interrupts although the selector values are real mode segment values. 

Only those interrupt and exception vectors altered by the program will be listed. 

Lastly, Callbacks are listed in the CW.ERR file. They list all active Callbacks for the active application at 
the time of its termination. 
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7 CauseWay Services 


The following information describes the services available through CauseWay for low-level protected 
mode compatible functions and interrupt servicing. 

The CauseWay services support both 16- and 32-bit selectors. Use of 32-bit selectors allows developers to 
directly access many megabytes of memory in a CauseWay program using only one selector value. In 
addition to the normal segment registers used in real mode programs, the additional segment registers FS 
and GS are always available for use by developers to access memory. Refer to a 386, 486, Pentium or 
compatible CPU reference book or manual for more information on 386+ level registers and instructions. 

7.1 Internal Operation 

A valid protected mode selector:offset is placed in the PSP at offset 34h for the file handle list pointer. 

Note that the default value in the program’s PSP will point to the real mode PSP, not the protected mode 
PSP, even if the handle count is less than or equal to twenty. Code that makes use of the handle list should 
use the address at PSP+34h rather than assuming the list’s position within the PSP. Also, when an 
application is operating in non-DPMI conditions the handle table will have an entry for CauseWay’s VMM 
swap file. 

The GetMem and GetMem32 calls with CX:DX and ECX set to -1 will report the largest free memory 
block, rather than total free memory. This value may be substantially lower than total free memory due to 
fragmentation of the linear memory blocks. Set CX to -1 (OFFFFH) and DX to -2 (OFFFEH) or ECX to -2 
(OFFFFFFFEH) for GetMem and GetMem32, respectively, for the total free memory value. 


7.2 Functions 


The CauseWay functions are based on the DPMI specification and offer additional enhancements. This 
means that several of the DPMI 1.0 functions are available to the CauseWay programmer in all systems 
providing access to lower level functions should you need them. All DPMI 0.9 functions are always 
available. 


7.3 CauseWay API 

CauseWay provides an API for C and assembly language programmers as an extension of the DPMI API 
via INT 3lh. Including the file CW.INC allows easy access to this API through appropriately named 
functions. You may also call the CauseWay API directly with appropriate register setup. 

CauseWay also provides all of the DPMI 0.9 API services on systems without a true DPMI server (thus 
CauseWay itself is the DPMI host in such situations). 

Some of the API services require pointers to a real mode register list. The format of this list follows: 
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dword 

EDI 

dword 

ESI 

dword 

EBP 

dword 

Reserved 

dword 

EBX 

dword 

EDX 

dword 

ECX 

dword 

EAX 

word 

Flags 

word 

ES 

word 

DS 

word 

FS 

word 

GS 

word 

IP 

word 

CS 

word 

SP 

word 

SS 


The values are passed to the target routine without any interpretation of their contents. There is no need to 
set the high words of the extended register entries unless the target routine requires them. 

7.4 Stack Frames 

Stack frames for 16-bit interrupts are the same as for real mode. 

The stack frame for 16-bit exceptions follows: 
word SS 

word SP - Original stack address 

word Flags 
word CS 

word IP - Original Flags:CS:IP values 

word Err Code - Processor supplied exception error code 

word CS 

word IP - Return address, returns to 

interrupt/exception dispatch code 

7.5 Default API 

The default CauseWay API follows. Functions that include the text near are intended only for backwards 
compatibility with CauseWay’s near memory model. This model is now obsolete. The assembly language 
include file *CW.INC* also contains this list. 

7.5.1 API functions (numerical index) 

FFOO Info Get system selectors/flags 

FF01 IntXX Simulate real mode interrupt 

FF02 FarCallReal Simulate real mode far call 
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FF03 GetSel 
FF04 RelSel 
FF05 CodeSel 
FF06 AliasSel 
FF07 GetSelDet 
FF08 GetSelDet32 
FF09 SetSelDet 
FFOA SetSelDet32 
FFOB GetMem 
FFOC GetMem32 
FFOD ResMem 
FFOE ResMem32 
FFOF RelMem 
FF10 GetMemLinear 
FF11 GetMemLinear32 
FF12 ResMemLinear 
FF13 ResMemLinear32 
FF14 RelMemLinear 
FF15 RelMemLinear32 
FF16 GetMemNear 
FF1 7 ResMemNear 
FF18 RelMemNear 
FF19 Linear2Near 
FF1A Near2Littear 
FF1B LockMem 
FF 1C LockMem32 
FF1D UnLockMem 


Allocate a new selector 

Release a selector 

Make a selector execute/read type 

Create a read/write data selector from source selector 

Get selector linear base and limit 

Get selector linear base and limit 

Set selector linear base and limit 

Set selector linear base and limit 

Allocate a block of memory 

Allocate a block of memory 

Resize a previously allocated block of memory 

Resize a previously allocated block of memory 

Release memory allocated by either GetMem or GetMem32 

Allocate a block of memory without a selector 

Allocate a block of memory without a selector 

Resize a previously allocated block of memory without a selector 

Resize a previously allocated block of memory without a selector 

Release previously allocated block of memory (linear address) 

Release previously allocated block of memory (linear address) 

Deprecated - Allocate an application relative block of memory 

Deprecated - Resize a previously allocated application relative block of memory 

Deprecated - Release previously allocated application relative block of memory 

Deprecated - Convert linear address to application relative address 

Deprecated - Convert application relative address to linear address 

Lock a region of memory 

Lock a region of memory 

Unlock a region of memory 
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FF1E UnLockMem32 
FFIF LockMemNear 
FF20 UnLockMemNear 
FF21 GetMemDOS 
FF22 ResMemDOS 
FF23 RelMemDOS 
FF24 Exec 
FF25 GetDOSTrans 
FF26 SetDOSTrans 
FF27 GetMCBSize 
FF28 SetMCBSize 
FF29 GetSels 
FF2A cwLoad 
FF2B cwclnfo 
FF2C GetMemSO 
FF2D ResMemSO 
FF2E RelMemSO 
FF2F UserDump 
FF30 SetDump 
FF31 UserErrTerm 
FF32 CWErrName 
FFF9 ID 
FFFA GetPatch 
FFFB cwcLoad 
FFFC LinearCheck 
FFFD ExecDebug 
FFFE CleanUp 


Unlock a region of memory 

Deprecated - Lock a region of memory using application relative address 
Deprecated - Unlock a region of memory using application relative address 
Allocate a region of DOS (conventional) memory 

Resize a block of DOS (conventional) memory allocated with GetMemDOS 
Release a block of DOS (conventional) memory allocated by GetMemDOS 
Run another CauseWay program directly 

Get current address and size of the buffer used for DOS memory transfers 

Set new address and size of the buffer used for DOS memory transfers 

Get current memory control block (MCB) memory allocation block size 

Set new MCB memory allocation block size 

Allocate multiple selectors 

Load another CauseWay program as an overlay 

Validate and get expanded length of a CWC'ed file 

Allocate a block of memory with selector:offset 

Resize a block of memory allocated via GetMemSO 

Release a block of memory allocated via GetMemSO 

Setup user-defined error buffer dump in CW.ERR 

Disable/enable error display and CW.ERR creation 

Call user error termination routine 

Change error file name, with optional drive/pathspec 

Get CauseWay identifier, PageDIRLinear and PagelstLinear info 

Get patch table address 

Load/Expand a CWC'ed data file into memory 
Check linear address of memory 
Load CauseWay program for debug 
Close all open file handles 


28 


Default API 




CauseWay Services 


7.5.2 API functions (alphabetical order) 


AliasSel 

Create a read/write data selector from source selector. 

Inputs: 

AX= 0ff06h 

BX= Source selector 

Outputs: 

Carry set on error, else 

AX= New data selector 

Errors: 

If an invalid selector is passed in BX, this function returns with carry set. 

Notes: 

This function always creates a read/write data selector regardless of the source selector 
type. It can be used to provide write access to variables in a code segment. 

CleanUp Close all open file handles. 

Inputs: 

AX= Offfeh 

Outputs: 

None. 

Errors: 

None. 

CodeSel 

Make a selector execute/read type. 

Inputs: 

AX= 0ff05h 

BX= Selector 

CL= Default operation size. (0=16-bit,l=32-bit) 

Outputs: 

Carry set on error. 

Errors: 

If an invalid selector is passed in BX, this function returns with carry set. 

Notes: 

This functions allows a selector to be converted to a type suitable for execution. 

cwclnfo 

Validate and get expanded length of a CWC'd file. 

Inputs: 

AX= 0ff2bh 

BX= File handle. 

Outputs: 

Carry set if not a CWC’d file, else 

ECX= Expanded data size. 

Errors: 

None. 
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Notes: The file pointer is not altered by this function. 


cwcLoad Load/Expand a CWC’ed data file into memory. 

Inputs: 

AX= Offfbh 

BX= Source file handle. ES:ED1= Destination memory. 

Outputs: 

Carry set on error and EAX is error code, else 

ECX= Expanded data length. 

Errors: 

1 - Error during file access. 

2 - Bad data. 

3 - Not a CWC’ed file. 

Notes: 

The source file's file pointer doesn't have to be at zero. A single file might be several 
CWC’ed files lumped together, as long as the file pointer is moved to the right place before 
calling this function. 

If error codes 1 or 2 are reported then the file pointer will be wherever it was last moved to 
by this function. For error code 3 the file pointer will be back at its original position on 
entry to this function. If no error occurs then the file pointer will be moved to whatever 
comes after the compressed data. 

CWErrName Change error file name, with optional drive/pathspec. 

Inputs: 

AX = 0ff32h 

CX:[E]DX = selector:offset of ASCIIZ error file name 

Outputs: 

None 

Errors: 

None 

Notes: 

If the error file name is invalid when a fault occurs, CauseWay defaults to using the 
standard CW.ERR file name in the current directory. The file name including any path and 
drive must not exceed 80 characters or it will be truncated. CX:EDX are not checked for 
validity and passing invalid values may cause a fault within the DOS extender. The 

ASCIIZ name pointed to by CX:EDX is copied to an internal DOS extender location and 
may be safely modified after calling the CWErrName function. 

cwLoad 

Load another CauseWay program as an overlay. 


Inputs: AX= 0ff2ah 

DS:EDX= File name. 

Outputs: Carry set on error and AX = error code, else 

CX:EDX= Entry CS:EIP 
BX:EAX= Entry SS:ESP 
SI= PSP. 
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Errors: 1 - DOS file access error. 

2 - Not recognisable file format. 

3 - Not enough memory. 

Notes: Program is loaded into memory, but not executed. 

The PSP returned in SI can be passed to RelMem to release the loaded programs memory 
and selectors. Only the memory and selectors allocated during loading will be released, it 
is the programs responsability to release any additional memory etc allocated while the 
program is running. Alternatively, if you pass the PSP value to INT 21h, AH=50h before 
makeing additional memory requests and then reset to the origional PSP the memory 
allocated will be released when the PSP is released. 


Exec Run another CauseWay program directly. 

Inputs: AX= 0ff24h 

DS:[E]DX= File name. 

ES:[E]SI= Command line. First byte is length, then real data. 

CX= Environment selector, 0 to use existing copy. 

Outputs: Carry set on error and AX = error code, else 

AL=ErrorLevel. 

Errors: 1 - DOS file access error. 

2 - Not recognisable file format. 

3 - Not enough memory. 

Notes: Only the first byte of the command line (length) has any significance to CauseWay so you 

are not restricted to ASCII values. It is still stored in the PSP at 80h though so the length is 
still limited to 127 bytes. 

ExecDebug Load CauseWay program for debug. 

Inputs: AX= Offfdh 

DS:EDX= File name. 

ES:ESI= Command line. First byte is length, then real data. 

CX= Environment selector, 0 to use existing copy. 

Outputs: Carry set on error and AX = error code, else 

CX:EDX= Entry CS:EIP 
BX:EAX= Entry SS:ESP 
SI= PSP. 

DI= Auto DS. 

EBP= Segment definition memory. 

Errors: 1 - DOS file access error. 

2 - Not recognisable file format. 

3 - Not enough memory. 
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FarCallReal Simulate real mode far call. 

Inputs: 

AX= 0ff02h 

ES:[E]DI= Real mode register list. 

Outputs: 

Register list updated. 

Errors: 

None. 

Notes: 

This function works much the same as IntXX but provides a 16 bit FAR stack frame and 
the CS:IP values are used to pass control to the real mode code. 

GetCallBack Allocate real mode callback address. 

Inputs: 

AX= 0303h 

DS:[E]SI= Call address. 

ES:[E]DI= Real mode register structure. 

Outputs: 

Carry set on error, else 

CX:DX= Real mode address to trigger mode switch. 

Errors: 

Callbacks are a limited resource. Normally only 16 are available per virtual machine. Use 
them carefully and release them as soon as they are no longer required. 

Callback: 

Interrupts disabled. 

DS:[E]SI = Selector:Offset of real mode SS:SP. 

ES:[E]DI = Selector:Offset of real mode call structure. 

SS:[E]SP = Locked protected mode stack. 

All other registers undefined. 

To return from callback procedure, execute an IRET to return. 

ES:[E]DI = Selector:Offset of real mode call structure to restore. 

Notes: 

Real mode callbacks provide a means of switching from real mode to protected mode. This 
function returns a unique real mode address that when given control in real mode, switches 
to protected mode and passes control to the protected mode routine supplied at entry to this 
function. On entry to the protected mode code the real mode register structure contains all 
the real mode register values. 

GetDOSTrans Get current address and size of the buffer used for DOS memory transfers. 


Inputs: AX = Off25h 

Outputs: BX = Real mode segment of buffer. 

DX = Protected mode selector for buffer. 

ECX = Buffer size 

Errors: None 
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Notes: This buffer is used by the INT API translation services, e.g., INT 21h, AH=40h (write to 

file). The default buffer is 8K and uses memory that would otherwise be wasted. This 
default is sufficient for most file I/O but if you are writing a program that reads/writes large 
amounts of data you should consider allocating your own larger buffer and pass the buffer’s 
address to CauseWay to speed file I/O. 


GetEVecI 

: Get Protected mode exception handler address. 

Inputs: 

AX= 0202h 

BL= Exception vector number. 

Outputs: 

Carry set on error, else 

CX:[E]DX= selector:offset of handler. 

Errors: 

The number in BL must be in the range 0-lFh. Anything outside this range returns carry 
set. 

GetMCBSize Get current memory control block (MCB) memory allocation block size. 

Inputs: 

AX = 0ff27h 

Outputs: 

ECX = Current threshold 

Errors: 

None 

Notes: 

See SetMCBMax 

GetMem 

Allocate a block of memory. 


Inputs: AX= OffObh 

CX:DX= Size of block required in bytes, (use -1:-1 to get maximum memory size) 

Outputs: Carry set on error, else 

BX= Selector to access the block with or if CX:DX was -1, 

CX:DX= size of largest block available. 

Errors: The amount of memory available is limited by physical memory present and free disk space 

of the drive being used by the VMM. If CauseWay is unable to find a large enough block 
this function returns carry set. 

Notes: This function allocates a block of extended (application) memory and allocates a selector 

with a suitable base and limit. 
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GetMem32 Allocate a block of memory. 


Inputs: AX= OffOch 

ECX= Size of block required in bytes. (-1 to get maximum memory size) 

Outputs: Carry set on error, else 

BX= Selector to access the block with or if ECX was -1, 

ECX= size of largest block available. 

Errors: See GetMem 

Notes: This function allocates a block of extended (application) memory and allocates a selector 

with a suitable base and limit. 


GetMemDOS Allocate a region of DOS (conventional) memory. 


Inputs: AX=0ff21h 

BX= Number of paragraphs (16 byte blocks) required. 

Outputs: Carry set on error and BX= largest block size, 

AX=DOS error, else 

AX= Initial real mode segment of allocated block 
DX= Initial selector for allocated block 

Errors: If there are not enough selectors or memory available then this function returns carry set. 

Notes: If the size of the block requested is greater than 64KB bytes (BX >1000h) then contiguous 

descriptors are allocated. If more than one descriptor is allowed under 32-bit applications, 
the limit of the first descriptor is set to the size of the entire block. All subsequent 
descriptors have a limit of 64KB except for the final descriptor which has a limit of block 
size modulo 64KB. For 16-bit applications, always set the limit of the first descriptor to 
64KB. 


GetMemLinear Allocate a block of memory without a selector. 


Inputs: AX= Off 1 Oh 

CX:DX= Size of block required in bytes. 

Outputs: Carry set on error, else 

SI:DI= Linear address of block allocated. 

Errors: If not enough memory is available to satisfy the request then this function returns carry set. 

Notes: Addresses returned by this function may be above 16MB. 
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GetMemLinear32 Allocate a block of memory without a selector. 

Inputs: 

AX= Offl lh 

ECX= Size of block required in bytes. 

Outputs: 

Carry set on error, else 

ESI= Linear address of block allocated. 

Errors: 

See GetMemLinear 

Notes: 

Addresses returned by this function may be above 16MB. 

GetMemSO Allocate a block of memory with selector:offset. 

Inputs: 

AX = 0ff2ch 

CX:DX = Size of block required in bytes 

Outputs: 

Carry set on error, else 

S1:DI = selector:offset of allocated memory 

Errors: 

See GetMem 

Notes: 

This function allocates a block of memory with an associated selector:offset. The 
allocation does not consume a selector on each call as does GetMem because a non-zero 
offset from an existing selector for this allocation type is returned. GetMemSO is useful 
for applications which make a large number of allocations where running out of selectors 
with GetMem could be a problem. A potential drawback is that memory accesses beyond 
the allocation boundary may go undetected since the selector is shared among several 
allocations. Also, resizing the block can change the selector:offset of the block. 

GetPatch 

Get patch table address. 

Inputs: 

AX= Offfah 

Outputs: 

EDX= Linear address of patch table. 

Errors: 

None. 

GetRVect Get real mode interrupt handler address. 


Inputs: AX= 0200h 

BL= Interrupt vector number. 

Outputs: CX:DX= selector:offset of handler. 
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Errors: None. 


GetSel 

Allocate a new selector. 

Inputs: 

AX= 0ff03h 

Outputs: 

Carry set on error, else 

BX= Selector. 

Errors: 

Approximately 8192 selectors are available initially. While this is a relatively large 
quantity, it is obviously possible to run out if the system is heavily loaded or selectors are 
being wasted. 

Notes: 

A selector is allocated and initialized with a base of 0, a limit of 0 and as read/write expand 
up data. Use SetSelDet to make the selector useful, setting an appropriate base and limit. 

GetSelDet Get selector linear base and limit. 

Inputs: 

AX= 0ff07h 

BX= Selector 

Outputs: 

Carry set on error, else 

CX:DX= Linear base. 

S1:D1= Byte granular limit. 

Errors: 

If an invalid selector is passed in BX, this function returns with carry set. 

GetSelDet32 Get selector linear base and limit. 

Inputs: 

AX= 0ff08h 

BX= Selector 

Outputs: 

Carry set on error, else 

EDX= Linear base. 

ECX= Byte granular limit. 

Errors: 

If an invalid selector is passed in BX, this function returns with carry set. 

GetSels 

Allocate multiple selectors. 


Inputs: AX= 0ff29h 

CX= Number of selectors. 

Outputs: BX= Base selector. 
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Errors: None. 

Notes: The selectors are allocated and initialised with a base of 0, a limit of 0 and as read/write 

expand up data. Use SetSelDet to make the selectors useful. 

GetVect Get Protected mode interrupt handler address. 


Inputs: AX= 0204h 

BL= Interrupt vector number. 

Outputs: CX: [E]DX= selector:offset of handler. 

Errors: None. 


ID Get CauseWay identifier, PageDIRLinear and PagelstLinear info. 


Inputs: AX= 0fff9h 

Outputs: ECX:EDX= CauseWay identifies. 

ESI= Linear address (PageDIRLinear) 
EDI= Linear address (PagelstLinear) 

Errors: None. 


Info Get system selectors/flags. 


Inputs: AX= OffOOh 

Outputs: AX= Selector for real mode segment address of OOOOOh, 4GB limit. 

BX= Selector for current PSP segment. lOOh limit. 

[E]CX= DOS transfer buffer size. Always <64KB. 

DX= DOS transfer buffer real mode segment address. 

ES:[E]SI= DOS transfer buffer address. 

ESI+ECX always <64KB 

EDI= System flags. Bits significant if set. 

0-32 bit code default. 

1 - Virtual memory manager functional. 

2-3 - Mode, 0 - raw, 1 - VCPI, 2 - DPMI. 

4 - DPMI available. 

5 - VCPI available. 

6 - No memory managers. 

7 - Descriptor table type. 0 - GDT, 1 - LDT. 

Errors: None 

Notes: Bits 1-2 of DI indicate the interface type being used by CauseWay. 
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Bits 4-5 indicate the interface types that are available. Bit 7 indicates the descriptor table 
being used to allocate selectors to the application when on a raw/VCPI system. The DOS 
transfer buffer is the area CauseWay uses to transfer data between conventional and 
extended memory during DOS interrupts. This memory can be used as temporary work 
space to access real mode code as long as you remember it may be overwritten the next 
time you issue an INT in protected mode that requires segment pointers. 


IntXX 

Simulate real mode interrupt. 

Inputs: 

AX= OffOlh 

BL= Interrupt number. 

ES:[E]DI= Real mode register list. 

Outputs: 

Register list updated. 

Errors: 

None. 

Notes: 

The real mode register list referenced by ES:[E]DI should contain the register values you 
want passed to the real mode interrupt handler. CauseWay fills in the SS:SP and Flags 
values to ensure that legal values are used and the CS:IP entries are ignored. This function 
bypasses protected mode interrupt handlers and provides access to INT APIs that require 
segment pointers. 

LinearCheck Check linear address of memory. 

Inputs: 

AX= Offfch 

ESI= Linear address of memory. 

Outputs: 

Carry set on invalid memory address. 

Errors: 

None. 

LockMem Lock a region of memory. 


Inputs: AX= Offlbh 

BX:CX= Starting linear address of memory to lock. 

SI:DI= Size of region to lock in bytes. 

Outputs: Carry set on error. 

Errors: If any of the region specified is invalid or if not enough physical memory is available to fill 

the region specified, then none of the memory is locked and this function returns carry set. 


Notes: Memory that is locked cannot be swapped to disk by the VMM. Locking applies to 

memory on page (4KB) boundaries. Therefore, areas of memory below and above the 
memory being locked are locked if the specified region is not aligned to a page boundary. 
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LockMem32 Lock a region of memory. 

Inputs: AX= Offlch 

ESI= Starting linear address of memory to lock. 

ECX= Size of region to lock in bytes. 

Outputs: Carry set on error. 

Errors: See LockMem. 

Notes: Memory that is locked cannot be swapped to disk by the VMM. Locking applies to 

memory on page (4KB) boundaries. Therefore, areas of memory below and above the 
memory being locked are locked if the specified region is not aligned to a page boundary. 

RelCallBack Release a real mode callback entry. 

Inputs: AX= 0304h 

CX:DX= Real mode address returned by GetCallBack 

Outputs: None. 

Errors: None. 

Notes: Uspe this function to release callback addresses once they are no longer needed. 

RelMem Release memory allocated by either GetMem or GetMem32. 

Inputs: AX= OffOfh 

BX= Selector for block to release. 

Outputs: Carry set on error. 

Errors: If an invalid selector is passed in BX or the memory was not allocated via GetMem or 

GetMem32, this function returns carry set. 

RelMemDOS Release a block of DOS (conventional) memory allocated by GetMemDOS. 

Inputs: AX= 0ff23h 

DX= Selector of block to free. 

Outputs: Carry set on error and AX= DOS error code. 

Errors: If an invalid block is passed, this function returns carry set. 

Notes: All descriptors allocated for the memory block are automatically freed and therefore should 

not be accessed once the block is freed by this function. 
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RelMemLinear Release previously allocated block of memory (linear address). 

Inputs: 

AX= 0ffl4h 

SI:DI= Linear address of block to release. 

Outputs: 

Carry set on error. 

Errors: 

If the address passed in SI:DI is not a valid memory block, this function returns carry set. 

ReIMemLinear32 Release previously allocated block of memory (linear address). 

Inputs: 

AX= 0ffl5h 

ESI= Linear address of block to release. 

Outputs: 

Carry set on error. 

Errors: 

See RelMemLinear 

RelMemSO Release a block of memory allocated via GetMemSO. 

Inputs: 

AX = 0ff2eh 

SI:DI = Selector:offset of block to release 

Outputs: 

Carry set on error. 

Errors: 

If an invalid selector:offset is passed in SI:DI or the memory was not allocated via 
GetMemSO, then this function returns carry set. 

RelSel Release a selector. 

Inputs: 

AX= 0ff04h 

BX= Selector. 

Outputs: 

Carry set on error. 

Errors: 

If an invalid selector is passed in BX, this function returns with carry set. 

Notes: 

Use this function to release selectors allocated by GetSel or AliasSel. 

ResMem 

Resize a previously allocated block of memory. 
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Inputs: 

AX- OffOdh 

BX= Selector for block. 

CX:DX= New size of block required in bytes. 

Outputs: 

Carry set on error. 

Errors: 

If an invalid selector is passed in BX or not enough memory is available when increasing 
the block size, then this function returns carry set. 

Notes: 

If the memory block cannot be resized in its current location, but a free block of memory of 
the new size exists, the memory is copied to a new block and the old one is released. The 
application is not affected as long as only the selector originally allocated with GetMem 
accesses the memory. 


ResMemSO Resize a block of memory allocated via GetMemSO. 

Inputs: AX = 0ff2dh 

SI:DI = Selector:offset of block to resize 
CX:DX = New size of block required in bytes 

Outputs: Carry set on error, else 

SI:DI = selector:offset of new memory block address. 

Errors: If an invalid selector:offset is passed in SI:DI or not enough memory is available when 

increasing the block size, then this function returns carry set. 

Notes: If the memory block cannot be resized in its current location, but a free block of memory of 

the new size exists, the memory is copied to a new block and the old one is released. The 
selector:offset will change if this occurs, so the SI:DI return value should be used to update 
all references and pointers to the memory block when this function is called. 

ResMem32 Resize a previously allocated block of memory. 

Inputs: AX= OffOeh 

BX= Selector for block. 

ECX= New size of block required in bytes. 

Outputs: Carry set on error. 

Errors: See ResMem 

Notes: If the memory block cannot be resized in its current location, but a free block of memory of 

the new size exists, the memory is copied to a new block and the old one released. This is 
transparent to the application as long as only the selector originally allocated with GetMem 
is used to access the memory. 
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ResMemDOS Resize a block of DOS (conventional) memory allocated with GetMemDOS. 


Inputs: AX= 0ff22h 

BX= New block size in paragraphs 
DX= Selector of block to modify 

Outputs: Carry set on error, AX= DOS error code, BX= Maximum block size in paragraphs. 

Errors: If an invalid block is passed or if not enough selectors or memory are available when 

expanding the block this function returns carry set. 

Notes: Growing a memory block is often likely to fail since other DOS block allocations prevent 

increasing the size of the block. Also, if the size of a block grows past a 64KB boundary 
then the allocation fails if the next descriptor in the LDT is not free. 

ResMemLinear Resize a previously allocated block of memory without a selector. 


Inputs: AX= 0ffl2h 

SI:DI= Linear address of block to resize. 

CX:DX= Size of block required in bytes. 

Outputs: Carry set on error, else 

SI:DI= New linear address of block. 

Errors: If not enough memory is available when extending the block size this function returns carry 

set. 

Notes: If the memory block cannot be expanded to the desired size, and a free block of sufficient 

size exists, the existing memory is copied to the free block and released. The new block is 
allocated in place of the old. 

ResMemLinear32 Resize a previously allocated block of memory without a selector. 


Inputs: AX=0ffl3h 

ESI= Linear address of block to resize. 

ECX= Size of block required in bytes. 

Outputs: Carry set on error, else 

ESI= New linear address of block. 

Errors: See ResMemLinear 

Notes: If the memory block cannot be expanded to the desired size, and a free block of sufficient 

size exists, the existing memory is copied to the free block and released. The new block is 
allocated in place of the old. 
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SetDOSTrans Set new address and size of the buffer used for DOS memory transfers. 

Inputs: 

AX = 0ff26h 

BX = Real mode segment of buffer. 

DX = Protected mode selector for buffer. 

ECX = Buffer size (should be <=64KB) 

Outputs: 

None 

Errors: 

None 

Notes: 

The buffer must be in conventional memory and only the first 64KB will be used even if a 
bigger buffer is specified. CauseWay will automatically restore the previous buffer setting 
when the application terminates but GetDOSTrans can be used to get the current buffer’s 
settings if you only want the change to be temporary. 

You can still use the default buffer for your own purposes even after setting a new address. 

SetDump Disable/enable error display and CW.ERR creation. 

Inputs: 

AX = 0ff30h 

CL = 0 if disable error display and CW.ERR file 

CL = nonzero if enable error display and CW.ERR file 

Outputs: 

None 

Errors: 

None 

Notes: 

By default, register dump display to screen and CW.ERR file creation are enabled on CPU 
faults. This option may be used to turn on and off CauseWay error processing output any 
number of times within an application. 

SetEVect 

Set Protected mode exception handler address. 


Inputs: AX= 0203h 

BL= Exception vector number. 

CX:[E]DX= selector:offset of new handler. 

Outputs: None 

Errors: The number in BL must be in the range 0-lFh. Anything outside this range returns carry 

set. 
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SetMCBMax Set new memory control block (MCB) memory allocation block size. 


Inputs: AX = 0ff28h 

ECX = New value to set (<=64KB) 

Outputs: None 

Errors: Carry set on error 

Notes: The maximum block size that will be allocated from MCB memory is 16 bytes less than the 

value set by this function. The default value is 16384. The maximum value is 65536. 

The CauseWay API memory allocation functions allocate memory from two sources. 
Allocation requests below the value returned by this function are allocated from a memory 
pool controlled via conventional style MCB's. Requests above this value are allocated via 
the normal DPMI functions. Because DPMI memory is always allocated in multiples of 
pages (4KB) it can become very inefficient for any program that needs to allocate small 
blocks of memory. The value set by this function controls the size of memory chunks that 
will be allocated to and managed by the MCB system. 

A value of zero can be passed to this function to disable the MCB allocation system. 

The value passed will be rounded up to the nearest page (4KB) boundary. 

SetRVect Set real mode interrupt handler address. 


Inputs: AX= 020 lh 

BL= Interrupt vector number. 

CX:DX= selector:offset of new handler. 

Outputs: None. 

Errors: None. 


SetSelDet Set selector linear base and limit. 


Inputs: AX= 0ff09h 

BX= Selector. 

CX:DX= Linear base. 

SI:DI= Byte granular limit. 

Outputs: Carry set on error. 

Errors: If an invalid selector is passed in BX, this function returns with carry set. 
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SetSelDet32 Set selector linear base and limit. 


Inputs: AX= OffOah 

BX= Selector. 

EDX= Linear base. 

ECX= Byte granular limit. 

Outputs: Carry set on error. 

Errors: If an invalid selector is passed in BX, this function returns with carry set. 

SetVect Set Protected mode interrupt handler address. 


Inputs: AX= 0205h 

BL= Interrupt vector number. 

CX:[E]DX= selector:offset of new handler. 

Outputs: None. 

Errors: None. 


UnLockMem Unlock a region of memory. 


Inputs: AX= Offldh 

BX:CX= Starting linear address of memory to unlock 
SI:DI= Size of region to unlock in bytes 

Outputs: Carry set on error. 

Errors: If any of the memory region specified is invalid this function returns carry set. 

Notes: This function allows the unlocked memory to be swapped to disk by the VMM if necessary. 

Areas below and above the specified memory to the nearest page (4KB) boundary are 
unlocked if the specified region is not aligned to a page boundary. 

UnLockMem32 Unlock a region of memory. 


Inputs: AX= Off 1 eh 

ESI= Starting linear address of memory to unlock 
ECX= Size of region to unlock in bytes 

Outputs: Carry set on error. 

Errors: See UnLockMem 
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Notes: This function allows the memory to be swapped to disk by the VMM if necessary. Areas 

below and above the specified memory to the nearest page (4KB) boundary are unlocked if 
the specified region is not aligned to a page boundary. 

UserDump Setup user-defined error buffer dump in CW.ERR. 

Inputs: AX = 0ff2fh 

ES:[E]DI - user buffer to display in CW.ERR 

CX = count of bytes to display from buffer in CW.ERR 

BL = 'A’ if ASCII dump (non-binary display of bytes, control characters display as 
periods) 

BH = nonzero if preset ASCII buffer to word value, ignored for non-ASCII 

DX = word value to fill ASCII dump buffer if BH is nonzero, ignored for non-ASCII 

Outputs: Carry set on ASCII dump invalid buffer address. 

Errors: The user buffer must be a valid readable selector and offset value when this function is 

called or else the request is ignored and a carry flag condition is returned. If BH is set to 
nonzero to flag presetting the buffer bytes, the selector must be writable. Specifying a 
larger CX count than available buffer size will also return an error. 

Notes: If the fill ASCII buffer condition is specified, any values previously in the buffer will be 

overwritten when this call is made. 


UserErrTerm Call user error termination routine. 


Inputs: AX = 0ff31h 

CL = 0 if 16-bit termination routine 

CL = nonzero if 32-bit termination routine 

DS:[E]SI = user termination routine address. If DS is zero, the user termination routine call 
is removed. 

ES:[E]DI = Information dump buffer address, 104 bytes. If ES is zero, no information 
dump is performed. 

Outputs: None 

Errors: None 

Notes: The user termination routine is responsible for returning to the CauseWay termination 

routines to allow proper shutdown of the application. The instruction must be the proper 
16- or 32-bit return to match the CL register setting. For ease of use with high-level 
languages (specifically Watcom C and setting SS back to DGROUP), [E]SI equals the 
internal DOS extender stack ESP immediately prior to the 32- or 16-bit call to the 
termination routine. If an information dump buffer address is provided, register and other 
termination values are placed into it using the following format: 
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dword 

EBP; 

dword 

EDI; 

dword 

ESI; 

dword 

EDX; 

dword 

ECX; 

dword 

EBX; 

dword 

EAX; 

word 

GS; 

word 

FS; 

word 

ES; 

word 

DS; 

dword 

EIP; 

word 

CS; 

word 

reservedl; 

dword 

EFLAGS; 

dword 

ESP; 

word 

SS; 

word 

reserved2; 

word 

TR; 

dword 

CRO; 

dword 

CR1; 

dword 

CR2; 

dword 

CR3; 

dword 

csAddress; 

dword 

dsAddress; 

dword 

esAddress; 

dword 

fsAddress; 

dword 

gsAddress; 

dword 

ssAddress; 

word 

ExceptionNumber; 

dword 

ErrorCode; 


7.6 API Notes 


A fixed segment selector at 40h is always available to the application. This selector maps the real mode 
memory at 400h where most of the BIOS variables can be found. CauseWay also provides selectors at 
standard video addresses OBOOOh, 0B800h and OAOOOh in non-DPMI environments to ease conversion of 
real mode code. 

The environment variable block address in the Program Segment Prefix (PSP) is a valid protected mode 
selector. A valid protected mode selector:offset is also placed in the PSP at offset 34h for the file handle 
list pointer. Note that the default value in the program’s PSP will point to the real mode PSP, not the 
protected mode PSP, even if the handle count is less than or equal to twenty. Code that makes use of the 
handle list should use the address at PSP+34h rather than assuming the list’s position within the PSP. Also, 
when an application is operating non-DPMI conditions the handle table will have an entry for CauseWay’s 
VMM swap file. 

DOS functions which use the obsolete file control blocks (FCBs) are not supported by CauseWay, although 
such support may be added by the developer. 

CauseWay applications should terminate using INT 21H function 4Ch. As with real mode operation, the 
error level passed to this function in the AL register is returned to the parent program or DOS. 
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If a CauseWay application needs to terminate and stay resident (TSR), then INT 21H function 3lh may be 
used. Unlike real mode operation, no memory value is required for this function. All memory owned by 
the application when the TSR function is issued remains the program’s property. There is currently no way 
of removing the CauseWay application from memory once it becomes a TSR without rebooting the 
machine or using a third party TSR manager. However, a TSR manager will not automatically release 
extended memory allocated for the CauseWay TSR. 

Unhandled exceptions terminate the program with a register display dump to screen and a text file called 
CW.ERR. CW.ERR contains other potentially useful information about the state of the application when it 
terminated. Refer to the appendices for more information on the CW.ERR file information format. 

CauseWay runs applications at privilege level 3. Privilege level 0 reserved instructions will cause a general 
protection fault (GPF). CauseWay emulates the four instructions MOV EAX.CRO; MOV CRO.EAX; MOV 
EAX.CR3; and MOV CR3,EAX in the GPF handler so that they may be used by an application. 

CauseWay will match a DPMI OAOOh function call with target string RATIONAL/4G. This in conjunction 
with CRO emulation allows support of floating point emulation by an exception handler. Watcom uses this 
approach under DOS/4GW operation if the floating point emulation library is not linked in. Note that this 
routine does not work for either CauseWay or DOS/4GW under a DPMI host such as Windows or OS/2. 
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8 Interrupt Services 


8.1 Extended or Altered Interrupt Services 

The size of registers used by CauseWay’s extended or modified interrupt services depends on the limit of 
the selector. Extended 32-bit registers are used for 32-bit sized selectors and 16-bit registers are used for 
selectors within 16-bits. To reflect this, the convention of an [E] in brackets is used before a listed register 
when it must be a 32-bit value with a 32-bit selector and a 16-bit value with a 16-bit selector. 

Required registers that are not specified in this list should be set up in the same way as required for normal 
DOS real mode operation. For INT APIs that are not listed and require segemnt pointers, either handle 
them using the CauseWay IntXX function or create your own interrupt translation code. 

INT lOh 

lOh sub function 02h, [E]DX instead of DX. 
lOh sub function 09h, [E]DX instead of DX. 
lOh sub function 12h, [E]DX instead of DX. 
lOh sub function 17h, [E]DX instead of DX. 

13h [E]BP instead of BP. 

ICh sub function Olh, [E]BX instead of BX. 

ICh sub function 02h, [E]BX instead of BX. 

INT 21h 

09h [E]DX instead of DX 
OAh [E]DX instead ofDX 

OFH - 17H not supported; use corresponding file handle function. 

1 Ah [E]DX instead of DX 

21h - 24h not supported; use corresponding file handle function. 

25h [E]DX instead of DX. Protected mode vector will be set. 

26h - 29h not supported; use corresponding file handle function. 

2Fh [E]BX instead of BX 
3lh No value is required in DX 

35h [E]DX instead of BX. Protected mode vector will be returned. 

39h [E]DX instead of DX 

3 Ah [E]DX instead ofDX 

3Bh [E]DX instead of DX 

3Ch [E]DX instead of DX 

3Dh [E]DX instead ofDX 

3Fh [E]DX instead ofDX 

40h [E]DX instead of DX 

41h [E]DX instead ofDX 

43h [E]DX instead of DX 

44h subfunction 02h, use [E]DX instead 

44h subfunction 03h, use [E]DX instead 

44h subfunction 04h, use [E]DX instead 

44h subfunction 05h, use [E]DX instead 
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47h [E]SI instead of SI 

48h Protected mode memory will be allocated 

49h Protected mode memory will be released 

4Ah Protected mode memory will be resized 

4Bh [E]DX & [E]BX instead of DX & BX 

Parameter block offset entries are [d]word 

4Eh [E]DX instead of DX 

56h [E]DX & [E]DI instead of DX & DI 

5 Ah [E]DX instead ofDX 

5Bh [E]DX instead of DX 

62h Protected mode selector will be returned 

6Ch [E]SI instead of SI 

INT 23h Control-C Handler Address 

This interrupt is always reflected back to the protected mode handler to ensure the CauseWay application 
can handle it correctly. The default handler aborts the application in the same manner as DOS. If you need 
to terminate your application in your own handler, perform an INT 21h AH=4ch as normal. 

INT 24h Critical Error Handler Address 

This interrupt is always reflected back to the protected mode handler to ensure the CauseWay application 
can handle it correctly. The default handler behaves in the same way as the DOS handler and it aborts your 
application, if appropriate. If you install your own handler, all memory accessed by this interrupt as code 
or data must be locked. 

The register values normally placed on the stack by DOS before entry to the interrupt handler are not 
present in protected mode. Only the register values are valid. You may terminate your application from 
within this interrupt with INT 21h, AH=4ch as normal. 

INT 33h 

09h [E]DX instead of DX 
OCh [E]DX instead of DX 
16h [E]DX instead of DX 
17h [E]DX instead of DX 

Notes: 

With the exception of software interrupts that require segment pointers as parameters, all interrupts can be 
issued as normal. The most common interrupt APIs that require segment pointers are intercepted by 
CauseWay to provide normal access to these services. Any other real mode interrupt services that require 
segment pointers can be accessed using CauseWay’s simulated real mode interrupt/far call services. 

Hardware interrupts are always reflected to protected mode handlers even when signaled during real mode 
operations. This ensures that protected mode applications always retain control without requiring you to 
patch real mode interrupt vectors. The remaining interrupts are serviced via the vector table appropriate to 
the mode. Use the real to protected mode callback services to provide real mode code with access to 
protected mode code, and allow any interrupt to be re-signaled in protected mode. 

If you add your own hardware interrupt handlers, suchas the timer tick at vector 08h, any memory that the 
handler reads or writes, including its code, must reside in locked memory. (CauseWay provides a locked 
stack.) This limitation is required because DOS is not re-entrant and hardware interrupts can occur at any 
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time. Interrupts occurring during DOS activity prevent CauseWay’s virtual memory manager from 
accessing its swap file. Lock memory will not move to the swap file. 
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9 Troubleshooting 


9.1 First Steps 

If you have problems using CauseWay, first try linking and running a one-line program that simply prints 
"Hello" on your computer screen. This will help establish if the problem is a basic incompatibility with 
CauseWay and your system setup, or if the error may lie elsewhere (e.g. a third party library). 

The remainder of this chapter provides a description of error and warning messages that you may encounter 
when using CauseWay. Suggested solutions to correct the errors are included where possible. 

9.2 DOS Extender Error Messages and Return Values 

DOS extender error messages are displayed by the CauseWay DOS extender when a CauseWay application 
is running and encounters a serious problem that it cannot recover from. The DOS extender then terminates 
the application with the appropriate return code, displaying a dump of register values, and writing system 
information to the file CW.ERR. 

Error 01 Unable to resize program memory block. 

Generated if DOS reports an error when CauseWay tries to resize its real mode memory 
block. As the block is always shrunk, the only possible cause of this is corrupted memory 
control blocks (MCBs). Reboot the system to correct this error. 

Error 02 386 or better required. 

Generated if CauseWay is run on any machine with a processor below a 386SX. To correct 
this error, run the application on another machine or upgrade the machine’s processor. 

Error 03 Non-standard protected mode program already active. 

Generated if the system is already operating under the control of another protected mode 
program which doesn't conform to either VCPI or DPMI standards. Identify and remove 
the other application before running the CauseWay application. 

Error 04 DOS 3.1 or better required. 

Generated if DOS version is less than 3.1. You need to upgrade the machine’s DOS 
version or use another machine to operate the CauseWay application. 

Error 05 Not enough memory for CauseWay. 

Generated if the system doesn’t have enough free physical memory to initialize the 
CauseWay kernel code and data. Free additional memory before running the CauseWay 
application. The memory can be any of the extended or conventional types supported by 
CauseWay. 
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Error 06 


Error 07 


Error 08 


Error 09 


Error 10 


Error 11 


Error 12 


Error 13 


Error 14 


VCPI failed to switch into protected mode. 

Generated if a VCPI server is detected and the server fails to switch into protected mode 
when requested. The only likely cause of this error is a corrupted system. Reboot the 
system and try again. 

Unable to control A20. 

Generated if CauseWay detects an A20 line that doesn’t respond to the normal control 
methods. This may indicate either a hardware fault or a nonstandard system. There is no 
software solution for these hardware problems. Installing an XMS driver such as 
HIMEM.SYS should address nonstandard systems. 

Selector allocation error. 

Generated if DPMI refuses to allocate enough selectors for CauseWay to function. 

Remove one or more programs that are also using DPMI. 

Unrecoverable exception. Program terminated. 

This is the standard General Protection Fault, or GPF, message. It is generated if a 
nonrecoverable exception occurs which suggests a bug in the application. Use the register 
dump displayed with this message along with the information in CW.ERR and the 
program’s .MAP file to help track down the location and cause of the problem. 

Unable to find application to load. 

Generated if CauseWay is unable to find the application within the executable .EXE file. 
This situation indicates a corrupted file. Rebuild or obtain another copy of the application. 

DOS reported error while accessing application. 

Generated if any kind of error is detected while accessing the CauseWay application 
executable file. This situation indicates a corrupted or missing file. Rebuild or obtain 
another copy of the application. 

Not enough memory to load application. 

Generated if CauseWay is unable to provide enough memory to load the application. Free 
additional memory and/or disk space before running the application. Check for 
CAUSEWAY=SWAP, TEMP and TMP environment variables that point to a disk with 
little free space. If running under an operating system that provides DPMI per application, 
increase the application’s DPMI allocation. 

DPMI failed to switch to protected mode. 

Generated if the machine is using a DPMI server and it fails to switch to protected mode. If 
the DPMI server only supports multiple clients of the same type (either 16- or 32-bit) then 
the problem is probably that different types of applications are already being run. Remove 
the other type of DPMI application(s) before running the CauseWay application. 

Memory structures destroyed. Program terminated. 
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Error 15 


Error 16 


Generated if internal memory management structures become corrupted. This is caused by 
the CauseWay application writing to memory regions that have not been allocated to it and 
is a bug in the application. Obtain a corrected version of the application to fix this error. 

DOS reported an error while accessing swap file. Program terminated. 

Generated if any level of error is detected while accessing the swap file. The swap file has 
probably been deleted inadvertently by the application or perhaps marked as read-only. 

Unsupported DOS function call. Program terminated. 

The CauseWay application attempted to use an obsolete DOS function which used file 
control blocks (FCBs). Use the file handle DOS functions in the application instead. 
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11ntroduction to Open Watcom C/C++ 


Welcome to the Open Watcom C/C++ 2.0 development system. Open Watcom C/C++ is an Open Source 
successor to commercial compilers previously marketed by Sybase, Powersoft and originally WATCOM 
International Corp. 

Version 2.0 of Open Watcom C/C++ is a professional, optimizing, multi-platform C and C++ compiler with 
a comprehensive suite of development tools for developing and debugging both 16-bit and 32-bit 
applications for DOS, extended DOS, Novell NLMs, 16-bit OS/2, 32-bit OS/2, Windows 3.x, Windows 
95/98/Me, Win32s, and Windows NT/2000/XP (Win32). 

You should read the entire contents of this booklet, as it contains information on new programs and 
modifications that have been made since the previous release. 

Special NOTE to users of previous versions! See the section entitled "Release Notes for Open Watcom 
C/C++ 2.0" on page 39 to determine if you need to recompile your application. 


1.1 What is in version 2.0 of Open Watcom C/C++? 

Version 2.0 incorporates the features professional developers have been demanding: 

Open, Multi-target Integrated Development Environment 

The IDE allows you to easily edit, compile, link, debug and build applications for 16-bit systems 
like DOS, OS/2 1.x, and Windows 3.x and 32-bit systems like extended DOS, Novell NLMs, 
OS/2, Windows 3.x (Win32s), Windows 95/98/Me, and Windows NT/2000/XP. Projects can be 
made up of multiple targets which permit a project to include EXEs and DLLs. The IDE produces 
makefiles for the project which can be viewed and edited with a text editor. The IDE is hosted 
under Windows 3.x, Windows 95/98/Me, Windows NT/2000/XP, and 32-bit OS/2. 

The Widest Range of Intel x86 Platforms 


Host Platforms 


• DOS (command line) 

• 32-bit OS/2 (IDE and command line) 

• Windows 3.x (IDE) 

• Windows 95/98/Me (IDE and command line) 

• Windows NT/2000/XP (IDE and command line) 

16-bit Target Platforms 

•DOS 

• Windows 3.x 
•OS/2 1.x 
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32-bit Target Platforms 

• Extended DOS 

• Win32s 

• Windows 95/98/Me 

• Windows NT/2000/XP 

• 32-bit OS/2 

• Novell NLMs 

Cross-Platform Development Tools 

The core tools in the package permit cross-platform development that allows developers to exploit 
the advanced features of today’s popular 32-bit operating systems, including Windows 95/98/Me, 
Windows NT/2000/XP, and OS/2. Cross-platform support allows you to develop on a host 
development environment for execution on a different target system. 

Multi-Platform Debugger 

The new debugger advances developer productivity. New features include redesigned interface, 
ability to set breakpoints on nested function calls, improved C++ and DLL debugging, reverse 
execution, and configurable interface. Graphical versions of the debugger are available under 
Windows 3.x, Windows 95/98/Me, Windows NT/2000/XP, and 32-bit OS/2. Character versions 
of the debugger are available under DOS, Windows 3.x, Windows NT/2000/XP, and 32-bit OS/2. 
Lor VIDEO fans, we have kept the command line compatibility from the original debugger. 

Class Browser 

The Browser lets you visually navigate the object hierarchies, functions, variable types, and 
constants of your C/C++ application. 

Performance Analysis 

The Open Watcom Execution Sampler and Open Watcom Execution Profiler are performance 
analysis tools that locate heavily used sections of code so that you may focus your efforts on these 
areas and improve your application’s performance. 

Editor The Open Watcom Editor is a context sensitive source editor, integrated into the Windows 3.x, 
Windows 95/98/Me and Windows NT/2000/XP version of the IDE. 

Graphical Development Tools 

Open Watcom C/C++ includes a suite of graphical development tools to aid development of 
Windows 3.x, Windows 95/98/Me and Windows NT/2000/XP applications. The development 
tools include: 


Resource Editors Enable you to create resources for your 16-bit and 32-bit Windows 

applications. For 32-bit OS/2 PM development. Open Watcom C/C++ 
interoperates with IBM’s OS/2 Developer’s Toolkit (available from IBM). 
These tools have been seamlessly integrated into the IDE. The resource 
compiler allows you to incorporate these resources into your application. 

Resource Compiler Produces a compiled resource file from a source file. 


Zoom 


Magnifies selected sections of your screen. 


Heap Walker Displays memory usage for testing and debugging purposes. 


Spy 


Monitors messages passed between your application and Windows. 


2 What is in version 2.0 of Open Watcom C/C++? 




Introduction to Open Watcom C/C++ 


DDESpy Monitors all DDE activity occurring in the system. 

Dr. Watcom Enables you to debug your program by examining both the program and the 

system after an exception occurs; monitors native applications running under 
Windows 3.x, Windows 95/98/Me or Windows NT/2000/XP. 


Assembler 

An assembler is included in the package. It is compatible with a subset of the Microsoft macro 
assembler (MASM). 

C++ Class Libraries 

Open Watcom C/C++ includes container and stream class libraries. 

Royalty-free 32-bit DOS Extender 

Open Watcom C/C++ includes the DOS/4GW 32-bit DOS extender by Tenberry Software with 
royalty-free run-time and virtual memory support up to 32MB. 

Support for wide range of DOS Extenders 

Open Watcom C/C++ allows you to develop and debug applications based on the following DOS 
extender technology: CauseWay DOS Extender, Tenberry Software’s DOS/4G and Phar Lap’s 
TNT DOS Extender. You can also develop applications using DOS/32A and FlashTek's DOS 
Extender but, currently, there is no support for debugging these applications. 

Sample programs and applications 

Open Watcom C/C++ includes a large set of sample applications to demonstrate the integrated 
development environment. 

1.2 Technical Support and Services 

We are committed to ensuring that our products perform as they were designed. Although a significant 
amount of testing has gone into this product, you may encounter errors in the software or documentation. 
Technical support is provided on an informal basis through the Open Watcom C/C++ newsgroups. Please 
visit http://www.openwatcom.org/ for more information. 

Resources at Your Fingertips 

Open Watcom C/C++ contains many resources to help you find answers to your questions. The 
documentation is the first place to start. With each release of the product, we update the manuals to answer 
the most frequently asked questions. Most of this information is also accessible through on-line help. 

The "README" file in the main product directory contains up-to-date information that recently became 
available. 

Answers to frequently asked questions are available on the Open Watcom World Wide Web server 
(http: //www. open watcom. org/). 
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Contacting Technical Support 

Our technical support is available to help resolve technical defects in the software. Note that all support is 
currently informal and free. The following are ways to contact technical support. 

Newsgroups The easiest way to get support is through the Open Watcom newsgroups at 
news://news.openwatcom.org/. 

World Wide Web You can also submit bug reports or enhancement requests through the Open Watcom bug 
tracking system at http://bugzilla.openwatcom.org/. 

Information Technical Support Will Need to Help You 

The more information you can provide to technical support, the faster they can help you solve your 
problem. A detailed description of the problem, short sample program, and a summary of steps to duplicate 
the problem (including compiler and linker options) are essential. Concise problem reports allow technical 
support to quickly pinpoint the problem and offer a resolution. Here is a list of information that will help 
technical support solve the problem: 

Contact information 

We would like your name, as well as telephone and fax numbers where you can be reached 
during the day. 

Product information 

Please tell us the product name and exact version number. 

Hardware configuration 

Please tell us what type of processor you are using (e.g., 2.2GHz Intel Pentium 4), how 
much memory is present, what kind of graphics adapter you are using, and how much 
memory it has. 

Software configuration 

Please tell us what operating system and version you are using. 

Concise problem report with short sample program 

Please provide a complete description of the problem and the steps to reproduce it. A 
small, self-contained program example with compile and link options is ideal. 

Suggested Reading 

There are a number of good books and references that can help you answer your questions. Following is a 
list of some of the books and documents we feel might be helpful. This is by no means an exhaustive list. 
Contact your local bookstore for additional information. 

C Programmers 
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The C Programming Language, 2nd Edition 

Brian W. Kernighan and Dennis M.Ritchie; Prentice Hall, 1988. 


C DiskTutor 

L. John Ribar; Osborne McGraw-Hill, 1992. 


C++ Programmers 

C++ Primer, 2nd Edition 

Stanley B. Lippman; Addison-Wesley Publishing Company, 1991. 

Teach Yourself C++ in 21 Days 

Jesse Liberty; Sams Publishing, 1994. 


DOS Developers 

PC Interrupts, Second Edition 

Ralf Brown and Jim Kyle; Addison-Wesley Publishing Company, 1994. 

Relocatable Object Module Format Specification, VI.1 

The Tool Interface Standards (TIS) OMF specification can be obtained from the Open 
Watcom website. Here is the URL. 

http://www.openwatcom.org/ftp/devel/docs/omf.pdf 

This file contains a PDF version of the TIS OMF V 1.1 specification. 

Extended DOS Developers 

Extending DOS—A Programmer’s Guide to Protected-Mode DOS, 2nd Edition 
Ray Duncan, et al; Addison-Wesley Publishing Company, 1992. 

DOS Protected-Mode Interface (DPMI) Specification 

The DPMI 1.0 specification can be obtained from the Open Watcom website. Here is the 
URL. 


http://www.openwatcom.org/ftp/devel/docs/dpmi10.pdf 


This file contains a PDF version of the DPMI 1.0 specification. 

Windows 3.x Developers 

Microsoft Windows Programmer’s Reference 

Microsoft Corporation; Microsoft Press, 1990. 

Programming Windows 3.1, Third Edition 

Charles Petzold; Microsoft Press, 1992. 

Windows Programming Primer Plus 

Jim Conger; Waite Group Press, 1992. 
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Windows NT Developers 

Advanced Windows NT 

Jeffrey Richter; Microsoft Press. 1994. 

Inside Windows NT 

Helen Custer; Microsoft Press. 1993. 

Microsoft Win32 Programmer’s Reference, Volume One 

Microsoft Corporation; Microsoft Press, 1993. 


OS/2 Developers 

The Design of OS/2 

H.M. Deitel and M.S. Kogan; Addison-Wesley Publishing Company, 1992. 

OS/2 Warp Unleashed, Deluxe Edition 

David Moskowitz and David Kerr, et al; Sams Publishing, 1995. 

Virtual Device Driver Developers 

Writing Windows Virtual Device Drivers 

David Thielen and Bryan Woodruff; Addison-Wesley Publishing Company, 1994. 
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2 Installation 


The package contains the following components: 

• Open Watcom C/C++ CD-ROM 

• This manual 


2.1 Hardware and Software Requirements 

Open Watcom C/C++ requires the following minimum configuration: 

• IBM PC compatible 

• An 80386 or higher processor 

• 8 MB of memory 

• Hard disk with enough space available to install the components you require. 

• A CD-ROM disk drive 

In addition to the above requirements, you need one of the following operating systems: 

• DOS version 5.0 or higher 

• Microsoft Windows version 3.1 running in enhanced mode 

• Microsoft Windows 95 or higher 

• Microsoft Windows NT version 3.1 or higher 
•IBM OS/2 2.1 or higher 


2.2 The README File 


Before you install Open Watcom C/C++, you should read the contents of the "README" file which is 
stored in the root directory of the CD-ROM. It contains valuable, up-to-date information concerning this 
product. 

2.3 Installing Open Watcom C/C++ 

The installation program in this version has been completely redesigned with several new "smart" features. 
If you have installed a previous version of Open Watcom C/C++ then you should install Open Watcom 
C/C++ 2.0 into the same path (except for the reason described in the following paragraph). It will examine 
a previous installation to determine what features were previously installed. It will use this information to 
establish default settings for the installation that you are about to attempt. Of course, you can add or 
remove features as you progress through the installation steps. 
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If you are installing only one of the Open Watcom C/C++ or Open Watcom FORTRAN 77 products and 
you have an older version of the other product, we do NOT recommend that you install the new product 
into the same directory as the old product. The Open Watcom C/C++ and Open Watcom FORTRAN 77 
products are compatible at the same version number. However, the Open Watcom C/C++ and Open 
Watcom FORTRAN 77 products are usually NOT compatible across different version numbers. If this is 
the case, care must be exercised when switching between use of the two products. Environment variables 
such as PATH and WATCOM must be modified and/or corrected. System files such as CONFIG.SYS 
and SYSTEM. INI must be modified and/or corrected. 

If you are installing both Open Watcom C/C++ 2.0 and Open Watcom FORTRAN 77 2.0, we recommend 
that you install both products under the same directory. This will eliminate duplication of files and, as a 
result, reduce the total required disk space. The two products share the use of certain environment variables 
which point to the installation directory. If separate installation directories are used, problems will arise. 

When you install Open Watcom C/C++ and Open Watcom FORTRAN 77 in the same directory, you 
should not deselect any options when running the second installation; otherwise the second product’s install 
may remove files that were installed (and are required) by the first product’s install. This isn't an issue if 
you only have one of Open Watcom C/C++ or Open Watcom FORTRAN 77. The problem is that Open 
Watcom C/C++ and Open Watcom FORTRAN 77 don’t know about the installation options you have 
selected for each other’s product. 

If you wish to create a backup of your previous version, please do so before installing Open Watcom 
C/C++ 2.0. 

If you decide to install Open Watcom C/C++ 2.0 into a different directory than the previously installed 
version, you will have to manually edit system files (e.g., CONFIG.SYS, AUTOEXEC.BAT, 

SYSTEM.INI) after the installation process is complete to remove the old version from various 
environment variables (e.g., PATH, DEVICE=). This is necessary since the path to the new version will 
appear after the path to the old version. To avoid this extra work, we recommend installing the new version 
into the same path as the old version. 

As an example, here are a few of the environment variables and "RUN" directives that are modified/added 
to the OS/2 CONFIG. SYS file. You should make sure that all references to the older version of the 
software are removed. 


Example: 

LIBPATH=...;D:\WATCOM\BINP\DLL;... 

SET PATH=. . .;D:\WATCOM\BINP;D:\WATCOM\BINW; . . . 
SET HELP=...;D:\WATCOM\BINP\HELP;... 

SET BOOKSHELF=...;D:\WATCOM\BINP\HELP;... 

SET INCLUDE=...;D:\WATCOM\H\OS2;D:\WATCOM\H; 

SET WATCOM=D:\WATCOM 

SET EDPATH=D:\WATCOM\EDDAT 

RUN=D:\WATCOM\BINP\NMPBIND.EXE 


You may wish to run Open Watcom C/C++ under more than one operating system on the same personal 
computer. For every operating system that you use, simply start up the operating system and run the 
corresponding install procedure. 

If you run the Windows 3.x installation procedure, you do not need to run the DOS installation procedure 
also. 

If you plan to use Win-OS/2 as a development platform under OS/2, you must run the Windows 3.1 install 
program (selecting Windows 3.1 host support). 
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Place the CD-ROM disk in your CD-ROM drive. Select one of the following procedures depending on the 
host operating system that you are currently running. Below, substitute the CD-ROM drive specification 
for "x:". 

DOS Enter the following command: 

x:\setup 

Windows 3.x Start Windows 3.x and choose Run from the File menu of the Program Manager. 

Enter the following command: 

x:\setup 

Windows 95/98/Me Choose Run from the Start menu and enter the following command: 

x:\setup 

Windows NT/2000/XP Log on to an account that is a member of the "Administrator" group so that you 

have sufficient rights to modify the system environment. Choose Run from the File 
menu of the Program Manager. Enter the following command: 

x:\setup 

OS/2 Start an OS/2 session and enter the following command: 

x:\install 


2.4 Incremental Installation 


You may wish to install Open Watcom C/C++, and subsequently install features that you omitted in the 
first install. You can also remove features that you no longer wish to have installed. You can achieve this 
as follows: 

1. Start the installation program. 

2. Select any new features that you wish to install. 

3. Deselect any features that you wish to remove. 

4. Re-run the installation program for each host operating system that you use. 

2.5 System Configuration File Modifications 

The install program makes changes to your operating system startup files to allow Open Watcom C/C++ to 
run. We strongly recommend that you allow the install program to modify your system configuration files 
for you, but you may do it by hand. The changes required may be found in any of the following files which 
have been placed in the root of the installation directory: 

CONFIG.NEW Changes required for CONFIG. SYS (DOS, Windows, Windows 95/98/Me, 

OS/2) 

AUTOEXEC.NEW Changes required for AUTOEXEC. BAT (DOS, Windows, Windows 95/98/Me, 

OS/2) 
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CHANGES.ENV Changes required for the Windows NT/2000/XP environment 


2.6 Installation Notes for Windows 3.x 

1. When you use the Integrated Development Environment under Windows 3.x, it is important that 
the IDE’s batch server program be able to run in the background. Therefore, make sure that the 
"Exclusive in Foreground" checkbox is NOT checked in the "Scheduling" options of "386 
Enhanced" in the "Control Panel". 

2. When you use the Integrated Development Environment under Windows 3.x, the line 

OverlappedIO=ON 

in your "SYSTEM.INI" file can cause problems. This controls (disables) the queuing of DisklO 
and makes some changes between DOS box timings to allow some processes to finish. 

3. When you use the Integrated Development Environment under Windows 3.x, it is important that 
the line 

NoEMMDriver=ON 

not appear in your "SYSTEM.INI" file. It will prevent a link from succeeding in the IDE.. 

4. When you use the Integrated Development Environment under Windows 3.x on the NEC 
PC-9800 series, it is important that the line 

InDOSPolling=TRUE 

not appear in your "SYSTEM.INI" file. It will prevent a make from succeeding in the IDE. 

5. Central Point Software’s anti-virus programs (VDEFEND, VSAFE, VWATCH) conflict with the 
Integrated Development Environment under Windows 3.x. 

6. The Program Information File "BATCHBOX.PIF" is used by the Integrated Development 
Environment (IDE) to start up a background batch server for compiling, linking, etc. The PIF 
references "COMMAND.COM". If you are using a substitute for "COMMAND.COM" such as 
"4DOS.COM" then you must modify the PIF accordingly using a PIF editor. 


2.7Installation Notes for OS/2 

1. The Integrated Development Environment (IDE) uses the IBM OS/2 Enhanced System Editor 
(EPM) for editing text files. You must ensure that EPM is installed in your OS/2 system if you 
are planning to use the IDE. You can selectively install the Enhanced Editor by running the 
OS/2 Setup and Installation program (Selective Install) and choosing "Enhanced Editor" from 
the "Tools and Games" detail page. 

2. On some systems with limited memory that use the UNDELETE feature of OS/2, compile times 
may be slow because OS/2 is saving copies of compiler temporary files. You may start the 
BATSERV process using the OS/2 STARTUP . CMD file with DELDIR turned off as illustrated 
below. 
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Installation 


SET OLD_ DEL_ DIR=%DELDIR% 

SET DELDIR= 

DETACH C:\WATCOM\BINP\BATSERV.EXE 
SET DELDIR=%OLD_ DEL_ DIR% 

SET OLD_ DEL_ DIR= 


3. If you plan to use the Named Pipe Remote Debugging support of the Open Watcom Debugger 
then the NMPSERV. EXE . program must be running. It may be started during OS/2 
initialization via a "RUN=" statement in your CONFIG. SYS file or manually as needed through 
the DETACH command. 


Installation Notes for OS/2 
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3 Hands-on Introduction to Open Watcom C/C++ 


Let’s get started and introduce some of the tools that are in Open Watcom C/C++. The purpose of this 
chapter is to briefly test out the new graphical tools in Open Watcom C/C++ using an existing application. 

In this tutorial, we will take an existing set of C++ source files, create a project in our integrated 
development environment, and perform the following tasks: 

• Add multiple targets 

• Make a target 

• Make all targets 

• Execute the program 

• Debug the program 

• Use the Browser 

• Correct errors 

• Sample and profile the executable 

• Save the project 

• Terminate the session 


3.1 Outline 


Open Watcom’s Integrated Development Environment (IDE) manages the files and tools that a programmer 
uses when developing a project. This includes all the source files, include files, libraries, compiler)s), 
linkers, preprocessors, etc. that one uses. 

The IDE has a graphical interface that makes it easy to visualize the make-up of a project. A single IDE 
session shows a project. If the project consists of a number of components, such as two executables and 
one library, these are each shown as target windows in the project window. Each target window shows the 
files that are needed to construct the target and is associated via its filename extension with a rule that 
describes the construction mechanism. For example, a filename with the extension ".EXE" may be 
associated with the rule for constructing 32-bit Windows executables, or a filename with the extension 
".LIB" may be associated with the rule for constructing static libraries. Different projects can refer to the 
same target. If they do, the target is shared and can be manipulated via either project, with changes made 
through one affecting the other. 

The IDE itself is a collection of programs that manages the various files and tools used to create the target 
libraries and executables. It creates makefile(s) from the information in the target descriptions and invokes 
Open Watcom Make to construct the targets themselves. A configuration file contains built-in knowledge 
of the Open Watcom compilers, editors. Profiler, and Browser, as well as all their switches. 


Outline 
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3.2 The Open Watcom C/C++ Tutorial 

This tutorial walks you through the creation and execution of a C/C++ program under Windows. This will 
give you an understanding of the basic concepts of the IDE and its components, and it will detail the steps 
involved in project development. The result of this tutorial is a three dimensional drawing of a kitchen 
which you can manipulate using either the menus or the icons on the toolbar. You can rotate and resize the 
drawing, as well as adjust the lighting and contrast. 

To begin, start the IDE. This is done by double-clicking on the "IDE" icon in the Open Watcom C/C++ 
window. 

A status field at the bottom of the IDE window indicates the function of the icon on the toolbar over which 
your mouse cursor is currently positioned. If the status area does not show you the function of the icons as 
you move the mouse cursor over them, check that no item in the menu bar is highlighted (if one is 
highlighted, press the Alt key). 



Figure 1. The initial IDE screen 


Defining a Project 

In this tutorial, you will be creating a new project called KITCHEN. Here are the steps required to 
accomplish this task. 

1. Define a new project by pulling down the File menu and selecting the New Project... item. You 
can also define a new project by clicking on the "Create a new project" icon on the toolbar. 

2. A choice of different sample project directories is available. Assuming that you installed the 
Open Watcom C/C++ software in the \WATCOM directory, you will find the sample project 
directories in the following directory: 

\WATCOM\SAMPLES\IDE 

For purposes of this tutorial, we recommend that you select one of the following project 
directories: 
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WIN for an example of 16-bit Windows 3.x application development when using 

Windows 3.x under DOS as a host development system, 

WIN386 for an example of 32-bit Windows 3.x application development when using 
Windows 3.x under DOS as a host development system, 

WIN32 for an example of 32-bit Win32 application development when using Windows 

NT/2000/XP or Windows 95/98/Me as a host development system, and 

OS2 for an example of 32-bit OS/2 application development when using 32-bit OS/2 

as a host development system. 

Thus the target that we refer to below should be one of WIN, WIN386, WIN32, or OS2 
depending on your selection. The tutorial uses the WIN32 example for illustrative purposes. 
You will find some minor variations from your selected target environment. 

When asked for a project name, you can do one of two things: 

1. enter the following pathname: 

d:[path]\SAMPLES\IDE\target\KITCHEN 

where d : [path] is the drive and path where you installed the Open Watcom 
software, or 

2. use the file browser to select the following directory: 

d:[path]\SAMPLES\IDE\target 
and specify the filename kitchen . 



Figure 2. Creating a new project 

Press the Enter key or click on OK (OPEN). 

The project description will be stored in this file and the IDE will set the current working 
directory to the specified path during your session. 

3. You will be prompted for a target name. Since we will be attaching pre-defined targets, just 

click the Browse button when prompted for the target name. Select the "draw" target file (it will 
be one of drawl 6 .tgt, draw.tgt, draw32.tgt, drawos2 . tgt depending on your 
selection of target). 
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Figure 3. Attaching existing targets 

Press the Enter key or click on OK (OPEN). 

4. You can ignore the settings displayed for Target Environment and Image Type since the target 
definition already exists (we created it for you). The settings are important when you are 
defining a new target (i.e., one that was not predefined). 



Figure 4. Selecting a target type 

Press the Enter key or click on OK. 

A target window is created in the project window for the "draw" target. This window contains all of the 
files associated with the target. You can click on any of the "Folder" icons to hide or un-hide all files with 
a particular extension. For example, you may wish to un-hide all the files with a . bmp extension by 
clicking on the folder icon associated with bitmap files. 
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Adding Multiple Targets 

Open Watcom’s IDE allows you to have multiple targets in any particular project. Note that targets can be 
used by multiple projects. To add a new target to the project, do the following. 

1. Pull down the Targets menu and select the New Target... item. 

2. Enter button. tgt as the target name for the new target to be added to the project. Do not 
forget to include the . tgt extension. It is required when selecting a pre-existing target. 

3. You can ignore the settings displayed for Target Environment and Image Type since the target 
definition already exists (we created it for you). The settings are important when you are 
defining a new target (i.e., one that was not predefined). 

4. Press the Enter key or click on OK. 

A target window is created in the project window for the button target. 

Making a Target 

Open Watcom’s IDE will automatically generate the sequence of steps required to build or "make" each of 
the targets in a project. Note that the targets in a project can be made individually or collectively. To make 
the button . lib target, do the following. 

1. Click on the window of the target you wish to make. In this case, click on the button . lib 
target window. 

2. Pull down the Targets menu and select the Make item (you can also do this by clicking on the 
"Make the current target" icon on the toolbar, or by right-clicking on the target and selecting the 
Make item from the pop-up menu). 

The IDE will now construct a makefile based on its knowledge of the target and construction rules, and 
then invoke the make utility to create the target, in this case button . lib . The output of this procedure 
is displayed in the Log window. 

Making All Targets 

Click the "Make all targets in the project" icon on the toolbar to make all of the targets in the current 
project. If one target depends on another target, the latter target will be made first. In this tutorial 
button . lib will be made first (there will be nothing to do since it was made previously) and then 
draw??? .exe, since button. lib is in the list of files associated with draw???.exe. In each case, 
the IDE constructs makefiles based on its knowledge of the target and construction rules. The output of this 
procedure is displayed in the Log window. 
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Figure 5. Making one or more targets 


Executing the Program 

The project should have built without errors, so now you are ready to execute the program you have 
developed. 

Click on the draw? ? ? . exe target window and simply click on the "Run the current target" icon on the 
toolbar. You can also do this by selecting Run from the Targets menu, or right-clicking anywhere on the 
target window outside of the inner frame and selecting Run from the pop-up menu (right-clicking is context 
sensitive and the pop-up menu that results will vary depending on the area of the window in which you 
right-click). 
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Figure 6. The kitchen demo 

The demo you have created is a simple three dimensional drawing of a kitchen. By using either the icons 
on the toolbar or the menus you can rotate the picture left, right, up, and down, make the picture brighter or 
dimmer, move the picture closer or farther away, and increase or decrease the amount of contrast (this latter 
feature is found in the "Lighting" menu). Choose Exit from the File menu to exit the demo program when 
you are finished. 

Smart Editing 

The IDE recognizes the type of file you wish to edit, and invokes the appropriate editor for the task. To 
edit a file, you either double-click on it or select it and click the "Edit" icon on the toolbar. Files with a 
.c, . epp, .h, . hpp, .for, . asm or . rc extension are edited with a text editor; files with a .bmp, 
. ico, or . cur extension are edited with the Image Editor; files with a . dig or . res extension are 
edited with the Resource Editor. 
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Figure 7. The Open Watcom Editor for Windows 


Now we will edit one of the source files and introduce an error into the application. 

1. Double-click on the "draw" source file (i.e., draw? ? ? . c) to load the source file into the editor. 

2. Scroll down to line 227 using the keyboard or mouse. You can also pull down the Edit menu, 
select Goto Line..., and enter 227. The Open Watcom Editor makes full use of colors and fonts 
to achieve syntax highlighting. File templates for C, C++, and FORTRAN files are defined to 
assist you in distinguishing the components of your code. 

3. Pull down the Options menu and select the Colors item. 

4. Click on a color from the palette, drag it to the word if on line 218, and release it. All 
keywords are now displayed in the chosen color. Drag a different color to a comment line (line 
225) and all comments will display in that color. Similarly, you can select the Fonts item from 
the Options menu, select a font style and size, and drag it to your source file. Close the Fonts 
and Colors dialog by double-clicking in the upper left hand corner. 

5. You can now save this color and font configuration for all . cpp files by pulling down the 
Options menu, selecting the General..., item and clicking next to Save configuration on exit in 
the "Features" box. Press Enter or click on OK. 

6. Now, to introduce an error into the application, replace the line #if 0 with #if 1. 

7. Save your changes by clicking on the "Write the current file to disk" icon or select Save from the 

File menu. 

8. Return to the IDE (by clicking on it if it is visible on your screen, or by using Alt-Tab), re-make 
your project, and run it. A fault occurs in your application, so the next step is to track down the 
problem using the Open Watcom Debugger. 
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Debugging the Program 

To debug a program it must first be compiled to include debugging information. The IDE maintains two 
sets of switches for each target in a project. These are known as the Development Switches and the Release 
Switches. 

1. Right click on dr aw ? ? ? . c and select Source options from the pop-up menu. Select C 
Compiler Switches from the sub-menu. 

By default, your target is placed in development mode with the debugging switches for the 
compiler and linker set to include debugging information. You can either set the switches in 
each category manually or you can copy the default Release switches using the CopyRel button. 
This method of setting switches is especially convenient since you can specify everything from 
diagnostic, optimization, and code generation switches to special linker switches all without 
having to memorize a cryptic switch name — you simply click next to the switches you wish to 
use for a particular item. 

2. Scroll through the categories using the » button until you get to: 

6. Debugging Switches 

We can see that full debugging information was used in the compile, so just click on Cancel to 
exit this screen. 



Figure 8. Setting compiler switches 

3. To invoke the debugger, pull down the Targets menu and choose the Debug item or select the 
"Debug the current target" icon from the toolbar. 

The Open Watcom Debugger is designed to be as convenient and intuitive as possible, while at the same 
time providing a comprehensive and flexible environment for serious debugging. You can configure your 
environment to display exactly the information you require to be most productive. Among the windows 
available are source and assembly, modules, functions, calls, threads, images, watches, locals, globals, file 
variables, registers, 80x87 FPU, stack, I/O ports, memory display, and a log window. You can step through 
your source using the keys or icons on the toolbar. Execute one line at a time by stepping over calls or 
stepping into calls, or execute until the current function returns. Right-mouse button functionality gives 
context-sensitive pop-up menus. 
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Figure 9. The Open Watcom Debugger 

We know that a fault has occurred in draw? ? ? . exe, so we will run the application and examine the state 
of the program when the fault occurs. 

1. Click on the "go!" icon on the toolbar to begin execution of the program. The exception occurs 
and the source window shows the line 

*pwidth = bitmap.bmWidth + 5; 

in the function button_ size as the last line executed before the exception. Examining the 
Locals window you will see that pwidth is a NULL pointer, hence the exception. 

2. We can now move up the call stack by clicking on the "Move up the call stack" icon on the 
toolbar (red up arrow) to follow the program’s execution. On the previous line, we see 
button_ size is called fromadd_ button. Moving up the call stack again, we see 
add_ button is called with NULL as its fifth parameter. An artificial error has been 
introduced for the purposes of this tutorial. It is located several lines back in the source file. 

3. By replacing the line #if 1 with #if 0 we can bypass this error. Right-click on the line #if 
1 and select Show, then Line... from the pop-up menus to see the line number which must be 
corrected, then exit the debugger. 

4. Double-click on draw? ? ? . c to load the source file into the editor. 

5. Scroll down to line 227 using the keyboard or mouse, or pull down the Edit menu, select Goto 
Line..., and enter 227. 
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6. Replace the line #if 1 with #if 0 and save your changes by clicking on the "Write the 
current file to disk" icon or selecting Save from the File menu. 

7. Return to the IDE (by clicking on it if it is visible on your screen, or by using Alt-Tab) and 
re-make your project. 

8. Run your project to see the kitchen demo. 

Using the Source Browser 

Suppose you wanted to change the color of the tabletop in your application. You can use the Open Watcom 
Browser to determine the code you will need to change. The Open Watcom Browser provides an easy way 
to examine the class definitions, member functions, and inheritance trees associated with your C++ code. 
First, you need to instruct the compiler to emit Open Watcom Browser information. 



Figure 10. The Open Watcom Browser 

1. Right click on furnitu. cpp, then select Source options from the pop-up menus. Select C++ 
Compiler Switches from the sub-menu. 

2. Go to the 

6. Debugging Switches 

category by selecting it from the drop-down list box or by scrolling through the categories using 
the » button. 

3. Select Emit Browser information [-db] and click on OK. 

4. Click the "Make all targets in the project" icon to re-make the project. The compiler will emit 
Browser information for furnitu . cpp in a file called draw? ? ? . dbr . Now you are ready 
to browse the target’s source. 
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5. Pull down the Targets menu and select Browse, or click the "Browse the current target" icon on 
the toolbar. The inheritance tree for the target is displayed. 

6. To view details on any particular class, double-click on the item for information such as the 
location of the class definition, the private, public, and protected functions of the class, and the 
class inheritance. Branches of the inheritance tree can be collapsed and expanded. A variety of 
tools are available to help you navigate your C++ source. Double-click on the table class. 

7. Double-click on the function top_ and_ f our_ legs () to see the details on this function. 

8. Select the variable tabletop, pull down the Detail menu, and select the Goto Definition... 
item. The Editor is invoked, loading the file furnitu . cpp which contains the definition of 
top_ and_ four_ legs. 

9. Next we will make some changes to furnitu . cpp in order to change the color of the tabletop. 
Scroll down to line 143 using the keyboard or mouse, or pull down the Edit menu, select Goto 
Line..., and enter 143 

10. Replace the line 

tabletop->rgb(0,255,255); 

with 

tabletop->black(); 

11. Save your changes by clicking on the "Write the current file to disk" icon or selecting Save from 
the File menu. 

12. Shut down the Browser before re-making the project. 

13. Return to the IDE (by clicking on it if it is visible on your screen, or by using Alt-Tab). 

14. Click the "Make all targets in the project" icon to re-make the project. 

Correcting an Error 

An error is encountered during the make and error message(s) appear in the log window. Additional 
information on the error is available by selecting the error, pulling down the Log menu and selecting the 
Help on Message item. 

1. Double-click on the error message 

furnitu.cpp (132): Error! E029: (col 15) symbol 'black' has not been 
declared. 

The offending source file ( furnitu . cpp) is loaded into the Editor and the cursor is 
positioned at the line which caused the error. Apparently, black has not been defined as a color. 

2. Restart the Browser. 

3. Double-click on color in the Inheritance window to see the member functions of the class 
color. Among our choices are blue () , green () , and red () . 
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4. Press the Alt-Tab key combination to return to the Editor and replace the line 

tabletop->black(); 

with 

tabletop->red(); 

5. Save your changes. 

6. Return to the IDE and re-make the project. 

7. Run the program to see the changes you have made to the tabletop. 

Editing a Bitmap 

You can edit bitmaps, icons, or cursors associated with your project using Open Watcom’s Image Editor. 
Double-click on a file with a . bmp, . ico, or . cur extension and the file is loaded into the Image 
Editor. The editor has many features to design your images, including resizing, rotation, shifting, and a 
utility to take a "snapshot" of another image and import it. 



Figure 11. The Open Watcom Image Editor 

Suppose you wanted to change the color of the right-arrow icon in your application. 

1. If the "Folder" icon next to . bmp is closed, click on it to restore all the files with a . bmp 
extension to the file list. 

2. Scroll the window until the file right. bmp is visible. 
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3. Double-click on right. bmp in the draw? ? ? . exe target window. 

4. Select the "Paint Can" icon from the Tool Palette. 

5. Select a color from the Color Palette. 

6. Click on the arrow. 

7. Save your changes using the "Save" icon on the toolbar and exit the Image Editor. 

8. Click the "Make all targets in the project" icon to rebuild the project with the change 
incorporated. 


Editing Menus 

Next, you will add source files to the list of items that make up draw? ? ? . exe . 

1. Pull down the Sources menu and select the New Source... item. 

Note: You can do this either by choosing from the menu bar or by positioning the 

mouse over the file list area and clicking the right mouse button. The IDE 
displays a pop-up menu from which you can choose the desired action. 

2. Enter the filename draw. res (or drawos2 . res for OS/2). For OS/2, click OK when you 
have entered the source file name. For all other systems, click on Add when you have entered 
the source file name and then click on Close. Now we will remove the . rc file from the project 
so that our changes to the . res file will not be overwritten. When an . rc file is present, the 

. res file is generated from the . rc file. 

3. Right click on draw. rc (or drawos2 . rc for OS/2), then select Remove Source from the 
pop-up menu. 

4. Double-click on draw. res (or drawos2 . res). The Resource Editor is invoked, displaying 
all the available resources (in this case, icons, bitmaps, and menus). 
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Figure 12. The Open Watcom Resource Editor 

5. Click on "Menu Resources". 

6. Double-click on "DrawMenu" in the right-hand box. This will bring up the Menu Editor. The 
Menu Editor displays the menus defined for the resource DrawMenu . You can specify pop-up 
menus, menu items and sub-items, text, separators, attributes, break styles, and memory flags. 


The Open Watcom C/C++ Tutorial 27 







































Chapter 3 



Figure 13. The Open Watcom Menu Editor 

7. Click on MENU ITEM " SDimmer" in the item list window. 

8. In the "Item Text" window change the item to SDarker and then click on the "Change" button. 

9. Select Update from the File menu or click on the "Update the file with this menu" icon. 

10. Exit the Menu Editor. 


11. Now, select Save from the File menu or click on the "Save this file" icon and exit the Resource 
Editor. 

12. Click the "Make all targets in the project" icon to re-make the project. 


Sampling and Profiling an Executable 

Together, the Open Watcom Execution Sampler and the Open Watcom Execution Profiler allow you to 
pinpoint the areas of your code that are the most heavily used, indicating possible candidates for 
performance improvements. 

1. Click on the draw? ? ? . exe target. 
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2. Select the Sample item from the Targets menu item, or click on the "Run and sample the current 
target" icon from the toolbar. The Open Watcom Execution Sampler is invoked and your 
application begins to execute. 

3. Try rotating and resizing the image a few times. The sampler takes a "snapshot" of the code that 
is being executed at regular intervals. Exit the application. A samples file with extension . smp 
is created in the current directory. This file is input for the profiler. 

4. You are now ready to profile the executable. Do this by selecting Profile from the Targets 
menu, or by clicking on the "Profile the current target" icon on the toolbar. The profiler scans 
the . smp file and reports the activity in the various modules of the application. The percentage 
of time spent in the modules is indicated as an absolute percentage (percent of total samples) and 
as a relative percentage (percent of samples in the . exe image). 

5. Double-click on the module or routine names to step down to the exact source being executed 
when a sample was taken. For more details, you can adjust the sampling rate of the Sampler to 
get a better picture of your code. To do this, exit the Profiler, pull down the Targets menu, and 
select Target options, then Sample Switches... from the pop-up menus. Specify a sampling rate 
such as 2 (for 2 milliseconds), click on OK, then run the Sampler and Profiler again. 


WATCOM Profiler 


File Convert Windows Actions Help 



Figure 14. The Open Watcom Execution Profiler 


Saving the Project and Terminating the Session 

You can now exit the IDE session by selecting Exit from the File menu. If you have not already saved your 
project, you will be prompted to do so. Choose "Yes" and the session ends. 
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3.3 Tutorial Review 


In this tutorial, you created a project called kitchen. wp j, which was composed of two targets: 
draw? ? ? . exe and button . lib. You compiled and linked it into an executable program using the 
WMAKE utility, the Open Watcom C and C++ compilers, and the Open Watcom Linker. You executed it 
both directly and under the control of the Open Watcom Debugger.. You browsed the source, and made 
changes using the text and resource editors. Finally, you sampled and profiled the application. 

When you saved the project, you created the following permanent files: 

• kitchen. wp j — describes the screen layout and refers to the target files called draw??? . tgt 
and button. tgt. 

• draw??? . tgt — describes the target executable draw? ? ? . exe and all switches required to link 
it. It also describes the . c and . cpp files and switches required to compile them. 

• button. tgt — describes the target library and all switches required to create it. It also describes 
the . c file and the switches used to build the library. 
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4 Documentation 


The following manuals comprise the Open Watcom C/C++ documentation set. When you install the 
software, portions of the documentation set are provided as on-line help files. Subsequent sections describe 
how to access this on-line help. 

The following describes the titles in the Open Watcom C/C++ documentation set. 

Open Watcom C/C++ User’s Guide 

This manual describes how to use Open Watcom C/C++. It contains an introduction to the 
compiler and a tutorial section. It also describes compiler options, precompiled header 
files, libraries, memory models, calling conventions, pragmas, in-line assembly, ROM 
based applications, and environment variables. 

Open Watcom C/C++ Tools User’s Guide 

This manual describes the command line oriented tools including the compile and link 
utility, library manager, object file disassembler, far call optimization tool, assembler, patch 
utility, strip utility, make utility, and touch utility. 

Open Watcom Graphical Tools User’s Guide 

This manual describes Open Watcom’s Windows and OS/2 graphical tools including the 
Integrated Development Environment, Browser, Dr. Watcom, Spy, DDE Spy, Image 
Editor, Resource Editor, Sampler/Profiler, Resource Compiler, Heap Walker, Zoom, and 
Editor. 

Open Watcom C/C++ Programmer’s Guide 

This manual includes 5 major sections each of which describes operating system specific 
development issues. The operating systems covered include extended DOS, OS/2, 
Windows 3.x, Windows NT/2000/XP, Windows 95/98/Me, 32-bit Windows 3.x (using 
Open Watcom’s Supervisor technology) and Novell NLMs. Topics include creating a 
sample program, operating system specific error messages, and debugging techniques. 

Open Watcom C Language Reference 

This manual describes the ISO C programming language and extensions which are 
supported by Open Watcom C. 

Open Watcom C Library Reference 

This manual describe the C and graphics libraries supported by Open Watcom C/C++. 

Open Watcom C++ Class Library Reference 

This manual provides a comprehensive reference to the C++ class libraries provided with 
Open Watcom C/C++. 

Open Watcom Debugger User’s Guide 

This manual describes the Open Watcom Debugger and discusses advanced debugging 
techniques. 

Open Watcom Linker User’s Guide 

This manual describes how to use the Open Watcom Linker to generate executables for 
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target systems such as extended DOS, Windows 3.x, Windows 95/98/Me, Windows 
NT/2000/XP, OS/2, and Novell NLMs. 

4.1 Accessing On-line Documentation 

The following sections describe how to access the on-line help that is available for DOS, Windows and 
OS/2. 

On-line Documentation under DOS 

The Open Watcom Help program, WHELP , may be used under DOS to access on-line documentation. The 
Open Watcom Help command line syntax is: 

WHELP help_ file [topic_name] 

Notes: 

1. If helpjile is specified without an extension then ".IHP" is assumed. 

2. The topic_name parameter is optional. 

3. If topic_name is not specified, the default topic is "Table of Contents". 

4. If topic_name contains spaces then it must be enclosed in quotes. 

The following help files are available: 

CGUIDE Open Watcom C/C++ User’s Guide (excludes C and C++ Diagnostic Messages appendices 
which are available as separate help files) 

CLIB Open Watcom C Library Reference 

CLR Open Watcom C Language Reference 

CMIX Open Watcom C/C++ Master Index 

CPPLIB Open Watcom C++ Class Library Reference 

LGUIDE Open Watcom Linker User’s Guide 

PGUIDE Open Watcom C/C++ Programmer’s Guide 

C_README Open Watcom C/C++ Getting Started manual 

RESCOMP Documentation for the Open Watcom Resource Compiler (excerpt from the Open Watcom 
Graphical Tools User’s Guide) 

TOOLS Open Watcom C/C++ Tools User’s Guide 

WD Open Watcom Debugger User’s Guide 


32 Accessing On-line Documentation 




Documentation 


WPROF Documentation for the Open Watcom Execution Sampler and Open Watcom Execution 

Profiler (excerpt from the Open Watcom Graphical Tools User’s Guide) 

WCCERRS Documentation for the Open Watcom C Diagnostic Messages (excerpt from the Open 
Watcom C/C++ User’s Guide). 

WPPERRS Documentation for the Open Watcom C++ Diagnostic Messages (excerpt from the Open 
Watcom C/C++ User’s Guide). 

On-line Documentation under Windows 

On-line documentation is presented in the form of Windows Help files (".HLP" files). When the software 
is installed under Windows 3.x, Windows 95/98/Me or Windows NT/2000/XP, a number of program 
groups are created. You can access the on-line document by opening a program group and double-clicking 
on a help icon. 

Open Watcom C/C++ Group 

Getting Started Open Watcom C/C++ Getting Started 

Open Watcom C/C++ Tools Help Group 

Accelerator Editor Help Documentation for the Accelerator Editor (excerpt from the Open Watcom 

Graphical Tools User’s Guide) 

C Error Messages Documentation for the Open Watcom C Diagnostic Messages (excerpt from the 

Open Watcom C/C++ User’s Guide) 

C++ Error Messages Documentation for the Open Watcom C++ Diagnostic Messages (excerpt from 
the Open Watcom C/C++ User’s Guide) 

C Language Reference Open Watcom C Language Reference 

C Library Reference Open Watcom C Library Reference 

C++ Library Reference Open Watcom C++ Class Library Reference 

C/C++ Master Index The master index for all of the Open Watcom C/C++ on-line help 

DDE Spy Help Documentation for the DDE Spy utility (excerpt from the Open Watcom 

Graphical Tools User’s Guide) 

Debugger Help Open Watcom Debugger User’s Guide 

Dialog Editor Help Documentation for the Dialogue Editor (excerpt from the Open Watcom 

Graphical Tools User’s Guide) 

Dr. Watcom Help Documentation for Dr. Watcom (excerpt from the Open Watcom Graphical 

Tools User’s Guide) 

Editor Help Documentation for the Open Watcom Editor (excerpt from the Open Watcom 

Graphical Tools User’s Guide) 
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Heap Walker Help 

Documentation for the Heap Walker utility (excerpt from the Open Watcom 
Graphical Tools User’s Guide) 

IDE Help 

Documentation for the Interactive Development Environment (excerpt from the 
Open Watcom Graphical Tools User’s Guide) 

Image Editor Help 

Documentation for the Image Editor (excerpt from the Open Watcom Graphical 
Tools User’s Guide) 

Linker Guide 

Open Watcom Linker User’s Guide 

Menu Editor Help 

Documentation for the Menu Editor (excerpt from the Open Watcom Graphical 
Tools User’s Guide) 

Profiler Help 

Documentation for the Open Watcom Execution Sampler and Open Watcom 
Execution Profiler (excerpt from the Open Watcom Graphical Tools User’s 


Guide) 


Programmer’s Guide 

Open Watcom C/C++ Programmer’s Guide 

Resource Compiler Help 

Documentation for the Resource Compiler (excerpt from the Open Watcom 
Graphical Tools User’s Guide) 

Resource Editor Help 

Documentation for the Resource Editor (excerpt from the Open Watcom 
Graphical Tools User’s Guide) 

Source Browser Help 

Documentation for the Browser (excerpt from the Open Watcom Graphical 
Tools User’s Guide) 

Spy Help 

Documentation for the Spy utility (excerpt from the Open Watcom Graphical 
Tools User’s Guide) 

String Editor Help 

Documentation for the String Editor (excerpt from the Open Watcom Graphical 
Tools User’s Guide) 

Tools Guide 

Open Watcom C/C++ Tools User’s Guide 

User’s Guide 

Open Watcom C/C++ User’s Guide (excludes C and C++ Diagnostic Messages 
appendices which are available as separate help files) 

Zoom Help 

Documentation for the Zoom utility (excerpt from the Open Watcom Graphical 
Tools User’s Guide) 


On-line Documentation under OS/2 

On-line documentation is presented in the form of OS/2 Information files (".INF" files). When the software 
is installed under OS/2, the Open Watcom C/C++ folder is created. You can access the on-line document 
by opening the Open Watcom C/C++ folder and double-clicking on a help icon. 


34 


Accessing On-line Documentation 




Documentation 


C Error Messages 

C++ Error Messages 

C Language Reference 
C Library Reference 
C++ Library Reference 
C/C++ Master Index 
Debugger Help 
Getting Started 
IDE Help 

Profiler Help 

Programmer’s Guide 
Source Browser Help 

Tools Guide 
User’s Guide 


Documentation for the C Diagnostic Messages (excerpt from the Open Watcom 
C/C++ User’s Guide) 

Documentation for the C++ Diagnostic Messages (excerpt from the Open 
Watcom C/C++ User’s Guide) 

Open Watcom C Language Reference 

Open Watcom C Library Reference 

Open Watcom C++ Class Library Reference 

The master index for all of the Open Watcom C/C++ on-line help 

Open Watcom Debugger User’s Guide 

Open Watcom C/C++ Getting Started 

Documentation for the Interactive Development Environment (excerpt from the 
Open Watcom Graphical Tools User’s Guide) 

Documentation for the Open Watcom Execution Sampler and Open Watcom 
Execution Profiler (excerpt from the Open Watcom Graphical Tools User’s 
Guide) 

Open Watcom C/C++ Programmer’s Guide 

Documentation for the Open Watcom Browser (excerpt from the Open Watcom 
Graphical Tools User’s Guide) 

Open Watcom C/C++ Tools User’s Guide 

Open Watcom C/C++ User’s Guide (excludes C and C++ Diagnostic Messages 
appendices which are available as separate help files) 


Accessing On-line Documentation 35 




Chapter 4 


36 Accessing On-line Documentation 




5 Benchmarking Hints 


The Open Watcom C/C++ compiler contains many options for controlling the code to be produced. It is 
impossible to have a certain set of compiler options that will produce the absolute fastest execution times 
for all possible applications. With that said, we will list the compiler options that we think will give the 
best execution times for most applications. You may have to experiment with different options to see 
which combination of options generates the fastest code for your particular application. 

The recommended options for generating the fastest 16-bit Intel code are: 

Pentium Pro -onatx -oh -oi+ -ei -zp8 -6 -fpi87 -fp6 

Pentium -onatx -oh -oi+ -ei -zp8 -5 -fpi87 -fp5 

486 -onatx -oh -oi+ -ei -zp8 -4 -fpi87 -fp3 

386 -onatx -oh -oi+ -ei -zp8 -3 -fpi87 -fp3 

286 -onatx -oh -oi+ -ei -zp8 -2 -fpi87 -fp2 

186 -onatx -oh -oi+ -ei -zp8 -1 -fpi87 

8086 -onatx -oh -oi+ -ei -zp8 -0 -fpi87 

The recommended options for generating the fastest 32-bit Intel code are: 

Pentium Pro -onatx -oh -oi+ -ei -zp8 -6 -fp6 

Pentium -onatx -oh -oi+ -ei -zp8 -5 -fp5 

486 -onatx -oh -oi+ -ei -zp8 -4 -fp3 

386 -onatx -oh -oi+ -ei -zp8 -3 -fp3 

The "oi+" option is for C++ only. Under some circumstances, the "ob" and "ol+" optimizations may also 
give better performance with 32-bit Intel code. 

Option "on" causes the compiler to replace floating-point divisions with multiplications by the reciprocal. 
This generates faster code (multiplication is faster than division), but the result may not be the same 
because the reciprocal may not be exactly representable. 

Option "oe" causes small user written functions to be expanded in-line rather than generating a call to the 
function. Expanding functions in-line can further expose other optimizations that couldn't otherwise be 
detected if a call was generated to the function. 

Option "oa" causes the compiler to relax alias checking. 
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Option "ot" must be specified to cause the code generator to select code sequences which are faster without 
any regard to the size of the code. The default is to select code sequences which strike a balance between 
size and speed. 

Option "ox" is equivalent to "obmiler" and "s" which causes the compiler/code generator to do branch 
prediction ("ob"), generate 387 instructions in-line for math functions such as sin, cos, sqrt ("om"), expand 
intrinsic functions in-line ("oi"), perform loop optimizations ("ol"), expand small user functions in-line 
("oe"), reorder instructions to avoid pipeline stalls ("or"), and to not generate any stack overflow checking 
("s"). Option "or" is very important for generating fast code for the Pentium and Pentium Pro processors. 

Option "oh" causes the compiler to attempt repeated optimizations (which can result in longer compiles but 
more optimal code). 

Option "oi+" causes the C++ compiler to expand intrinsic functions in-line (just like "oi") but also sets the 
inline_depth to its maximum (255). By default, inline_depth is 3. The inline_depth can also be changed by 
using the C++ inline_ depth pragma. 

Option "ei" causes the compiler to allocate at least an "int" for all enumerated types. 

Option "zp8" causes all data to be aligned on 8 byte boundaries. The default is "zp2" for the 16-bit 
compiler and "zp8" for 32-bit compiler. If, for example, "zpl" packing was specified then this would pack 
all data which would reduce the amount of data memory required but would require extra clock cycles to 
access data that is not on an appropriate boundary. 

Options "0", "1", "2", "3", "4", "5" and "6" emit Intel code sequences optimized for processor-specific 
instruction set features and timings. For 16-bit Intel applications, the use of these options may limit the 
range of systems on which the application will run but there are execution performance improvements. 

Options "fp2", "fp3", "fp5" and "fp6" emit Intel floating-point operations targetted at specific features of 
the math coprocessor in the Intel series. For 16-bit Intel applications, the use of these options may limit the 
range of systems on which the application will run but there are execution performance improvements. 

Option "fpi87" causes in-line Intel 80x87 numeric data processor instructions to be generated into the 
object code for floating-point operations. Floating-point instruction emulation is not included so as to 
obtain the best floating-point performance in 16-bit Intel applications. 

For 32-bit Intel applications, the use of the "fp5" option will give good performance on the Intel Pentium 
but less than optimal performance on the 386 and 486. The use of the "5" option will give good 
performance on the Pentium and minimal, if any, impact on the 386 and 486. Thus, the following set of 
options gives good overall performance for the 386, 486 and Pentium processors. 

-onatx -oh -oi+ -ei -zp8 -5 -fp3 
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6 Release Notes for Open Watcom C/C++ 2.0 


There are a number of enhancements and changes in this new version of Open Watcom C/C++. The 
following sections outline most of the major changes. You should consult the User’s Guide for full details 
on these and other changes made to the compiler and related tools. You should check the next section to 
determine if you need to recompile your application. 

6.1 Differences from Open Watcom version 1.9 

Following is a list of changes made in Open Watcom C/C++ 2.0: 

• OW tools were ported to 64-bit host platform (Linux and Windows) 

6.2 Differences from Open Watcom version 1.8 

Following is a list of changes made in Open Watcom C/C++ 1.9: 

• The NULL macro is now defined as ((void *)0) for C; for C++, NULL is still defined as 0 or 0L as 
previously. This change may require modifications to user code if NULL was incorrectly used as an 
integer constant. Note: The 16-bit windows.h header defines NULL as 0; for 16-bit Windows 
programming, the effective definition of NULL depends on whether windows.h or one of the 
standard C headers is included first. 

• The C compiler has improved handling of the _Bool type (C99 mode specific). The _Bool type can 
now generally be used in expressions wherever an integer may be used. 

• The C compiler now considers enumeration types to be compatible with their underlying integer 
type, as required by ISO C. Note that the choice of the underlying type varies and should not be 
relied upon. 

• The C compiler now correctly handles initialization of static floating-point variables with 64-bit 
integer constants. 

• The C and C++ compilers now support the_int8,_intl6, and_int32 extension keywords. 

• The 16-bit C and C++ compilers now allow the :> operator to be used in initializers of variables with 
static storage, as long as both operands are integer constants. This enables the use of MK_FP macro 
in initializers. 

• The C++ compiler now treats warning W737, implicit conversion of pointers to integral types of 
same size, as an error. 

• The C++ compiler now supports several new warnings: W931, warn about meaningless cv-qualifier 
in casts; W932, warn about meaningless cv-qualifier in function return types; and W933, warn about 


Differences from Open Watcom version 1.8 39 





Chapter 6 


use of C-style casts in C++ code. These warnings must be explicitly enabled through the -wee 
option. 

• The code generator now eliminates redundant epilogue code for 32-bit Intel processors when doing 
size optimization. 

• The code generator correctly handles constant folding of signed 64-bit integer division and right 
shift operations. 

• The code generator now supports constant folding of 64-bit integer modulo operations. 

• The code generator no longer mishandles floating-point comparisons where one operand is a 
variable of type float and the other operand is a constant of type double or long double. 

• The code generator no longer produces incorrect code when a constant expression of type float (e.g., 
l.Of + 1 .Of) is passed as an argument to a function which takes a float argument. 

• The code generator now makes more accurate decision when choosing whether a multiplication by a 
constant should be replaced by a sequence of shifts and additions. Results depend on target CPU 
type. 

• The 386 code generator now produces a CDQ instruction except when targeting a Pentium and 
optimizing for speed, when a MOV/SAR sequence is emitted as previously when converting a signed 
32-bit integer to 64-bit. 

• The code generator no longer emits redundant CS segment overrides when creating calls to symbols 
imported from DLLs. 

• The Win32 API headers and import libraries have been updated to support the new interfaces in 
Windows 7. 

• Support for 16-bit OLE 2.0 has been added. 

• Support for RDOS targets has been added. 

• Support for ZDOS targets has been added to the linker. 

• The floating-point exception handler for 16-bit DOS no longer crashes if the user signal handler 
modified DS. 

• The _floodfill() graphics library function now works correctly again. 

• The library no longer leaks memory when a thread created by _beginthread() terminates. 

• The %Lf format specifier (and related format specifiers) used with printf family functions now 
works. 

• The library now contains _fseeki64 and _ftelli64 functions to handle 64-bit file offset pointer for 
streams. 

• The library implementations of _lseeki64, _telli64, _fileleni64, _(w)stati64, _(w)findfirsti64, 
_(w)findnexti64 on OS/2 now properly use 64-bit file sizes and offsets. 

• The library implementations of puts and putws now correctly return EOF if they fail 
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• DOS long file name (LFN) support has been added (new doslfn??.lib model specific libraries contain 
DOS LFN version of appropriate modules). By default DOS LFN support is enabled. It can be 
switch off by setup LFN=N environment variable. 

• The wasm assembler now implements support for Turbo Assembler compatible IDEAL mode. The 
-zcm option may be used to select this feature. 

• The assembler now supports built-in @code and @data symbols. 

• The assembler now supports ELSEIF directives for conditional assembly. 

• The assembler no longer incorrectly assumes that absolute segments are byte aligned; they are 
paragraph (16 byte) aligned. 

• The built-in cd command in wmake now supports quoted paths with spaces. 

• The linker now supports libraries in BSD, COFF, and GNU ar format. 

• The linker now allows stack sizes smaller than 512 bytes to be specified and does not silently 
override them. However, a new warning (W1172) will be emitted in such case. 

• A FULLHEADER option specific to the DOS EXE format has been added to the linker. Please see 
the Linker Guide for further information. 

• The library manager (wlib) now supports BSD, COFF, and GNU variants of the ar library archive 
format. Extended -fab, -fag, -fac options select the variant. The -fa option now selects default 
format depending on host platform. 

• This release introduces Open Watcom’s IPF compiler (wipfc) used for creating help files on OS/2. 

• Documentation is now provided in Windows CHM format as an option. 

• The vi editor now supports non-ASCII characters in the 0x80-0xFF range. 

• The console version of the vi editor for Windows now uses standard Windows keyboard processing; 
AltGr and dead keys now function correctly. Additionally, Caps Lock is only effective for keys 
which generate characters. 

• The editor now supports for syntax highlight of awk files. 

• The editor now supports a Select All command. 

• The windowed editor now holds the position of the replace and search/replace dialogs between 
invocations. 

• The wcl and wcl386 utilities now work correctly on a Linux host. 

• The DOS NetBIOS trap file and debug server have been modified to work when running on 
Windows NT (through NTVDM). 

• The 16-bit Windows GUI tools no longer require CTL3DV2.DLL, but still use it if the library is 
present. 
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6.3 Differences from Open Watcom Version 1.7 

Following is a list of changes made in Open Watcom C/C++ 1.8: 

• The C compiler now performs stricter type checking on enumerated types. Previously, enums were 
treated as their underlying type (signed/unsigned char, int, etc.) for type checks. 

• The C compiler now adds location information about enumerated symbols in appropriate 
diagnostics. 

• The C compiler has been improved with respect to the handling of near/far pointers, especially when 
converting or comparing pointers and integers of different sizes. 

• The C compiler now properly recognizes functions that do not return, such as long) mp(), and 
correctly diagnoses control flow issues such as unreachable code or missing return statements. 

• The C compiler now supports a #pragma alias. This pragma emits alias records into the object file 
for processing by the linker. 

• The C compiler now has larger capacity and can compile some complex source files that previously 
caused out of memory errors (E1064). 

• The C compiler now always warns about unprototyped functions (W131). Previously, some 
forgivable instances of missing prototypes were undiagnosed by default, which caused users to write 
non-portable code usually by accident. 

• Warning W139 (Divisor for modulo or division operation is zero) has been added to the C compiler. 
This warning is triggered whenever the right operand of an integer division or modulo operation is a 
constant expression with the value of zero. 

• The handling of pragma aux is now correct in cases where code is emitted and a function body 
already exists for the corresponding symbolic name. 

• Various fixes to the handling of the include_alias pragma have been made. 

• The C and C++ compilers now have diagnostics for meaningless comparison of 64-bit and bit-field 
operands. 

• The C and C++ compilers now have conversion tables from CP= 1250,1252 (Latin-2,1 for Windows 
ANSI) to Unicode to support Windows programming. 

• The C++ compiler now supports the explicit specification of function template arguments. For 
example: f<T>(). 

• The C++ compiler now uses lazy instantiation for class templates and template members. Only the 
members actually used are instantiated. 

• The C++ compiler now allows member templates to be defined outside their class. 

• Numerous bugs in the C++ compiler have been fixed. 

• The C++ compiler allows a class declaration with modifiers to have those modifiers propagate into 
the class definition. 
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• When -SH switch is used with the Fortran compiler, the default size of an integer constant is now 
INTEGER*2. 

• The Fortran compiler no longer crashes when equivalencing common/global with automatics. 

• Fortran processing for the text record EOL has been normalized. On UNIX systems write/seek uses 
LF and read uses LF or CRLF. On non-UNIX systems write/seek uses CRLF and read uses FF or 
CRLF. 

• Various code generation bug fixes to both the 16-bit and 32-bit compilers have been made. 

• The Win32 headers and libraries are now Open Watcom’s own internal version. The MinGW 
headers and libraries are no longer being used. The new headers and libraries provider greater 
compatibility with the Microsoft SDK and better support for Microsoft Vista. 

• The version of Causeway in the official distribution is now version 4.03. 

• The Finux run time libraries now have recvfrom() and sendto() implementations. 

• A POSIX compatible fnmatchO function and a corresponding fnmatch.h header has been added. 

• The _dos_getfileattr() function no longer crashes in large data models on 16-bit DOS and Windows. 

• The C run time library now has implementations of the following functions to improve compatibility 
with other compilers: _chmod, _chsize, _creat, _dup2, _eof, _filelength, _isatty, _read, _sopen, _tell, 
_umask, _unlink, and _write. 

• The date and time arguments to _dos_getftime() and _dos_setftime() are now using ’unsigned int' 
type instead of ’unsigned short’. This change has been made to improve compatibility with other 
compilers. 

• The segment argument used with _dos_allocmem(), _dos_freemem() and _dos_setblock() is now 
unsigned int instead of unsigned short. This change was made for compatibility with other 
compilers. 

• The Fortran run time environment now works on Linux. 

• The Linux Fortran run time libraries now have FSYSTEM and FSPAWN implementations. 

• The Fortran run time now exposes the saved stack pointer for when crashes occur in the IO 
subsystems. 

• The debugger’s options context menu now has an option to allow all child nodes to be expanded 
recursively. 

• The debugger now uses the full size of the type when displaying hexadecimal values (for example 
0x03 instead of 0x3). 

• The debugger now has a new menu entry to change the display format of all values in an array (all 
hex or all decimal). 

• The debugger now supports break on write rather than just break on change. The trap must support 
exact breakpoints for this to happen. 
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• The Windows debugger now properly handles quoted program names. 

• The Windows debugger now has proper color support. 

• The NetWare TCP server and trap have been updated for NW6.5SP7 with the latest libcpre.obj file. 

• The DOS real-mode trap file (std.trp) now correctly displays high parts of 32-bit registers on 386+ 
CPUs. Previously, the high parts were always displayed as zeros. 

• WLIB now has a new -pa option to set up library page size automatically to optimal size. 

• WLIB now handles COFF import libraries more correctly. 

• WCL now properly handles the -fd and -fm options without the file name specified. 

• WASM now handles EXTERNDEF directives properly; an EXTDEF record is created only if the 
symbol is actually referenced. 

• WASM now handles the auto-dependency filename properly. 

• WASM now implicitly creates the_UNIX_macro for the BSD target as it has for LINUX and 

QNX. 

• The internal version numbers for WASM and WMAKE are now compatible with that used by the C 

and C++ compilers. Specifically the macro_WASM_has the value 1280 for WASM and the 

macro_VERSION_has the value 1280 for WMAKE. 

• The 32-bit DOS WD and WPROF can now be used with DOS/4G 2.x. The DOS4GOPTIONS 
settings are no longer exported. Users may still override the defaults by supplying their own wd.ini 
and wprof.ini, respectively. These files must be in the appropriate format for the DOS/4G version 
used. Note that this does not affect DOS/4GW users. 

• WLINK now handles offsets and groups larger than 64 KB for 32 bit code and 16 bit targets. 

• WLINK now ignores fixup displacement when the target relocation is absolute. This is required for 
compatibility with object files generated by MASM 5.1. 

• WLINK now properly handles the alignment of the last segment in a group if the last segment 
fragment is blank. 

• WLINK can now use the WLINK_LNK environment variable to override the default directive file 
name (wlink.lnk). If the specified file isn’t found then default file is used as usual. 

• WLINK now properly emits segments overlapped by groups to output file. 

• WLINK now properly handles imported symbols that are locally defined with the dllimport specifier 
in PE formatted files. 

• WLINK DLL was renamed from wlink.dll to wlinkd.dll. It requires to correct wmake directive 
"lloaddll" to use this new name if it is used in makefile. 

• WRC on Far-Eastern NT-based systems now honors the DBCS encoding specified on the command 
line. 


44 Differences from Open Watcom Version 1.7 




Release Notes for Open Watcom C/C++ 2.0 


• The text editor now supports syntax highlighting for resource files. 

• The Fgrep dialog box in graphical editor now has a browse button to display the standard browse for 
folder dialog box on versions of Windows that support it. 

• The ide2make utility has been added to the Open Watcom distribution. This utility converts IDE 
project files to make files. 

• The exe2bin utility now performs properly if relocation items are unsorted. 

• The installer now generates a batch file that automatically sets the environment variables used by the 
Open Watcom tools. 

6.4 Changes in 1.8 that may Require Recompilation 

_dos_getftime and _dos_setftime functions 32-bit users of _dos_getftime() and _dos_setftime() need to 
recompile. Consider using stat()/utime() instead of the non-portable functions. 

_dos_allocmem and _dos_freemem functions 32-bit DOS users of _dos_allocmem() and _dos_freemem() 
need to recompile. Consider not using this functions in the first place. 

6.5 Differences from Open Watcom Version 1.6 

Following is a list of changes made in Open Watcom C/C++ 1.7: 

• Functions using the_cdecl calling convention now return floating-point values in FPU registers in 

32-bit code. This is the correct behavior compatible with other compilers. 

• The C and C++ compilers now support an include_alias pragma which can be used, among other 
things, to map long include filenames onto 8.3 names. In addition, the compilers now support a -na 
switch to disable the automatic inclusion of _ialias.h (which contains new include_alias pragmas for 
certain standard headers). 

• The C compiler now emits warnings on operations which mix multi-level pointer types such as 
void** and int**. Previously a warning was only emitted in ANSI mode. Note that while void** is 
not assignment compatible with int**, void* is. The new stricter behavior is in line with most other 
C compilers and helps users write cleaner and more portable code. 

• The C compiler now warns (W400) when an expression of plain char type is used as array index. 
Because the sign of plain char changes depending on compiler choice and settings, using plain char 
as array index is inherently non-portable and likely to cause problems. 

• The C compiler now folds constant expression before checking for range overflows etc. This 
enables the compiler to diagnose constant out of range issues in more cases. 

• The C compiler now allows benign variable redefinitions where_near or_far modifiers aren’t 

always explicitly specified but match when current data model is taken into account (eg. ’extern int 

_near x;’ and ’extern int x;’ in small data models). The new behavior is compatible with the C++ 

compiler as well as with other vendors’ compilers. 
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• The default stack size for 32-bit DOS extended executables has been increased from 4K to 64K. 

Note that the linker can still set greater or smaller stack size. 

• The code generator now produces better 16-bit code for 64-bit math operations 

• The code generator no longer incorrectly optimizes out conditionals. The problem only occurred in 
very rare situations and probably only when doubles were being compared. 

• A long-standing problem with use of certain 64-bit constants as results of ternary operators has been 
fixed. 

• The C++ compilers now has a workaround for bugzilla bug #63 

(http://bugzilla.openwatcom.org/show_bug-cgi?id=63). The compiler now generates an error 
message referring to the bug entry rather than crashing. 

• The LIBC and CLIB thin netware libraries have been added to the distribution as experimental. 

• 32-bit DOS executables now correctly pass environment to child processes started through the 
spawn family of functions. Previous incorrect behavior was introduced in version 1.6. 

• In the NetWare libraries,_get_stdout with_get_std_stream was causing an infinite recursion. 

This has been fixed. 

• Fixed 8087 emulator/mathlib 80-bit real multiplication if one operator is zero and second is a power 
of two. 

• The _outgtext() function in graph.lib no longer fails on 32-bit targets. 

• The Win32 stat() function now returns correct results when it tries to access a file with given name 
and the directory containing that file also contained a subdirectory with the same name. 

• The debugger now supports a "No Source" toggle (right mouse click menu) in the assembly code 
window to switch on/off associated source code. 

• The debugger no longer crashes when tracing F77 programs that use variable-size arrays. This only 
applies to DWARF debugging information (which is used by default). 

• The debugger now correctly displays multi-dimensional Fortran arrays when DWARF debug 
information format is used (which is used by default). 

• The debugger can now display [partial] strings in Fortran code when the string length exceeds the 
debugger’s internal limit. The internal limit has also been increased from 512 to 1024 characters. 

• The resource compiler now properly copies non-resident name table when processing LX 
executables. 

• The console version of vi for Win32 no longer quits after Ctrl+Left is pressed followed by any other 
key. 

• WCL now correctly takes options from the environment when there is more then one file to compile. 

• The linker now supports a MIXED1632 option to allow mixing of 16- and 32-bit logical segments 
into a single physical segment in OS/2 LX/LE executables. 
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• The linker now supports a NOSTUB option for Windows and OS/2 executable formats. This option 
causes no DOS stub executable to be written to the output image. 

• The installer now allows you to disable creating program groups or modifying the startup 
environment using the /np and /ns switches. 

6.6 Changes in 1.7 that may Require Recompilation 

_ cdecl Calling Convention Functions in 32-bit code that return floating-point values now do so using the 

FPU registers. Such functions will need to be recompiled if they are to be linked with 
object code produced by Open Watcom C/C++ 1.7. 

6.7 Differences from Open Watcom Version 1.5 

Following is a list of changes made in Open Watcom C/C++ 1.6: 

• The C compiler has been modified to use the underlying bit-field type and not signed/unsigned int as 
the type of operand which is a bit-field. This is consistent with the C++ compiler and fixes some 
problems when bit-fields larger than int are used. 

• Processing of #pragma aux has been corrected in the C compiler. This fixes problems when using 
the mmintrin.h header, among others. 

• The C compiler now accepts_declspec modifiers specifying calling conventions applied to 

variables, not just functions. The new behavior is consistent with the C++ compiler, and also with 
the fact that ordinary calling convention type modifiers can be used with variables. 

• The C and C++ compilers have been fixed to properly declare variable names based on calling 
convention specifiers. This fixes problems with building code using IBM SOM. Note that the 
current behavior is the same as in Open Watcom 1.3 and earlier. 

• The C compiler’s preprocessor has been modified to allow use of macros with large number of 
arguments (255 or more). 

• The C compiler no longer generates internal errors when options -ri and -oe are specified at the same 
time. 

• The C++ compiler has been fixed to inline intrinsic functions. 

• The 386 compilers have been changed to default to tuning code for P6 architecture instead of 
Pentium. Optimizing for P6 typically results in slightly more compact and faster code. 

• The 386 C compiler has been fixed to properly convert between flat and_farl6 pointers, especially 

pointers to functions. Its behavior should now be compatible with the C++ compiler. The problem 
was most likely affecting OS/2 users who wrote mixed 16-bit and 32-bit code. 

• The C compiler has been changed to allow redeclaration of functions in rare cases where initial 
declaration did not specify a calling convention and the subsequent declaration specified a calling 
convention which matched the default. 
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• A new -zwf switch has been added to the C and C++ compilers. This switch is off by default and 
enables generation of FWAIT instructions on 386 and later CPUs. It is only needed in unusual 
situations. 

• The C compiler now correctly converts 64-bit integer constants to floating-point constants. 

• The code generator no longer merges memory accesses when volatile variables are involved. 

• The code generator now correctly const folds 64-bit right shifts. 

• The code generator now properly converts between far pointers and 64-bit integers. Attempts to 
convert a 48-bit far pointer to 64-bit integer no longer cause a crash. 

• The code generator has been modified to slightly decrease code size when optimizing for size (-os). 

• The non-standard alloca.h header has been added for compatibility with other compilers. 

• The strftimeO library function has been extended to support date formats introduced in C99. 

• The file pointer type used with lseek() and tell() has been changed to off_t (from long) for 
compatibility with POSIX. 

• The 386 versions of _clear87() and _status87() functions have been modified to use the no-wait form 
of FPU control instructions. This allows these functions to be used in exception handlers when there 
are pending unmasked floating-point exceptions. 

• The 16-bit 8087 emulator has been fixed to correctly evaluate multiplies as infinity instead of zero in 
rare overflow situations. 

• The resource compiler (wrc) has been fixed to store long integer constants as 32-bit quantities in 
RCDATA or user data resource statements. This behavior applies to Winl6, Win32, and OS/2 
targets. Integers without the ’L’ suffix are stored as 16-bit and potentially truncated. 

• The OS/2 specific part of the resource compiler has been corrected to process RCDATA statements 
properly. 

• The assembler (wasm) now supports external absolute symbols. The SIZE, SIZEOF, LENGTH, and 
LENGTHOF operators have been corrected for structures. 

• Classification of privileged instructions in the assembler has been updated to match MASM. 

• The assembler now evaluates expressions in return instructions correctly. Previously, code such as 
’ret 28+4’ would be sometimes erroneously assembled as ’ret 28’ instead of ’ret 32’. 

• The linker has been changed to only recognize segments of class ’STACK’ as stack segment. 
Previously, any segment with class name ending with 'STACK' (eg. ’FSTACK’) was recognized. 

• Several minor problems related to creating DOS executables have been fixed in the linker. 

• The RUNTIME linker directive has been extended to allow ELF ABI type and version specification. 
This functionality is similar to the brandelf utility. See the Linker Guide for details. 
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• The wmake utility has been modified such that in native wmake mode, a symbolic target with no 
command list is always considered to have had its command list executed. That will cause any 
targets that are dependent on this symbolic target to be considered out of date. 

• The Win32 trap file is now able to determine the full pathname of debuggee’s loaded DLLs. This 
may ease debugging in some cases as the debugger will be more likely to find debugging information 
for DLLs. 

• The Winl6 debugger trap file (std.dll) has been modified to allow 16-bit wdw to run on Windows 
NT platforms without reporting a spurious error message on exit. 

• Numerous problems with the Win386 extender support have been fixed so that Win386 now works 
again. 

• The dmpobj utility has been enhanced to support additional OMF records, and new command line 
options have been added. 

6.8 Differences from Open Watcom Version 1.4 

Following is a list of changes made in Open Watcom C/C++ 1.5: 

• Support for ISO/IEC TR 24731, "Extensions to the C Library, Part I: Bounds-checking interfaces" 
has been added to the C runtime library. The C compiler now predefines the macro 

_STDC_LIB_EXT1_(which evaluates to 200509L) to indicate this support. This set of functions 

is also known as the Safer C Library. Please see the C Library Reference for detailed documentation 
of these functions. 

• In C99 mode, the C compiler now supports C99 style declarations intermixed with statements within 
a block, as well as declarations in the opening clause of a for loop. 

• The C compiler now predefines additional macros required by the C standards. These include 

_STDC_HOSTED_(evaluates to 1) to indicate a hosted implementation and 

_STDC_VERSION_(either 199409L or 199901L) to indicate C94 or C99 support depending on 

compilation switches. 

• A_restrict keyword has been added to the C compiler. It is functionally equivalent to the C99 

’restrict' keyword but is always visible, even in non-C99 mode. 

• In C99 mode, the C compiler no longer requires explicit return statement in a main function 
returning an integer. In accordance with C99 standard, ’return 0;’ is implied if end of function is 
reached and no return statement was encountered. 

• The C compiler has been fixed so that it no longer loses track of pointer base when using 

_based(_self) pointers. The C compiler has also been fixed to properly handle dereferencing of 

based arrays. 

• The 16-bit C++ compiler now correctly casts pointers to_segment type without crashing. Proper 

semantics of the cast were implemented. 

• The 16-bit C compiler has also been modified to handle casts to_segment type correctly, ie. return 

segment portion of a pointer. 
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• The C compiler has been fixed to properly support named based segments (ie. _based!_segname( 

<name> )) pointers) that reference the default _DATA and _CONST segments. 

• The compilers and library headers have been modified to properly support use of standard libraries 
when one of the -ec switches is used to change default calling convention. 

• The C compiler has been modified such that segments created through #pragma data_seg are no 
longer part of DGROUP. Typically, the pragma is used only when data segments need to be located 
in a physically separate segment in the output module. 

• New warning W137, "Extern function ’fn’ redeclared as static", has been added to the C compiler. 
Existing error E1072, "Storage class disagrees with previous definition of ’symbol’" has been 
extended to cover redefinitions from ’extern’ to ’static’ and not only from ’static’ to ’extern’. 
Changing the linkage of a symbol invokes undefined behavior according to ISO C. 

• New warning W138, "No newline at end of file", has been added to the C compiler. It is emitted if 
no line terminator character was found before the end of a source file. Such files do not conform to 
ISO C. The missing newline character will be automatically inserted; this matches the C++ compiler 
behavior. Note that missing newlines could previously lead to spurious "#endif matches #if in 
different source file" warnings. 

• The C compiler has been modified to allow the_export or_declspec(dllexport) modifier on a 

declaration when earlier declaration exists with no modifier. The updated behavior is compatible 
with the C++ compiler as well as some compilers from other vendors. 

• In ISO/ANSI mode (-za), the compiler now always warns if it encounters a call to unprototyped 
function. In extensions mode (default, -ze), this warning (W131) is suppressed if a matching 
prototype is found later in the source file. Note that the behavior in extensions mode is unchanged 
from earlier versions. 

• The C compiler now eliminates static functions that are always inlined from the object file (the 
functions are of course still emitted if their address is taken). 

• The C compiler has been fixed to properly evaluate boolean expressions (especially the ternary 
operator) where the condition is a 64-bit integer constant. Previously, the high 32 bits were in some 
cases ignored, which could lead to erroneous results. 

• The C compiler has been modified to properly cast floating-point constants to the specified type. 
Notably FLT_MIN stored or passed as double is now handled correctly (without spurious precision). 

• Handling of empty macro arguments has been corrected in the C compiler’s preprocessor. 
Previously, empty macro arguments could result in invalid tokens in certain cases. 

• The peephole optimizer is now run again after register allocation. This allows the code generator to 
take advantage of some optimization opportunities that were previously missed. 

• The code generator has been modified to copy DS into ES in_interrupt routine prolog (right after 

DS was loaded) if the ES register is considered unalterable, ie. in flat model. This may avoid 
crashes if ES is dereferenced explicitly or implicitly in interrupt handlers, for instance when calling 
memcpy(). 

• The linker and other tools have been fixed to correctly classify code segments. Previously, code 
segments could be misclassified as data, which led to incorrect disassembly and generation of 
debugging information. 
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• A performance problem related to emitting debugging information for structures or unions with 
many members has been corrected in the code generator. 

• The POSIX-defined header libgen.h has been implemented. This includes two functions, 
basename() and dirname(). 

• The functions btowc(), fwide(), mbsinit(), wctrans(), and towctrans() have been added to the C 
runtime library. These functions are all related to wide-character and multi-byte support, and were 
first defined by the ISO C Normative Amendment 1. 

• C99 functions llabs(), lldiv(), and _Exit() have been added to the C runtime library. Note that the 
latter is equivalent to _exit(), defined by POSIX. 

• Support for C99 floating-point classification macros has been implemented. This includes 
fpclassify, isfinite, isinf, isnan, isnormal, and signbit. 

• Modifiers 'hh\ ’j’, ’z\ and ’t' defined by C99 for the printf and scanf family of functions have been 
implemented in the C runtime library. Please see the C Library Reference for details. 

• The ’F’ modifier for printf and scanf families of functions conflicts with ’F’ format specifier defined 
by ISO C for floating-point conversions. It has been replaced by a ’ W’ modifier which is now used 
to denote a far pointer. The ’F’ modifier is still recognized in DOS builds of the runtime library 
(which therefore cannot handle the ’F’ format specifier as defined by ISO C), but is no longer 
documented and will be removed in a future release. 

• Several very obscure bugs have been fixed in the printf and scanf family of functions. These 
problems were discovered thanks to a more stringent testing procedure and had never been reported 
by users. 

• The strtod function has been enhanced to follow C99 specification. It will now parse infinity and 
NaN, as well as hexadecimal floating-point numbers. See the C Library Reference for details. 

• The math library has been fixed to perform binary to decimal floating-point conversions with greater 
precision. This fixes a problem where in some cases a conversion from binary to decimal and back 
was losing precision or producing erroneous results. 

• The graphics library has been fixed to correctly work with VESA modes where the number of bytes 
per line does not directly correspond to width of the mode in pixels. 

• The owcc utility has been much improved and documented; this tool is a POSIX style compiler 
driver, designed to provide certain level of command line compatibility with gcc and ease porting. 

• The NOEXTension linker option has been documented; this option instructs the linker not to add any 
extension (.exe, .dll, etc.) to the executable name. Any argument to the NAME directive will be used 
verbatim. This option had been supported by earlier versions of the linker but not documented. 

• The ’include’ preprocessor directive not prefixed by an exclamation mark is now recognized in 
wmake -ms mode for compatibility with Microsoft and IBM NMAKE. 

• The wmake utility has been enhanced to evaluate NMAKE style ’[cmd]’ expressions (ie. shell 
commands) in preprocessor !if directives. This functionality is supported in both wmake and -ms 
mode. 
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• Several problems related to the Watcom debugging information format have been fixed in the linker 
and debugger. Note that the Watcom format is considered obsolete and its use is not recommended. 

• A random but very rare startup failure of Windows based GUI tools (notably wdw) has been fixed. 

6.9 Differences from Open Watcom Version 1.3 

Following is a list of changes made in Open Watcom C/C++ 1.4: 

• Support for C99 designated initializers has been added to the C compiler, for example "struct {int a, 
b;} c = {.a=0, .b=l};". This is also supported for arrays, for example "int a [4] = {[0]=5, [3]=2};". 

• Handling of enumerations has been fixed in the C compiler. In certain cases, the compiler chose the 
wrong type for operations on objects of enumerated types. Enumerated constants up to 64 bits wide 
are now also allowed (including in 16-bit compilers). 

• The C compiler will now warn if the right hand operand of a bitwise shift expression is a constant 
that is either negative or greater than or equal to the bit with of the promoted left operand. The result 
of such operation is not defined by ISO C. The warnings are 'W134: Shift amount negative’ and 
'W135: Shift amount too large’. 

• The C compiler now warns in cases where an unsigned type is compared for <= 0. This is equivalent 
to ’unsigned == 0’ and often indicates that a signed comparison was intended. 

• New_watcall keyword has been added to the C and C++ compilers to designate the default 

Watcom calling convention. 

• New -ec? switches have been added to set the default calling convention. 

• The 16-bit C compiler now defines _M_I86 macro for consistency with the C++ compiler. The new 
macro should be used in preference to the existing M_I86. 

• A number of new keywords have been added to the C compiler; these were previously defined as 

macros: _Cdecl, _Export, _Farl6, _Fastcall, _Pascal,_sycall, _System,_try,_except,_finally, 

_leave. 

• Analogous change has been made to the C++ compiler. The new keywords (and removed 

predefined macros) are: _Cdecl, _Export, _Farl6, _Fastcall,_inline, _Pascal,_syscall, _System. 

• The C++ compiler now handles the "new" template specialization syntax, and partial specialization 
is partially supported (no pun intended). 

• The C++ compiler now correctly handles the situation where control reaches the end of main() 
function without encountering a return statement. In that case, the effect is that of executing "return 
0;". 

• The C++ compiler now properly allows return statements with a void expression in functions that 
return void. 

• 386 C and C++ compilers now support the Microsoft fastcall calling convention, and recognize the 
_fastcall keyword. 
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• The C compiler now recognizes #pragma data_seg and code_seg forms that specify segment and 
class names without enclosing them in parentheses. The new behavior is consistent with other 
compilers. 

• New -fti switch has been added to the C compiler to track #include file opens. This helps diagnose 
include file problems in complex projects. 

• The code generator no longer emits debug information for unreferenced typedefs when -dl+ or -d2 
switch is used. This produces slightly to significantly smaller debug information. Note that behavior 
of -d3 is unchanged. 

• The 386 code generator will no longer select the ’and’ instruction to perform zero extension when 
optimizing for time on the 686 architecture (-6r or -6s switch). The ’movzx’ instruction will always 
be used instead, because it avoids partial register stalls and in certain cases significantly improves 
performance on P6 and newer class CPUs. 

• Support for long long based bitfields has been improved in the code generator. 

• The code generator now properly diagnoses attempts to emit symbol names that overflow the OMF 
limit (255 bytes). 

• Several problems related to loss of segment information in 386 non-flat models have been fixed in 
the code generator. 

• Command line processing has been changed in the Compile and Link utility (wcl). Forward slashes 
now may be used as path separators in file arguments, such that "foo/bar" is now interpreted as 
"foo\bar.c". Note that this does not affect options delimited with forward slashes. 

• Support for raw binary and Intel Hex output has been added to the linker, along with support for 
24-bit segmented addressing architectures (HSH1FT option) and arbitrary class/segment reordering 
(OUTPUT and ORDER directives). See Linker Guide for details. 

• Support for overlays (16-bit DOS) has been reinstated in the linker. A related 
FARCALLS/NOFARCALLS option has been added to the linker. See Linker Guide for details. 

• The linker now correctly processes relocations to symbols in absolute segments. 

• The linker now checks for bitness conflicts (16 vs. 32-bit) when adding segments to a group. 

• The minimum accepted value for linker OBJALIGN option has been changed to 16 bytes 
(previously 512). 

• The linker no longer creates a separate .bss section when linking PE modules. Instead, uninitialized 
data is added at the end of the data section. This creates slightly smaller executables and reduces 
memory usage. 

• The st_name member was removed from struct stat and related structures. This was done for 
consistency across platforms (UNIX has no such field), because the st_name field was almost entirely 
useless (being limited to 13 characters), and for compatibility with Microsoft compilers; the latter 
because struct _wstat and struct _wstati64 are now obsolete and struct _stat/_stati64 can be used for 
wide character stat functions. NB: This change requires recompilation. New object files will not 
work with old libraries and vice versa. 
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• The signalQ function no longer modifies floating-point control word on Win32 and 32-bit OS/2. 
Also, default value for SIGFPE has been changed to SIG_DFL from SIG_IGN on all platforms. 

• The e/E format of printf() family of functions has been changed to format the exponent with 
minimum of two digits (instead of three). This behavior is dictated by C99 and consistent with most 
other compilers. 

• The floating-point to string conversion routines now format values with greater precision. This 
means that floating-point values printed by C and C++ programs may be slightly different from 
earlier versions of the runtime libraries (but more accurate). 

• The sleep() function is now declared in unistd.h and its return type has been changed to unsigned int, 
for compatibility with POSIX. 

• The clock)) function now uses millisecond counters (where available) on DOS and Windows, and is 
no longer susceptible to problems related to TZ changes. 

• The DOS runtime has been tuned to produce smaller executables. 

• C99 functions wmemchrO, wmemcmp(), wmemcpy(), wmemmove(), and wmemset() have been 
added to the C runtime library. 

• A POSIX compatible getoptO function has been added to the C runtime library. 

• A POSIX compatible mkstemp() function has been added to the C runtime library. 

• BSD compatible safe string copy and concatenation functions, strlcpy() and strlcat(), have been 
added. Use of these functions is highly recommended over strncpyO and strncat(), because they are 
safer and much easier to use. 

• New strings.h header has been added for POSIX compatibility, although legacy functions index)) 
and rindex() are not supported. Functions strcasecmp)) and strncasecmp() are also declared in 
string.h for compatibility with other compilers. 

• The C runtime library no longer returns ESP1PE when calling write() on a pipe or device that was 
opened with 0_APPEND flag. The old behavior was not POSIX conforming. 

• Handling of pathnames that include spaces has been improved in the make utility (wmake). 

• The disassembler (wdis) now handles big endian object files on little endian host platforms, and vice 
versa. 

• Support for MIPS R4000 and SPARC V8 instruction sets has been added to the disassembler. 

• New -zz and -zzo option have been added to the assembler (wasm) for backwards compatibility. See 
Tools User’s Guide for details. 

• Default behavior of inline assembler has changed. The CPU optimization level (-4, -5, -6) now 
implies the available instruction set: -5 implies MMX and 3DNowl, -6 also implies 
SSE/SSE2/SSE3. Also note that any CPU setting override now reverts to default at the end of each 
inline assembly block. 

• 16-bit DOS version of the assembler (wasmr) has been added. This version runs on 8086 and above 
and requires less memory than the protected mode version. 
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• The debugger has been changed to look for support files in directories relative to the debugger 
executable’s location. This allows the debugger to be used when no debugger specific environment 
variables have been set. 

• A problem with stepping into code (F8) right after debuggee was loaded has been fixed in the 
debugger. 

• The debugger now looks for debug information in a .sym file when the /DOwnload option was 
specified. Previously it erroneously only looked at the executable if the download option was used. 

• Support for Microsoft/IBM .sym files generated by the MAPSYM utility has been added to the 
debugger and profiler. This is helpful especially with symbol files provided by IBM for OS/2 system 
DLLs; disassembly now shows for instance "call DOS32EXIT" instead of "call 01C74634". 

• The CauseWay trap file no longer incorrectly maps symbol addresses in Targe’ executables (code 
segment > 64K). 

• Interoperability with GNU tools has been improved. The debugger (wd/wdw) should now be able to 
debug GNU-produced executables (with DWARF 2 debug information) and vice versa. 

• New -zld option has been added to the library manager (wlib) to strip autodependency information 
from OMF objects. 

• New exe2bin utility has been added. See Tools User’s Guide for details. 

• Basic support for compiling OS/2 resource scripts and binding resources into OS/2 executables (both 
NE and LX formats) has been added to the resource compiler (wrc). 

• The include search order in the resource compiler has been changed to be more consistent with the 
C/C++ compilers, as well as with IBM’s and Microsoft’s resource compilers. System include files 
(enclosed in angle brackets) are no longer searched in current directory or in the directory of the file 
containing the #include directive. 

• The Windows resource compiler has been made more compatible with scripts designed for 
Microsoft's RC in the way it treats string literals. 

• The MS LINK compatibility wrapper now supports a /RELEASE switch. 

• Syntax highlighting support for makefiles has been added to the editor. The default syntax 
highlighting scheme has also been made more colorful. 

• The editor and Windows GUI tools now store configuration files in more appropriate locations 
(notably on multi-user machines). 

• Several new DOS extender related targets have been added to the IDE. Better support for remote 
debugging has also been added to the IDE. 

• The CauseWay DOS extender now supports SSE instructions on plain DOS. 

• Several simple OS/2 SOM programming examples have been added. 
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6.10 Changes in 1.4 that may Require Recompilation 

stat() The stat function now uses a slightly different struct stat argument. Source code that uses 

the stat function or references struct stat must be recompiled before linking the application 
with new libraries. 


6.11 Differences from Open Watcom Version 1.2 

Following is a list of changes made in Open Watcom C/C++ 1.3: 

• The C++ compiler now restricts the scope of variables declared in a for loop to the scope of that loop 
in accordance with ISO C++, not extending the scope beyond the loop (ARM compliant behavior). 
Code relying on the pre-standard behavior must either be changed or compiled with new -zf switch 
which reverts to old scoping rules. 

• Support for default template arguments has been added to the C++ compiler. 

• Support for alternative tokens (and, xor etc.) has been added to the C++ compiler. It is enabled by 
default, can be turned off with the new -zat switch. 

• The C runtime library has been made significantly more C99 compliant. A number of new headers 
have been added (inttypes.h, stdbool.h, stdint.h, wctype.h) and corresponding new functions 
implemented. Wide character classification functions were moved out of ctype.h into wctype.h. C99 
va_copy macro was added to stdarg.h. 

• Added 'cname’ style C++ headers. 

• Support for SSE, SSE2, SSE3 and 3DNow! instruction sets has been added. Affected tools are the 
assembler (wasm), as well as all x86 compilers, disassembler and debugger. The debugger now also 
supports MMX registers formatted as floats (for 3DNow!) as well as a new XMM register window 
for SSE. 

• Inline assembler directives .MMX, .K3D, .XMM, .XMM2 and .XMM3 are now supported in the 
_asm as well as #pragma aux style inline assembler interface. Note: .MMX directive is now 
required (in addition to .586) to use MMX instructions. 

• C compiler performance has been significantly improved (up to 5-10 times speedup) when 
compiling large and complex source files. 

• All x86 compilers now have the ability to perform no truncation when converting floating point 

values to integers. Additionally, 32-bit x86 compilers have the option to inline the rounding code 
instead of calling_CHP. 

• The C lexical scanner no longer evaluates constants with (U)LL suffix that fit into 32 bits as zero 
(1ULL was wrong, LONGLONG_MAX was correct). 

• C and C++ x86 inline assembler has been fixed to properly process hexadecimal constants postfixed 
with 'h'. 

• The C compiler now supports the C99 ’inline’ keyword, in addition to previously supported ’_inline’ 

and ’_inline’ keywords. 
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• The C compiler now treats a sequence of adjacent character strings as wide if any of the components 
are wide (required by C99), instead of depending on the type of the last component. For example, 
L"foo " "bar" is now interpreted as L"foo bar", instead of "foo bar". 

• The internal C compiler limit on complex expressions has been increased and if it is still insufficient, 
the compiler now reports an error instead of crashing. 

• The C compiler now issues a warning on the default warning level if a function with no prototype is 
referenced. This was previously warning W301 (level 3), now it is warning W131 (level 1). 

• Warning "W132: No storage class or type specified" has been added to the C compiler. This 
warning is issued if a variable is declared without specifying either storage class or type. This is not 
allowed in C89. 

• Warning "W304: Return type 'int’ assumed for function 'foo’" has been added. This warning is 
issued if a function is declared without specifying return type. This is allowed in C89 but not in C99. 

• Warning "W305: Type ’int’ assumed in declaration of ’foo’" has been added to the C compiler. 

This warning is issued if a variable is declared without specifying its type. This is allowed in C89 
but not in C99. Note that if warning W132 is issued, W305 applies as well. 

• The C compiler now properly warns if a function with implied ’int’ return type fails to return a 
value. This potential error was previously undetected. 

• C++ compiler diagnostic messages have been made more consistent and slightly more detailed. 

• Linker for Win32 targets can now create file checksums. These are primarily used for DLLs and 
device drivers, but can be applied to all Win32 PE images if required. 

• Linker for Win32 targets can now set operating system version requirements into the PECOFF 
optional header (Microsoft extended header). 

• Linker for Win32 targets can now set the linker version number into the PE optional header 
(Microsoft extended header). 

• The linker will now eliminate zero-sized segments from NE format (16-bit OS/2 and Windows) 
executables. This fixes a problem where Windows 3.x would refuse to load an executable with zero 
sized segment. This could happen especially with C++ programs where some segments may have 
ended up empty after eliminating unused functions. 

• The linker now (again) produces correct Watcom style debugging information. This was a 
regression introduced in previous version. 

• Command line parsing for wccxxx, wppxxx and cl has been changed such that a double backslash 
inside a quoted string is collapsed to a single backslash, and hence "foo\\" now translates to 'fooV 
and not 'foo\"\ 

• The IDE and other graphical tools no longer leak system resources (a bug introduced in version 1.2). 

• The Image Editor limit on bitmap size has been changed from 512x512 pixels to 2048x2048 pixels. 

• The source browser now correctly decodes array information; Version 11.0c of Watcom C/C++ 
started emitting array browse information in a new format and the browser hadn't been updated 
accordingly. 
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• The NT debugger trap file has been changed so an exception generated during a step operation is 
handled correctly. Previously, the single step flag was not being cleared and when the exception was 
being offered to the debuggee’s own exception handlers, a single step exception occurred in NT’s 
exception handler rather than the exception being passed back to our handler. 

• The OS/2 debuggers now dynamically allocate buffer for the command line, preventing crashes 
when the command line was over approx. 260 bytes long. 

• The NetWare 5 debugger NLM has been changed to use kernel primitives. Previous version were 
using legacy semaphores. 

• The make program (wmake) has been sped up very slightly. Also the ’echo’ command is now 
internal and no longer spawns the system command interpreter. 

• The precision of DBL_MAX, DBL_MIN and DBL_EPSILON has been increased; the non-standard 
variants prefixed with an underscore have been removed. 

• The C99 functions atoll(), lltoa(), ulltoa(), strtolK), strtoullO and corresponding wide character 
functions have been added to the C runtime library. 

• The _beginthread() function now consistently returns -1 in case of error on all platforms. 

• The stdaux and stdprn streams are now only defined on DOS based platforms, ie. DOS, Winl6 and 
Win386. No other platforms support stdaux or stdprn. 

• The assert/) macro now prints function name in addition to source file and line number, in 
accordance with C99. 

• The _heapchk() function will now always perform a consistency check on the heap, where it would 
previously only check consistency if there had been allocations/frees since last call to _heapchk(). 

As a consequence, _heapchk() previously did not detect certain instances of heap corruption. 

• [OS/2 32-bit] The default_disallow_single_dgroup() implementation no longer statically links 

against PMWIN.DLL. This allows DLLs to load on systems where PMWIN.DLL isn't present. 

• [OS/2 32-bit] Re-implemented clock(). The new implementation uses the OS millisecond counter 
and is hence not susceptible to TZ changes. It is also smaller, faster and more accurate, although it 
may wrap around earlier than the original implementation. 

• The disassembler (wdis) now correctly processes x86 ’push 8-bit immediate’ instructions. 

• The disassembler now correctly processes absolute memory references. All memory references 
without fixup are now disassembled as ds:[...] or sreg:[...]. 

• Several DirectX Win32 programming samples have been added. Note that a separate DirectX SDK 
(available from Microsoft) is required to build these sample programs. 
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6.12 Differences from Open Watcom Version 1.1 

Following is a list of changes made in Open Watcom C/C++ 1.2: 

• Handling of default libraries for Win32 targets has been changed. Previously default library records 
were included in the C runtime library, now they are specified part of the wlink Win32 target 
definitions in wlsystem.lnk. The list of libraries has changed from previous version as well and now 
reflects the Microsoft compiler defaults; existing IDE projects and makefiles may need to have 
additional libraries specified if those are no longer part of the default list. 

• The C compiler now performs stricter checking on function prototypes and pointer operations. This 
may lead to previously undiagnosed warnings/errors appearing when compiling incorrect or 
ambiguous code. 

• The C compiler diagnostic messages have been improved to print more information, making it easier 
to isolate the problem. 

• A new warning (WOO) has been added to the C compiler to diagnose possible precision loss on 
assignment operations. This warning is never on by default and must be enabled through '#pragma 
enable_message(130)’ or’-wce=130’ switch. 

• Support for C99 style variable argument macros (and_VA_ARGS_) has been added to the C and 

C++ compilers. 

• Added support for the_func_symbol (name of the current function) which is equivalent to the 

already existing_FUNCTION_symbol. 

• Better C99 style support for "long long" type is now available in the C and C++ compilers. LL, 

ULL and LLU suffixes are recognized for constants, "long long int" is now also recognized. 

• Added C99 style *LLONG_MIN/MAX defines to limits.h. 

• The C++ compiler has been fixed to properly accept source files where a template was the last item 
in a name space or an external linkage. 

• Several new -adxx options have been added to the C and C++ compilers to support automatic 
generation of ’make’ style dependency files. 

• The C compiler has been fixed to correctly diagnose illegal union assignments. 

• The C compiler now issues warnings on operations involving pointers to different but compatible 
unions. 

• The C and C++ compilers now ensure word alignment of wide character string literals to satisfy 
Win32 API restrictions. 

• The_UNIX_macro is now supported in C and C++ compilers, wmake and wasm. It is currently 

defined for QNX and Linux targets. 

• Default windowing support has been re-enabled for Winl6 and Win386 runtime libraries. 

• Since default windowing is no longer supported on most platforms, the Programmer’s Guide and 
IDE tutorial have been updated to reflect that fact. 
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• The Win32 GUI tools now support the Windows XP look and feel. 

• AutoCAD and MFC targets have been removed from the IDE, the -bw switch (default windowing) is 
no longer available in the IDE for OS/2 and Win32 targets. 

• Manual for the CauseWay DOS extender has been added. 

• The dmpobj tool has been added. This utility dumps the contents of OMF object files and can be 
useful to developers. 

• Several system definitions have been added to wlink: os2_pm (16-bit OS/2 Presentation Manager 
executable), os2_dll (16-bit OS/2 DLL) and os2v2_dll (32-bit OS/2 DLL). 

• The linker has been fixed to read "AR" style archives produced by third party tools. 

• The linker has been fixed to prevent crashes when linking with COFF files providing uninitialized 
COMDAT entries 

• Several linker crashes related to ELF object files and executables have been resolved. 

• Updated wlink to call wlib with the -c (case sensitive) option when creating import libraries. This 
fixes problems with DLLs that export symbols differing only in case. 

• The C runtime library has been optimized to produce smaller executables. 

• The printf() function now supports the "11" format specifier for "long long" integers. 

• The printf() function has been enhanced to support %b format specifier for bitfields. 

• Execution order of C library termination routines is now better defined to prevent instances where 
temporary files created through mktempO could be left behind. 

• [OS/2 32-bit] To prevent crashes, termination code is not run if second instance of a DLL failed to 
load due to single DGROUP. 

• [OS/2 32-bit] The_grow_handles() function was incorrectly adding n requested handles to existing 

limit instead of setting the limit to n. 

• [OS/2 32-bit] Fixed a problem with _STACKLOW in multithreaded programs and DLLs. This 
prevents crashes where Fortran DLLs would run out of stack. 

• [OS/2 16-bit] Fixed default math exception handler which wasn't popping the FP status word off the 
stack and would therefore crash on exit. 

• The Win32 Image Editor has been enhanced with drag-and-drop support. 

• The IDE has been fixed to properly handle mixed case filenames. 

• The Microsoft compatibility tools (NMAKE, CL) have been fixed to better handle command line 
arguments. 

• The Dialog Editor (wde) has been fixed to prevent occasional DDE related crashes when run from 
inside the Resource Editor (wre). 
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• The 'Change font’ option no longer crashes the GUI debugger (wdw). 

• On OS/2, wdw now intercepts the F10 key instead of passing it on to the system. 

• The code generator now deletes object files if it was interrupted. Previously zero-length invalid 
object files could be left behind, interfering with make operation. 

• The wasm assembler has been enhanced to generate file dependency information usable by wmake. 

• Numerous minor fixes have been made to wasm. 

• Compatibility with MASM 6 has been improved with wasm. 

• Support for sysenter and sysexit instructions has been added to wasm and wdis. 

• Disassembly of xchg and bound instructions has been fixed in wdis (corrected order of operands). 

• Several previously undocumented wmake directives have been documented. 

• A -sn ('noisy') option has been added to wmake to print all commands that wmake executes, 
including silent ones. 

• The w32api project has been updated to the latest version. 

• The os2api project has been enhanced - added multimedia headers and libraries and numerous fixes 
have been made to the header files. 

• The debugger now supports the F7 key as a shortcut for "run to cursor". This is consistent with 
CodeView. 

• New internal variable dbg$ntid (next thread id) has been added to the debugger. This permits 
automated iteration of all threads. 

• The wsample tool has been updated to dynamically allocate storage for command line, where 
previously the command line length was limited to 128 characters. 

• The FORTRAN compiler has been changed to preserve case of symbols with linkage other than 
FORTRAN. This is especially helpful when calling OS API functions and using case sensitive link 
step (now default). 

6.13 Differences from Open Watcom Version 1.0 

A number of problems has been corrected in Open Watcom C/C++ 1.1. 

• Using the -ol option (loop optimization) sometimes resulted in generation of incorrect code. 

• The printfO function could access too much data when formatting strings, causing page faults. 

• NANs, INFs and denormals were not handled correctly by the math emulation library. 

• The assembler did not generate implicit segment override prefixes when accessing data in code 
segment. 
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• The clock() function sometimes produced incorrect results on OS/2 if the TZ environment variable 
was set. 

• The Open Watcom editor (vi/viw) has been changed to store temporary files in directory designated 
by the TMP environment variable, instead of using the TMPDIR environment variable. 

• Many packaging problems (missing files) have been resolved. 


6.14 Differences from Version 11.0 


Open Watcom C/C++ 1.0 is not substantially different from Watcom C/C++ version 11.0. There are 
however several changes that may require you to change your source and/or makefiles or project files. 

• The C compiler now implements stricter function prototype processing. This may result in new 
warning or error messages on code that was previously compiling cleanly but contained mismatches 
between function prototypes and actual definitions. The C++ compiler did not have this problem. 

• The linker now defaults to case sensitive symbol resolution. In most cases this is not a problem and 
may in fact avoid certain problems. If your project relies on case insensitive linking, please add 
OPTION NOCASEEX to your linker directives. 

• Default windowing support has been removed from the runtime libraries. 

• Components of the Win32 SDK and OS/2 Toolkits are no longer supplied. 

• MFC libraries, source code and documentation are no longer supplied. 

6.15 Changes in 11.0 that may Require Recompilation 

Do not attempt to mix object code generated by earlier versions of the compilers with object code generated 
by this release or with the libraries provided in this release. 

A new C++ object model has been implemented. If you have undefined references to_wcpp_ 3_ * 

names, you have old object code. If you have undefined references to_wcpp_ 4_ *, you have old 

libraries and new object code. 

clock() The clock function accuracy has changed from 100 ticks per second to 1000 ticks per 

second (i.e., CLOCKS_PER_SEC has changed). Source code that uses the clock function 
and CLOCKS_PER_SEC in its calculations must be recompiled before linking the 
application with new libraries. 

6.16 Major Differences from Version 10.6 

The following sections summarize the major differences from the previous release. 

• In general, we have improved Microsoft compatibility in our compilers (more warnings instead of 
errors, support for MS extensions, etc.) and tools. 

• Some of the Win32 and 32-bit OS/2 versions of our tools are now available in DLL form. 
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EXE 

DLL 

Description 


wcc 

weed 

16-bit x86 

C compiler 

wcc38 6 

wccd38 6 

32-bit x86 

C compiler 

wpp 

wppdi8 6 

16-bit x86 

C++ compiler 

wpp38 6 

wppd38 6 

32-bit x86 

C++ compiler 

wlink 

wlink 

Open Watcom 

Linker 

wlib 

wlibd 

Open Watcom 

Library Manager 


This provides better performance when using the Integrated Development Environment or Open 
Watcom Make. See the description of the ! loaddll preprocessing directive in Open Watcom 
Make for more information. 

Changes to the C++ Compiler for 11.0 

• The C++ compiler now optimizes empty base-classes to occupy zero storage in the derived class 
memory layout. The C++ Working Paper recently allowed this optimization to be performed by 
conforming implementations. Furthermore, the optimization has speed and size benefits. There are 
certain classes of (broken) C++ programs that may not function properly with the new optimization. 
If you explicitly memset() an empty base class, you will be clearing memory that you may not expect 
to be cleared since the "zero sized" base class in actual fact shares storage with the first member of 
the derived class. A memset() of the entire derived class is fine though. 

• We have added support for the mutable keyword which is used to indicate data members that can 
be modified even if you have a const pointer to the class. 

Example: 

class S { 

mutable int x; 
void foo() const; 

} ; 


void S::foo() const { 

x = 1; // OK since it is mutable 

} 

• We have added support for the bool type along with true and false . 

• We have added support for the explicit attribute. It marks a constructor so that it will not be 
considered for overloading during implicit conversions. 

Example: 

struct S { 

explicit S( int ) ; 

1 ; 

S v = 1; // error; cannot convert 'int' to 'S' 

Suppose the class was changed as follows: 
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Example: 

struct S { 

explicit S(int ); 

S( char ); 

} ; 

S v = 1; // OK; S( char ) is called 

The fact that S (int ) is not considered leaves S (char) as the only way to satisfy the implicit 
conversion. 

•We have added support for name spaces, 
namespace x { 

// anything that can go in file-scope 

} 

namespace { 

// anything in here is local to your module! 

} 

In the above example, you can access names in the namespace "x" by "x::" scoping. Alternatively, 
you can use the "using namespace x" statement (thereby eliminating the need for "x::" scoping). You 
can include a part of the namespace into the current scope with the "using x: member" statement, 
(also eliminating the need for "x::" scoping). 

1. Name spaces eliminate the hand mangling of names. For example, instead of prefixing 
names with a distinguishing string like "XPQ_" (e.g., XPQ_Lookup), you can put the 
names in a namespace called "XPQ". 

2. Name spaces allow for private names in a module. This is most useful for types which are 
used in a single module. 

3. Name spaces encourage the meaningful classification of implementation components. For 
example, code-generation components might reside in a namespace called "CodeGen". 

• We have added support for RTTI (Run-Time Type Information). 

• We have added support for the new C++ cast notation. It allows you to use less powerful casts that 
the all powerful C-style cast and to write more meaningful code. The idea is to eliminate explicit 
casts by using a more meaningful new-style cast. The new C++ casts are: 

reinterpret_cast < type-id >(expr) 
const_cast < type-id >( expr ) 
static cast < type-id >( expr ) 
dynamic_cast < type-id >( expr ) (part of RTTI) 

•We have improved (faster) pre-compiled header support. 

• We have added "long long" (64-bit integer) support in the form of a new_ int64 type. 

• The default structure packing was changed from "zpl" to "zp2" in the 16-bit compiler and from 
"zpl" to "zp8" in the 32-bit compiler. 

• The default type of debugging information that is included in object files is "Dwarf". It used to be 
"Watcom". 
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• A new double-byte string processing option has been added (zkl). When this option is specified, the 
local or current code page character set is used to decide if the compiler should process strings as if 
they might contain double-byte characters. 

Changes to the C Compiler for 11.0 

• We have improved (faster) pre-compiled header support. 

• We have added "long long" (64-bit integer) support in the form of a new_ inl64 type. 

• The default structure packing was changed from "zpl" to "zp2" in the 16-bit compiler and from 
"zpl" to "zp8" in the 32-bit compiler. 

• The default type of debugging information that is included in object files is "Dwarf". It used to be 
"Watcom". 

• A new double-byte string processing option has been added (zkl). When this option is specified, the 
local or current code page character set is used to decide if the compiler should process strings as if 
they might contain double-byte characters. 

Changes to the Code Generator for 11.0 

• We support Microsoft-compatible in-line assembly formats using the "_asm" keyword. 

• A new optimization, "branch prediction", has been added. This optimization is enabled by the "ob" 
or "ox" compiler options. The code generator tries to increase the density of cache use by predicting 
branches based upon heuristics (this optimization is especially important for Intel’s Pentium Pro). 

• We have added Multi-media Extensions (MMX) support to the in-line assemblers. 

• We have added "long long" (64-bit integer) support in the form of a new_ int64 type. 

Changes to the Compiler Tools for 11.0 

• The Open Watcom Linker supports incremental linking. 

• The Open Watcom Linker can now process COLL and ELL format object files, as well as OML et al. 
The Open Watcom Linker can now read both AR-format (Microsoft compatible) libraries and 
old-style OML libraries. 

• Support for creating 16-bit DOS overlaid executables has been removed from the linker. 

• The Open Watcom Library Manager (WLIB) can now process COLL and ELL format object files, as 
well as OML et al. The Open Watcom Library Manager can now read/write both AR-format 
(Microsoft compatible) libraries and old-style OML libraries. The default output format is 
AR-format and this can be changed by switches. The Open Watcom Library Manager can output 
various format import libraries. 

• We have added Multi-media Extensions (MMX) support to the Open Watcom Assembler (WASM). 
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• A new version of the Open Watcom Disassembler (WDIS) can disassemble Intel or Alpha AXP 
object code files. It can process ELF, COFF or OMF object files and ELF, COFF or PE format 
(Win32) executables. The Open Watcom Disassembler looks at image file being input to determine 
the processor-type (defaults to Intel). 

The old disassembler (WDISASM) has been retired and is not included in the package. 

• We have added new tool front-ends that emulate Microsoft tools. These are: 

• nmake 

• cl 

• link 
•lib 

• rc 

• cvtres 

These programs take the usual Microsoft arguments and translate them, where possible, into 
equivalent Open Watcom arguments and spawn the equivalent Open Watcom tools. 

• Open Watcom Make now processes Microsoft format makefiles when the "ms" option is used. 

Changes to the C/C++ Libraries for 11.0 

• We have added multi-byte and wide character (including UNICODE) support to the libraries. 

• We include run-time DLLs for the C, Math and C++ Libraries. 

• We have added Multi-media Extensions (MMX) support to the libraries. 

• The following new functions were added to the library... 
multi-byte functions 

• The clock function accuracy has changed from 100 ticks per second to 1000 ticks per second (i.e., 
CLOCKS_PER_SEC has changed). 

• A "commit" flag ("c") was added to the fopen() mode argument. 

• The global translation mode flag default is "text" unless you explicitly link your program with 
BINMODE.OBJ. 

• Processing of the "0" flag in the format string for the printf() family of functions has been corrected 
such that when a precision is specified, the "0" flag is ignored. 

Example: 

printf ( "%09.31f\n", 1.34242 ); // "0" flag is ignored 
printf( "%091f\n", 1.34242 ); // "0" flag is not ignored 

• Support for printing_ int64 values was added to printf and related functions. 

• Support for scanning_ int64 values was added to scanf and related functions. 

• The Win32 _osver variable was added to the library. 
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• The Win32 winmqjor, winminor and _winver variables were added to the library. 

Changes to the DOS Graphics Library for 11.0 

• The graphics library now performs the VESA test before testing for vendor specific graphics cards. 
This fix is intended to broaden the number of graphics cards that are supported. 

Changes in Microsoft Foundation Ciasses Support for 11.0 

• Version 4.1 of the 32-bit MFC is included in the package. 

• Version 2.52b of the 16-bit MFC is included in the package. 

Changes in Microsoft Win32 SDK Support for 11.0 

• The Win32 SDK is supported for Windows 95 and Windows NT platforms. 

Changes in Blue Sky’s Visual Programmer for 11.0 

• A new 32-bit version of Visual Programmer is included in the package. This version runs on 32-bit 
Windows 95 and NT. The 16-bit version of Visual Programmer is no longer included in the package. 

• You can generate 16-bit applications with it, but you must be careful to avoid using Win95 controls. 

• This new version fixes all known bugs in the previous version. 

6.17 Changes in 10.6 that may Require Recompilation 

_diskfree_t The struct members of the _diskfree_t structure has been changed from UNSIGNED 

SHORTs to UNSIGNED INTs. This is to deal with possible HPFS partitions whose size 
will overflow a short, as well as Microsoft compatibility. 

clock() The clock function accuracy has changed from 100 ticks per second to 1000 ticks per 

second (i.e., CLOCKS_PER_SEC has changed). Source code that uses the clock function 
and CLOCKS_PER_SEC in its calculations must be recompiled before linking the 
application with new libraries. 

6.18 Major Differences from Version 10.5 

The following sections summarize the major differences from the previous release of Watcom C/C++. 
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Windows 95 Help File Format 

We have included Windows 95 format help files. 

Changes to the C++ Compiler in 10.6 

We have improved Microsoft compatibility so that Win32 SDK and MFC header files can be compiled 
without change. The following changes were required to support Win32 SDK header files. 

• We recognize the single underscore versions of_stdcall,_inline, and_fastcall 

keywords. 

• The _ fastcall and_fastcall keywords are scanned but ignored since they refer to a 

particular Microsoft code generation technique. Open Watcom’s generated code is always "fast". 

The following changes were required to support MFC source code. 

• When /bt=DOS is specified, define _ DOS . 

• When /bt=WINDOWS is specified, define _ WINDOWS . 

• When /m[slmlclllh] is specified, define_SW_ M[s|m|c|l|h] and M_ 186 [S |m|c| l|h]M. 

The compiler now supports the C++ Standard Template Library (STL). This library is available at the ftp 
site "butler.hpl.hp.com". When compiling applications that use the STL, you must use the "hd" compiler 
option for debugging info (the "hw" option causes too much debug information to be generated). 

Changes to the C Compiler in 10.6 

We have improved Microsoft compatibility so that Win32 SDK and MFC header files can be compiled 
without change. The following changes were required to support Win32 SDK header files. 

• Support for the single underscore version of the_stdcall keyword. 

• When /bt=DOS is specified, define _ DOS . 

• When /bt=WINDOWS is specified, define _ WINDOWS . 

The following changes were required to support SDK sample code. 

• You can specify calling convention information in a function prototype and you do not have to 
specify the same information in the definition. (Note: This is required by the OS/2 Warp SDK 
samples.) 

• Structured exception handling is supported (_ try, _except and_finally keywords). 

• Allow initialization of automatic array/struct data using variables and function calls. 
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Changes to the C Library in 10.6 

The following new functions were added to the library. 

_getw read int from stream file 

_putw write int to stream file 

The clock function accuracy has changed from 100 ticks per second to 1000 ticks per second (i.e., 
CLOCKS_PER_SEC has changed). 

Changes in Microsoft Foundation Classes Support for 10.6 

• Version 3.2 of the 32-bit MFC is included in the package. 

• Version 2.52b of the 16-bit MFC is included in the package. 

Changes to the Image Editor in 10.6 

• Support has been added for 256 color bitmaps. 

• Support has been added for 16 X 16 icons. 

• Support has been added for 48 X 48 icons. 

Changes to the Dialog Editor in 10.6 

• Support has been added for Windows 95 controls. 

• Support has been added for adding new control styles to existing controls. 

• Support has been added for new dialog styles. 

• Support has been added for allowing help IDs to be specified in dialog and control statements. 

• Support has been added for generating new resource statements in .RC files. 

Changes to the Resource Editor in 10.6 

• Support has been added for new Windows 95 DIALOGEX resource type. 

• Support has been added for generating new DIALOGEX resource statements in .RC files. 


Major Differences from Version 10.5 69 




Chapter 6 


Changes to the Resource Compiler in 10.6 

• Support has been added for extended styles for dialogs. 

• Support has been added for the RCINCLUDE keyword. 

6.19 Major Differences from Version 10.0 

• New installation program 

• Visual Programmer for Windows (MFC) applications 

• MFC 3.0 support 

• Native C++ exception handling support 

• Improved language compatibility with Microsoft 

• Browser can now be used to browse C code 

• OS/2 3.0 Warp support 

• Toolkit for OS/2 1.3 

• Windows NT 3.5 support 

• Toolkit for Windows NT 3.5 

• Windows 95 (Chicago) support 

• Source Revision Control System hooks in editor 

• TCP/IP remote debug servers for OS/2 and Windows NT/95 

In addition to these new features, we have also made a number of improvements to the software. 

1. The editor is more tightly integrated with the IDE. 

2. It is now easier to select your own favorite editor from the IDE. 

3. The keyboard interface in the Integrated Development Environment (IDE) has been improved. 

4. The "fr" option, which is supported by the compilers & assembler, can be used to name the error 
file drive, path, file name and/or extension. 

5. We have added the "t<number>" option to the C++ compiler to set the number of spaces in a tab 
stop (for column numbers in error messages). 

6. The C compiler now supports @ftlename on the command line like the C++ compiler currently 
does. 
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7. The "_stdcall" linkage convention has changed. All C symbols (extern "C" symbols in C++) 

are now suffixed by "@nnn" where "nnn" is the sum of the argument sizes (each size is rounded 
up to a multiple of 4 bytes so that char and short are size 4). When the argument list contains 

the "@nnn" suffix is omitted. This was done for compatibility with Microsoft. Use the 
"zz" option for backwards compatibility. 

8. The 32-bit"_cdecl" linkage convention has changed. Watcom C/C++ 10.0_cdecl did not 

match the Microsoft Visual C++_cdecl in terms of the binary calling convention; Visual C++ 

saves EBX in a_cdecl function but Watcom C/C++ 10.0 modified EBX. Watcom C/C++ has 

been changed to match Visual C/C++. 

If you wrote a "_cdecl" function in an earlier version of Watcom C/C++, the EBX register was 

not saved/restored. Starting with release 10.5, the EBX register will be saved/restored in the 
prologue/epilogue of a "_cdecl" function. 

Another implication of this change is that"_cdecl" functions compiled with an earlier version 

of Watcom C/C++ don’t match the calling conventions of the current version. The solution is 

either to recompile the functions or to define a "_cdecl_old" pragma that matches the old 

calling conventions. 

♦pragma aux_cdecl_ old *" \ 

parm caller [] \ 

value struct float struct routine [eax] \ 
modify [eax ebx ecx edx]; 

♦pragma aux (_cdecl_ old) foo; 

extern int foo( int a, int b ); 

void main() 

{ 

printf ( "%d\n", foo( 1, 2 ) ); 

} 


9. We now allow: 

extern "C" int _ cdecl x; 

It must be extern "C" for_cdecl to take effect since variables have their type mangled 

into the name for "C++" linkage. 

10. In C++, we have removed the warning for "always true/false" expressions if the sub-expressions 
are constant values. 

11. We have added support for: 

♦pragma pack(push,4); 

♦pragma pack(push); 

♦pragma pack(pop) 

12. We have added support for: 

♦pragma comment(lib,"mylib.lib") 
which has the same semantics as: 
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♦pragma library( "mylib.lib" ) 

13. We have added support for expanding macros in the code_seg/data_seg pragmas: 

♦define DATA_ SEG_ NAME "MYDATA" 

♦define CODE_ SEG_ NAME "MYCODE" 

♦pragma data_ seg( DATA_ SEG_ NAME ) 
int x = 3; 

♦pragma code_ seg( CODE_ SEG_ NAME ) 
int fn () { 

return x; 

} 

14. We have fixed the 16-bit compiler so that it matches the Microsoft 16-bit C compiler for the 
following cases: 

• If a pascal function is defined when compiling for Windows 3.x, use the fat Windows 3.x 
prologue in the function. 

• If a cdecl function is defined when compiling for Windows 3.x, use the fat Windows 3.x 
prologue in the function. 

15. We have fixed the compiler so that 

♦include </dir/file.h> 

works as expected (it was searching along the INCLUDE path only). 

16. In C++, we have fixed a problem where an import was generated in the object file for a virtual 
function call. This will reduce the size of executables under certain circumstances. 

17. In C++, we have removed the prohibition of pointer to array of unknown size declarations. 

Example: 

int (*p) [ ]; 

18. In C++, we have fixed the diagnosis of lexical problems during macro expansion to remove 
spurious warnings. 

Example: 

♦define stringize( x ) ♦x 

stringize( 2131231236172637126371273612763612731 ) 

19. We have corrected the check for too many bytes in #pragma for assembler style aux #pragmas. 

20. Undeclared class names in elaborated class specifiers are now declared in the nearest enclosing 
non-class scope. Undeclared classes are also allowed in arguments now. 
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Example: 

struct S { 

// used to declared ::S::N but now declares ::N 
struct N *p; 

} ; 


void foo( struct Z *p ); // declares ::Z 

21. We have fixed unduly harsh restriction on virtual ...-style functions. They are now allowed in 
single inheritance hierarchies as long as the return type is not changed when the virtual function 
is overridden. In multiple inheritance hierarchies, an implementation restriction is still present 
for generating a ’this’ adjustment thunk for virtual functions. 

22. We have fixed line number information for multi-line statement expressions in some weird 
cases. 

23. We have fixed function template parsing of user-defined conversions that use an uninstantiated 
class in their operator name. 

Example: 

void ack( int ); 

template <class T> 
struct S { 

S ( T x ) 

{ 

ack ( x ); 


} ; 


template <class T> 
struct W { 

operator S<T>(); 

} ; 


template <class T> 

W<T>::operator S<T>() { 

return 0; 

} 

24. We have fixed a compiler problem that caused a linker warning "lazy reference for <virtual-fn> 
has different default resolutions" in cases where the compiler or programmer optimized virtual 
function calls to direct calls in modules that also contained virtual calls. 

Example: 

T.H 

struct S { 

virtual int foo() { return_LINE_; } 

} ; 

struct T : S { 

virtual int foo() { return _LINE_; } 

} ; 
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T1.CPP 

♦include "t.h" 
struct Q : T { 

virtual int foo() { return S::foo() +_LINE_; } 

} ; 

void too( T *p ) 

{ 

Q y; 

y.too (); 
p->foo (); 

} 

T2.CPP 

♦include "t.h" 

void too( T *p ); 

void ack( T *p ) { 

p->foo (); 
foo (p); 

} 

main () { 

T q; 

ack( &q ); 

} 

25. When a class value is returned and is immediately (in the same expression) used to call a 
member function, the value may not be stored in memory. 

Work around: introduce a temporary 

Example: 

struct S { 
int v; 

int member(); 


S foo (); 

void example( void ) 

{ 

// foo ().member(); // replace this line with: 

S temp = foo(); 
temp.member(); 

} 

26. Throwing pointers to functions did not work when the size of a function pointer is greater than 
the size of a data pointer. 

Work around: place the function pointer in a class and throw the class object. 

27. We have fixed default argument processing for const references to an abstract class. The 
following example would not compile properly: 
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Example: 

struct A { 

virtual int foo() = 0; 

} ; 

A &foo(); 

void ack( A const &r = foo() ); 

void bar () { 

ack (); 

} 

28. We have made "DllMain" default to extern "C" linkage for Microsoft Visual C++ compatibility. 

29. We have duplicated a Microsoft Visual C++ extension that was required to parse the Windows 
95 SDK header files. 

Example: 

typedef struct S { 

} S, const *CSP; 

A A A A A no ^- a ]_]_ OWeC l j_ n ISO c or ISO C + + 

30. We now do not warn about starting a nested comment if the comment is just about to end. 

We also fixed the code that figures out where a comment was started so that a nested comment 
warning is more helpful. 

Example: 

/*/////////*/ 


31. We have fixed a problem where extra informational notes were not being printed for the error 
message that exceeded the error message limit. 

Example: 

// compile -e2 
struct S { 

void too (); 

} ; 


void foo( S 

{ 

p->foo( 
p->foo( 
p->foo( 
p->foo( 


const *p ) 

) ; 

) ; 

) ; 

) ; 


32. We have fixed a problem where the line number for an error message was incorrect. 
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Example: 

struct S { 

void foo() const; 
void bar(); 

} ; 

void S::foo() const 

{ 

bar (); 

this->bar(); 


} 

33. We have fixed output of browser information for instantiated function template typedefs. 

34. We have upgraded the C++ parser so that casts and member pointer dereferences can appear on 
the left hand side of the assignment expression without parentheses. 

Example: 

p->*mp = 1; 

(int&)x = 1; 

35. In several cases, when a function return or a construction was immediately dotted in an 
expression, the generated code was incorrect: 

Example: 

struct S { 
int x; 
int foo(); 

} ; 


extern S gorf(); 

void bar() 

{ 

gorf () .foo (); 

1 

The work around was to break the statement in two: 

Example: 

S temp = gorf (); 
temp.foo(); 

36. In several cases, when a function return or a construction was immediately addressed in an 
expression, the generated code was incorrect: 
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Example: 

struct S { 
int x; 

} ; 


extern void fun( S* ); 

extern S gorf (); 

void bar() 

{ 

fun( &gorf() ); 

} 

The work around was to break the statement in two: 

Example: 

S temp = gorf (); 
fun( &temp ); 

37. We have added support for: 

#pragma error "error message" 

Use the ISO/ANSI method because it is more portable and acceptable (Microsoft header files use 
the less portable #pragma when there is a perfectly fine, portable way to issue a message). 

The portable, acceptable method is: 

terror "error message" 

38. We have added support for_declspec (dllexport) £ _declspec (dllimport) , 

_declspec (thread) , and_declspec (naked) for Win32 (i.e., WinNT 3.5 and 

Win95) programs. Here are some examples: 

Example: 

_declspec(dllexport) int a; 

_declspec(dllexport) int b() 

{ 

} 

struct _declspec(dllexport) S { 

static int a; 
member 

void b(); 

} ; 

extern _declspec(dllimport) int a; // import 'a' from a .DLL 

extern _declspec(dllimport) int b();//import 'b' from a .DLL 

struct _declspec(dllimport) I { 

static int a; // import 'a' static 

member 

void b(); // import 'b' member fn 

}; 


// export 'a' static 
// export 'b' member fn 


// export 'a' variable 
// export 'b' function 
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39. The C++ compiler generates better error messages for in-class initializations and pure virtual 
functions. 

Example: 

struct S { 

static int const a = 0; 
static int const b = 1; 
void too() = 0; 
void bar() = 1; 
virtual void ack() = 0; 
virtual void sam() = 1; 

} ; 

40. We have fixed macro processing code so that the following program compiles correctly. The 
compiler was not treating "catch" as a keyword after the expansion of "catch_all". 

Example: 

♦define catch(n) catch(n Sexception) 

♦define xall (...) 

♦define catch_ all catch xall 

main () 

{ 

try { 

} 

catch_ all{ 

} 

} 

41. We have fixed a problem where ♦pragma code_ seg caused a page fault in the compiler 
when the code_seg was empty. 

42. We have fixed a rare problem where a #include of a file that was previously included caused the 
primary source file to finish up if the CR/LF pair for the line that the #include was on, straddled 
the C++ compiler’s internal buffering boundary. 

43. We have added support for ♦pragma message! "message text" ) . It outputs a 
message to stdout when encountered. It is used in Microsoft SDK header files to warn about 
directly including header files and obsolete files. 

44. We have fixed #pragma code_seg/data_seg to properly set the class name of the new segment in 
the object file. 

45. We have a fixed a problem with the -zm -d2 options that caused a compiler fault in some 
circumstances. 

46. We have fixed default library records in .OBJ file so that user libraries are ahead of default 
compiler libraries in the linker search order. 

47. We have fixed handling of intrinsic math functions so that the code generator will treat functions 
like sqrt as an operator. 

48. We have added support for using OS-specific exception handling mechanisms for C++ exception 
handling during code generation. Enable it with the new -zo option. 
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49. _stdcall functions now have Microsoft Visual C/C++ compatible name mangling. 

50. We have added a number of new functions to the C Library. These have been added to improve 
Microsoft compatibility. 

dllmain (nt only) 
libmain (nt only) 

_ access 
_ dos_ commit 
_ dup 
_ ecvt 
_ fcvt 
_ fstat 
_ fstrdup 
_ gcvt 
_ itoa 
_ itoa 
_ locking 
_ lseek 
_ Itoa 
_ Itoa 
_ memicmp 

_ set_ new_ handler 
_ stat 
_ strdate 
_ strdup 
_ stricmp 
_ strlwr 
_ strnicmp 
_ strrev 
_ strtime 
_ strupr 
_ tolower 
_ toupper 

_ isascii 

_ iscsym 

_ iscsymf 

51. In version 9.5, the linker used to include LIBFILE object files in reverse order (i.e., the last one 
listed was the first to be included). We have corrected this behavior so that they are included in 
the order listed. 


Directive 


Old Order New Order 


FILE obj_ a 3 
LIBFILE obj_b 2 
LIBFILE obj_ c 1 
FILE obj_ d 4 


3 

1 

2 

4 


In the above example, the object files will be included in the order indicated (LIBFILE object 
files are always included first). 
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Changes in 10.5 that may Require Recompilation 

_ stdcall If you use the_stdcall attribute within a program then you must re-compile the function 

definition and all callers of the stdcall function. 

_ cdecl The_cdecl attribute is not heavily used in Win32 programming so the impact should be 

minimal but if you do use_cdecl within your own programs, a re-compilation will be 

necessary. 

6.20 Major Differences from Version 10.0 LA 

If you have .tgt files created with the Limited Availability or Beta Integrated Development Environment, 
when you load them, the target window may say "Obsolete Form: rename target type". If it does: 

1. Select the target window by clicking in it, 

2. Choose "rename target" from the target menu (a rename target dialog will appear), 

3. Reselect the target type for this target (e.g., Win32 EXE), and 

4. Select OK. 

You should not continue to use .cfg files from the Limited Availability version of the compiler. Several 
new features have been added. Using the old files will cause problems. 

The C++ compiler calling conventions have changed. Any program that passes a "data only" class or struct 
as a parameter, or returns a C++ object will need to be recompiled. We recommend that you recompile 
your application. 

The C++ compiler now supports the use of the export. cdecl , pascal , stdcall and syscall 

keyword on class definitions. These keywords will affect all members of the defined class. 


6.21 Major Differences from Watcom C9.5/386 

• The functionality of Watcom C/C++(16) and Watcom C/C++(32) is included in a single package. 

• An Integrated Development Environment for Windows 3.x, Windows NT, Windows 95 and OS/2 
PM is included. 

• New, redesigned debugger with GUI interfaces for Windows 3.x, Windows NT, Windows 95 and 
OS/2 PM is included. 

• The optimizer has been enhanced. 

• C++ Class Browser 

• New, redesigned user interface for the Profiler. 

• New support for C and C++ precompiled header files. 

• Windows resource editing tools are included: 
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Dialog Editor 
Bitmap Editor 
Resource Editor 
Menu Editor 
String Editor 
Accelerator Editor 

• Windows development tools are included: 

Dr. Watcom (a post mortem debug utility) 

Spy (Windows message spy program) 

DDESpy 
Heap Walker 
Zoom 

• On-line documentation is included. 

• Microsoft Foundation Classes for 32-bit Windows applications (MFC 4.1) and 16-bit Windows 3.1 
applications (MFC 2.52b) is included. 

• Creation of FlashTek DOS extender applications is supported. 

• Compiler executables have been created that run under all supported operating systems. They are 
located in the BINW directory. 

Items No Longer Supported 

• PenPoint development 

• Debugging of Ergo OS/386 DOS extender applications 

• DESQView remote debugging 

Changes in 10.0 that may Require Recompilation 

All C++ applications will require recompilation due to changes in the underlying object model. C 
applications should not require recompilation, but you should recompile your application if you want to 
take full advantage new features in the debugger. The changes to the C++ object model are: 

• Virtual table layout changed (NULL entry at offset 0 removed) 

• derived class packing adjusted to minimize padding bytes 

• exception handling code is improved (incompatible with 9.5) 

• name mangling for ’char' reduced from two chars to one char 
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6.22 Major Differences from Watcom C9.011386 

• C++ support added 

• Pentium optimizations added ("5r", "5s", "fp5" options) 

• Windows NT support added 

• Microsoft resource compiler (RC.EXE) replaced with Watcom resource compiler (WRC.EXE) 

• OS/2 libraries modified so that single library supports single and multiple threads and DLL’s 

• "fpi287" switch renamed to "fp2" 

• #pragma intrinsic and #pragma function added 

• 80x87 usage modified so that compiler assumes all eight registers are available upon entry to 
function instead of only four registers, "fpr" option added for reverse compatibility with object files 
compiled with previous versions of compiler 

Changes that may Require Recompilation 

The stat structure in "stat.h" changed in version 9.5. Any object files compiled with an earlier version of 
the compiler will have to be recompiled if they use the stat structure. 

A new function _grow_handles was added to version 9.5 for growing the number of available file handles. 
Details on how to use this function can be found in the Watcom C/C ++ 32 Commonly Asked Questions & 
Answers booklet. 

If you compile with structure packing (/zp2, /zp4, /zp8) or use the "pack" pragma to specify a packing value 
other than 1, and you have structures that contain other structures, field offsets and structure sizes may be 
different depending on the contents of the structures. 

In version 9.01, the new Windows Supervisor now has 32 user-defined callbacks. If you have any 
user-defined callbacks in your Windows program, you must recompile because the constant definitions 
have changed. 

In version 9.0, the compiler will not use FS by default to avoid conflicts with new operating systems (OS/2 
2.0, PenPoint, Windows NT). This will cause compile errors if you have defined a pragma that uses the FS 
register. 

In version 8.5, the compiler was changed so that it by default does not save and restore segment registers 
across function calls. This is to solve problems that occur where a segment register is saved and restored in 
a function that tries to free the segment. When the segment register is popped from the stack in the 
epilogue, a general protection exception occurs because the selector is no longer valid. In order to provide 
backward compatibility with existing code, we have added a "-r" option that will cause the compiler to save 
and restore segment registers across calls. The C run-time library has been compiled with the "-r" option so 
that it will work should you choose to compile your application with the same option. 

The packing algorithm was also changed in version 8.5. If you are using one of the "-zp2, -zp4, or -zp8" 
options to pack structures, you must recompile your application. The packing algorithm has been changed 
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so that the minimum number of slack bytes are inserted into structures to align fields onto their required 
alignment. 

6.23 Major Differences from Watcom C9.0/386 

• Windows 3.1 SDK components 

• Support for Windows 3.1 DLLs 

• On-line Watcom C Library Reference help file for OS/2 2.0. Help can be accessed by issuing the 
command "VIEW WATCOMC". The command can be followed by a topic, e.g. VIEW 
WATCOMC PRINTF. 

Command Line Options added to Watcom C9.0/386 

4r Use register calling conventions and optimize for 486. 

4s Use stack calling conventions and optimize for 486. 

ee Generate a call to_EPI at the end of a function 

ep{=number} Generate a call to_PRO at the start of a function 

oe In-line user defined functions. 

or Reorder instructions to take advantage of 486 pipelining. 

zff Allows the FS register to be used by the code generator for far pointers. 

zfp Disallows use of the FS register. This is the default in flat memory model, because 

operating systems are now using FS to point to important information, (e.g. OS/2 2.0, 
PenPoint, Windows NT). 

Z.m Places each function into a separate segment. This will allow for smart linking. 

6.24 Major Differences from Watcom C8.5/386 

Several major items have been added to Watcom C9.0 /386. They are: 

• 486 instruction selection 

• 486 instruction scheduling 

• Tail recursion elimination 

• Function Mining 

• strcmp function optimized for 486 

• Support for OS/2 2.0 

• New keywords added (_farl6, _Segl6, _Packed, _Cdecl, _Pascal, _System) 

• Linkage pragma for compatibility with IBM C Set/2 

• Based pointers 

• Machine language code sequences can now be entered into pragmas using assembly language 
instead of numeric codes. 
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• Remote debugging over the parallel port using either a "LapLink" cable or a "Flying Dutchman" 
cable. 

• Remote debugging of PenPoint applications 

Command Line Options added to Watcom C8.5/386 

dl+ to generate line number information plus typing information for global symbols and local 

structs and arrays 

ei force all enumerated types to be of type ’int’ 

en emit routine name before prologue 

ez generate PharLap EZ-OMF object file 

fpi287 for programs that run on a system with a 287 

of to generate traceable stack frames 

of+ to generate traceable stack frames for all functions 

om to generate in-line math functions 

p to generate preprocessor output 

pi to generate preprocessor output with #line directives 

pc to generate preprocessor output preserving comments 

pic to generate preprocessor output with #line directives and preserving comments 

r save/restore segment registers across calls 

we treat warnings as errors 

6.25 Major Differences from Watcom C8.0/386 

Several major items were added to Watcom C8.5 /386. They are: 

• Royalty-free 32-bit DOS extender 

• Windows 3.0 support 

• Windows SDK components included 

• Improved optimizations 

• OS/2 hosted version of the compiler 

• The compiler now generates Microsoft format object files by default. Use the Vez’ option to 
generate Phar Lap EZ-OMF object files. 

• More library functions to create higher compatibility with Microsoft C 5.1 and Microsoft C 6.0. 

• Preprocessor output from the compiler 

• Standalone help utility 

• Object module convert utility can convert debugging information into CodeView format 

• Protected-mode version of the linker 

• Debugger support for ADS applications 

• Support for Pharlap 3.0 and Pharlap 4.0 

• Support for Tenberry Software DOS/4G 

• Support for Intel 386/486 Code Builder Kit 

• Support for UNICODE. Literal strings and character constants that are preceded by "L" map code 
page 437 onto UNICODE unless one of the options "-zkO, -zkl, or -zk2" is specified. 
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Command Line Options added to Watcom C8.0/386 

d2 symbolic debugging information 

oc disable "call" followed by "ret" being changed into a "jmp" optimization 

u<name> undefine a pre-defined name 

zc places literal strings in the CODE segment 

zk{0,l,2} double-byte character support 

6.26 Major Differences from Watcom C7.0/386 

Several major items have been added to Watcom C8.0 /386. They are: 

• Linker 

• Librarian 

• Graphics library 

• More library functions to create higher compatibility with Microsoft C 5.1 and Microsoft C 6.0. 
The professional edition also gives you the following most asked for features: 

• Protected-mode version of the compiler 

• Lull-screen source-level debugger 

• Execution profiler 

Protected-mode Compiler and Linker 

The protected-mode version of the compiler "WCC386P.EXE" and linker "WLINKP.EXE" use a DPMI 
compliant DOS extender. This allows you to run the compiler and linker on a normal DOS system or in a 
Windows 3.x DOS box operating in enhanced mode. 
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7 Sybase Open Watcom Public License 


USE OF THE SYBASE OPEN WATCOM SOFTWARE DESCRIBED BELOW ("SOFTWARE") IS 
SUBJECT TO THE TERMS AND CONDITIONS SET FORTH IN THE SYBASE OPEN 
WATCOM PUBLIC LICENSE SET FORTH BELOW ("LICENSE"). YOU MAY NOT USE THE 
SOFTWARE IN ANY MANNER UNLESS YOU ACCEPT THE TERMS AND CONDITIONS OF 
THE LICENSE. YOU INDICATE YOUR ACCEPTANCE BY IN ANY MANNER USING 
(INCLUDING WITHOUT LIMITATION BY REPRODUCING, MODIFYING OR 
DISTRIBUTING) THE SOFTWARE. IF YOU DO NOT ACCEPT ALL OF THE TERMS AND 
CONDITIONS OF THE LICENSE, DO NOT USE THE SOFTWARE IN ANY MANNER. 

Sybase Open Watcom Public License version 1.0 

1. General; Definitions. This License applies only to the following software programs: the open source 
versions of Sybase’s Watcom C/C++ and Fortran compiler products ("Software"), which are modified 
versions of, with significant changes from, the last versions made commercially available by Sybase. As 
used in this License; 

1.1 "Applicable Patent Rights" mean: (a) in the case where Sybase is the grantor of rights, (i) claims of 
patents that are now or hereafter acquired, owned by or assigned to Sybase and (ii) that cover subject matter 
contained in the Original Code, but only to the extent necessary to use, reproduce and/or distribute the 
Original Code without infringement; and (b) in the case where You are the grantor of rights, (i) claims of 
patents that are now or hereafter acquired, owned by or assigned to You and (ii) that cover subject matter in 
Your Modifications, taken alone or in combination with Original Code. 

1.2 "Contributor" means any person or entity that creates or contributes to the creation of Modifications. 

1.3 "Covered Code" means the Original Code, Modifications, the combination of Original Code and any 
Modifications, and/or any respective portions thereof. 

1.4 "Deploy" means to use, sublicense or distribute Covered Code other than for Your internal research and 
development (R&D) and/or Personal Use, and includes without limitation, any and all internal use or 
distribution of Covered Code within Your business or organization except for R&D use and/or Personal 
Use, as well as direct or indirect sublicensing or distribution of Covered Code by You to any third party in 
any form or manner. 

1.5 "Larger Work" means a work which combines Covered Code or portions thereof with code not 
governed by the terms of this License. 

1.6 "Modifications" mean any addition to, deletion from, and/or change to, the substance and/or structure of 
the Original Code, any previous Modifications, the combination of Original Code and any previous 
Modifications, and/or any respective portions thereof. When code is released as a series of files, a 
Modification is: (a) any addition to or deletion from the contents of a file containing Covered Code; and/or 
(b) any new file or other representation of computer program statements that contains any part of Covered 
Code. 

1.7 "Original Code" means (a) the Source Code of a program or other work as originally made available by 
Sybase under this License, including the Source Code of any updates or upgrades to such programs or 
works made available by Sybase under this License, and that has been expressly identified by Sybase as 
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such in the header file(s) of such work; and (b) the object code compiled from such Source Code and 
originally made available by Sybase under this License. 

1.8 "Personal Use" means use of Covered Code by an individual solely for his or her personal, private and 
non-commercial purposes. An individual’s use of Covered Code in his or her capacity as an officer, 
employee, member, independent contractor or agent of a corporation, business or organization (commercial 
or non-commercial) does not qualify as Personal Use. 

1.9 "Source Code" means the human readable form of a program or other work that is suitable for making 
modifications to it, including all modules it contains, plus any associated interface definition files, scripts 
used to control compilation and installation of an executable (object code). 

1.10 "You" or "Your" means an individual or a legal entity exercising rights under this License. For legal 
entities, "You" or "Your" includes any entity which controls, is controlled by, or is under common control 
with. You, where "control" means (a) the power, direct or indirect, to cause the direction or management of 
such entity, whether by contract or otherwise, or (b) ownership of fifty percent (50%) or more of the 
outstanding shares or beneficial ownership of such entity. 

2. Permitted Uses; Conditions & Restrictions.Subject to the terms and conditions of this License, Sybase 
hereby grants You, effective on the date You accept this License and download the Original Code, a 
world-wide, royalty-free, non-exclusive license, to the extent of Sybase’s Applicable Patent Rights and 
copyrights covering the Original Code, to do the following: 

2.1 You may use, reproduce, display, perform, modify and distribute Original Code, with or without 
Modifications, solely for Your internal research and development and/or Personal Use, provided that in 
each instance: 

(a) You must retain and reproduce in all copies of Original Code the copyright and other proprietary notices 
and disclaimers of Sybase as they appear in the Original Code, and keep intact all notices in the Original 
Code that refer to this License; and 

(b) You must retain and reproduce a copy of this License with every copy of Source Code of Covered Code 
and documentation You distribute, and You may not offer or impose any terms on such Source Code that 
alter or restrict this License or the recipients’ rights hereunder, except as permitted under Section 6. 

(c) Whenever reasonably feasible you should include the copy of this License in a click-wrap format, which 
requires affirmative acceptance by clicking on an "I accept" button or similar mechanism. If a click-wrap 
format is not included, you must include a statement that any use (including without limitation 
reproduction, modification or distribution) of the Software, and any other affirmative act that you define, 
constitutes acceptance of the License, and instructing the user not to use the Covered Code in any manner if 
the user does not accept all of the terms and conditions of the License. 

2.2 You may use, reproduce, display, perform, modify and Deploy Covered Code, provided that in each 
instance: 

(a) You must satisfy all the conditions of Section 2.1 with respect to the Source Code of the Covered Code; 

(b) You must duplicate, to the extent it does not already exist, the notice in Exhibit A in each file of the 
Source Code of all Your Modifications, and cause the modified files to carry prominent notices stating that 
You changed the files and the date of any change; 

(c) You must make Source Code of all Your Deployed Modifications publicly available under the terms of 
this License, including the license grants set forth in Section 3 below, for as long as you Deploy the 
Covered Code or twelve (12) months from the date of initial Deployment, whichever is longer. You should 
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preferably distribute the Source Code of Your Deployed Modifications electronically (e.g. download from 
a web site); 

(d) if You Deploy Covered Code in object code, executable form only. You must include a prominent 
notice, in the code itself as well as in related documentation, stating that Source Code of the Covered Code 
is available under the terms of this License with information on how and where to obtain such Source 
Code; and 

(e) the object code form of the Covered Code may be distributed under Your own license agreement, 
provided that such license agreement contains terms no less protective of Sybase and each Contributor than 
the terms of this License, and stating that any provisions which differ from this License are offered by You 
alone and not by any other party. 

2.3 You expressly acknowledge and agree that although Sybase and each Contributor grants the licenses to 
their respective portions of the Covered Code set forth herein, no assurances are provided by Sybase or any 
Contributor that the Covered Code does not infringe the patent or other intellectual property rights of any 
other entity. Sybase and each Contributor disclaim any liability to You for claims brought by any other 
entity based on infringement of intellectual property rights or otherwise. As a condition to exercising the 
rights and licenses granted hereunder. You hereby assume sole responsibility to secure any other 
intellectual property rights needed, if any. For example, if a third party patent license is required to allow 
You to distribute the Covered Code, it is Your responsibility to acquire that license before distributing the 
Covered Code. 

3. Your Grants. In consideration of, and as a condition to, the licenses granted to You under this License, 
You hereby grant to Sybase and all third parties a non-exclusive, royalty-free license, under Your 
Applicable Patent Rights and other intellectual property rights (other than patent) owned or controlled by 
You, to use, reproduce, display, perform, modify, distribute and Deploy Your Modifications of the same 
scope and extent as Sybase’s licenses under Sections 2.1 and 2.2. 

4. Larger Works. You may create a Larger Work by combining Covered Code with other code not 
governed by the terms of this License and distribute the Larger Work as a single product. In each such 
instance. You must make sure the requirements of this License are fulfilled for the Covered Code or any 
portion thereof. 

5. Limitations on Patent License. Except as expressly stated in Section 2, no other patent rights, express or 
implied, are granted by Sybase herein. Modifications and/or Larger Works may require additional patent 
licenses from Sybase which Sybase may grant in its sole discretion. 

6. Additional Terms. You may choose to offer, and to charge a fee for, warranty, support, indemnity or 
liability obligations and/or other rights consistent with this License ("Additional Terms") to one or more 
recipients of Covered Code. However, You may do so only on Your own behalf and as Your sole 
responsibility, and not on behalf of Sybase or any Contributor. You must obtain the recipient’s agreement 
that any such Additional Terms are offered by You alone, and You hereby agree to indemnify, defend and 
hold Sybase and every Contributor harmless for any liability incurred by or claims asserted against Sybase 
or such Contributor by reason of any such Additional Terms. 

7. Versions of the License. Sybase may publish revised and/or new versions of this License from time to 
time. Each version will be given a distinguishing version number. Once Original Code has been published 
under a particular version of this License, You may continue to use it under the terms of that version. You 
may also choose to use such Original Code under the terms of any subsequent version of this License 
published by Sybase. No one other than Sybase has the right to modify the terms applicable to Covered 
Code created under this License. 
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8. NO WARRANTY OR SUPPORT. The Covered Code may contain in whole or in part pre-release, 
untested, or not fully tested works. The Covered Code may contain errors that could cause failures or loss 
of data, and may be incomplete or contain inaccuracies. You expressly acknowledge and agree that use of 
the Covered Code, or any portion thereof, is at Your sole and entire risk. THE COVERED CODE IS 
PROVIDED "AS IS" AND WITHOUT WARRANTY, UPGRADES OR SUPPORT OF ANY KIND AND 
SYBASE AND SYBASE’S LICENSOR!S) (COLLECTIVELY REFERRED TO AS "SYBASE" FOR 
THE PURPOSES OF SECTIONS 8 AND 9) AND ALL CONTRIBUTORS EXPRESSLY DISCLAIM 
ALL WARRANTIES AND/OR CONDITIONS, EXPRESS OR IMPLIED, INCLUDING, BUT NOT 
LIMITED TO, THE IMPLIED WARRANTIES AND/OR CONDITIONS OF MERCHANTABILITY, OF 
SATISFACTORY QUALITY, OF FITNESS FOR A PARTICULAR PURPOSE, OF ACCURACY, OF 
QUIET ENJOYMENT, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. SYBASE AND 
EACH CONTRIBUTOR DOES NOT WARRANT AGAINST INTERFERENCE WITH YOUR 
ENJOYMENT OF THE COVERED CODE, THAT THE FUNCTIONS CONTAINED IN THE 
COVERED CODE WILL MEET YOUR REQUIREMENTS, THAT THE OPERATION OF THE 
COVERED CODE WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT DEFECTS IN THE 
COVERED CODE WILL BE CORRECTED. NO ORAL OR WRITTEN INFORMATION OR ADVICE 
GIVEN BY SYBASE, A SYBASE AUTHORIZED REPRESENTATIVE OR ANY CONTRIBUTOR 
SHALL CREATE A WARRANTY. You acknowledge that the Covered Code is not intended for use in the 
operation of nuclear facilities, aircraft navigation, communication systems, or air traffic control machines in 
which case the failure of the Covered Code could lead to death, personal injury, or severe physical or 
environmental damage. 

9. LIMITATION OF LIABILITY. TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT 
SHALL SYBASE OR ANY CONTRIBUTOR BE LIABLE FOR ANY DIRECT, INCIDENTAL, 
SPECIAL, INDIRECT, CONSEQUENTIAL OR OTHER DAMAGES OF ANY KIND ARISING OUT 
OF OR RELATING TO THIS LICENSE OR YOUR USE OR INABILITY TO USE THE COVERED 
CODE, OR ANY PORTION THEREOF, WHETHER UNDER A THEORY OF CONTRACT, 
WARRANTY, TORT (INCLUDING NEGLIGENCE), PRODUCTS LIABILITY OR OTHERWISE, 
EVEN IF SYBASE OR SUCH CONTRIBUTOR HAS BEEN ADVISED OF THE POSSIBILITY OF 
SUCH DAMAGES, AND NOTWITHSTANDING THE FAILURE OF ESSENTIAL PURPOSE OF ANY 
REMEDY. SOME JURISDICTIONS DO NOT ALLOW THE LIMITATION OF LIABILITY OF 
INCIDENTAL OR CONSEQUENTIAL OR OTHER DAMAGES OF ANY KIND, SO THIS 
LIMITATION MAY NOT APPLY TO YOU. In no event shall Sybase’s or any Contributor’s total liability 
to You for all damages (other than as may be required by applicable law) under this License exceed the 
amount of five hundred dollars ($500.00). 


10. Trademarks. This License does not grant any rights to use the trademarks or trade names "Sybase" or 
any other trademarks or trade names belonging to Sybase (collectively "Sybase Marks") or to any 
trademark or trade name belonging to any ContributorC'Contributor Marks"). No Sybase Marks or 
Contributor Marks may be used to endorse or promote products derived from the Original Code or Covered 
Code other than with the prior written consent of Sybase or the Contributor, as applicable. 

11. Ownership. Subject to the licenses granted under this License, each Contributor retains all rights, title 
and interest in and to any Modifications made by such Contributor. Sybase retains all rights, title and 
interest in and to the Original Code and any Modifications made by or on behalf of Sybase ("Sybase 
Modifications"), and such Sybase Modifications will not be automatically subject to this License. Sybase 
may, at its sole discretion, choose to license such Sybase Modifications under this License, or on different 
terms from those contained in this License or may choose not to license them at all. 


12. Termination. 


12.1 Termination. This License and the rights granted hereunder will terminate: 
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(a) automatically without notice if You fail to comply with any term(s) of this License and fail to cure such 
breach within 30 days of becoming aware of such breach; 

(b) immediately in the event of the circumstances described in Section 13.5(b); or 

(c) automatically without notice if You, at any time during the term of this License, commence an action 
for patent infringement (including as a cross claim or counterclaim) against Sybase or any Contributor. 

12.2 Effect of Termination. Upon termination. You agree to immediately stop any further use, 
reproduction, modification, sublicensing and distribution of the Covered Code and to destroy all copies of 
the Covered Code that are in your possession or control. All sublicenses to the Covered Code that have 
been properly granted prior to termination shall survive any termination of this License. Provisions which, 
by their nature, should remain in effect beyond the termination of this License shall survive, including but 
not limited to Sections 3, 5, 8, 9, 10, 11, 12.2 and 13. No party will be liable to any other for compensation, 
indemnity or damages of any sort solely as a result of terminating this License in accordance with its terms, 
and termination of this License will be without prejudice to any other right or remedy of any party. 

13. Miscellaneous. 

13.1 Government End Users. The Covered Code is a "commercial item" as defined in FAR 2.101. 
Government software and technical data rights in the Covered Code include only those rights customarily 
provided to the public as defined in this License. This customary commercial license in technical data and 
software is provided in accordance with FAR 12.211 (Technical Data) and 12.212 (Computer Software) 
and, for Department of Defense purchases, DFAR 252.227-7015 (Technical Data — Commercial Items) and 
227.7202-3 (Rights in Commercial Computer Software or Computer Software Documentation). 
Accordingly, all U.S. Government End Users acquire Covered Code with only those rights set forth herein. 

13.2 Relationship of Parties. This License will not be construed as creating an agency, partnership, joint 
venture or any other form of legal association between or among you, Sybase or any Contributor, and You 
will not represent to the contrary, whether expressly, by implication, appearance or otherwise. 

13.3 Independent Development. Nothing in this License will impair Sybase’s or any Contributor’s right to 
acquire, license, develop, have others develop for it, market and/or distribute technology or products that 
perform the same or similar functions as, or otherwise compete with. Modifications, Larger Works, 
technology or products that You may develop, produce, market or distribute. 

13.4 Waiver; Construction. Failure by Sybase or any Contributor to enforce any provision of this License 
will not be deemed a waiver of future enforcement of that or any other provision. Any law or regulation 
which provides that the language of a contract shall be construed against the drafter will not apply to this 
License. 

13.5 Severability, (a) If for any reason a court of competent jurisdiction finds any provision of this 
License, or portion thereof, to be unenforceable, that provision of the License will be enforced to the 
maximum extent permissible so as to effect the economic benefits and intent of the parties, and the 
remainder of this License will continue in full force and effect, (b) Notwithstanding the foregoing, if 
applicable law prohibits or restricts You from fully and/or specifically complying with Sections 2 and/or 3 
or prevents the enforceability of either of those Sections, this License will immediately terminate and You 
must immediately discontinue any use of the Covered Code and destroy all copies of it that are in your 
possession or control. 

13.6 Dispute Resolution. Any litigation or other dispute resolution between You and Sybase relating to this 
License shall take place in the Northern District of California, and You and Sybase hereby consent to the 
personal jurisdiction of, and venue in, the state and federal courts within that District with respect to this 
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License. The application of the United Nations Convention on Contracts for the International Sale of 
Goods is expressly excluded. 

13.7 Entire Agreement; Governing Law. This License constitutes the entire agreement between the parties 
with respect to the subject matter hereof. This License shall be governed by the laws of the United States 
and the State of California, except that body of California law concerning conflicts of law. 

Where You are located in the province of Quebec, Canada, the following clause applies; The parties 
hereby confirm that they have requested that this License and all related documents be drafted in English. 
Les parties ont exige que le present contrat et tous les documents connexes soient rediges en anglais. 

EXHIBIT A. 


Portions Copyright (c) 1983-2002 Sybase, Inc. All Rights Reserved. 

This file contains Original Code and/or Modifications of 
Original Code as defined in and that are subject to the 
Sybase Open Watcom Public License version 1.0 (the 
'License'). You may not use this file except in compliance 
with the License. BY USING THIS FILE YOU AGREE TO ALL 
TERMS AND CONDITIONS OF THE LICENSE. A copy of the License 
is provided with the Original Code and Modifications, and 
is also available at www.sybase.com/developer/opensource. 

The Original Code and all software distributed under the 
License are distributed on an 'AS IS' basis, WITHOUT 
WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, AND SYBASE 
AND ALL CONTRIBUTORS HEREBY DISCLAIM ALL SUCH WARRANTIES, 

INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF 
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, QUIET 
ENJOYMENT OR NON-INFRINGEMENT. Please see the License for 
the specific language governing rights and limitations 
under the License. 
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8 Trouble-Shooting 


This section is intended to provide you with help on some of the common (and not so common) problems 
that users have encountered when trying to run the software. 

Symptom: The message "Cannot connect to batch spawn server" is displayed. 

Resolution: This message occurs when the Open Watcom IDE is trying to connect to the batch server. 

The batch server is a program that is employed by the Open Watcom IDE to run "makes" in 
the background. There are several reasons why you may receive this message. 

• Installing Under the Host System and Selecting "Modify System Files" During 
Install 

For the IDE to run properly under a particular host operating system, the install 
program must be run on that system. 

It is very important to check the "Modify System Files" when running the install on 
the host platform. Otherwise, changes required in the host system’s environment will 
not be made. If this is the problem, you should re-install under the host environment 
and select this option. 

• System stability 

If for some reason the operating system has become unstable, the IDE may have 
trouble connecting to the batch server. This can happen if you have run a badly 
behaved application that caused an exception, for example a page fault. If this is the 
problem, you should shutdown the operating system and reboot. 

• Running Windows 3.1 in Enhanced Mode 

The IDE requires at least version 3.1 of Windows to be running, in enhanced mode. 
Windows 3.0 is not supported. 

Running Third-Party Shell Programs 

If you run 4DOS.COM or some other shell besides COMMAND.COM, you must change the 
"BATCHBOX.PIF" file accordingly. You can do this using the standard Windows PIF editor. 

Running Virus Checkers 

If you are running Central Point’s PCTOOLS, VWATCH, or some other virus checker, it may be 
conflicting with our batch server. To isolate the problem, uninstall the virus checker and see if the IDE 
works again. 

386 Enhanced "Exclusive in Foreground" Option 

If you go to the Windows Control Panel, "Scheduling Options" of "386 Enhanced", and the "Exclusive in 
Foreground" checkbox is checked, uncheck it. This causes our batch server to starve under Windows. 
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Changes to the SYSTEM.INI File 

The WDEBUG.386 driver is required to be installed in the [386Enh] section of SYSTEM.INI. This should 
have been done automatically by the WATCOM install program when the software was installed under the 
host environment and the "modify system files" option was selected. 

It has been reported that the line 

OverlappedIO=on 

not appear in the SYSTEM.INI file. 

It appears the user’s problem was related to conflicts with other devices installed in the SYSTEM.INI file. 
On its own, the above line does not appear to affect the execution of the IDE. 

It has been reported that the line 

NoEMMDriver=ON 

not appear in the SYSTEM.INI file. It will prevent a link from succeeding in the IDE. 

8.1 Win-OS/2 and OS/2 Specific 

Installing for a Win-OS/2 Host 

For Win-OS/2, the install must be run under OS/2 and "Modify System Files" must be selected. This 
installs the batch server under OS/2, which we require under Win-OS/2. Then the Windows install 
program should be run under Win-OS/2 so that the program groups will be created. "Modify System Files" 
should also be checked for the Win-OS/2 install. 

Named Pipe Conflicts 

Under OS/2, the batch server is a named pipe. Win-OS/2 uses the OS/2 named pipe for the batch server, 
hence the OS/2 IDE will conflict with the Win-OS/2 IDE if they are both running. If this is the problem, 
you should run only one of the OS/2 and Win-OS/2 IDE, not both at the same time. 
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Preface 

The Open Watcom FORTRAN 77 Optimizing Compiler is an implementation of the American National 
Standard programming language FORTRAN, ANSI X3.9-1978, commonly referred to as FORTRAN 77. 
The language level supported by this compiler includes the full language definition as well as significant 
extensions to the language. 

This manual describes the Open Watcom FORTRAN 77 Graphics Library. This library of routines is used 
to create graphical images such as lines and circles on the screen. Routines are also provided for displaying 
text. 

This book was produced with the Open Watcom GML electronic publishing system, a software tool 
developed by WATCOM. In this system, writers use an ASCII text editor to create source files containing 
text annotated with tags. These tags label the structural elements of the document, such as chapters, 
sections, paragraphs, and lists. The Open Watcom GML software, which runs on a variety of operating 
systems, interprets the tags to format the text into a form such as you see here. Writers can produce output 
for a variety of printers, including laser printers, using separately specified layout directives for such things 
as font selection, column width and height, number of columns, etc. The result is type-set quality copy 
containing integrated text and graphics. 
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1 Graphics Library 


The Open Watcom FORTRAN 77 Graphics Library consists of a large number of routines that provide 
graphical image support under DOS and QNX. This chapter provides an overview of this support. The 
following topics are discussed. 

• Graphics Routines 

• Graphics Adapters 

• Classes of Graphics Routines 

1. Environment Routines 

2. Coordinate System Routines 

3. Attribute Routines 

4. Drawing Routines 

5. Text Routines 

6. Graphics Text Routines 

7. Image Manipulation Routines 

8. Font Manipulation Routines 

9. Presentation Graphics Routines 

Display Routines 
Analyze Routines 
Utility Routines 


• Include Files 


1.1 Graphics Routines 

Graphics routines are used to display graphical images such as lines and circles upon the computer screen. 
Routines are also provided for displaying text along with the graphics output. 

1.2 Graphics Adapters 

Support is provided for both color and monochrome screens which are connected to the computer using any 
of the following graphics adapters: 

• IBM Monochrome Display/Printer Adapter (MDPA) 

• IBM Color Graphics Adapter (CGA) 

• IBM Enhanced Graphics Adapter (EGA) 

• IBM Multi-Color Graphics Array (MCGA) 
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• IBM Video Graphics Array (VGA) 

• Hercules Monochrome Adapter 

• SuperVGA adapters (SVGA) supplied by various manufacturers 

1.3 Classes of Graphics Routines 

The routines in the Open Watcom FORTRAN 77 Graphics Library can be organized into a number of 
classes: 

Environment Routines 

These routines deal with the hardware environment. 

Coordinate System Routines 

These routines deal with coordinate systems and mapping coordinates from one system to 
another. 

Attribute Routines 

These routines control the display of graphical images. 

Drawing Routines 

These routines display graphical images such as lines and ellipses. 

Text Routines 

These routines deal with displaying text in both graphics and text modes. 

Graphics Text Routines 

These routines deal with displaying graphics text. 

Image Manipulation Routines 

These routines store and retrieve screen images. 

Font Manipulation Routines 

These routines deal with displaying font based text. 

Presentation Graphics Routines 

These routines deal with displaying presentation graphics elements such as bar charts and 
pie charts. 

The following subsections describe these routine classes in more detail. Each routine in the class is noted 
with a brief description of its purpose. 

1.3.1 Environment Routines 

These routines deal with the hardware environment. The _ getvideoconf ig routine returns information 
about the current video mode and the hardware configuration. The _ setvideomode routine selects a 
new video mode. 

Some video modes support multiple pages of screen memory. The visual page (the one displayed on the 
screen) may be different than the active page (the one to which objects are being written). 
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The following routines are defined: 


_getactivepcige 

_get\’ideoconfig 

_get\’isualpage 

_grstatus 

_setactivepage 

_settextrows 

_setvideomode 

_setvideomoderows 

_setvisualpage 


get the number of the current active graphics page 

get information about the graphics configuration 

get the number of the current visual graphics page 

get the status of the most recently called graphics library routine 

set the active graphics page (the page to which graphics objects are 

drawn) 

set the number of rows of text displayed on the screen 
select the video mode to be used 

select the video mode and the number of text rows to be used 
set the visual graphics page (the page displayed on the screen) 


1.3.2 Coordinate System Routines 

These routines deal with coordinate systems and mapping coordinates from one system to another. The 
Open Watcom FORTRAN 77 Graphics Library supports three coordinate systems: 

1. Physical coordinates 

2. View coordinates 

3. Window coordinates 

Physical coordinates match the physical dimensions of the screen. The physical origin, denoted (0,0), is 
located at the top left corner of the screen. A pixel to the right of the origin has a positive x-coordinate and 
a pixel below the origin will have a positive y-coordinate. The x- and y-coordinates will never be negative 
values. 


The view coordinate system can be defined upon the physical coordinate system by moving the origin from 
the top left corner of the screen to any physical coordinate (see the _ setvieworg routine). In the view 
coordinate system, negative x- and y-coordinates are allowed. The scale of the view and physical 
coordinate systems is identical (both are in terms of pixels). 

The window coordinate system is defined in terms of a range of user-specified values (see the 
_ setwindow routine). These values are scaled to map onto the physical coordinates of the screen. This 
allows for consistent pictures regardless of the resolution (number of pixels) of the screen. 

The following routines are defined: 


_getcliprgn 

_getphyscoord 

_get\’iewcoord 

_get\’iewcoord_w 

_get\’iewcoord_wxy 

_getwindowcoord 

jsetcliprgn 

_setvieworg 

jsetviewport 

jsetwindow 


get the boundary of the current clipping region 
get the physical coordinates of a point in view coordinates 
get the view coordinates of a point in physical coordinates 
get the view coordinates of a point in window coordinates 
get the view coordinates of a point in window coordinates 
get the window coordinates of a point in view coordinates 
set the boundary of the clipping region 

set the position to be used as the origin of the view coordinate system 
set the boundary of the clipping region and the origin of the view 
coordinate system 

define the boundary of the window coordinate system 
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1.3.3 Attribute Routines 


These routines control the display of graphical images such as lines and circles. Lines and figures are 
drawn using the current color (see the _ setcolor routine), the current line style (see the 
_ setlinestyle routine), the current fill mask (see the_ setf illmask routine), and the current 
plotting action (see the _ setplotaction routine). 

The following routines are defined: 


_getarcinfo 

_getbkcolor 

_getcolor 

_getfillmask 

_getlinestyle 

_getplotaction 

_remapa Up alette 

_remappalette 

_selectpalette 

_setbkcolor 

_setcolor 

_setfillmask 

_setlinestyle 

_setplotaction 


get the endpoints of the most recently drawn arc 

get the background color 

get the current color 

get the current fill mask 

get the current line style 

get the current plotting action 

assign colors for all pixel values 

assign color for one pixel value 

select a palette 

set the background color 

set the current color 

set the current fill mask 

set the current line style 

set the current plotting action 


1.3.4 Drawing Routines 

These routines display graphical images such as lines and ellipses. Routines exist to draw straight lines (see 
the _ lineto routines), rectangles (see the_ rectangle routines), polygons (see the_ polygon 
routines), ellipses (see the _ ellipse routines), elliptical arcs (see the_ arc routines) and pie-shaped 
wedges from ellipses (see the _ pie routines). 

These figures are drawn using the attributes described in the previous section. The routines ending with _ w 
or _ wxy use the window coordinate system; the others use the view coordinate system. 

The following routines are defined: 


_arc 

_arc_w 

_arc_wxy 

_clearscreen 

_ellipse 

_ellipse_w 

_ellipse_wxy 

Jloodfill 

_Jloodfill_w 

_getcurrentposition 

_getcurrentposition_w 

_getpixel 

_getpixel_w 

_lineto 


draw an arc 

draw an arc using window coordinates 

draw an arc using window coordinates 

clear the screen and fill with the background color 

draw an ellipse 

draw an ellipse using window coordinates 
draw an ellipse using window coordinates 
fill an area of the screen with the current color 

fill an area of the screen in window coordinates with the current color 

get the coordinates of the current output position 

get the window coordinates of the current output position 

get the color of the pixel at the specified position 

get the color of the pixel at the specified position in window 

coordinates 

draw a line from the current position to a specified position 
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_lineto_w 

_moveto 

_moveto_w 

_pie 

_pie_w 

_pie_wxy 

_polygon 

_polygon_w 

_polygon_wxy 

_rectangle 

_rectangle_w 

_rectangle_wxy 

_setpixel 

_setpixel_w 


draw a line from the current position to a specified position in window 
coordinates 

set the current output position 

set the current output position using window coordinates 
draw a wedge of a "pie" 

draw a wedge of a "pie" using window coordinates 
draw a wedge of a "pie" using window coordinates 
draw a polygon 

draw a polygon using window coordinates 
draw a polygon using window coordinates 
draw a rectangle 

draw a rectangle using window coordinates 
draw a rectangle using window coordinates 
set the color of the pixel at the specified position 

set the color of the pixel at the specified position in window coordinates 


1.3.5 Text Routines 

These routines deal with displaying text in both graphics and text modes. This type of text output can be 
displayed in only one size. 


This text is displayed using the _ out text and_ outmem routines. The output position for text follows 
the last text that was displayed or can be reset (see the _ settextposition routine). Text windows can 
be created (see the _ settextwindow routine) in which the text will scroll. Text is displayed with the 
current text color (see the _ settextcolor routine). 


The following routines are defined: 


_clearscreen 

_displaycursor 

_getbkcolor 

_gettextcolor 

_gettextcursor 

_gettextposition 

_gettextwindow 

_outmem 

_outtext 

jscrolltextwindow 

_setbkcolor 

_settextcolor 

_settextcursor 

_settextposition 

_settextwindow 

_wrapon 


clear the screen and fill with the background color 

determine whether the cursor is to be displayed after a graphics routine 

completes execution 

get the background color 

get the color used to display text 

get the shape of the text cursor 

get the current output position for text 

get the boundary of the current text window 

display a text string of a specified length 

display a text string 

scroll the contents of the text window 

set the background color 

set the color used to display text 

set the shape of the text cursor 

set the output position for text 

set the boundary of the region used to display text 

permit or disallow wrap-around of text in a text window 


1.3.6 Graphics Text Routines 

These routines deal with displaying graphics text. Graphics text is displayed as a sequence of line 
segments, and can be drawn in different sizes (see the _ setcharsize routine), with different 
orientations (see the _ settextorient routine) and alignments (see the_ settextalign routine). 
The routines ending with _ w use the window coordinate system; the others use the view coordinate system. 
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The following routines are defined: 


_gettextextent 

_gettextsettings 

_grtext 

_grtext_w 

_setcharsize 

_setcharsize_w 

_setcharspacing 

_setcharspacing_w 

_settextalign 

_settextorient 

_settextpath 


get the bounding rectangle for a graphics text string 

get information about the current settings used to display graphics text 

display graphics text 

display graphics text using window coordinates 

set the character size used to display graphics text 

set the character size in window coordinates used to display graphics 

text 

set the character spacing used to display graphics text 

set the character spacing in window coordinates used to display 

graphics text 

set the alignment used to display graphics text 
set the orientation used to display graphics text 
set the path used to display graphics text 


1.3.7Image Manipulation Routines 

These routines are used to transfer screen images. The _ get image routine transfers a rectangular image 
from the screen into memory. The _ put image routine transfers an image from memory back onto the 
screen. The routines ending with _ w or_ wxy use the window coordinate system; the others use the view 
coordinate system. 

The following routines are defined: 


_getimcige 

_getimage_w 

_getimage_wxy 

_imagesize 

_imagesize_w 

_imagesize_wxy 

_putimage 

_putimage_w 


store an image of an area of the screen into memory 

store an image of an area of the screen in window coordinates into 

memory 

store an image of an area of the screen in window coordinates into 
memory 

get the size of a screen area 

get the size of a screen area in window coordinates 
get the size of a screen area in window coordinates 
display an image from memory on the screen 

display an image from memory on the screen using window coordinates 


1.3.8 Font Manipulation Routines 

These routines are for the display of fonts compatible with Microsoft Windows. Fonts are contained in 
files with an extension of . FON. Before font based text can be displayed, the fonts must be registered with 
the _ registerf onts routine, and a font must be selected with the_ setfont routine. 

The following routines are defined: 


_getfontinfo 

_getgtextextent 

_getgtext\’ector 

_outgtext 

jregisterfonts 

_setfont 

_setgtextvector 

_un re gist erf on ts 


get information about the currently selected font 

get the length in pixels of a text string 

get the current value of the font text orientation vector 

display a string of text in the current font 

initialize the font graphics system 

select a font from among the registered fonts 

set the font text orientation vector 

frees memory allocated by the font graphics system 
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1.3.9 Presentation Graphics Routines 

These routines provide a system for displaying and manipulating presentation graphics elements such as bar 
charts and pie charts. The presentation graphics routines can be further divided into three classes: 

Display Routines 

These routines are for the initialization of the presentation graphics system and the 
displaying of charts. 

Analyze Routines 

These routines calculate default values for chart elements without actually displaying the 
chart. 


Utility Routines 

These routines provide additional support to control the appearance of presentation 
graphics elements. 

The following subsections describe these routine classes in more detail. Each routine in the class is noted 
with a brief description of its purpose. 


1.3.9.1 Display Routines 

These routines are for the initialization of the presentation graphics system and the displaying of charts. 

The _ pg_ initchart routine initializes the system and should be the first presentation graphics routine 
called. The single-series routines display a single set of data on a chart; the multi-series routines (those 
ending with ms) display several sets of data on the same chart. 

The following routines are defined: 


_pg_chart 

display a 

_pg_chartms 

display a 

_pg_chartpie 

display a 

_pg_chartscatter 

display a 

_pg_chartscatterms 

display a 

_j)g_defaultchart 

initialize 

_pg_initchart 

initialize 


bar, column or line chart 
multi-series bar, column or line chart 
pie chart 
scatter chart 

multi-series scatter chart 

the chart environment for a specific chart type 

the presentation graphics system 


1.3.9.2 Analyze Routines 


These routines calculate default values for chart elements without actually displaying the chart. The 
routines ending with ms analyze multi-series charts; the others analyze single-series charts. 

The following routines are defined: 


_pg_analyzechart 

_pg_analyzechartms 

_pg_analyzepie 

_pg_analyzescatter 

_pg_analyzescatterms 


analyze a bar, column or line chart 

analyze a multi-series bar, column or line chart 

analyze a pie chart 

analyze a scatter chart 

analyze a multi-series scatter chart 
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1.3.9.3 Utility Routines 

These routines provide additional support to control the appearance of presentation graphics elements. 
The following routines are defined: 


_pg_getchardef 

_j)g_getpalette 

_pg_getstyleset 

jpgjilabelchart 
_pg_resetpalette 
_pg_resetstyleset 
_pg_se tchardef 
_j?g_setpalette 

_pg_setstyleset 

_pg_vlabelchart 


get bit-map definition for a specific character 

get presentation graphics palette (colors, line styles, fill patterns and 

plot characters) 

get presentation graphics style-set (line styles for window borders and 
grid lines) 

display text horizontally on a chart 
reset presentation graphics palette to default values 
reset presentation graphics style-set to default values 
set bit-map definition for a specific character 

set presentation graphics palette (colors, line styles, fill patterns and plot 
characters) 

set presentation graphics style-set (line styles for window borders and 
grid lines) 

display text vertically on a chart 


1.4 Include Files 


All program modules which use the Graphics Library should include the file graphapi . f i . This file 
contains definitions of all the routines in the library. As well, each routine should include graph . f i 
which contains all the structure and constant definitions. 

Modules using the presentation graphics routines should also include the file pgapi . f i . As well, each 
routine should include pg. f i . 
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2 Graphics Library Routines 


This chapter contains, in alphabetical order, descriptions of the routines which comprise the graphics 
library. Each description consists of a number of subsections: 

Synopsis: 

This subsection gives an example of a declaration for the routine, showing the types of the 
routine and its arguments. 

Description: 

This subsection is a description of the routine. 

Returns: 

This subsection describes the return value (if any) for the routine. 

See Also: 

This subsection provides a list of related routines. 

Example: 

This subsection consists of an example program demonstrating the use of the routine. In 
some cases the output from the program is also displayed. 


Classification: 

This subsection provides an indication of where the routine is commonly found. The 
following notation is used: 

PC Graphics These &routiness are part of the PC graphics library. 

Systems: This subsection provides an indication of where the routine is supported. The following 

notation is used: 

DOS This routine is available on both 16-bit DOS and 32-bit extended 

DOS. 

QNX This routine is available on QNX Software Systems’ 16 or 32-bit 

operating systems. 
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arc Routines 


Synopsis: 


Description: 


integer*2 

function 

_ arc( xl, yl, x2, y2. 

integer*2 

xl. 

yi 

x3, y3, x4, y4 ) 

integer*2 

x2, 

y2 


integer*2 

x3. 

y3 


integer*2 

x4. 

y4 


integer*2 

function 

_ arc_ w ( xl, yl, x2, y2. 


x3, y3, x4, y4 ) 

double precision xl, yl 
double precision x2, y2 
double precision x3, y3 
double precision x4, y4 


integer*2 function _ arc_ wxy ( pi, p2, p3, p4 ) 

record /_ wxycoord/ pi 

record /_ wxycoord/ p2 

record /_ wxycoord/ p3 

record /_ wxycoord/ p4 


The _ arc routines draw elliptical arcs. The_ arc routine uses the view coordinate system. The 
_ arc_ w and_ arc_ wxy routines use the window coordinate system. 

The center of the arc is the center of the rectangle established by the points (xl,yl) and (x2,y2). 
The arc is a segment of the ellipse drawn within this bounding rectangle. The arc starts at the point on 
this ellipse that intersects the vector from the centre of the ellipse to the point (x3, y 3) . The arc ends 
at the point on this ellipse that intersects the vector from the centre of the ellipse to the point 
(x4, y4) . The arc is drawn in a counter-clockwise direction with the current plot action using the 
current color and the current line style. 

The following picture illustrates the way in which the bounding rectangle and the vectors specifying the 
start and end points are defined. 
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Returns: 

See Also: 

Example: 


Classification: 

Systems: 


When the coordinates (xl,yl) and (x2,y2) establish a line or a point (this happens when one or 
more of the x-coordinates or y-coordinates are equal), nothing is drawn. 

The current output position for graphics output is set to be the point at the end of the arc that was drawn. 

The _ arc routines return a non-zero value when the arc was successfully drawn; otherwise, zero is 
returned. 

_ ellipse^ pie,_ rectangle^ getarcinfo,_ setcolor,_ setlinestyle, 

_ setplotaction 

include 'graphapi.fi' 
include 'graph.fi' 

call _ setvideomode ( _VRES16C0L0R ) 

call _ arc( 120, 90, 520, 390, 500, 20, 450, 460 ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

produces the following: 



PC Graphics 

_ arc - DOS 
_ arc_ w - DOS 
_ arc_ wxy - DOS 
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clearscreen 


Synopsis: 

Description: 


See Also: 
Example: 


Classification: 

Systems: 


subroutine _ clearscreen( area ) 
integer*2 area 

The _ clearscreen routine clears the indicated area and fills it with the background color. The area 
argument must be one of the following values: 

_GCLEARSCREEN area is entire screen 

_G VIE WPOR T area is current viewport or clip region 

_GWINDOW area is current text window 

_ setbkcolor^ setviewport,_ setcliprgn,_ settextwindow 

include 'graphapi.fi' 
include 'graph.fi' 

call _ setvideomode( _ VRES16C0L0R ) 
call _ rectangle( _ GFILLINTERIOR, 

+ 100, 100, 540, 380 ) 

pause 

call _ setviewport( 200, 200, 440, 280 ) 
call _ clearscreen ( _ GVIEWPORT ) 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

PC Graphics 
DOS 
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displaycursor 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


integer*2 function _ displaycursor( mode ) 
integer*2 mode 

The _ displaycursor routine is used to establish whether the text cursor is to be displayed when 
graphics routines complete. On entry to a graphics routine, the text cursor is turned off. When the 
routine completes, the mode setting determines whether the cursor is turned back on. The mode 
argument can have one of the following values: 

_GCURSORON the cursor will be displayed 

_GCURSOROFF the cursor will not be displayed 

The _ displaycursor routine returns the previous setting for mode. 

_ gettextcursor,_ settextcursor 

include 'graphapi.fi' 
include 'graph.fi' 

character*30 name 

call _ setvideomode ( _ TEXTC80 ) 

call _ settextposition ( 2, 1 ) 

call _ displaycursor ( _ GCURSORON ) 

call _ outtext( 'Cursor ON'//char(10)//char (10) 

+ //'Enter your name >'c ) 

read( *, ' (a30)' ) name 

call _ displaycursor( _ GCURSOROFF ) 
call _ settextposition ( 6, 1 ) 

call _ outtext ( 'Cursor OFF'//char(10)//char (10) 

+ //'Enter your name >'c ) 

read( *, '(a30)' ) name 

call _ setvideomode( _ DEFAULTMODE ) 
end 

PC Graphics 
DOS 
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ellipse Routines 


Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


integer*2 

integer*2 

integer*2 

integer*2 


function 
fill 
xl, yl 
x2, y2 


ellipse( fill, xl, yl, x2, y2 ) 


integer*2 function _ 
integer*2 fill, 
double precision xl, 
double precision x2. 


ellipse_ w ( 

yl 

y2 


fill. 


xl, yl, x2, y2 ) 


integer*2 function _ ellipse_ wxy( fill, pi, p2 ) 

integer*2 fill, 

record /_ wxycoord/ pi, p2 


The _ ellipse routines draw ellipses. The_ ellipse routine uses the view coordinate system. The 
_ ellipse_ w and_ ellipse_ wxy routines use the window coordinate system. 

The center of the ellipse is the center of the rectangle established by the points (xl, yl) and 
(x2,y2) . 

The argument/;// determines whether the ellipse is filled in or has only its outline drawn. The argument 
can have one of two values: 


_GFILLINTERIOR fill the interior by writing pixels with the current plot action using the current 

color and the current fill mask 

JGBORDER leave the interior unchanged; draw the outline of the figure with the current 

plot action using the current color and line style 

When the coordinates (xl,yl) and (x2,y2) establish a line or a point (this happens when one or 
more of the x-coordinates or y-coordinates are equal), nothing is drawn. 

The _ ellipse routines return a non-zero value when the ellipse was successfully drawn; otherwise, 
zero is returned. 


_ arc,_ rectangle^ setcolor^ setf illmask,_ setlinestyle,_ setplotaction 

include 'graphapi.fi' 
include 'graph.fi' 

call _ setvideomode( _ VRES16C0L0R ) 

call _ ellipse / _ GBORDER, 120, 90, 520, 390 ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

produces the following: 
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ellipse Routines 



Classification: PC Graphics 

Systems: _ ellipse - DOS 

_ ellipse_ w - DOS 
_ ellipse_ wxy - DOS 
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floodfill Routines 


Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


integer*2 function _ floodfill ( x, y, stop_ color ) 
integer*2 x, y 
integer*2 stop_ color 

integer*2 function _ floodfill_ w ( x, y, stop_ color ) 
double precision x, y 
integer*2 stop_ color 

The _ floodfill routines fill an area of the screen. The_ floodfill routine uses the view 
coordinate system. The _ f loodf ill_ w routine uses the window coordinate system. 

The filling starts at the point (x,y) and continues in all directions: when a pixel is filled, the 
neighbouring pixels (horizontally and vertically) are then considered for filling. Filling is done using 
the current color and fill mask. No filling will occur if the point (x, y) lies outside the clipping region. 

If the argument stop_color is a valid pixel value, filling will occur in each direction until a pixel is 
encountered with a pixel value of stop_color. The filled area will be the area around (x, y) , bordered 
by stop_color. No filling will occur if the point (x, y) has the pixel value stop_color. 

If stop_color has the value (-1), filling occurs until a pixel is encountered with a pixel value different 
from the pixel value of the starting point (x, y) . No filling will occur if the pixel value of the point 
(x, y) is the current color. 

The _ floodfill routines return zero when no filling takes place; a non-zero value is returned to 
indicate that filling has occurred. 

_ setcliprgn^ setcolor^. setfillmask,_ setplotaction 

include 'graphapi.fi' 
include 'graph.fi' 

call _ setvideomode ( _VRES16C0L0R ) 
call _ setcolor ( 1 ) 

call _ ellipse ( _ GBORDER, 120, 90, 520, 390 ) 

call _ setcolor ( 2 ) 

call _ floodfill ( 320, 240, 1 ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

PC Graphics 

_ floodfill - DOS 
_ floodfill_ w - DOS 
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getactivepage 


Synopsis: integer*2 function _ getactivepage () 

Description: The _ getactivepage routine returns the number of the currently selected active graphics page. 

Only some combinations of video modes and hardware allow multiple pages of graphics to exist. When 
multiple pages are supported, the active page may differ from the visual page. The graphics 
information in the visual page determines what is displayed upon the screen. Animation may be 
accomplished by alternating the visual page. A graphics page can be constructed without affecting the 
screen by setting the active page to be different than the visual page. 

The number of available video pages can be determined by using the _ getvideoconf ig routine. 
The default video page is 0. 

Returns: The _ getactivepage routine returns the number of the currently selected active graphics page. 

See Also: _ setactivepage,_ setvisualpage,_ getvisualpage,_ getvideoconf ig 

Example: include 'graphapi.fi' 

include 'graph.fi' 

integer old_ apage, old_ vpage 

call _ setvideomode ( _HRES16COLOR ) 
old_ apage = _ getactivepage () 
old_ vpage = _ getvisualpage () 

! draw an ellipse on page 0 
call _ setactivepage ( 0 ) 
call _ setvisualpage ( 0 ) 

call _ ellipse! _ GFILLINTERIOR, 100, 50, 

+ 540, 150 ) 

! draw a rectangle on page 1 
call _ setactivepage ( 1 ) 

call _ rectangle ( _ GFILLINTERIOR, 100, 50, 

+ 540, 150 ) 

pause 

! display page 1 

call _ setvisualpage ( 1 ) 

pause 

call _ setactivepage ( old_ apage ) 
call _ setvisualpage ( old_ vpage ) 
call _ setvideomode ( _ DEFAULTMODE ) 
end 

Classification: PC Graphics 
Systems: DOS 
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getarcinfo 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


integer*2 function _ getarcinfo ( start_pt, end_ pt, 

inside_ pt ) 

record /xycoord/ start_ pt 
record /xycoord/ end_ pt 
record /xycoord/ inside_ pt 

The _ getarcinfo routine returns information about the arc most recently drawn by the_ arc or 
_ pie routines. The arguments start_jrt and end_pt are set to contain the endpoints of the arc. The 
argument inside_pt will contain the coordinates of a point within the pie. The points are all specified in 
the view coordinate system. 

The endpoints of the arc can be used to connect other lines to the arc. The interior point can be used to 
fill the pie. 

The _ getarcinfo routine returns a non-zero value when successful. If the previous arc or pie was 
not successfully drawn, zero is returned. 

_ arc,_ pie 

include 'graphapi.fi' 
include 'graph.fi' 

record /xycoord/ start_pt, end_pt, inside_ pt 

call _ setvideomode ( _VRES16C0L0R ) 

call _ arc( 120, 90, 520, 390, 520, 90, 120, 390 ) 

call _ getarcinfo ( start_pt, end_pt, inside_ pt ) 

call _ moveto ( start_ pt. xcoord, start_ pt. ycoord ) 

call _ lineto ( end_ pt. xcoord, end_ pt. ycoord ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

produces the following: 
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getarcinfo 



Classification: PC Graphics 
Systems: DOS 
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getbkcolor 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


integer*4 function _ getbkcolor () 

The _ getbkcolor routine returns the current background color. In text modes, the background color 
controls the area behind each individual character. In graphics modes, the background refers to the 
entire screen. The default background color is 0. 

The _ getbkcolor routine returns the current background color. 


setbkcolor*_ remappalette 


include 'graphapi.fi' 
include 'graph.fi' 

integer bk, old_ bk 
integer colors(16)/ 

+ _ BLACK, _ BLUE, _ GREEN, 

+ _ CYAN, _ RED, _ MAGENTA, 

+ _ BROWN, _ WHITE, _ GRAY, _ LIGHTBLUE, 

+ _ LIGHTGREEN, _ LIGHTCYAN, _ LIGHTRED, 

+ _ LIGHTMAGENTA, _ YELLOW, _ BRIGHTWHITE/ 

call _ setvideomode ( _VRES16COLOR ) 
old_ bk = _ getbkcolor () 
do bk = 1, 16 

call _ setbkcolor ( colors ( bk ) ) 

pause 
enddo 

call _ setbkcolor ( old_ bk ) 

call _ setvideomode ( _ DEFAULTMODE ) 

end 

PC Graphics 
DOS 
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getcliprgn 


Synopsis: subroutine _ getcliprgn ( xl, yl, x2, y2 ) 

integer*2 xl, yl 
integer*2 x2, y2 

Description: The _ getcliprgn routine returns the location of the current clipping region. A clipping region is 
defined with the _ setcliprgn or_ setviewport routines. By default, the clipping region is the 
entire screen. 

The current clipping region is a rectangular area of the screen to which graphics output is restricted. 
The top left corner of the clipping region is placed in the arguments (xl, yl) . The bottom right 
corner of the clipping region is placed in (x2, y2) . 

See Also: _ setcliprgn,_ setviewport 

Example: include 'graphapi.fi' 

include 'graph.fi' 

integer*2 xl, yl, x2, y2 

call _ setvideomode ( _VRES16COLOR ) 

call _ getcliprgn( xl, yl, x2, y2 ) 

call _ setcliprgn( 130, 100, 510, 380 ) 

call _ ellipse ( _ GBORDER, 120, 90, 520, 390 ) 

pause 

call _ setcliprgn( xl, yl, x2, y2 ) 
call _ setvideomode( _DEFAULTMODE ) 
end 

Classification: PC Graphics 
Systems: DOS 
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getcolor 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


integer*2 function _ getcolor () 

The _ getcolor routine returns the pixel value for the current color. This is the color used for 
displaying graphics output. The default color value is one less than the maximum number of colors in 
the current video mode. 

The _ getcolor routine returns the pixel value for the current color. 

_ setcolor 

include 'graphapi.fi' 
include 'graph.fi' 

integer col, old_ col 

call _ setvideomode( _ VRES16C0L0R ) 
old_ col = _ getcolor () 
do col = 0, 15 

call _ setcolor ( col ) 

call _ rectangle ( _ GFILLINTERIOR, 

+ 100, 100, 540, 380 ) 

pause 
enddo 

call _ setcolor ( old_ col ) 

call _ setvideomode ( _ DEFAULTMODE ) 

end 

PC Graphics 
DOS 
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getcurrentposition Routines 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


record /xycoord/ function _ getcurrentposition() 

record /_ wxycoord/ function _ getcurrentposition_ w () 

The _ getcurrentposition routines return the current output position for graphics. The 
_ getcurrentposition routine returns the point in view coordinates. The 
_ getcurrentposition_ w routine returns the point in window coordinates. 

The current position defaults to the origin, (0,0) , when a new video mode is selected. It is changed 
by successful calls to the _ arc^ moveto and_ lineto routines as well as the_ setviewport 
routine. 

Note that the output position for graphics output differs from that for text output. The output position 
for text output can be set by use of the _ settextposition routine. 

The _ getcurrentposition routines return the current output position for graphics. 

_ moveto^ settextposition 

include 'graphapi.fi' 
include 'graph.fi' 

record /xycoord/ old_ pos 

call _ setvideomode ( _VRES16COLOR ) 

old_ pos = _ getcurrentposition () 

call _ moveto ( 100, 100 ) 

call _ lineto ( 540, 100 ) 

call _ lineto ( 320, 380 ) 

call _ lineto ( 100, 100 ) 

call _ moveto ( old_ pos . xcoord, old_ pos . ycoord ) 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

PC Graphics 

_ getcurrentposition - DOS 
_ getcurrentposition_ w - DOS 


Graphics Library Routines 23 




getfillmask 


Synopsis: 

Description: 


See Also: 
Example: 


Classification: 

Systems: 


subroutine _ getfillmask( mask ) 
integer*l mask(8) 

The _ getfillmask routine copies the current fill mask into the area located by the argument mask. 
The fill mask is used by the _ ellipse^ f loodfill,_ pie^_ polygon and_ rectangle 
routines that fill an area of the screen. 

The fill mask is an eight-byte array which is interpreted as a square pattern (8 by 8) of 64 bits. Each bit 
in the mask corresponds to a pixel. When a region is filled, each point in the region is mapped onto the 
fill mask. When a bit from the mask is one, the pixel value of the corresponding point is set using the 
current plotting action with the current color; when the bit is zero, the pixel value of that point is not 
affected. 

When the fill mask is not set, a fill operation will set all points in the fill region to have a pixel value of 
the current color. 


floodfill,_ setfillmask,_ setplotaction 


include 'graphapi.fi' 
include 'graph.fi' 

integer*l old_mask(8) 
integer*l new_ mask(8)/ 

+ ' 81'x, ' 42'x, ' 24'x, ' 18'x, 

+ ' 18'x, ' 24'x, ' 42'x, ' 81'x/ 


+ 


call 

call 

call 

call 

call 

pause 

call 

end 


setvideomode ( _VRES16C0L0R ) 
getfillmask( old_ mask ) 
setfillmask( new_ mask ) 
rectangle ( _ GFILLINTERIOR, 

100, 100, 540, 380 ) 
setfillmask( old_ mask ) 

setvideomode( _ DEFAULTMODE ) 


PC Graphics 
DOS 
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getfontinfo 


Synopsis: 

Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


integer*2 function _ getfontinfo ( info ) 
record /_ fontinfo/ info 


The _ getfontinfo routine returns information about the currently selected font. Fonts are selected 
with the _ setfont routine. The font information is returned in the_ fontinfo structure indicated 
by the argument info. The structure contains the following fields: 


type 

ascent 

pixwidth 

pixheight 

avgwidth 

filename 

facename 


1 for a vector font, 0 for a bit-mapped font 

distance from top of character to baseline in pixels 

character width in pixels (0 for a proportional font) 

character height in pixels 

average character width in pixels 

name of the file containing the current font 

name of the current font 


The _ getfontinfo routine returns zero if the font information is returned successfully; otherwise a 
negative value is returned. 


registerfonts,_ unregisterf onts,_ setfont^_ outgtext,_ getgtextextent, 
setgtextvector,_ getgtextvector 


include 'graphapi.fi' 
include 'graph.fi' 

record /_ fontinfo/ info 


integer width 


+ 


call _ setvideomode ( _VRES16COLOR ) 

call _ getfontinfo( info ) 

call _ moveto( 100, 100 ) 

call _ outgtext ( 'WATCOM Graphics'c ) 

width = _ getgtextextent ( 'WATCOM Graphics'c ) 

call _ rectangle ( _ GBORDER, 100, 100, 

100 + width, 100 + info.pixheight ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 


PC Graphics 
DOS 
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getgtextextent 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


integer*2 function _ getgtextextent( text ) 
character* (*) text 

The _ getgtextextent routine returns the length in pixels of the argument text as it would be 
displayed in the current font by the routine _ outgtext. Note that the text is not displayed on the 
screen, only its length is determined. 

The _ getgtextextent routine returns the length in pixels of a string. 

_ registerfonts,_ unregisterfonts,_ setfont,_ getfontinfo,_ outgtext, 

_ setgtextvector,_ getgtextvector 


include 'graphapi.fi' 
include 'graph.fi' 

record /_ fontinfo/ info 


integer width 


+ 


call _ setvideomode ( _VRES16COLOR ) 

call _ getfontinfo( info ) 

call _ moveto ( 100, 100 ) 

call _ outgtext ( 'WATCOM Graphics'c ) 

width = _ getgtextextent ( 'WATCOM Graphics'c ) 

call _ rectangle ( _ GBORDER, 100, 100, 

100 + width, 100 + info.pixheight ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 


PC Graphics 
DOS 


26 Graphics Library Routines 




getgtextvector 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


record /xycoord/ function _ getgtextvector() 

The _ getgtextvector routine returns the current value of the text orientation vector. This is the 
direction used when text is displayed by the _ out gt ext routine. 

The _ getgtextvector routine returns, as anxycoord structure, the current value of the text 
orientation vector. 

_ registerfonts,_ unregisterfonts,_ setfont,_ getf ontinfo,_ outgtext, 

_ getgtextextent,_ setgtextvector 

include 'graphapi.fi' 
include 'graph.fi' 

record /xycoord/ old_ vec 

call _ setvideomode( _ VRES16C0L0R ) 

old_ vec = _ getgtextvector () 

call _ setgtextvector ( 0, -1 ) 

call _ moveto( 100, 100 ) 

call _ outgtext ( 'WATCOM Graphics'c ) 

call _ setgtextvector ( old_ vec. xcoord, old_ vec . ycoord ) 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

PC Graphics 
DOS 
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getimage Routines 


Synopsis: 


Description: 


See Also: 
Example: 


Classification: 

Systems: 


subroutine _ getimage( xl, yl, x2, y2, image ) 
integer*2 xl, yl 
integer*2 x2, y2 
integer*! image(*) 

subroutine _getimage_w( xl, yl, x2, y2, image ) 
double precision xl, yl 
double precision x2, y2 
integer*l image(*) 

subroutine _ getimage_ wxy ( pi, p2, image ) 
record /_ wxycoord/ pi, p2 
integer*l image(*) 

The _ getimage routines store a copy of an area of the screen into the buffer indicated by the image 
argument. The _ getimage routine uses the view coordinate system. The_ getimage_ w and 
_ getimage_ wxy routines use the window coordinate system. 

The screen image is the rectangular area defined by the points (xl,yl) and (x2,y2). The buffer 
image must be large enough to contain the image (the size of the image can be determined by using the 
_ imagesize routine). The image may be displayed upon the screen at some later time by using the 
_ put image routines. 

_ imagesize^ putimage 

include 'graphapi.fi' 
include 'graph.fi' 

integer*l image(:) 

integer y, image_ size, istat 


call _ setvideomode ( _VRES16C0L0R ) 
call _ ellipse( _ GFILLINTERIOR, 


100, 

100, 

200, 

200 ) 

image_ size = _ imagesize ( 

100 

, 100, 201, 201 ) 

allocate ( image(image_ size), 

stat = istat ) 

if( istat .eq. 0 )then 



call _ getimage ( 

100, 

100, 

201, 201, image ) 

call _ putimage ( 

260, 

200, 

image, _ GPSET ) 

call _ putimage ( 

420, 

100, 

image, _ GPSET ) 

do y = 100, 280, 

20 




call _ putimage ( 420, y, image, _ GXOR ) 
call _putimage( 420, y+20, image, _ GXOR ) 
enddo 

deallocate( image ) 
endif 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

PC Graphics 

_ getimage - DOS 
_ getimage_ w - DOS 
_ getimage_ wxy - DOS 
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getlinestyle 


Synopsis: integer*2 function _ getlinestyle () 

Description: The _ getlinestyle routine returns the current line-style mask. 

The line-style mask determines the style by which lines and arcs are drawn. The mask is treated as an 
array of 16 bits. As a line is drawn, a pixel at a time, the bits in this array are cyclically tested. When a 
bit in the array is 1, the pixel value for the current point is set using the current color according to the 
current plotting action; otherwise, the pixel value for the point is left unchanged. A solid line would 
result from a value of ' FFFF' x and a dashed line would result from a value of ' FOFO' x. 

The default line style mask is ' FFFF' x. 

Returns: The _ getlinestyle routine returns the current line-style mask. 

See Also: _ lineto^ pie^ rectangle^ polygon^, setlinestyle 

Example: include 'graphapi.fi' 

include 'graph.fi' 

integer DASHED 
parameter (DASHED='fOf0'x) 

integer old_ style 

call _ setvideomode( _ VRES16COLOR ) 
old_ style = _ getlinestyle () 
call _ setlinestyle ( DASHED ) 

call _ rectangle ( _ GBORDER, 100, 100, 540, 380 ) 

call _ setlinestyle ( old_ style ) 

pause 

call _ setvideomode( _DEFAULTMODE ) 
end 

Classification: PC Graphics 
Systems: DOS 
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getphyscoord 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


record /xycoord/ function _ getphyscoord( x, y ) 
integer*2 x, y 

The _ getphyscoord routine returns the physical coordinates of the position with view coordinates 
(x, y) . View coordinates are defined by the _ setvieworg and_ setviewport routines. 

The _ getphyscoord routine returns the physical coordinates, as anxycoord structure, of the given 
point. 

_ getviewcoord,_ setvieworg,_ setviewport 


include 'graphapi.fi' 
include 'graph.fi' 

record /xycoord/ pos 


real urand 
integer seed 


+ 

+ 


+ 

+ 


seed = 75347 

call _ setvideomode ( _VRES16C0L0R ) 
call _ setvieworg( 

mod( int( urand( seed )*32767 ), 640 ), 
mod( int( urand( seed )*32767 ), 480 ) ) 
pos = _ getphyscoord ( 0, 0 ) 
call _ rectangle ( _ GBORDER, 

- pos.xcoord, - pos.ycoord, 

639 - pos.xcoord, 479 - pos.ycoord ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 


PC Graphics 
DOS 
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getpixel Routines 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


integer*2 function _ getpixel ( x, y ) 
integer*2 x, y 

integer*2 function _ getpixel_ w ( x, y ) 
double precision x, y 

The _ getpixel routines return the pixel value for the point with coordinates (x, y) . The 
_ getpixel routine uses the view coordinate system. The_ getpixel_ w routine uses the window 
coordinate system. 

The _ getpixel routines return the pixel value for the given point when the point lies within the 
clipping region; otherwise, (-1) is returned. 

_ setpixel 

include 'graphapi.fi' 
include 'graph.fi' 

integer x, y, i 
real urand 
integer seed 

seed = 75347 

call _ setvideomode( _ VRES16C0L0R ) 

call _ rectangle ( _ GBORDER, 100, 100, 540, 380 ) 

do i = 0, 60000 

x = 101 + mod( int( urand( seed )*32767 ), 

+ 439 ) 

y = 101 + mod( int( urand( seed )*32767 ), 

+ 279 ) 

call _ setcolor ( _ getpixel ( x, y ) + 1 ) 

call _ setpixel ( x, y ) 
enddo 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

PC Graphics 

_ getpixel - DOS 
_ getpixel_ w - DOS 
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getplotaction 


Synopsis: integer*2 function _ getplotaction () 

Description: The _ getplotaction routine returns the current plotting action. 

The drawing routines cause pixels to be set with a pixel value. By default, the value to be set is 
obtained by replacing the original pixel value with the supplied pixel value. Alternatively, the replaced 
value may be computed as a function of the original and the supplied pixel values. 

The plotting action can have one of the following values: 

JGPSET replace the original screen pixel value with the supplied pixel value 

_GAND replace the original screen pixel value with the bitwise and of the original 

pixel value and the supplied pixel value 

_GOR replace the original screen pixel value with the bitwise or of the original pixel 

value and the supplied pixel value 

JGXOR replace the original screen pixel value with the bitwise exclusive-or of the 

original pixel value and the supplied pixel value. Performing this operation 
twice will restore the original screen contents, providing an efficient method 
to produce animated effects. 

Returns: The _ getplotaction routine returns the current plotting action. 

See Also: _ setplotaction 

Example: include 'graphapi.fi' 

include 'graph.fi' 

integer old_ act 

call _ setvideomode ( _VRES16C0L0R ) 

old_ act = _ getplotaction () 

call _ setplotaction ( _ GPSET ) 

call _ rectangle ( _ GFILLINTERIOR, 100, 100, 

+ 540, 380 ) 

pause 

call _ setplotaction ( _ GXOR ) 

call _ rectangle ( _ GFILLINTERIOR, 100, 100, 

+ 540, 380 ) 

pause 

call _ setplotaction ( old_ act ) 
call _ setvideomode ( _ DEFAULTMODE ) 
end 

Classification: PC Graphics 
Systems: DOS 
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gettextcolor 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


integer*2 function _ gettextcolor() 

The _ gettextcolor routine returns the pixel value of the current text color. This is the color used 
for displaying text with the _ outtext and_ outmem routines. The default text color value is set to 7 
whenever a new video mode is selected. 

The _ gettextcolor routine returns the pixel value of the current text color. 

_ settextcolor,_ setcolor,_ outtext^ outmem 

include 'graphapi.fi' 
include 'graph.fi' 

integer old_ col 
integer old_ bk 

call _ setvideomode( _ TEXTC80 ) 

old_ col = _ gettextcolor () 

old_ bk = _ getbkcolor () 

call _ settextcolor ( 7 ) 

call _ setbkcolor ( _ BLUE ) 

call _ outtext ( ' WATCOM '//char(10)// 

+ ' Graphics'c ) 

call _ settextcolor ( old_ col ) 
call _ setbkcolor ( old_ bk ) 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

PC Graphics 
DOS 
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gettextcursor 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


integer*2 function _ gettextcursor () 

The _ gettextcursor routine returns the current cursor attribute, or shape. The cursor shape is set 
with the _ settextcursor routine. See the_ settextcursor routine for a description of the 
value returned by the _ gettextcursor routine. 

The _ gettextcursor routine returns the current cursor shape when successful; otherwise, (-1) is 
returned. 

_ settextcursor^. displaycursor 

include 'graphapi.fi' 
include 'graph.fi' 

integer*2 old_ shape 

old_ shape = _ gettextcursor () 
call _ settextcursor ( ' 0007'x ) 
call _ outtext ( 

+ char(10)//'Block cursor'c ) 

pause 

call _ settextcursor ( ' 0407'x ) 
call _ outtext( 

+ char(10)//'Half height cursor'c ) 

pause 

call _ settextcursor ( ' 2000'x ) 
call _ outtext( 

+ char(10)//'No cursor'c ) 

pause 
end 

PC Graphics 
DOS 
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gettextextent 


Synopsis: 

Description: 


See Also: 
Example: 


subroutine _ gettextextent( x, y, text, concat, extent ) 

integer*2 x, y 

character* (*) text 

record /xycoord/ concat 

record /xycoord/ extent(4) 

The _ gettextextent routine simulates the effect of using the_ grtext routine to display the text 
string text at the position (x, y) , using the current text settings. The concatenation point is returned in 
the argument concat. The text extent parallelogram is returned in the array extent. 

The concatenation point is the position to use to output text after the given string. The text extent 
parallelogram outlines the area where the text string would be displayed. The four points are returned 
in counter-clockwise order, starting at the upper-left corner. 

_ grtext^ gettextsettings 

include 'graphapi.fi' 
include 'graph.fi' 

record /xycoord/ concat, extent (4) 

call _ setvideomode ( _VRES16C0L0R ) 
call _ grtext( 100, 100, 'hot'c ) 
call _ gettextextent( 100, 100, 'hot'c, 

+ concat, extent ) 

call _ polygon ( _ GBORDER, 4, extent ) 
call _ grtext ( concat.xcoord, concat.ycoord, 

+ 'dog'c ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

produces the following: 
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gettextextent 



Classification: PC Graphics 
Systems: DOS 
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gettextposition 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


record /rccoord/ function _ gettextposition() 

The _ gettextposition routine returns the current output position for text. This position is in 
terms of characters, not pixels. 

The current position defaults to the top left corner of the screen, (1,1), when a new video mode is 
selected. It is changed by successful calls to the _ outtext^_ outmenL settextposition and 
_ settextwindow routines. 

Note that the output position for graphics output differs from that for text output. The output position 
for graphics output can be set by use of the _ moveto routine. 

The _ gettextposition routine returns, as anrccoord structure, the current output position for 
text. 

_ outtext^_ outmeirL settextposition,_ settextwindow,_ moveto 

include 'graphapi.fi' 
include 'graph.fi' 

record /rccoord/ old_ pos 

call _ setvideomode ( _ TEXTC80 ) 
old_ pos = _ gettextposition () 
call _ settextposition ( 10, 40 ) 
call _ outtext( 'WATCOM Graphics'c ) 

call _ settextposition ( old_pos.row, old_ pos . col ) 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

PC Graphics 
DOS 
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gettextsettings 


Synopsis: 

subroutine _ gettextsettings( settings ) 
record /textsettings/ settings 

Description: 

The _ gettextsettings routine returns information about the current text settings used when text is 
displayed by the _ grtext routine. The information is stored in thetextsettings structure 
indicated by the argument settings. The structure contains the following fields (all are integer *2 
fields): 


basevectorx 

x-component of the current base vector 


basevectory 

y-component of the current base vector 


path 

current text path 


height 

current text height (in pixels) 


width 

current text width (in pixels) 


spacing 

current text spacing (in pixels) 


horizalign 

horizontal component of the current text alignment 


vertalign 

vertical component of the current text alignment 

See Also: 

_ grtext^ setcharsize^. setcharspacing,_ settextalign^_ settextpath, 

_ settextorient 

Example: 

include 

include 

'graphapi.fi' 

'graph.fi' 


record /textsettings/ ts 


call 

call 

call 

call 

call 

call 

pause 

call 

end 


setvideomode ( _VRES16C0L0R ) 
gettextsettings( ts ) 
grtext( 100, 100, 'WATCOM'c ) 
2 * ts.height, 2 
300, 'Graphics'c 


setcharsize( 
grtext( 100, 
setcharsize( 


ts.width 


ts.height, ts.width ) 
setvideomode( _ DEFAULTMODE ) 


) 


Classification: PC Graphics 
Systems: DOS 
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gettextwindow 


Synopsis: 

Description: 

See Also: 
Example: 


Classification: 

Systems: 


subroutine _ gettextwindow( rowl, coll, row2, col2 ) 
integer*2 rowl, coll 
integer*2 row2, col2 

The _ gettextwindow routine returns the location of the current text window. A text window is 
defined with the _ settextwindow routine. By default, the text window is the entire screen. 

The current text window is a rectangular area of the screen. Text display is restricted to be within this 
window. The top left corner of the text window is placed in the arguments (rowl, coll) . The 
bottom right corner of the text window is placed in (row2, col2) . 

_ settextwindow,_ outtext,_ outmem^ settextposition,_ scrolltextwindow 

include 'graphapi.fi' 
include 'graph.fi' 

integer i 

integer*2 rl, cl, r2, c2 
character*80 buff 

call _ setvideomode( _ TEXTC80 ) 
call _ gettextwindow( rl, cl, r2, c2 ) 
call _ settextwindow( 5, 20, 20, 40 ) 
do i = 1, 20 

write( buff, '(''Line '', i2, al, al )' ) 

+ i, char(10), char(0) 

call _ outtext ( buff ) 
enddo 
pause 

call _ settextwindow( rl, cl, r2, c2 ) 
call _ setvideomode( _ DEFAULTMODE ) 
end 

PC Graphics 
DOS 
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getvideoconfig 


Synopsis: subroutine _ getvideoconfig ( config ) 

record /videoconfig/ config 

Description: The _ getvideoconfig routine returns information about the current video mode and the hardware 
configuration. The information is returned in the videoconf ig structure indicated by the argument 
config. The structure contains the following fields (all are integer*2 fields): 

numxpixels number of pixels in x-axis 

numypixels number of pixels in y-axis 

numtextcols number of text columns 

numtextrows number of text rows 

numcolors number of actual colors 

bitsperpixel number of bits in a pixel value 

numvideopages number of video pages 

mode current video mode 

adapter adapter type 

monitor monitor type 

memory number of kilobytes (1024 characters) of video memory 

The adapter field will contain one of the following values: 


_NODISPLA Y 

no display adapter attached 

J UNKNOWN 

unknown adapter/monitor type 

_MDPA 

Monochrome Display/Printer Adapter 

_CGA 

Color Graphics Adapter 

_HERCULES 

Hercules Monochrome Adapter 

_MCGA 

Multi-Color Graphics Array 

_EGA 

Enhanced Graphics Adapter 

_VGA 

Video Graphics Array 

_SVGA 

SuperVGA Adapter 
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getvideoconfig 


The monitor field will contain one of the following values: 

_MONO regular monochrome 

jCOLOR regular color 

_ENHANCED enhanced color 

_ANALOGMONO analog monochrome 

_ANALOGCOLOR analog color 

The amount of memory reported by _ getvideoconfig will not always be correct for SuperVGA 
adapters. Since it is not always possible to determine the amount of memory, _ getvideoconfig 
will always report 256K, the minimum amount. 

See Also: _ setvideomode,_ setvideomoderows 
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getvideoconfig 


Example: 


include 'graphapi.fi' 
include 'graph.fi' 

integer mode 

record /videoconfig/ vc 

character*80 buff 

call _ getvideoconfig( vc ) 
select ( vc.adapter ) 
case ( _ VGA, _ SVGA ) 

mode = _ VRES16C0L0R 
case ( _ MCGA ) 

mode = _ MRES256COLOR 
case ( _ EGA ) 

if( vc.monitor .eq. _ MONO )then 
mode = _ ERESNOCOLOR 

else 

mode = _ ERESCOLOR 
endif 

case ( _ CGA ) 

mode = _ MRES4C0L0R 
case ( _ HERCULES ) 

mode = _ HERCMONO 
case default 

stop 'No graphics adapter' 
endselect 

if ( _ setvideomode( mode ) .ne. 0 )then 

call _ getvideoconfig( vc ) 
write( buff, 

+ ' ( i3, " x " , i3, " x " , i3, 

+ vc.numxpixels, vc.numypixels, 

+ vc.numcolors, char(O) 

call _ outtext( buff ) 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
endif 
end 


Classification: PC Graphics 
Systems: DOS 


al ) ' ) 
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getviewcoord Routines 


Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


record /xycoord/ function _ getviewcoord( x, y ) 
integer*2 x, y 

record /xycoord/ function _ getviewcoord_ w ( x, y ) 
double precision x, y 

record /xycoord/ function _ getviewcoord_ wxy ( p ) 
record /_ wxycoord/ p 

The _ getviewcoord routines translate a point from one coordinate system to viewport coordinates. 
The _ getviewcoord routine translates the point (x, y) from physical coordinates. The 
_ getviewcoord_ w and_ getviewcoord_ wxy routines translate the point from the window 
coordinate system. 

Viewport coordinates are defined by the _ setvieworg and_ setviewport routines. Window 
coordinates are defined by the _ setwindow routine. 

The _ getviewcoord routines return the viewport coordinates, as anxycoord structure, of the 
given point. 

_ getphyscoord,_ setvieworg,_ setviewport^ setwindow 

include 'graphapi.fi' 
include 'graph.fi' 

record /xycoord/ posl, pos2 

integer seed 
real urand 

seed = 75347 

call _ setvideomode ( _VRES16C0L0R ) 
call _ setvieworg( 

+ mod( int( urand( seed )*32767 ), 640 ), 

+ mod( int( urand( seed )*32767 ), 480 ) ) 

posl = _ getviewcoord( 0, 0 ) 
pos2 = _ getviewcoord( 639, 479 ) 
call _ rectangle ( _ GBORDER, 

+ posl.xcoord, posl.ycoord, 

+ pos2.xcoord, pos2.ycoord ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

PC Graphics 

_ getviewcoord - DOS 
_ getviewcoord_ w - DOS 
_ getviewcoord_ wxy - DOS 
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getvisualpage 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


integer*2 function _ getvisualpage() 

The _ getvisualpage routine returns the number of the currently selected visual graphics page. 

Only some combinations of video modes and hardware allow multiple pages of graphics to exist. When 
multiple pages are supported, the active page may differ from the visual page. The graphics 
information in the visual page determines what is displayed upon the screen. Animation may be 
accomplished by alternating the visual page. A graphics page can be constructed without affecting the 
screen by setting the active page to be different than the visual page. 

The number of available video pages can be determined by using the _ getvideoconf ig routine. 
The default video page is 0. 

The _ getvisualpage routine returns the number of the currently selected visual graphics page. 

_ setvisualpage,_ setactivepage,_ getactivepage,_ getvideoconf ig 

include 'graphapi.fi' 
include 'graph.fi' 

integer old_ apage, old_ vpage 


+ 


+ 


call _ setvideomode( _ HRES16COLOR ) 
old_ apage = _ getactivepage () 
old_ vpage = _ getvisualpage () 

! draw an ellipse on page 0 
call _ setactivepage ( 0 ) 
call _ setvisualpage ( 0 ) 

call _ ellipse! _ GFILLINTERIOR, 100, 50, 

540, 150 ) 

! draw a rectangle on page 1 
call _ setactivepage ( 1 ) 

call _ rectangle ( _ GFILLINTERIOR, 100, 50, 

540, 150 ) 

pause 

! display page 1 

call _ setvisualpage ( 1 ) 

pause 

call _ setactivepage ( old_ apage ) 
call _ setvisualpage ( old_ vpage ) 
call _ setvideomode ( _ DEFAULTMODE ) 
end 


PC Graphics 
DOS 
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getwindowcoord 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


record /_ wxycoord/ function _ getwindowcoord ( x, y ) 
integer*2 x, y 

The _ getwindowcoord routine returns the window coordinates of the position with view 
coordinates (x,y) . Window coordinates are defined by the _ setwindow routine. 

The _ getwindowcoord routine returns the window coordinates, as a_ wxycoord structure, of the 
given point. 

_ setwindow^. getviewcoord 

include 'graphapi.fi' 
include 'graph.fi' 

record /xycoord/ centre 
record /_ wxycoord/ posl, pos2 

call _ setvideomode( _ MAXRESMODE ) 

! draw a box 50 pixels square 

! in the middle of the screen 

centre = _ getviewcoord_ w( 0.5, 0.5 ) 

posl = _ getwindowcoord( centre.xcoord - 25, 

+ centre.ycoord - 25 ) 

pos2 = _ getwindowcoord( centre.xcoord + 25, 

+ centre.ycoord + 25 ) 

call _ rectangle_ wxy ( _ GBORDER, posl, pos2 ) 
pause 

call _ setvideomode( _ DEFAULTMODE ) 
end 

PC Graphics 
DOS 
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grstatus 


Synopsis: integer*2 function _ grstatus () 

Description: The _ grstatus routine returns the status of the most recently called graphics library routine. The 
routine can be called after any graphics routine to determine if any errors or warnings occurred. The 
routine returns 0 if the previous routine was successful. Values less than 0 indicate an error occurred; 
values greater than 0 indicate a warning condition. 

The following values can be returned: uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 
uindex=2 uindex=2 uindex=2 uindex=2 


Constant 

Value 

Explanation 

_ GROK 

0 

no error 

_ GRERROR 

-1 

graphics error 

_ GRMODENOTSUPPORTED 

-2 

video mode not supported 

_ GRNOTINPROPERMODE 

-3 

routine n/a in this mode 

_ GRINVALIDPARAME TER 

-4 

invalid parameter(s) 

_ GRINSUFFICIENTMEMORY 

-5 

out of memory 

_ GRFONTFILENOTFOUND 

-6 

can't open font file 

_ GRINVALIDFONTFILE 

-7 

font file has invalid format 

_ GRNOOUTPUT 

1 

nothing was done 

_ GRCLIPPED 

2 

output clipped 


Returns: The _ grstatus routine returns the status of the most recently called graphics library routine. 


Example: 


include 'graphapi.fi' 
include 'graph.fi' 


integer x, y 
real urand 
integer seed 


seed = 75347 

call _ setvideomode ( _VRES16C0L0R ) 
while( _ grstatus!) .eq. _ GROK )do 

x = mod! int( urand! seed )*32767 ), 700 ) 
y = mod! int( urand! seed )*32767 ), 500 ) 
call _ setpixel ( x, y ) 
endwhile 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 


Classification: PC Graphics 
Systems: DOS 
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grtext Routines 


Synopsis: 


Description: 


Returns: 


See Also: 


Example: 


integer*2 function _ grtext ( x, y, text ) 
integer*2 x, y 
character* (*) text 

integer*2 function _ grtext_ w ( x, y, text ) 
double precision x, y 
character* (*) text 

The _ grtext routines display a character string. The_ grtext routine uses the view coordinate 
system. The _ grtext_ w routine uses the window coordinate system. 

The character string text is displayed at the point (x, y) . The string must be terminated by a null 
character (char(O)). The text is displayed in the current color using the current text settings. 

The graphics library can display text in three different ways. 

1. The _ outtext and_ outmem routines can be used in any video mode. However, this 
variety of text can be displayed in only one size. 

2. The _ grtext routine displays text as a sequence of line segments, and can be drawn in 
different sizes, with different orientations and alignments. 

3. The _ outgtext routine displays text in the currently selected font. Both bit-mapped and 
vector fonts are supported; the size and type of text depends on the fonts that are available. 

The _ grtext routines return a non-zero value when the text was successfully drawn; otherwise, zero 
is returned. 

_ outtext,_ outmem^ outgtext^ setcharsize^ settextalign,_ settextpath, 

_ settextorient,_ setcharspacing 


include 'graphapi.fi' 
include 'graph.fi' 


call 

call 

call 

pause 

call 

end 


setvideomode ( _VRES16C0L0R ) 
grtext( 200, 100, ' WATCOM'c ) 
grtext( 200, 200, 'Graphics'c ) 


setvideomode( _DEFAULTMODE ) 


produces the following: 
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grtext Routines 



Classification: PC Graphics 

Systems: _ grtext - DOS 

_ grtext_ w - DOS 
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imagesize Routines 


Synopsis: 


Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


integer*4 

integer*2 

integer*2 


function 
xl, yl 
x2, y2 


imagesize( xl, yl, x2, y2 ) 


integer*4 function _ imagesize_ w( xl, yl, x2, 
double precision xl, yl 
double precision x2, y2 


y2 ) 


integer*4 function _ imagesize_ wxy ( pi, p2 ) 
record /_ wxycoord/ pi, p2 


The _ imagesize routines compute the number of bytes required to store a screen image. The 
_ imagesize routine uses the view coordinate system. The_ imagesize_ w and 
_ imagesize_ wxy routines use the window coordinate system. 

The screen image is the rectangular area defined by the points (xl,yl) and (x2,y2). The storage 
area used by the _ get image routines must be at least this large (in bytes). 

The _ imagesize routines return the size of a screen image. 


getimage^_ putimage 


include 'graphapi.fi' 
include 'graph.fi' 


integer*l image(:) 

integer y, image_ size, istat 


call _ setvideomode ( _VRES16C0L0R ) 
call _ ellipse! _ GFILLINTERIOR, 



100, 

100, 

200, 

200 ) 

image_ size = _ imagesize! 

100 

, 100, 201, 201 ) 

allocate ( 

image (image_ size) , 

stat = istat ) 

if( istat 

.eq. 0 )then 



call 

_ getimage( 

100, 

100, 

201, 201, image ) 

call 

_ putimage( 

260, 

200, 

image, _ GPSET ) 

call 

_ putimage( 

420, 

100, 

image, _ GPSET ) 

do y 

= 100, 280, 

20 




call _ putimage ( 420, y, image, _ GXOR ) 


call _putimage ( 420, y+20, image, _ GXOR ) 
enddo 

deallocate( image ) 
endif 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 


PC Graphics 

_ imagesize - DOS 
_ imagesize_ w - DOS 
_ imagesize_ wxy - DOS 
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lineto Routines 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


integer*2 function _ lineto ( x, y ) 
integer*2 x, y 

integer*2 function _ lineto_ w ( x, y ) 
double precision x, y 

The _ lineto routines draw straight lines. The_ lineto routine uses the view coordinate system. 
The _ lineto_ w routine uses the window coordinate system. 

The line is drawn from the current position to the point at the coordinates (x, y) . The point (x, y) 
becomes the new current position. The line is drawn with the current plotting action using the current 
line style and the current color. 

The _ lineto routines return a non-zero value when the line was successfully drawn; otherwise, zero 
is returned. 

_ moveto^ setcolor^ setlinestyle,_ setplotaction 

include 'graphapi.fi' 
include 'graph.fi' 

call _ setvideomode ( _VRES16C0L0R ) 

call _ moveto( 100, 100 ) 

call _ lineto ( 540, 100 ) 

call _ lineto ( 320, 380 ) 

call _ lineto ( 100, 100 ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

produces the following: 
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Classification: PC Graphics 

Systems: _ lineto - DOS 

_ lineto_ w - DOS 
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moveto Routines 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


record /xycoord/ function _ moveto( x, y ) 
integer*2 x, y 

record /_ wxycoord/ function _moveto_w( x, y ) 
double precision x, y 

The _ moveto routines set the current output position for graphics. The_ moveto routine uses the 
view coordinate system. The _ moveto_ w routine uses the window coordinate system. 

The current output position is set to be the point at the coordinates (x, y) . Nothing is drawn by the 
routine. The _ lineto routine uses the current output position as the starting point when a line is 
drawn. 

Note that the output position for graphics output differs from that for text output. The output position 
for text output can be set by use of the _ settextposition routine. 

The _ moveto routines return the previous value of the output position for graphics. 

_ getcurrentposition,_ lineto,_ settextposition 

include 'graphapi.fi' 
include 'graph.fi' 

call _ setvideomode( _ VRES16C0L0R ) 

call _ moveto ( 100, 100 ) 

call _ lineto ( 540, 100 ) 

call _ lineto ( 320, 380 ) 

call _ lineto ( 100, 100 ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

PC Graphics 

_ moveto - DOS 
_ moveto_ w - DOS 
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outgtext 


Synopsis: subroutine _ outgtext ( text ) 

character*(*) text 

Description: The _ outgtext routine displays the character string indicated by the argument text. The string must 
be terminated by a null character (char(O)). 

The string is displayed starting at the current position (see the _ mo veto routine) in the current color 
and in the currently selected font (see the _ set font routine). The current position is updated to 
follow the displayed text. 

When no font has been previously selected with _ set font, a default font will be used. The default 
font is an 8-by-8 bit-mapped font. 

The graphics library can display text in three different ways. 

1. The _ outtext and_ outmem routines can be used in any video mode. However, this 
variety of text can be displayed in only one size. 

2. The _ grtext routine displays text as a sequence of line segments, and can be drawn in 
different sizes, with different orientations and alignments. 

3. The _ outgtext routine displays text in the currently selected font. Both bit-mapped and 
vector fonts are supported; the size and type of text depends on the fonts that are available. 

See Also: _ registerfonts,_ unregisterfonts,_ setfont^_ getfontinfo,_ getgtextextent, 

_ setgtextvector,_ getgtextvector,_ outtext^ outmem^ grtext 

Example: include 'graphapi.fi' 

include 'graph.fi' 

integer i, n 
character*10 buff 

call _ setvideomode ( _VRES16COLOR ) 
n = _ registerfonts ( '*.fon'c ) 
do i = 0, n - 1 

write( buff, ' (''n'', i2.2, al )' ) i, char(0) 

call _ setfont ( buff ) 

call _ moveto ( 100, 100 ) 

call _ outgtext ( 'WATCOM Graphics'c ) 

pause 

call _ clearscreen ( _ GCLEARSCREEN ) 
enddo 

call _ unregisterfonts () 

call _ setvideomode ( _ DEFAULTMODE ) 

end 

Classification: PC Graphics 
Systems: DOS 
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outmem 


Synopsis: subroutine _ outmem ( text, length ) 

character*(*) text 
integer*2 length 

Description: The _ outmem routine displays the character string indicated by the argument text. The argument 

length specifies the number of characters to be displayed. Unlike the _ outtext routine,_ outmem 
will display the graphical representation of characters such as ASCII 10 and 0, instead of interpreting 
them as control characters. 

The text is displayed using the current text color (see the _ settextcolor routine), starting at the 
current text position (see the _ settextposition routine). The text position is updated to follow 
the end of the displayed text. 

The graphics library can display text in three different ways. 

1. The _ outtext and_ outmem routines can be used in any video mode. However, this 
variety of text can be displayed in only one size. 

2. The _ grtext routine displays text as a sequence of line segments, and can be drawn in 
different sizes, with different orientations and alignments. 

3. The _ outgtext routine displays text in the currently selected font. Both bit-mapped and 
vector fonts are supported; the size and type of text depends on the fonts that are available. 

See Also: _ settextcolor^ settextposition,_ settextwindow,_ grtext^ outtext, 

_ outgtext 

Example: include 'graphapi.fi' 

include 'graph.fi' 

integer i 
character*20 buf 

call _ clearscreen( _ GCLEARSCREEN ) 
do i = 0, 255 

call _ settextposition ( 1 + mod( i, 16 ), 

+ 1+5* (i/16) ) 

buf ( 1:1 ) = char( i ) 
call _ outmem( buf, 1 ) 
enddo 
pause 
end 

Classification: PC Graphics 
Systems: DOS 
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outtext 


Synopsis: subroutine _ outtext ( text ) 

character*(*) text 


Description: The _ outtext routine displays the character string indicated by the argument text. The string must be 
terminated by a null character (char(O)). When a line-feed character (char(10)) is encountered in the 
string, the characters following will be displayed on the next row of the screen. 

The text is displayed using the current text color (see the _ settextcolor routine), starting at the 
current text position (see the _ settextposition routine). The text position is updated to follow 
the end of the displayed text. 

The graphics library can display text in three different ways. 

1. The _ outtext and_ outmem routines can be used in any video mode. However, this 
variety of text can be displayed in only one size. 

2. The _ grtext routine displays text as a sequence of line segments, and can be drawn in 
different sizes, with different orientations and alignments. 

3. The _ outgtext routine displays text in the currently selected font. Both bit-mapped and 
vector fonts are supported; the size and type of text depends on the fonts that are available. 

See Also: _ settextcolor,_ settextposition,_ settextwindow,_ grtext^ outmem, 

_outgtext 

Example: include 'graphapi.fi' 

include 'graph.fi' 


call 

call 

call 

pause 

call 

end 


setvideomode( _ TEXTC80 ) 
settextposition ( 10, 30 ) 
outtext( 'WATCOM Graphics'c ) 

setvideomode( _ DEFAULTMODE ) 


Classification: PC Graphics 
Systems: DOS 
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pgjanalyzechart Routines 


Synopsis: 


Description: 


Returns: 
See Also: 


integer*2 function _ pg_ analyzechart( env, cat, values, n ) 

record /chartenv/ env 

integer*4 cat(*) 

real values(*) 

integer*2 n 

integer*2 function _ pg_ analyzechartms( env, cat, values, 

nseries, n, 
dim, labels ) 

record /chartenv/ env 
integer*4 cat(*) 
real values(*) 
integer*2 nseries, n, dim 
integer*4 labels(*) 

The _ pg_ analyzechart routines analyze either a single-series or a multi-series bar, column or line 
chart. These routines calculate default values for chart elements without actually displaying the chart. 

The _ pg_ analyzechart routine analyzes a single-series bar, column or line chart. The chart 
environment structure env is filled with default values based on the type of chart and the values of the 
cat and values arguments. The arguments are the same as for the _ pg_ chart routine. 

The _ pg_ analyzechartms routine analyzes a multi-series bar, column or line chart. The chart 
environment structure env is filled with default values based on the type of chart and the values of the 
cat, values and labels arguments. The arguments are the same as for the _ pg_ chartms routine. 

The _ pg_ analyzechart routines return zero if successful; otherwise, a non-zero value is returned. 

_ pg_ defaultchart*. pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter^ pg_ analyzepie^ pg_ analyzescatter 
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pg_analyzechart Routines 


Example: include 'graphapi.fi' 

include 'graph.fi' 
include 'pgapi.fi' 
include 'pg.fi' 

integer NUM_ VALUES 
parameter (NUM_ VALUES=4) 

integer*4 categories ( NUM_ VALUES ) 
real values ( NUM_ VALUES ) 

+ / 20, 45, 30, 25 / 

record /chartenv/ env 

categories( 1 ) = loc( 'Jan'c ) 

categories( 2 ) = loc( 'Feb'c ) 

categories( 3 ) = loc( 'Mar'c ) 

categories ( 4 ) = loc( 'Apr'c ) 

call _ setvideomode ( _VRES16COLOR ) 

call _ pg_ initchart() 

call _ pg_ defaultchart( env, 

+ _ PG_ COLUMNCHART, _ PG_ PLAINBARS ) 

env.maintitle.title = 'Column Chart'c 
call _ pg_ analyzechart( env, categories, 

+ values, NUM_ VALUES ) 

! use manual scaling 

env.yaxis.autoscale = 0 

env.yaxis.scalemin = 0.0 

env.yaxis.scalemax = 100.0 

env.yaxis.ticinterval = 25.0 

call _ pg_ chart( env, categories, 

+ values, NUM_ VALUES ) 

pause 

call _ setvideomode( _DEFAULTMODE ) 
end 

Classification: PC Graphics 

Systems: _ pg_ analyzechart - DOS 

_ pg_ analyzechartms - DOS 
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pgjanalyzepie 


Synopsis: 

Description: 

Returns: 

See Also: 


integer*2 function _ pg_ analyzepie( env, cat, values, 

explode, n ) 

record /chartenv/ env 
integer*4 cat(*) 
real values(*) 
integer*2 explode(*), n 

The _ pg_ analyzepie routine analyzes a pie chart. This routine calculates default values for chart 
elements without actually displaying the chart. 

The chart environment structure env is filled with default values based on the values of the cat , values 
and explode arguments. The arguments are the same as for the _ pg_ chartpie routine. 

The _ pg_ analyzepie routine returns zero if successful; otherwise, a non-zero value is returned. 

_ pg_ defaultchart*. pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter* pg_ analyzechart*. pg_ analyzescatter 
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pg_analyzepie 


Example: 


Classification: 

Systems: 


include 'graphapi.fi' 
include 'graph.fi' 
include 'pgapi.fi' 
include 'pg.fi' 

integer NUM_ VALUES 
parameter (NUM_ VALUES=4) 


integer*4 categories ( NUM_ VALUES ) 
real values ( NUM_ VALUES ) 

+ / 20, 45, 30, 25 / 

integer*2 explode( NUM_ VALUES ) 

+ / 1 , 0 , 0 , 0 / 

record /chartenv/ env 


categories ( 1 ) 
categories ( 2 ) 
categories( 3 ) 
categories ( 4 ) 


loc( 'Jan'c ) 
loc( 'Feb'c ) 
loc( 'Mar'c ) 
loc( 'Apr'c ) 


call _ setvideomode( _ VRES16COLOR ) 

call _ pg_ initchart () 

call _ pg_ defaultchart( env, 

+ _ PG_ PIECHART, _ PG_ NOPERCENT ) 

env.maintitle.title = 'Pie Chart'c 
env.legend.place = _ PG_ BOTTOM 
call _ pg_ analyzepie( env, categories, 

+ values, explode, NUM_ VALUES ) 

! make legend window same width as data window 
env.legend.autosize = 0 

env.legend.legendwindow.xl = env.datawindow.xl 
env.legend.legendwindow.x2 = env.datawindow.x2 
call _ pg_ chartpie( env, categories, 

+ values, explode, NUM_ VALUES ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 


PC Graphics 
DOS 
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pgjanalyzescatter Routines 


Synopsis: 


Description: 


Returns: 


See Also: 


integer*2 function _ pg_ analyzescatter( env, x, y, n ) 
record /chartenv/ env 
real x(*), y(*) 
integer*2 n 

integer*2 function _ pg_ analyzescatterms( env, x, y, 

nseries, n, 
dim, labels ) 

record /chartenv/ env 
real x(*), y(*) 
integer*2 nseries, n, dim 
integer*4 labels(*) 

The _ pg_ analyzescatter routines analyze either a single-series or a multi-series scatter chart. 
These routines calculate default values for chart elements without actually displaying the chart. 

The _ pg_ analyzescatter routine analyzes a single-series scatter chart. The chart environment 
structure env is filled with default values based on the values of the x and y arguments. The arguments 
are the same as for the _ pg_ chartscatter routine. 

The _ pg_ analyzescatterms routine analyzes a multi-series scatter chart. The chart environment 
structure env is filled with default values based on the values of the x, y and labels arguments. The 
arguments are the same as for the _ pg_ chartscatterms routine. 

The _ pg_ analyzescatter routines return zero if successful; otherwise, a non-zero value is 
returned. 

_ pg_ defaultchart*. pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter^ pg_ analyzechart*. pg_ analyzepie 
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pg_analyzescatter Routines 


Example: 


Classification: 

Systems: 


include 'graphapi.fi' 
include 'graph.fi' 
include 'pgapi.fi' 
include 'pg.fi' 

integer NUM_ VALUES 
parameter (NUM_ VALUES=4) 
integer NUM_ SERIES 
parameter (NUM_ SERIES=2) 

integer*4 labels ( NUM_ SERIES ) 
real x( NUM_ SERIES, NUM_ VALUES ) 

+ / 5, 15, 30, 40, 10, 20, 30, 45 / 

real y( NUM_ SERIES, NUM_ VALUES ) 

+ / 10, 15, 30, 45, 40, 30, 15, 5 / 

record /chartenv/ env 

labels( 1 ) = loc( 'Jan'c ) 
labels ( 2 ) = loc( 'Feb'c ) 

call _ setvideomode( _ VRES16COLOR ) 

call _ pg_ initchart() 

call _ pg_ defaultchart( env, 

+ _ PG_ SCATTERCHART, _ PG_ POINTANDLINE ) 

env.maintitle.title = 'Scatter Chart'c 
call _ pg_ analyzescatterms ( env, x, y, NUM_ SERIES, 

+ NUM_ VALUES, NUM_ VALUES, labels ) 

! display x-axis labels with 2 decimal places 
env.xaxis.autoscale = 0 
env.xaxis.ticdecimals = 2 

call _ pg_ chartscatterms ( env, x, y, NUM_ SERIES, 

+ NUM_ VALUES, NUM_ VALUES, labels ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

PC Graphics 

_ pg_ analyzescatter - DOS 
_ pg_ analyzescatterms - DOS 
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pg_chart Routines 


Synopsis: 


Description: 


Returns: 
See Also: 


integer*2 function _ pg_ chart ( env, cat, values, n ) 

record /chartenv/ env 

integer*4 cat(*) 

real values(*) 

integer*2 n 

integer*2 function _ pg_ chartms( env, cat, values, nseries, 

n, dim, labels ) 

record /chartenv/ env 
integer*4 cat(*) 
real values(*) 
integer*2 nseries, n, dim 
integer*4 labels(*) 

The _ pg_ chart routines display either a single-series or a multi-series bar, column or line chart. The 
type of chart displayed and other chart options are contained in the env argument. The argument cat is 
an array of addresses of strings. These strings describe the categories against which the data in the 
values array is charted. 

The _ pg_ chart routine displays a bar, column or line chart from the single series of data contained in 
the values array. The argument n specifies the number of values to chart. 

The _ pg_ chartms routine displays a multi-series bar, column or line chart. The argument nseries 
specifies the number of series of data to chart. The argument values is assumed to be a two-dimensional 
array defined as follows: 

real values( nseries, dim ) 

The number of values used from each series is given by the argument n, where n is less than or equal to 
dim. The argument labels is an array of addresses of strings. These strings describe each of the series 
and are used in the chart legend. 

The _ pg_ chart routines return zero if successful; otherwise, a non-zero value is returned. 

_ pg_ defaultcharts pg_ initchart^ pg_ chartpie*. pg_ chartscatter, 

_ pg_ analyzechartj_ pg_ analyzepiej, pg_ analyzescatter 
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pg_chart Routines 


Example: 


include 'graphapi.fi' 
include 'graph.fi' 
include 'pgapi.fi' 
include 'pg.fi' 

integer NUM_ VALUES 
parameter (NUM_ VALUES=4) 

integer*4 categories ( NUM_ VALUES ) 
real values ( NUM_ VALUES ) 

+ / 20, 45, 30, 25 / 

record /chartenv/ env 

categories( 1 ) = loc( 'Jan'c ) 

categories( 2 ) = loc( 'Feb'c ) 

categories ( 3 ) = loc( 'Mar'c ) 

categories( 4 ) = loc( 'Apr'c ) 


call _ setvideomode( _ VRES16COLOR ) 

call _ pg_ initchart () 

call _ pg_ defaultchart( env, 

+ _ PG_ COLUMNCHART, _ PG_ PLAINBARS ) 

env.maintitle.title = 'Column Chart'c 
call _ pg_ chart( env, categories, 

+ values, NUM_ VALUES ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 


produces the following: 



Classification: PC Graphics 
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pg_chart Routines 


Systems: 


pg_ chart - DOS 
pg_ chartms - DOS 
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pg_chartpie 


Synopsis: 

Description: 


Returns: 
See Also: 

Example: 


integer*2 function _ pg_ chartpie( env, cat, values, explode, n ) 

record /chartenv/ env 

integer*4 cat(*) 

real values(*) 

integer*2 explode(*), n 

The _ pg_ chartpie routine displays a pie chart. The chart is displayed using the options specified in 
the env argument. 

The pie chart is created from the data contained in the values array. The argument n specifies the 
number of values to chart. 


The argument cat is an array of addresses of strings. These strings describe each of the pie slices and 
are used in the chart legend. The argument explode is an array of values corresponding to each of the 
pie slices. For each non-zero element in the array, the corresponding pie slice is drawn "exploded", or 
slightly offset from the rest of the pie. 

The _ pg_ chartpie routine returns zero if successful; otherwise, a non-zero value is returned. 

_ pg_ defaultchart*. pg_ initchart*. pg_ chart*. pg_ chartscatter, 

_ pg_ analyzechart*. pg_ analyzepie^ pg_ analyzescatter 


include 'graphapi.fi' 
include 'graph.fi' 
include 'pgapi.fi' 
include 'pg.fi' 

integer NUM_ VALUES 
parameter (NUM_ VALUES=4) 


integer*4 categories! NUM_ VALUES ) 
real values ( NUM_ VALUES ) 

+ / 20, 45, 30, 25 / 

integer*2 explode( NUM_ VALUES ) 

+ / 1 , 0 , 0 , 0 / 

record /chartenv/ env 


categories ( 1 ) 
categories ( 2 ) 
categories( 3 ) 
categories ( 4 ) 


loc( 'Jan'c ) 
loc( 'Feb'c ) 
loc( 'Mar'c ) 
loc( 'Apr'c ) 


call _ setvideomode( _ VRES16COLOR ) 

call _ pg_ initchart () 

call _ pg_ defaultchart( env, 

+ _ PG_ PIECHART, _ PG_ NOPERCENT ) 

env.maintitle.title = 'Pie Chart'c 
call _ pg_ chartpie( env, categories, 

+ values, explode, NUM_ VALUES ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 


produces the following: 
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pg_chartpie 



Classification: PC Graphics 
Systems: DOS 
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pg_chartscatter Routines 


Synopsis: 


Description: 


Returns: 
See Also: 


integer*2 function _ pg_ chartscatter( env, x, y, n ) 
record /chartenv/ env 
float x (*), y(*) 
integer*2 n 

integer*2 function _ pg_ chartscatterms ( env, x, y, nseries, 

n, dim, labels ) 

record /chartenv/ env 
real x(*), y(*) 
integer*2 nseries, n, dim 
integer*4 labels(*) 

The _ pg_ chartscatter routines display either a single-series or a multi-series scatter chart. The 
chart is displayed using the options specified in the env argument. 

The _ pg_ chartscatter routine displays a scatter chart from the single series of data contained in 
the arrays x and y. The argument n specifies the number of values to chart. 

The _ pg_ chartscatterms routine displays a multi-series scatter chart. The argument nseries 
specifies the number of series of data to chart. The arguments x and y are assumed to be 
two-dimensional arrays defined as follows: 

real x( nseries, dim ) 

The number of values used from each series is given by the argument n, where n is less than or equal to 
dim. The argument labels is an array of addresses of strings. These strings describe each of the series 
and are used in the chart legend. 

The _ pg_ chartscatter routines return zero if successful; otherwise, a non-zero value is returned. 

_ pg_ defaultchart*. pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ analyzechart*. pg_ analyzepie*. pg_ analyzescatter 
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pg_chartscatter Routines 


Example: include 'graphapi.fi' 

include 'graph.fi' 
include 'pgapi.fi' 
include 'pg.fi' 

integer NUM_ VALUES 
parameter (NUM_ VALUES=4) 
integer NUM_ SERIES 
parameter (NUM_ SERIES=2) 

integer*4 labels ( NUM_ SERIES ) 
real x( NUM_ SERIES, NUM_ VALUES ) 

+ / 5, 15, 30, 40, 10, 20, 30, 45 / 

real y( NUM_ SERIES, NUM_ VALUES ) 

+ / 10, 15, 30, 45, 40, 30, 15, 5 / 

record /chartenv/ env 

labels( 1 ) = loc( 'Jan'c ) 
labels( 2 ) = loc( 'Feb'c ) 

call _ setvideomode ( _VRES16COLOR ) 

call _ pg_ initchart() 

call _ pg_ defaultchart( env, 

+ _ PG_ SCATTERCHART, _ PG_ POINTANDLINE ) 

env.maintitle.title = 'Scatter Chart'c 
call _ pg_ chartscatterms ( env, x, y, NUM_ SERIES, 

+ NUM_ VALUES, NUM_ VALUES, labels ) 

pause 

call _ setvideomode ( _DEFAULTMODE ) 
end 


produces the following: 








pg_chartscatter Routines 


Classification: 

Systems: 


PC Graphics 

_ pg_ chartscatter - 
_ pg_ chartscatterms 


DOS 
- DOS 
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pg_defaultchart 


Synopsis: 

Description: 


Returns: 
See Also: 


integer*2 function _ pg_ defaultchart( env, type, style ) 
record /chartenv/ env 
integer*2 type, style 

The _ pg_ defaultchart routine initializes the chart structure env to contain default values before a 
chart is drawn. All values in the chart structure are initialized, including blanking of all titles. The 
chart type in the structure is initialized to the value type, and the chart style is initialized to style. 

The argument type can have one of the following values: 


_PG_BARCHART 

Bar chart (horizontal bars) 


_PG_COLUMNCHART 

Column chart (vertical bars) 


_PG_LINECHART 

Line chart 


_PG_SCATTERCHART 

Scatter chart 


_PG_PIE CHAR T 

Pie chart 


Each type of chart can be drawn in one of two styles. For each chart type the argument style can have 
one of the following values: uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 

Type 

Style 1 

Style 2 

Bar 

Column 

Line 

Scatter 

Pie 

_ PG_ PLAINBARS 
_ PG_ PLAINBARS 
_ PG_ POINTANDLINE 
_ PG_ POINTANDLINE 
_ PG_ PERCENT 

_ PG_ STACKEDBARS 
_ PG_ STACKEDBARS 
_ PG_ POINTONLY 
_ PG_ POINTONLY 
_ PG_ NOPERCENT 


For single-series bar and column charts, the chart style is ignored. The "plain" (clustered) and "stacked" 
styles only apply when there is more than one series of data. The "percent" style for pie charts causes 
percentages to be displayed beside each of the pie slices. 

The _ pg_ defaultchart routine returns zero if successful; otherwise, a non-zero value is returned. 
_ pg_ initchart^ pg_ charts pg_ chartpie^ pg_ chartscatter 
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pg_defaultchart 


Example: 


include 'graphapi.fi' 
include 'graph.fi' 
include 'pgapi.fi' 
include 'pg.fi' 

integer NUM_ VALUES 
parameter (NUM_ VALUES=4) 

integer*4 categories ( NUM_ VALUES ) 
real values ( NUM_ VALUES ) 

+ / 20, 45, 30, 25 / 

record /chartenv/ env 

categories( 1 ) = loc( 'Jan'c ) 

categories( 2 ) = loc( 'Feb'c ) 

categories ( 3 ) = loc( 'Mar'c ) 

categories( 4 ) = loc( 'Apr'c ) 


call _ setvideomode( _ VRES16COLOR ) 

call _ pg_ initchart () 

call _ pg_ defaultchart( env, 

+ _ PG_ COLUMNCHART, _ PG 

env.maintitle.title = 'Column Chart'c 
call _ pg_ chart( env, categories, 

+ values, NUM_ VALUES ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 


Classification: PC Graphics 
Systems: DOS 


PLAINBARS ) 
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pg_getchardef 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


integer*2 function _ pg_ getchardef( ch, def ) 
integer*2 ch 
integer*l def(8) 

The _ pg_ getchardef routine retrieves the current bit-map definition for the character ch. The 
bit-map is placed in the array def. The current font must be an 8-by-8 bit-mapped font. 

The _ pg_ getchardef routine returns zero if successful; otherwise, a non-zero value is returned. 

_ pg_ defaultcharts pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter^ pg_ setchardef 


include 'graphapi.fi' 
include 'graph.fi' 
include 'pgapi.fi' 
include 'pg.fi' 

integer NUM_ VALUES 
parameter (NUM_ VALUES=4) 

real x ( NUM_ VALUES ) 

+ / 5, 25, 45, 65 / 

real y ( NUM_ VALUES ) 

+ / 5, 45, 25, 65 / 

integer*l diamond! 8 ) 

+ / '10'x, '28'x, '44'x, '82'x, 

+ ' 44'x, ' 28'x, ' 10'x, ' 00' x / 

record /chartenv/ env 
integer*l old_ def( 8 ) 

call _ setvideomode( _ VRES16COLOR ) 

call _ pg_ initchart () 

call _ pg_ defaultchart( env, 

+ _ PG_ SCATTERCHART, _ PG_ POINTANDLINE ) 

env.maintitle.title = 'Scatter Chart'c 
! change asterisk character to diamond 
call _ pg_ getchardef ( ichar ( '*' ), old_ def ) 
call _ pg_ setchardef( ichar( '*' ), diamond ) 
call _ pg_ chartscatter ( env, x, y, NUM_ VALUES ) 
call _ pg_ setchardef ( ichar ( '*' ), old_ def ) 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 


PC Graphics 
DOS 
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pg_getpalette 


Synopsis: integer*2 function _ pg_ getpalette ( pal ) 

record /paletteentry/ pal(*) 

Description: The _ pg_ getpalette routine retrieves the internal palette of the presentation graphics system. The 
palette controls the colors, line styles, fill patterns and plot characters used to display each series of data 
in a chart. 

The argument pal is an array of palette structures that will contain the palette. Each element of the 
palette is a structure containing the following fields: 

color color used to display series 

style line style used for line and scatter charts 

fill fill pattern used to fill interior of bar and pie sections 

plotchar character plotted on line and scatter charts 

Returns: The _ pg_ getpalette routine returns zero if successful; otherwise, a non-zero value is returned. 

See Also: _ pg_ defaultchart*. pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter^ pg_ setpalette^ pg_ resetpalette 
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pg_getpalette 


Example: 


Classification: 

Systems: 


include 'graphapi.fi' 
include 'graph.fi' 
include 'pgapi.fi' 
include 'pg.fi' 

integer NUM_ VALUES 
parameter (NUM_ VALUES=4) 

integer*4 categories ( NUM_ VALUES ) 
real values ( NUM_ VALUES ) 

+ / 20, 45, 30, 25 / 

integer*l bricks( 8 ) 

+ / ' ff'x, ' 80'x, ' 80'x, ' 80'x, 

+ ' ff'x, ' 08'x, ' 08'x, ' 08'x / 

record /chartenv/ env 

record /paletteentry/ pal( _ PG_ PALETTELEN ) 
integer i 


categories ( 1 ) 
categories ( 2 ) 
categories( 3 ) 
categories ( 4 ) 


loc( 'Jan'c ) 
loc( 'Feb'c ) 
loc( 'Mar'c ) 
loc( 'Apr'c ) 


call _ setvideomode( _ VRES16COLOR ) 

call _ pg_ initchart () 

call _ pg_ defaultchart( env, 

+ _ PG_ COLUMNCHART, _ PG_ PLAINBARS ) 

env.maintitle.title = 'Column Chart'c 
! get default palette and change 1st entry 
call _ pg_ getpalette ( pal ) 
pal( 2 ).color = 12 
do i = 1, 8 

pal( 2 ).fill( i ) = bricks( i ) 
enddo 

! use new palette 

call _ pg_ setpalette( pal ) 

call _ pg_ chart( env, categories, 

+ values, NUM_ VALUES ) 

! reset palette to default 
call _ pg_ resetpalette () 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 


PC Graphics 
DOS 
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pg_getstyleset 


Synopsis: 

Description: 

See Also: 

Example: 


Classification: 

Systems: 


subroutine _ pg_ getstyleset( style ) 
integer*2 style(*) 

The _ pg_ getstyleset routine retrieves the internal style-set of the presentation graphics system. 
The style-set is a set of line styles used for drawing window borders and grid-lines. The argument style 
is an array that will contain the style-set. 

_ pg_ defaultcharts pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter^ pg_ setstyleset*. pg_ resetstyleset 

include 'graphapi.fi' 
include 'graph.fi' 
include 'pgapi.fi' 
include 'pg.fi' 

integer NUM_ VALUES 
parameter (NUM_ VALUES=4) 

integer*4 categories! NUM_ VALUES ) 
real values ( NUM_ VALUES ) 

+ / 20, 45, 30, 25 / 

record /chartenv/ env 

integer*2 style! _ PG_ PALETTELEN ) 

categories! 1 ) = loc( 'Jan'c ) 

categories! 2 ) = loc( 'Feb'c ) 

categories! 3 ) = loc( 'Mar'c ) 

categories! 4 ) = loc( 'Apr'c ) 

call _ setvideomode( _ VRES16COLOR ) 

call _ pg_ initchart() 

call _ pg_ defaultchart( env, 

+ _ PG_ COLUMNCHART, _ PG_ PLAINBARS ) 

env.maintitle.title = 'Column Chart'c 
! turn on yaxis grid, and use style 2 
env.yaxis.grid = 1 
env.yaxis.gridstyle = 2 

! get default style-set and change entry 2 

call _ pg_ getstyleset( style ) 

style! 3 ) = '8888'x 

! use new style-set 

call _ pg_ setstyleset( style ) 

call _ pg_ chart( env, categories, 

+ values, NUM_ VALUES ) 

! reset style-set to default 
call _ pg_ resetstyleset () 
pause 

call _ setvideomode( _ DEFAULTMODE ) 
end 

PC Graphics 
DOS 
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pg_hlabelchart 


Synopsis: integer*2 function _ pg_ hlabelchart ( env, x, y, 

color, label ) 

record /chartenv/ env 
integer*2 x, y, color 
character* (*) label 

Description: The _ pg_ hlabelchart routine displays the text string label on the chart described by the env chart 
structure. The string is displayed horizontally starting at the point (x, y) , relative to the upper left 
corner of the chart. The color specifies the palette color used to display the string. 

Returns: The _ pg_ hlabelchart routine returns zero if successful; otherwise, a non-zero value is returned. 

See Also: _ pg_ defaultchart*. pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter* pg_ vlabelchart 

Example: include 'graphapi.fi' 

include 'graph.fi' 
include 'pgapi.fi' 
include 'pg.fi' 

integer NUM_ VALUES 
parameter (NUM_ VALUES=4) 

integer*4 categories! NUM_ VALUES ) 
real values ( NUM_ VALUES ) 

+ / 20, 45, 30, 25 / 

record /chartenv/ env 

categories! 1 ) = loc( 'Jan'c ) 

categories! 2 ) = loc( 'Feb'c ) 

categories! 3 ) = loc( 'Mar'c ) 

categories! 4 ) = loc( 'Apr'c ) 

call _ setvideomode ( _VRES16COLOR ) 

call _ pg_ initchart() 

call _ pg_ defaultchart( env, 

+ _ PG_ COLUMNCHART, _ PG_ PLAINBARS ) 

env.maintitle.title = 'Column Chart'c 
call _ pg_ chart( env, categories, 

+ values, NUM_ VALUES ) 

call _ pg_ hlabelchart( env, 64, 32, 1, 

+ 'Horizontal label'c ) 

call _ pg_ vlabelchart( env, 48, 32, 1, 

+ 'Vertical label'c ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

Classification: PC Graphics 
Systems: DOS 
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pg_initchart 


Synopsis: integer*2 function _ pg_ initchart () 

Description: The _ pg_ initchart routine initializes the presentation graphics system. This includes initializing 
the internal palette and style-set used when drawing charts. This routine must be called before any of 
the other presentation graphics routines. 

The initialization of the presentation graphics system requires that a valid graphics mode has been 
selected. For this reason the _ setvideomode routine must be called before_ pg_ initchart is 
called. If a font has been selected (with the _ set font routine), that font will be used when text is 
displayed in a chart. Font selection should also be done before initializing the presentation graphics 
system. 

Returns: The _ pg_ initchart routine returns zero if successful; otherwise, a non-zero value is returned. 

See Also: _ pg_ defaultchart*. pg_ chart*. pg_ chartpie^ pg_ chartscatter, 

_ setvideomode,_ setfont^ registerfonts 

Example: include 'graphapi.fi' 

include 'graph.fi' 
include 'pgapi.fi' 
include 'pg.fi' 

integer NUM_ VALUES 
parameter (NUM_ VALUES=4) 

integer*4 categories ( NUM_ VALUES ) 
real values ( NUM_ VALUES ) 

+ / 20, 45, 30, 25 / 

record /chartenv/ env 

categories( 1 ) = loc( 'Jan'c ) 

categories( 2 ) = loc( 'Feb'c ) 

categories( 3 ) = loc( 'Mar'c ) 

categories( 4 ) = loc( 'Apr'c ) 

call _ setvideomode ( _VRES16COLOR ) 
call _ pg_ initchart() 
call _ pg_ defaultchart( env, 

_ PG_ COLUMNCHART, _ PG_ PLAINBARS ) 
env.maintitle.title = 'Column Chart'c 
call _ pg_ chart( env, categories, 

values, NUM_ VALUES ) 

pause 

call _ setvideomode ( _DEFAULTMODE ) 
end 

Classification: PC Graphics 
Systems: DOS 
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pg_resetpalette 


Synopsis: 

Description: 

Returns: 

See Also: 


integer*2 function _ pg_ resetpalette() 

The _ pg_ resetpalette routine resets the internal palette of the presentation graphics system to 
default values. The palette controls the colors, line styles, fill patterns and plot characters used to 
display each series of data in a chart. The default palette chosen is dependent on the current video 
mode. 

The _ pg_ resetpalette routine returns zero if successful; otherwise, a non-zero value is returned. 

_ pg_ defaultcharts pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter^ pg_ getpalette^ pg_ setpalette 
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pg_resetpalette 


Example: 


Classification: 

Systems: 


include 'graphapi.fi' 
include 'graph.fi' 
include 'pgapi.fi' 
include 'pg.fi' 

integer NUM_ VALUES 
parameter (NUM_ VALUES=4) 

integer*4 categories ( NUM_ VALUES ) 
real values ( NUM_ VALUES ) 

+ / 20, 45, 30, 25 / 

integer*l bricks( 8 ) 

+ / ' ff'x, ' 80'x, ' 80'x, ' 80'x, 

+ ' ff'x, ' 08'x, ' 08'x, ' 08'x / 

record /chartenv/ env 

record /paletteentry/ pal( _ PG_ PALETTELEN ) 
integer i 


categories ( 1 ) 
categories ( 2 ) 
categories( 3 ) 
categories ( 4 ) 


loc( 'Jan'c ) 
loc( 'Feb'c ) 
loc( 'Mar'c ) 
loc( 'Apr'c ) 


call _ setvideomode( _ VRES16COLOR ) 

call _ pg_ initchart () 

call _ pg_ defaultchart( env, 

+ _ PG_ COLUMNCHART, _ PG_ PLAINBARS ) 

env.maintitle.title = 'Column Chart'c 
! get default palette and change 1st entry 
call _ pg_ getpalette ( pal ) 
pal( 2 ).color = 12 
do i = 1, 8 

pal( 2 ).fill( i ) = bricks( i ) 
enddo 

! use new palette 

call _ pg_ setpalette( pal ) 

call _ pg_ chart( env, categories, 

+ values, NUM_ VALUES ) 

! reset palette to default 
call _ pg_ resetpalette () 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 
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pg_resetstyleset 


Synopsis: 

Description: 

See Also: 

Example: 


Classification: 

Systems: 


subroutine _ pg_ resetstyleset() 

The _ pg_ resetstyleset routine resets the internal style-set of the presentation graphics system to 
default values. The style-set is a set of line styles used for drawing window borders and grid-lines. 

_ pg_ defaultcharts pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter^ pg_ getstyleset*. pg_ setstyleset 

include 'graphapi.fi' 
include 'graph.fi' 
include 'pgapi.fi' 
include 'pg.fi' 

integer NUM_ VALUES 
parameter (NUM_ VALUES=4) 

integer*4 categories! NUM_ VALUES ) 
real values ( NUM_ VALUES ) 

+ / 20, 45, 30, 25 / 

record /chartenv/ env 

integer*2 style! _ PG_ PALETTELEN ) 

categories! 1 ) = loc( 'Jan'c ) 

categories! 2 ) = loc( 'Feb'c ) 

categories! 3 ) = loc( 'Mar'c ) 

categories! 4 ) = loc( 'Apr'c ) 

call _ setvideomode( _ VRES16COLOR ) 

call _ pg_ initchart() 

call _ pg_ defaultchart( env, 

+ _ PG_ COLUMNCHART, _ PG_ PLAINBARS ) 

env.maintitle.title = 'Column Chart'c 
! turn on yaxis grid, and use style 2 
env.yaxis.grid = 1 
env.yaxis.gridstyle = 2 

! get default style-set and change entry 2 

call _ pg_ getstyleset( style ) 

style! 3 ) = '8888'x 

! use new style-set 

call _ pg_ setstyleset( style ) 

call _ pg_ chart( env, categories, 

+ values, NUM_ VALUES ) 

! reset style-set to default 
call _ pg_ resetstyleset () 
pause 

call _ setvideomode( _ DEFAULTMODE ) 
end 

PC Graphics 
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pg_setchardef 


Synopsis: integer*2 function _ pg_ setchardef ( ch, def ) 

integer*2 ch 
integer*l def(8) 

Description: The _ pg_ setchardef routine sets the current bit-map definition for the character ch. The bit-map is 
contained in the array def. The current font must be an 8-by-8 bit-mapped font. 

Returns: The _ pg_ setchardef routine returns zero if successful; otherwise, a non-zero value is returned. 

See Also: _ pg_ defaultchart*. pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter^ pg_ getchardef 

Example: include 'graphapi.fi' 

include 'graph.fi' 
include 'pgapi.fi' 
include 'pg.fi' 

integer NUM_ VALUES 
parameter (NUM_ VALUES=4) 

real x ( NUM_ VALUES ) 

/ 5, 25, 45, 65 / 
real y ( NUM_ VALUES ) 

/ 5, 45, 25, 65 / 
integer*l diamond! 8 ) 

/ '10'x, '28'x, '44'x, '82'x, 

' 44'x, ' 28'x, ' 10'x, ' 00'x / 

record /chartenv/ env 
integer*l old_ def( 8 ) 

call _ setvideomode ( _VRES16COLOR ) 
call _ pg_ initchart() 
call _ pg_ defaultchart( env, 

+ _ PG_ SCATTERCHART, _ PG_ POINTANDLINE ) 

env.maintitle.title = 'Scatter Chart'c 
! change asterisk character to diamond 
call _ pg_ getchardef ( ichar ( '*' ), old_ def ) 
call _ pg_ setchardef( ichar( '*' ), diamond ) 
call _ pg_ chartscatter ( env, x, y, NUM_ VALUES ) 
call _ pg_ setchardef ( ichar ( '*' ), old_ def ) 
pause 

call _ setvideomode( _DEFAULTMODE ) 
end 

Classification: PC Graphics 

Systems: DOS 


+ 

+ 

+ 

+ 
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pg_setpalette 


Synopsis: integer*2 function _ pg_ setpalette ( pal ) 

record /paletteentry/ pal(*) 

Description: The _ pg_ setpalette routine sets the internal palette of the presentation graphics system. The 

palette controls the colors, line styles, fill patterns and plot characters used to display each series of data 
in a chart. 

The argument pal is an array of palette structures containing the new palette. Each element of the 
palette is a structure containing the following fields: 

color color used to display series 

style line style used for line and scatter charts 

fill fill pattern used to fill interior of bar and pie sections 

plotchar character plotted on line and scatter charts 

Returns: The _ pg_ setpalette routine returns zero if successful; otherwise, a non-zero value is returned. 

See Also: _ pg_ defaultchart*. pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter^ pg_ getpalette^ pg_ resetpalette 
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pg_setpalette 


Example: 


Classification: 

Systems: 


include 'graphapi.fi' 
include 'graph.fi' 
include 'pgapi.fi' 
include 'pg.fi' 

integer NUM_ VALUES 
parameter (NUM_ VALUES=4) 

integer*4 categories ( NUM_ VALUES ) 
real values ( NUM_ VALUES ) 

+ / 20, 45, 30, 25 / 

integer*l bricks( 8 ) 

+ / ' ff'x, ' 80'x, ' 80'x, ' 80'x, 

+ ' ff'x, ' 08'x, ' 08'x, ' 08'x / 

record /chartenv/ env 

record /paletteentry/ pal( _ PG_ PALETTELEN ) 
integer i 


categories ( 1 ) 
categories ( 2 ) 
categories( 3 ) 
categories ( 4 ) 


loc( 'Jan'c ) 
loc( 'Feb'c ) 
loc( 'Mar'c ) 
loc( 'Apr'c ) 


call _ setvideomode( _ VRES16COLOR ) 

call _ pg_ initchart () 

call _ pg_ defaultchart( env, 

+ _ PG_ COLUMNCHART, _ PG_ PLAINBARS ) 

env.maintitle.title = 'Column Chart'c 
! get default palette and change 1st entry 
call _ pg_ getpalette ( pal ) 
pal( 2 ).color = 12 
do i = 1, 8 

pal( 2 ).fill( i ) = bricks( i ) 
enddo 

! use new palette 

call _ pg_ setpalette( pal ) 

call _ pg_ chart( env, categories, 

+ values, NUM_ VALUES ) 

! reset palette to default 
call _ pg_ resetpalette () 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 
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pg_setstyleset 


Synopsis: 

Description: 

See Also: 

Example: 


Classification: 

Systems: 


subroutine _ pg_ setstyleset( style ) 
integer*2 style(*) 

The _ pg_ setstyleset routine retrieves the internal style-set of the presentation graphics system. 
The style-set is a set of line styles used for drawing window borders and grid-lines. The argument style 
is an array containing the new style-set. 

_ pg_ defaultcharts pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter^ pg_ getstyleset*. pg_ resetstyleset 

include 'graphapi.fi' 
include 'graph.fi' 
include 'pgapi.fi' 
include 'pg.fi' 

integer NUM_ VALUES 
parameter (NUM_ VALUES=4) 

integer*4 categories! NUM_ VALUES ) 
real values ( NUM_ VALUES ) 

+ / 20, 45, 30, 25 / 

record /chartenv/ env 

integer*2 style! _ PG_ PALETTELEN ) 

categories! 1 ) = loc( 'Jan'c ) 

categories! 2 ) = loc( 'Feb'c ) 

categories! 3 ) = loc( 'Mar'c ) 

categories! 4 ) = loc( 'Apr'c ) 

call _ setvideomode( _ VRES16COLOR ) 

call _ pg_ initchart() 

call _ pg_ defaultchart( env, 

+ _ PG_ COLUMNCHART, _ PG_ PLAINBARS ) 

env.maintitle.title = 'Column Chart'c 
! turn on yaxis grid, and use style 2 
env.yaxis.grid = 1 
env.yaxis.gridstyle = 2 

! get default style-set and change entry 2 

call _ pg_ getstyleset( style ) 

style! 3 ) = '8888'x 

! use new style-set 

call _ pg_ setstyleset( style ) 

call _ pg_ chart( env, categories, 

+ values, NUM_ VALUES ) 

! reset style-set to default 
call _ pg_ resetstyleset () 
pause 

call _ setvideomode( _ DEFAULTMODE ) 
end 

PC Graphics 
DOS 
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pg_vlabelchart 


Synopsis: integer*2 function _ pg_ vlabelchart ( env, x, y, 

color, label ) 

record /chartenv/ env 
integer*2 x, y, color 
character* (*) label 

Description: The _ pg_ vlabelchart routine displays the text string label on the chart described by the env chart 
structure. The string is displayed vertically starting at the point (x, y) , relative to the upper left 
corner of the chart. The color specifies the palette color used to display the string. 

Returns: The _ pg_ vlabelchart routine returns zero if successful; otherwise, a non-zero value is returned. 

See Also: _ pg_ defaultchart*. pg_ initchart*. pg_ chart*. pg_ chartpie, 

_ pg_ chartscatter* pg_ hlabelchart 

Example: include 'graphapi.fi' 

include 'graph.fi' 
include 'pgapi.fi' 
include 'pg.fi' 

integer NUM_ VALUES 
parameter (NUM_ VALUES=4) 

integer*4 categories! NUM_ VALUES ) 
real values ( NUM_ VALUES ) 

+ / 20, 45, 30, 25 / 

record /chartenv/ env 

categories! 1 ) = loc( 'Jan'c ) 

categories! 2 ) = loc( 'Feb'c ) 

categories! 3 ) = loc( 'Mar'c ) 

categories! 4 ) = loc( 'Apr'c ) 

call _ setvideomode ( _VRES16COLOR ) 

call _ pg_ initchart() 

call _ pg_ defaultchart( env, 

+ _ PG_ COLUMNCHART, _ PG_ PLAINBARS ) 

env.maintitle.title = 'Column Chart'c 
call _ pg_ chart( env, categories, 

+ values, NUM_ VALUES ) 

call _ pg_ hlabelchart( env, 64, 32, 1, 

+ 'Horizontal label'c ) 

call _ pg_ vlabelchart( env, 48, 32, 1, 

+ 'Vertical label'c ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

Classification: PC Graphics 
Systems: DOS 
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pie Routines 


Synopsis: 


Description: 


integer*2 function 


integer*2 fill 
integer*2 xl, yl 
integer*2 x2, y2 
integer*2 x3, y3 
integer*2 x4, y4 


pie( fill, xl, yl, x2, y2, 
x3, y3, x4, y4 ) 


integer*2 function _ pie. 

integer*2 fill 
double precision xl, yl 
double precision x2, y2 
double precision x3, y3 
double precision x4, y4 


w( fill, xl, yl, x2, y2, 
x3, y3, x4, y4 ) 


integer*2 function _pie_ wxy ( fill, pi, p2, p3, p4 ) 

integer*2 fill, 

record /_ wxycoord/ pi, p2 

record /_ wxycoord/ p3, p4 


The _ pie routines draw pie-shaped wedges. The_ pie routine uses the view coordinate system. The 
_ pie_ w and_ pie_ wxy routines use the window coordinate system. 

The pie wedges are drawn by drawing an elliptical arc (in the way described for the _ arc routines) and 
then joining the center of the rectangle that contains the ellipse to the two endpoints of the arc. 


The elliptical arc is drawn with its center at the center of the rectangle established by the points 
(xl,yl) and (x2,y2). The arc is a segment of the ellipse drawn within this bounding rectangle. 
The arc starts at the point on this ellipse that intersects the vector from the centre of the ellipse to the 
point (x3, y3) . The arc ends at the point on this ellipse that intersects the vector from the centre of 
the ellipse to the point (x4, y4) . The arc is drawn in a counter-clockwise direction with the current 
plot action using the current color and the current line style. 

The following picture illustrates the way in which the bounding rectangle and the vectors specifying the 
start and end points are defined. 
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pie Routines 


Returns: 

See Also: 
Example: 



When the coordinates (xl,yl) and (x2,y2) establish a line or a point (this happens when one or 
more of the x-coordinates or y-coordinates are equal), nothing is drawn. 

The argument/?// determines whether the figure is filled in or has only its outline drawn. The argument 
can have one of two values: 

_GFILLINTERIOR fill the interior by writing pixels with the current plot action using the current 

color and the current fill mask 

_GBORDER leave the interior unchanged; draw the outline of the figure with the current 

plot action using the current color and line style 

The _ pie routines return a non-zero value when the figure was successfully drawn; otherwise, zero is 
returned. 

_ arc^. ellipse^ setcolor^ setfillmask,_ setlinestyle,_ setplotaction 

include 'graphapi.fi' 
include 'graph.fi' 

call _ setvideomode ( _VRES16C0L0R ) 
call _ pie( _ GBORDER, 120, 90, 520, 390, 

+ 140, 20, 190, 460 ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

produces the following: 
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pie Routines 



Classification: PC Graphics 

Systems: _ pie - DOS 

_ pie_ w - DOS 
_ pie_ wxy - DOS 
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polygon Routines 


Synopsis: 


Description: 


Returns: 

See Also: 
Example: 


integer*2 function _polygon( fill, numpts, points ) 

integer*2 fill 

integer*2 numpts 

record /xycoord/ points(*) 

integer*2 function _polygon_ w ( fill, numpts, points ) 

integer*2 fill 

integer*2 numpts 

double precision points(*) 

integer*2 function _ polygon_ wxy ( fill, numpts, points ) 

integer*2 fill 

integer*2 numpts 

record /_ wxycoord/ points(*) 

The _ polygon routines draw polygons. The_ polygon routine uses the view coordinate system. 
The _ polygon_ w and_ polygon_ wxy routines use the window coordinate system. 

The polygon is defined as containing numpts points whose coordinates are given in the array points. 

The argument//// determines whether the polygon is filled in or has only its outline drawn. The 
argument can have one of two values: 

_GFILLINTERIOR fill the interior by writing pixels with the current plot action using the current 

color and the current fill mask 

_GBORDER leave the interior unchanged; draw the outline of the figure with the current 

plot action using the current color and line style 

The _ polygon routines return a non-zero value when the polygon was successfully drawn; otherwise, 
zero is returned. 

_ setcolor,_ setfillmask,_ setlinestyle,_ setplotaction 

include 'graphapi.fi' 
include 'graph.fi' 

record /xycoord/ points (5)/ 

+ 319, 140, 224, 209, 261, 320, 

+ 378, 320, 415, 209/ 

call _ setvideomode ( _VRES16COLOR ) 

call _ polygon ( _ GBORDER, 5, points ) 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

produces the following: 
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polygon Routines 



Classification: PC Graphics 

Systems: _ polygon - DOS 

_ polygon_ w - DOS 
_ polygon_ wxy - DOS 
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Synopsis: 


Description: 


See Also: 


putimage Routines 


subroutine _putimage( x, y, image, mode ) 
integer*2 x, y 
integer*l image(*) 
integer*2 mode 

subroutine _putimage_w( x, y, image, mode ) 
double precision x, y 
integer*! image(*) 
integer*2 mode 

The _ putimage routines display the screen image indicated by the argument image. The 
_ putimage routine uses the view coordinate system. The_ putimage_ w routine uses the window 
coordinate system. 

The image is displayed upon the screen with its top left corner located at the point with coordinates 
(x, y) . The image was previously saved using the _ getimage routines. The image is displayed in 
a rectangle whose size is the size of the rectangular image saved by the _ getimage routines. 

The image can be displayed in a number of ways, depending upon the value of the mode argument. 

This argument can have the following values: 


_GPSET 

replace the rectangle on the screen by the saved image 

jGPRESET 

replace the rectangle on the screen with the pixel values of the saved image 
inverted; this produces a negative image 

_GAND 

produce a new image on the screen by ANDing together the pixel values 
from the screen with those from the saved image 

_GOR 

produce a new image on the screen by ORing together the pixel values from 
the screen with those from the saved image 

_GXOR 

produce a new image on the screen by exclusive ORing together the pixel 
values from the screen with those from the saved image; the original screen 
is restored by two successive calls to the _putimage routine with this value, 
providing an efficient method to produce animated effects 


getimage,_ imagesize 
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putimage Routines 


Example: 


Classification: 

Systems: 


include 'graphapi.fi' 
include 'graph.fi' 

integer*l image(:) 

integer y, image_ size, istat 


call _ setvideomode ( _VRES16C0L0R ) 
call _ ellipse( _ GFILLINTERIOR, 



100, 

100, 

200, 

200 ) 

image_ size = _imagesize( 

100 

, 100, 201, 201 ) 

allocate ( 

image (image_ size) , 

stat = istat ) 

if( istat 

.eq. 0 )then 



call 

_ getimage( 

100, 

100, 

201, 201, image 

call 

_ putimage( 

260, 

200, 

image, _ GPSET ) 

call 

_ putimage( 

420, 

100, 

image, _ GPSET ) 

do y 

= 100, 280, 

20 




call _ putimage ( 420, y, image, _ GXOR ) 
call _putimage( 420, y+20, image, _ GXOR ) 
enddo 

deallocate( image ) 
endif 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

PC Graphics 

_ putimage - DOS 
_ putimage_ w - DOS 
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rectangle Routines 


Synopsis: integer*2 function _ rectangle ( fill, xl, yl, x2, y2 ) 

integer*2 fill 
integer*2 xl, yl 
integer*2 x2, y2 

integer*2 function _ rectangle_ w ( fill, xl, yl, x2, y2 ) 

integer*2 fill 

double precision xl, yl 

double precision x2, y2 

integer*2 function _ rectangle_ wxy( fill, pi, p2 ) 

integer*2 fill 

record /_ wxycoord/ pi, p2 

Description: The _ rectangle routines draw rectangles. The_ rectangle routine uses the view coordinate 

system. The _ rectangle_ w and. rectangle_ wxy routines use the window coordinate system. 

The rectangle is defined with opposite corners established by the points (xl,yl) and (x2,y2). 

The argument/;// determines whether the rectangle is filled in or has only its outline drawn. The 
argument can have one of two values: 

JGFILLINTERIOR fill the interior by writing pixels with the current plot action using the current 

color and the current fill mask 

JGBORDER leave the interior unchanged; draw the outline of the figure with the current 

plot action using the current color and line style 

Returns: The _ rectangle routines return a non-zero value when the rectangle was successfully drawn; 

otherwise, zero is returned. 

See Also: _ setcolor^ setfillmask^ setlinestyle,_ setplotaction 

Example: include 'graphapi.fi' 

include 'graph.fi' 

call _ setvideomode ( _VRES16C0L0R ) 

call _ rectangle ( _ GBORDER, 100, 100, 540, 380 ) 

pause 

call _ setvideomode( _DEFAULTMODE ) 
end 

produces the following: 
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rectangle Routines 


Classification: 

Systems: 


v 


J 


PC Graphics 


rectangle - DOS 
rectangle_ w - DOS 
rectangle_ wxy - DOS 
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registerfonts 


Synopsis: 

Description: 


Returns: 

See Also: 

Example: 


Classification: 

Systems: 


integer*2 function _ registerfonts ( path ) 
character* (*) path 

The _ registerfonts routine initializes the font graphics system. Fonts must be registered, and a 
font selected, before text can be displayed with the _ outgtext routine. 

The argument path specifies the location of the font files. This argument is a file specification, and can 
contain drive and directory components and may contain wildcard characters. The _ registerfonts 
routine opens each of the font files specified and reads the font information. Memory is allocated to 
store the characteristics of the font. These font characteristics are used by the _ setf ont routine when 
selecting a font. 

The _ registerfonts routine returns the number of fonts that were registered if the routine is 
successful; otherwise, a negative number is returned. 

_ unregisterfonts,_ setfont^_ getfontinfo^ outgtext,_ getgtextextent, 

_ setgtextvector,_ getgtextvector 

include 'graphapi.fi' 
include 'graph.fi' 

integer i, n 
character*10 buff 

call _ setvideomode( _ VRES16C0L0R ) 
n = _ registerfonts( '*.fon'c ) 
do i = 0, n - 1 

write( buff, '(''n'', i2.2, al )' ) i, char(O) 

call _ setfont ( buff ) 

call _ moveto( 100, 100 ) 

call _ outgtext ( 'WATCOM Graphics'c ) 

pause 

call _ clearscreen ( _ GCLEARSCREEN ) 
enddo 

call _ unregisterfonts () 

call _ setvideomode ( _ DEFAULTMODE ) 

end 

PC Graphics 
DOS 
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remapallpalette 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


integer*2 function _ remapallpalette ( colors ) 
integer*4 colors(*) 

The _ remapallpalette routine sets (or remaps) all of the colors in the palette. The color values in 
the palette are replaced by the array of color values given by the argument colors. This routine is 
supported in all video modes, but only works with EGA, MCGA and VGA adapters. 

The array colors must contain at least as many elements as there are supported colors. The newly 
mapped palette will cause the complete screen to change color wherever there is a pixel value of a 
changed color in the palette. 

The representation of colors depends upon the hardware being used. The number of colors in the 
palette can be determined by using the _ getvideoconf ig routine. 

The _ remapallpalette routine returns (-1) if the palette is remapped successfully and zero 
otherwise. 


remappalette,. 


getvideoconfig 


include 'graphapi.fi' 
include 'graph.fi' 

integer colors(16)/ 

+ _ BRIGHTWHITE, _ YELLOW, _ LIGHTMAGENTA, 

+ _ LIGHTRED, _ LIGHTCYAN, _ LIGHTGREEN, 

+ _ LIGHTBLUE, _ GRAY, _ WHITE, _ BROWN, 

+ _ MAGENTA, _ RED, _ CYAN, 

+ _ GREEN, _ BLUE, _ BLACK/ 

integer x, y 


+ 

+ 


call _ setvideomode ( _VRES16C0L0R ) 
do y = 0, 3 

do x = 0, 3 

call _ setcolor ( x + 4 * y ) 
call _ rectangle( _ GFILLINTERIOR, 
x * 160, y * 120, 

( x + 1 ) * 160, ( y + 1 ) * 120 ) 

enddo 

enddo 

pause 

call _ remapallpalette ( colors ) 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 


PC Graphics 
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remappalette 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


integer*4 function _ remappalette ( pixval, color ) 
integer*2 pixval 
integer*4 color 

The _ remappalette routine sets (or remaps) the palette color pixval to be the color color. This 
routine is supported in all video modes, but only works with EGA, MCGA and VGA adapters. 

The argument pixval is an index in the color palette of the current video mode. The argument color 
specifies the actual color displayed on the screen by pixels with pixel value pixval. Color values are 
selected by specifying the red, green and blue intensities that make up the color. Each intensity can be 
in the range from 0 to 63, resulting in 262144 possible different colors. A given color value can be 
conveniently specified as a value of type integer * 4 . The color value is of the form 
' OObbggrr' x, where bb is the blue intensity, gg is the green intensity and rr is the red intensity of 
the selected color. The file graph. f i defines constants containing the color intensities of each of the 
16 default colors. 


The _ remappalette routine takes effect immediately. All pixels on the complete screen which have 
a pixel value equal to the value of pixval will now have the color indicated by the argument color. 

The _ remappalette routine returns the previous color for the pixel value if the palette is remapped 
successfully; otherwise, (-1) is returned. 


remapallpalette,_ setvideomode 


include 'graphapi.fi' 
include 'graph.fi' 


+ 

+ 

+ 

+ 

+ 


integer col 
integer colors(16)/ 

_ BLACK, _ BLUE, _ GREEN, 

_ CYAN, _ RED, _ MAGENTA, 

_ BROWN, _ WHITE, _ GRAY, _ LIGHTBLUE, 

_ LIGHTGREEN, _ LIGHTCYAN, _ LIGHTRED, 

_ LIGHTMAGENTA, _ YELLOW, _ BRIGHTWHITE/ 


call _ setvideomode ( _VRES16COLOR ) 
do col =1, 16 

call _ remappalette( 0, colors (col) ) 
pause 
enddo 

call _ setvideomode ( _ DEFAULTMODE ) 
end 


PC Graphics 
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scrolltextwindow 


Synopsis: subroutine _ scrolltextwindow ( rows ) 

integer*2 rows 

Description: The _ scrolltextwindow routine scrolls the lines in the current text window. A text window is 
defined with the _ settextwindow routine. By default, the text window is the entire screen. 

The argument rows specifies the number of rows to scroll. A positive value means to scroll the text 
window up or towards the top of the screen. A negative value means to scroll the text window down or 
towards the bottom of the screen. Specifying a number of rows greater than the height of the text 
window is equivalent to clearing the text window with the _ clearscreen routine. 

Two constants are defined that can be used with the _ scrolltextwindow routine: 

JGSCROLLUP the contents of the text window are scrolled up (towards the top of the 

screen) by one row 

JGSCROLLDOWN the contents of the text window are scrolled down (towards the bottom of the 

screen) by one row 

See Also: _ settextwindow,_ clearscreen^ outtext^ outmem^ settextposition 

Example: include 'graphapi.fi' 

include 'graph.fi' 

integer i 
character*80 buff 

call _ setvideomode ( _ TEXTC80 ) 
call _ settextwindow( 5, 20, 20, 40 ) 
do i = 1, 10 

write( buff, '(''Line '', i2, al, al )' ) 

+ i, char(10), char(0) 

call _ outtext ( buff ) 
enddo 
pause 

call _ scrolltextwindow ( _ GSCROLLDOWN ) 
pause 

call _ scrolltextwindow ( _ GSCROLLUP ) 
pause 

call _ setvideomode( _DEFAULTMODE ) 
end 

Classification: PC Graphics 
Systems: DOS 
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selectpalette 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


integer*2 function _ selectpalette ( palnum ) 
integer*2 palnum 

The _ selectpalette routine selects the palette indicated by the argument palnum from the color 
palettes available. This routine is only supported by the video modes _ MRES4COLOR and 
_ MRESNOCOLOR. 


Mode _ MRES4COLOR supports four palettes of four colors. In each palette, color 0, the background 
color, can be any of the 16 possible colors. The color values associated with the other three pixel 
values, (1,2 and 3), are determined by the selected palette. 


The following table outlines the available color palettes: 


Palette 
Number 1 


Pixel Values 
2 


3 


0 

1 

2 

3 


green 

cyan 

light green 
light cyan 


red 

magenta 
light red 
light magenta 


brown 

white 

yellow 

bright white 


The _ selectpalette routine returns the number of the previously selected palette. 


setvideomode,_ getvideoconfig 


include 'graphapi.fi' 
include 'graph.fi' 

integer x, y, pal 

call _ setvideomode( _ MRES4COLOR ) 
do y = 0, 1 

do x = 0, 1 

call _ setcolor ( x + 2 * y ) 
call _ rectangle( _ GFILLINTERIOR, 

+ x * 160, y * 100, 

+ ( x + 1 ) * 160, ( y + 1 ) * 100 ) 

enddo 
enddo 

do pal =0, 3 

call _ selectpalette ( pal ) 
pause 
enddo 

call _ setvideomode ( _ DEFAULTMODE ) 
end 


PC Graphics 
DOS 
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setactivepage 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


integer*2 function _ setactivepage( pagenum ) 
integer*2 pagenum 

The _ setactivepage routine selects the page (in memory) to which graphics output is written. The 
page to be selected is given by the pagenum argument. 

Only some combinations of video modes and hardware allow multiple pages of graphics to exist. When 
multiple pages are supported, the active page may differ from the visual page. The graphics 
information in the visual page determines what is displayed upon the screen. Animation may be 
accomplished by alternating the visual page. A graphics page can be constructed without affecting the 
screen by setting the active page to be different than the visual page. 

The number of available video pages can be determined by using the _ getvideoconf ig routine. 
The default video page is 0. 

The _ setactivepage routine returns the number of the previous page when the active page is set 
successfully; otherwise, a negative number is returned. 

_ getactivepage,_ setvisualpage,_ getvisualpage,_ getvideoconf ig 

include 'graphapi.fi' 
include 'graph.fi' 

integer old_ apage, old_ vpage 


+ 


+ 


call _ setvideomode ( _ HRES16COLOR ) 
old_ apage = _ getactivepage () 
old_ vpage = _ getvisualpage () 

! draw an ellipse on page 0 
call _ setactivepage ( 0 ) 
call _ setvisualpage ( 0 ) 

call _ ellipse ( _ GFILLINTERIOR, 100, 50, 

540, 150 ) 

! draw a rectangle on page 1 
call _ setactivepage ( 1 ) 

call _ rectangle ( _ GFILLINTERIOR, 100, 50, 

540, 150 ) 

pause 

! display page 1 

call _ setvisualpage ( 1 ) 

pause 

call _ setactivepage ( old_ apage ) 
call _ setvisualpage ( old_ vpage ) 
call _ setvideomode ( _ DEFAULTMODE ) 
end 


PC Graphics 
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setbkcolor 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


integer*4 function _ setbkcolor( color ) 
integer*4 color 

The _ setbkcolor routine sets the current background color to be that of the color argument. In text 
modes, the background color controls the area behind each individual character. In graphics modes, the 
background refers to the entire screen. The default background color is 0. 

When the current video mode is a graphics mode, any pixels with a zero pixel value will change to the 
color of the color argument. When the current video mode is a text mode, nothing will immediately 
change; only subsequent output is affected. 

The _ setbkcolor routine returns the previous background color. 


_ getbkcolor 

include 'graphapi.fi' 
include 'graph.fi' 

integer bk, old_ bk 
integer colors(16)/ 

+ _ BLACK, _ BLUE, _ GREEN, 

+ _ CYAN, _ RED, _ MAGENTA, 

+ _ BROWN, _ WHITE, _ GRAY, _ LIGHTBLUE, 

+ _ LIGHTGREEN, _ LIGHTCYAN, _ LIGHTRED, 

+ _ LIGHTMAGENTA, _ YELLOW, _ BRIGHTWHITE/ 

call _ setvideomode ( _VRES16COLOR ) 
old_ bk = _ getbkcolor () 
do bk = 1, 16 

call _ setbkcolor ( colors ( bk ) ) 

pause 
enddo 

call _ setbkcolor ( old_ bk ) 

call _ setvideomode ( _ DEFAULTMODE ) 

end 

PC Graphics 
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setcharsize Routines 


Synopsis: subroutine _ setcharsize ( height, width ) 

integer*2 height, width 

subroutine _ setcharsize_ w ( height, width ) 
double precision height, width 

Description: The _ setcharsize routines set the character height and width to the values specified by the 
arguments height and width. For the _ setcharsize routine, the arguments height and width 
represent a number of pixels. For the _ setcharsize_ w routine, the arguments height and width 
represent lengths along the y-axis and x-axis in the window coordinate system. 

These sizes are used when displaying text with the _ grtext routine. The default character sizes are 
dependent on the graphics mode selected, and can be determined by the _ gettextsettings 
routine. 

See Also: _ grtext^_ gettextsettings 

Example: include 'graphapi.fi' 

include 'graph.fi' 

record /textsettings/ ts 

call _ setvideomode( _ VRES16COLOR ) 

call _ gettextsettings( ts ) 

call _ grtext( 100, 100, 'WATCOM'c ) 

call _ setcharsize ( 2 * ts.height, 2 * ts.width ) 

call _ grtext( 100, 300, 'Graphics'c ) 

call _ setcharsize( ts.height, ts.width ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

produces the following: 
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setcharsize Routines 


Classification: 

Systems: 



PC Graphics 

_ setcharsize - DOS 
_ setcharsize_ w - DOS 
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setcharspacing Routines 


Synopsis: subroutine _ setcharspacing ( space ) 

integer*2 space 

subroutine _ setcharspacing_ w ( space ) 
double precision space 

Description: The _ set char spacing routines set the current character spacing to have the value of the argument 
space. For the _ set char spacing routine, space represents a number of pixels. For the 
_ setcharspacing_ w routine, space represents a length along the x-axis in the window coordinate 
system. 

The character spacing specifies the additional space to leave between characters when a text string is 
displayed with the _ grtext routine. A negative value can be specified to cause the characters to be 
drawn closer together. The default value of the character spacing is 0. 

See Also: _ grtext^_ gettextsettings 

Example: include 'graphapi.fi' 

include 'graph.fi' 

call _ setvideomode ( _VRES16COLOR ) 

call _ grtext( 100, 100, 'WATCOM'c ) 

call _ setcharspacing( 20 ) 

call _ grtext( 100, 300, 'Graphics'c ) 

pause 

call _ setvideomode( _DEFAULTMODE ) 
end 

produces the following: 



Classification: PC Graphics 
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setcharspacing Routines 


Systems: 


setcharspacing - DOS 
setcharspacing_ w - DOS 
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setcliprgn 


Synopsis: subroutine _ setcliprgn ( xl, yl, x2, y2 ) 

integer*2 xl, yl 
integer*2 x2, y2 

Description: The _ setcliprgn routine restricts the display of graphics output to the clipping region. This region 
is a rectangle whose opposite corners are established by the physical points (xl,yl) and (x2,y2). 

The _ setcliprgn routine does not affect text output using the_ outtext and_ outmem routines. 
To control the location of text output, see the _ settextwindow routine. 

See Also: _ settextwindow,_ setvieworg^ setviewport 

Example: include 'graphapi.fi' 

include 'graph.fi' 

integer*2 xl, yl, x2, y2 

call _ setvideomode ( _VRES16C0L0R ) 

call _ getcliprgn( xl, yl, x2, y2 ) 

call _ setcliprgn( 130, 100, 510, 380 ) 

call _ ellipse! _ GBORDER, 120, 90, 520, 390 ) 

pause 

call _ setcliprgn( xl, yl, x2, y2 ) 
call _ setvideomode( _DEFAULTMODE ) 
end 

Classification: PC Graphics 
Systems: DOS 


106 Graphics Library Routines 




setcolor 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


integer*2 function _ setcolor ( pixval ) 
integer*2 pixval 

The _ setcolor routine sets the pixel value for the current color to be that indicated by the pixval 
argument. The current color is only used by the routines that produce graphics output; text output with 
_ outtext uses the current text color (see the_ settextcolor routine). The default color value is 
one less than the maximum number of colors in the current video mode. 

The _ setcolor routine returns the previous value of the current color. 

_ getcolor^ settextcolor 

include 'graphapi.fi' 
include 'graph.fi' 

integer col, old_ col 

call _ setvideomode( _ VRES16C0L0R ) 
old_ col = _getcolor() 
do col = 0, 15 

call _ setcolor ( col ) 

call _ rectangle ( _ GFILLINTERIOR, 

+ 100, 100, 540, 380 ) 

pause 
enddo 

call _ setcolor ( old_ col ) 

call _ setvideomode ( _ DEFAULTMODE ) 

end 

PC Graphics 
DOS 


Graphics Library Routines 107 




setfillmask 


Synopsis: 

Description: 


See Also: 


Example: 


subroutine _ setfillmask( mask ) 
integer*l mask(8) 

The _ setfillmask routine sets the current fill mask to the value of the argument mask. 

The fill mask is an eight-byte array which is interpreted as a square pattern (8 by 8) of 64 bits. Each bit 
in the mask corresponds to a pixel. When a region is filled, each point in the region is mapped onto the 
fill mask. When a bit from the mask is one, the pixel value of the corresponding point is set using the 
current plotting action with the current color; when the bit is zero, the pixel value of that point is not 
affected. 

When the fill mask is not set, a fill operation will set all points in the fill region to have a pixel value of 
the current color. By default, no fill mask is set. 

_ getfillmask,_ ellipse^ floodfill,_ rectangle^ polygon^ pie,_ setcolor, 

_ setplotaction 

include 'graphapi.fi' 
include 'graph.fi' 

integer*l old_mask(8) 
integer*l new_ mask(8)/ 

' 81'x, '42'x, ' 24'x, ' 18'x, 

'18'x, ' 24'x, ' 42'x, ' 81'x/ 

call _ setvideomode( _ VRES16C0L0R ) 
call _ getfillmask ( old_ mask ) 
call _ setfillmask ( new_ mask ) 
call _ rectangle( _ GFILLINTERIOR, 

100, 100, 540, 380 ) 
call _ setfillmask( old_ mask ) 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

produces the following: 


+ 

+ 
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setfillmask 



Classification: PC Graphics 
Systems: DOS 
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setfont 


Synopsis: 

Description: 


integer*2 function _ setfont ( opt ) 
character* (*) opt 

The _ setfont routine selects a font from the list of registered fonts (see the_ registerf onts 
routine). The font selected becomes the current font and is used whenever text is displayed with the 
_ out gt ext routine. The routine will fail if no fonts have been registered, or if a font cannot be found 
that matches the given characteristics. 

The argument opt is a string of characters specifying the characteristics of the desired font. These 
characteristics determine which font is selected. The options may be separated by blanks and are not 
case-sensitive. Any number of options may be specified and in any order. The available options are: 

hX character height X (in pixels) 

wX character width X (in pixels) 

/ choose a fixed-width font 

p choose a proportional-width font 

/• choose a raster (bit-mapped) font 

v choose a vector font 

b choose the font that best matches the options 

iiX choose font number X (the number of fonts is returned by the 

_ registerf onts routine) 

t’facename’ choose a font with specified facename 

The facename option is specified as a "t" followed by a facename enclosed in single quotes. The 
available facenames are: 


Courier 

Helv 

Tins Rmn 
Script 
Modern 
Roman 


fixed-width raster font with serifs 
proportional-width raster font without serifs 
proportional-width raster font with serifs 

proportional-width vector font that appears similar to hand-writing 
proportional-width vector font without serifs 
proportional-width vector font with serifs 


When "nX" is specified to select a particular font, the other options are ignored. 

If the best fit option ("b") is specified, _ setfont will always be able to select a font. The font chosen 
will be the one that best matches the options specified. The following precedence is given to the 
options when selecting a font: 


1. Pixel height (higher precedence is given to heights less than the specified height ) 
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setfont 


Returns: 
See Also: 

Example: 


Classification: 

Systems: 


2. Facename 

3. Pixel width 

4. Font type (fixed or proportional) 

When a pixel height or width does not match exactly and a vector font has been selected, the font will 
be stretched appropriately to match the given size. 

The _ setfont routine returns zero if successful; otherwise, (-1) is returned. 

_ registerfonts,_ unregisterfonts,_ getfontinfo*_ outgtext, 

_ getgtextextent,_ setgtextvector,_ getgtextvector 

include 'graphapi.fi' 
include 'graph.fi' 

integer i, n 
character*10 buff 

call _ setvideomode ( _VRES16C0L0R ) 
n = _ registerfonts( '*.fon'c ) 
do i = 0, n - 1 

write( buff, ' (''n'', i2.2, al )' ) i, char(0) 

call _ setfont ( buff ) 

call _ moveto ( 100, 100 ) 

call _ outgtext ( 'WATCOM Graphics'c ) 

pause 

call _ clearscreen ( _ GCLEARSCREEN ) 
enddo 

call _ unregisterfonts () 

call _ setvideomode ( _ DEFAULTMODE ) 

end 

PC Graphics 
DOS 


Graphics Library Routines 111 




setgtextvector 


Synopsis: 

Description: 

Returns: 

See Also: 

Example: 


Classification: 

Systems: 


record /xycoord/ function _ setgtextvector( x, y ) 
integer*2 x, y 

The _ setgtextvector routine sets the orientation for text output used by the_ outgtext routine 
to the vector specified by the arguments (x, y) . Each of the arguments can have a value of -1, 0 or 1, 
allowing for text to be displayed at any multiple of a 45-degree angle. The default text orientation, for 
normal left-to-right text, is the vector (1,0) . 

The _ setgtextvector routine returns, as anxycoord structure, the previous value of the text 
orientation vector. 

_ registerfonts,_ unregisterfonts,_ setfont,_ getfontinfo,_ outgtext, 

_ getgtextextent,_ getgtextvector 

include 'graphapi.fi' 
include 'graph.fi' 

record /xycoord/ old_ vec 

call _ setvideomode( _ VRES16COLOR ) 

old_ vec = _ getgtextvector () 

call _ setgtextvector ( 0, -1 ) 

call _ moveto( 100, 100 ) 

call _ outgtext ( 'WATCOM Graphics'c ) 

call _ setgtextvector ( old_ vec. xcoord, old_ vec . ycoord ) 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

PC Graphics 
DOS 
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setlinestyle 


Synopsis: 

Description: 


See Also: 
Example: 


subroutine _ setlinestyle ( style ) 
integer*2 style 

The _ setlinestyle routine sets the current line-style mask to the value of the style argument. 

The line-style mask determines the style by which lines and arcs are drawn. The mask is treated as an 
array of 16 bits. As a line is drawn, a pixel at a time, the bits in this array are cyclically tested. When a 
bit in the array is 1, the pixel value for the current point is set using the current color according to the 
current plotting action; otherwise, the pixel value for the point is left unchanged. A solid line would 
result from a value of ' FFFF' x and a dashed line would result from a value of ' FOFO' x. 

The default line style mask is ' FFFF' x. 

_ getlinestyle,_ lineto,_ rectangle^ polygon^ setplotaction 

include 'graphapi.fi' 
include 'graph.fi' 

integer DASHED 
parameter (DASHED='fOf0'x) 

integer old_ style 

call _ setvideomode ( _VRES16COLOR ) 
old_ style = _ getlinestyle () 
call _ setlinestyle ( DASHED ) 

call _ rectangle ( _ GBORDER, 100, 100, 540, 380 ) 

call _ setlinestyle ( old_ style ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

produces the following: 
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Classification: PC Graphics 
Systems: DOS 


114 Graphics Library Routines 





setpixel Routines 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


integer*2 function _ setpixel ( x, y ) 
integer*2 x, y 

integer*2 function _ setpixel_ w ( x, y ) 
double precision x, y 

The _ setpixel routine sets the pixel value of the point (x, y) using the current plotting action with 
the current color. The _ setpixel routine uses the view coordinate system. The_ setpixel_ w 
routine uses the window coordinate system. 

A pixel value is associated with each point. The values range from 0 to the number of colors (less one) 
that can be represented in the palette for the current video mode. The color displayed at the point is the 
color in the palette corresponding to the pixel number. For example, a pixel value of 3 causes the fourth 
color in the palette to be displayed at the point in question. 

The _ setpixel routines return the previous value of the indicated pixel if the pixel value can be set; 
otherwise, (-1) is returned. 

_ getpixel,_ setcolor^ setplotaction 

include 'graphapi.fi' 
include 'graph.fi' 

integer x, y, i 
real urand 
integer seed 

seed = 75347 

call _ setvideomode( _ VRES16C0L0R ) 

call _ rectangle ( _ GBORDER, 100, 100, 540, 380 ) 

doi=0, 60000 

x = 101 + mod( int( urand( seed )*32767 ), 

+ 439 ) 

y = 101 + mod( int( urand( seed )*32767 ), 

+ 279 ) 

call _ setcolor ( _ getpixel ( x, y ) + 1 ) 

call _ setpixel ( x, y ) 
enddo 
pause 

call _ setvideomode( _ DEFAULTMODE ) 
end 

PC Graphics 

_ setpixel - DOS 
_ setpixel_ w - DOS 


Graphics Library Routines 115 




setplotaction 


Synopsis: integer*2 function _ setplotaction ( action ) 

integer*2 action 

Description: The _ setplotaction routine sets the current plotting action to the value of the action argument. 

The drawing routines cause pixels to be set with a pixel value. By default, the value to be set is 
obtained by replacing the original pixel value with the supplied pixel value. Alternatively, the replaced 
value may be computed as a function of the original and the supplied pixel values. 

The plotting action can have one of the following values: 

JGPSET replace the original screen pixel value with the supplied pixel value 

_GAND replace the original screen pixel value with the bitwise and of the original 

pixel value and the supplied pixel value 

_GOR replace the original screen pixel value with the bitwise or of the original pixel 

value and the supplied pixel value 

_GXOR replace the original screen pixel value with the bitwise exclusive-or of the 

original pixel value and the supplied pixel value. Performing this operation 
twice will restore the original screen contents, providing an efficient method 
to produce animated effects. 

Returns: The previous value of the plotting action is returned. 

See Also: _ getplotaction 

Example: include 'graphapi.fi' 

include 'graph.fi' 

integer old_ act 

call _ setvideomode( _VRES16C0L0R ) 

old_ act = _ getplotaction () 

call _ setplotaction ( _ GPSET ) 

call _ rectangle ( _ GFILLINTERIOR, 100, 100, 

+ 540, 380 ) 

pause 

call _ setplotaction ( _ GXOR ) 

call _ rectangle ( _ GFILLINTERIOR, 100, 100, 

+ 540, 380 ) 

pause 

call _ setplotaction ( old_ act ) 
call _ setvideomode ( _ DEFAULTMODE ) 
end 

Classification: PC Graphics 
Systems: DOS 
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settextalign 


Synopsis: subroutine _ settextalign ( horiz, vert ) 

integer*2 horiz, vert 

Description: The _ settextalign routine sets the current text alignment to the values specified by the arguments 
horiz and vert. When text is displayed with the _ grtext routine, it is aligned (justified) horizontally 
and vertically about the given point according to the current text alignment settings. 

The horizontal component of the alignment can have one of the following values: 

NORMAL use the default horizontal alignment for the current setting of the text path 

_LEFT the text string is left justified at the given point 

jCENTER the text string is centred horizontally about the given point 

_RIGHT the text string is right justified at the given point 

The vertical component of the alignment can have one of the following values: 

NORMAL use the default vertical alignment for the current setting of the text path 

_TOP the top of the text string is aligned at the given point 

_CAP the cap line of the text string is aligned at the given point 

_HALF the text string is centred vertically about the given point 

_BASE the base line of the text string is aligned at the given point 

_BOTTOM the bottom of the text string is aligned at the given point 

The default is to use _ LEFT alignment for the horizontal component unless the text path is 
_ PATH_ LEFT, in which case_ RIGHT alignment is used. The default value for the vertical 
component is _ TOP unless the text path is_ PATH_ UP, in which case_ BOTTOM alignment is used. 

See Also: _ grtext^ gettextsettings 

Example: include 'graphapi.fi' 

include 'graph.fi' 

call _ setvideomode ( _VRES16COLOR ) 

call _ grtext( 200, 100, 'WATCOM'c ) 

call _ setpixel ( 200, 100 ) 

call _ settextalign ( _ CENTER, _ HALF ) 

call _ grtext( 200, 200, 'Graphics'c ) 

call _ setpixel ( 200, 200 ) 

pause 

call _ setvideomode( _DEFAULTMODE ) 
end 

produces the following: 
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Classification: PC Graphics 
Systems: DOS 
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settextcolor 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 

Systems: 


integer*2 function _ settextcolor( pixval ) 
integer*2 pixval 

The _ settextcolor routine sets the current text color to be the color indicated by the pixel value of 
the pixval argument. This is the color value used for displaying text with the _ outtext and 
_ outmem routines. Use the_ setcolor routine to change the color of graphics output. The default 
text color value is set to 7 whenever a new video mode is selected. 

The pixel value pixval is a number in the range 0-31. Colors in the range 0-15 are displayed normally. 

In text modes, blinking colors are specified by adding 16 to the normal color values. The following 
table specifies the default colors in color text modes. 


Pixel 

Color 

Pixel 

Color 

value 


value 


0 

Black 

8 

Gray 

1 

Blue 

9 

Light Blue 

2 

Green 

10 

Light Green 

3 

Cyan 

11 

Light Cyan 

4 

Red 

12 

Light Red 

5 

Magenta 

13 

Light Magenta 

6 

Brown 

14 

Yellow 

7 

White 

15 

Bright White 


The _ settextcolor routine returns the pixel value of the previous text color. 

_ gettextcolor,_ outtext^ outmem^ setcolor 

include 'graphapi.fi' 
include 'graph.fi' 

integer old_ col 
integer old_ bk 

call _ setvideomode( _ TEXTC80 ) 

old_ col = _ gettextcolor () 

old_ bk = _ getbkcolor () 

call _ settextcolor ( 7 ) 

call _ setbkcolor ( _ BLUE ) 

call _ outtext ( ' WATCOM '//char(10)// 

+ ' Graphics'c ) 

call _ settextcolor ( old_ col ) 
call _ setbkcolor ( old_ bk ) 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

PC Graphics 
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settextcursor 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


integer*2 function _ settextcursor( cursor ) 
integer*2 cursor 

The _ settextcursor routine sets the attribute, or shape, of the cursor in text modes. The argument 
cursor specifies the new cursor shape. The cursor shape is selected by specifying the top and bottom 
rows in the character matrix. The high byte of cursor specifies the top row of the cursor; the low byte 
specifies the bottom row. 


Some typical values for cursor are; 


Cursor 


Shape 


' 0607'x 
' 0007' x 
' 0407'x 
' 2000'x 


normal underline cursor 
full block cursor 
half-height block cursor 
no cursor 


The _ settextcursor routine returns the previous cursor shape when the shape is set successfully; 
otherwise, (-1) is returned. 

_ gettextcursor,_ displaycursor 

include 'graphapi.fi' 
include 'graph.fi' 

integer*2 old_ shape 

old_ shape = _ gettextcursor () 
call _ settextcursor ( ' 0007'x ) 
call _ outtext ( 

+ char(10)//'Block cursor'c ) 

pause 

call _ settextcursor( '0407'x ) 
call _ outtext( 

+ char(10)//'Half height cursor'c ) 

pause 

call _ settextcursor ( ' 2000'x ) 
call _ outtext( 

+ char(10)//'No cursor'c ) 

pause 
end 


PC Graphics 
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settextorient 


Synopsis: 

Description: 

See Also: 
Example: 


Classification: 

Systems: 


subroutine _ settextorient( vecx, vecy ) 
integer*2 vecx, vecy 

The _ settextorient routine sets the current text orientation to the vector specified by the 
arguments (vecx, vecy) . The text orientation specifies the direction of the base-line vector when a 
text string is displayed with the _ grtext routine. The default text orientation, for normal left-to-right 
text, is the vector (1,0) . 

_ grtext^ gettextsettings 

include 'graphapi.fi' 
include 'graph.fi' 

call _ setvideomode ( _VRES16COLOR ) 

call _ grtext( 200, 100, 'WATCOM'c ) 

call _ settextorient ( 1, 1 ) 

call _ grtext( 200, 200, 'Graphics'c ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

produces the following: 
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settextpath 


Synopsis: subroutine _ settextpath ( path ) 

integer*2 path 

Description: The _ settextpath routine sets the current text path to have the value of the path argument. The 
text path specifies the writing direction of the text displayed by the _ grtext routine. The argument 
can have one of the following values: 

_PATH_RIGHT subsequent characters are drawn to the right of the previous character 

_PATH_LEFT subsequent characters are drawn to the left of the previous character 

_PATH_UP subsequent characters are drawn above the previous character 

_PATH_DOWN subsequent characters are drawn below the previous character 

The default value of the text path is _ PATH_ RIGHT . 

See Also: _ grtext^ gettextsettings 

Example: include 'graphapi.fi' 

include 'graph.fi' 

call _ setvideomode ( _VRES16C0L0R ) 
call _ grtext( 200, 100, 'WATCOM'c ) 
call _ settextpath ( _ PATH_ DOWN ) 
call _ grtext( 200, 200, 'Graphics'c ) 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

produces the following: 
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settextpath 
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settextposition 


Synopsis: record /rccoord/ function _ settextposition ( row, col ) 

integer*2 row, col 

Description: The_ settextposition routine sets the current output position for text to be (row,col) where 
this position is in terms of characters, not pixels. 

The text position is relative to the current text window. It defaults to the top left corner of the screen, 
(1,1) , when a new video mode is selected, or when a new text window is set. The position is 
updated as text is drawn with the _ outtext and_ outmem routines. 

Note that the output position for graphics output differs from that for text output. The output position 
for graphics output can be set by use of the _ moveto routine. 

Returns: The _ settextposition routine returns, as anrccoord structure, the previous output position for 

text. 

See Also: _ gettextposition,_ outtext^. outmem^ settextwindow,_ moveto 

Example: include 'graphapi.fi' 

include 'graph.fi' 

record /rccoord/ old_ pos 

call _ setvideomode ( _ TEXTC80 ) 
old_ pos = _ gettextposition () 
call _ settextposition ( 10, 40 ) 
call _ outtext( 'WATCOM Graphics'c ) 

call _ settextposition ( old_pos.row, old_ pos . col ) 
pause 

call _ setvideomode( _ DEFAULTMODE ) 
end 

Classification: PC Graphics 
Systems: DOS 
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settextrows 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


integer*2 function _ settextrows( rows ) 
integer*2 rows 

The _ settextrows routine selects the number of rows of text displayed on the screen. The number 
of rows is specified by the argument rows. Computers equipped with EGA, MCGA and VGA adapters 
can support different numbers of text rows. The number of rows that can be selected depends on the 
current video mode and the type of monitor attached. 

If the argument rows has the value _MAXTEXTROWS, the maximum number of text rows will be 
selected for the current video mode and hardware configuration. In text modes the maximum number of 
rows is 43 for EGA adapters, and 50 for MCGA and VGA adapters. Some graphics modes will support 
43 rows for EGA adapters and 60 rows for MCGA and VGA adapters. 

The _ settextrows routine returns the number of screen rows when the number of rows is set 
successfully; otherwise, zero is returned. 


getvideoconfig,_ setvideomode,_ setvideomoderows 


include 'graphapi.fi' 
include 'graph.fi' 


+ 

+ 


integer valid_ rows(8)/ 
14, 25, 28, 30, 
34, 43, 50, 60/ 


integer i, j, rows 
character*80 buff 


do i = 0, 7 

rows = valid_ rows( i ) 

if ( _ settextrows( rows ) .eq. rows )then 
do j = 1, rows 

write( buff, '(''Line '', i2, al )' ) 

j, char(0) 

call _ settextposition( j, 1 ) 
call _ outtext ( buff ) 
enddo 
pause 
endif 
enddo 

call _ setvideomode ( _ DEFAULTMODE ) 
end 
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settextwindow 


Synopsis: 

Description: 


See Also: 
Example: 


Classification: 

Systems: 


subroutine _ settextwindow( rowl, coll, row2, col2 ) 
integer*2 rowl, coll 
integer*2 row2, col2 

The _ settextwindow routine sets the text window to be the rectangle with a top left corner at 
(rowl,coll) and a bottom right corner at (row2,col2). These coordinates are in terms of 
characters not pixels. 

The initial text output position is (1,1). Subsequent text positions are reported (by the 
_ gettextposition routine) and set (by the_ outtext^_ outmem and_ settextposition 
routines) relative to this rectangle. 

Text is displayed from the current output position for text proceeding along the current row and then 
downwards. When the window is full, the lines scroll upwards one line and then text is displayed on the 
last line of the window. 

_ gettextposition,_ outtext^ outmem^ settextposition 

include 'graphapi.fi' 
include 'graph.fi' 

integer i 

integer*2 rl, cl, r2, c2 
character*80 buff 

call _ setvideomode ( _ TEXTC80 ) 
call _ gettextwindow( rl, cl, r2, c2 ) 
call _ settextwindow( 5, 20, 20, 40 ) 
do i = 1, 20 

write( buff, '(''Line '', i2, al, al )' ) 

+ i, char(10), char(0) 

call _ outtext ( buff ) 
enddo 
pause 

call _ settextwindow( rl, cl, r2, c2 ) 
call _ setvideomode( _ DEFAULTMODE ) 
end 

PC Graphics 
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setvideomode 


Synopsis: integer*2 function _ setvideomode ( mode ) 

integer*2 mode 

Description: The _ setvideomode routine sets the video mode according to the value of the mode argument. The 
value of mode can be one of the following: uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 
uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 
uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 uindex=2 

Mode Type Size Colors Adapter 

_ MAXRESMODE (graphics mode with highest resolution) 

_ MAXCOLORMODE (graphics mode with most colors) 

_ DEFAULTMODE (restores screen to original mode) 


_ TEXTBW40 

M, T 

40 

X 

25 

16 

MDPA, HGC,VGA, SVGA 

_ TEXTC40 

C,T 

40 

X 

25 

16 

CGA, EGA, MCGA, VGA, SVGA 

_ TEXTBW80 

M, T 

80 

X 

25 

16 

MDPA, HGC, VGA, SVGA 

_ TEXTC80 

C,T 

80 

X 

25 

16 

CGA, EGA, MCGA, VGA, SVGA 

_ MRES4COLOR 

C,G 

320 

X 

200 

4 

CGA, EGA, MCGA, VGA, SVGA 

_ MRESNOCOLOR 

C,G 

320 

X 

200 

4 

CGA, EGA, MCGA, VGA, SVGA 

_ HRESBW 

C,G 

640 

X 

200 

2 

CGA, EGA, MCGA, VGA, SVGA 

_ TEXTMONO 

M, T 

80 

X 

25 

16 

MDPA, HGC, VGA, SVGA 

_ HERCMONO 

M, G 

720 

X 

350 

2 

HGC 

_ MRES16COLOR 

C,G 

320 

X 

200 

16 

EGA, VGA, SVGA 

_ HRES16COLOR 

C,G 

640 

X 

200 

16 

EGA, VGA, SVGA 

_ ERESNOCOLOR 

M, G 

640 

X 

350 

4 

EGA, VGA, SVGA 

_ ERESCOLOR 

C,G 

640 

X 

350 

4/16 

EGA, VGA, SVGA 

_ VRES2COLOR 

C,G 

640 

X 

480 

2 

MCGA, VGA, SVGA 

_ VRES16COLOR 

C,G 

640 

X 

480 

16 

VGA, SVGA 

_ MRES256COLOR 

C,G 

320 

X 

200 

256 

MCGA, VGA, SVGA 

_ URES256COLOR 

C, G 

640 

X 

400 

256 

SVGA 

_ VRES256COLOR 

C,G 

640 

X 

480 

256 

SVGA 

_ SVRES16COLOR 

C, G 

800 

X 

600 

16 

SVGA 

_ SVRES256COLOR 

C,G 

800 

X 

600 

256 

SVGA 

_ XRES16COLOR 

C, G 

1024 

X 

768 

16 

SVGA 

_ XRES256COLOR 

C, G 

1024 

X 

768 

256 

SVGA 


In the preceding table, the Type column contains the following letters: 

M indicates monochrome; multiple colors are shades of grey 

C indicates color 

G indicates graphics mode; size is in pixels 

T indicates text mode; size is in columns and rows of characters 

The Adapter column contains the following codes: 


MDPA 

IBM Monochrome Display/Printer Adapter 

CGA 

IBM Color Graphics Adapter 

EGA 

IBM Enhanced Graphics Adapter 

VGA 

IBM Video Graphics Array 

MCGA 

IBM Multi-Color Graphics Array 

HGC 

Hercules Graphics Adapter 
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setvideomode 


Returns: 

See Also: 
Example: 


Classification: 

Systems: 


SVGA SuperVGA adapters 

The modes _ MAXRESMODE and_ MAXCOLORMODE will select from among the video modes supported 
by the current graphics adapter the one that has the highest resolution or the greatest number of colors. 
The video mode will be selected from the standard modes, not including the SuperVGA modes. 

Selecting a new video mode resets the current output positions for graphics and text to be the top left 
corner of the screen. The background color is reset to black and the default color value is set to be one 
less than the number of colors in the selected mode. 

The _ setvideomode routine returns the number of text rows when the new mode is successfully 
selected; otherwise, zero is returned. 

_ getvideoconfig,_ settextrows^ setvideomoderows 

include 'graphapi.fi' 
include 'graph.fi' 

integer mode 

record /videoconfig/ vc 

character*80 buff 

call _ getvideoconfig ( vc ) 
select! vc.adapter ) 
case ( _ VGA, _ SVGA ) 

mode = _ VRES16COLOR 
case ( _ MCGA ) 

mode = _ MRES256COLOR 
case ( _ EGA ) 

if( vc.monitor .eq. _ MONO )then 
mode = _ ERESNOCOLOR 

else 

mode = _ ERESCOLOR 
endif 

case ( _ CGA ) 

mode = _ MRES4COLOR 
case ( _ HERCULES ) 

mode = _ HERCMONO 
case default 

stop 'No graphics adapter' 
endselect 

if ( _ setvideomode( mode ) .ne. 0 )then 

call _ getvideoconfig( vc ) 
write ( buff, 

+ '( i3, " x ", i3, " x ", i3, al )' ) 

+ vc.numxpixels, vc.numypixels, 

+ vc.numcolors, char(O) 

call _ outtext ( buff ) 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
endif 
end 

PC Graphics 
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setvideomoderows 


Synopsis: integer*2 function _ setvideomoderows ( mode, rows ) 

integer*2 mode 
integer*2 rows 

Description: The _ setvideomoderows routine selects a video mode and the number of rows of text displayed on 
the screen. The video mode is specified by the argument mode and is selected with the 
_ setvideomode routine. The number of rows is specified by the argument rows and is selected with 
the _ settextrows routine. 


Computers equipped with EGA, MCGA and VGA adapters can support different numbers of text rows. 
The number of rows that can be selected depends on the video mode and the type of monitor attached. 

Returns: The _ setvideomoderows routine returns the number of screen rows when the mode and number of 

rows are set successfully; otherwise, zero is returned. 

See Also: _ getvideoconf ig,_ setvideomode,_ settextrows 


Example: 


include 'graphapi.fi' 
include 'graph.fi' 

integer rows 
character*80 buff 

rows = _ setvideomoderows( _ TEXTC80, _ MAXTEXTROWS ) 
if( rows .ne. 0 )then 
write( buff, 

+ '(''Number of rows is '', i2, al )' ) 

+ rows, char (0) 

call _ outtext ( buff ) 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
endif 
end 


Classification: PC Graphics 
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setvieworg 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 

Systems: 


record /xycoord/ function _ setvieworg( x, y ) 
integer*2 x, y 

The _ setvieworg routine sets the origin of the view coordinate system, (0,0), to be located at the 
physical point (x,y) . This causes subsequently drawn images to be translated by the amount 
(x, y) . 

The _ setvieworg routine returns, as anxycoord structure, the physical coordinates of the previous 
origin. 

_ getviewcoord,_ getphyscoord,_ setcliprgn,_ setviewport 

include 'graphapi.fi' 
include 'graph.fi' 

call _ setvideomode( _ VRES16COLOR ) 
call _ setvieworg( 320, 240 ) 

call _ ellipse ( _ GBORDER, -200, -150, 200, 150 ) 
pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 

PC Graphics 
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setviewport 


Synopsis: 

Description: 

See Also: 
Example: 


Classification: 

Systems: 


subroutine _ setviewport ( xl, yl, x2, y2 ) 
integer*2 xl, yl 
integer*2 x2, y2 

The _ setviewport routine restricts the display of graphics output to the clipping region and then 
sets the origin of the view coordinate system to be the top left corner of the region. This region is a 
rectangle whose opposite corners are established by the physical points (xl,yl) and (x2,y2). 

The _ setviewport routine does not affect text output using the_ outtext and_ outmem routines. 
To control the location of text output, see the _ settextwindow routine. 

_ setcliprgn^ setvieworg,_ settextwindow,_ setwindow 


include 'graphapi.fi' 
include 'graph.fi' 

integer XSIZE, YSIZE 
parameter (XSIZE=380) 
parameter (YSIZE=280) 


+ 


call _ setvideomode( _ VRES16C0L0R ) 
call _ setviewport ( 130, 100, 

130 + XSIZE, 100 + YSIZE ) 
call _ ellipse! _ GBORDER, 0, 0, XSIZE, YSIZE ) 

pause 

call _ setvideomode ( _ DEFAULTMODE ) 
end 
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setvisualpage 


Synopsis: integer*2 function _ setvisualpage ( pagenum ) 

integer*2 pagenum 

Description: The _ setvisualpage routine selects the page (in memory) from which graphics output is displayed. 
The page to be selected is given by the pagenum argument. 

Only some combinations of video modes and hardware allow multiple pages of graphics to exist. When 
multiple pages are supported, the active page may differ from the visual page. The graphics 
information in the visual page determines what is displayed upon the screen. Animation may be 
accomplished by alternating the visual page. A graphics page can be constructed without affecting the 
screen by setting the active page to be different than the visual page. 

The number of available video pages can be determined by using the _ getvideoconf ig routine. 
The default video page is 0. 

Returns: The _ setvisualpage routine returns the number of the previous page when the visual page is set 

successfully; otherwise, a negative number is returned. 

See Also: _ getvisualpage,_ setactivepage,_ getactivepage,_ getvideoconf ig 

Example: include 'graphapi.fi' 

include 'graph.fi' 

integer old_ apage, old_ vpage 

call _ setvideomode ( _HRES16COLOR ) 
old_ apage = _ getactivepage () 
old_ vpage = _ getvisualpage () 

! draw an ellipse on page 0 
call _ setactivepage ( 0 ) 
call _ setvisualpage ( 0 ) 

call _ ellipse ( _ GFILLINTERIOR, 100, 50, 

540, 150 ) 

! draw a rectangle on page 1 
call _ setactivepage ( 1 ) 

call _ rectangle ( _ GFILLINTERIOR, 100, 50, 

540, 150 ) 

pause 

! display page 1 
call _ setvisualpage ( 1 ) 
pause 

call _ setactivepage ( old_ apage ) 
call _ setvisualpage ( old_ vpage ) 
call _ setvideomode( _DEFAULTMODE ) 
end 

Classification: PC Graphics 
Systems: DOS 
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setwindow 


Synopsis: integer*2 function _setwindow( invert, xl, yl, x2, y2 ) 

logical invert 
double precision xl, yl 
double precision x2, y2 

Description: The _ setwindow routine defines a window for the window coordinate system. Window coordinates 
are specified as a user-defined range of values. This allows for consistent pictures regardless of the 
video mode. 

The window is defined as the region with opposite corners established by the points (xl, yl) and 
(x2,y2). The argument invert specifies the direction of the y-axis. If the value is . TRUE ., the y 
values increase from the bottom of the screen to the top, otherwise, the y values increase as you move 
down the screen. 

The window defined by the _ setwindow routine is displayed in the current viewport. A viewport is 
defined by the _ setviewport routine. 

By default, the window coordinate system is defined with the point (0.0,0.0) located at the lower 
left corner of the screen, and the point (1.0,1.0) at the upper right corner. 

Returns: The _ setwindow routine returns a non-zero value when the window is set successfully; otherwise, 

zero is returned. 

See Also: _ setviewport 

Example: include 'graphapi.fi' 

include 'graph.fi' 

call _ setvideomode( _ MAXRESMODE ) 

call draw_ house ( 'Default window'c ) 

call _ setwindow( .TRUE., -0.5, -0.5, 1.5, 1.5 ) 

call draw_ house ( 'Larger window'c ) 

call _ setwindow( .TRUE., 0.0, 0.0, 0.5, 1.0 ) 

call draw_ house ( 'Left side'c ) 

call _ setvideomode( _DEFAULTMODE ) 

end 

subroutine draw_ house ( msg ) 

include 'graph.fi' 
character*80 msg 

call _ clearscreen( _ GCLEARSCREEN ) 
call _ outtext ( msg ) 

call _ rectangle_ w ( _ GBORDER, 0.2, 0.1, 0.8, 0.6 ) 

call _ moveto_ w ( 0.1, 0.5 ) 

call _lineto_w( 0.5, 0.9 ) 

call _lineto_w( 0.9, 0.5 ) 

call _ arc_ w ( 0.4, 0.5, 0.6, 0.3, 

+ 0.6, 0.4, 0.4, 0.4 ) 

call _ rectangle_ w ( _ GBORDER, 0.4, 0.1, 0.6, 0.4 ) 

pause 

end 

Classification: PC Graphics 
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setwindow 


Systems: 


DOS 
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unregisterfonts 


Synopsis: 

Description: 

See Also: 

Example: 


Classification: 

Systems: 


subroutine _ unregisterfonts () 

The _ unregisterfonts routine frees the memory previously allocated by the_ registerfonts 
routine. The currently selected font is also unloaded. 

Attempting to use the _ setfont routine after calling_ unregisterfonts will result in an error. 

_ registerfonts,_ setfont^_ getfontinfo,_ outgtext^_ getgtextextent, 

_ setgtextvector,_ getgtextvector 

include 'graphapi.fi' 
include 'graph.fi' 

integer i, n 
character*10 buff 

call _ setvideomode ( _VRES16C0L0R ) 
n = _ registerfonts( '*.fon'c ) 
do i = 0, n - 1 

write( buff, ' (''n'', i2.2, al )' ) i, char(0) 

call _ setfont ( buff ) 

call _ moveto( 100, 100 ) 

call _ outgtext ( 'WATCOM Graphics'c ) 

pause 

call _ clearscreen ( _ GCLEARSCREEN ) 
enddo 

call _ unregisterfonts () 

call _ setvideomode ( _ DEFAULTMODE ) 

end 

PC Graphics 
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wrapon 


Synopsis: integer*2 function _ wrapon ( wrap ) 

integer*2 wrap 

Description: The _ wrapon routine is used to control the display of text when the text output reaches the right side 
of the text window. This is text displayed with the _ outtext and_ outmem routines. The wrap 
argument can take one of the following values: 

JGWRAPON causes lines to wrap at the window border 

JGWRAPOFF causes lines to be truncated at the window border 

Returns: The _ wrapon routine returns the previous setting for wrapping. 

See Also: _ outtext^ outmem^ settextwindow 

Example: include 'graphapi.fi' 

include 'graph.fi' 

integer i 
character buff*80 

call _ setvideomode( _ TEXTC80 ) 
call _ settextwindow( 5, 20, 20, 30 ) 
call _ wrapon ( _ GWRAPOFF ) 
do i = 1, 3 

call _ settextposition ( 2 * i, 1 ) 
write ( buff, 

'(''Very very long line '', i2, al)' ) 

i, char(0) 

call _ outtext ( buff ) 
enddo 

call _ wrapon ( _ GWRAPON ) 
do i = 4, 6 

call _ settextposition ( 2 * i, 1 ) 
write( buff, 

' (''Very very long line ' ' , i2, al) ' ) 

i, char(0) 

call _ outtext ( buff ) 
enddo 
pause 

call _ setvideomode( _DEFAULTMODE ) 
end 

Classification: PC Graphics 
Systems: DOS 
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ERESCOLOR 127 
ERESNOCOLOR 127 
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CAP 117 
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_clearscreen 12 , 98 
COLOR 41 
coordinate systems 3 
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1 FORTRAN Source Program Format 


1.1 Character Set 


The FORTRAN character set consists of twenty-six letters, ten digits, and thirteen special characters. 
The letters are: 

ABCDEFGHI JKLMNOPQRSTUVWXYZ 
The digits are: 0123456789 


The special characters are: 


Character 

Name of Character 


Blank 


Equals 

■ 

Plus 

- 

Minus 

* 

Asterisk 

/ 

Slash 

( 

Left Parenthesis 

) 

Right Parenthesis 
Comma 

Decimal Point 

$ 

Currency Symbol 
Apostrophe 

Colon 


The FORTRAN character set is a subset of the character set of the computing system which you are using. 
We shall refer to the larger character set as the processor character set. 


1.2 Extended Character Set 


Open Watcom FORTRAN 77 also includes the following special characters. 


Character 

Name of Character 

! 

Exclamation Mark 

% 

Percentage Symbol 

\ 

Back slash 
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1.3 Source Program Format 

Open Watcom FORTRAN 77 supports one source program format. A FORTRAN program is composed of 
lines. There are three types of lines; the comment line, the initial line, and the continuation line. 

1.3.1 Comment Line 

Comment lines are denoted by placing a "C" or in column one of the line. Open Watcom FORTRAN 
77 also allows the use of a lowercase "c" as a comment indicator. Blank lines are treated as comment lines. 
Comment lines may be placed anywhere in the program source (i.e., they may appear before a FORTRAN 
statement, they may be intermingled with continuation lines, or they may appear after a statement). There 
is no restriction on the number of comment lines. Comment lines may contain any characters from the 
processor character set. 


Open Watcom FORTRAN 77 allows end-of-line comments. If a "!" character appears in column 1 or 
anywhere in the statement portion of a source line, the remainder of that line is treated as a comment unless 
the "!" appears inside quotation marks or in column 6. 

1.3.2 Debug Line (Extension) 

Debug lines are denoted by placing a "D" or "d" in column one of the line. Debug lines contain 
FORTRAN statements. There is no restriction on the number of debug lines. Normally, the FORTRAN 
statements on debug lines are ignored by the compiler. See the User’s Guide for information on activating 
debug statements. 

1.3.3 Initial Line 

An initial line is the first line of a FORTRAN statement. Column 6 of this line must be blank or contain the 
digit "0". A comment line can never be an initial line. Columns 1 through 5 of an initial line may contain a 
statement label. Statement labels are composed entirely of digits. The statement label may be thought of 
as an integral number and, as such, leading 0 digits are not significant. For example, the label composed of 
the digits "00123" is the same as the label "123". The same label may not identify more than one statement 
in a program unit. A program unit is a series of comment lines and FORTRAN statements ending in an 
END statement. The body of the FORTRAN statement is entered starting in column 7 and stopping at 
column 72. Column 73 and on is called the sequence field and is ignored by the compiler. 

1.3.4 Continuation Line 

A statement may be continued on a new line. A continuation character is placed in column 6. The 
continuation character may not be a blank character or a "0" character. FORTRAN 77 requires that the 
continuation character be selected from the FORTRAN character set but Open Watcom FORTRAN 77 
allows any character from the processor’s character set. The statement number field must be blank. The 
previous statement is continued on the new line, starting in column 7 and continuing to column 72. Under 
the control of a compiler option. Open Watcom FORTRAN 77 permits the source statement to extend to 
column 132. 
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FORTRAN 77 allows up to 19 continuation lines to continue a statement. Open Watcom FORTRAN 77 
extends this by allowing more than 19 continuation lines. A minimum of 61 continuation lines are 
permitted when the source statement ends at column 72. A minimum of 31 continuation lines are permitted 
when the source statement ends at column 132. The maximum number of continuation lines depends on the 
sum of the lengths of all the continuation lines. 

1.3.5 Significance of the Blank Character 

Except in the following cases, blank characters have no meaning within a program unit. 

(1) Character and Hollerith constants. 

(2) Apostrophe and H edit descriptors in format specifications. 

For example, the symbolic name A B is the same as the symbolic name AB. 

1.3.6 Significance of Lower Case Characters (Extension) 


Except in the following cases, lower case characters are treated as if they were the upper case equivalent. 
This is a Open Watcom FORTRAN 77 extension to the usual rules of FORTRAN. 

(1) Character and Hollerith constants. 

(2) Apostrophe and H edit descriptors in format specifications. 

Hence, TOTAL, total, and Total represent the same symbolic name and 3F10.2 and 3f 10 . 2 
represent the same format edit descriptor. 

1.3.7 Examples 

Example: 

C This and the following five lines are comment lines, 
c The following statement "INDEX = INDEX + 2" has a 
c statement number and is continued by placing a "$" 
c in column 6. 

* Column Numbers 
*234567890 

10 INDEX = INDEX 
$ + 2 

* The above blank lines are treated like comment lines. 

The following example demonstrates the use of comment lines, blanks lines, and continuation lines. We 
use the symbol "$" to denote continuation lines although any character other than a blank or "0" could have 
been used. 
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Example: 

* From the quadratic equation 

★ 

* 2 

* ax + bx + c = 0 

★ 

* we derive the following two equations: 


+ / 2 

-b - \/ b - 4ac 


and express these equations 

in 

FORTRAN as 

XI 

= ( -B + 

SQRT ( 

B* *2 

- 4 

* A * C ) 

$ 

/ 

( 2 

* A ) 



X2 

= ( -B - 

SQRT ( 

B* *2 

- 4 

* A * C ) 

$ 

/ 

( 2 

* A ) 




1.4 Order of FORTRAN Statements and Lines 


The first statement of a program unit may be a PROGRAM, FUNCTION, SUBROUTINE, or BLOCK DATA 
statement. The PROGRAM statement identifies the start of a main program and there may only be one of 
these in an executable FORTRAN program. Execution of a FORTRAN program begins with the first 
executable statement in the main program. The other statements identify the start of a subprogram. If the 
first statement of a program unit is not one of the above then the program unit is considered to be a main 
program. 

Although you may not be familiar with all of the terms used here, it is important that you understand that 
FORTRAN 77 has specific rules regarding the ordering of FORTRAN statements. You may wish to refer 
to this section at later times. In general, the following rules apply to the order of statements and comment 
lines within a program unit: 

1. Comment lines and INCLUDE statements may appear anywhere. 

2. FORMAT statements may appear anywhere in a subprogram. 

3. All specification statements must precede all DATA statements, statement function statements, 
and executable statements. 

4. All statement function statements must precede all executable statements. 

5. DATA statements may appear anywhere after the specification statements. 

6. ENTRY statements may appear anywhere except between a block IF statement and its 
corresponding END IF statement, or between a DO statement and its corresponding terminal 
statement. Open Watcom FORTRAN 77 extends these rules to apply to all program structure 
blocks resulting from the use of statements introduced to the language by Open Watcom 
FORTRAN 77 (e.g., WHILE, LOOP, SELECT). 

7. IMPLICIT statements must precede all other specification statements, except PARAMETER 
statements. A specification statement that defines the type of a symbolic constant must appear 


6 Order of FORTRA N Statements and Lines 






FORTRAN Source Program Format 


before the PARAMETER statement that defines the name and value of a symbolic constant. A 
PARAMETER statement that defines the name and value of a symbolic constant must precede all 
other statements containing a reference to that symbolic constant. 

The following chart illustrates the required order of FORTRAN statements. Vertical lines delineate 
varieties of statements that may be interspersed, while horizontal lines mark varieties of statements that 
may not be interspersed. 



PROGRAM, FUNCTION, SUBROUTINE, or 


BLOCK DATA Statement 





IMPLICIT 



PARAMETER 

Statements 

Comment 

ENTRY 

Statements 

Other 

Lines 

and 


Specification 

Statements 


FORMAT 


Statement 

INCLUDE 



Function 

Statement 

Statements 

DATA 

Statements 



Statements 

Executable 

Statements 


END 

Statement 



Required Order of Comment Lines and Statements 

For example, DATA statements may be interspersed with statement function statements and executable 
statements but statement function statements must precede executable statements. 
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2 FORTRAN Statements 


2.1 Classifying Statements 

The following table is a summary of Open Watcom FORTRAN 77 statement classification. 

Column 1 indicates that the statement is a specification statement. 

Column 2 indicates that the statement is not allowed as the terminal statement of a DO-loop. 

Column 3 indicates that the statement is not executable. 

Column 4 indicates that the statement is not allowed as the object of a logical IF 

or WHILE statement. 

Column 5 indicates that the statement cannot have control of execution transferred to it by using a 

statement label. 

Column 6 indicates that the statement is allowed in a block data subprogram. 


Statement 

1 

2 

3 

4 

5 

6 

ADMIT 


* 


* 

* 


ALLOCATE 







ASSIGN 







AT END 


* 


* 

* 


BACKSPACE 







BLOCK DATA 


* 

* 

* 

* 


CALL 







CASE 


* 


* 

* 


CHARACTER 

* 

* 

* 

* 

* 

* 

CLOSE 







COMMON 

* 

* 

* 

* 

* 

* 
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Statement 

1 

2 

3 

4 

5 

6 

COMPLEX 

CONTINUE 

CYCLE 

* 

* 

* 

* 

* 

* 

DATA 


* 

* 

* 

* 

* 

DEALLOCATE 

DIMENSION 

* 

* 

* 

* 

* 

* 

DO 


* 


* 



DOUBLE COMPLEX 

* 

* 

* 

* 

* 

* 

DOUBLE PRECISION 

* 

* 

* 

* 

* 

* 

DO WHILE 


* 


* 



ELSE 


* 


* 

* 


ELSE IF 


* 


* 

* 


END 


* 


* 


* 

END AT END 


* 


* 

* 


END BLOCK 


* 


* 

* 


END DO 

ENDFILE 




* 

* 


END GUESS 


* 


* 



END IF 


* 


* 



END LOOP 


* 


* 

* 


END MAP 

* 

* 

* 

* 

* 

* 

END SELECT 

* 

* 

* 

* 

* 


END STRUCTURE 

* 

* 

* 

* 

* 

* 

END UNION 


* 


* 

* 

* 

END WHILE 


* 


* 

* 


ENTRY 


* 


* 

* 


EQUIVALENCE 

EXECUTE 

EXIT 

* 

* 

* 

* 

* 

* 

EXTERNAL 

* 

* 

* 

* 

* 


FORMAT 


* 

* 

* 

* 


FUNCTION 


* 

* 

* 

* 


assigned GO TO 
computed GO TO 


* 





unconditional GO TO 


* 





GUESS 


* 


* 



arithmetic IF 
logical IF 


* 


* 



block IF 


* 


* 
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Statement 

1 

2 

3 

4 

5 

6 

IMPLICIT 

* 

* 

* 

* 

* 

* 

INCLUDE 


* 

* 

* 

* 

* 

INQUIRE 







INTEGER 

* 

* 

* 

* 

* 

* 

INTRINSIC 

* 

* 

* 

* 

* 


LOGICAL 

* 

* 

* 

* 

* 

* 

LOOP 


* 


* 



MAP 

* 

* 

* 

* 

* 

* 

NAMELIST 

* 

* 

* 

* 

* 


OPEN 







OTHERWISE 


* 


* 

* 


PARAMETER 

* 

* 

* 

* 

* 

* 

PAUSE 







PRINT 







PROGRAM 


* 

* 

* 

* 


QUIT 







READ 







REAL 

* 

* 

* 

* 

* 

* 

RECORD 

* 

* 

* 

* 

* 

* 

REMOTE BLOCK 


* 

* 

* 

* 


RETURN 


* 





REWIND 







SAVE 

* 

* 

* 

* 

* 

* 

SELECT 


* 


* 



STOP 


* 





STRUCTURE 

* 

* 

* 

* 

* 

* 

SUBROUTINE 


* 

* 

* 

* 


UNION 

* 

* 

* 

* 

* 

* 

UNTIL 


* 


* 

* 


VOLATILE 

* 

* 

* 

* 

* 

* 

WHILE 


* 


* 



WRITE 








2.2 FORTRAN Statement Summary 

The following sections describe each FORTRAN 77 statement. The statement descriptions are organized 
alphabetically for quick reference. The syntax models for each statement are presented in shaded or 
unshaded boxes. The unshaded box denotes a standard FORTRAN 77 statement. The shaded box denotes 
a Open Watcom FORTRAN 77 extension to the language. Users should note that extensions which are 
supported by this compiler may not be supported by other compilers. We leave the choice to use a 
particular extension to the discretion of the programmer. 

In the following sections the use of square brackets ([ ]) denotes items which may be optionally specified. 
The use of the ellipsis (...) denotes items which may be repeated as often as desired. 
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2.3 ADMIT Statement 


ADMIT 


The ADMIT statement is used in conjunction with the structured GUESS statement. The ADMIT statement 
marks the beginning of an alternative block of statements that are executed if a QUIT statement is executed 
in a previous GUESS or ADMIT block. 

Example: 

* Assume incorrect sex code 

GUESS 

IF ( SEX .EQ. 'F' )QUIT 

IF( SEX .EQ. 'M' )QUIT 

PRINT *, 'Invalid sex code encountered' 

CALL INVSEX( SEX ) 


Wrong assumption - sex code is fine 
ADMIT 


END GUESS 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.4 ALLOCATE Statement 


ALLOCATE 

(array([1:]u[. 

[l:]u, . 


. .] [,LOCATION=loc]) 

or 





ALLOCATE 

(array([1:]u[. 

[l:]u, . 


. .] [,STAT=ierr] ) 

or 





ALLOCATE 

(char*len) 





where: 

array is the name of an allocatable array. 

/ is an integer expression that sets the lower bound of the array dimension. 

u is an integer expression that sets the upper bound of the array dimension. 

char is the name of an allocatable character variable. 

ten is an integer expression that sets the length of the character variable. 

LOCATION = loc 

loc is an integer expression that specifies the location of the allocated memory. 

STAT = ierr 

ierr is an allocation status specifier. The integer variable or integer array element ierr is 
defined with 0 if the allocation succeeded, 1 if the allocation failed, and 2 if the array is 
already allocated. The STAT= specifier may not be used with the LOCATION= specifier. 

Allocatable arrays and character variables may be dynamically allocated and deallocated at execution time. 
An array must have been declared allocatable by specifying its dimensions using colons only. No array 
bounds are specified. 

Example: 

DIMENSION A(:), B(:,:) 

In the above example, A is declared to be a one-dimensional allocatable array and B is declared to be a 
two-dimensional allocatable array. 

A character variable must have been declared allocatable by specifying its size as (*). 

Example: 

CHARACTER C*(* ) 

For an allocatable array, the ALLOCATE statement establishes the lower and upper bounds of each array 
dimension and calculates the amount of memory required for the array. 

For an allocatable character variable, the ALLOCATE statement establishes the number of characters in the 
character variable and thus the size of the character variable. 

If there is no LOCATION= specifier, it then attempts to dynamically allocate memory for the array or 
character variable. The success of the allocation can be checked by using the STAT= specifier. 
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If there is a LOCATION= specifier, the expression in the specification is evaluated and that value is used as 
the address of the array or character variable. This permits the programmer to specify a substitute memory 
allocator or to map the array or character variable onto a fixed memory location. 

Example: 

DIMENSION A(:), B(:, :) 


ALLOCATE( A(N) ) 

ALLOCATE ( B(0:4,5) ) 

More than one allocatable array or character variable may appear in an ALLOCATE statement, separated by 
commas. 

Example: 

DIMENSION A(:), B(:, :) 


ALLOCATE( A(N), B(0:4,5) ) 

If the allocation fails and the STAT= specifier was not used, an execution-time error occurs. If the STAT= 
specifier is used, the specified variable returns a zero value if the allocation succeeded, and a non-zero 
value if the allocation failed. 


Example: 

DIMENSION A(:), B(:,:) 


ALLOCATE( A(N), B(0:4,5), STAT=IALLOC ) 

IF( IALLOC .NE. 0 ) PRINT *, 'Allocation failure' 

An attempt to allocate a previously allocated array or character variable results in an execution-time error. 

If the LOCATION= specifier was not used, the array or character variable must be deallocated first before it 
can be allocated a second time (see the DEALLOCATE statement). 

An absolute memory location may be specified using the LOCATION= specifier. 


Example: 

CHARACTER*1 SCREEN) 

N = 80*25 
*$IFDEF_ 38 6_ 

ALLOCATE( SCREEN(0:1,0:N-l), LOCATION='B8000'x ) 

* $ELSE 

ALLOCATE( SCREEN(0:1,0:N-l), LOCATION='B8000000'x ) 
*$ENDIF 

DO I = 0, N-l 

SCREEN(0,1) = '*' 

ENDDO 

END 


The above example maps the array SCREEN onto the IBM PC colour monitor screen memory and then fills 
the screen with asterisks (16-bit real-mode only). The character is stored in SCREEN (0,1) and the 
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character attribute (unchanged in this example) is stored in SCREEN (1,1) . The column major ordering 
of arrays must be taken into consideration when mapping an array onto a fixed area of memory. 

The following example is similar but uses an allocatable character variable. 


Example: 

CHARACTER*(*) SCREEN 

INTEGER SCRSIZE, I 

PARAMETER ( SCRSIZE = 80*25*2 ) 

*$IFDEF_ 38 6_ 

ALLOCATE( SCREEN*SCRSIZE, LOCATION^B8000'X ) 

* $ELSE 

ALLOCATE( SCREEN*SCRSIZE, LOCATION^B8000000' X ) 
*$ENDIF 

DO I = 1, SCRSIZE, 2 
SCREEN(I:I) = '*' 

ENDDO 

END 


A user-defined memory allocator may be specified using the LOCATION= specifier. 
Example: 

CHARACTER*1 BUFFER(:) 

N = 128 

ALLOCATE( BUFFER(0:N-l), LOCATION=MYALLOC(N) ) 


END 


Perhaps a better way to check for a successful allocation, in this case, would be the following. 


Example: 

CHARACTER*1 BUFFER(:) 

N = 128 

LOC = MYALLOC( N ) 

IF( LOC .EQ. 0 ) STOP 

ALLOCATE( BUFFER(0:N-l) , LOCATION=LOC ) 


END 

For more information on arrays, see the chapter entitled "Arrays" on page 159. 
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2.5 Statement Label Assignment (ASSIGN) Statement 


ASSIGN s TO i 


where: 

s is a statement label 

i is an integer variable name 

The statement label s is assigned to the integer variable i . The statement label must appear in the same 
program unit as the ASSIGN statement. The statement label must be that of an executable statement or a 
FORMAT statement. 

After a statement label has been assigned to an integer variable, that variable may only be used in an 
assigned GO TO statement or as a format identifier in an input/output statement. The integer variable must 
not be used in any other way (e.g., in an arithmetic expression). It may, however, be redefined with another 
statement label using the ASSIGN statement or it may be assigned an integer value (e.g., in an arithmetic 
assignment statement). 

Example: 

INTEGER RET 

X = 0.0 

ASSIGN 100 TO RET 
GO TO 3000 
100 X = X + 1 

ASSIGN 110 TO RET 
GO TO 3000 
110 X = X + 1 


* Print both X and its square root 

3000 Y = SQRT( X ) 

PRINT *, X, Y 
GO TO RET 


In the above example, we illustrate the use of the ASSIGN statement and the assigned GO TO statement to 
implement a "local subroutine" in a program unit. A sequence of often-used code can be "called" using the 
unconditional GO TO statement and "return" is accomplished using the assigned GO TO statement. Care 
must be exercised to properly assign the return label value. 


Example: 

IF ( FIRST )THEN 

ASSIGN 100 TO LFRMT 

ELSE 

ASSIGN 200 TO LFRMT 
END IF 

WRITE( UNIT=5, FMT=LFRMT) X, Y, Z 
100 FORMAT(IX,3F10.5) 

200 FORMAT(IX,3E15.7) 
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It should be noted that the ASSIGN statement does not assign the numeric value of the statement label to 
the variable. 


Example: 

ASSIGN 100 TO LABEL2 
PRINT *, LABEL2 


Try the above example; the value printed will not be 100. 
Consider the following example. 


Example: 

* Illegal use of a GOTO 
LABEL2 = 123 
LABEL3 = LABEL2 + 
GO TO LABEL3 


statement. 
10 


LABEL3 is assigned the integer value 133. The assigned GO TO statement, which follows it, is illegal and 
a run-time error will occur when it is executed. 

Statement label values are quite different from integer values and the two should never be mixed. In the 
following example, the assignment statement is illegal since it involves an integer variable that was 
specified in an ASSIGN statement. 

Example: 

* Illegal use of an ASSIGNed variable in an expression. 

ASSIGN 100 TO LABEL2 
LABEL3 = LABEL2 +10 

Note that if the assignment statement was preceded by 

LABEL2 = 100 

the assignment statement would have been legal. 
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2.6 AT END Statement 



where: 

stmt is an executable statement other than an AT END statement. 

The AT END control statement is an extension of the END= option of the READ statement for sequential 
files. It allows a statement or a block of code following the READ statement to be executed when an 
end-of-file condition is encountered during the read. The AT END statement or block is by-passed if no 
end-of-file occurs. It is not valid to use this control statement with direct-access or internal files. It is not 
valid to use this statement when END= is also specified in the READ statement. The AT END statement or 
block must immediately follow the READ statement to which it applies. 


Example: 

READ( UNIT=1, FMT=' (15,FI0.4)' ) I, X 

AT END DO 

PRINT *, 'END-OF-FILE ENCOUNTERED ON UNIT 1' 
EOFSW = .TRUE. 

END AT END 


The second form of the AT END statement is illustrated below. 


Example: 

READ( UNIT=1, FMT='(F10.4)' ) X 

AT END, EOFSW = .TRUE. 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.7 BACKSPACE Statement 


BACKSPACE u 
BACKSPACE (alist) 


where: 

u is an external unit identifier. 

alist is a list of backspace specifiers separated by commas: 

[UNIT =] u 
IOSTAT = ios 
ERR = s 

Execution of a BACKSPACE statement causes the file connected to the specified unit to be positioned at the 
beginning of the preceding record. If the preceding record is an endfile record then the file is positioned at 
the beginning of the endfile record. 

Backspace Specifiers 

[UNIT =] u 

u is an external unit identifier. An external unit identifier is a non-negative integer 
expression. If the optional UNIT= specifier is omitted then the specifier must be the first 
item in the list of specifiers. 

IOSTAT = ios 

is an input/output status specifier. The integer variable or integer array element ios is 
defined with zero if no error condition occurs or a positive integer value if an error 
condition occurs. 

ERR = s 

is an error specifier and s is a statement label. When an error occurs, execution is 
transferred to the statement labelled by s . 

Example: 

LOOP 

READ( UNIT=8, END=100, FMT=200 ) RECORD 
ENDLOOP 

100 BACKSPACE( UNIT=8 ) 

WRITE( UNIT=8, FMT=200 ) NEWREC 

In the previous example, we illustrate how one might append a record to the end of an existing file. 

Notes: 

1. The unit must be connected for sequential access. 

2. If the file is positioned before the first record then the BACKSPACE statement has no effect. 

3. It is illegal to backspace a file that does not exist. 
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The FORTRAN 77 standard specifies that it is illegal to backspace over records that were written using 
list-directed formatting; Open Watcom FORTRAN 77 allows it. 

If the file has been opened with access ' APPEND' , which is a form of sequential access in which the file 
is positioned at the endfile record, then the BACKSPACE statement cannot be used. 

For more information on input/output, see the chapter entitled "Input/Output" on page 215. 
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2.8 BLOCK DATA Statement 


BLOCK DATA [sub] 


where: 

sub is an optional symbolic name of the block data subprogram and must not be the name of an 
external procedure, main program, common block, other block data subprogram, or any local 
name in the block data subprogram. 

The BLOCK DATA statement is used to define the start of a block data subprogram. A block data 
subprogram is used to provide initial values for variables and array elements in named common blocks. 

The only statements which are allowed to appear in a block data subprogram are: 


1 . 

IMPLICIT 

2. 

PARAMETER 

3. 

DIMENSION 

4. 

COMMON 

5. 

SAVE 

6. 

EQUIVALENCE 

7. 

DATA 

8. 

STRUCTURE, END STRUCTURE 

9. 

UNION, END UNION 

10. 

MAP, END MAP 

11. 

RECORD 

12. 

END 

13. 

type statements 

Example: 

BLOCK DATA INITCB 
DIMENSION A(10), B(10) 
COMMON /CB/ A, B 

DATA A/10*1.0/, B/10*2 
END 


In the above example, the arrays A and B in the named common block CB are initialized. 

Notes: 

1. More than one named common block may appear in a block data subprogram. 

2. All entities of the named common block(s) must be specified. 

3. Not all entities need be given initial values. 

4. Only entities that appear in (or are associated, through the EQUIVALENCE statement, with 
entries in) a named common block may be given initial values. 

5. Only one unnamed block data subprogram may occur in an executable program. 
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6. A named block data subprogram may occur only once in an executable program. 
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2.9 CALL Statement 


CALL sub [( [a [, a] ... ] ) ] 


where: 

sub is a symbolic name of a subroutine and must not be the name of a main program, function, 

common block, or block data subprogram. As an extension to FORTRAN 77, Open Watcom 
FORTRAN 77 permits the calling of functions. 

a is an actual argument. 

The CALL statement is used to invoke the execution of a subroutine subprogram or function. 


Example: 

X = 1.0 
Y = 1.1 
Z = 1.2 

CALL QUAD( X, Y, Z ) 


END 

SUBROUTINE QUAD( ARGA, ARGB, ARGC ) 
REAL ARGA, ARGB, ARGC 

PRINT *, 2.0*ARGA**2 + 4.0*ARGB + ARGC 
END 


In the above example, the variables X, Y and Z are passed to the subroutine QUAD . This subroutine 
computes an expression and prints the result. 

Notes: 

1. The parameters in the CALL statement are called actual arguments. 

2. The parameters in the SUBROUTINE statement are called dummy arguments. 

3. The actual arguments in a subroutine or function reference must agree in order, number and 
type with the corresponding dummy arguments. 

4. An actual argument may be an expression, array name, intrinsic function name, external 
procedure name (i.e., a subroutine or function name), a dummy procedure name (i.e., one that 
was an argument to the calling subroutine or function), or an alternate return specifier 
(subroutines only). An alternate return specifier takes the form *s, where s is the statement 
label of an executable statement that appears in the same program unit as the CALL statement. 
An expression may not be a character expression involving the concatenation of an operand 
whose length specification is (*) unless the operand is the symbolic name of a constant. 

5. Actual arguments are associated with dummy arguments by passing the address of the actual 
arguments. 
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It is important to note that versions of FORTRAN compilers that implement the previous 
FORTRAN language standard may have associated arguments by passing the value of the actual 
argument and assigning it to the dummy argument and then updating the actual argument upon 
return from the subprogram (this is called "value-result" argument handling). The FORTRAN 
77 language standard prohibits this technique for handling argument association. 

The following example illustrates the importance of this rule. 


Example: 

1=1 

CALL ASSOC( I, I ) 

END 

SUBROUTINE ASSOC( M, N ) 
M = M + 1 
PRINT *, M, N 
END 


In the above example, M and N refer to the same variable; they are both associated to I in the 
calling subprogram. The value 2 will be printed twice. 

For more information, see the chapter entitled "Functions and Subroutines" on page 243. 
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2.10 CASE Statement 


CASE cl 


where: 


cl is a list, enclosed in parentheses, of one or more cases separated by commas, or the DEFAULT 
keyword. A case is either 

(a) a single integer, logical or character constant expression or 

(b) an integer, logical or character constant expression followed by a colon followed by 
another expression or the same type. This form of a case defines a range of values 
consisting of all integers or characters greater than or equal to the value of the 
expression preceding the colon and less than or equal to the value of the expression 
following the colon. 

The CASE statement is used in conjunction with the SELECT statement. The CASE statement marks the 
start of a new CASE block which is a series of zero or more statements ending in another CASE statement, a 
CASE DEFAULT statement, or an END SELECT statement. 


A particular case value or range of values must not be contained in more than one CASE block. 

The CASE DEFAULT statement is used to indicate a block of statements that are to be executed when no 
other case is selected. 


Example: 


SELECT CASE 
CASE ( 'a' : 

PRINT *, 
CASE ( 'A' : 

PRINT *, 
CASE ( 'O' : 

PRINT *, 
CASE DEFAULT 
PRINT *, 
END SELECT 


CH ) 

' z' ) 

'Lower case 
' Z' ) 

'Upper case 
' 9' ) 

'Digit' 


letter' 

letter' 


'Special character' 


In order to retain compatibility with earlier versions of WATCOM FORTRAN 77 compilers, the 
OTHERWISE statement may be used in place of the CASE DEFAULT statement. 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.11 CHARACTER Statement 


The CHARACTER statement is a type declaration statement and can be used to declare a name to be of type 
character. The implicit type of the name, whether defined by the "first letter rule" (see the chapter entitled 
"Names, Data Types and Constants" on page 151) or by an IMPLICIT statement, is either confirmed or 
overridden. However, once a name has been declared to be of type character, it cannot appear in another 
type declaration statement. 

There are various forms of the CHARACTER statement. The following sections describe them. 

2.11.1 Standard CHARACTER Statement 


CHARACTER[*len [,]] name [,name] ... 


where: 

name is one of the following forms: 
v [ *len] 
a(d)[*len] 
a[*len](d) 

v is a variable name, symbolic name of a constant, function name or dummy procedure name. 

a is an array name. 

(d) is that part of the array declarator defining the dimensions of the array. 

ten is called the length specification and is the length (number of characters) of a character variable, 

character array element, symbolic character constant or character function. It has one of the 
following forms: 

(1) An unsigned positive integer constant. 

(2) A positive integer constant expression enclosed in parentheses. 

(3) An asterisk in parentheses (*) . 

The length specification immediately following the word CHARACTER is the length specification for each 
entity in the statement not having its own length specification. If omitted, the default is 1. An entity with 
its own length specification overrides the default length specification or the length specification 
immediately following the word CHARACTER . Note that for an array the length specification applies to 
each element of the array. 
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Example: 

DIMENSION C(-5:5) 

CHARACTER A, B*10(10), C*20 
CHARACTER*? X, Y, Z*4 

The (*) length specification is only allowed for external functions, dummy arguments or symbolic 
character constants. If a dummy argument has a length specification of (*) , it assumes the length of the 
corresponding actual argument. If the actual argument is an array name, the length assumed by the dummy 
argument is the length of an array element of the actual array. 


Example: 

SUBROUTINE OUTCHR( STR ) 
CHARACTER STR*(*) 

PRINT *, STR 
END 


In this example, STR is a character variable whose length is the length of the actual argument. Thus 
OUTCHR can be called with a character entity of any length. 

If an external function has a length specification of (*) declared in a function subprogram, the function 
name must appear as the name of a function in a FUNCTION or ENTRY statement in the same subprogram. 
When the function is called, the function assumes the length specified in the program unit that called it. In 
the following example, when F is called its length is assumed to be 10. 

Example: 

CHARACTER*(10) F 


PRINT *, F() 


END 

CHARACTER*(*) FUNCTION F 
F = 'HELLO' 

END 


The following example is illegal since F does not appear in a FUNCTION or ENTRY statement. 
Example: 

* Illegal definition of function F. 

CHARACTER*(*) F 


PRINT *, F() 


END 


The length specified for a character function in the program unit that referenced it must agree with the 
length specified in the subprogram that defines the character function. Note that there is always agreement 
if the function is defined to have a length specification of (*) . 
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If a symbolic name is of type character and has a length specification of (*) , it assumes the length of the 
corresponding character constant expression in the PARAMETER statement. 

The length specification of a character statement function or statement function dummy argument must not 
be (*) . 

2.11.2 Extended CHARACTER Statement: Data Initialization 


CHARACTER[*len[,]] name [/cl/] [,name[/cl/]] ... 


where: 


name 

is as described in the previous section. 

len 

is as described in the previous section. 

cl 

is a list of the form: 


k [,k] ... 

k 

is one of the forms: 


c 

r*c (equivalent to r successive appearances of c) 
c is a constant or the symbolic name of a constant 

r is an unsigned positive integer constant or the symbolic name of a constant. 

This form of the CHARACTER statement is an extension to the FORTRAN 77 language. The rules for data 
initialization are the same as for the DATA statement. 

Example: 

CHARACTER*5 A/'AAAAA' /, B*3 (10)/10 * '111'/ 

In the previous example, A is initialized with the character constant ' AAAAA' and each element of the 
array B is initialized with the character constant '111' . 
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2.12 CLOSE Statement 


CLOSE (cllist) 


where: 

cllist is a list of close specifiers separated by commas: 

[UNIT =] u 
IOSTAT = ios 
ERR = s 
STATUS = sta 

A CLOSE statement is used to terminate the connection of a file to the specified unit. 

Close Specifiers 
[UNIT =] u 

u is an external unit identifier. An external unit identifier is a non-negative integer 
expression. If the optional UNIT= specifier is omitted then the specifier must be the first 
item in the list of specifiers. 

IOSTAT = ios 

is an input/output status specifier. The integer variable or integer array element ios is 
defined with zero if no error condition occurs or a positive integer value if an error 
condition occurs. 

ERR = s 

is an error specifier and s is a statement label. When an error occurs, execution is 
transferred to the statement labelled by s . 


STATUS = sta 

is a status specifier and sta is a character expression whose value when trailing blanks are 

removed evaluates to one of ' KEEP ' or ' DELETE' . 

KEEP 'KEEP' may not be specified for a file whose status is 'SCRATCH' (see 

description of the OPEN statement). If the file exists, it will exist after 
execution of the CLOSE statement. If the file does not exist, it will not 
exist after execution of the CLOSE statement. If not specified, ' KEEP ' is 
assumed, unless the file status is 'SCRATCH' in which case 'DELETE' is 
assumed. 

DELETE If ' DELETE ' is specified, the file will not exist after execution of the 
CLOSE statement. 
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Example: 

LOOP 

READ( UNIT=8, END=100, FMT=200 ) RECORD 
ENDLOOP 

100 CLOSE ( UNIT=8 ) 

In the previous example, we illustrate how one might process the records in a file and then terminate the 

connection of the file to unit 8 using the CLOSE statement. 

Notes: 

1. Execution of a CLOSE statement specifying a unit that is not connected to a file or a unit that is 
connected to a file that does not exist has no effect. 

2. It is possible to connect the unit to another file after a CLOSE statement has been executed. 

3. It is possible to connect the unit to the same file after a CLOSE statement has been executed, 
provided that the file still exists. 

4. It is possible to connect the file to another unit after a CLOSE statement has been executed, 
provided that the file still exists. 

5. At the termination of execution of the program, for whatever the reason of termination, any units 
that are connected are closed. Each unit is closed with status ' KEEP ' unless the file status was 
' SCRATCH' , in which case the unit is closed with status ' DELETE' . The effect is the same 
as if a CLOSE statement is executed without a STATUS= specifier. 

For more information on input/output, see the chapter entitled "Input/Output" on page 215. 
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2.13 COMMON Statement 


COMMON [/[cb]/] nlist [[,]/[cb]/ nlist] ... 


where: 

cb is a common block name. 

nlist is a list of names each separated by a comma. 

If cb is omitted, the blank common block is assumed. If specified, cb is called a named common block. 

The names appearing in nlist can be variable names, array names, and array declarators. Dummy 
arguments are not allowed in nlist. 

The COMMON statement allows sharing of blocks of storage between subprograms. Each name appearing in 
the nlist following a common block name cb is declared to belong to that common block. A variable or 
an array name can belong to only one common block. A common block name can occur more than once in 
the same COMMON statement as well as in more than one COMMON statement. Lists following successive 
appearances of the same common block name in COMMON statements are considered a continuation of the 
list of names belonging to the common block. A variable or an array can appear in a COMMON statement 
only once. 

Common blocks are defined as follows. A common block is one consecutive block of storage. It consists 
of all the storage sequences of all the entities specified in all the lists declared to belong to that common 
block. The order in which each entity appears in a common block is defined by the order in which they 
appear in the lists. Storage sequences associated to a common block through the EQUIVALENCE statement 
are considered to belong to that common block. In this way a common block may only be extended beyond 
the last storage unit. The size of a common block is the sum of all the storage sequences of all the names 
belonging to that common block plus any storage sequence which extends the common block through 
equivalence association. 

An EQUIVALENCE statement must not cause storage sequences of two different common blocks to 
become associated nor should they extend the common block by adding storage units preceding the first 
storage unit of the common block. 

Example: 

DIMENSION A(5) 

COMMON /COMBLK/ A,B(10),C 

In this example, the common block COMBLK contains the array A followed by the array B and finally the 
variable C. 
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Example: 

REAL A,B,C,D 
DIMENSION D (5) 

EQUIVALENCE (B,D) 

COMMON A,B,C 

In this example. A, B, C, and D belong to the blank common block; A, B, and C have been explicitly 
defined to be in the blank common block whereas D has been equivalenced to a variable in common, 
namely B . Also note that the EQUIVALENCE statement has caused the extension of the common block 
beyond its last storage unit. In this example, array D has extended the common block by 3 storage units. 

Example: 

* Illegal definition of a common block. 

DIMENSION A(5) 

EQUIVALENCE (A(2),B) 

COMMON /XYZ/ B 

This example demonstrates an illegal use of the COMMON statement. B is in the named common block XYZ 
since it appeared in a COMMON statement. A is in the common block XYZ since it was equivalenced to B . 
However, A illegally extends the common block by adding 1 storage unit before the first storage unit of the 
common block. 

The following outlines the differences between a blank common block and a named common block. 

(1) All named common blocks with the same name in an executable program must be the same 
size. Blank common blocks do not have to be the same size. 

(2) Entities in named common blocks can be initialized by using DATA statements in block 
data subprograms; entities in blank common blocks cannot. 

(3) Entities in named common blocks can become undefined after the execution of a RETURN 
or END statement; entities in blank common blocks cannot. This situation can arise when 
all subprograms which refer to the named common block become inactive. A typical case 
occurs when program overlays are used. If the named common block is placed in an 
overlay, then the entities in the named common block will become undefined when the 
overlay is replaced by another. Of course, if the named common block is referenced in the 
main program then this could never happen. The main program and any named common 
blocks referenced in the main program remain memory-resident until the application 
terminates. 

The SAVE statement should be used if entities in named common blocks must not become 
undefined. 


The FORTRAN 77 standard specifies that a common block cannot contain both numeric and character 
data; Open Watcom FORTRAN 77 allows common blocks to contain both numeric and character data. 

The FORTRAN 77 standard specifies that a named common block must be initialized in a block data 
subprogram. Open Watcom FORTRAN 77 permits the initialization of named common blocks in other 
subprograms. 
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2.14 COMPLEX Statement 


The COMPLEX statement is a type declaration statement and can be used to declare a name to be of type 
complex. The implicit type of the name, whether defined by the "first letter rule" (see the chapter entitled 
"Names, Data Types and Constants" on page 151) or by an IMPLICIT statement, is either confirmed or 
overridden. However, once a name has been declared to be of type complex, it cannot appear in another 
type declaration statement. 

There are various forms of the COMPLEX statement. The following sections describe them. 

2.14.1 Standard COMPLEX Statement 


COMPLEX name [,name] ... 


where: 

name is a variable name, array name, array declarator, symbolic name of a constant, function name or 
dummy procedure name. 

This form is the standard form of the COMPLEX statement. 

Example: 

DIMENSION C (-5:5) 

COMPLEX A, B(10), C 

In the previous example, A is defined to be a variable of type complex and B and C are defined to be arrays 
of type complex. 

2.14.2 Extended COMPLEX Statement: Length Specification 


COMPLEX[*len[,]] name [,name] ... 


where: 

name is one of the following forms: 
v [ *len] 
a [ *len] (d) 
a(d)[*len] 

v is a variable name, array name, symbolic name of a constant, function name or dummy 

procedure name. 
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a is an array name. 

(cl) is that part of the array declarator defining the dimensions of the array. 

len is called the length specification and is an unsigned positive integer constant or an integer 

constant expression enclosed in parentheses whose value is 8 or 16. 

This form of the COMPLEX statement is a Open Watcom FORTRAN 77 extension to the FORTRAN 77 
language. The length specification specifies the number of bytes of storage that will be allocated for the 
name appearing in the COMPLEX statement. The default length specification is 8. A length specification of 
16 specifies that the data type of the name appealing in the COMPLEX statement is to be double precision 
complex. 

The length specification immediately following the word COMPLEX is the length specification for each 
entity in the statement not having its own length specification. If a length specification is not specified the 
default length specification is used. An entity with its own specification overrides the default length 
specification or the length specification immediately following the word COMPLEX. Note that for an array 
the length specification applies to each element of the array. 

Example: 

DIMENSION C (-5:5) 

COMPLEX A, B*16(10), C*16 
COMPLEX*16 X 

In the previous example, X is declared to be a variable of type double precision complex, A is declared to be 
a variable of type complex and B and C are declared to be arrays of type double precision complex. 

2.14.3 Extended COMPLEX Statement: Data Initialization 


COMPLEX[*len[,]] name [/cl/] [,name[/cl/]] ... 


where: 


name 

is as described in the previous section. 

len 

is as described in the previous section. 

cl 

is a list of the form: 


k [,k] ... 

k 

is one of the forms: 


c 

r*c (equivalent to r successive appearances of c) 
c is a constant or the symbolic name of a constant 
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r is an unsigned positive integer constant or the symbolic name of a constant. 

This form of the COMPLEX statement is an extension to the FORTRAN 77 language. The rules for data 
initialization are the same as for the DATA statement. 

Example: 

COMPLEX A/(.4,-.3)/, B(10)/10* (0,1) / 

In the previous example, A is initialized with the complex constant ( .4, — .3) and each element of the 
array B is initialized with the complex constant (0,1) . 
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2.15 CONTINUE Statement 


CONTINUE 


Execution of a CONTINUE statement has no effect. This statement is often used in conjunction with DO 
statements. It is usually identified with a label. It often provides a convenient reference for statements 
which have the ability to transfer control of execution. 

Example: 

DO 10 X = -5.1, 12.8, 0.125 


10 CONTINUE 

IF( A .LT. B ) GO TO 20 
IF( A .GT. C ) GO TO 20 


20 CONTINUE 


36 CONTINUE Statement 




FORTRAN Statements 


2.16 CYCLE Statement 


CYCLE [: block-label] 


The CYCLE statement may be used to cause a transfer of control from within a loop to the terminal 
statement of a corresponding DO, DO WHILE, WHILE or LOOP statement. If block-label is present 
then control is transferred to the terminal statement of the block identified by that block label. The CYCLE 
statement is an extension to the FORTRAN 77 language. 

Example: 

LOOP 

WRITE( UNIT=*, FMT='(A)' ) 'Enter a number' 

READ( UNIT=*, FMT=' (FI0.4)', IOSTAT=IOS ) X 
IF ( IOS .NE. 0 ) CYCLE 
IF( X .LT. 0 ) EXIT 
PRINT *, X, SQRT( X ) 

END LOOP 
END 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.17 DATA Statement 


DATA nlist/clist/ [[,]nlist/clist/] ... 


where: 

nlist is a list of variable names, array element names, substring names and implied-DO lists. 

clist is a list of the form: 

a [,a] ... 

a is one of the forms: 

c 

r*c (equivalent to r successive appearances of c) 
c is a constant or the symbolic name of a constant 

r is an unsigned positive integer constant or the symbolic name of a constant. 

The items of nlist are initialized with the values specified in clist in the following manner. The first 
item in nlist is assigned the value of the first item in clist, the second item in nlist is assigned the 
value of the second item in clist, etc. In this way all items of nlist are initialized. 

The number of items in nlist must equal the number of items in clist so that a one-to-one 
correspondence exists between the two lists. If an array without a subscript list appears in nlist there 
must be an element in clist for each element of the array. 

If the type of an entity in nlist is character or logical then the type of its corresponding item in clist 
must also be character or logical respectively. As an extension to FORTRAN 77, Open Watcom 
FORTRAN 77 permits an item of type character to be initialized with integer data. 

An item of type character is initialized using the rules of assignment. If the length of the item in nlist is 
greater than the length of the corresponding character constant in clist, the rightmost remaining 
characters in the item are initialized with blanks. If the length of the item in nlist is less than the length 
of the character constant in clist, the character constant is truncated to the length of the item in 
nlist. Note that initializing a character entity causes all of the characters in the entity to become defined 
and that each character constant defines exactly one character variable, array element or substring. 

If the type of an entity in nlist is integer, real, double precision or complex then the corresponding item 
in clist can be one of integer, real, double precision or complex. If necessary the constant in clist is 
converted to the type of the item in nlist according to the rules of arithmetic conversion (see the chapter 
entitled "Assignment Statements" on page 187). 

A variable, array element or substring can only be initialized once. If two entities are associated (for 
example equivalenced), only one of the items can be initialized. 
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Example: 

CHARACTER*30 MSG 
LOGICAL TRUE 
REAL X, Y (10) 

DATA X/1.0/, TRUE/.TRUE./, MSG/'ENTER DATA'/ 

DATA Y/10*5/ 

An implied-DO list in a DATA statement has the following form: 

( dlist, i = ml, m2[, m3] ) 

where: 

dlist is a list of array element names and implied-DO lists. 

i is the name of an integer variable called the implied-DO-variable. 

ml,m2,m3 are each integer constant expressions. The expressions may contain 

implied-DO-variables of other implied-DO lists that have this implied-DO list in their 
ranges. 

The range of the implied-DO list is the list dlist. An iteration count and the value of the 
implied-DO-variable are computed from ml, m2 and m3 in the same way as for a DO-loop except that the 
iteration count must be positive. An implied-DO-variable does not affect the definition of a variable by the 
same name in the same program unit. An implied-DO list is processed as follows. Each item in the 
implied-DO list is processed once for each iteration with the appropriate substitution of values for any 
occurrence of the implied-DO-variable. The following example initializes the upper right triangle of the 
array A. 

Example: 

DIMENSION A(5,5) 

DATA ((A(I,J),J=l,I),1=1,5)/15*0/ 

Dummy arguments, functions, and entities in blank common are not allowed in nlist. Entities in a 
named common block can be initialized only within a block data subprogram. 

The following extensions to data initialization are supported by Open Watcom FORTRAN 77. 

1. Character constants can initialize a variable of any type. If the item in nlist is of numeric 
type and is being initialized with character data, the size of the item in nlist is the maximum 
number of characters that can be stored in the space allocated for that item. The rules for 
initializing such items, are the same as for items of type character. See the chapter entitled 
"Names, Data Types and Constants" on page 151 for the number of bytes required for a 
particular data type. 

Example: 

INTEGER I,J 

DATA I/'AA'/, J/' 123456'/ 

In the previous example, I and J each occupy 4 character storage units. I will be initialized 
with the characters AA followed by 2 blank characters. J will be initialized with the characters 
12 34 . Note the the character constant initializing J is truncated on the right to the number of 
character storage units occupied by J. 
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2. As an extension to FORTRAN 77, Open Watcom FORTRAN 77 permits an item of type 
character to be initialized with integer data. 

Example: 

CHARACTER C, D 
DATA C/65/, D/66/ 

END 


3. Open Watcom FORTRAN 77 allows data initialization using hollerith constants. Initializing 
items using hollerith constants behaves in the same way as initializing items using character 
constants. Note that hollerith data can initialize entities of any type. See the chapter entitled 
"Names, Data Types and Constants" on page 151 for a description of hollerith constants. 

4. Open Watcom FORTRAN 77 allows data initialization using hexadecimal or octal constants. 
Hexadecimal or octal constants can be used to initialize memory with any binary pattern. 

Items are initialized with hexadecimal constants in the following way. Two hexadecimal digits 
are required to initialize one byte of storage. If the number of characters in the hexadecimal 
constant is less than 2 times the number of bytes of storage allocated for the entity being 
initialized, the entity is padded on the left with zeroes. If the number of characters in the 
hexadecimal constant is greater than 2 times the number of bytes of storage allocated for the 
entity being initialized, the constant is truncated on the left to the size (in bytes) of the entity 
being initialized. 

Items are initialized with octal constants in the following way. Each octal digit initializes three 
bits of storage. If the number of digits in the octal constant times 3 is less than the number of 
bits of storage allocated for the entity being initialized, the entity is padded on the left with zero 
bits. If the number of digits in the octal constant times 3 is greater than the number of bits of 
storage allocated for the entity being initialized, bits are truncated on the left to the size (in bits) 
of the entity being initialized. 

Note that hexadecimal or octal data can initialize entities of any type. See the chapter entitled 
"Names, Data Types and Constants" on page 151 for a description of hexadecimal and octal 
constants. 

Example: 

DOUBLE PRECISION DPREC 
COMPLEX CMPLX 

* Initialize an integer variable with the value 5 

DATA I/Z05/ 

* Initialize a real variable with the value 5.0 

DATA X/Z41500000/ 

* Initialize a double precision variable 

* with the value 5D0 

DATA DPREC/Z4150000000000000/ 

* Initialize a complex variable 

* with the value (5.0,5.0) 

DATA CMPLX/Z4150000041500000/ 


END 
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Caution should be used when initializing items with hexadecimal constants, in particular those 
whose type is real or double precision, since the data they represent depends on the computer 
being used. In the previous example, the hexadecimal constant used to initialize the variable X, 
represents the number 5.0 on a computer with an IBM 370 architecture. The number 5.0 will 
have a different floating-point representation on other computers. 


DATA Statement 


41 





Language Reference 


2.18 DEALLOCATE Statement 


DEALLOCATE (arraylist [, STAT = ierr]) 


where: 

arraylist is a list of allocatable array names separated by commas. 

ierr is an integer variable that returns the status of the attempted deallocation. 

Allocatable arrays may be dynamically allocated and deallocated at execution time. An array must have 
been declared allocatable by specifying its dimensions using colons only. No array bounds are specified. 

Example: 

DIMENSION A(:), B(:,:) 

In the above example, A is declared to be a one-dimensional allocatable array and B is declared to be a 
two-dimensional allocatable array. 

The DEALLOCATE statement frees up any memory allocated for the specified array(s). It then 
disassociates the specified array(s) from the memory to which it was associated. The deallocation does not 
necessarily succeed. For example, an attempt to deallocate an array that was not previously allocated will 
cause an error. 

Example: 

DIMENSION A(:), B(:,:) 


ALLOCATE( A(N), B(0:4,5) ) 


DEALLOCATE( A ) 

More than one allocatable array may appear in an DEALLOCATE statement, separated by commas. 
Example: 

DIMENSION A(:), B(:, :) 


ALLOCATE( A(N), B(0:4,5) ) 


DEALLOCATE( A, B ) 

If the deallocation fails and the STAT= specifier was not used, an execution-time error occurs. If the 
STAT= specifier is used, the specified variable returns a zero value if the deallocation succeeded, and a 
non-zero value if the deallocation failed. 
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Example: 

DIMENSION A(:), B(:, :) 


ALLOCATE( A(N), B(0:4,5), STAT=IALLOC ) 

IF( IALLOC .NE. 0 ) PRINT *, 'Allocation failure' 


DEALLOCATE( A, B, STAT=IFREE ) 

IF( IFREE .NE. 0 ) PRINT *, 'Deallocation failure' 

An attempt to deallocate an unallocated array results in an execution-time error. The array must be 
allocated first (see the ALLOCATE statement). 

An array that was allocated using the LOCATION= specifier need not be deallocated. 

For more information on arrays, see the chapter entitled "Arrays" on page 159. 
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2.19 DIMENSION Statement 


DIMENSION a(d) [,a(d)] ... 


where: 

a is the name of the array. 

d defines the dimension of the array and the range of its subscripts. See the chapter entitled "Arrays" 
on page 159 for more information on dimensioning arrays. 

Each name a appearing in a DIMENSION statement defines a to be an array in the program unit containing 
the DIMENSION statement. A name can only be dimensioned once in a program unit. Note that a name 
can also be dimensioned in a COMMON statement and type declaration statements. 

Example: 

DIMENSION A(10), B(-5:5), C(I,J), D (4,*) 

In this example A is a 1-dimensional array containing 10 elements, each element referenced as A (1) , 
A(2), ...,A(9),A(10). Bisa 1-dimensional array containing 11 elements, each element 
referenced asB(-5),B(-4), ...,B(4),B(5). Cisa 2-dimensional array containing I rows and J 
columns. C, I, and J must be dummy arguments or belong to a common block. D is a 2-dimensional 
array containing 4 rows. The * in the last dimension indicates that D is an assumed size array. D must be a 
dummy argument. The number of columns is determined from the number of elements of the actual 
argument. For example, if the actual argument contains 8 elements then D would contain 2 columns (i.e., 8 
elements / 4 rows). 

For more information on dimensioning arrays refer to the chapter entitled "Arrays" on page 159. See also 
the description of the ALLOCATE and DEALLOCATE statements for information on dynamically 
allocatable arrays. 
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2.20 DO Statement 

Two forms of the DO statement are presented. The second form is a Open Watcom FORTRAN 77 
extension to the FORTRAN 77 language. 

2.20.1 Standard DO Statement 

DO s [,] i = el, e2 [, e3] 

where: 

s is the statement label of an executable statement, called the terminal statement, 

which follows the DO statement in the same program unit. 

i is an integer, real, or double precision variable, called the DO-variable. 

el, e2, e3 are each an integer, real, or double precision expression. 

2.20.2 Extended DO Statement 



where: 

s is an optional statement label of an executable statement, called the terminal 

statement, which follows the DO statement in the same program unit. 

i is an integer, real, or double precision variable, called the DO-variable. 

el, e2, e3 are each an integer, real, or double precision expression. 

block-label is an optional block label. 

This form of the DO statement is an extension to the FORTRAN 77 language. If no statement label is 
present then the terminal statement of the DO-loop must be an END DO statement. In all other respects, the 
rules are the same as those given for the standard DO statement. 

2.20.3 Description of DO Statement 

The range of a DO-loop consists of all of the executable statements that appear following the DO statement 
that specifies the DO-loop, up to and including the terminal statement of the DO-loop. Only certain 
statements can be the terminal statement of a DO-loop. See the section entitled "Classifying Statements" 
on page 9 at the beginning of this chapter for a list of these statements. 
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Transfer of control into the range of a DO-loop from outside the range is not permitted. 

A DO-loop may be executed 0 or more times. The following sequence occurs when a DO statement is 
encountered. 

(i) An initial value, ml, is calculated by evaluating expression el. A terminal value, m2, is 
calculated by evaluating expression e2 . An incrementation value, m3, is calculated by 
evaluating expression e3 if it is present; otherwise m3 has the value one. If e3 is specified, 
m3 must not be zero. The type of ml, m2, and m3 is determined from the DO-variable 
and any conversions of type are done as required. 

(ii) The DO-variable is defined with the initial value ml. 

(iii) The iteration count (i.e., the maximum number of times that the DO-loop will be executed) 
is calculated as follows: 

MAX ( INT((m2 - ml + m3)/m3), 0 ) 

The iteration count will be zero whenever: 

ml > m2 and m3 >0, or 
ml < m2 and m3 < 0. 

The number of times that the DO-loop is executed may be reduced if control is transferred 
outside the range of the DO-loop, or if a RETURN or STOP statement is executed. 

The steps involved in each iteration of the DO-loop are as follows: 

(i) Check the iteration count. If it is not zero then start execution of the first executable 
statement of the DO-loop. If the count is zero then iteration of the DO-loop is complete. 

(ii) Execute statements until the terminal statement is encountered. During this time, the 
DO-variable may not be redefined. 

(iii) Execute the terminal statement. Unless execution of the terminal statement causes a 
transfer of control, proceed with the next step which is "incrementation" processing. 

(iv) The DO-variable is incremented by the value m3 . The iteration count is decremented by 
one. Go back to step (i). 

Example: 

DO 10 I = -5, 5 

PRINT *, I, 1*1 
10 CONTINUE 

In this example, the initial value is -5, the terminal value is 5, and the incrementation value is 1 (the 
default). The DO-variable is I. The DO-loop is executed 

MAX ( INT((5 - (-5) + 1)/1), 0 ) 

or 11 times. The successive values of I, inside the range of the DO-loop, are -5, -4, -3, ..., 0, 1, ..., 4, 5. 
When the DO-loop is terminated, the value of I will be 6. It should be noted that when a DO-loop variable 
is of type real, the iteration count may be one less than expected. Because of rounding errors, the value of 
m2 - ml + m3 may be slightly less than the exact value and when the INT function is applied, the 
resulting iteration count is one less than expected. 


46 DO Statement 




FORTRAN Statements 


Example: 

DO 10 X = -5, 6 , 2 
PRINT *, X, X*X 
10 CONTINUE 


In this example, the terminal value has been changed to 6 and the incrementation value has been changed to 
2. The DO-variable is X, a real variable. Thus the values of el, e2 and e3 are converted to type real. 
The DO-loop is executed 

MAX( INT((6 - (-5) + 2 ) 12 ), 0 ) 

MAX( INT ( 13 / 2), 0 ) 

or 6 times. The successive values of X, inside the range of the DO-loop, are -5.0, -3.0, -1.0, 1.0, 3.0, 5.0. 
When the DO-loop is terminated, the value of X will be 7.0. 


DO-loops may be nested, that is, another DO-loop may be contained within the range of the outer DO-loop. 
More than one DO-loop may have the same terminal statement. 


Example: 

DO 10 I = -5, 5 
DO 10 J = -2, 3 
10 ARRAY( I, J ) 


0.0 


This is equivalent to the following example. 

Example: 

DO 10 I = -5, 5 

DO 20 J = -2, 3 

ARRAY( I, J ) =0.0 
20 CONTINUE 

10 CONTINUE 


If a DO statement appears within the range of a DO-loop, its range must be entirely contained within the 
range of the outer DO-loop. 


Example: 

* Illegal use of nested DO-loops. 
DO 20 I = -5, 5 

DO 10 J = -2, 3 

ARRAY( I, J ) =0.0 
20 CONTINUE 

10 CONTINUE 


The above example is illegal since the terminal statement of the first DO-loop precedes that of the second 
DO-loop. 

Similarly, the range of a DO-loop that appears within the range of an IF-block, ELSE IF-block, or 
ELSE-block must be entirely contained within that IF-block, ELSE IF-block, or ELSE-block, respectively. 
This rule applies to all Open Watcom FORTRAN 77 structured block extensions. 


DO Statement 


47 




Language Reference 


Example: 

* Illegal nesting of a DO-loop and an IF-block. 

IF( A .LT. B )THEN 
DO 10 I = 1, 5 

PRINT *, 'Iteration number', I 

END IF 

VECTOR( I ) = I 
10 CONTINUE 

The above example is illegal since the range of the IF-block must terminate after the range of the DO-loop. 
Note how statement indentation helps to illustrate the problem with this example. 

It is also illegal to attempt to transfer control into the range of a DO-loop. The following example 
illustrates this error. 


Example: 

* Illegal transfer into the range of a DO-loop. 
GO TO 20 


DO 10, I = 100, 0, -1 

PRINT *, 'Counting down from 100 to O', I 
20 PRINT *, I, SQRT( FLOAT(I) ) 

10 CONTINUE 


The following example shows a more subtle form of this error. 


Example: 

* Illegal transfer into the range of a DO-loop. 

DO 10 I = 1, 10 

* Skip row 5 of 10x10 matrix 
IF( I .EQ. 5 )GO TO 10 

DO 10 J = 1, 10 

A( I, J ) = 0.0 

10 CONTINUE 


Since the CONTINUE statement is included in the range of the inner DO-loop, an error message is issued. 


The following example illustrates the Open Watcom FORTRAN 77 structured DO statement. 

Example: 

DO I = -5, 5 

DO J = -2, 3 

ARRAY( I, J ) =0.0 
END DO 
END DO 

In keeping with more modern programming practices, this feature allows the programmer to write 
DO-loops without resorting to the use of statement labels. A well-chosen indentation style further enhances 
the readability of the program. 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.21 DOUBLE COMPLEX Statement 


The DOUBLE COMPLEX statement is a type declaration statement and can be used to declare a name to be 
of type double complex. The implicit type of the name, whether defined by the "first letter rule" (see the 
chapter entitled "Names, Data Types and Constants" on page 151) or by an IMPLICIT statement, is either 
confirmed or overridden. However, once a name has been declared to be of type double complex, it cannot 
appear in another type declaration statement. 

There are various forms of the DOUBLE COMPLEX statement. The following sections describe them. 

2.21.1 Simple DOUBLE COMPLEX Statement 


DOUBLE COMPLEX name [,name] ... 


where: 

name is a variable name, array name, array declarator, symbolic name of a constant, function name or 
dummy procedure name. 

The DOUBLE COMPLEX statement is an extension to the FORTRAN 77 language. 

Example: 

DIMENSION C (-5:5) 

DOUBLE COMPLEX A, B(10), C 

In the previous example, A is defined to be a variable of type double complex and B and C are defined to be 
arrays of type double complex. 

2.21.2 DOUBLE COMPLEX Statement: Data Initialization 


DOUBLE COMPLEX name [/cl/] [,name[/cl/]] ... 


where: 


name 

is as described in the previous section. 

cl 

is a list of the form: 


k [,k] ... 

k 

is one of the forms: 


c 

r*c (equivalent to r successive appearances of c) 


DOUBLE COMPLEX Statement 


49 










Language Reference 


c is a constant or the symbolic name of a constant 

r is an unsigned positive integer constant or the symbolic name of a constant. 

This form of the DOUBLE COMPLEX statement is also an extension to the FORTRAN 77 language. The 
rules for data initialization are the same as for the DATA statement. 

Example: 

DOUBLE COMPLEX A/ (4D4,5.1D4)/, B(1 0 )/1 0 *(5D1,3.1D1) / 

In the previous example, A is initialized with the double precision complex constant ( 4D4,5 . ID4 ) and 
each element of the array B is initialized with the double precision complex constant ( 5D 1, 3 . ID 1 ) . 
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2.22 DOUBLE PRECISION Statement 


The DOUBLE PRECISION statement is a type declaration statement and can be used to declare a name to 
be of type double precision. The implicit type of the name, whether defined by the "first letter rule" (see 
the chapter entitled "Names, Data Types and Constants" on page 151) or by an IMPLICIT statement, is 
either confirmed or overridden. However, once a name has been declared to be of type double precision, it 
cannot appear in another type declaration statement. 

There are various forms of the DOUBLE PRECISION statement. The following sections describe them. 


2.22.1 Standard DOUBLE PRECISION Statement 


DOUBLE PRECISION name [,name] ... 


where: 

name is a variable name, array name, array declarator, symbolic name of a constant, function name or 
dummy procedure name. 

This form is the standard form of the DOUBLE PRECISION statement. 

Example: 

DIMENSION C (-5:5) 

DOUBLE PRECISION A, B(10), C 

In the previous example, A is defined to be a variable of type double precision and B and C are defined to 
be arrays of type double precision. 

2.22.2 Extended DOUBLE PRECISION Statement: Data Initialization 


DOUBLE PRECISION name [/cl/] [,name[/cl/]] ... 


where: 


name 

is as described in the previous section. 

cl 

is a list of the form: 


k [,k] ... 

k 

is one of the forms: 


c 

r*c (equivalent to r successive appearances of c) 
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c is a constant or the symbolic name of a constant 

r is an unsigned positive integer constant or the symbolic name of a constant. 

This form of the DOUBLE PRECISION statement is an extension to the FORTRAN 77 language. The 
rules for data initialization are the same as for the DATA statement. 

Example: 

DOUBLE PRECISION A/4D4/, B(10)/10*5D1/ 

In the previous example, A is initialized with the double precision constant 4D4 and each element of the 
array B is initialized with the double precision constant 5D1. 
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2.23 DO WHILE Statement 


DO [s[,]] WHILE (e) [: block-label] 


where: 

s is an optional statement label of an executable statement, called the terminal 

statement, which follows the DO statement in the same program unit. 

e is a logical expression or integer arithmetic expression, in which case the result 

of the integer expression is compared for inequality to the integer value 0. 

block-label is an optional block label. 

The DO WHILE statement is an extension to the FORTRAN 77 language. 


Example: 

X = 0.0 

DO 10 WHILE ( X .LT. 100.0 ) 
PRINT *, X, SQRT( X ) 

X = X + 1.0 
10 CONTINUE 


If no statement label is present, the terminal statement of the DO-loop must be an END DO statement. 
Example: 

X = 0.0 

DO WHILE( X .LT. 100.0 ) 

PRINT *, X, SQRT( X ) 

X = X + 1.0 
ENDDO 


The following example illustrates the use of an integer arithmetic expression. 


Example: 

I = 10 

DO WHILE ( I ) 
PRINT *, I 
1 = 1-1 
ENDDO 
END 


The DO WHILE statement, is similar to the DO statement. All nesting rules that apply to the DO statement 
also apply to the DO WHILE statement. The difference is the way in which the looping is accomplished; 
the DO-loop is executed while the logical expression of the DO WHILE statement has a true value or until 
control is transferred out of the DO-loop. 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.24 ELSE Statement 


ELSE 


The ELSE statement is used in conjunction with the IF or ELSE IF statement. The range of the ELSE 
block is terminated by a matching END IF statement. 


Example: 

IF( A .LT. B )THEN 
PRINT *, 'A is 

ELSE 

PRINT *, 'A is 
END IF 


less than B' 

greater than or equal to B' 


Transfer of control into the range of an ELSE block is illegal. It is interesting to note that the ELSE 
statement may be identified by a statement label but it must not be referenced by any statement! 


Example: 

* Illegal branch to a labelled ELSE statement. 

IF( A .LT. B )THEN 

PRINT *, 'A is less than B' 

100 ELSE 

PRINT *, 'A is greater than or equal to B' 
GO TO 100 
END IF 


The above is an example of an illegal way to construct an infinitely repeating loop. The following is the 
correct way to do this. 


Example: 

IF( A .LT. B )THEN 

PRINT *, 'A is less than B' 

ELSE 

100 PRINT *, 'A is greater than or equal to B' 

GO TO 100 
END IF 


For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.25 ELSE IF Statement 


ELSE IF (e) THEN 


where: 

e is a logical expression or integer arithmetic expression, in which case the result of the integer 
expression is compared for inequality to the integer value 0. 

The ELSE IF statement is used in conjunction with the IF statement. The range of the ELSE IF block 
is terminated by another ELSE IF statement, an ELSE statement, or an END IF statement. 


Example: 

IF( A .LT. B )THEN 

PRINT *, 'A is less than B' 
ELSE IF( A .EQ. B )THEN 

PRINT *, 'A is equal to B' 

ELSE 

PRINT *, 'A is greater than B' 
END IF 


Transfer of control into the range of an ELSE IF block is illegal. It is interesting to note that the ELSE 
IF statement may be identified by a statement label but it must not be referenced by any statement! 


Example: 

* Illegal transfer into the range of 

* an ELSE IF statement. 

IF( A .EQ. 0.0 )GO TO 110 
IF( A .LT. B )THEN 

PRINT *, 'A is less than B' 
ELSE IF( A .EQ. B )THEN 

PRINT *, 'A is equal to B or' 
110 PRINT *, 'A is equal to O' 

ELSE 

PRINT *, 'A is greater than B' 
END IF 


The above is an example of an illegal attempt to branch into the range of an ELSE IF block. 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.26 END Statement 


END 


The END statement indicates the end of a sequence of statements and comment lines of a program unit. 
Execution of an END statement in a function or subroutine subprogram has the same effect as a RETURN 
statement. Control is returned to the invoking program unit. Execution of an END statement in a main 
program causes termination of execution of the program. 

Example: 

SUBROUTINE EULER( X, Y, Z ) 


END 

Upon executing the END statement, execution control is returned to the calling program unit. 
Example: 

PROGRAM PAYROL 


END 

Upon executing the END statement, execution of the program is terminated. 

Some rather special rules apply to the END statement. The statement is written in columns 7 to 72 of an 
initial line. In other words, it must not be continued. Also, no other statement in the program unit may 
have an initial line that appears to be an END statement. 

Example: 

* An illegal ENDIF statement. 

IF( A .LT. B )THEN 


END 
& IF 

The above END IF statement is illegal since the initial line appears to be an END statement. 
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2.27 END AT END Statement 


END AT END 


The END AT END statement is used in conjunction with the structured AT END statement. The END AT 
END statement marks the end of a sequence of statements which are part of an AT END-block. The AT 
END statement marks the beginning of the AT END-block. The AT END-block is executed when the 
preceding READ statement terminates because of an end-of-file condition. 


Example: 

READ( UNIT=1, FMT='(315)' ) I, J, K 
AT END DO 

PRINT *, 'END-OF-FILE ENCOUNTERED ON UNIT 1' 

EOFSW = .TRUE. 

END AT END 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.28 END BLOCK Statement 


END BLOCK 


The END BLOCK statement is used to terminate a REMOTE-block. The END BLOCK statement is 
implicitly a transfer statement, since it returns program control from a REMOTE-block. 

Example: 

REMOTE BLOCK A 
1 = 1 + 1 

PRINT *, 'I = ',I 

END BLOCK 

For more information, see the description of the EXECUTE and REMOTE BLOCK statements or the chapter 
entitled "Program Structure Control Statements" on page 193. 
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2.29 END DO Statement 



The END DO statement is used to terminate the range of a "structured" DO statement. A structured DO 
statement is one in which a statement label is not present. For more information, see the description of the 
structured DO statement or the chapter entitled "Program Structure Control Statements" on page 193. 

Example: 

DO X = -5.1, 12.8, 0.125 


END DO 

Example: 

X = -5.1 

DO WHILE( X .LE. 12.8 ) 


X = X + 0.125 
END DO 
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2.30 ENDFILE Statement 


ENDFILE 

u 

ENDFILE 

(alist) 


where: 

u is an external unit identifier. 

alist is a list of endfile specifiers separated by commas: 

[UNIT =] u 
IOSTAT = ios 
ERR = s 

Execution of an ENDFILE statement causes an endfile record to be written to the file connected to the 
specified unit. The file is then positioned after the endfile record. If the file may be connected for direct 
access, only those records before the endfile record are considered to have been written. Thus, only those 
records before the endfile record may be read during subsequent direct access connections to the file. 

Endfile Specifiers 


[UNIT =] u 

u is an external unit identifier. An external unit identifier is a non-negative integer 
expression. If the optional UNIT= specifier is omitted then the specifier must be the first 
item in the list of specifiers. 

IOSTAT = ios 

is an input/output status specifier. The integer variable or integer array element ios is 
defined with zero if no error condition exists or a positive integer value if an error condition 
exists. 

ERR = s 

is an error specifier and s is a statement label. When an error occurs, execution is 
transferred to the statement labelled by s . 

Example: 

LOOP 

READ( UNIT=7, END=100, FMT=200 )RECORD 
WRITE( UNIT=8, FMT=200 )RECORD 
ENDLOOP 

100 ENDFILE( UNIT=8 ) 

In the previous example, we illustrate how one might read all the records from one file (unit 7), write them 
to another file (unit 8) and then write an endfile record to the end of the file on unit 8. 
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Notes: 

1. The unit must be connected for sequential access. 

2. After execution of an ENDFILE statement, a BACKSPACE or REWIND statement must be used 
to reposition the file before any other input/output statement which refers to this file can be 
executed. 

3. If the file did not exist before execution of the ENDFILE statement then it will be created after 
execution of this statement. 

For more information on input/output, see the chapter entitled "Input/Output" on page 215. 
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2.31 END GUESS Statement 


END GUESS 


The END GUESS statement is used in conjunction with the structured GUESS statement. The END 
GUESS statement marks the end of a series of GUESS-ADMIT blocks. 

Example: 

CHARACTER CH 
READ *, CH 
GUESS 

IF ( CH .LT. 'a' )QUIT 

IF ( CH .GT. 'z' )QUIT 

PRINT *, 'Lower case letter' 

ADMIT 

IF ( CH .LT. 'A' )QUIT 

IF ( CH .GT. 'Z' )QUIT 

PRINT *, 'Upper case letter' 

ADMIT 

IF ( CH .LT. '0' )QUIT 

IF ( CH .GT. '9' )QUIT 

PRINT *, 'Digit' 

ADMIT 

PRINT *, 'Special character' 

END GUESS 
END 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.32 END IF Statement 


END IF 


The END IF statement is used in conjunction with the block IF statement. The END IF statement marks 
the end of a sequence of statements which are to be conditionally executed. 


Example: 

IF( X .LT. 100.0 )THEN 

PRINT *, 'X IS LESS THAN 100' 
END IF 


The END IF statement can also be used in conjunction with the ELSE and ELSE IF statements. For 
more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.33 END LOOP Statement 


END LOOP 


The END LOOP statement is used in conjunction with the structured LOOP statement. The END LOOP 
statement marks the end of a sequence of statements which are to be repeated. The LOOP statement marks 
the beginning of the loop. The LOOP-block is executed until control is transferred out of the LOOP-block. 

The QUIT statement may be used to transfer control out of a LOOP-block. 

Example: 

LOOP 

READ *, X 

IF ( X .GT. 99.0 ) QUIT 
PRINT *, X 
END LOOP 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 


64 END LOOP Statement 







FORTRAN Statements 


2.34 END MAP Statement 


END MAP 


The END MAP statement is used in conjunction with the MAP declarative statement. The END MAP 
statement marks the end of a MAP structure. The following example maps out a 4-byte integer on an Intel 
80x86-based processor. 


Example: 

STRUCTURE /MAPINT/ 
UNION 


MAP 


INTEGER* 4 

LONG 

END 

MAP 


MAP 


INTEGER*2 

LO_ WORD 


INTEGER*2 

HI_ WORD 

END 

MAP 


MAP 


INTEGER*1 

BYTE_ 0 


INTEGER*1 

BYTE_ 1 


INTEGER*1 

BYTE_2 


INTEGER*1 

BYTE_ 3 

END 

MAP 



END UNION 
END STRUCTURE 

RECORD /MAPINT/ I 

I%LONG = '01020304 'x 

PRINT ’ (2Z4 ) ' , I%LO_ WORD, I%HI_ WORD 
END 

For more information, see the chapter entitled "Structures, Unions and Records" on page 167. 
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2.35 END SELECT Statement 


END SELECT 


The END SELECT statement is used in conjunction with the SELECT statement. The END SELECT 
statement marks the end of a series of CASE blocks. 

Example: 

SELECT CASE ( CH ) 

CASE ( 'a' : ' z' ) 

PRINT *, 'Lower case letter' 

CASE ( 'A' : 'Z' ) 

PRINT *, 'Upper case letter' 

CASE ( '0' : '9' ) 

PRINT *, 'Digit' 

CASE DEFAULT 

PRINT *, 'Special character' 

END SELECT 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.36 END STRUCTURE Statement 


END STRUCTURE 


The END STRUCTURE statement is used in conjunction with the STRUCTURE declarative statement. The 
END STRUCTURE statement marks the end of a structure definition. 


Example: 

STRUCTURE /ADDRESS/ 

CHARACTER*20 STREET 
CHARACTER*20 CITY 
CHARACTER*20 STATE 
CHARACTER*20 COUNTRY 
CHARACTER*10 ZIP_ CODE 
END STRUCTURE 

STRUCTURE /PEOPLE/ 

CHARACTER*20 NAME 
RECORD /ADDRESS/ ADDR 
INTEGER*2 AGE 
END STRUCTURE 


For more information, see the chapter entitled "Structures, Unions and Records" on page 167. 
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2.37 END UNION Statement 


END UNION 


The END UNION statement is used in conjunction with the UNION declarative statement. The END 
UNION statement marks the end of a series of MAP structures. The following example maps out a 4-byte 
integer on an Intel 80x86-based processor. 


Example: 

STRUCTURE /MAPINT/ 
UNION 


MAP 


INTEGER* 4 

LONG 

END 

MAP 


MAP 


INTEGER*2 

LO_ WORD 


INTEGER*2 

HI_ WORD 

END 

MAP 


MAP 


INTEGER*1 

BYTE_ 0 


INTEGER*1 

BYTE_ 1 


INTEGER*1 

BYTE_2 


INTEGER*1 

BYTE_ 3 

END 

MAP 



END UNION 
END STRUCTURE 

RECORD /MAPINT/ I 

I%LONG = '01020304 'x 

PRINT ’ (2Z4 ) ' , I%LO_ WORD, I%HI_ WORD 
END 

For more information, see the chapter entitled "Structures, Unions and Records" on page 167. 
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2.38 END WHILE Statement 


END WHILE 


The END WHILE statement is used in conjunction with the structured WHILE statement. The END 
WHILE statement marks the end of a sequence of statements which are to be repeated. The WHILE 
statement marks the beginning of the WHILE-block. The WHILE-block is executed while the logical 
expression (or integer arithmetic expression) of the WHILE statement has a true (or non-zero) value or until 
control is transferred out of the WHILE-block. 

Example: 

X = 1.0 

WHILE( X .LT. 100 )DO 

PRINT *, X, SQRT( X ) 

X = X + 1.0 
END WHILE 

Example: 

I = 10 

WHILE ( I )DO 

PRINT *, I 
1 = 1-1 
ENDWHILE 
END 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.39 ENTRY Statement 


ENTRY name [( [d [, d] ...] )] 


where: 

name is a symbolic name of an entry in a function or subroutine subprogram. If the ENTRY statement 
appears in a subroutine subprogram then name is a subroutine name. If the ENTRY statement 
appears in a function subprogram then name is an external function name. 

d is a variable name, array name, dummy procedure name, or an asterisk, d is called a dummy 

argument. An asterisk is allowed only in a subroutine subprogram. 

The ENTRY statement is used to define an alternate entry into a subprogram. 


Example: 


PRINT *, 

TMAX2( 

121.0, 

-290 

.0 ) 

PRINT *, 
END 

TMAX3( 

1 

I — 1 

o 

12.0, 

o 

LD 

FUNCTION 

T3 = 

TMAX3( 
ARGC 

ARGA, 

ARGB, 

ARGC 


GO TO 10 

ENTRY TMAX2( ARGA, ARGB ) 

T3 = ARGA 

10 TMAX2 = ARGA 

IF( ARGB .GT. TMAX2 ) TMAX2 = ARGB 
IF( T3 .GT. TMAX2 ) TMAX2 = T3 

END 


In the above example, an entry was defined to permit us to find the maximum of two real variables. Either 
the entry name TMAX2 or the function name TMAX3 could have been used as the variable for returning the 
maximum value since they agree in type. It is not necessary to precede an ENTRY statement with a transfer 
statement as the ENTRY statement is not an executable statement; the next statement executed will be the 
first executable statement following the ENTRY statement. 

Notes: 

1. No dummy arguments need be specified in the ENTRY statement. If this is the case, the 
parentheses () are optional. 

For more information, see the chapter entitled "Functions and Subroutines" on page 243. 
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2.40 EQUIVALENCE Statement 

EQUIVALENCE (nlist) [,(nlist)] ... 


where: 

nlist is a list of at least two names, each name separated by a comma. 

The names appearing in nlist can be variable names, array names, array element names, character 
names, character substring names, and character array element substring names. Dummy arguments are not 
allowed in nlist. 

The EQUIVALENCE statement specifies that the storage occupied by the entities appearing in nlist all 
start at the same place. It in no way changes the characteristics of an object. For example, if a variable is 
equivalenced to an array, the variable does not inherit the properties of the array. Similarly, if a variable of 
type integer is equivalenced to a variable of type real, there is no implied type conversion. 

If an array element name appears in an EQUIVALENCE statement, the number of subscript expressions 
must be the same as the number of dimensions specified when the array was declared and each subscript 
expression must be in the range specified. As an extension to FORTRAN 77, Open Watcom FORTRAN 
77 allows a single subscript expression for a multi-dimensional array. An array name used by itself is 
equivalent to specifying the first element of the array. 

If a character substring appears in an EQUIVALENCE statement, the substring defined by the substring 
expression must be properly contained in the character entity being substrung. A character name used by 
itself is equivalent to specifying the first character of the character variable. 

Example: 

REAL A,B 

DIMENSION A(10),B(20) 

EQUIVALENCE (A,B(16)) 

In the above example, the first 5 elements of A occupy the same storage as the last 5 elements of B . 
Example: 

DIMENSION A(10) 

EQUIVALENCE (C,A(2)),(D,A(4)) 

In the above example, C is assigned the same storage unit as A (2 ) and D is assigned the same storage unit 
as A (4) . 
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The following example illustrates a Open Watcom FORTRAN 77 extension. 

Example: 

REAL A(2,10),B(20) , C(2, 2, 5) 

EQUIVALENCE (A(5),B(l) ) , (B(l),C(l) ) 

In the above example, a single subscript is specified for arrays A and C . The following table shows the 
mapping of a 2-dimensional array onto a 1-dimensional array. 


A ( 1 , 1 ) 

== A( 1 ) 

A (2, 1) 

== A(2) 

A(1,2) 

== A(3) 

A(2,2) 

== A(4) 

A (1, 3) 

== A(5) 

A (2, 3) 

== A(6) 


In the above table, "==" is read as "is equivalent to". In FORTRAN, arrays are stored in "column major" 
format (i.e., arrays are stored column by column rather than row by row). 

Example: 

CHARACTER*5 A, D 
EQUIVALENCE (A(3:5), D(l:3)) 

In this example, the last 3 characters of A occupy the same character storage units as the first 3 characters of 

D. 

There are certain restrictions on EQUIVALENCE statements. It is not possible to equivalence a storage unit 
to 2 different storage units. This is illustrated by the following example. 

Example: 

* Illegally equivalencing a storage unit to 

* 2 different storage units. 

DIMENSION A(2) 

EQUIVALENCE (A(1),B),(A(2),B) 

B has been given 2 different storage units. 

It is also not possible to specify that consecutive storage units be non-consecutive. For example. 

Example: 

* Illegally equivalencing consecutive storage units to 

* non-consecutive storage units. 

DIMENSION A(2),B(2) 

EQUIVALENCE (A(1),B(2) ), (A(2) , B(1) ) 

A (1) and A (2) are consecutive but B (1) and B (2) are not. 

The FORTRAN 77 standard specifies that character and numeric data cannot be equivalenced; Open 
Watcom FORTRAN 77 allows character and numeric data to be equivalenced. 
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2.41 EXECUTE Statement 


EXECUTE name 


where: 


name is the name of a REMOTE BLOCK located in the same program unit. 

The EXECUTE statement allows a named block of code to be executed. The named block of code may be 
defined anywhere in the same program unit and is delimited by the REMOTE BLOCK and END BLOCK 
statements. Executing a REMOTE-block is similar in concept to calling a subroutine, with the advantage 
that shared variables do not need to be placed in a COMMON block or passed in an argument list. When 
execution of the REMOTE-block is complete (i.e., when the END BLOCK statement is executed), control 
returns to the statement following the EXECUTE statement which invoked it. 


Example: 

EXECUTE INCR 
PRINT *, 'FIRST' 
EXECUTE INCR 
PRINT *, 'SECOND' 


REMOTE BLOCK INCR 
1 = 1 + 1 

PRINT *, 'I=',I 

END BLOCK 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.42 EXIT Statement 


EXIT [: block-label] 


The EXIT statement is used to transfer control: 

1. from within a loop (DO, DO WHILE, WHILE or LOOP) to the statement following the loop, 

2. from within a GUESS or ADMIT block to the statement following the ENDGUESS statement, or 

3. from within a remote block to the statement following the EXECUTE statement that invoked the 
remote block. 

The EXIT statement may be used to cause a transfer of control to the first executable statement that follows 
the terminal statement of the block which contains it. Examples of such terminal statements are END DO, 
END LOOP, END WHILE, UNTIL, etc. If block-label is present then control is transferred out of the 
block identified by that block label. The EXIT statement is an extension to the FORTRAN 77 language. 


Example: 

LOOP 

WRITE( UNIT=*, FMT='(A)' ) 'Enter a number' 

READ( UNIT=*, FMT=' (F10.4)', IOSTAT=IOS ) X 
IF( IOS .NE. 0 ) EXIT 
IF( X .LT. 0 ) EXIT 
PRINT *, X, SQRT( X ) 

END LOOP 
END 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 


74 EXIT Statement 







FORTRAN Statements 


2.43 EXTERNAL Statement 


EXTERNAL p [,p] 


where: 

p is the name of an external procedure, dummy procedure or block data subprogram. 

The EXTERNAL statement identifies a symbolic name to be a dummy procedure or an external procedure 
and allows these names to be passed as an actual argument. In the following example, SAM, ERRRTN and 
POLY are declared to be external procedures. 

Example: 

EXTERNAL SAM, ERRRTN, POLY 

In the following example, F is declared to be an external procedure and is passed as such to subroutine 
SAM . If the EXTERNAL statement were eliminated then the variable F would be passed on to subroutine 
SAM since there is no way of knowing that F is an external function. 

Example: 

EXTERNAL F 


CALL SAM( F ) 

The appearance of an intrinsic function in an EXTERNAL statement declares that name to be an external 
procedure and the intrinsic function by that name is no longer available in that program unit. This allows 
the programmer to define a function by the same name as an intrinsic function. In the following example, 
the programmer’s SIN function will be called instead of the intrinsic SIN function. 

Example: 

EXTERNAL SIN 


CALL SIN( .1 ) 

A statement function name must not appear in an EXTERNAL statement. A name must only appear in an 
EXTERNAL statement once. 
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2.44 FORMAT Statement 


label FORMAT fs 


where: 

fs is a format specification and is described in the chapter entitled "Format" on page 225. 

label is the statement label used by an I/O statement to identify the FORMAT statement to be used. 

The FORMAT statement must be labelled. 

Example: 

REAL X 
X = 234.43 
PRINT 100, X 
100 FORMAT(F10.2) 

END 


In the previous example, the PRINT statement uses the format specification in the FORMAT statement 
whose statement label is 100 to display the value of X. 

For more information on the FORMAT statement, see the chapter entitled "Format" on page 225. 
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2.45 FUNCTION Statement 


A FUNCTION statement is used to define the start of a function subprogram. There are two forms of the 
FUNCTION function statement. The second form is a Open Watcom FORTRAN 77 extension. 


2.45.1 Standard FUNCTION Statement 


[type] FUNCTION fun ( [d [, d] ...] ) 


where: 

type is one of LOGICAL, INTEGER, REAL, DOUBLE PRECISION, COMPLEX or CHARACTER 
[*len] . 

fun is a symbolic name of a function subprogram. 

d is a variable name, array name, or a dummy procedure name, d is called a dummy argument. 

ten is called the length specification and is the length (number of characters) of the result of the 

character function. It has one of the following forms: 

(1) An unsigned positive integer constant. 

(2) A positive integer constant expression enclosed in parentheses. 

(3) An asterisk in parentheses, (*). 

Example: 

PRINT *, TMAX3( -1.0, 12.0, 5.0 ) 

END 

FUNCTION TMAX3( ARGA, ARGB, ARGC ) 

TMAX3 = ARGA 

IF( ARGB .GT. TMAX3 ) TMAX3 = ARGB 
IF( ARGC .GT. TMAX3 ) TMAX3 = ARGC 

END 

In the above example, the function TMAX3 is defined to find the maximum of three real variables. 

Notes: 

1. No dummy arguments need be specified in the FUNCTION statement. However, the parentheses 
() are mandatory. 

For more information, see the chapter entitled "Functions and Subroutines" on page 243. 
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2.45.2 Extended FUNCTION Statement 


[type[*len]] FUNCTION fun[*len] ( [d [, d] ...] ) 


is one of LOGICAL, INTEGER, REAL, DOUBLE PRECISION, COMPLEX, CHARACTER 
or RECORD /typename/ 

is a symbolic name of a function subprogram. 

is a variable name, array name, or a dummy procedure name, d is called a dummy argument. 
is called the length specification and has one of the following forms: 

(1) An unsigned positive integer constant. 

(2) A positive integer constant expression enclosed in parentheses. 

(3) An asterisk in parentheses, (*). 

For valid values of len, refer to the appropriate type declaration statement. 

This form of the FUNCTION statement is an extension to the FORTRAN 77 language. 

Example: 

INTEGER*2 M0D2, I, J 

I = 12 
J = 5 

PRINT *, MOD2( I, J ) 

END 

INTEGER*2 FUNCTION M0D2( I, J ) 

INTEGER*2 I, J 
INTEGER II, JJ 

II = I 
JJ = J 

MOD2 = MOD (II, JJ) 

END 

Notes: 

1. No dummy arguments need be specified in the FUNCTION statement. However, the parentheses 
() are mandatory. 

2. The length specification can appear only once in the FUNCTION statement. 

For more information, see the chapter entitled "Functions and Subroutines" on page 243. 
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2.46 Unconditional GO TO Statement 


GO TO s 


where: 

s is the statement label of an executable statement that appears in the same program unit as the GO TO 
statement. 

Example: 

GO TO 10 


10 S = S + 1 

When the GO TO statement is executed, control is transferred to the statement identified by that label. In 
the above example, the GO TO statement causes execution to proceed to the statement labelled 10. 

Example: 

* An illegal GO TO statement 
GO TO 100 


100 FORMAT( IX, 3F10.2 ) 

The above example contains an illegal GO TO statement since the statement identified by the label 100 is 
not executable. 
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2.47 Computed GO TO Statement 


GO TO (s [,s] . ..) [,] i 


where: 

i is an integer expression. 

s is the statement label of an executable statement that appears in the same program unit as the 
computed GO TO statement. 

The integer expression i is evaluated and the ith label is selected for transfer of control. If i is less than 1 
or greater than the number of statement labels in the list then execution control continues with the next 
executable statement that follows the computed GO TO statement. 

Example: 

GO TO (110, 120, 130, 140) INDEX 

100 CALL AUDIT 

In the above example, control is transferred to the statement identified by the label 110 if INDEX has the 
value 1, the label 120 if INDEX has the value 2, etc. If INDEX has a value that is negative, zero or larger 
than 4, control continues with the statement labelled 100. In this example, the integer expression consists 
simply of an integer variable. 

Example: 

GO TO (100, 200, 100, 200, 100, 200), 1/10 

The above example illustrates that statement labels may be repeated in the list and that a may follow the 
closing right parenthesis. 
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2.48 Assigned GO TO Statement 

GO TO i [[,] (s [,s]...)] 


where: 

i is an integer variable name. 

s is the statement label of an executable statement that appears in the same program unit as the 
assigned GO TO statement. 

The variable i must be defined with the value of a statement label of an executable statement that appears 
in the same program unit (see the ASSIGN statement). The execution of the assigned GO TO statement 
causes a transfer of control to the statement that is identified by that label. 


Example: 

INTEGER RET 
X = 0.0 

ASSIGN 100 TO RET 
GO TO 3000 
100 X = X + 1 

ASSIGN 110 TO RET 
GO TO 3000 
110 X = X + 1 


* Print both X and its square root 

3000 Y = SQRT( X ) 

PRINT *, X, Y 
GO TO RET 


In the above example, we illustrate the use of the ASSIGN statement and the assigned GO TO statement to 
implement a "local subroutine" in a program unit. A sequence of often-used code can be "called" using the 
unconditional GO TO statement and "return" is accomplished using the assigned GO TO statement. Care 
must be exercised to properly assign the return label value. 

If a list of statement labels is present then the statement label assigned to i must be in the list. If it is not in 
the list, an error will occur when the assigned GO TO statement is executed. Unlike the computed GO TO 
statement, execution does not continue with the next statement. This is demonstrated by the following 
example. Note that the "," preceding the statement label list is optional. 

Example: 
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* Illegal use of the assigned GO TO: 

* Statement label 100 does not appear in the statement 

* label list of the assigned GO TO statement. 

ASSIGN 100 TO ICASE 

GO TO ICASE, (110, 120, 130) 

* beginning of selections 

100 PRINT *, 100 

GO TO 200 

110 PRINT *, 110 

GO TO 200 

120 PRINT *, 120 

GO TO 200 

130 PRINT *, 130 

* end of selections 

200 END 
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2.49 GUESS Statement 


GUESS [: block-label] 


The GUESS statement is an extension to the FORTRAN 77 language. The GUESS statement marks the 
beginning of a block of statements for which a certain assumption or hypothesis has been made. This 
hypothesis may be tested using logical IF statements in conjunction with QUIT statements. The ADMIT 
statement may be used to mark the beginning of an alternate hypothesis. The END GUESS statement is 
used to mark the end of a series of GUESS-AD MIT blocks. 

Example: 

CHARACTER CH 
READ *, CH 
GUESS 

IF ( CH .LT. 'a' )QUIT 

IF ( CH .GT. 'z' )QUIT 

PRINT *, 'Lower case letter' 

ADMIT 

IF ( CH .LT. 'A' )QUIT 

IF ( CH .GT. 'Z' )QUIT 

PRINT *, 'Upper case letter' 

ADMIT 

IF ( CH .LT. '0' )QUIT 

IF ( CH .GT. '9' )QUIT 

PRINT *, 'Digit' 

ADMIT 

PRINT *, 'Special character' 

END GUESS 
END 

An optional block label may be specified with the GUESS statement. 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.50 Arithmetic IF Statement 


IF (e) si, s2, s3 


where: 

e is an integer, real, or double precision expression. 

si, s2, s3 are statement labels of executable statements that appear in the same program unit 

as the arithmetic IF statement. 

The expression e is evaluated and if the value is less than zero then transfer is made to the statement 
identified by label si. If the value is equal to zero then transfer is made to the statement identified by 
label s2 . If the value is greater than zero then transfer is made to the statement identified by label s3 . 

Example: 

IF( SIN( X ) ) 10, 20, 30 
10 PRINT *, 'SIN(X) IS < 0' 

GO TO 40 

20 PRINT *, 'SIN(X) = O' 

GO TO 40 

30 PRINT *, 'SIN(X) > O' 

40 CONTINUE 

The above example evaluates the sine of the real variable X and prints whether the result is less than 0, 
equal to 0, or greater than 0. 

The same label may appear more than once in the arithmetic IF statement. 

Example: 



IF( SIN( 

x ) ) 10, 

10 

PRINT *, 

'SIN(X) IS 


GO TO 40 


30 

PRINT *, 

'SIN(X) > 

40 

CONTINUE 



The above example evaluates the sine of the real variable X and prints whether the result is less than or 
equal to zero, or that it is greater than 0. 
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2.51 Logical IF Statement 


IF (e) st 


where: 

e is a logical expression or integer arithmetic expression, in which case the result of the integer 
expression is compared for inequality to the integer value 0. 

st is an executable statement. Only certain executable statements are allowed. See the section entitled 
"Classifying Statements" on page 9 at the beginning of this chapter for a list of allowable statements. 

The expression e is evaluated and must result in a true or a false value. If the result is true then the 
statement st is executed, otherwise it is not executed. 


Example: 

IF ( A . LT . B ) PRINT *, 'A < B' 

In the above example, the logical expression A . LT. B is evaluated and, if it is true, the message A < 

B is printed. A logical expression is one in which the result is either true or false. An expression such as 1 
+ 2 is clearly not an example of a logical expression. 

Logical variables have logical values of true or false and may also be used in the logical expression. 
Consider the following two examples. 


Example: 

LOGICAL RESULT 

RESULT = A .LT. B 

IF( RESULT )PRINT *, 'A < B' 

The above example is equivalent to the preceding one but introduces the use of a logical variable. 

Example: 

LOGICAL RESULT 
RESULT = A .LT. B 

IF( .NOT. RESULT )PRINT *, 'A >= B' 

In the above example, the logical expression is negated through the use of the . NOT . operator in order to 
test for the inverse condition, namely . GE . . 

Much more complex logical expressions can be constructed and then tested for their truth value. 


Example: 


IF( 


A.LT.B .OR. C.GE.D 


)PRINT *, 


' A<B or C>=D' 
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An example of an integer expression in an IF statement follows: 
Example: 

1 = 1 

* Integer arithmetic expression 

IF( I )THEN 

PRINT *, 'Yes' 

END IF 

* Equivalent logical expression 

IF( I .NE. 0 )THEN 

PRINT *, 'Yes' 

END IF 
END 
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2.52 Block IF Statement 


There are two forms of the block IF statement. The second is a Open Watcom FORTRAN 77 extension. 

2.52.1 Standard Block IF Statement 


IF (e) THEN 


where: 

e is a logical expression. 

The block IF statement is used in conjunction with the ELSE IF, ELSE, and END IF statements. 
Example: 

IF( A .LT. B )THEN 
PRINT *, 'A < B' 

END IF 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 

2.52.2 Extended Block IF Statement 

IF (e) THEN [: block-label] 


where: 

e is a logical expression or integer arithmetic expression, in which case the result 

of the integer expression is compared for inequality to the integer value 0. 

block-label is an optional block label. 

This form of the block IF statement is an extension to the FORTRAN 77 language. It is identical to the 
standard form of the block IF statement with the exception that an integer arithmetic expression and an 
optional block label are permitted. 

Example: 
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IF( I .EQ. 10 )THEN : IFBLK 
IF( J .EQ. 20 )THEN 


IF( K. EQ. 0 )QUIT : IFBLK 


END IF 


END IF 


In the previous example, the QUIT statement will transfer control to the statement following the second 
END IF statement. 
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2.53 IMPLICIT Statement 

Open Watcom FORTRAN 77 supports three forms of the IMPLICIT statement. The second and third 
forms are extensions to the FORTRAN 77 language. 

2.53.1 Standard IMPLICIT Statement 

IMPLICIT type (a [,a] ...) [,type (a [,a] 


where: 

type is one of LOGICAL, INTEGER, REAL, DOUBLE PRECISION, COMPLEX or 
CHARACTER[*len]. 

a is either a single letter or a range of letters denoted by separating the first letter in the range from 

the last letter in the range by a minus sign. 

lett is the length of the character entities and is a positive unsigned integer constant or a positive 

integer constant expression enclosed in parentheses. If len is not specified, the length is 1. 

2.53.2 Extended IMPLICIT Statement 


IMPLICIT type[*len] 

(a 

I,a] . 

- ■) 

[,type[*len] 

(a 

I,a] . 

• •) ] ... 


where: 

type is one of LOGICAL, INTEGER, REAL, DOUBLE PRECISION, COMPLEX or 
CHARACTER. 

len is a positive unsigned integer constant or a positive integer constant expression enclosed in 

parentheses. If type is CHARACTER then (*) is also allowed. The possible values of len are 
as follows: 

1. If type is LOGICAL then len can be 1 or 4. The default is 4. 

2. If type is INTEGER then len can be 1, 2 or 4. The default is 4. 

3. If type is REAL then len can be 4 or 8. The default is 4. 

4. If type is DOUBLE PRECISION then len cannot be specified. 

5. If type is COMPLEX then len can be 8 or 16. The default is 8. 

6. If type is CHARACTER then len can be (*) or any positive integer. 
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2.53.3 IMPLICIT NONE Statement 


IMPLICIT NONE 


2.53.4 Description of IMPLICIT Statement 

The IMPLICIT statement defines the default type and length for all variables, arrays, symbolic constants, 
external functions and statement functions that begin with any letter that has appeared in an IMPLICIT 
statement as a single letter or as a member of a range of letters. 

The following example specifies that any name beginning with the letters A, D, E, F or G will have 
default a default type of integer and any name beginning with the letters X, Y or Z will have a default type 
of character and length 3. 

Example: 

IMPLICIT INTEGER (A,D-G), CHARACTER*3 (X-Z) 


The next example illustrates the extended form of the IMPLICIT statement. 
Example: 

IMPLICIT INTEGER*2 (A,B), L0GICAL*1 (C-F) 
IMPLICIT COMPLEX*16 (X,Y,Z), REAL * 8 (P) 


Specifying NONE in the IMPLICIT statement will cause Open Watcom FORTRAN 77 to issue an error 
when a symbol is used and has not appeared in a type specification statement. 

Example: 

* Referencing X will cause an error 
IMPLICIT NONE 
X = 13143.383 

In the above example, the IMPLICIT statement specifies that the type of all symbols must be explicitly 
declared in a type specification statement. The assignment statement will cause an error since the type of X 
has not been explicitly declared. 

Notes: 

1. The implicit type set by an IMPLICIT statement may be overridden or confirmed for any 
variable, array, symbolic constant, external function or statement function name by its 
appearance in a type statement. The default length specification may also be overridden or 
confirmed in a type statement. 
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Example: 

IMPLICIT CHARACTER*10 (S-U) 

IMPLICIT INTEGER*2 (P) 

CHARACTER STRING 
INTEGER POINTS 

In the above example, the variable STRING is of type character but its length is 1 since it has 
appeared in a CHARACTER statement which has a default length of 1. Also, the variable 
POINTS is of type integer but its length is 4 since it has appeared in an INTEGER statement 
which has a default length of 4. 

2. A letter cannot appear more than once as a single letter or be included in a range of letters in all 
IMPLICIT statements in a program unit. 

3. An IMPLICIT statement applies only to the program unit that contains it. 

4. The IMPLICIT statement does not change the type of intrinsic functions. 

5. A program unit can contain more than one IMPLICIT statement. 

6. Within the specification statements of a program unit, IMPLICIT statements must precede all 
other specification statements except PARAMETER statements. 

7. The IMPLICIT NONE statement is allowed only once in a program unit. Furthermore, no 
other IMPLICIT statement can be specified in the program unit containing an IMPLICIT 
NONE statement. 
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2.54 INCLUDE Statement 

INCLUDE 'inc_spec' 


where: 

inc_spec is an include specification. You should refer to the compiler’s User’s Guide for a detailed 

description of an include specification and include file processing. 

Example: 

INCLUDE 'GBLDEFS' 


END 
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2.55 INQUIRE Statement 


The INQUIRE statement is used to ask about certain properties of a named file or its connection to a 
particular unit. There are two forms of the INQUIRE statement; inquire by file name and inquire by unit. 

2.55.1 INQUIRE by FILE 


INQUIRE (iflist) 


where: 

iflist includes the FILE= specifier and may include at most one of each of the inquiry specifiers 

listed below. Specifiers are separated by commas. The FILE= specifier has the form 

FILE = fin 

where fin is a character expression whose value when trailing blanks are removed is the 
name of a file being inquired about. The file need not exist or be connected to a unit. 

Example: 

LOGICAL EX, OD 
INTEGER NUM 

INQUIRE( FILE='ROLL',EXIST=EX,OPENED=OD,NUMBER=NUM ) 

In the above example, information is requested on the file PAYROLL. In particular, we want to know if it 
exists, whether it is connected to a unit, and what the unit number is (if it is indeed connected). 

2.55.2 INQUIRE by UNIT 


INQUIRE (iulist) 


where: 

iulist includes the UNIT= specifier and may include at most one of each of the inquiry specifiers 

listed below. Specifiers are separated by commas. The UNIT= specified has the form 

[UNIT =] u 

where u is an external unit identifier. An external unit identifier is a non-negative integer 
expression. If the optional UNIT= specifier is omitted then the specifier must be the first 
item in the list of specifiers. 
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Example: 

LOGICAL EX, OD 
CHARACTER*30 FN 

INQUIRE( UNIT=7, EXIST=EX, OPENED=OD, NAME=FN ) 

In the above example, information is requested on unit 7. In particular, we want to know if the unit exists, 
whether it is connected to a file, and, if so, what the file name is. 


2.55.3 Inquiry Specifiers 

The following inquiry specifiers are supported. 

IOSTAT = ios 
ERR = s 
EXIST = ex 
OPENED = od 
NUMBER = num 
NAMED = nmd 
NAME = fn 
ACCESS = acc 
SEQUENTIAL = seq 
DIRECT = dir 
FORM = fm 
FORMATTED = fmt 
UNFORMATTED = unf 
RECL = rcl 
NEXTREC = nr 
BLANK = blnk 


As an extension to the FORTRAN 77 language, the following inquiry specifiers are also supported. 

ACTION = act 
CARRIAGECONTROL = cc 
RECORDTYPE = ret 
BLOCKSIZE = bl 


IOSTAT = ios is an input/output status specifier. The integer variable or integer array element ios is 

defined with zero if no error condition exists or a positive integer value if an error condition 
exists. 

ERR = s is an error specifier and s is a statement label. When an error occurs, execution is 

transferred to the statement labelled by s . 

EXIST = ex ex is a logical variable or logical array element. 

Inquire by file: The value .TRUE, is assigned if a file exists with the specified name; 
otherwise the value .FALSE, is assigned. 

Inquire by unit: The value .TRUE, is assigned if the specified unit exists; otherwise the 
value .FALSE, is assigned. 

OPENED = od od is a logical variable or logical array element. 
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Inquire by file: The value .TRUE, is assigned if the specified file is connected to a unit; 
otherwise the value .FALSE, is assigned. 

Inquire by unit: The value .TRUE, is assigned if the specified unit is connected to a file; 
otherwise the value .FALSE, is assigned. 

NUMBER = num 

num is an integer variable or integer array element that is assigned the value of the unit 
number to which the file is connected. If no unit is connected to the file then num becomes 
undefined. 

NAMED = nmd 

nmd is a logical variable or logical array element name that is assigned the value .TRUE, if 
the file has a name; otherwise the value .FALSE, is assigned. 

NAME = fit f n is a character variable or character array element. Open Watcom FORTRAN 77 also 

permits f n to be a character substring. 

It is assigned the name of the file, if the file has a name; otherwise it becomes undefined. 
The file name that is returned need not be the same as that given in a FILE= specifier but it 
must be suitable for use in the FILE= specification of an OPEN statement (e.g., the file 
name returned may have additional system qualifications attached to it). 

ACCESS = acc 

acc is a character variable or character array element. Open Watcom FORTRAN 77 also 
permits acc to be a character substring. 

It is assigned the value ' SEQUENTIAL' if the file is connected for sequential access. It is 
assigned the value ' DIRECT' if the file is connected for direct access. It is assigned an 
undefined value if there is no connection. 

SEQUENTIAL = seq 

seq is a character variable or character array element. Open Watcom FORTRAN 77 also 
permits seq to be a character substring. 

It is assigned the value 'YES' if SEQUENTIAL is included in the set of allowed access 
methods for the file, the value 'NO' if SEQUENTIAL is not included in the set of allowed 
access methods for the file, or ' UNKNOWN' if Open Watcom FORTRAN 77 is unable to 
determine whether or not SEQUENTIAL is included in the set of allowed access methods 
for the file. 

DIRECT = dir dir is a character variable or character array element. Open Watcom FORTRAN 77 also 
permits dir to be a character substring. 

It is assigned the value ' YES' if DIRECT is included in the set of allowed access methods 
for the file, the value ' NO' if DIRECT is not included in the set of allowed access methods 
for the file, or ' UNKNOWN' if Open Watcom FORTRAN 77 is unable to determine 
whether or not DIRECT is included in the set of allowed access methods for the file. 

FORM =fm fm is a character variable or character array element. Open Watcom FORTRAN 77 also 
permits fm to be a character substring. 
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It is assigned the value ' FORMATTED' if the file is connected for formatted input/output, 
the value ' UNFORMATTED' if the file is connected for unformatted input/output, or an 
undefined value if there is no connection. 

FORMATTED =fmt 

fmt is a character variable or character array element. Open Watcom FORTRAN 77 also 
permits fmt to be a character substring. 

It is assigned the value 'YES' if FORMATTED is included in the set of allowed forms for 
the file, the value 'NO' if FORMATTED is not included in the set of allowed forms for the 
file, or ' UNKNOWN' if Open Watcom FORTRAN 77 is unable to determine whether or not 
FORMATTED is included in the set of allowed forms for the file. 

UNFORMATTED = unf 

unf is a character variable or character array element. Open Watcom FORTRAN 77 also 
permits unf to be a character substring. 

It is assigned the value 'YES' if UNFORMATTED is included in the set of allowed forms 
for the file, the value ' NO' if UNFORMATTED is not included in the set of allowed forms 
for the file, or ' UNKNOWN' if Open Watcom FORTRAN 77 is unable to determine 
whether or not UNFORMATTED is included in the set of allowed forms for the file. 

RECL = rcl rcl is an integer variable or integer array element that is assigned the value of the record 
length of the file connected for direct access. If the file is connected for formatted 
input/output, the length is the number of characters. If the file is connected for unformatted 
input/output, the length is measured in processor-dependent units (bytes). See the compiler 
User’s Guide for a discussion of record length or size. If there is no connection or if the 
file is not connected for direct access then the value is undefined. The RECL= specifier is 
also allowed if the file is connected for sequential access. 

NEXTREC = nr 

nr is an integer variable or integer array element that is assigned the value n+1 , where n 
is the record number of the last record read or written on the file connected for direct 
access. If the file is connected but no records have been read or written then the value is 1. 
If the file is not connected for direct access or if the position of the file can not be 
determined because of an input/output error then nr becomes undefined. 


BLANK = blnk 

bInk is a character variable or character array element. Open Watcom FORTRAN 77 
also permits blnk to be a character substring. 

It is assigned the value ' NULL' if null blank control is in effect for the file connected for 
formatted input/output, and is assigned the value ' ZERO' if zero blank control is in effect 
for the file connected for formatted input/output. If there is no connection, or if the file is 
not connected for formatted input/output, blnk becomes undefined. 


ACTION = act act is a character variable or character array element. Open Watcom FORTRAN 77 also 
permits act to be a character substring. 

It is assigned the value ' READ' if data can only be read from the file, ' WRITE' if data 
can only be written from the file, and ' READWRITE ' if data can be both read and written. 
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CARRIAGECONTROL = cc 

cc is a character variable or character array element. Open Watcom FORTRAN 77 also 
permits cc to be a character substring. 

It is assigned the value 'YES' if the first character of each record is interpreted as a 
carriage control character and ' NO' if no interpretation is placed on the first character of 
each record. 

RECORDTYPE = ret 

ret is a character variable or character array element. Open Watcom FORTRAN 77 also 
permits ret to be a character substring. 

It is assigned a value that represents the record type (or record structure) that is used for the 
file. The value assigned depends on the system on which you are running the program. 

See the compiler User’s Guide for a discussion of record types. 

BLOCKSIZE = bl 

bl is an integer variable or integer array element. 

It is assigned a value that represents the internal buffer size that is used for input/output 
operations on the file. The value assigned depends on the system on which you are running 
the program. See the compiler User’s Guide for a discussion of default internal buffer size. 


2.55.4 Definition Status of Specifiers - Inquire by Fife 

The following table summarizes which specifier variables or array elements become defined with values 
under what conditions when using the FILE= specifier. 


IOSTAT = ios 


(1) 

EXIST = ex 


(2) 

OPENED = od 


(2) 

NUMBER = num 


(4) 

NAMED = nmd 


(3) 

NAME = fn 


(3) 

ACCESS = acc 


(5) 

SEQUENTIAL = 

seq 

(3) 

DIRECT = dir 


(3) 

FORM = fm 


(5) 

FORMATTED = 

fmt 

(3) 

UNFORMATTED 

= unf 

(3) 

RECL = rcl 


(5) 

NEXTREC = nr 


(5) 

ACTION = act 


(5) 

CARRIAGECONTROL = cc 

(5) 

RECORDTYPE = 

ret 

(5) 

BLOCKSIZE = : 

bl 

(5) 


1. The IOSTAT= specifier variable is always defined with the most recent error status. If an error 
occurs during execution of the INQUIRE statement then the error status is defined with a 
positive integer; otherwise the status is that of the most recent input/output statement which 
referenced that file. 

2. The specifier always becomes defined unless an error condition occurs. 
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3. This specifier becomes defined with a value only if the file name specified in the FILE= 
specifier is an acceptable file name and the named file exists. Also, no error condition can occur 
during the execution of the INQUIRE statement. 

4. This specifier becomes defined with a value if and only if od becomes defined with the value 
.TRUE.. Also, no error condition can occur during the execution of the INQUIRE statement. 

5. This specifier may become defined with a value only if od becomes defined with the value 
.TRUE.. However, there may be other conditions under which this specifier does not become 
defined with a value. In other words, (5) is a necessary, but not sufficient condition. For 
example, blnk is undefined if the file is not connected for formatted input/output. 


2.55.5 Definition Status of Specifiers - Inquire by Unit 

The following table summarizes which specifier variables or array elements become defined with values 
under what conditions when using the UNIT= specifier. 


IOSTAT = ios 


(1) 

EXIST = ex 


(2) 

OPENED = od 


(2) 

NUMBER = num 


(3) 

NAMED = nmd 


(3) 

NAME = fn 


(3) 

ACCESS = acc 


(3) 

SEQUENTIAL = 

seq 

(3) 

DIRECT = dir 


(3) 

FORM = fm 


(3) 

FORMATTED = 

fmt 

(3) 

UNFORMATTED 

= unf 

(3) 

RECL = rcl 


(3) 

NEXTREC = nr 


(3) 

ACTION = act 


(3) 

CARRIAGECONTROL = cc 

(3) 

RECORDTYPE = 

ret 

(3) 

BLOCKSIZE = : 

bl 

(3) 


1. The IOSTAT= specifier variable is always defined with the most recent error status. If an error 
occurs during execution of the INQUIRE statement then the error status is defined with a 
positive integer; otherwise the status is that of the most recent input/output statement which 
referenced that unit. 

2. This specifier always becomes defined unless an error condition occurs. 

3. This specifier becomes defined with a value only if the specified unit exists and if a file is 
connected to the unit. Also, no error condition can occur during the execution of the INQUIRE 
statement. 

For more information on input/output, see the chapter entitled "Input/Output" on page 215. 
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2.56 INTEGER Statement 


The INTEGER statement is a type declaration statement and can be used to declare a name to be of type 
integer. The implicit type of the name, whether defined by the "first letter rule" (see the chapter entitled 
"Names, Data Types and Constants" on page 151) or by an IMPLICIT statement, is either confirmed or 
overridden. However, once a name has been declared to be of type integer, it cannot appear in another type 
declaration statement. 

There are various forms of the INTEGER statement. The following sections describe them. 

2.56.1 Standard INTEGER Statement 


INTEGER name [,name] ... 


where: 

name is a variable name, array name, array declarator, symbolic name of a constant, function name or 
dummy procedure name. 

This form is the standard form of the INTEGER statement. 

Example: 

DIMENSION C (-5:5) 

INTEGER A, B (10), C 

In the previous example, A is defined to be a variable of type integer and B and C are defined to be arrays of 
type integer. 

2.56.2 Extended INTEGER Statement: Length Specification 


INTEGER[*len[,]] name [,name] ... 


where: 

name is one of the following forms: 
v [ *len] 
a [ *len] (d) 
a(d)[*len] 

v is a variable name, array name, symbolic name of a constant, function name or dummy 

procedure name. 
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a is an array name. 

(d) is that part of the array declarator defining the dimensions of the array. 

len is called the length specification and is an unsigned positive integer constant or an integer 

constant expression enclosed in parentheses whose value is 1, 2 or 4. 

This form of the INTEGER statement is a Open Watcom FORTRAN 77 extension to the FORTRAN 77 
language. The length specification specifies the number of bytes of storage that will be allocated for the 
name appearing in the INTEGER statement. The default length specification is 4. A length specification of 
1 or 2 does not change the data type; it merely restricts the magnitude of the integer that can be represented. 
See the chapter entitled "Names, Data Types and Constants" on page 151 for more information. 

The length specification immediately following the word INTEGER is the length specification for each 
entity in the statement not having its own length specification. If a length specification is not specified the 
default length specification is used. An entity with its own specification overrides the default length 
specification or the length specification immediately following the word INTEGER . Note that for an array 
the length specification applies to each element of the array. 

Example: 

DIMENSION C (-5:5) 

INTEGER A, B*2(10), C*2 
INTEGER*1 X 

In the previous example, X is declared to be a variable of type integer and occupying 1 byte of storage, A is 
declared to be a variable of type integer and occupying 4 bytes of storage and B and C are declared to be 
arrays of type integer with each element of the array occupying 2 bytes. 

2.56.3 Extended INTEGER Statement: Data Initialization 


INTEGER[*len[,]] name [/cl/] [,name[/cl/]] ... 


where: 


name 

is as described in the previous section. 

len 

is as described in the previous section. 

cl 

is a list of the form: 


k [,k] ... 

k 

is one of the forms: 


c 

r*c (equivalent to r successive appearances of c) 
c is a constant or the symbolic name of a constant 
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r is an unsigned positive integer constant or the symbolic name of a constant. 

This form of the INTEGER statement is an extension to the FORTRAN 77 language. The rules for data 
initialization are the same as for the DATA statement. 

Example: 

INTEGER A/100/, B(10)/10*0/ 

In the previous example, A is initialized with the integer constant 100 and each element of the array B is 
initialized with the integer constant 0 . 
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2.57 INTRINSIC Statement 


intrinsic f [,f] 


where: 


f is the name of an intrinsic function name. 

An INTRINSIC statement is used to identify a symbolic name as the name of an intrinsic function. It also 
allows a specific intrinsic function to be passed as an actual argument. The names of intrinsic functions for 
type conversion (INT, IFIX, HFIX, IDINT, FLOAT, DFLOAT, SNGL, REAL, DREAL, DBLE, CMPLX, 
DCMPLX, ICHAR, CHAR), lexical relationship (LGE, LGT, LLE, LLT), for choosing the largest or 
smallest value (MAX, MAXO, AMAX1, DMAX1, AMAXO, MAXI, MIN, MINO, AMIN1, DMIN1, 
AMINO, MINI), as well as ALLOCATED, ISIZEOF and LOC, must not be used as actual arguments. 

A generic intrinsic function does not lose its generic property if it appears in an INTRINSIC statement. 

A name must only appear in an INTRINSIC statement once. A symbolic name must not appear in both an 
INTRINSIC and an EXTERNAL statement in a program unit. 

Example: 

INTRINSIC SIN 


CALL SAM( SIN ) 

In the previous example, the intrinsic function SIN was passed to the subroutine SAM . If the INTRINSIC 
statement were eliminated then the variable SIN would be passed to the subroutine SAM. 
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2.58 LOGICAL Statement 


The LOGICAL statement is a type declaration statement and can be used to declare a name to be of type 
logical. The implicit type of the name, whether defined by the "first letter rule" (see the chapter entitled 
"Names, Data Types and Constants" on page 151) or by an IMPLICIT statement, is either confirmed or 
overridden. However, once a name has been declared to be of type logical, it cannot appear in another type 
declaration statement. 

There are various forms of the LOGICAL statement. The following sections describe them. 

2.58.1 Standard LOGICAL Statement 


LOGICAL name [,name] ... 


where: 

name is a variable name, array name, array declarator, symbolic name of a constant, function name or 
dummy procedure name. 

This form is the standard form of the LOGICAL statement. 

Example: 

DIMENSION C (-5:5) 

LOGICAL A, B(10), C 

In the previous example, A is defined to be a variable of type logical and B and C are defined to be arrays of 
type logical. 

2.58.2 Extended LOGICAL Statement: Length Specification 


LOGICAL[*len[,]] name [,name] ... 


where: 

name is one of the following forms: 
v [ *len] 
a [ *len] (d) 
a(d)[*len] 

v is a variable name, array name, symbolic name of a constant, function name or dummy 

procedure name. 
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a is an array name. 

(cl) is that part of the array declarator defining the dimensions of the array. 

len is called the length specification and is an unsigned positive integer constant or an integer 

constant expression enclosed in parentheses whose value is 1 or 4. 

This form of the LOGICAL statement is a Open Watcom FORTRAN 77 extension to the FORTRAN 77 
language. The length specification specifies the number of bytes of storage that will be allocated for the 
name appealing in the LOGICAL statement. The default length specification is 4. A length specification of 
1 only changes the storage requirement from 4 bytes to 1 byte; the values of true and false can be 
represented regardless of the length specification. 

The length specification immediately following the word LOGICAL is the length specification for each 
entity in the statement not having its own length specification. If a length specification is not specified the 
default length specification is used. An entity with its own specification overrides the default length 
specification or the length specification immediately following the word LOGICAL . Note that for an array 
the length specification applies to each element of the array. 

Example: 

DIMENSION C (-5:5) 

LOGICAL A, B*1(10) , C*1 

LOGICAL*4 X 

In the previous example, X is declared to be a variable of type logical and occupying 4 bytes of storage, A is 
declared to be a variable of type logical and occupying 4 bytes of storage and B and C are declared to be 
arrays of type logical with each element of the array occupying 1 byte. 

2.58.3 Extended LOGICAL Statement: Data Initialization 


LOGICAL[*len[,]] name [/cl/] [,name[/cl/]] ... 


where: 


name 

is as described in the previous section. 

len 

is as described in the previous section. 

cl 

is a list of the form: 


k [,k] ... 

k 

is one of the forms: 


c 

r*c (equivalent to r successive appearances of c) 
c is a constant or the symbolic name of a constant 
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r is an unsigned positive integer constant or the symbolic name of a constant. 

This form of the LOGICAL statement is an extension to the FORTRAN 77 language. The rules for data 
initialization are the same as for the DATA statement. 

Example: 

LOGICAL A/.TRUE./, B(10)/10*.FALSE./ 

In the previous example, A is initialized with the logical constant . TRUE . and each element of the array B 
is initialized with the logical constant . FALSE . . 
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2.59 LOOP Statement 


LOOP [:block-label] 


The LOOP statement is used in conjunction with the structured END LOOP or UNTIL statement. The 
LOOP statement marks the beginning of a sequence of statements which are to be repeated. The END 
LOOP or UNTIL statement marks the end of the loop. The LOOP-block is executed until control is 
transferred out of the LOOP-block or the logical expression (or integer arithmetic expression) of the 
UNTIL statement has a true (or non-zero) value. 

The QUIT statement may be used to transfer control out of a LOOP-block. 


Example: 

LOOP 

READ *, X 

IF( X .GT. 99.0 ) QUIT 
PRINT *, X 
END LOOP 

Example: 

X = 1.0 
LOOP 

PRINT *, X, SQRT( X ) 

X = X + 1.0 
UNTIL( X .GT. 10.0 ) 

An optional block label may be specified with the LOOP statement. 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.60 MAP Statement 


MAP 


The MAP statement is used in conjunction with the END MAP declarative statement. The MAP statement 
marks the start of a memory mapping structure. A MAP structure must appear within a UNION block. Any 
number of variables of any type may appear within a memory map. At least two MAP structures must 
appear within a UNION block. A UNION block permits the mapping of the same storage in several 
different ways. 

The following example maps out a 4-byte integer on an Intel 80x86-based processor. 


Example: 

STRUCTURE /MAPINT/ 
UNION 


MAP 


INTEGER* 4 

LONG 

END 

MAP 


MAP 


INTEGER*2 

LO_ WORD 


INTEGER*2 

HI_ WORD 

END 

MAP 


MAP 


INTEGER*1 

BYTE_ 0 


INTEGER*1 

BYTE_ 1 


INTEGER*1 

BYTE_2 


INTEGER*1 

BYTE_ 3 

END 

MAP 



END UNION 
END STRUCTURE 

RECORD /MAPINT/ I 

I%LONG = '01020304'x 

PRINT ’ (2Z4 ) ' , I%LO_ WORD, I%HI_ WORD 
END 

For more information, see the chapter entitled "Structures, Unions and Records" on page 167. 
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2.61 NAMELIST Statement 


NAMELIST /name/ vlist [[,]/name/ vlist] ... 


where: 

name is the name, enclosed in slashes, of a group of variables. It may not be the same as a variable 
or array name. 

vlist is a list of variable names and array names separated by commas. 

The NAMELIST statement is used to declare a group name for a set of variables so that they may be read or 
written with a single namelist-directed READ, WRITE, or PRINT statement. 

The list of variable or array names belonging to a NAMELIST name ends with a new NAMELIST name 
enclosed in slashes or with the end of the NAMELIST statement. The same variable name may appear in 
more than one namelist. 

A dummy variable, dummy array name, or allocatable array may not appear in a NAMELIST list. Also, a 
variable whose type is a user-defined structure may not appear in a NAMELIST list. 

The NAMELIST statement must precede any statement function definitions and all executable statements. 

A NAMELIST name must be declared in a NAMELIST statement and may be declared only once. The 
name may appear only in input/output statements. The READ, WRITE, and PRINT statements may be used 
to transmit data between a file and the variables specified in a namelist. 


Example: 


CHARACTER*20 NAME 
CHARACTER*20 STREET 
CHARACTER*15 CITY 
CHARACTER*20 STATE 
CHARACTER*20 COUNTRY 
CHARACTER*10 ZIP_ CODE 
INTEGER AGE 
INTEGER MARKS(10) 

NAMELIST /PERSON/ NAME, STREET, CITY, 
+ COUNTRY, ZIP_ CODE, 


STATE, 

AGE, MARKS 


OPEN( UNIT=1, FILE='PEOPLE' ) 

LOOP 

READ( UNIT=1, FMT=PERSON, END=99 ) 
WRITE( UNIT=6, FMT=PERSON ) 

ENDLOOP 

99 CLOSE ( UNIT=1 ) 

END 


The following example shows another form of a namelist-directed READ statement. 
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Example: 


CHARACTER*20 NAME 
CHARACTER*20 STREET 
CHARACTER*15 CITY 
CHARACTER*20 STATE 
CHARACTER*20 COUNTRY 
CHARACTER*10 ZIP_ CODE 
INTEGER AGE 
INTEGER MARKS(10) 
NAMELIST /PERSON/ NAME, 


STREET, CITY, 


+ 


COUNTRY, ZIP_ CODE, 


STATE, 

AGE, MARKS 


READ PERSON 
PRINT PERSON 
END 


The input data must be in a special format. The first character in each record must be blank. The second 
character in the first record of a group of data records must be an ampersand (&) or dollar sign ($) 
immediately followed by the NAMELIST name. The NAMELIST name must be followed by a blank and 
must not contain any imbedded blanks. This name is followed by data items separated by commas. The 
end of a data group is signaled by the character "&" or optionally followed by the string "END". If the 
"&" character was used to start the group, then it must be used to end the group. If the "$" character was 
used to start the group, then it must be used to end the group. 

The form of the data items in an input record is: 

Name = Constant 

The name may be a variable name or an array element name. The constant may be integer, 
real, complex, logical or character. Logical constants may be in the form "T" or ".TRUE" 
and "F" or ".FALSE". Character constants must be contained within apostrophes. 
Subscripts must be of integer type. 

ArrayName = Set of Constants 

The set of constants consists of constants of the type integer, real, complex, logical or 
character. The constants are separated by commas. The number of constants must be less 
than or equal to the number of elements in the array. Successive occurrences of the same 
constant may be represented in the form r*constant, where r is a non-zero integer 
constant specifying the number of times the constant is to occur. 

The variable and array names specified in the input file must appear in the NAMELIST list, but the order is 
not important. A name that has been made equivalent to a name in the input data cannot be substituted for 
that name in the NAMELIST list. The list can contain names of items in COMMON but must not contain 
dummy argument names. 

Each data record must begin with a blank followed by a complete variable or array name or constant. 
Embedded blanks are not permitted in name or constants. Trailing blanks after integers and exponents are 
treated as zeros. 
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Example: 

&PERSON 

NAME = 'John Doe' 

STREET = '22 Main St.' CITY = 'Smallville' 
STATE = 'Texas' COUNTRY = 'U.S.A.' 

ZIP_ CODE = ' 78910-1203' 

MARKS = 73, 82, 3*78, 89, 2*93, 91, 88 
AGE =23 
SEND 


The form of the data items in an output record is suitable for input using a namelist-directed READ 
statement. 

1. Output records are written using the ampersand character (&), not the dollar sign ($), although 
the dollar sign is accepted as an alternative during input. That is, the output data is preceded by 
"&name" and is followed by "&END". 

2. All variable and array names specified in the NAMELIST list and their values are written out, 
each according to its type. 

3. Character data is enclosed in apostrophes. 

4. The fields for the data are made large enough to contain all the significant digits. 

5. The values of a complete array are written out in columns. 

For more information, see the chapters entitled "Format" on page 225 and "Input/Output" on page 215. 
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2.62 OPEN Statement 


OPEN (oplist) 


where: 

oplist must include the UNIT= specifier and may include at most one of each of the open 

specifiers listed below. Specifiers are separated by commas. 

[UNIT =] u 
IOSTAT = ios 
ERR = s 
FILE = fin 
STATUS = sta 
ACCESS = acc 
FORM = fm 
RECL = rcl 
BLANK = blnk 


As an extension to the FORTRAN 77 language, the following inquiry specifiers are also 
supported. 

ACTION = act 
CARRIAGECONTROL = cc 
RECORDTYPE = ret 
BLOCKSIZE = bl 
SHARE = shr 


The OPEN statement may be used to connect an existing file to a unit, create a file that is preconnected, 
create a file and connect it to a unit, or change certain specifications of a connection between a file and a 
unit. 

Open Specifiers 
[UNIT =] u 

u is an external unit identifier. An external unit identifier is a non-negative integer 
expression. If the optional UNIT= specifier is omitted then the specifier must be the first 
item in the list of specifiers. 

IOSTAT = ios 

is an input/output status specifier. The integer variable or integer array element ios is 
defined with zero if no error condition exists or a positive integer value if an error condition 
exists. 

ERR = s 

is an error specifier and s is a statement label. When an error occurs, execution is 
transferred to the statement labelled by s . 
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FILE = fin 

fin is a character expression whose value when trailing blanks are removed is the name of 
a file to be connected to the specified unit. If this specifier is omitted and the unit is not 
connected to a file, it becomes connected to a file determined by Open Watcom FORTRAN 
77. The name established by Open Watcom FORTRAN 77 is described in the section 
entitled "Units" on page 219 of the chapter entitled "Input/Output" 

STATUS = sta 

sta is a character expression whose value when trailing blanks are removed is ' OLD' , 
'NEW' , ' SCRATCH' , or 'UNKNOWN' . 


OLD 


When OLD is specified, a FILE= specifier must be given. The file 
must exist. 


NEW When NEW is specified, a FILE= specifier must be given. The file 

must not exist. Successful execution of the OPEN statement creates the 
file and changes the status to OLD . 


SCRATCH SCRATCH may only be specified for an unnamed file (i.e. FILE= is 

not allowed). When the file is closed, it is deleted. 

UNKNOWN If UNKNOWN is specified, the status is ignored. If the STATUS= 
specifier is omitted then UNKNOWN is assumed. 


ACCESS = acc 

acc is a character expression whose value when trailing blanks are removed is 
' SEQUENTIAL' or 'DIRECT' . It specifies the access method for the file. If the 
ACCESS= specifier is omitted then 'SEQUENTIAL' is assumed. If the file exists then the 
access method must be in the set of allowed access methods for the file. If the file does not 
exist then the file is created with a set of allowed access methods that includes the specified 
access method. 

Open Watcom FORTRAN 77 also supports access ' APPEND' which is a form of 
sequential access in which the file is positioned at the endfile record. The file must exist or 
the append access method must be in the set of allowed access methods for the file. In all 
other respects, the file is treated as if ' SEQUENTIAL' had been specified. 


FORM =fm 

f m is a character expression whose value when trailing blanks are removed is 
' FORMATTED' or ' UNFORMATTED' . It specifies that the file is being connected for 
formatted or unformatted input/output. If the FORM= specifier is omitted and the file is 
being connected for direct access then 'UNFORMATTED' is assumed. If the FORM= 
specifier is omitted and the file is being connected for sequential access then 
' FORMATTED' is assumed. If the file exists then the specified form must be included in 
the set of allowed forms for the file. If the file does not exist then the file is created with a 
set of allowed forms that includes the specified form. 

RECL = rcl 

rcl is an integer expression whose value must be positive. It specifies the length of each 
record in a file being connected for direct access. If the file is being connected for direct 
access, this specifier must be given; otherwise it must be omitted. Open Watcom 
FORTRAN 77 allows the RECL= specifier for files opened for sequential access. 
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BLANK = blnk 

blnk is a character expression whose value when trailing blanks are removed is ' NULL' 
or ' ZERO' . If ' NULL' is specified then all blank characters in numeric formatted input 
fields are ignored except that an entirely blank field has a value of zero. If 'ZERO' is 
specified then all blank characters other than leading blanks are treated as zeroes. If this 
specifier is omitted then ' NULL' is assumed. This specifier may only be present for a file 
being connected for formatted input/output. 

ACTION = act 

act is a character expression whose value when trailing blanks are removed is ' READ' , 

' WRITE' or ' READWRITE' . If ' READ' is specified, data can only be read from the 
file. If 'WRITE' is specified, data can only be written to the file. If 'READWRITE' is 
specified, data can both be read and written. The default is ' READWRITE ' . 

CARRIAGECONTROL = cc 

cc is a character expression whose value when trailing blanks are removed is 'YES', or 
' NO' . If ' YES' is specified. Open Watcom FORTRAN 77 will automatically add an 
extra character at the beginning of each record. This character will be interpreted as a 
carriage control character. If 'NO' is specified, records will be written to the file without 
adding a carriage control character at the beginning of the record. The default is ' NO' . 

RECORDTYPE = ret 

ret is a character expression whose value when trailing blanks are removed specifies the 
type of record (or record structure) to be used for the file. The allowed values for ret 
depend on the system on which you are running the program. See the compiler User’s 
Guide for a discussion of the RECORDTYPE= specifier. 

BLOCKSIZE = bl 

bl is an integer expression whose value specifies the internal buffer size to be used for file 
input/output. The allowed values for bl depend on the system on which you are running 
the program. Generally, the larger the buffer, the faster the input/output. See the compiler 
User’s Guide for a discussion of the BLOCKS I ZE= specifier. 

SHARE = shr 

shr is a character expression whose value when trailing blanks are removed specifies the 
way in which other processes can simultaneously access the file. The allowed values for 
shr depend on the system on which you are running the program. See the compiler User’s 
Guide for a discussion of the SHARE= specifier. 


Example: 

OPEN( UNIT=1, FILE='TEST', STATUS='UNKNOWN', 

+ ACCESS = 'SEQUENTIAL', 

+ FORM='FORMATTED', BLANK='ZERO' ) 

In the above example, the file 'TEST' , containing FORMATTED records, is connected to unit 1. The 
status of the file is ' UNKNOWN' since we do not know if it already exists. We will access the file 
sequentially, using formatted input/output statements. Blanks in numeric input data are to be treated as 
zeroes. 
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Notes: 

1. If the unit is already connected to a file that exists, the execution of an OPEN statement for that 
unit is permitted. 

(a) If the same file is opened then only the BLANK= specifier may be different. The 
same file is opened if no FILE= specifier was given or if the FILE= specifier 
refers to the same file. 

(b) If a different file is opened then the currently connected file is automatically 
closed. 

2. If the file to be connected to the unit does not exist, but is already preconnected to the unit, any 
properties specified in the OPEN statement are merged with and supersede those of the 
preconnection. For example, the RECL= specification will override the record length attribute 
defined by a preconnection of the file. 

3. The same file may not be connected to two or more different units. 

For more information on input/output, see the chapter entitled "Input/Output" on page 215. 


114 OPEN Statement 




FORTRAN Statements 


2.63 OTHERWISE Statement 


OTHERWISE 


The OTHERWISE statement is used in conjunction with the SELECT statement. The OTHERWISE 
statement marks the start of a new CASE block which is a series of zero or more statements ending in an 

END SELECT statement. 


When this statement is used and the value of a case expression is not found in any case list then control of 
execution is transferred to the first executable statement following the OTHERWISE statement. 


The CASE DEFAULT statement may be used in place of the OTHERWISE statement. 


Example: 


SELECT CASE 
CASE ( 'a' : 

PRINT *, 
CASE ( 'A' : 

PRINT *, 
CASE ( 'O' : 

PRINT *, 
OTHERWISE 

PRINT *, 
END SELECT 


( CH ) 

' z' ) 

'Lower 
' Z' ) 

'Upper 
' 9' ) 

'Digit 

'Special 


letter 
letter 

character 


case 

case 


In the above example, if the character CH is not a letter or digit then the OTHERWISE block is executed. 
Note: The OTHERWISE or CASE DEFAULT block must follow all other CASE blocks. 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 


OTHERWISE Statement 115 







Language Reference 


2.64 PARAMETER Statement 


PARAMETER (p=e [,p=e] ...) 


where: 

p is a symbolic name. 

e is a constant expression. Refer to the chapter entitled "Expressions" on page 173 for more 
information. 

p is known as a symbolic constant whose value is determined by the value of the expression e according to 
the rules of assignment as described in the chapter entitled "Assignment Statements" on page 187. Any 
symbolic constant appearing in expression e must have been previously defined in the same or a previous 
PARAMETER statement in the same program unit. A symbolic constant may not be defined more than once 
in a program unit. 

If the symbolic name p is of type integer, real, double precision or complex then the corresponding 
expression e must be an arithmetic constant expression (see the chapter entitled "Expressions" on page 
173). If the symbolic name p is of type character or logical then the expression e must be a character 
constant expression or a logical constant expression respectively (see the chapter entitled "Expressions" on 
page 173). 

Example: 

PARAMETER (PI=3.14159,BUFFER=80,PIBY2=PI/2) 

PARAMETER (ERRMSG='AN ERROR HAS OCCURRED' ) 

If a symbolic constant is not of default implied type, its type must be specified in an IMPLICIT statement 
or a type statement before its occurrence in a PARAMETER statement. Similarly, if the length of a character 
symbolic constant is not the default length of 1, its length must be specified in an IMPLICIT statement or 
a type statement before its occurrence in a PARAMETER statement. 
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2.65 PAUSE Statement 


pause [n] 


where: 

n is a character constant or an unsigned integer constant of no more than five digits. 

Open Watcom FORTRAN 77 allows n to be any unsigned integer constant. 

Execution of a PAUSE statement causes a cessation of execution of the program. Execution of the program 
may be resumed by the program operator by pressing the terminal line entering key (e.g., ENTER or 
RETURN). The PAUSE statement may appear in any program unit. 

If the Open Watcom FORTRAN 77 debugger was requested then execution of the PAUSE statement will 
cause entry into the debugger. Program execution may be resumed by issuing the debugger "go" command. 

Example: 

PAUSE 4341 

The four digit number 4 341 is displayed on the terminal. The program temporarily ceases execution. 
Execution is resumed by pressing the terminal line entering key. 

Example: 

PAUSE 'Ready the paper and then resume execution' 

The character string 

Ready the paper and then resume execution 
is displayed on the terminal. Execution of the program may be resumed. 
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2.66 PRINT Statement 


Two forms of the PRINT statement are supported by Open Watcom FORTRAN 77. 

2.66.1 Standard PRINT Statement 


PRINT f [,olist] 


where: 

f is a format identifier. 

olist is an optional output list. 

2.66.2 Extended PRINT Statement 

PRINT, olist 


where: 

olist is an output list. 

2.66.3 Description of PRINT Statement 

The PRINT statement is used to transfer data from the executing FORTRAN program to an external device 
or file. 

Format Identifier - A format identifier is one of the following: 

1. A statement label of a FORMAT statement that appears in the same program unit as the format 
identifier. 

2. An integer variable name that has been assigned the statement label of a FORMAT statement that 
appears in the same program unit as the format identifier (see the ASSIGN statement). 

3. An integer array name. 

4. A character array name. 

5. Any character expression except one involving the concatenation of an operand whose length 
specification is (*) unless the operand is a symbolic constant (see the PARAMETER statement). 

6. An asterisk (*) , indicating list-directed formatting. 


Open Watcom FORTRAN 77 supports a variation of list-directed formatting in which the 
asterisk (*) may be omitted. It is equivalent to 

PRINT * [,olist] 
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7. A NAMELIST name, indicating namelist-directed formatting. 

Output list - An output list may contain one or more of the following: 

1. A variable name. 

2. An array element name. 

3. A character substring name. 

4. An array name except an assumed-size dummy array. 

5. Any other expression except a character expression involving concatenation of an operand 
whose length specification is an asterisk in parentheses unless the operand is the symbol name of 
a constant (since the length can be determined at compile time). 

6. An implied-DO list of the form: 

( dlist, i = el, e2 [,e3] ) 

where dlist is composed of one or more of items (1) through (6). 

Example: 

CHARACTER*5 S 
COMPLEX C 
S = 'Hello' 

I = 123 

X = 12.5 

C = (12.5,4.58) 

PRINT *, S, I, X, C 
END 

The above example illustrates list-directed formatting using the PRINT statement. The asterisk specifies 
that the variables in the output list are to be displayed in some format that is appropriate to the type of the 
variable (hence the term "list-directed"). The CHARACTER variable S is printed using a suitable A format 
descriptor. The INTEGER variable I is printed using a suitable I format descriptor. The REAL variable X 
is printed using a suitable G format descriptor. The COMPLEX variable C is printed using a suitable G 
format descriptor and is displayed with enclosing parentheses and a comma. Output from the above 
program would resemble the following. 

Hello 123 12.5000000 (12.5000000,4.5799999) 

Example: 

CHARACTER*5 S 
COMPLEX C 
S = 'Hello' 

I = 123 

X = 12.5 

C = (12.5,4.58) 

PRINT, S, I, X, C 
END 

The above example illustrates a Open Watcom FORTRAN 77 extension of list-directed formatting using 
the PRINT statement. The asterisk is omitted but the results are exactly the same as in the previous 
example. 
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Example: 

PRINT 100, X, Y, Z 
100 FORMAT( 3F10.5 ) 

PRINT ' ( 3F10.5 ) ' , X, Y, Z 

The above gives two examples of the PRINT statement. In both cases, the format conversion is identical 
but it was specified in different ways. When executed, the effect of both PRINT statements is the same. 

Example: 

PRINT '(IX,100A1)', ('*',I=1,J) 

The above example illustrates a technique for producing histograms using the implied DO-loop. Each time 
this statement is executed, a number of asterisks are printed, depending on the value of J. 

Notes: 

1. The PRINT statement is implicitly a formatted output statement. 

2. The unit number that is implicitly used in the PRINT statement is unit number 6. 

3. If no output list is specified then the effect of the PRINT statement is to produce one or more 
records whose characters are all blanks. 

4. FORTRAN 77 leaves the format of output in list-directed formatting to the discretion of Open 
Watcom FORTRAN 77. Hence other FORTRAN compilers may produce different results. If 
the format of output must be consistent from one compiler to the next then list-directed 
formatting should not be used. 

5. An implication of point (6) above is that nesting of implied-DO lists is permitted. For example, 
the output list 

( (A (I, J) , B (I, J) , J = 1, 5), I = 1, 10 ) 

may be broken down into the following components: 

A (I, J) , B (I, J) 

(_dlistl_, J = 1, 5) 

( .dlist2., 1 = 1, 10 ) 

For more information on input/output, see the chapter entitled "Input/Output" on page 215. For more 
information on formatted input/output, see the chapter entitled "Format" on page 225. 
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2.67 PROGRAM Statement 


PROGRAM pgm 


where: 

pgm is the symbolic name of the main program. 

A PROGRAM statement is optional in an executable program. If it does appear, it must be the first statement 
in the main program. 

Example: 

PROGRAM CALC 


CALL COMPUTE 


END 

The main program can contain any Open Watcom FORTRAN 77 statement except a FUNCTION, 
SUBROUTINE, BLOCK DATA. RETURN or ENTRY statement. Note that a SAVE statement is allowed but 
has no effect in the main program. 
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2.68 QUIT Statement 


QUIT [: block-label] 


The QUIT statement may be used to cause a transfer of control to the first executable statement that follows 
the terminal statement of the block which contains it. Examples of such terminal statements are ADMIT, 
CASE, END DO, END LOOP, END WHILE, UNTIL, etc. If block-label is present then control is 
transferred out of the block identified by that block label. The QUIT statement is an extension to the 
FORTRAN 77 language. 


Example: 

LOOP 

WRITE( UNIT=*, FMT='(A)' ) 'Enter a number' 

READ( UNIT=*, FMT=' (FI0.4)', IOSTAT=IOS ) X 
IF( IOS .NE. 0 ) QUIT 
IF( X .LT. 0 ) QUIT 
PRINT *, X, SQRT( X ) 

END LOOP 
END 


For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.69 READ Statement 


Three forms of the READ statement are supported by Open Watcom FORTRAN 77. 

2.69.1 Standard READ Statement 


READ (cilist) [ilist] 
READ f [,ilist] 


where: 

cilist is a control information list of specifiers separated by commas: 

[UNIT =] u 
[FMT =] f 
REC = rn 
IOSTAT = ios 
ERR = s 
END = s 

is a format identifier, 
is an optional input list. 


/ 

ilist 


2.69.2 Extended READ Statement 


READ, ilist 


where: 

ilist is an input list. 

2.69.3 Description of READ Statement 

The READ statement is used to transfer data from a device or file into the executing FORTRAN program. 
As shown above. Open Watcom FORTRAN 77 supports three forms of the READ statement. 

Control Information List and Format Identifier 

[UNIT =] u 

u is an external unit identifier or an internal file identifier. 

1. An external unit identifier is a non-negative integer expression or an asterisk 

(*) in which case unit 5 is assumed. 
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2. An internal file identifier is the name of a character variable, character array, 
character array element, or character substring. 

If the optional UNIT= specifier is omitted then the unit specifier must be the first item in 
the list of specifiers. 


[FMT =]f 

f is a format identifier. A format identifier is one of the following: 

1. A statement label of a FORMAT statement that appears in the same program unit 
as the format identifier. 

2. An integer variable name that has been assigned the statement label of a 
FORMAT statement that appears in the same program unit as the format identifier 
(see the ASSIGN statement). 

3. An integer array name. 

4. A character array name. 

5. Any character expression except one involving the concatenation of an operand 
whose length specification is (*) unless the operand is a symbolic constant (see 
the PARAMETER statement). 

6. An asterisk (*) , indicating list-directed formatting. 

Open Watcom FORTRAN 77 supports a third form of the READ statement in 
which the asterisk (*) may be omitted. This is a form of list-directed 
formatting in which unit 5 is assumed. It is equivalent to 

READ * [,ilist] 

7. A NAMELIST name, indicating namelist-directed formatting. 

If the optional FMT= specifier is omitted then the format specifier must be the second item 
in the list of specifiers and UNIT= must not be specified for the first item in the list. 


REC = rn 

rn is an integer expression whose value must be positive. It is the number of the record to 
be read when a file is connected for direct access. 


IOSTAT = ios 

is an input/output status specifier. The integer variable or integer array element ios is 
defined with zero if no error occurs, a positive integer value if an error occurs, or a negative 
integer value if an end-of-file occurs. 


ERR = s 

is an error specifier and s is a statement label. When an error occurs, execution is 
transferred to the statement labelled by s . 

END = s 

is an end-of-file specifier and s is a statement label. When an end-of-file occurs, execution 
is transferred to the statement labelled by s . 

Input list - An input list may contain one or more of the following: 

1. A variable name. 

2. An array element name. 
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3. A character substring name. 

4. An array name except an assumed-size dummy array. 

5. An implied-DO list of the form: 

( dlist, i = el, e2 [,e3] ) 

where dlist is composed of one or more of items (1) through (5). 


Example: 

READ ( 

5, 100 )X, Y, Z 





READ ( 

UNIT=5, FMT=100 

)X, 

Y, 

Z 

100 

FORMAT( 3F10.5 ) 





READ ( 

UNIT=5, FMT='( 

3F10 

.5 : 

) ' 


READ ( 

5, ' ( 3F10.5 )' 

)X, 

Y, 

z 


The above gives four examples of formatted READ statements, using the first of three supported forms of 
the READ statement. In all cases, the format conversion is identical but it was specified in different ways. 
When executed, the effect of all READ statements is the same. The unit number that is explicitly used in 
this form of the READ statement is unit number 5. There are, in fact, many other ways in which the READ 
statement could have been written, all of which would have the same effect when executed. We have not 
shown the use of all the specifiers. 

Example: 

READ 100, X, Y, Z 
100 FORMAT( 3F10.5 ) 

READ '( 3F10.5 )', X, Y, Z 


The above gives two examples of formatted READ statements, using the second of three supported forms of 
the READ statement. In both cases, the format conversion is identical but it was specified in different ways. 
When executed, the effect of both READ statements is the same. The unit number that is implicitly used in 
this form of the READ statement is unit number 5. 


Example: 

READ( 5, * )X, Y, Z 

READ( *, * )X, Y, Z 

READ( UNIT=5, FMT=* )X, Y, Z 

READ( UNIT=*, FMT=* )X, Y, Z 

READ *, X, Y, Z 

READ , X, Y, Z 


The above six examples of list-directed formatted input are all equivalent. Open Watcom FORTRAN 77 
assumes unit 5 when the unit number identifier is an asterisk (as in the second and fourth examples). In the 
fifth example, the asterisk is a format identifier indicating list-directed formatting. The fifth and sixth 
examples are examples of the second and third forms, respectively, of the READ statement in which Open 
Watcom FORTRAN 77 assumes unit 5. When the format identifier is an asterisk or when the third form of 
the READ statement is used, we call this list-directed list-directed formatting. 
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Example: 

READ( 8 ) X, Y, Z 
READ( UNIT=8 )X, Y, Z 

The above gives two examples of unformatted READ statements. The unit number used in the example is 8. 
When executed, the effect of both of these statements is the same. The values of the variables X, Y and Z 
are read from the file connected to unit 8. The values are stored in the file in their binary form (a form 
quite incomprehensible to most human beings). An advantage to using this particular form of the READ 
statement is that no conversion is required between the internal binary representation of the values and their 
textual (human-readable) form (which means it takes less computer time to process the data). 

Notes: 

1. The REC= specifier may not be used when list-directed output is specified. 

2. If no input list is specified then the effect of the READ statement is to skip one or more records in 
the file. 

3. An implication of point (5) above is that nesting of implied-DO lists is permitted. For example, 
the input list 

( (A(I,J), B(I,J), J = 1, 5), I = 1, 10 ) 

may be broken down into the following components: 

A (I, J) , B (I, J) 

(_dlistl_, J = 1, 5) 

( .dlist2., 1 = 1, 10 ) 

For more information on input/output, see the chapter entitled "Input/Output" on page 215. For more 
information on formatted input/output, see the chapter "Format" on page 225. 
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2.70 REAL Statement 


The REAL statement is a type declaration statement and can be used to declare a name to be of type real. 
The implicit type of the name, whether defined by the "first letter rule" (see the chapter entitled "Names, 
Data Types and Constants" on page 151) or by an IMPLICIT statement, is either confirmed or overridden. 
However, once a name has been declared to be of type real, it cannot appear in another type declaration 
statement. 

There are various forms of the REAL statement. The following sections describe them. 

2.70.1 Standard REAL Statement 


REAL name [,name] ... 


where: 

name is a variable name, array name, array declarator, symbolic name of a constant, function name or 
dummy procedure name. 

This form is the standard form of the REAL statement. 

Example: 

DIMENSION C (-5:5) 

REAL A, B (10), C 

In the previous example, A is defined to be a variable of type real and B and C are defined to be arrays of 
type real. 

2.70.2 Extended REAL Statement: Length Specification 


REAL[*len[,]] name [,name] ... 


where: 

name is one of the following forms: 
v [ *len] 
a [ *len] (d) 
a(d)[*len] 

v is a variable name, array name, symbolic name of a constant, function name or dummy 

procedure name. 
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a is an array name. 

(d) is that part of the array declarator defining the dimensions of the array. 

len is called the length specification and is an unsigned positive integer constant or an integer 

constant expression enclosed in parentheses whose value is 4 or 8. 

This form of the REAL statement is a Open Watcom FORTRAN 77 extension to the FORTRAN 77 
language. The length specification specifies the number of bytes of storage that will be allocated for the 
name appealing in the REAL statement. The default length specification is 4. A length specification of 8 
specifies that the data type of the name appearing in the REAL statement is to be double precision. 

The length specification immediately following the word REAL is the length specification for each entity in 
the statement not having its own length specification. If a length specification is not specified the default 
length specification is used. An entity with its own specification overrides the default length specification 
or the length specification immediately following the word REAL . Note that for an array the length 
specification applies to each element of the array. 

Example: 

DIMENSION C (-5:5) 

REAL A, B*8 (10), C*8 
REAL*8 X 

In the previous example, X is declared to be a variable of type double precision, A is declared to be a 
variable of type real and B and C are declared to be arrays of type double precision. 

2.70.3 Extended REAL Statement: Data Initialization 


REAL[*len[,]] name [/cl/] [,name[/cl/]] ... 


where: 


name 

is as described in the previous section. 

len 

is as described in the previous section. 

cl 

is a list of the form: 


k [,k] ... 

k 

is one of the forms: 


c 

r*c (equivalent to r successive appearances of c) 
c is a constant or the symbolic name of a constant 

r is an unsigned positive integer constant or the symbolic name of a constant. 
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This form of the REAL statement is an extension to the FORTRAN 77 language. The rules for data 
initialization are the same as for the DATA statement. 

Example: 

REALA/1.2/, B(10)/10*5.0/ 

In the previous example, A is initialized with the real constant 1 . 2 and each element of the array B is 
initialized with the real constant 5.0. 
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2.71 RECORD Statement 


RECORD /typename/ name [,name] ... 


where: 

typename is the name of a user-defined structure type. 

name is a variable name, array name, array declarator, function name or dummy procedure 

name. 


The RECORD statement is used to assign a structure type to a variable. 


Example: 

STRUCTURE /ADDRESS/ 

CHARACTER*20 STREET 
CHARACTER*15 CITY 
CHARACTER*20 STATE 
CHARACTER*20 COUNTRY 
CHARACTER*10 ZIP_ CODE 
END STRUCTURE 

STRUCTURE /PEOPLE/ 

CHARACTER*20 NAME 
RECORD /ADDRESS/ ADDR 
INTEGER*2 AGE 
END STRUCTURE 

RECORD /PEOPLE/ CUSTOMER 

CUSTOMER%NAME = 'John Doe' 
CUSTOMER%ADDR%STREET = '22 Main St.' 
CUSTOMER%ADDR%CITY = 'Smallville' 
CUSTOMER%ADDR%STATE = 'Texas' 
CUSTOMER%ADDR%COUNTRY = 'U.S.A.' 
CUSTOMER%ADDR%ZIP_ CODE = '78910-1203' 
CUSTOMER%AGE =23 


For more information, see the chapter entitled "Structures, Unions and Records" on page 167. 
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2.72 REMOTE BLOCK Statement 


REMOTE BLOCK name 


where: 

name is a valid FORTRAN symbolic name. 

The REMOTE BLOCK statement is used to define a block of statements which may be executed by an 
EXECUTE statement. A REMOTE-block must be defined in the program unit in which it is used and is 
terminated by an END BLOCK statement. A REMOTE-block is similar in concept to a subroutine, with the 
advantage that shared variables do not need to be placed in a common block or passed in an argument list. 
When execution of the REMOTE-block is complete, control returns to the statement following the 
EXECUTE statement which invoked it. 


This feature is helpful in avoiding duplication of code for a common sequence of statements required in a 
number of places throughout a program. It can also be an aid to writing a well structured program. This 
feature can be mimicked using the ASSIGN and assigned GO TO statements. However, statement numbers 
must be introduced which could lead to errors. 

Each REMOTE-block must have a different name and it must not be a subprogram or variable name. Note 
that a REMOTE-block is local to the program unit in which it is defined and may not be referenced 
(executed) from another program unit. 

Note that the nested definition of REMOTE-blocks is not permitted. 


Example: 

EXECUTE INCR 
PRINT *, 'FIRST' 
EXECUTE INCR 
PRINT *, 'SECOND' 


REMOTE BLOCK INCR 
1 = 1 + 1 

PRINT *, 'I=',I 

END BLOCK 

Both EXECUTE statements will cause REMOTE-block INCR to be executed. That is, variable I will be 
incremented and its value will be printed. When the block has been executed by the first EXECUTE 
statement, control returns to the PRINT statement following it and the word FIRST is printed. Similarly, 
when the block is executed by the second EXECUTE statement, control returns to the PRINT statement 
following it and the word SECOND is printed. 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.73 RETURN Statement 


RETURN [e] 


where: 

e is an integer expression. 

A RETURN statement is used to terminate execution of a subprogram and return control to the program unit 
that referenced it. As an extension to FORTRAN 77, Open Watcom FORTRAN 77 permits the use of the 
RETURN statement in the main program. When a RETURN statement is executed in the main program, 
program execution terminates in the same manner as the STOP or END statement. 

The expression e is not permitted when returning from an external function subprogram (or main program); 
it can only be specified when returning from a subroutine subprogram. 


Example: 

FUNCTION ABS( A ) 

ABS = A 

IF( A .GE. 0 )RETURN 

ABS = -A 

RETURN 

END 


For more information, see the chapter entitled "Functions and Subroutines" on page 243. 
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2.74 REWIND Statement 


REWIND u 
REWIND (alist) 


where: 

u is an external unit identifier. 

alist is a list of rewind specifiers separated by commas: 

[UNIT =] u 
IOSTAT = ios 
ERR = s 

Execution of a REWIND statement causes the file connected to the specified unit to be positioned at the 
beginning (or before the first record) of the file. 

Rewind Specifiers 

[UNIT =] u 

u is an external unit identifier. An external unit identifier is a non-negative integer 
expression. If the optional UNIT= specifier is omitted then the specifier must be the first 
item in the list of specifiers. 

IOSTAT = ios 

is an input/output status specifier. The integer variable or integer array element ios is 
defined with zero if no error condition exists or a positive integer value if an error condition 
exists. 

ERR = s 

is an error specifier and s is a statement label. When an error occurs, execution is 
transferred to the statement labelled by s . 

Example: 

LOOP 

READ( UNIT=7, END=100, FMT=2 00 )RECORD 
PRINT *, RECORD 
ENDLOOP 

100 REWIND( UNIT=7 ) 

LOOP 

READ( UNIT=7, END=101, FMT=2 00 )RECORD 
WRITE( UNIT=8, FMT=200 )RECORD 
ENDLOOP 

101 CONTINUE 


In the previous example, we illustrate how one might process the records in a file twice. After reaching the 
endfile record, a REWIND statement is executed and the file is read a second time. 
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Notes: 

1. The unit must be connected for sequential access. 

2. If the file is positioned at the beginning of the file then the REWIND statement has no effect. 

3. It is permissible to rewind a file that does not exist but it has no effect. 

For more information on input/output, see the chapter entitled "Input/Output" on page 215. 
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2.75 SAVE Statement 


SAVE [a [,a] 


where: 

a is a named common block preceded and followed by a slash (V), a variable name or an array name. 

The SAVE statement is used to retain the value of an entity after the execution of a RETURN or END 
statement in a subprogram. Upon re-entry to the subprogram, the entity will have the same value it had 
when exit was made from the subprogram. However, an entity belonging to a common block that has 
appeared in a SAVE statement may become redefined in another program unit. 

Notes: 

1. A name cannot appear in a SAVE statement more than once in the same program unit. 

2. Dummy arguments, procedure names and names belonging to a common block are not permitted 
in a SAVE statement. 

3. A SAVE statement with no list is identical to a SAVE statement containing all allowable names in 
a program unit. 

4. A common block name appearing in a SAVE statement has the same effect of specifying all 
names belonging to that common block in the SAVE statement. 

5. If a named common block is specified in a SAVE statement in a subprogram, it must be specified 
in a SAVE statement in every subprogram in which that common block appears. Furthermore, 
upon executing a RETURN or END statement, the current values of the entities in that common 
block are made available to the next program unit executed in which that common block appears. 

6. If a named common block is specified in a SAVE statement in the main program unit, the current 
values of the entities in that common block are made available to every subprogram that 
specifies that common block. In this case, a SAVE statement has no effect in the subprogram. 

In the following example, the subroutine BLKINIT initializes the entities of the common block BLK and 
uses a SAVE statement to ensure that their values are made available to subroutine BLKPRT . 

Example: 
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PROGRAM MAIN 


CALL BLKINIT 
CALL BLKPRT 


END 

SUBROUTINE BLKINIT 
COMMON /BLK/ A, B, C 
SAVE /BLK/ 

A = 1.0 
B = 2.0 
C = 3.0 
END 

SUBROUTINE BLKPRT 
COMMON /BLK/ A, B, C 
SAVE /BLK/ 

PRINT *, A, B, C 
END 
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2.76 SELECT Statement 


SELECT [CASE] (e) [FROM] [: block-label] 


The SELECT statement is used in conjunction with the CASE and END SELECT statements. The form of 
a SELECT block is as follows: 

SELECT [CASE] (e) [FROM] [: block-label] 

CASE ( case-list ) 
statement (s) 

CASE ( case-list ) 
statement (s) 


CASE ( case-list ) 
statement (s) 

CASE DEFAULT 

statement(s) 

END SELECT 

where: 

e is an integer expression. 

case-list is a list of one or more cases separated by commas. A case is either 

(a) a single integer, logical or character constant expression or 

(b) an integer, logical or character constant expression followed by a colon 
followed by another expression or the same type. This form of a case 
defines a range of values consisting of all integers or characters greater 
than or equal to the value of the expression preceding the colon and less 
than or equal to the value of the expression following the colon. 

The CASE and FROM keywords are optional in the SELECT statement. An optional block label may be 

specified with the SELECT statement. 

The case expression e is evaluated and if the result is equal to one of the values covered by case-list 

then the control of execution is transferred to the associated CASE block. 
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Example: 


SELECT CASE 
CASE ( 'a' : 

PRINT *, 
CASE ( 'A' : 

PRINT *, 
CASE ( 'O' : 

PRINT *, 
CASE DEFAULT 
PRINT *, 
END SELECT 


( CH ) 

' z' ) 

'Lower case 

' Z' ) 

'Upper case 
' 9' ) 

'Digit' 


letter' 

letter' 


'Special character' 


In the above example, if the character CH is not a letter or digit then the CASE DEFAULT block is 
executed. 

The CASE DEFAULT statement is optional. If it is present and the case expression is out of range (i.e., no 
CASE blocks are executed) then the CASE DEFAULT block is executed. If it is not present and the case 
expression is out of range then execution continues with the first executable statement following the END 
SELECT statement. The CASE DEFAULT block must follow all other CASE blocks. 


Example: 

SELECT CASE ( I ) 

CASE ( 1 ) 

Y = Y + X 

X = X * 3.2 
CASE ( 2 ) 

Z = Y* *2 + X 
CASE ( 3 ) 

Y = Y * 13. + X 
X = X - 0.213 

CASE ( 4 ) 

Z = X**2 + Y**2 - 3.0 

Y = Y + 1.5 
X = X * 32.0 

CASE DEFAULT 

PRINT *, 'CASE is not in range' 

END SELECT 
PRINT *, X, Y, Z 

In order to retain compatibility with earlier versions of WATCOM FORTRAN 77 compilers, the 
OTHERWISE statement may be used in place of the CASE DEFAULT statement. 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.77 STOP Statement 

STOP [n] 


where: 

n is a character constant or an unsigned integer constant of no more than five digits. 

Open Watcom FORTRAN 77 allows n to be any unsigned integer constant. 

Execution of a STOP statement causes termination of execution of the program. A STOP statement may 
appear in any program unit (although good programming practice suggests that the main program is the 
proper place for this statement). 

Example: 

STOP 943 

The three digit number 94 3 is displayed on the console prior to program termination. 

Example: 

STOP 'Finished at last' 

The character string 

Finished at last 

is displayed on the console prior to program termination. 
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2.78 STRUCTURE Statement 


STRUCTURE /typename/ 


where: 


typename is the name for a new, compound variable, data type. 

The STRUCTURE statement is used in conjunction with the END STRUCTURE declarative statement. The 
STRUCTURE statement marks the start of a structure definition. 

The STRUCTURE statement defines a new variable type, called a structure. It does not declare a specific 
program variable. The RECORD statement is used to declare variables and arrays to be of this particular 
structure type. 

Structures may be composed of simple FORTRAN types or more complex structure types. This is shown 
in the following example. 


Example: 


STRUCTURE /ADDRESS/ 

CHARACTER*20 STREET 
CHARACTER*20 CITY 
CHARACTER*20 STATE 
CHARACTER*20 COUNTRY 
CHARACTER*10 ZIP_ CODE 
END STRUCTURE 


STRUCTURE /PEOPLE/ 

CHARACTER*20 NAME 
RECORD /ADDRESS/ ADDR 
INTEGER*2 AGE 
END STRUCTURE 

RECORD /PEOPLE/ CUSTOMER 


Element names are local to the structure in which they appear. The same element name can appear in more 
than one structure. Nested structures may have elements with the same name. A particular element is 
specified by listing the sequence of elements required to reach the desired element, separated by percent 
symbols (%) or periods (.). 


Example: 

CUSTOMER%NAME = 'John Doe' 
CUSTOMER%ADDR%STREET = '22 Main St.' 
CUSTOMER%ADDR%CITY = 'Smallville' 
CUSTOMER%ADDR%STATE = 'Texas' 
CUSTOMER%ADDR%COUNTRY = 'U.S.A.' 
CUSTOMER%ADDR%ZIP_ CODE = '78910-1203' 
CUSTOMER%AGE =23 


For more information, see the chapter entitled "Structures, Unions and Records" on page 167. 
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2.79 SUBROUTINE Statement 


SUBROUTINE sub [( [d [, d] ...] )] 


where: 


sub is a symbolic name of a subroutine subprogram. 

d is a variable name, array name, dummy procedure name or an asterisk (*). d is called a dummy 

argument. 

A SUBROUTINE statement is used to define the start of a subroutine subprogram. 


Example: 


CALL TMAX3( -1.0, 12.0, 5.0 ) 

END 

SUBROUTINE TMAX3( ARGA, ARGB, ARGC ) 
THEMAX = ARGA 

IF( ARGB .GT. THEMAX ) THEMAX = 
IF ( ARGC .GT. THEMAX ) THEMAX = 
PRINT *, THEMAX 

END 


ARGB 

ARGC 


In the above example, the subroutine TMAX3 is defined to find and print out the maximum value of three 
real variables. 


Notes: 

1. No dummy arguments need be specified in the SUBROUTINE statement. If such is the case, the 
parentheses () are optional. 

For more information, see the chapter entitled "Functions and Subroutines" on page 243. 
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2.80 UNION Statement 


UNION 


The UNION statement is used in conjunction with the END UNION declarative statement. The UNION 
statement marks the start of a series of MAP structures. A UNION block must contain at least two MAP 
structures. A UNION block permits the mapping of the same storage in several different ways. 

The following example maps out a 4-byte integer on an Intel 80x86-based processor. 


Example: 

STRUCTURE /MAPINT/ 
UNION 


MAP 


INTEGER* 4 

LONG 

END 

MAP 


MAP 


INTEGER*2 

LO_ WORD 


INTEGER*2 

HI_ WORD 

END 

MAP 


MAP 


INTEGER*1 

BYTE_ 0 


INTEGER*1 

BYTE_ 1 


INTEGER*1 

BYTE_2 


INTEGER*1 

BYTE_ 3 

END 

MAP 



END UNION 
END STRUCTURE 

RECORD /MAPINT/ I 

I%LONG = '01020304'x 

PRINT ’ (2Z4 ) ’ , I%LO_ WORD, I%HI_ WORD 
END 

For more information, see the chapter entitled "Structures, Unions and Records" on page 167. 
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2.81 UNTIL Statement 


UNTIL (e) 


where: 

e is a logical expression or integer arithmetic expression, in which case the result of the integer 
expression is compared for inequality to the integer value 0. 

The UNTIL statement is used in conjunction with the structured LOOP or block WHILE statement. The 
LOOP or block WHILE statement marks the beginning of a sequence of statements which are to be repeated. 
The UNTIL statement marks the end of the loop. The LOOP-block or WHILE-block is executed until 
control is transferred out of the block or the logical expression of the UNTIL statement has a true value. 

Example: 

X = 1.0 
LOOP 

PRINT *, X, SQRT( X ) 

X = X + 1.0 
UNTIL( X .GT. 10.0 ) 

Example: 

1 = 1 

WHILE( I .LT. 100 )DO 
J = 4 * I * I 
K = 3 * I 

PRINT *, '4x**2 + 3x + 6 = ' , J + K+ 6 
1 = 1 + 1 

UNTIL( (J+K+6 ) .GT. 100 ) 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.82 VOLATILE Statement 


VOLATILE [a [,a] ...] 


where: 

a is a variable name or an array name. 

The VOLATILE statement is used to indicate that a variable or an element of an array may be updated 
concurrently by other code. A volatile variable or array element will not be cached (in a register) by the 
code generator. Each time a volatile variable or array element is referenced, it is loaded from memory. 
Each time a volatile variable or array element is updated, it is stored back into memory. 

Notes: 

1. A name cannot appear in a VOLATILE statement more than once in the same program unit. 

2. Dummy arguments, procedure names, and common block names are not permitted in a 
VOLATILE statement. 

In the following example, the subroutine A_ THREAD waits on theHoldThreads semaphore. It uses the 
VOLATILE statement to ensure that the variable is re-loaded from memory each time through the loop. 


Example: 

SUBROUTINE A_ THREAD() 


STRUCTURE /RTL 
INTEGER*4 
INTEGER*4 
INTEGER*4 
INTEGER*4 
INTEGER*4 
INTEGER*4 
END STRUCTURE 


_ CRITICAL_ SECTION/ 

Debuglnfo 

LockCount 

RecursionCount 

OwningThread 

LockSemaphore 

Reserved 


INTEGER NumThreads 
LOGICAL HoldThreads 
VOLATILE HoldThreads 

RECORD /RTL_ CRITICAL_ SECTION/ CriticalSection 
COMMON NumThreads, HoldThreads, CriticalSection 
INTEGER threadid 


WHILE( HoldThreads )DO 
CALL Sleep( 1 ) 

END WHILE 

PRINT ' (''Hi from thread '', i4)', threadid() 

CALL EnterCriticalSection( CriticalSection ) 
NumThreads = NumThreads - 1 

CALL LeaveCriticalSection( CriticalSection ) 

CALL endthreadO 

END 
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2.83 Block WHILE Statement 


WHILE (e) DO [: block-label] 


where: 

e is a logical expression or integer arithmetic expression, in which case the result of the integer 
expression is compared for inequality to the integer value 0. 

The block WHILE statement is used in conjunction with the structured END WHILE or UNTIL statement. 
The block WHILE statement marks the beginning of a sequence of statements which are to be repeated. 

The END WHILE or UNTIL statement marks the end of the WHILE-block. The WHILE-block is executed 
while the logical expression of the WHILE statement has a true value or until control is transferred out of 
the WHILE-block. 

Example: 

X = 1.0 

WHILE( X .LT. 100 )DO 

PRINT *, X, SQRT( X ) 

X = X + 1.0 
END WHILE 

Example: 

1 = 1 

WHILE( I .LT. 100 )DO 
J = 4 * I * I 
K = 3 * I 

PRINT *, ’ 4x* *2 + 3x + 6 = ', J + K+ 6 
1 = 1 + 1 

UNTIL( (J+K+6 ) .GT. 100 ) 

END 

An optional block label may be specified with the WHILE statement. 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193. 
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2.84 WHILE Statement 


WHILE (e) stmt 


where: 

e is a logical expression. 

stmt is an executable statement. Only certain executable statements are allowed. See the section 

entitled "Classifying Statements" on page 9 at the beginning of this chapter for a list of allowed 
statements. 

This form of the WHILE statement allows an executable statement to be repeatedly executed until the 
logical expression e is false. 

Example: 

1 = 0 

WHILE( I .LE. 100 ) CALL PRTSQR( I ) 

END 

SUBROUTINE PRTSQR( J ) 

PRINT *, J, J**2 

J = J + 1 

END 

In the above example, the subroutine PRTSQR is called again and again until the value of I has been 
incremented beyond 100. Note that the subroutine increments its argument thereby guaranteeing that the 
program will eventually stop execution. 

For more information, see the chapter entitled "Program Structure Control Statements" on page 193 Control 
Statements". 
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2.85 WRITE Statement 


WRITE (cilist) [olist] 


where: 

cilist is a control information list of specifiers separated by commas: 

[UNIT =] u 
[FMT =] f 
REC = rn 
IOSTAT = ios 
ERR = s 

olist is an output list. 

The WRITE statement is used to transfer data from the executing FORTRAN program to an external device 
or file. 

Control Information List 
[UNIT =] u 

u is an external unit identifier or an internal file identifier. 

1. An external unit identifier is a non-negative integer expression or an asterisk 
(*) in which case unit 6 is assumed. 

2. An internal file identifier is the name of a character variable, character array, 
character array element, or character substring. 

If the optional UNIT= specifier is omitted then the unit specifier must be the first item in 
the list of specifiers. 


[FMT =]f 

f is a format identifier. A format identifier is one of the following: 

1. A statement label of a FORMAT statement that appears in the same program unit 
as the format identifier. 

2. An integer variable name that has been assigned the statement label of a 
FORMAT statement that appears in the same program unit as the format identifier 
(see the ASSIGN statement). 

3. An integer array name. 

4. A character array name. 

5. Any character expression except one involving the concatenation of an operand 
whose length specification is (*) unless the operand is a symbolic constant (see 
the PARAMETER statement). 

6. An asterisk (*) , indicating list-directed formatting. 

7. A NAMELIST name, indicating namelist-directed formatting. 

If the optional FMT= specifier is omitted then the format specifier must be the second item 
in the list of specifiers and UNIT= must not be specified for the first item in the list. 
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REC = rn 

rn is an integer expression whose value must be positive. It is the number of the record to 
be written when a file is connected for direct access. 

IOSTAT = ios 

is an input/output status specifier. The integer variable or integer array element ios is 
defined with zero if no error condition occurs or a positive integer value if an error 
condition occurs. 

ERR = s 

is an error specifier and s is a statement label. When an error occurs, execution is 
transferred to the statement labelled by s . 

Output list - An output list may contain one or more of the following: 

1. A variable name. 

2. An array element name. 

3. A character substring name. 

4. An array name except an assumed-size dummy array. 

5. Any other expression except a character expression involving concatenation of an operand 
whose length specification is an asterisk in parentheses unless the operand is the symbolic name 
of a constant (since the length can be determined at compile time). 

6. An implied-DO list of the form: 

( dlist, i = el, e2 [,e3] ) 

where dlist is composed of one or more of items (1) through (6). 

Example: 

WRITE( 6, 100 )X, Y, Z 

WRITE( UNIT=6, FMT=100 )X, Y, Z 

100 FORMAT( 3F10.5 ) 

WRITE( UNIT=6, FMT='( 3F10.5 )' )X, Y, Z 

WRITE( 6, '( 3F10.5 )' )X, Y, Z 

The above gives four examples of formatted WRITE statements. In all cases, the format conversion is 
identical but it was specified in different ways. When executed, the effect of all WRITE statements is the 
same. The unit number, used here, is 6. There are, in fact, many other ways in which the WRITE statement 

could have been written, all of which would have the same effect when executed. We have not shown use 

of all the specifiers. 

Example: 

WRITE( 6, * )X, Y, Z 

WRITE( *, * )X, Y, Z 

WRITE( UNIT=6, FMT=* )X, Y, Z 

WRITE( UNIT=*, FMT=* )X, Y, Z 

The above four examples of list-directed formatted output are all equivalent. Open Watcom FORTRAN 77 
assumes unit 6 when the unit number identifier is an asterisk (as in the second and fourth examples). In the 
examples, the format identifier is an asterisk indicating list-directed formatting. 
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Example: 

WRITE( 8 )X, Y, Z 
WRITE( UNIT=8 ) X, Y, Z 

The above gives two examples of unformatted WRITE statements. The unit number used in the example is 
8. When executed, the effect of both of these statements is the same. The values of the variables X, Y and 
Z are written to the file connected to unit 8 in their binary form (a form quite incomprehensible to most 
human beings). An advantage to using this particular form of the WRITE statement is that no conversion is 
required between the internal binary representation of the values and their textual (human-readable) form 
(which means it takes less computer time to process the data). 

Notes: 

1. If no output list is specified then the effect of the WRITE statement is to produce a record whose 
characters are all blanks. 

2. The REC= specifier may not be used when list-directed output is specified. 

3. An implication of point (6) above is that nesting of implied-DO lists is permitted. For example, 
the output list 

( (A (I , J) , B (I, J) , J = 1, 5), I = 1, 10 ) 

may be broken down into the following components: 

A(I,J), B (I, J) 

(_dlistl_, J = 1, 5) 

( .dlist2., 1 = 1, 10 ) 

For more information on input/output, see the chapter entitled "Input/Output" on page 215. For more 
information on formatted input/output, see the chapter entitled "Format" on page 225. 
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3 Names, Data Types and Constants 


3.1 Symbolic Names 

Symbolic names are names that represent variables, arrays, functions, etc. Names are formed using any of 
the upper-case letters A-Z and the digits 0-9, the first of which must be a letter. Symbolic names are 
limited to 6 characters in length. The following are examples of symbolic names. 

AMOUNT 

AGE 

CUST73 


Open Watcom FORTRAN 77 extends the allowable characters that can make up a symbolic name to 
include the lower-case letters a-z, the dollar sign ($) and the underscore (_). Note that the dollar sign and 
the underscore are treated as letters and are therefore allowed as the first letter of a symbolic name. 
Furthermore, Open Watcom FORTRAN 77 allows symbolic names of up to 32 characters. The following 
are examples of permissible symbolic names. 

Evaluate 

$Cheque 

ComputeAverage 
_ device 
IO$ERROR 
student_ total 

Open Watcom FORTRAN 77 makes no distinction between upper and lower case letters. The following 
symbolic names are identical. 

Account 

ACCount 

ACCOUNT 


Spaces are allowed in symbolic names and are ignored. The following symbolic names are identical. 

C R E DIT 
CRE DIT 

FORTRAN 77 allows certain keywords such as WRITE to be used as symbolic names. In Open Watcom 
FORTRAN 77, all keywords satisfy the requirements of a symbolic name. A keyword is a sequence of 
letters that is interpreted in a special way by Open Watcom FORTRAN 77. Whether a string of characters 
is interpreted as a keyword or as a symbolic name depends on the context in which it is used. In the 
following example, the first statement is an assignment statement assigning the value 2 to the symbolic 
name DOl 0 1. The second statement is the beginning of a DO-loop. 
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Example: 

DO10I=l 
DO10I=l,10 


3.2 Data Types 

There are 6 basic data types in FORTRAN 77; logical, integer, real, double precision, complex and 
character. Open Watcom FORTRAN 77 provides an additional data type, namely double precision 
complex ( DOUBLE COMPLEX or COMPLEX*16). Open Watcom FORTRAN 77 also supports the 
creation of more complex user-defined data types using the STRUCTURE statement. 

Each data type can be classified as numeric, logical or character. Each datum occupies a sequence of 
storage units. Numeric data and logical data occupy numeric storage units whereas character data occupy 
character storage units. In Open Watcom FORTRAN 77, a numeric storage unit occupies 4 bytes and a 
character storage unit occupies 1 byte. 

The following table summarizes all data types supported by Open Watcom FORTRAN 77. 


Data Type 

Size 

(in bytes) 

Standard 

FORTRAN 

LOGICAL 

4 

yes 

LOGICAL* 1 

1 

extension 

LOGICAL*4 

4 

extension 

INTEGER 

4 

yes 

INTEGER* 1 

1 

extension 

INTEGER*2 

2 

extension 

INTEGER*4 

4 

extension 

REAL 

4 

yes 

REAL*4 

4 

extension 

REAL *8 

8 

extension 

DOUBLE PRECISION 

8 

yes 

COMPLEX 

8 

yes 

COMPLEX *8 

8 

extension 

DOUBLE COMPLEX 

16 

extension 

COMPLEX* 16 

16 

extension 

CHARACTER 

1 

yes 

CHARACTER*!! 

n 

yes 


Detailed information on the size and range of values supported by each of these data types is provided in 
the User’s Guide. 


3.3 Data Type of a Name 

A name must only have one data type. Its type is specified by the appearance of that name in a type 
statement. If a name does not appear in any type statement then an implied type is assigned to it by the 
"first letter rule". A name not appearing in any type statement and beginning with any of the letters I, J, K, 
L, M or N is assigned the type integer. A name not appearing in any type statement and beginning with any 
other letter is assigned the type real. The implied type of a letter can be changed by an IMPLICIT 
statement. 
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The type associated with a name defines the type of the data it is to contain. For example, if A is of type 
integer, then the storage unit which A occupies is assumed to contain integer data. Note that the data type 
of an array element is the same as the data type associated with the array name. 

The data type of a function name specifies the type of the result returned by the function when it is 
referenced. A name that identifies a specific intrinsic function has type as specified in the chapter entitled 
"Functions and Subroutines" on page 243. A generic function name has no type associated with it; its type 
is determined by the type of its argument(s). The appearance of a generic function in a type statement is 
not sufficient to remove the generic properties of that name. For example, if SIN was declared to be of type 
real, it could still be called with an argument of type complex. The type of an external function reference is 
determined in the same way as for variables and arrays. The actual type of the external function is 
determined implicitly by its name or explicitly by its appearance in a FUNCTION or type statement. Note 
that an IMPLICIT statement can affect the type of the external function being defined. 


3.4 Constants 


A constant can be one of arithmetic, logical or character. Each constant has a data type and value 
associated with it and, once established in a program, cannot be changed. Arithmetic constants consist of 
those constants whose data type is one of integer, real, double precision, complex or double precision 
complex. Logical constants consist of those constants whose data type is logical and character constants 
consist of those constants whose data type is character. The string of characters representing a constant 
determines its value and data type. The blank character is insignificant for all but character constants. 

3.4.11nteger Constants 

An integer constant is formed by a non-empty string of digits preceded by an optional sign. 

The following are examples of integer constants. 

1423 
+ 345 

-34565788 

3.4.2 Real Constants 

We first define a simple real constant as follows: an optional sign followed by an integer part followed by 
a decimal point followed by a fractional part. The integer and fractional parts are non-empty strings of 
digits. Either can be omitted but not both. 

A real constant has one of the following forms. 

1. A simple real constant. 

2. A simple real constant followed by an E followed by an optionally signed integer constant. 

3. An integer constant followed by an E followed by an optionally signed integer constant. 

The optionally signed integer constant that follows the E is called the exponent. The value of a real 
constant that contains an exponent is the value of the constant preceding the E multiplied by the power of 
ten determined by the exponent. 

The following are examples of real constants. 
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123.764 
.4352344 
1423.34E12 
+345.E-4 
-.4565788E3 
2E6 
1234 . 


3.4.3 Double Precision Constant 


A double precision constant has one of the following forms. 

1 . A simple real constant followed by a D followed by an optionally signed integer constant. 

2. An integer constant followed by a D followed by an optionally signed integer constant. 

The optionally signed integer constant that follows the D is called the exponent. The value of a double 
precision constant that contains an exponent is the value of the constant preceding the D multiplied by the 
power of ten determined by the double precision exponent. Note that the resulting approximation is of 
greater precision than the equivalent real constant. The approximations may be of equal precision if the 
approximations are exact representations. For example, 0D0 and 0E0 are double and single precision 
constants respectively, both representing zero with the same precision. 

The following are examples of double precision constants. 

1423.34D12 
+345.D-4 
-. 4565788D5 
2D6 


3.4.4 Complex Constant 

A complex constant consists of a left parenthesis, followed by a real or integer constant representing the 
real part of the complex constant, followed by a comma, followed by a real or integer constant representing 
the imaginary part of the complex constant, followed by a right parenthesis. 

The following are examples of complex constants. 

( 1423.34E12, 3 ) 

( +345, 4 ) 

3.4.5 Double Precision Complex Constant (Extension) 

A double precision complex constant has the same form as a complex constant except that at least one of 
the real and imaginary parts must be a double precision constant. 

The following are examples of double precision complex constants. 

( 1423.34D12, 3 ) 

( +345, 4D2 ) 
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3.4.6 Logical Constant 

A logical constant can have one of the following forms. 

1 . . TRUE . representing the value true. 

2. . FALSE . representing the value false. 

3.4.7 Character Constant 

A character constant consists of an apostrophe followed by any string of characters followed by an 
apostrophe. The apostrophes are not part of the datum. If an apostrophe is to appear as part of the datum it 
must be followed immediately by another apostrophe. Note that blanks are significant. The length of the 
character constant is the number of characters appearing between the delimiting apostrophes. Consecutive 
apostrophes in a character datum represent one character, namely the apostrophe. A character constant 
must not have length 0. 

The following are examples of character constants. 

'ABCDEFG1234567' 

'There''s always tomorrow' 

3.4.8 String Constant (Extension) 


A string constant consists of an apostrophe followed by any string of characters followed by an apostrophe 
and then the letter C or c . The apostrophes are not part of the datum. The datum is stored in memory with 
a terminating NUL character (CHAR(O)). If an apostrophe is to appear as part of the datum it must be 
followed immediately by another apostrophe. Note that blanks are significant. The length of the string 
constant is the number of characters appearing between the delimiting apostrophes plus one for the 
terminating NUL character (CHAR(O)). Consecutive apostrophes in a string datum represent one character, 
namely the apostrophe. A string constant must not have length 0. A string constant may be used anywhere 
a character constant may be used. 

The following are examples of string constants. 

'Hello there'C 
'There''s always tomorrow'c 
'The result for %s=%d'c 


3.4.9 Hollerith Constants (Extension) 


A Hollerith constant consists of a positive unsigned integer constant n followed by the letter H or h 
followed by a string of exactly n characters. The actual data is the n characters following the letter H or h . 
A hollerith constant is another way of representing character data. 
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Actually, hollerith constants are treated as character constants and can be used wherever a character 
constant can be used. Hollerith constants are different from character constants in that a quote is 
represented by two quotes in character constants and by a single quote in hollerith constants. 

The following are examples of hollerith constants. 

5HABCDEFG 
lOh xxxxx '4 4 


3.4.10 Hexadecimal Constants (Extension) 


Two forms of hexadecimal constant are supported. The first form can only be used in type declaration or 
DATA statements. The second form may be used anywhere an integer constant may be used. 

The first form of hexadecimal constant consists of the letter Z or z followed by a suing of hexadecimal 
digits. A hexadecimal digit can be any digit or one of the letters A, B, C, D, E or F (the lower case of 
these letters is also acceptable). The actual data is the hexadecimal digits following the letter Z or z . 
Hexadecimal constants of this form can only be used in type declaration statements and DATA statements 
for initializing memory with binary patterns. 

The following are examples of the first form of hexadecimal constant. 

zl234 

Zac 

The first example is equivalent to the binary pattern 0001 0010 0011 0100. The second example is 
equivalent to the binary pattern 1010 1100. 

The second form of hexadecimal constant consists of an apostrophe followed by any suing of hexadecimal 
digits followed by an apostrophe and then the letter X or x. A hexadecimal digit can be any digit or one of 
the letters A, B, C, D, E or F (the lower case of these letters is also acceptable). The actual data is the 
hexadecimal digits placed inside apostrophes. 

The following are examples of the second form of hexadecimal constant. 

'1234'x 
'ac'X 

The first example is equivalent to the binary pattern 0001 0010 0011 0100. The second example is 
equivalent to the binary pattern 1010 1100. 

3.4.11 Octal Constants (Extension) 

An octal constant consists of an aposUophe followed by any string of octal digits followed by an 
aposttophe and then the letter 0 or o . An octal digit can be any of the digits 0 through 7. The actual data 
is the octal digits placed inside apostrophes. An octal constant may be used anywhere an integer constant 
may be used. 
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The following are examples of octal constants. 

'1234'o 
' 37'0 

The first example is equivalent to the binary pattern 001 010 011 100. The second example is 
equivalent to the binary pattern Oil 111. 


3.5 Symbolic Constants 

It is possible to give a constant a symbolic name. This is done through PARAMETER statements. For more 
details, see the section on the PARAMETER statement in the chapter entitled "FORTRAN Statements" on 
page 9. 
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4 Arrays 


4.1 Introduction 


An array is a non-empty collection of data. Arrays allow a convenient way of manipulating large quantities 
of data. An array can be referenced as an entity. In this way it is possible to conveniently pass large 
quantities of data between subprograms. Alternatively, it is possible to reference each element of an array 
individually so that data can be selectively processed. Consider the task of managing the marks of 100 
students. Without arrays one would have to have a unique name for each mark. They might be Ml, M2, 
etc. up to M100. This is clearly cumbersome. Instead, we can use an array called MARKS containing 100 
elements. Now there is one name for all the marks. Each mark can be referenced by using that name 
followed by a subscript. Furthermore, suppose the size of the class doubled. Do we add the names M101, 
M102, etc. up to M200? Not if we use arrays. If the size of the class doubled, all that need be done is to 
define the array to contain 200 elements. It is not hard to see that programs that use arrays tend to be 
general in nature. Arrays also facilitate the repetitive computations that must be performed on large 
amounts of data in that they lend themselves to loop processing. 

4.2 Properties of Arrays 

Arrays are defined by an array declarator. The form of an array declarator is: 


a ( d [, d] . . . ) 


where: 

a is the symbolic name of the array 
d is a dimension declarator. 

The number of dimensions of the array is determined by the number of dimension declarators appearing in 
the array declarator. Allowable dimensions for arrays range from 1 to 7. A 1-dimensional array can be 
viewed as a vector, a 2-dimensional array as a matrix and a 3-dimensional array as a number of parallel 
matrices. Arrays with dimension higher than 3 are generally difficult to intuitively describe and hence 
examples will deal with arrays whose dimension is 1, 2 or 3. 

Each dimension has a range of values. When referencing elements in that dimension, the dimension 
expression must fall in that range. The range of a dimension is defined in the dimension declarator. A 
dimension declarator has the following form: 
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[lo:] hi 


where: 

lo is the lower dimension bound. 
hi is the upper dimension bound. 

The lower and upper dimension bounds must be integer expressions and the upper dimension bound must 
be greater than or equal to the lower dimension bound. The upper dimension bound of the last dimension 
may be an asterisk (*) . The meaning of this will be discussed later. If the lower dimension bound is not 
specified then a default of 1 is assumed. The size of a dimension is defined as hi - lo + 1. Note that if 
the lower dimension bound is not specified the size of the dimension is just hi . The size of the array (or 
the number of elements in the array) is defined as the product of all the sizes of the dimensions of the array. 
The maximum number of elements in any dimension is limited to 65535. The maximum size of an array is 
limited by the amount of available memory. 

Arrays are defined by the appearance of an array declarator in a DIMENSION statement, a type statement 
or a COMMON statement. 

Example: 

DIMENSION A(10), B(-5:5,-10:10) 

INTEGER C(10,20) 

COMMON /DATA/ X,Y(30,30),Z 

In the previous example, B is a 2-dimensional array with 11 rows and 21 columns and has 231 elements 
(i.e. 11*21). 

Each array has a data type associated with it. This data type is inherited by all elements of the array. 


4.3 Array Elements 

Each array is comprised of a sequence of array elements. An array element is referenced by following the 
array name with a subscript. Different elements of the array are referenced by simply changing the 
subscript. An array element has the following form: 


a(s[, s] . . .) 


where: 


a 

is the array name. 

(s[,s]„.) 

is a subscript. 

s 

is a subscript expression. 
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Each subscript expression must be an integer expression and must be in the range defined by the upper and 
lower dimension bounds of the corresponding dimension. The number of subscript expressions must be 
equal to the dimension of the array. 

If an array has n elements then there is a 1-to-l correspondence between the elements of the array and the 
integers from 1 to n. Each subscript has a subscript value associated with it which determines which 
element of the array is being referenced. If the subscript value is i then the ;th element of the array is the 
one referenced. The subscript value depends on the subscript expressions and on the dimensions of the 
array. The following table describes how to compute the subscript value. 


n 

Dimension 

Declarator 

Subscript 

Value 

Subscript 

i 

(J1: K1) 

(SI) 

1+(S1-J1) 

2 

(J1:K1,J2:K2) 

(S1,S2) 

1+CS1-J1) 

+(S2-J2)*D1 


(J1:K1J2:K2,J3:K3) 

(S1,S2,S3) 

1+CS1-J1) 

+(S2-J2)*D1 

+(S3-J3)*D2*D1 





n 

(Jl:Kl,...,Jn:Kn) 

(Sl,...,Sn) 

1+CS1-J1) 

+(S2-J2)*D1 

+(S3-J3)*D2*D1 

+ 

+(Sn-Jn)*Dn-l*Dn-2*...*Dl 


Notes: 

1. n is the number of dimensions, 1 <= n <= 7. 

2. Ji is the value of the lower bound of the i’th dimension. 

3. Ki is the value of the upper bound of the i’th dimension. 

4. If only the upper bound is specified, then li = 1 

5. Si is the integer value of the i’th subscript expression. 

6. Di = Ki-Ji+1 is the size of the i’th dimension. If the value of the lower bound is 1, then Di = Ki. 

7. A subscript of the form (Jl,...,Jn) has subscript value 1 and identifies the first element of the 
array. A subscript of the form (Kl,...,Kn) has subscript value equal to the size of the array and 
identifies the last element of the array. 
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4.4 Classifying Array Declarators by Dimension Declarator 

Array declarators can be classified according to the characteristics of the dimension declarator. The 
following sections discuss the three classifications. 


4.4.1 Constant Array Declarator 

A constant array declarator is one in which each of the dimension bound expressions is an integer constant 
expression. It is called a constant array declarator because the dimension bound expressions can never 
change. In the following example both A (10) and B (-5:5) are constant array declarators. 

Example: 

SUBROUTINE SQUARE( A ) 

DIMENSION A(10), B(-5:5) 


END 

4.4.2 Adjustable Array Declarator 

An adjustable array declarator is one that contains at least one variable in all of its dimension bound 
expressions. It is called an adjustable array declarator because the dimension bound expressions can 
change depending on the current value of the variables in the dimension bound expressions. The array 
name must be a dummy argument. In the following example, A (M, 2*N) is an adjustable array declarator. 
If SQUARE is called with M having value 5 and N having value 10, then the array A will be a 2-dimensional 
array having 5 rows and 20 columns. 

Example: 

SUBROUTINE SQUARE( A, M, N ) 

DIMENSION A(M,2*N) 


END 

4.4.3 Assumed-size Array Declarator 

An assumed-size array declarator is a constant array declarator or an adjustable array declarator whose 
upper dimension bound of the last dimension is an asterisk (e.g., A(M,N,*)) or the integer value 1 (e.g., 
A(M,N,1)). The array name must be a dummy argument. The value of the upper bound of the last 
dimension is determined by the number of elements of the actual array argument and is computed as 
follows. First we compute the size of the dummy array. Note that this size is really an upper bound. 

1. If the corresponding actual array argument is a non-character array name, the size of the dummy 
array is the size of the actual array. 

2. If the corresponding actual array argument is a non-character array element name with a 
subscript value of r in an array of size x, the size of the dummy array is x + 1 — r. 
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3. If the corresponding actual argument is a character array name, character array element or a 
substrung character array element which begins at character 1 of an array with c characters then 
the size of the dummy array is INT(( c + 1 - t) / e) where e is the size of an element of the 
dummy array. 

If the assumed-size array has dimension n then the product of the first n— 1 dimensions must be less than or 
equal to the size of the array as determined by one of the preceding rules. The value of the assumed 
dimension is the largest integer such that the product of all of the dimensions is less than or equal to the size 
of the dummy array. In the following example, A ( 4 , *) is an assumed-size array declarator. 

Example: 

DIMENSION B(10) 


CALL SQUARE( B ) 


END 

SUBROUTINE SQUARE( A ) 
DIMENSION A(4,*) 


END 

By rule 1, the upper bound of the size of A is 10. We now look for the largest integer n such that 4 * n is 
less than or equal to 10. Clearly, n is 2. A is therefore a 2-dimensional array with 4 rows and 2 columns. 

4.4.4 Allocatable Array Declarator 

An allocatable array declarator is one that contains no dimension bound expressions. It is called an 
allocatable array declarator because the dimension bounds are specified at run-time in an ALLOCATE 
statement. 

Example: 

DIMENSION A(:), B(:,:) 


ALLOCATE( A(N) ) 

ALLOCATE( B(0:4,5) ) 

In the previous example, A ( :) is a one-dimensional allocatable array declarator and B (:, :) is a 
two-dimensional allocatable array declarator. The first ALLOCATE statement is used to allocate the array A 
with bounds 1 : N . The second ALLOCATE statement is used to allocate the array B with bounds 0 : 4 in 
the first dimension and 1: 5 in the second dimension. 
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4.5 Classifying Array Declarators by Array Name 

Array declarators can also be classified according to the characteristic of the array name. The following 
sections discuss the two classifications. 

4.5.1 Actual Array Declarator 

An actual array declarator is one in which the array name is not a dummy argument. All actual array 
declarators must also be constant array declarators. An actual array declarator is permitted in a 
DIMENSION statement, a type statement or a COMMON statement. 

4.5.2 Dummy Array Declarator 

A dummy array declarator is one in which the array name is a dummy argument and hence can only appear 
in a function or subroutine subprogram. It can be a constant, adjustable or assumed-size array declarator. 

A dummy array declarator can appear in a DIMENSION statement or a type statement but not in a COMMON 
statement. It should be noted that the array declarator for a dummy array declarator need not be the same as 
the array declarator of the corresponding actual array declarator. Also note that every array declarator in a 
main program must be a constant array declarator. 

4.6 Use of Array Names 

The appearance of an array name must always be as part of an array element name except in the following 
cases: 

1. in a list of dummy arguments. For example, a subroutine that has as one of its arguments an 
array. 

2. in a COMMON statement to define that array as belonging to a common block. 

3. in a type statement either as part of an array declarator or by itself to establish the type of the 
array. 

4. in an array declarator in a DIMENSION, type or COMMON statement. 

5. in an EQUIVALENCE statement. 

6. in a DATA statement. 

7. in the list of actual arguments when calling an external procedure. 

8. In the list of an input/output statement. 

9. as a unit identifier for an internal file in an input/output statement. 

10. as a format identifier in an input/output statement. 

11. in a SAVE statement. 
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5.1 Introduction 

A substring is a contiguous portion of a character entity. The substring operation selects a substring from a 
character entity. The resulting substring can then be treated as a character entity in itself. Substringing also 
allows the replacement of substrings from character entities with other character entities. 

5.2 Substring Names 

Substrings are formed by specifying a substring name. The forms of a substring name are: 


v( [ el] : 

: [ e2] ) 


a (s [,s] . 

■ ■) ( [el] : 

: [ e2] ) 


where: 

v is a character variable name. 

a(s[,s]...) is a character array element name. 

el is an integer expression identifying the leftmost character of the substring. 

e2 is an integer expression identifying the rightmost character of the substring, 

el and e2 are called substring expressions. They must be such that 
1 <= el <= e2 <= len 

where len is the length of the character entity. If el is omitted, a value of 1 is assumed. If e2 is omitted, 
a value of len is assumed. Both el and e2 may be omitted. The length of the substring is e2 - el + 1. 
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Example: 

CHARACTER A*8, B(4)*8, C*14 

* A gets the string 'EVERYDAY' 

A = 'EVERYDAY' 

* Replace 'DAY' with 'ONE' in A 

A ( 6 : 8) = 'ONE' 

* B(l) gets the string 'OTHELLO' 

B (1) = 'OTHELLO' 

* B(2) gets same value as B(l) 

B(2)(:) = 'OTHELLO' 

* B(3) gets last 6 characters of B(l) 

B (3) = B (1) (3:8) 

* B(4) gets first 4 characters of B(l) 

* concatenated with the letter 'R' 

B (4 ) = B (1) (1:4) // 'R' 

* C gets last 6 characters of B(l) 

* concatenated with the variable A 
C = B(l)(3:) // A 

* Print out the results 

PRINT *, A 
PRINT ' (A8) ' , B 
PRINT *, C 
END 


5.3 Extensions 


Open Watcom FORTRAN 77 allows an external character function reference or a character statement 
function reference as part of the substring name (see the chapter entitled "Functions and Subroutines" on 
page 243. for more information). 


Example: 

CHARACTER*10 F,G 
CHARACTER*10 X 

•k 

* DEFINE CHARACTER STATEMENT FUNCTION 

★ 

G (X) = X 

★ 

PRINT *, F (' 0123456789') (1:5) 
PRINT *, G('0123456789')(6:10) 
END 


* DEFINE CHARACTER EXTERNAL FUNCTION 

★ 

CHARACTER*(*) FUNCTION F( X ) 
CHARACTER*10 X 
F = X 
END 
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6.1 Structures and Records 


As an extension to the basic FORTRAN 77 types such as INTEGER, REAL, LOGICAL, etc.. Open 
Watcom FORTRAN 77 supports the creation of hierarchical, composite data types called structures. A 
structure is a template describing the form of a record. It is composed of members or fields of various 
types, including other structures. A structure does not reserve any storage. 

For example, you could describe the structure of the COMPLEX data type using the following 
construction. 


Example: 

STRUCTURE /CMPLX/ 
REAL REAL_ PART 
REAL IMAG_ PART 
END STRUCTURE 


Since the COMPLEX data type is an intrinsic type of FORTRAN, there is no need to do so. The 
STRUCTURE and END STRUCTURE statements mark the start and end of a structure definition. 


There are, however, many practical examples of collections of data that may be described using a structure. 
Consider, for example, the contents of a data record on disk. It may contain fields such as last name, first 
name, and middle initial which describe the name of a customer. Each of these fields are fixed in length. A 
sample structure declaration might be: 

STRUCTURE /NAME/ 

CHARACTER* 2 0 LAST_ NAME 
CHARACTER*20 FIRST_ NAME 
CHARACTER*1 MIDDLE_ INITIAL 
END STRUCTURE 

As we stated above, a structure does not allocate storage. Instead, we have created a new type called NAME 
which may be used to describe objects. Objects of the new type are defined using the RECORD statement. 
For example, the following statements describe two objects, STUDENT_ 1 andSTUDENT_ 2, to be of type 
NAME. 


RECORD /NAME/ STUDENT_ 1 
RECORD /NAME/ STUDENT_ 2 

There are other attributes of a person besides one’s name that could be recorded in the record. For 
example, we can also store a person’s date of birth and sex. First, let us define a DATE structure. 

STRUCTURE /DATE/ 

INTEGER*! DAY 
INTEGER*! MONTH 
INTEGER*2 YEAR 
END STRUCTURE 


Now we can describe a person in terms of name, date of birth, and sex. 
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STRUCTURE /PERSON/ 

RECORD /NAME/ NAME 
RECORD /DATE/ BIRTH_ DATE 
CHARACTER*1 SEX 
END STRUCTURE 

RECORD /PERSON/ STUDENT 


Having declared STUDENT to be of type PERSON, how do we reference the component parts of 
STUDENT? The following example illustrates this. 

S TUDENT. NAME. LAS T_ NAME = 'Pugsley' 

STUDENT . NAME . FIRST_ NAME = 'Elmar' 

STUDENT.NAME.MIDDLE_ INITIAL = 'M' 

STUDENT. BIRTH_ DATE. DAY = 21 
STUDENT. BIRTH_ DATE. MONTH = 11 
STUDENT . BIRTH_ DATE . YEAR = 195 9 
STUDENT.SEX = 'M' 


The object’s name is specified first, followed by a "." (or "%") and the structure member name. If the 
structure member is itself a record then another "." (or "%") and member name is specified. This continues 
until the desired structure member is identified. The "." or is called a field selection operator. 

The previous example contained both a structure called NAME (RECORD /NAME /) and a structure 
member called NAME (RECORD /NAME/ NAME). The structure name is enclosed within slashes ("/"). 
A structure name must be unique among structure names. However, the same name can also be used to 
name either variables or structure members (fields). Thus it is possible to have a variable named X, a 
structure named X, and one or more fields named X. 

Structure, field, and variable names are all local to the program unit in which they are defined. 

6.2 Arrays of Records 

It is often the case that the individual attributes of objects are stored in separate arrays. If, for example, 
your application deals with 1000 objects with attributes "size", "weight", and "colour", the traditional 
approach is to declare three different arrays. 

PARAMETER (MAX_ ELS=10 0 0 ) 

REAL SIZE (MAX_ ELS) 

INTEGER WEIGHT (MAX_ ELS) 

CHARACTER*2 COLOUR(MAX_ ELS) 

To read or write the attributes relating to an object, you would use a statement such as: 

READ(UNIT=3) SIZE(I), WEIGHT(I), COLOUR(I) 

Using a simple structure, we can express the problem as follows: 
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PARAMETER (MAX_ ELS=10 0 0 ) 

STRUCTURE /OBJECT/ 

REAL SIZE 

INTEGER WEIGHT 

CHARACTER*2 COLOUR 
END STRUCTURE 

RECORD /OBJECT/ ITEM(MAX_ ELS) 


To read or write the attributes relating to an object, you would use a statement such as: 
READ(UNIT=3) ITEM(I) 


6.3 Unions 


Sometimes it is useful to be able to describe parts of structures in different ways in much the same way that 
the EQUIVALENCE statement is used to describe a specific storage area in different ways. The UNION - 
END UNION statements are used to mark a section of a structure that will have alternate storage 
organizations (MAPs). The MAP - END MAP statements are used to define the start and end of an alternate 
storage map. Thus several MAP - END MAP pairs will appear between a UNION - END UNION section. 

Consider the following example. The subroutine displays the contents of a field using different names and 
formats depending on a TYPE field. 

Example: 
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SUBROUTINE PRINT_ ITEM( ITEM ) 
STRUCTURE /DATA_ MAP/ 


INTEGER 

UNION 

TYPE 


MAP 

LOGICAL 

LGL 

END 

MAP 


MAP 

INTEGER 

INT 

END 

MAP 


MAP 

REAL 

FLT 

END 

MAP 


MAP 

DOUBLE PRECISION 

DBL 

END 

MAP 



END UNION 
END STRUCTURE 

RECORD /DATA_ MAP/ ITEM 

IF( ITEM%TYPE .EQ. 1 ) THEN 
PRINT '(L2)', ITEM%LGL 
ELSEIF( ITEM%TYPE .EQ. 2 ) THEN 
PRINT '(18)', ITEM%INT 
ELSEIF ( ITEM%TYPE .EQ. 3 ) THEN 
PRINT ' (E12.5)', ITEM%FLT 
ELSEIF( ITEM%TYPE .EQ. 4 ) THEN 
PRINT ' (D12.5)', ITEM%DBL 
END IF 

END 


The organization of the record in memory is as follows: 
offset +0 +4 +8 


integer 

logical 

(slack) 


integer 

(slack) 

real 

(slack) 

double precision 


The first 4 bytes of storage are occupied by TYPE . The next 4 to 8 bytes of storage are occupied by either 
LGL, INT, FLT, or DBL depending on the interpretation of the contents of the variable TYPE. The size 
of the record ITEM is a total of 12 bytes. Based on the conventions of the above program example, only 8 
bytes of the record ITEM are used when TYPE is 1, 2, or 3. When TYPE is 4 then 12 bytes of the record 
are used. 

The following example maps out a 4-byte integer on an Intel 80x86-based processor. 
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Example: 

STRUCTURE /MAPINT/ 
UNION 


MAP 


INTEGER* 4 

LONG 

END 

MAP 


MAP 


INTEGER*2 

LO_ WORD 


INTEGER*2 

HI_ WORD 

END 

MAP 


MAP 


INTEGER*1 

BYTE_ 0 


INTEGER*1 

BYTE_ 1 


INTEGER*1 

BYTE_2 


INTEGER*1 

BYTE_ 3 

END 

MAP 



END UNION 
END STRUCTURE 

RECORD /MAPINT/ I 

I%LONG = '01020304'x 
PRINT ' (Z8) ', I%LONG 

PRINT '(Z4,IX,Z4)', I%LO_ WORD, I%HI 
PRINT '(Z2,3(IX,Z2))', I%BYTE_ 0, 1% 
$ I%BYTE_ 2, 1% 

END 


The above example produces the following output: 

01020304 
0304 0102 
04 03 02 01 


_ WORD 
BYTE_ 1, 
;BYTE_ 3 
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7 Expressions 


The following topics are discussed in this chapter. 

• Arithmetic Expressions 

• Character Expressions 

• Relational Expressions 

• Logical Expressions 

• Evaluating Expressions 

• Constant Expressions 

7.1 Arithmetic Expressions 

Arithmetic expressions are used to describe computations involving operands with numeric data type, 
arithmetic operators and left and right parentheses. The result of the computation is of numeric data type. 

7.1.1 Arithmetic Operators 

The following table lists the arithmetic operators and the operation they perform. 


Operator 

Arithmetic Operation 

'k ★ 

Exponentiation 

/ 

Division 

★ 

Multiplication 

- 

Subtraction or Negation 

+ 

Addition or Identity 


Some operators can be either binary or unary. A binary operator is one that requires two operands. A 
unary operator is one that requires one operand. Each of the operators **, /, and * are binary operators. 
The operators + and - can either be binary or unary operators. The following table describes how each 
operator is used with their operands. 
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Operator 

Arithmetic Operation 

x ** y 
x / y 
x * y 

x - y 

x + y 

- X 

+ X 

x is raised to the power y 
x is divided by y 
x is multiplied by y 
y is subtracted from x 
y is added to x 
x is negated 
identity 


Arithmetic expressions can contain more than one operator. It is thus necessary to define rules of 
evaluation for such expressions. A precedence relation is defined between operators. This relation defines 
the order in which operands are combined and hence describes the evaluation sequence of an arithmetic 
expression. Operands of higher precedence operators are combined using that operator to form an operand 
for an operator of lower precedence. The following rules define the precedence relation among arithmetic 
operators. 

1. Exponentiation (* *) has highest precedence. 

2. Multiplication (*) and division (/) have equal precedence but have lower precedence than 
exponentiation. 

3. Addition (+) and subtraction (-) have equal precedence but have lower precedence than 
multiplication and division. 

For example, to evaluate the expression 

A-B* * 4 


B is raised to the exponent 4 first and the result is then subtracted from A. 

Parentheses can be used to alter the evaluation sequence of an arithmetic expression. When a left 
parenthesis is encountered, the entire expression enclosed in parentheses is evaluated. Consider the 
following expression. 

3*(4+5) 

We first evaluate the expression in the parentheses, the result being 9. We now multiply the result by 3 
giving a final result of 27. Now suppose we remove the parentheses. According to the precedence rules, * 
has precedence over + so we perform the multiplication before the addition. The result in this case is 17. 

7 . 1.2 Rules for Forming Standard Arithmetic Expressions 

The building blocks for arithmetic expressions are called arithmetic primaries. They are one of the 
following: 

1. unsigned arithmetic constant 

2. arithmetic symbolic constant 

3. arithmetic variable reference 

4. arithmetic array element reference 

5. arithmetic function reference 

6. ( arithmetic expression ) 
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A grammar for forming arithmetic expressions can be described which reflects the precedence relation 
among arithmetic operators. 

Exponentiation has highest precedence. We define a factor as: 

1. primary 

2. primary ** factor 

A factor is simply a sequence of primaries, each separated by the exponentiation operator. Rule (2) 
specifies that the primaries involving exponentiation operators are combined from right to left when 
evaluating a factor. 

Next in the precedence hierarchy are the multiplication and division operators. We define a term as: 

1. factor 

2. term / factor 

3. term * factor 

A term is simply a sequence of factors, each separated by a multiplication operator or a division operator. 
Rules (2) and (3) imply that in such a sequence, factors are combined from left to right when evaluating a 
term. Factors can be interpreted as the result obtained from evaluating them. This implies that all factors 
are evaluated before any of the multiplication or division operands are combined. This interpretation is 
consistent with the precedence relation between the exponentiation operator and the division and 
multiplication operators. 

An arithmetic expression can now be defined as follows. 

1. term 

2. + term 

3. - term 

4. arithmetic expression + term 

5. arithmetic expression - term 

An arithmetic expression is simply a sequence of terms, each separated by an addition operator or a 
subtraction operator. Rules (4) and (5) imply that terms are evaluated from left to right. Rules (2) and (3) 
imply that only the first term of an arithmetic expression can be preceded by a unary + or - operator. 
Terms can be interpreted in the same way as factors were interpreted in the definition of terms. 

Note that consecutive operators are not permitted. For example, the expression 

A+-B 

is illegal. However, expressions of the form 
A+(-B) 
are allowed. 
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7 . 1.3 Arithmetic Constant Expression 

An arithmetic constant expression is an arithmetic expression in which all primaries are one of the 
following. 

1. arithmetic constant 

2. symbolic arithmetic constant 

3. ( arithmetic constant expression ) 

There is a further restriction with the exponentiation operator; the exponent must be of type INTEGER. 


As an extension to the FORTRAN 77 language. Open Watcom FORTRAN 77 supports the use of the 
intrinsic function ISIZEOF in an arithmetic constant expression. 

Example: 

PARAMETER (INTSIZ = ISIZEOF(INTEGER)) 


An integer constant expression is an arithmetic constant expression in which all constants and symbolic 
constants are of type INTEGER. 

Example: 

123 

-753+2 
-(12*13) 

A real constant expression is an arithmetic constant expression in which at least one constant or symbolic 
constant is of type REAL and all other constants or symbolic constants are of type REAL or INTEGER. 

Example: 

123. 

-753+2.0 
-(13E0*12) 

A double precision constant expression is an arithmetic constant expression in which at least one constant 
or symbolic constant is of type DOUBLE PRECISION and all other constants or symbolic constants are of 
type DOUBLE PRECISION, REAL or INTEGER. 


Example: 

123.4D0 
-753D0*2+.5 
-(12D0*12.2) 

A complex constant expression is an arithmetic constant expression in which at least one constant or 
symbolic constant is of type COMPLEX and all other constants or symbolic constants are of type 
COMPLEX, REAL or INTEGER. 
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Example: 

(123,0) 

(-753,12.3)*2 

- ( 12 , - 12 . 4 ) - ( 1 . 0 , . 2 ) 


A double precision complex constant expression is an arithmetic constant expression in which at least one 
constant or symbolic constant is of type COMPLEX* 16 and all other constants or symbolic constants are of 
type COMPLEX* 16, DOUBLE PRECISION, REAL or INTEGER. If there are no constants or symbolic 
constants of type COMPLEX* 16 in a constant expression, the type of the constant expression will be 
COMPLEX* 16 if it contains at least one constant or symbolic constant of type COMPLEX and at least one 
constant or symbolic constant of type DOUBLE PRECISION. Open Watcom FORTRAN 77 supports this 


Example: 

(123,0D0) 

(-753,12.3D0)*2 
-(12D0,-12.4)-(1.0,.2) 


7.1.4 Data Type of Arithmetic Expressions 


Evaluating an arithmetic expression produces a result which has a type. The type of the result is 
determined by the type of its operands. The following table describes the rules for determining the type of 
arithmetic expressions. The letters I, R, D, C and Z stand for INTEGER, REAL, DOUBLE PRECISION, 
COMPLEX and COMPLEX*16 respectively. An entry in the table represents the data type of the result 
when the operands are of the type indicated by the row and column in which the entry belongs. The 
column represents the type of the operand to the right of the operator, and the row represents the type of the 
operand to the left of the operator. The table is valid for all of the arithmetic operators. 


op 

1*1 

1*2 

1*4 

R 

D 

C 

Z 

1*1 

1*1 

1*2 

1*4 

R 

D 

C 

Z 

1*2 

1*2 

1*2 

1*4 

R 

D 

C 

Z 

1*4 

1*4 

1*4 

1*4 

R 

D 

C 

Z 

R 

R 

R 

R 

R 

D 

C 

Z 

D 

D 

D 

D 

D 

D 

Z 

Z 

C 

C 

C 

C 

C 

Z 

C 

Z 

Z 

Z 

Z 

Z 

Z 

Z 

Z 

Z 


Notes: 

1. 1*1 represents the INTEGER*! data type, 1*2 represents the INTEGER*2 data type, and 1*4 
represents the INTEGER or INTEGER*4 datatype. 

2. The data type of the result obtained by dividing an integer datum by an integer datum is also of 
type INTEGER even though the mathematical result may not be an integer. This result is called 
the integer quotient and is defined as the integer part of the mathematical quotient. 

3. Open Watcom FORTRAN 77 supports the double precision complex data type 
(COMPLEX* 16) as an extension of the FORTRAN 77 language. Combining an operand of type 
DOUBLE PRECISION with an operand of type COMPLEX yields a result of type 
COMPLEX*16. 
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7.2 Character Expressions 

Character expressions are used to describe computations involving operands of type CHARACTER, the 
concatenation operator (//) and left and right parentheses. The result of the computation is of type 
CHARACTER. 

7.2.1 Character Operators 

There is only one character operator, namely the concatenation operator (//). It requires two operands of 
type CHARACTER. If x is the left operand and y is the right operand, then the result is y concatenated to 
x. The length of the result is the sum of the lengths of the two operands. For example, the result of 

'AAAAA'//'BBB' 

is the string AAAAABBB. 

7.2.2 Rules for Forming Character Expressions 

The building blocks for character expressions are called character primaries. They are one of the 
following. 

1. character constant 

2. character symbolic constant 

3. character variable reference 

4. character array element reference 

5. character substring reference 

6. character function reference 

7. ( character expression ) 

Character expressions are defined as follows: 

1. character primary 

2. character expression // character primary 

A character expression is simply a sequence of character primaries, each separated by the concatenation 
operator (//). Rule 2 implies that character primaries are combined from left to right. Except in a character 
assignment statement, the operands in a character expression must not contain operands whose length 
specification is (*) unless the operand is a symbolic constant. 

Note that, unlike arithmetic expressions, parentheses have no effect on the result of evaluating a character 
expression. For example, the result of the expressions 


'A'//'B'//'C' 


and 


'A' // ('B' //'C' ) 


is identically the string ABC . 
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7.2.3 Character Constant Expressions 

A character constant expression is a character expression in which all primaries are one of the following. 

1. character constant 

2. symbolic character constant 

3. ( character constant expression ) 


As an extension to the FORTRAN 77 language. Open Watcom FORTRAN 77 supports the use of the 
intrinsic function CHAR in a character constant expression. 

Example: 

CHARACTER*6 HELLO, WORLD 
PARAMETER (HELLO = 'Hello'//CHAR(0)) 

PARAMETER (WORLD = 'world'//CHAR(7)) 

PRINT *, HELLO, WORLD 
END 


7.3 Relational Expressions 

A relational expression is used to compare two arithmetic expressions or two character expressions. It is 
not possible to compare a character expression to an arithmetic expression. Evaluation of a relational 
expression produces a result of type logical. 

7.3.1 Relational Operators 

The following table lists the relational operators and the operation they perform. 


Operator 

Relational Operation 

. LT. 

Less than 

. LE . 

Less than or equal 

• EQ. 

Equal 

.NE. 

Not equal 

.GT. 

Greater than 

.GE. 

Greater than or equal 


7.3.2 Form of a Relational Expression 

The form of a relational expression is as follows. 


el relop e2 
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where: 

relop is a relational operator. 

el, e2 are both arithmetic expressions or both character expressions. 

7.3.2.1 Arithmetic Relational Expressions 

An arithmetic relational expression is a relational expression in which el and e2 are both arithmetic 
expressions. An arithmetic relational expression has a value of true if the operands satisfy the relation 
specified by the relational operator and false otherwise. 

A complex operand is only permitted when using either the .EQ. or .NE. relational operators. Open 
Watcom FORTRAN 77 allows operands of type COMPLEX* 16. 

7.3.2.2 Character Relational Expressions 

Character relational expressions are relational expressions whose operands are of type CHARACTER. 

The value of a relation between character strings is established by using the collating sequence of the 
processor character set. The collating sequence is an ordering of the characters in the processor character 
set. Note, for example, that the EBCDIC character set has a different collating sequence than that of the 
ASCII character set. For example, el is greater than e2 if the value of el follows the value of e2 in the 
processor collating sequence. The value of a character relational expression depends on the collating 
sequence. In the case of the .NE. and .EQ. operators, the collating sequence has no effect. 

Example: 

IF( 'A' .LT. 'a' )THEN 

PRINT *, 'The processor character set' 

PRINT *, 'appears to be ASCII' 

ELSE 

PRINT *, 'The processor character set' 

PRINT *, 'appears to be EBCDIC' 

END IF 
END 

The above example is a crude test for determining the character set used on your processor. 

It is possible to have operands of unequal length. In this case, the character string of smaller length is 
treated as if blanks were padded to the right of it to the length of the larger string. The relational operator is 
then applied. 

7.4 Logical Expressions 

Logical expressions are used to describe computations involving operands whose type is LOGICAL or 
INTEGER , logical operators and left and right parentheses. The result of the computation is of type 
LOGICAL unless both operands are of type INTEGER in which case the result of the computation is of 
type INTEGER. 
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7.4.1 Logical Operators 

The following table lists the logical operators and the operation they perform. 


Operator 

Logical Operation 

.NOT. 

Logical negation 

.AND. 

Logical conjunction 

.OR. 

Logical inclusive disjunction 

. EQV. 

Logical equivalence 

.NEQV. 

Logical non-equivalence 

. XOR. 

Exclusive or 


The logical operator .NOT. is a unary operator; all other logical operators are binary. The following tables 
describe the result of each operator when it is used with logical operands. 


X 

.NOT. x 

true 

false 

false 

true 


X 

y 

x . AND. y 

true 

true 

true 

true 

false 

false 

false 

true 

false 

false 

false 

false 


X 

y 

x .OR. y 

true 

true 

true 

true 

false 

true 

false 

true 

true 

false 

false 

false 


X 

y 

x .EQV. y 

true 

true 

true 

true 

false 

false 

false 

true 

false 

false 

false 

true 


X 

y 

x .NEQV. y 



. x .XOR. y 

true 

true 

false 

true 

false 

true 

false 

true 

true 

false 

false 

false 
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Note that the operators .NEQV. and .XOR. perform the same logical operation. 


The following tables describe the result of the logical operators when they are used with integer operands. 
These operators apply to bits in the operand(s), hence we show only the result of operations on individual 
bits. The way to read the entries in the following tables is: 

1. If the bit in "x" is 0 then the corresponding bit in ".NOT.x" is 1, and so on. 

2. If the bit in "x" is 1 and the corresponding bit in "y" is 1 then the corresponding bit in "x.AND.y" 
is 1, and so on. 



Note that the operators .NEQV. and .XOR. perform the same mathematical operation on bits. 
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As is the case with arithmetic operators, we must define rules in order to evaluate logical expressions. 
Again we define rules of precedence for logical operators which dictate the evaluation sequence of logical 
expressions. The following lists the logical operators in order of precedence. 

1. .NOT. (highest precedence) 

2. .AND. 

3. .OR. 

4. .EQV., .NEQV. and .XOR. (lowest precedence) 

For example, in the expression 

A .OR. B .AND. C 

the .AND. operator has higher precedence than the .OR. operator so B and C are combined first using the 
.AND. operator. The result is then combined with A using the .OR. operator. 

Parentheses can be used to alter the sequence of evaluation of logical expressions. If in the previous 
example we had written 

(A .OR. B) .AND. C 

then A and B would have been combined first. 

7.4.2 Rules for Forming Logical Expressions 

Logical primaries are the building blocks for logical expressions. They are one of the following. 

1. logical or integer constant 

2. symbolic logical or integer constant 

3. logical or integer variable reference 

4. logical or integer array element reference 

5. logical or integer function reference 

6. relational expression 

7. ( logical or integer expression ) 

As was done with arithmetic expressions, a grammar can be defined which dictates the precedence relation 
among logical operators. 

The .NOT. logical operator has highest precedence. We define a logical factor as: 

1. logical primary 

2. .NOT. logical primary 

Next in the precedence hierarchy is the .AND. operator. We define a logical term as: 

1. logical factor 

2. logical term .AND. logical factor 

A logical term is simply a sequence of logical factors, each separated by the .AND. operator. Rule (2) 
specifies that the logical factors are combined from left to right. 

Next is the .OR. operator. We define a logical disjunct as: 
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1. logical term 

2. logical disjunct .OR. logical term 

A logical disjunct is simply a sequence of logical terms each separated by the .OR. operator. Rule (2) 
specifies that the logical terms are combined from left to right. 

A logical expression can now be defined as follows. 

1. logical disjunct 

2. logical expression .EQV. logical disjunct 

3. logical expression .NEQV. logical disjunct or logical expression .XOR. logical disjunct 

A logical expression is therefore a sequence of logical disjuncts, each separated by the .EQV. operator or 
the .NEQV. or .XOR. operator. Rules (2) and (3) indicate that logical disjuncts are combined from left 
to right. 

Consider the following example. 

A .OR. .NOT. B .AND. C 

Since the .NOT. operator has highest precedence we first logically negate B . The result is then combined 
with C using the .AND. operator. That result is then combined with A using the .OR. operator to form the 
final result. 

7.4.3 Logical Constant Expressions 

A logical constant expression is a logical expression in which each primary is one of the following: 

1. logical constant 

2. symbolic logical constant 

3. a relational expression in which each primary is a constant expression 

4. ( logical constant expression ) 

The following are examples of a logical constant expression (assume that A, B, C and D are arithmetic 
constants appearing in PARAMETER statements). 

.TRUE. .AND. .NOT. .FALSE. 

'A' .LT. 'a' 

A * B .GT. C * D 


7.5 Evaluating Expressions 

Four different types of operators have been discussed; arithmetic, character, relational and logical. It is 
possible to form an expression which contains all of these operators. Consider the following example. 

A+B .LE. C .AND. X // Y .EQ. Z .AND. L 

where A, B and C are of numeric type, X, Y and Z are of type CHARACTER and L is of type 
LOGICAL. In this expression, + is an arithmetic operator, // is a character operator, .EQ. is a relational 
operator and .AND. is a logical operator. Since we can mix these four types of operators, it is necessary to 
define a precedence among these four classes of operators. The following defines this precedence of 
operators. 
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1. arithmetic operators (highest precedence) 

2. character operators 

3. relational operators 

4. logical operators (lowest precedence) 

With this precedence any expression can now be evaluated without ambiguity. 

7.6 Constant Expressions 

A constant expression is an arithmetic constant expression, a character constant expression or a logical 
constant expression. 
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8 Assignment Statements 


8.1 Introduction 


Assignment statements are used to define entities. There are four different types of assignment. 

1. Arithmetic 

2. Logical 

3. Statement label ( ASSIGN) 

4. Character 


8.2 Arithmetic Assignment 

The form of an arithmetic assignment statement is 


v = e 


where: 

v is a variable name or array element name of type INTEGER, REAL, DOUBLE PRECISION, 
COMPLEX or double precision complex (COMPLEX* 16). 

e is an arithmetic expression. 

The following are examples of arithmetic assignment statements. 

Y = X**2 + 4.0*X + 3.0 
Z(10) = 4.3*(X+Y) 

Executing an arithmetic assignment statement causes the evaluation of the arithmetic expression e, 
converting the type of the expression e to the type of v, and defining v with the result. 

If v is of type INTEGER* 1 or INTEGER*2, then the value of the expression e is first converted to type 
INTEGER. The resulting integer is then assigned to v in the following way. 

1. If v is of type INTEGER*2 and the value of e is such that -32768 <= e <= 32767, v will be 
assigned the value of e . Otherwise, v will be undefined. 

2. If v is of type INTEGER* 1 and the value of e is such that -128 <= e <= 127, v will be assigned 
the value of e . Otherwise, v will be undefined. 
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8.3 Logical Assignment 

The form of a logical assignment statement is 


v = e 


where: 

v is a variable name or array element name of type LOGICAL. 
e is a logical expression. 

The following are examples of logical assignment statements. 

L0G1 = .TRUE. 

L0G2 = (X.GT.Y) .AND. (X.LT.Z) 

L0G3(2) = L0G2 .EQV. L0G1 

Executing a logical assignment statement causes the evaluation of the logical expression e, and defining v 
with the result. Note that the type of v and e must be LOGICAL. 


8.4 Statement Label Assignment 

The form of a statement label assignment is 


ASSIGN s to i 


where: 

s is a statement label. 
i is the name of an integer variable. 

The following is an example of a statement label assignment statement. 

ASSIGN 10 TO I 

The result of executing an ASSIGN statement causes the integer variable i to be defined with the value of 
the statement label s . s must be the statement label of an executable statement or a format statement in 
the same program unit in which the ASSIGN statement appears. It is possible to change the value of i by 
executing another ASSIGN statement. 

During execution when i is used in an assigned GO TO statement, an ASSIGN statement which defines i 
must have been executed prior to the execution of the assigned GO TO statement. 
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While the variable i is defined with a statement label, it should not be used in any other way other than in 
an assigned GO TO statement. Consider the following example. 

Example: 

10 ASSIGN 10 TO I 

* Illegal use of an ASSIGNed variable 
PRINT *, I 

The output produced by the PRINT statement is not the integer 10. Its value is undefined and should be 
treated that way. 


8.5 Character Assignment 

The form of a character assignment statement is 


v = e 


where: 

v is a character variable name, character array element, or character substring. 
e is a character expression. 

The following are examples of character assignment statements. 

CHARACTER*20 C,D(5) 

C='ABCDEF' 

C(3:5)='XYZ' 

D (5) (14 :15) =* 12* 

Executing a character assignment statement causes the evaluation of the character expression e and the 
definition of v with the result. 

None of the character positions defined in v may be referenced in e . The following example is illegal 
since the 4th and 5th character positions of A appear on the left and right hand side of the equal sign. 

Example: 

* Illegal character assignment. 

CHARACTER*10 A, B*5 
A(2:6) = A(4:5) // B 

The length of v and e may be different. If the length of v is less than the length of e then the assignment 
has the effect of truncating e from the right to the length of v. If the length of v is greater than the length 
of e, the value assigned to v is the value of e padded on the right with blanks to the length of v. 
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8.6 Extended Assignment Statement 

Open Watcom FORTRAN 77 supports an extension to the FORTRAN 77 assignment statement, namely 
the extended assignment statement shown here: 


v = v = v = ... = v = e 
12 3 n 


where: 

v’i must be one of the following: 

1. Variable names or array element names of type INTEGER, REAL, DOUBLE 
PRECISION, COMPLEX or double precision complex (COMPLEX* 16). 

2. Variable names or array element names of type LOGICAL. 

3. Character variable names, character array elements, or character substrings. 

e must be one of the following and must follow the rules of the arithmetic, logical or character 
assignment statements: 

1. An arithmetic expression. 

2. A logical expression. 

3. A character expression. 

The extended assignment statement is equivalent to the following individual statements. 

v = e 

n 

v = v 

n-1 n 


v = v 

2 3 

v = v 

1 2 

When using an extended assignment statement involving variables of mixed type, it is important to 
understand the exact way in which the assignments are performed. Assignment of each variable is made 
using the value of the variable to its immediate right, starting with the rightmost variable which is assigned 
the value of the expression. To help make this clear, consider the following program. 
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Example: 

CHARACTER Cl*10, C2*5, C3*7 
LOGICAL LI, L2, L3 
INTEGER*2 K, L 
I = S = J = T = 1.25 
PRINT *, I, S, J, T 
I=K=J=L= 70000 
PRINT *, I, K, J, L 


Cl = C2 

= C3 

_ r 

ABCDEFGHIJKL' 

PRINT *, 

Cl, 

C2, 

C3 

LI = L2 

= L3 

= . 

TRUE. 

PRINT *, 

LI, 

L2, 

L3 


END 


The output from this program would be: 

1 1.0000000 1 1.2500000 

4464 4464 4464 4464 

ABCDE ABCDEABCDEFG 

T T T 


Note that variables K and L are of type INTEGER*2 and cannot contain any value greater than 32767. 
Truncation resulted and this value (4464) was propagated to the left. 


Extended Assignment Statement 191 




Language Reference 


192 Extended Assignment Statement 




9 Program Structure Control Statements 


9.1 Introduction 


The use of structured programming statements has been found to encourage better programming and design 
practices among beginners, and aids the more experienced programmer in writing error-free programs. 

The format of these statements and their blocks is illustrated below. Following this, the use and meaning of 
each statement is described and illustrated with examples. In each of these illustrations, the blocks are 
denoted by statement (s) and are delimited by control statements. 


In the descriptions, logical-expression can also be an integer expression, in which case the result 
of the integer expression is compared for inequality to the integer value 0. 

Example: 

IF( LEN - 1 )THEN 

In the preceding example, the expression LEN - 1 is interpreted as LEN - 1 . NE . 0 . 


9.2 IF - ELSE ■ END IF 

The ELSE portion of this construct is optional, thus there are two possible formats. 


(a) IF( logical-expression )THEN [: block-label] 

statement(s) 

END IF 

(b) IF( logical—expression )THEN [: block-label] 

statement(s) 

ELSE 

statement(s) 

END IF 


This construct is an enhancement of the FORTRAN logical IF statement. If the value of the parenthesized 
logical expression is true in (a), the block of statements following the IF statement is executed, after which 
control passes to the statement following the END IF statement; otherwise, control will pass directly to the 
statement following the END IF statement. When the ELSE statement is used and the logical expression 
is true, the block of statements between the IF and the ELSE statements is executed and then control 
passes to the statement following the END IF statement; otherwise the block of statements following 
ELSE statement is executed and then control passes to the statement following the END IF statement. 

An optional block label may be specified with the IF statement (see the CYCLE, EXIT or QUIT statement 
for more information). 
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Examples follow which illustrate the use of the two formats. 

Example: 

IF( I .EQ. 0 )THEN 

PRINT *, 'I IS ZERO' 

1 = 1 
END IF 

If variable I is zero when the IF statement is executed, the string I IS ZERO will be printed, variable I 
will be assigned the value 1, and the statement following the END IF will be executed. If variable I is not 
zero when the IF statement is executed, control will pass to the statement following the END IF 
statement. 


Example: 

IF( A .GT. B )THEN 

PRINT *, 'A GREATER THAN B' 

A = A - B 

ELSE 

PRINT *, 'A NOT GREATER THAN B' 
END IF 


If the value of variable A is greater than the value of variable B when this IF statement is executed, the 
string A GREATER THAN B will be printed and variable A will be assigned the value of the expression A 
- B. Control will then pass to the statement following the END IF statement. 

If the value of variable A is not greater than the value of variable B when the IF statement is executed, the 
string A NOT GREATER THAN B will be printed and control will pass to the statement following the 
END IF statement. 


9.3 ELSE IF 


A further enhancement of the IF-THEN-ELSE construct is the ELSE IF statement which may be used in 
the following two formats: 


(a) IF( logical-expression-1 )THEN [: block-label] 

statement(s) 

ELSE IF( logical—expression-2 )THEN 
statement(s) 

END IF 

(b) IF( logical-expression-1 )THEN [: block-label] 

statement(s) 

ELSE IF( logical—expression-2 )THEN 
statement(s) 

ELSE 

statement(s) 

END IF 
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The presence of the in the above formats indicates that the ELSE IF statement may be repeated as 
often as desired. If the value of logical-expression-1 is true in case (a), the block of statements 
following the IF statement up to the first ELSE IF statement is executed, after which control passes to the 
statement following the END IF statement; otherwise, control will pass to the first ELSE IF statement. If 
the value of logical-expression-2 is true, the block of statements following the first ELSE IF 
statement up to the next ELSE IF statement or END IF statement is executed, after which control passes 
to the statement following the END IF statement; otherwise, control will pass to the next ELSE IF 
statement, if there is one, or directly to the statement following the END IF statement. When the ELSE 
statement is used, as in case (b), and the values of all the logical expressions in the IF and ELSE IF 
statements are false, the block of statements following the ELSE statement is executed and then control 
passes to the statement following the END IF statement. An optional block label may be specified with 
the IF statement (see the CYCLE, EXIT or QUIT statement for more information). 

Examples follow which illustrate the use of the two formats. 

Example: 

IF( I .EQ. 0 )THEN 

PRINT *, 'I IS ZERO' 

ELSE IF( I .GT. 0 )THEN 

PRINT *, 'I IS GREATER THAN ZERO' 

END IF 

If variable I is zero when the IF statement is executed, the string I IS ZERO will be printed and the 
statement following the END IF statement will be executed. If variable I is not zero when the IF 
statement is executed, control will pass to the ELSE IF statement. If variable I is greater than zero, the 
string I IS GREATER THAN ZERO will be printed and the statement following the END IF statement 
will be executed. If variable I is less than zero then nothing would be printed and control passes from the 
ELSE IF statement to the statement following the END IF statement. 

Example: 

IF( A .GT. B )THEN 

PRINT *, 'A GREATER THAN B' 

A = A - B 

ELSE IF( A .LT. B )THEN 

PRINT *, 'A LESS THAN B' 

A = B - A 

ELSE 

PRINT *, 'A EQUAL TO B' 

A = 0.0 
END IF 

If the value of variable A is greater than the value of variable B when the IF statement is executed, the 
string A GREATER THAN B will be printed and variable A will be assigned the value of the expression A 

- B. Control will then pass to the statement following the END IF statement. 

If the value of variable A is not greater than the value of variable B when the IF statement is executed, 
control passes to the ELSE IF statement. If the value of variable A is less than the value of variable B, 
the string A LESS THAN B will be printed and variable A will be assigned the value of the expression B 

- A. Control will then pass to the statement following the END IF statement. 

If the value of variable A is not less than the value of variable B when the ELSE IF statement is executed, 
the string A EQUAL TO B will be printed and variable A will be assigned the value zero. Control will 
pass to the statement following the END IF statement. 
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9.4 DO - END DO 



This extension to FORTRAN 77 allows the creation of DO-loops without the introduction of statement 
numbers. An optional block label may be specified (see the CYCLE, EXIT or QUIT statement for more 
information). The END DO statement is used to indicate the end of the range of its corresponding DO 
statement. A statement number may not be specified in the corresponding DO statement. Nested DO-loops 
of this form require separate END DO statements to terminate the range of the corresponding DO statement. 
Since a statement number may appear on the END DO statement, the number may be used to terminate 
outer DO-loops. This is not a recommended practice (a CONTINUE statement or a structured DO statement 
should be used). A transfer of control from within the DO-loop to a statement number on the END DO 
statement is treated in the same manner as if the word CONTINUE had been used instead of END DO. 

Some examples follow. 

Example: 

DO I = 1, 3 

DO J = 1, 5 

PRINT *, MATRIX( I, J ) 

END DO 
END DO 

The above is equivalent to the following example which uses statement numbers. 

Example: 

DO 10 I = 1, 3 

DO 20 J = 1, 5 

PRINT *, MATRIX( I, J ) 

20 CONTINUE 

10 CONTINUE 

The next example demonstrates the use of a GO TO statement to control execution of all or part of a 
DO-loop. 

Example: 

DO I = 1, 3 

DO J = 1, 5 

PRINT *, 'INNER LOOP - J=', J 
IF( J .LE. 3 )GO TO 20 
PRINT *, ' J > 3' 

20 END DO 

PRINT *, 'OUTER LOOP - J=', J 
END DO 

A result of this example is that the character string J > 3 is printed 6 times (i.e., twice for each iteration 
of the outer loop). Of course there is a much better way of coding this algorithm using the IF-END IF 
construct. The example is included to illustrate the behaviour of transfers of control to an END DO 
statement. The following example is an equivalent algorithm to the one above but the intent is much 
clearer. 
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Example: 

DO I = 1, 3 

DO J = 1, 5 

PRINT *, 'INNER LOOP - J=', J 
IF( J .GT. 3 )THEN 
PRINT *, 'J > 3' 

END IF 
END DO 

PRINT *, 'OUTER LOOP - J=', J 
END DO 


9.5 DO WHILE ■ END DO 


DO WHILE (e) [: block-label] 

statement(s) 

END DO 


This extension to FORTRAN 77 allows the creation of DO-loops without iterative techniques. Instead, the 
DO-loop is executed while the parenthesized expression is true. The logical expression is evaluated before 
entry to the DO-loop. If the value is false, control is transferred to the statement following the END DO 
statement. If the logical expression if true, the statements of the DO-loop are executed. When the END DO 
statement is reached, the expression is re-evaluated and program control proceeds as previously described. 
An optional block label may be specified (see the CYCLE, EXIT or QUIT statement for more information). 

An optional statement number can be specified after the DO keyword. When the END DO statement is used 
to indicate the end of the range of its corresponding DO WHILE statement, a statement number may not be 
specified. 

Some examples follow. 

Example: 

1 = 1 

DO WHILE( I .LE. 3 ) 

J = 1 

DO WHILE( J .LE. 5 ) 

PRINT *, MATRIX( I, J ) 

END DO 
END DO 


The above is equivalent to the following example which uses statement numbers. 


Example: 

1 = 1 

DO 10 WHILE( I .LE. 3 ) 

J = 1 

DO 20 WHILE( J .LE. 5 ) 

PRINT *, MATRIX( I, J ) 
20 CONTINUE 

10 CONTINUE 
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The next example demonstrates the use of a GO TO statement to control execution of all or part of a 
DO-loop. 

Example: 

1 = 1 

DO WHILE( I .LE. 3 ) 

J = 1 

DO WHILE( J .LE. 5 ) 

PRINT *, 'INNER LOOP - J=', J 
IF( J .LE. 3 )GO TO 20 
PRINT *, 'J > 3' 

2 0 END DO 

PRINT *, 'OUTER LOOP - J=' , J 
END DO 


A result of this example is that the character string J > 3 is printed 6 times (i.e., twice for each iteration 
of the outer loop). Of course there is a much better way of coding this algorithm using the IF-END IF 
construct. The example is included to illustrate the behaviour of transfers of control to an END DO 
statement. The following example is an equivalent algorithm to the one above but the intent is much 
clearer. 


Example: 

1 = 1 

DO WHILE( I .LE. 3 ) 

J = 1 

DO WHILE( J .LE. 5 ) 

PRINT *, 'INNER LOOP - J=', J 
IF( J .GT. 3 )THEN 
PRINT *, 'J > 3' 

END IF 
END DO 

PRINT *, 'OUTER LOOP - J=', J 
END DO 


9.6 LOOP - END LOOP 


LOOP [: block—label] 
statement(s) 

END LOOP 


This extension to FORTRAN 77 causes the statements between the LOOP and END LOOP statements to be 
repeated until control is transferred out of the loop, usually by an EXIT or QUIT statement. An optional 
block label may be specified (see the CYCLE, EXIT or QUIT statement for more information). An 
example follows: 
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Example: 

LOOP 

READ *, X 

IF ( X .EQ. 99.0 )EXIT 
PRINT *, X 
END LOOP 


The above statements cause values to be read and printed, one to a line, until the value 99.0 is read. When 
variable X has this value, the logical expression in the IF statement evaluates as true and the EXIT 
statement causes a transfer of control to the statement following the END LOOP statement. The EXIT 
statement is discussed in more detail in a later section. 


9.7 WHILE - END WHILE 


WHILE( logical-expression )DO [: block—label] 

statement(s) 

END WHILE 


This extension to FORTRAN 77 causes its block of code to be executed repeatedly while the parenthesized 
logical expression is true. The logical expression is evaluated before entry to the block. If the value is 
false, control passes to the statement following the END WHILE statement. If the logical expression is 
true, the statements of the block are executed. When the END WHILE statement is reached, the WHILE 
logical expression is re-evaluated and the above program control decisions are repeated. An optional block 
label may be specified (see the CYCLE, EXIT or QUIT statement for more information). An example 
follows: 

Example: 

WHILE( J .GT. 0 )DO 
A (J) = B (I + J) 

J = J - 1 
END WHILE 

If variable J is zero or negative when the WHILE statement is executed, the WHILE block of code will be 
by-passed and the statement following the END WHILE statement will be executed. 

If variable J is greater than zero when the WHILE statement is executed, the WHILE block will be executed 
repeatedly until J becomes equal to zero. The effect of this loop will be to assign values to elements of 
array A from array B, starting with the element of A corresponding to the initial value of variable J and 
working backwards down the array to element 1. 


9.8 WHILE - Executable-statement 


WHILE( logical—expression )stmt 
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where: 

stmt is an executable statement. Only certain executable statements are are allowed. See the section 
entitled "Classifying Statements" on page 9 in the chapter entitled "FORTRAN Statements" for a 
list of allowable statements. 

This control statement is another form of the WHILE construct. 

Example: 

WHILE( I .GT. 0 )EXECUTE A 

When this statement is executed, if the logical expression is not true, control passes to the next statement. 
If the expression is true, REMOTE-block A (assumed to be defined elsewhere in the program unit) is 
executed, and the logical expression is re-evaluated. This is repeated until the logical expression, when 
evaluated, is false; control then passes to the next statement. 


9.9 UNTIL 


LOOP [: block—label] 
statement(s) 

UNTIL( logical—expression ) 


or 


WHILE( logical-expression )DO [: block—label] 

statement(s) 

UNTIL( logical—expression ) 


The UNTIL statement, an extension to FORTRAN 77, may be combined with either a LOOP or WHILE 
statement by replacing the END LOOP or END WHILE statement. It provides a way of specifying a 
condition to be tested at the end of each iteration of a loop, which will determine whether or not the loop is 
repeated. After all of the statements in the block have been executed, the logical expression in the UNTIL 
statement is evaluated. If the result of the condition is false, the loop is repeated; otherwise, control passes 
to the statement following the UNTIL statement. 

In the following example, the statements between the LOOP and the UNTIL statements are executed until 
the value of variable X is greater than 10.0. 

Example: 

X = 1.0 
LOOP 

PRINT *, X, SQRT( X ) 

X = X + 1.0 
UNTIL( X .GT. 10.0 ) 
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9.10 SELECT - END SELECT 


SELECT [CASE] (e) [FROM] 

[: block-label] 

CASE ( case-list ) 


statement (s) 


CASE ( case-list ) 


statement (s) 


CASE DEFAULT 


statement(s) 


END SELECT 



where: 

case-list is a list of one or more cases separated by commas. A case is either 

(a) a single integer, logical or character constant expression or 

(b) an integer, logical or character constant expression followed by a colon 
followed by another expression or the same type. This form of a case defines 
a range of values consisting of all integers or characters greater than or equal 
to the value of the expression preceding the colon and less than or equal to 
the value of the expression following the colon. 

The SELECT construct, an extension to FORTRAN 77, is similar in concept to the FORTRAN computed 
GO TO statement. It allows one of a number of blocks of code (case blocks) to be selected for execution by 
means of an integer expression in the SELECT statement. 

The SELECT statement keywords, CASE and FROM, are optional. The SELECT statement may contain a 
block label (see the CYCLE, EXIT or QUIT statements for more information). 

Each block must be started with a CASE statement; however, the last block may begin with a CASE 
DEFAULT statement. The CASE DEFAULT block is optional. In order to retain compatibility with earlier 
versions of WATCOM FORTRAN 77 compilers, the OTHERWISE statement may be used in place of the 
CASE DEFAULT statement. The last block is ended by the END SELECT statement. The number of case 
blocks is optional, from one to many; however, it is recommended that the SELECT construct not be used 
for fewer than 3 case blocks. The conditional execution of one or two blocks of code is handled more 
efficiently by the IF-THEN-ELSE construct. 

A particular case value or range of values must not be contained in more than one CASE-block. For 
example, the following is illegal: 
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Example: 

* Illegal SELECT block - case value in more 

* than one CASE block. 

SELECT CASE ( I - 3 ) 

CASE (1,3,7:10) 
statement(s) 

CASE (5,6,8) 

statement(s) 

CASE (—3:—2+4) 

statement(s) 

END SELECT 

The second CASE-block includes 8 which is already handled by the first CASE-block. As well, the third 
CASE-block handles cases -3, —2, —1, 0, 1, 2 but the first CASE-block also handles case 1. Thus the 
second and third CASE-ranges are in error. 

When the SELECT statement case expression is evaluated as i, the case block whose range contains i is 
executed and control passes to the statement following the END SELECT statement. If no range contains i, 
control is transferred to the statement following the CASE DEFAULT statement, if one is specified. If the 
CASE DEFAULT block is omitted and the case expression is out of range when the SELECT statement is 
executed (that is, none of the CASE-blocks handles the particular expression value), control is passed to the 
statement following the END SELECT statement and none of the CASE-blocks is executed. 

Example: 

SELECT CASE ( I ) 

CASE (1) 

Y = Y + X 

X = X * 3.2 
CASE (2) 

Z = Y**2 + X 
PRINT *, X, Y, Z 
CASE (3) 

Y = Y * 13. + X 
X = X - 0.213 

CASE (4) 

Z = X**2 + Y**2 - 3.0 

Y = Y + 1.5 
X = X * 32.0 

PRINT *, 'CASE 4', X, Y, Z 
END SELECT 

This example will execute in the manner described below for each of the possible values of variable I. 

(i) I is zero or negative: 

- control will pass to the statement after the END SELECT statement 

(ii) 1 = 1 : 

- the value of X will be added to Y 

- X will be multiplied by 3.2 

- control will pass to the statement after the END SELECT statement 

(iii) 1 = 2 : 

- Z will be assigned the value of the expression Y**2 + X 

- the values of X, Y and Z will be printed 

- control will pass to the statement after the END SELECT statement 
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(iv) 1 = 3: 

- Y will be assigned the value of the expression Y * 13. + X 

- 0.213 will be subtracted from X 

- control will pass to the statement after the END SELECT statement 

(v) 1 = 4: 

- Z, Y and X will be assigned new values 

- the string CASE 4, followed by the values of X, Y and Z will be printed 

- control will pass to the statement after the END SELECT statement 

(vi) 1 = 5, 6, . . . : 

- control will pass to the statement after the END SELECT statement 

CASE DEFAULT allows a block of code to be specified for execution when the SELECT expression is out 
of range. It must follow all CASE-blocks and thus is ended by the END SELECT statement. The CASE 
DEFAULT statement terminates the previous and last CASE-block. Note that only one CASE DEFAULT 
block may be specified in a SELECT construct. 

If a CASE DEFAULT block were included in the above example, it would be executed in cases (i) and (vi) 
of the description. After a CASE DEFAULT block is executed, control then passes to the statement after 
the END SELECT statement. 

Empty or null case blocks are permitted (that is, two CASE statements with no statements between). The 
net result of executing a null CASE-block is to effectively bypass the SELECT construct. 

Example: 

SELECT CASE ( I * 4 - J ) 

CASE (-10 : -5) 

PRINT *,'First case:' 

PRINT *,'-10 <= I*4-J <= -5' 

CASE (-4 : 2) 

PRINT Second case:' 

PRINT *,'-4 <= I*4-J <= 2' 

CASE (3, 5, 7) 

PRINT Third case:' 

PRINT *, ' I*4-J is one of 3, 5 or 7' 

CASE (4, 6, 8:10) 

PRINT *,'Fourth case:' 

PRINT *, ' I*4-J is one of 4, 6, 8, 9 or 10' 

CASE DEFAULT 

PRINT *,'A11 other cases:' 

PRINT *,'I*4-J < -10 or I*4-J > 10' 

END SELECT 

This example will execute in the manner described below for each of the possible values of expression 
I* 4-J. 


(i) expression < -10 

- control will pass to the statement after the CASE DEFAULT statement 

- the string All other cases : will be printed 

- the string 1*4- J < -10 or I*4-J > 10 will be printed 

(ii) -10 <= expression <= -5: 

- control will pass to the statement after the first CASE statement 

- the string First case: will be printed 
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- the string -10 <= I*J-4 <= -5 will be printed 

- control will pass to the statement after the END SELECT statement 

(iii) -4 <= expression <= 2: 

- control will pass to the statement after the second CASE statement 

- the string Second case: will be printed 

- the string -4 <= I*J-4 <= 2 will be printed 

- control will pass to the statement after the END SELECT statement 

(iv) expression = 3, 5 or 7: 

- control will pass to the statement after the third CASE statement 

- the string Third case : will be printed 

- the string I * J-4 is one of 3, 5 or 7 will be printed 

- control will pass to the statement after the END SELECT statement 

(v) expression = 4, 6, 8, 9 or 10: 

- control will pass to the statement after the fourth CASE statement 

- the string Fourth case : will be printed 

- the string I * J-4 is one of 4, 6, 8, 9 or 10 will be printed. 

- control will pass to the statement after the END SELECT statement 

(vi) expression >10: 

- control will pass to the statement after the CASE DEFAULT statement 

- the string All other cases: will be printed 

- the string 1*4-J < -10 or I*4-J > 10 will be printed 


9.11 EXECUTE and REMOTE BLOCK 



where: 

name is a valid FORTRAN symbolic name. 

The EXECUTE statement, an extension to FORTRAN 77, allows a named block of code to be executed. 
The named block of code may be defined anywhere in the same program unit and is delimited by the 
REMOTE BLOCK and END BLOCK statements. Executing a REMOTE-block is similar in concept to 
calling a subroutine, with the advantage that shared variables do not need to be placed in a common block 
or passed in an argument list. In addition there is less overhead involved in executing a REMOTE-block 
than in calling a subroutine (in both amount of object code and execution time). When execution of the 
REMOTE-block is complete, control returns to the statement following the EXECUTE statement which 
invoked it. 
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This feature is helpful in avoiding duplication of code for a function (such as I/O) required in a number of 
places throughout a program. It can also be an aid to writing a well-sttuctured program. 

Each REMOTE-block within the same program unit must have a different name and it must not be a 
subprogram or variable name. Note that a REMOTE-block is local to the program unit in which it is 
defined and may not be referenced (executed) from another program unit. 

REMOTE-blocks may be defined anywhere in the program unit except as follows. 

1. They must follow all specification statements. 

2. They must not be defined within a conUol structure. 

If a REMOTE BLOCK statement is encountered during execution, control is transferred to the statement 
following the corresponding END BLOCK statement. 

Note that the nested definition of REMOTE-blocks is not permitted. 

Example: 

EXECUTE A 
PRINT *, 'FIRST' 


EXECUTE A 
PRINT *, 'SECOND' 


REMOTE BLOCK A 
1 = 1 + 1 
PRINT *, '1=', I 

END BLOCK 

Both EXECUTE statements will cause REMOTE-block A to be executed. That is, variable I will be 
incremented and its value will be printed. When the block has been executed by the first EXECUTE 
statement, control returns to the PRINT statement following it and the word FIRST is printed. Similarly, 
when the block is executed by the second EXECUTE statement, conUol returns to the PRINT statement 
following it and the word SECOND is printed. 

REMOTE-blocks may be executed from other REMOTE-blocks. For example, REMOTE-block A might 
contain the statement EXECUTE B, where B is a REMOTE-block defined elsewhere in the program unit. 
The execution of REMOTE-blocks from other REMOTE-blocks may take place to any level; however, the 
recursive execution of REMOTE-blocks is not permitted, either directly or through a chain of EXECUTE 
statements. Attempts to execute REMOTE-blocks recursively are detected as errors at execution time. 
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9.12 GUESS-ADMIT-END GUESS 


GUESS [: block-label] 
statement(s) 

ADMIT 

statement(s) 

ADMIT 

statement(s) 


ADMIT 

statement(s) 
END GUESS 


The GUESS-ADMIT-END GUESS structure is a rejection mechanism which is useful when sets of 
statements are to be conditionally chosen for execution, but not all of the conditions required to make a 
selection are available beforehand. It is an extension to FORTRAN 77. The sets of statements to be chosen 
may be thought of as alternatives, the first alternative being statements immediately after the GUESS 
statement. Execution begins with the statements in the first alternative. If a condition is detected which 
indicates that the first alternative was the wrong choice, a QUIT statement may be executed to cause 
control to be passed to the statements after the ADMIT statement (i.e., the second alternative). A QUIT 
statement within the second alternative passes control to the third alternative, etc. A QUIT statement 
within the last alternative passes control to the statement after the END GUESS statement. If an alternative 
completes execution without encountering a QUIT statement (i.e., all statements are executed up to the next 
ADMIT statement) then control is passed to the statement after the END GUESS statement. An optional 
block label may be specified following the keyword GUESS (see the QUIT statement for more 
information). 

In the following example, two sets of codes and numbers are read in and some simple sequence checking is 
performed. If a sequence error is detected an error message is printed and processing terminates; otherwise 
the numbers are processed and another pair of numbers is read. 
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Example: 

LOOP : PRLOOP 
GUESS 

LINE = LINE + 1 

READ *, ICODE, X 

AT END, QUIT :PRLOOP 

IF( ICODE .NE. 1 )QUIT 

LINE = LINE + 1 

READ *, ICODE, Y 

AT END, QUIT 

IF( ICODE .NE. 2 )QUIT 

PRINT *, X, Y 

CALL PROCES(X, Y) 

ADMIT 

PRINT *, 'INVALID SEQUENCE: LINE =', LINE 
QUIT :PRLOOP 
END GUESS 
END LOOP 

The above example attempts to read a code and number. If an end of file occurs then the loop is terminated 
by the QUIT statement. 

If the code is not 1 then we did not get what we expected and an error situation has arisen. Control is 
passed to the statement following the ADMIT statement. An error message is printed and the loop is 
terminated by the QUIT statement. 

If the code is 1 then a second code and number are read. If an end of file occurs then we are missing a set 
of data and an error situation has arisen. Control is passed to the statement following the ADMIT statement. 
An error message is printed and the loop is terminated by the QUIT statement. Similarly if the expected 
code is not 2 an error situation has arisen. Control is passed to the statement following the ADMIT 
statement. An error message is printed and the loop is terminated by the QUIT statement. 

If the second code is 2, the values of variables X and Y are printed. A subroutine is then called to process 
the data. Control resumes at the statement following the END GUESS statement. Since this statement is an 
END LOOP, control is transferred to the beginning of the loop. 

The above example illustrates the point that all the information required to make a choice (in this case 
between a valid set of data and an invalid set) is not available from the beginning. In this case we make an 
assumption that the data values are correct (our hypothesis) and then test the assumption at various points in 
the algorithm. If any of the tests fail we reject the hypothesis (and, perhaps, select a new hypothesis). 

It should be noted that no alternative selection need be coded (i.e., we need not use any ADMIT-blocks). 

This is illustrated in the following example. 

Example: 

GUESS 

X=SQRT( X ) 

IF( X .LT. EPS )QUIT 
X=Y+SQRT(Y) 

IF ( X .LT. EPS )QUIT 
CALL INTGRT( X, Y ) 

END GUESS 

It might be noted that the IF-ELSE-END IF construct is simply a specific instance of the more general 
GUESS-ADMIT-END GUESS construct wherein the data values are known beforehand (as could be 
illustrated using the previous example). 
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9.13 QUIT 

QUIT [ : block-label] 


The QUIT statement may be used to transfer control to the first executable statement following the terminal 
statement of the block in which it is contained. 

When transferring out of a loop, control is passed to the statement following the END DO, END WHILE, 
END LOOP or UNTIL statement. 

When transferring out of a GUESS block, control is passed to the statement after the next ADMIT or END 
GUESS statement. 

When transferring out of an IF-block or SELECT-block, control is passed to the statement after the 
corresponding END IF or END SELECT statement. 

When transferring out of a REMOTE-block, control passes to the statement following the EXECUTE 
statement that invoked the REMOTE-block. 

If no block label is specified in the QUIT statement, control is transferred from the immediately enclosing 
structure. If several structures or DO-loops are nested, it is possible to exit from any one of them by 
specifying the block label of the corresponding block structure. 

The QUIT statement is most commonly used as the statement in a logical IF or AT END statement but 
may also be used to cause an unconditional transfer of control. (The AT END statement is described in a 
subsequent section). 

Examples of the QUIT statement with and without a block label follow. 


Example: 


CHARACTER CH 
READ *, CH 
GUESS 



IF( CH .LT 

. 'a' 

) QUIT 

IF( CH .GT 

. ' z ' 

) QUIT 

PRINT *, ' 

Lower 

case letter' 

ADMIT 



IF( CH .LT 

. 'A' 

) QUIT 

IF( CH .GT 

. ' Z' 

) QUIT 

PRINT *, ' 

Upper 

case letter' 

ADMIT 



IF ( CH .LT 

. '0' 

) QUIT 

IF ( CH .GT 

. ' 9' 

) QUIT 

PRINT *, ' 

Digit' 


ADMIT 




PRINT 
END GUESS 
END 


'Special character' 


The above statements read and print values until an end of file occurs. At that point control is passed to the 
QUIT statement, as specified by the AT END statement. The QUIT statement causes control to continue 
with the statement after the END LOOP statement. 
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Example: 

CHARACTER RECORD(80) 

LOOP : RDREC 

READ(5,100) RECORD 
AT END, STOP 
DO I = 1, 80 

IF( RECORD(I) .LT. 'O' 

+ .OR. RECORD(I) .GT. '9' )QUIT : RDREC 

END DO 

WRITE(6,101) RECORD 
END LOOP 

PRINT *, 'INVALID RECORD' 


The above example reads in records and verifies that they contain only numeric data. The QUIT statement 
is within two levels of nesting: the DO-loop and the LOOP-END LOOP structure. If a non-numeric 
character is found, the QUIT : RDREC statement will cause control to be passed to the PRINT 
statement after the END LOOP statement. 


9.14 EXIT 

EXIT [ : block-label] 


The EXIT statement is used to transfer control: 

1. from within a loop (DO, DO WHILE, WHILE or LOOP) to the statement following the loop, 

2. from within a GUESS or ADMIT block to the statement following the ENDGUESS statement, or 

3. from within a remote block to the statement following the EXECUTE statement that invoked the 
remote block. 

When transferring out of a loop, control is passed to the statement following the END DO, END WHILE, 
END LOOP or UNTIL statement. 

When transferring out of a GUESS block, control is passed to the statement after the corresponding END 
GUESS statement. 

When transferring out of a REMOTE-block, control passes to the statement following the EXECUTE 
statement that invoked the REMOTE-block. 

If no block label is specified in the EXIT statement, control is transferred from the immediately enclosing 
structure. If several structures or DO-loops are nested, it is possible to exit from any one of them by 
specifying the block label of the corresponding block structure. 

The EXIT statement is most commonly used as the statement in a logical IF or AT END statement but 
may also be used to cause an unconditional transfer of control. (The AT END statement is described in a 
subsequent section). 

Examples of the EXIT statement with and without a block label follow. 
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Example: 

LOOP 

READ *, X 
AT END, EXIT 
PRINT *, X 
END LOOP 


The above statements read and print values until an end of file occurs. At that point control is passed to the 
EXIT statement, as specified by the AT END statement. The EXIT statement causes control to continue 
with the statement after the END LOOP statement. 


Example: 

CHARACTER RECORD(80) 

LOOP : RDREC 

READ(5,100) RECORD 
AT END, STOP 
DO I = 1, 80 

IF( RECORD(I) .LT. 'O' 

+ .OR. RECORD(I) .GT. '9' )EXIT : RDREC 

END DO 

WRITE(6,101) RECORD 
END LOOP 

PRINT *, 'INVALID RECORD' 


The above example reads in records and verifies that they contain only numeric data. The EXIT statement 
is within two levels of nesting: the DO-loop and the LOOP-END LOOP structure. If a non-numeric 
character is found, the EXIT : RDREC statement will cause control to be passed to the PRINT 
statement after the END LOOP statement. 


9.15 CYCLE 

CYCLE [ : block-label] 


The CYCLE statement is used to cause a transfer of control from within a loop to the terminal statement of a 
corresponding DO, DO WHILE, WHILE or LOOP statement. If block-label is present then control is 
transferred to the terminal statement of the block identified by that block label. 

If no block label is specified in the CYCLE statement, control is transferred to the terminal statement of the 
immediately enclosing loop structure. If several loop structures are nested, it is possible to cycle to the 
terminal statement of any one of them by specifying the block label of the corresponding block structure. 

The CYCLE statement is most commonly used as the statement in a logical IF statement but may also be 
used to cause an unconditional transfer of control. 

Examples of the CYCLE statement with and without a block label follow. 
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Example: 

LOOP 

WRITE( UNIT=*, FMT='(A)' ) 'Enter a number' 

READ( UNIT=*, FMT=' (F10.4)', IOSTAT=IOS ) X 
IF ( IOS .NE. 0 ) CYCLE 
IF( X .LT. 0 ) EXIT 
PRINT *, X, SQRT( X ) 

END LOOP 


The above statements read and print values until a negative integer value is entered. If an input error 
occurs, the input operation (READ) is retried using the CYCLE statement. The CYCLE statement causes 
control to resume at the END LOOP statement which then immediately transfers control to the statement 
following the LOOP statement. 


Example: 

CHARACTER RECORD(80) 

LOOP : RDREC 

READ(5,100) RECORD 
AT END, STOP 
DO I = 1, 80 

IF( RECORD(I) .LT. '0' 

+ .OR. RECORD(I) .GT. '9' )THEN 

PRINT *, 'INVALID RECORD' 

CYCLE : RDREC 
ENDIF 
END DO 

WRITE(6,101) RECORD 
END LOOP 


The above example reads in records and verifies that they contain only numeric data. If the record does 
not, the input operation is tried again. The CYCLE statement is within three levels of nesting: the IF, the 
DO-loop, and the LOOP-END LOOP structure. If a non-numeric character is found, the CYCLE : 
RDREC statement will cause control to be passed to the READ statement that follows the LOOP statement. 


9.16 AT END 



or 


(READ statement) 
AT END, statement 


The AT END control statement, an extension to FORTRAN 77, is an extension of the END= option of the 
FORTRAN READ statement for sequential files. It allows a statement or a block of code following the 
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READ statement to be executed when an end of file condition is encountered during the READ and to be 
by-passed immediately following a READ statement. It is not valid to use this control statement with 
direct-access or memory-to-memory reads. Clearly, it is not valid to use this statement when END= is 
specified in the READ statement. 

Example: 

READ(7, *) I, X 

AT END DO 

PRINT *, 'END-OF-FILE ENCOUNTERED' 

EOFSW = .TRUE. 

END AT END 

If the READ statement is executed without encountering end of file, control passes to the statement 
following the END AT END statement. If an end of file condition occurs during the read, the string, 
END-OF-FILE ENCOUNTERED is printed, logical variable EOFSW is assigned the value .TRUE, and 
control passes to the statement following the END AT END statement. 

Example: 

READ(7, *) X 

AT END, EOFSW = .TRUE. 

If an end of file is not encountered by the READ statement, control passes to the statement following the AT 
END statement. If an end-of-file condition occurs, variable EOFSW is set to . TRUE . and control then 
passes to the statement following the AT END statement. Note that the use of the second form of the AT 
END statement requires the use of a comma (,) between the AT END word and the executable statement. 
This is necessary to distinguish the case where the executable statement is an assignment statement. The 
executable statement may be any statement that is also allowed as the operand of a logical IF statement. 

9.17 Notes on Structured Programming Statements 

In addition to the definitions and examples of these constructs, the following points should be noted: 

(i) Any of the new control statements with their blocks may be used within the block of any 

other statement. For example, a WHILE-block may contain another WHILE or an 
IF-THEN-ELSE block. Blocks may be nested in this manner to any level within storage 
limitations. An important exception to this rule is the REMOTE-block A REMOTE-block 
may contain other types of blocks (nested to any level); however, another REMOTE-block 
may not be defined within it. Furthermore, REMOTE-blocks may not be defined within 
another control structure. The following example is illegal. 

Example: 

* Illegal definition of a REMOTE-block. 

IF ( I .EQ. 3 )then 
REMOTE BLOCK A 


END BLOCK 
END IF 

(ii) When nesting blocks, the inner blocks must always be completed with the appropriate 

block-terminating END statement before the outer blocks are terminated. Similarly, when 
nesting blocks with DO-loops, a DO-loop started within a block must be completed before 
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the block is completed. A block started within a DO-loop must be terminated before the 
DO-loop is completed. Indenting the statements of each new block, as shown in the 
examples, is helpful in avoiding invalid nesting and helps to make the structure of the 
program visually obvious. 

(iii) The normal flow of control of the new programming constructs described earlier may be 
altered with standard FORTRAN control statements. For example, the program may exit 
from a block using a GO TO, STOP, RETURN or arithmetic IF statement. However, a 
block may not be entered in the middle through use of any control statement such as GO 
TO or the arithmetic IF. 

Consider the following example. 

Example: 

GO TO 20 

10 IF( X .GT. Y )THEN 

CALL REDUCE( X, Y ) 

20 X = X - 1 

ELSE 

CALL SCALE( X ) 

END IF 

This is an example of an illegal attempt to transfer execution into the middle of an IF-block. 
The statement X = X - 1 is contained within the IF-block and may only be transferred 
to from within the block. 

Example: 

IF( X .GT. Y )THEN 
2 0 CALL REDUCE ( X, Y ) 

X = X - 1 

IF( X .GT. 0 )GO TO 20 

ELSE 

CALL SCALE( X ) 

END IF 

This last example demonstrates a legal transfer of control within an IF-block. However, we 
have seen better ways to express the loop with this IF-block. 

Example: 

IF( X .GT. Y )THEN 
LOOP 

CALL REDUCE( X, Y ) 

X = X - 1 
UNTIL( X .LE. 0 ) 

ELSE 

CALL SCALE( X ) 

END IF 

(iv) Many control structure statements cannot be branched to using a GO TO statement. For a 
list of these statements, see the section entitled "Classifying Statements" on page 9 in the 
chapter entitled "FORTRAN Statements" 

(v) Many control structure statements cannot be the object statement of a logical IF statement, 
or be the last statement of a DO-loop. For a list of these statements, see the section entitled 
"Classifying Statements" on page 9 in the chapter entitled "FORTRAN Statements" 
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10 Input/Output 


10.1 Introduction 


FORTRAN 77 provides a means of communicating information or data between a FORTRAN program 
and the computing environment. The computing environment may include a number of devices which are 
capable of the recording, retrieval, display, and input of data. Disk and magnetic tape devices are capable 
of storing large amounts of data. Other devices such as printers and display terminals can be used to 
present a visual (i.e., human-readable) representation of the data. Yet other devices such as terminal 
keyboards and card-readers make possible the entry of new data into the computing environment. 

For the purposes of our discussion, data is any information which can be processed by an executing 
FORTRAN program. Some examples of data are names, addresses, telephone numbers, credit card 
balances, flight trajectories, bus schedules, athletic records, etc. In computing, such information is usually 
well-organized in order to make it useful for processing. 

To use an example, consider the entries in a telephone book. There are essentially three pieces of data 
listed for each entry; a name, an address, and a number. 


Smith J 32 Arthur St-555-3208 

Smith JW 512 King St-555-9229 

Smith Jack 255-113 Queen St N-555-0572 


Each entry is a record. The organization of the book is clear. The name is always listed first, the address 
second, and the number last. The records are sorted, for our convenience, by name (within each city or 
geographical location). The length of each record is the same. This fixed length does sometimes lead to 
problems since entries which have a long name or address won't fit in a record. The phone company 
solved this by continuing the information in subsequent records. We might have solved this problem by 
increasing the length of a record with the disadvantage of wasting a lot of printing space. Alternatively, we 
could have used a variable length record. This solves the problem of wasted space but creates a severe 
problem when trying to display the records in nice orderly columns. The telephone book itself is a 
collection of records or a file. 

We have introduced much of the terminology of data processing: "data", "records", "fixed and variable 
record sizes", "files", "sorted", etc. 

10.2 Reading and Writing 

FORTRAN provides a mechanism called "reading" for transferring data into the environment of an 
executing program. The READ statement is used to do this. Similarly "writing" is the mechanism for 
transferring data out of an executing program. The WRITE and PRINT statements are used to do this. 
Other statements provide additional functions such as positioning to a certain record in a file, establishing 
which files are to be processed by the program, or making inquiries about files. 
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10.3 Records 


FORTRAN distinguishes between three kinds of records, namely: 

1. Formatted 

2. Unformatted 

3. Endfile 

We shall describe each of these in the following sections. 

10.3.1 Formatted Record 

A formatted record consists of characters. The length of a formatted record is determined by the number of 
characters in it. A formatted record may contain no characters at all and thus has zero length. Formatted 
records are read or written using formatted input/output statements. An excellent example of a file 
consisting of formatted records is our telephone book example. 

10.3.2 Unformatted Record 

An unformatted record consists of values such as integers, real numbers, complex numbers, etc. It may also 
consist of characters. Essentially, these values have the same representation in a record as they have in the 
computer’s memory. The length of an unformatted record depends on the amount of storage required to 
represent these values in the computer’s memory. For example, on this computer an integer value is stored 
using 4 bytes of memory (a byte is a grouping of 8 binary digits). Thus, integer values in unformatted 
records also require 4 bytes of storage. For example, 3 integer values stored in an unformatted record 
would require 12 bytes of storage. Unformatted records are read or written using unformatted input/output 
statements. 

To illustrate the difference between a formatted and unformatted record consider the following example. 
Example: 

INTEGER NUMBER 
NUMBER=12345 
PRINT 100, NUMBER 
100 FORMAT(IX,15) 

WRITE( UNIT=7 ) NUMBER 

If you print the variable NUMBER on a printer, it requires 5 character positions. If you write it to a file 
using an unformatted WRITE statement, it only requires 4 bytes or character positions in the record. Note 
that a character is conveniently represented in one byte of storage, hence we sometimes use the term "byte" 
or "character" interchangeably when talking about the size of variables. 

10.3.3 Endfile Record 

An endfile record is a special record that follows all other records in a file. Simply stated, an endfile record 
occurs at the end of a file. Actually, an endfile record is a conceptual thing. It has no length. When the 
end of a file is reached (i.e., an attempt to read a record results in the endfile record being read), an 
"end-of-file" condition exists. There are no more records following the endfile record. There is only one 
endfile record so it is strictly illegal to attempt to read another record after the endfile record has been read 
(i.e., when the end-of-file condition exists). 
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10.4 Files 


Earlier we described the notion of a file as a collection of records. In FORTRAN, there are two kinds of 
files: 


1. External 

2. Internal 

10.4.1 External Files 

External files are files that exist or can be created upon external media such as disks, printers, terminal 
displays, etc. A file may exist before the execution of a FORTRAN program. It may be brought into 
existence or "created" during execution. It may also be deleted and therefore not exist after the execution 
of a FORTRAN program. 

All input/output statements may refer to files that exist. In addition, the INQUIRE, OPEN, CLOSE, 
WRITE, PRINT, and ENDFILE statements may refer to files that do not exist (and in so doing, may very 
well cause the file to be created). 

Properties of External Files 

Name In FORTRAN, a file may or may not have a name. If it does have a name then, not 

surprisingly, it is called a named file. All files in Open Watcom FORTRAN 77 have names 
and so it may seem odd to introduce this notion. However, we do since the INQUIRE 
statement lets you find out if a file is named and, if so, what its name is. File naming 
conventions may differ from one computing system to the next. As well, different 
FORTRAN 77 compilers may have different file naming conventions. 

Access "Access" simply refers to the way in which we can position to and read or write the data in 

a particular record in a file. There are two ways in which records can be accessed in a file; 
sequentially or directly. 

Using the sequential access method, records may be read or written in order starting with 
the first record and proceeding to the last record. For example, it would be quite 
impossible to read or write the tenth record in a file and then read or write the third record. 
Similarly the eleventh record must be read or written before we can access the twelfth 
record. If we adopt the convention that each record in a file has a record number then the 
first record is record number 1, the second is 2, and so on. This numbering convention is 
important when we look at the other access method which is "direct". 

Using the direct access method, records may be read or written in any order. It is possible 
to read or write the tenth record of a file and then the third and then the twelfth and so on. 

A caveat: a record cannot be read if it has never been written since the file was created. In 
direct access, the idea of a record number is very important and so by convention, we 
number them starting at 1 as the first record and proceeding on up. With direct access, if 
you create a new file and write record number 10 then the file has ten records regardless of 
the fact that only one has been written. You could, at some later time, write records 1 
through 9 (in whatever order you please) and add additional records by writing records with 
record numbers greater than 10. 

Some files have the property of being able to sustain both of these access methods. Some 
files may only have one of these properties. For example, most line printers cannot be 
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accessed directly. You have no choice but to write records sequentially. Sometimes a file 
that was created using the sequential access method may not be accessed using the direct 
method or vice versa. FORTRAN calls this property of a file the "set of allowed access 
methods". 

Record Form Some files have the property of being able to handle both formatted and unformatted record 
formats. Some files may only have one of these properties. For example, if you tried to 
write unformatted records to a line printer, the result might be gibberish. On the other hand 
a graphics printer may readily accept unformatted records for reproducing graphical images 
on paper. FORTRAN calls this property of a file the "set of allowed forms". 

Record Length Another property of a file is record length. Some files may have restrictions on the length 
of a record. Some files do not allow records of zero length. Other files, such as printers, 
may restrict the length of a record to some maximum. FORTRAN calls this property the 
"set of allowed record lengths". 

10.4.2 Internal Files 

Internal files are special files that reside only in memory. They do not exist before or after the execution of 
a FORTRAN program, only during the execution of a program. An internal file allows you to treat 
memory in the computer as if it were one or more records in a file. The file must be a character variable, 
character array element, character array, or character substring. A record in this file may be a character 
variable, character array element or character substring. 

Another way of looking at this is that an internal file that is either a character variable, character array 
element or character substring can contain only one record but an internal file that is a character array can 
contain several records (as many as there are elements in the array). 

Properties of Internal Files 

Records Unless the name of a character array is used, only one record is contained in an internal file. 

The length of this record is the same as the length of the variable, array element, or 
substring. If the file is a character array then each element in the array is a record. The 
order of the records in the file is the same as the order of the elements in the array. The 
length of a record in this case is the same as the length of the character array elements. 

If the number of characters written to a record in an internal file is less than the length of 
the record then the record is padded with blanks. 

Definition A record may be read only if the variable, array element, or substring is defined (i.e., it has 
been assigned some value). Definition may not only result from an output statement such 
as WRITE. It may also be defined through other means; for example, a character 
assignment statement. 

Position For all input/output statements, the file is positioned at the beginning of the first record. 

Multiple records may be read or written using the "slash" format edit descriptor (see the 
chapter entitled "Format" on page 225). 

Restrictions Only sequential access formatted input and output statements ( READ and WRITE) may be 
used to transfer data to and from records in an internal file. 
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Although FORTRAN 77 states that list-directed formatted input/output to an internal file is 
not permitted. Open Watcom FORTRAN 77 allows you to use list-directed formatted 
input/output statements. This is an extension to the language standard. 

Example: 

WRITE(INTFIL,*) X, Y, Z 


No other input/output statements ( OPEN, ENDFILE. REWIND, etc.) may be used. 


Internal files may be used to convert data from one format to another. The following example illustrates 
one use of internal files. 


Example: 

CHARACTER*11 INPUT 

PRINT *, ' TYPE IN "I" FOLLOWED BY AN INTEGER' 

PRINT *, 'OR TYPE IN " R" FOLLOWED BY A REAL' 

READ 100, INPUT 
100 FORMAT( All ) 

IF( INPUT(1:1) .EQ. 'I' )THEN 

READ( UNIT=INPUT(2:11), FMT='(I10)' ) IVAR 

PRINT *, 'AN INTEGER WAS ENTERED ', IVAR 
ELSE IF( INPUT(1:1) .EQ. 'R' )THEN 

READ( UNIT=INPUT(2:11), FMT='(FI0.3)' ) RVAR 

PRINT *, 'A REAL NUMBER WAS ENTERED ', RVAR 
END IF 
END 

After checking for an " I" or "R" as the first character of the character variable INPUT, the appropriate 
internal READ statement is executed. 


10.5 Units 


Many FORTRAN 77 input/output statements refer to external files using a mechanism called the unit. 

There are many units available to the FORTRAN 77 programmer. Open Watcom FORTRAN 77 numbers 
these units from 0 to 999; thus the unit number is a non-negative integer less than 1000. 

A unit may be associated with a particular file. This association is called connection. Any unit may or may 
not be connected to a file. There are a number of ways in which this connection may be established. 

A unit may be preconnected to a file before execution of a program begins. The User’s Guide describes the 
mechanism for preconnecting a unit to a file. 

Alternatively, a unit may become connected to a file by the execution of an OPEN statement. 

All input/output statements except OPEN, CLOSE, and INQUIRE must refer to a unit that is connected to a 
file. Open Watcom FORTRAN 77 automatically establishes a connection of the unit to a file if no 
connection previously existed. Consider the following example in which unit number 1 is not previously 
connected to a file. 
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Example: 

WRITE(1,*) 'Output on unit 1 ' 

END 

Open Watcom FORTRAN 77 constructs a file name using the specified unit number. The format of the file 
name is described in the User’s Guide since it varies from one computer system to the next. 

Connection of a unit to a file does not imply that the file must exist. For example, it could be a new file. 
When we speak of a unit being connected to a file, we can also say that a file is connected to a unit. Under 
the rules of FORTRAN, it is illegal to connect the same file to more than one unit at the same time. 
However, a file may be connected to different units at different times. We shall explain how this is 
possible. 

A file may be disconnected from a unit by the use of the CLOSE statement. 

Example: 

CLOSE(UNIT=1) 

Under certain circumstances, the file may be disconnected from a unit by the use of the OPEN statement. 
Example: 

OPEN(UNIT=1,FILE=' FILEI ’ ) 


OPEN(UNIT=1,FILE=' FILE2' ) 

In the above example, the second OPEN statement disconnects unit 1 from one file and connects it to a 
second file. You may think of the second OPEN statement as automatically closing the first file and then 
establishing a connection to the second file. 

If a unit has been disconnected from a file through the execution of a CLOSE statement, the unit may 
subsequently be connected to the same file or to a different file. It also follows that a file which has been 
disconnected from one unit number may be connected to the same unit number or a different unit number. 
The following example may help to illustrate this last point. 

Example: 

OPEN(UNIT=1,FILE=' FILE1' ) 


CLOSE(UNIT=1) 

OPEN(UNIT=2,FILE=' FILE1' ) 

Once a file has been disconnected, the only means for referring to the file is by its name in an OPEN 
statement or an INQUIRE statement. 
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10.6 Specifiers 

All input/output statements contain one or more specifiers. They appear in a list separated by commas. 
Some of the more common specifiers are those listed below. Not all of them need be used in every 
input/output statement. You should consult the description of the input/output statement under 
consideration to discover which specifiers are allowed and what they mean. 

[UNIT =] u the unit specifier 

[FMT =]f the format specifier 

REC = rn the record specifier 

IOSTAT = ios the input/output status specifier 

ERR = s the error specifier 

END = s the end-of-file specifier 

We shall look at these specifiers in more detail. 

10.6.1 The Unit Specifier 

The form of a unit specifier in an input/output statement is: 

[UNIT =] u u is an external unit identifier or an internal file identifier. 

1. An external unit identifier is a non-negative integer expression or an asterisk 

(*) in which case unit 5 is assumed for an input statement and unit 6 is assumed 
for an output statement. The unit identifier must not be an asterisk for the 
BACKSPACE. ENDFILE and REWIND statements. 

2. An internal file identifier is the name of a character variable, character array, 
character array element, or character substring. 

If the optional UNIT= specifier is omitted then the unit specifier must be the first item in the list of 
specifiers. 

10.6.2 Format Specifier 

The form of a format specifier in an input/output statement is: 

[FMT =]f f is a. format identifier. A format identifier is one of the following: 

1. A statement label of a FORMAT statement that appears in the same program unit 
as the format identifier. 

2. An integer variable name that has been assigned the statement label of a 
FORMAT statement that appears in the same program unit as the format identifier 
(see the ASSIGN statement). 

3. An integer array name. 

4. A character array name. 
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5. Any character expression except one involving the concatenation of an operand 
whose length specification is (*) unless the operand is a symbolic constant (see 
the PARAMETER statement). 

6. An asterisk (*) , indicating list-directed formatting. 

7. A NAMELIST name, indicating namelist-directed formatting. 

If the optional FMT= specifier is omitted then the format specifier must be the second item in the list of 
specifiers and UNIT= must not be specified for the first item in the list. 

10.6.3 Record Specifier 

The form of a record specifier in an input/output statement is: 

REC = rn rn is an integer expression whose value must be positive. It is the number of the record to 
be read when a file is connected for direct access. 

10.6.4 Input/Output Status Specifier 

The form of an input/output status specifier in an input/output statement is: 

IOSTAT = ios ios is an integer variable or integer array element. It is defined with zero if no error 
occurs, a positive integer value if an error occurs, or a negative integer value if an 
end-of-file occurs. 

If an input/output error or end-of-file condition occurs during the execution of an input/output statement 
and the input/output status specifier is present then execution of the program is not terminated. 

Input/output errors may result from a violation of the rules of FORTRAN or from a file system error. For 
example, a negative unit number will result in an error since this is a violation of the rules of FORTRAN. 
An example of a file system error might be an attempt to create a file on a non-existent file storage device. 

Consult the User’s Guide for a list of Open Watcom FORTRAN 77 diagnostic messages. An input/output 
status of nn corresponds to the message IO-nn . For example, if the status returned is 3 then the error is: 

10-03 ENDFILE statement requires sequential access mode 

10.6.5 Error Specifier 

The form of an error specifier in an input/output statement is: 

ERR = s s is a statement label. When an error occurs, execution is transferred to the statement 

labelled by s. 

If an input/output error occurs during the execution of an input/output statement and the ERR= specifier is 
present then execution of the program is not terminated. 
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10.6.6 End-of-File Specifier 

The form of an end-of-file specifier in an input/output statement is: 

END = s s is a statement label. When an end-of-file condition occurs, execution is transferred to the 

statement labelled by s . 

If an end-of-file condition occurs during the execution of an input/output statement and the END= specifier 
is present then execution of the program is not terminated. 

10.7 Printing of Formatted Records 

Printing occurs when formatted records are transferred to a device which interprets the first character of the 
record as a special spacing command. The remaining characters in the record are "printed". Printing can be 
accomplished by use of either the PRINT statement or the WRITE statement. What actually determines 
whether or not you are "printing" is the device (or file) to which records are transferred. 

The first character of the record controls the vertical spacing. This feature is quite often called ASA 
(American Standards Association) carriage control. 


Character 

Vertical Spacing Before Printing 

Blank 

One Line 

0 

Two Lines 

- 

Three Lines 

1 

To First Line of Next Page 

+ 

No Advance 


The " control character is an extension to the FORTRAN 77 language that is supported by many 
"printing" devices. 
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11.1 Introduction 


A format specification used in conjunction with formatted I/O provides a means of specifying the way 
internal data is converted to a character string and vice versa. A format specification can be given in two 
ways. 

1. In a FORMAT statement. 

2. As values of character expressions or character arrays. 

11.2 The FORMAT Statement 


The form of a FORMAT statement is 


label FORMAT fs 


where: 

label is the statement label used by an I/O statement to identify the FORMAT statement. 

fs is a format specification which will be described later. 

Example: 

REAL X 
X = 234.43 
PRINT 100, X 
100 FORMAT(F10.2) 

END 


In the previous example, the PRINT statement uses the format specification in the FORMAT statement 
whose statement label is 100 to display the value of X. 

11.3 FORMAT as a Character Expression 

Instead of specifying the statement label of a FORMAT statement, a character expression can be used. The 
previous example could be modified as follows and achieve the identical result. 
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Example: 

REAL X 

X = 234.43 

PRINT '(F10.2)', X 

END 


When using a character expression to represent a format specification, the format specification can be 
preceded by blank characters and followed by any character data without affecting the format specification. 
The following example produces the identical result to the previous example. 


Example: 

REAL X 
X = 234.43 

PRINT ' (F10.2) THIS IS FOR X', X 

END 


If a character array is used to describe the format specification, the format specification is considered to be 
the concatenation of all the character array elements in the order given by array element ordering described 
in the chapter entitled "Arrays" on page 159. Note that if a character array element is used, the format 
specification is considered to be only that array element. 


Example: 

REAL X 

CHARACTER*5 FMTSPEC(3) 
X = 234.43 
FMTSPEC(1)=' (' 

FMTSPEC(2)='F10.2' 
FMTSPEC(3)=')' 

PRINT FMTSPEC, X 
END 


11.4 Format Specification 

A format specification has the following form. 


( [flist] ) 


where: 

flist is a list whose items are separated by commas. The forms of the items in flist are: 

[r] ed 
ned 
[r] f s 

ed is a repeatable edit descriptor. 

ned is a nonrepeatable edit descriptor. 
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fs is a format specification with a nonempty list f list. 

r is a positive unsigned integer constant called a repeat specification. 

The comma separating the items of f list can be omitted in the following cases. 

1. Between a P edit descriptor and an F, E, D or G edit descriptor which immediately follows. 

2. Before or after a slash edit descriptor. 

3. Before or after a colon edit descriptor. 

Open Watcom FORTRAN 77 allows the omission of a comma between the items of f list. Care should 
be taken when omitting commas between edit descriptors. For example, the format specification (15 
213) may appear to be an 15 edit descriptor followed by two 13 edit descriptors when in actuality it is 
interpreted as an 152 edit descriptor followed by an 13 edit descriptor. 


11.5 Repeatable Edit Descriptors 

The forms of repeatable edit descriptors are: 

Iw 

Iw.m 
Fw. d 
Ew. d 
Ew.dEe 
Dw. d 
Gw. d 
Gw.dEe 
Lw 
A 
Aw 


As an extension to the FORTRAN 77 language, the following repeatable edit descriptors are also 
supported. 

Ew.dDe 
Zw 


where: 


I, F, E, D, G, L, A and Z indicate the method of editing, 
w and e are positive unsigned integer constants, 
d and m are unsigned integer constants. 
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11.6 Nonrepeatable Edit Descriptors 

The forms of nonrepeatable edit descriptors are: 

'hh...h' (apostrophe) 
nHhh...h 
Tc 
TLc 
TRc 
nX 
/ 

S 

SP 

ss 

kP 

BN 

BZ 

X 


As an extension to the FORTRAN 77 language, the following nonrepeatable edit descriptors are also 
supported. 

$ 

\ 


where: 


Apostrophe, H, T, TL, TR, X, /, S, SP, SS, P, BN, BZ, \ and $ indicate the 
method of editing. 

h is a character. 

n and c are positive unsigned integer constants, 
k is an optionally signed integer constant. 

Open Watcom FORTRAN 77 allows edit descriptors to be specified using lower case letters. 

11.7 Editing 

Edit descriptors are used to describe the way the editing between internal representation of data and the 
characters of a record in a file is to take place. When the edit descriptors I, F, E, D, G, L, A, H, 
Z or apostrophe are processed, they process a sequence of characters called a field. On input, the field is 
the character data read from a record; on output it is the character data written to a record. The number of 
characters in a field is called the field width. 
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11.7.1 Apostrophe Editing 

The apostrophe edit descriptor has the same form as a character constant and can only be used on output. 

It causes the characters in the format specification enclosed in quotes to be written. The field width is the 
number of characters enclosed in quotes. 

Example: 

PRINT ' ("HI THERE' ' ) ' 

END 

In the previous example, the string 
HI THERE 

would be the output produced by the PRINT statement. 

11.7.2 H Editing 

The nH edit descriptor causes the n characters following the H, including blanks, to be written. Like the 
apostrophe edit descriptor, it can only appear in a format specification used for output. 

Example: 

PRINT '(8HHI THERE)' 

END 

In the previous example, the string 
HI THERE 

would be the output produced by the PRINT statement. 

11.7.3 Positional Editing: T, TL, TR and X Editing 

The T, TL, TR and X edit descriptors specify at which position the next character will be read from or 
written to the record. In the case of input, this allows data to be read more than once with different edit 
descriptors. On output, it is possible to overwrite data previously written. 

On output it is possible to use positional editing to create a record in which gaps appear. That is, there may 
be parts of the record where no data has been written. The parts of a record in which no data has been 
written are filled with blanks. The effect is as if the record was previously initialized to blanks. Note that 
positioning does not cause any data to be transmitted. 

The Tc edit descriptor specifies that the next character to be transmitted is to be from the cth character 
position in the record. The TLc edit descriptor specifies that the next character to be transmitted is to be 
from the cth position backward from the current position. The TRc edit descriptor is identical to the TLc 
edit descriptor except that positioning is forward from the current position. The nX edit descriptor behaves 
identically to the TRc edit descriptor; the transmission of the next character is n character positions forward 
from the current position. If n is omitted then the transmission of the next character is 1 character position 
forward from the current position. 
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Example: 

PRINT ' (' ' THE NUMBER IS AN INTEGER' ' ,TL19, 

$ ''12345'')' 

END 

The output produced is 

THE NUMBER 12345 IS AN INTEGER 

11.7.4 Slash Editing 

The slash edit descriptor indicates the end of data transfer on the current record. On input from a record 
connected for sequential access, the remaining characters in the record are skipped and the file is positioned 
to the start of the next record. Note that entire records may be skipped. On output, a new record is created 
and becomes the last and current record of the file. Note that a record with no characters can be written. If 
the file is an internal file or a direct access file, the record is filled with blanks. 

For a file connected for direct access, the current record number is increased by one and the file is 
positioned at the beginning of that record. 

11.7.5 Colon Editing 

The colon edit descriptor terminates processing of the format specification if there are no more items in the 
I/O list. If there are items remaining in the I/O list, the colon edit descriptor has no effect. 

11.7.6 S, SP and SS Editing 

The S, SP and SS edit descriptors control optional plus characters in numeric output fields. They only 
effect the I, F, E, D and G edit descriptors during output and have no effect on input. The FORTRAN 77 
standard specifies that before processing a format specification, the appearance of a plus sign in numeric 
output fields is optional and is determined by the processor. Open Watcom FORTRAN 77 does not 
produce plus signs in numeric output fields. When an SP edit descriptor is encountered, a plus sign is 
produced in any subsequent position that optionally contains a plus sign. When as SS edit descriptor is 
encountered, a plus sign is not produced in any subsequent position that optionally contains a plus sign. If 
an S edit descriptor is encountered, the option is returned to the processor. 

Example: 

PRINT ' (1H<, 15, SP, 15, SS, 15, 1H>)',1, 2,3 
END 

The output produced by the PRINT statement in the previous example is: 

< 1+2 3> 

11.7.7 P Editing 

The form of a P edit descriptor is kP where k is an optionally signed integer constant called the scale 
factor. The value of the scale factor is zero at the beginning of each I/O statement. The scale factor applies 
to all subsequent F, E, D and G edit descriptors until another scale factor is encountered. The scale factor 
affects editing in the following way. 
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1. On input with F, E, D and G editing, provided that no exponent exists in the field, the effect is 
that the represented number equals the internally represented number multiplied by 10 * *k. 

2. On input with F, E, D and G editing, the scale factor has no effect if there is an exponent in the 
field. 

3. On F output editing, the effect is that the represented number equals the internally represented 
number multiplied by 10 * * k. 

4. On output with E and D editing, the simple real constant (see the chapter entitled "Names, Data 
Types and Constants" on page 151) part of the data is multiplied by 10**k and the exponent is 
reduced by k. 

5. On output with G editing, the scale factor has no effect unless the magnitude of the datum is 
outside the range that allows F editing (see the section entitled "G Editing" on page 235). If E 
editing is required, the scale factor has the same effect as with E output editing. 

11.7.8 BN and BZ Editing 

The BN and BZ edit descriptors are used to describe the interpretation of embedded blanks in numeric input 
fields. They only effect I, F, E, D and G editing and have no effect during output. When a BN edit 
descriptor is encountered in a format specification, embedded blanks in subsequent numeric input fields are 
ignored. However, a field of all blanks has the value of zero. If a BZ edit descriptor is encountered, then 
all embedded blanks in subsequent numeric input fields are treated as zeroes. At the beginning of each I/O 
statement, all blanks are treated as zeroes or ignored depending on the value of the BLANK= specifier (see 
the OPEN statement) currently in effect for the unit. 

11.7.9 $ or 1 Editing (Extension) 

The $ and \ edit descriptors behave identically. The $ and \ edit descriptors are intended for output to an 
interactive device such as a terminal. They are a Open Watcom FORTRAN 77 extensions. The output 
record is displayed at the terminal leaving the cursor at the end of the record; the carriage return at the end 
of the line is suppressed. Its use is intended for prompting for input so that the response can be entered 
immediately following the prompt. 

Depending on the type of terminal, the prompt may be returned as part of the input. An application must be 
aware of the way a particular terminal behaves. The following example demonstrates this. Note that the 
format specification in the FORMAT statement labelled 2 0 ignores the first eleven characters of the 
response since the prompt also appears in the response. 

Example: 

INTEGER AGE 
WRITE(6,FMT=10) 

10 FORMAT( 'Enter age: ',$ ) 

READ(5,20) AGE 
20 FORMAT( 11X, 12 ) 

PRINT *,'Your age is ' , AGE 
END 

If the terminal you are using does not return the prompt as part of the response (that is, a read from the 
terminal only includes characters typed at the terminal), the format specification in the FORMAT statement 
labelled 2 0 must be changed, as in the following example, to achieve the same result. 
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Example: 



INTEGER AGE 

WRITE(6,FMT=10) 


10 

FORMAT( 'Enter age: ' 
READ(5,20) AGE 

,\/ ) 

20 

FORMAT( 12 ) 



PRINT *,'Your age is 
END 

' , AGE 


11.7.10 Numeric Editing: I, F, E, D and G Edit Descriptors 

Numeric edit descriptors are used to specify I/O of integer, real, double precision, complex and double 
precision complex data. The following rules apply to all numeric edit descriptors. 

1. On input, leading blanks are not significant. The interpretation of blanks other than leading 
blanks is determined by any BN or BZ edit descriptors in effect and the BLANK= specifier (see 
the OPEN statement). A field of all blanks is always zero. Plus signs are optional. 

2. On input, with F, E, D and G editing, the decimal location specified in the edit descriptor is 
overridden by a decimal point appearing in the input field. 

3. On output, the plus sign is optional and is determined by the S, SP and SS edit descriptors. A 
negative quantity is represented by a negative sign. A minus sign is never produced when 
outputting a value of zero. 

4. On output, the representation is always right justified in the field with leading blanks inserted at 
the beginning of the field if the number of characters in the representation is less than the field 
width. 

5. On output, if the number of characters in the external representation is greater than the field 
width or an exponent exceeds its specified length using Ew.dEe, Gw.dEe, Ew.dDeor 
Gw. dDe edit descriptors, the entire field is filled with asterisks. 

11.7.10.11nteger Editing: Iw and Iw.m Edit Descriptors 

The Iw and Iw.m edit descriptors indicate that the field width of the field to be edited is w . The item in 
the I/O list must be of type integer; on input the I/O list item will be defined by integer data, on output the 
I/O list item must be defined with an integer datum. 

On input, the Iw.m edit descriptor is treated identically to the Iw edit descriptor. The output field for the 
Iw edit descriptor consists of zero or more leading blanks followed by a minus sign if the value of the I/O 
list item is negative or an optional plus sign otherwise, followed by the magnitude of the integer datum with 
no leading zeroes. Note that the integer constant contains at least one digit. On output, the Iw.m edit 
descriptor specifies that at least m digits are to be displayed with leading zeroes if necessary. The value of 
m must be less than or equal to the value of w. If m is zero and the value of the datum is zero, then the 
output field is filled with blanks. 

Example: 

PRINT '(1H<,14.4,15,1H>)',23,2345 
The output produced by the PRINT statement in the previous example is the string: 

<0023 2345> 
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11.7.10.2 Floating-point Editing: F, E, D and G Edit Descriptors 

The F , E , D and G edit descriptors describe the editing of real, double precision, complex and double 
precision complex data. The I/O list item corresponding to one of these edit descriptors must be of type 
real, double precision, complex or double precision complex. On input, the I/O list item will become 
defined with a datum whose type is the same as that of the I/O list item. On output, the I/O list item must 
be defined with a datum whose type is that of the I/O list item. 

11.7.10.3 F Editing 

An F edit descriptor has the form Fw . d where w is the field width and d is the number of digits in the 
fractional part. The input field consists of an optional sign, followed by a string of digits optionally 
containing a decimal point. If the decimal point is omitted, the rightmost d digits with leading zeroes 
assumed if necessary, are interpreted as the fractional part of the value represented. An exponent of one of 
the following forms may follow. 

1. A signed integer constant. 

2. An E or D followed by an optionally signed integer constant. 

Consider the following example, where the decimal point is omitted. The formula used in the evaluation is: 

-d (exponent subfield) 

(integer subfield) x 10 x 10 

If the specification is F10.8 and the input quantity is 31415E+5 then the following conversion takes place. 

-8 5 

00031415 x 10 x 10 
5 

.00031415 x 10 
31.415 

In other words, the decimal point is assumed to lie to the left of the 8 digits (padded with zeroes on the left) 
forming the fractional part of the input value. 

The output field produced by an F edit descriptor consists of blanks if necessary followed by a minus sign 
if the item in the I/O list is negative or an optional plus sign otherwise, followed by a string of digits 
containing a decimal point which represents the magnitude of the I/O list item. The string representing the 
magnitude of the I/O list item is modified according to the scale factor and is rounded to d fractional digits. 
An optional leading zero is produced only if the magnitude of the I/O list item is less than one. Note that a 
leading zero is required if there would otherwise be no digits in the output field. 

Example: 

PRINT '(1H<, F8 . 4, 1H>) ', 234.43 
The output produced by the PRINT statement in the previous example is the string: 

<234.4300> 
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11.7.10.4 E and D Editing 

The Ew. d, Dw. d and Ew. dEe edit descriptors indicate that the field width is w, the fractional part 
contains d digits unless a scale factor greater than one is in effect, and the exponent consists of e digits. 
The e has no effect on input. 

The form of the input field and processing of it is the same as that for F editing. The form of the output 
field is: 


[ + ] [0] 

. X 

X . . 

. . x exp 

[-] 

1 

2 

d 


where: 

p indicates a plus or minus sign. 

x’s are the d most significant digits of the value after rounding. 
exp is a decimal exponent. 

The form of the exponent is as follows. 

1. When using the Ew. d edit descriptor, the form of the exponent is 

E+nn 

or if |exp| <= 99 

E-nn 

and 

+nnn 

or if 99 < |exp| <= 999 

-nnn 

2. When using the Ew. dEe edit descriptor, the form of the exponent is 

E+n ... n where |exp| <= (10**e)-l 
- 1 e 

3. When using the Dw. d edit descriptor, the form of the exponent is 

D+nn 

or if |exp| <= 99 

D-nn 

and 

+nnn 

or if 99 < |exp| <= 999 

-nnn 

Note that a sign in the exponent is always present. If the exponent is 0, a plus sign is used. The forms 
Ew. d and Dw. d are not to be used if | exp | > 999. 
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Example: 

PRINT ' (1H<,E10.4, 1H>, 1H<,E9.4, 1H>, 1H<,E12.4E3, 1H>) ' , 

$ .5, .5, .5 

END 

The output from the PRINT statement in the previous example is the string: 

<0.5000E+00X. 5000E+00X 0.5000E+000> 

The scale factor k in a P edit descriptor controls decimal normalization as follows: 

1. If-d < k <= 0 , then the output field contains | k | leading zeroes and d- | k | significant 
digits after the decimal point. 

2. If 0 < k < d+2 , the output field contains exactly k significant digits to the left of the 
decimal point and d-k+1 significant digits to the right of the decimal point. 

3. Other values of k are not permitted. 

The Ew. dDe edit descriptor behaves in the same way as the Ew. dEe edit descriptor on input; on output 
the only difference is that the letter D is used to mark the exponent instead of the letter E . 

11.7.10.5 G Editing 

The Gw. d and Gw. dEe edit descriptors indicate that the field width is w, the fractional part contains d 
digits unless a scale factor greater than one is in effect, and the exponent consists of e digits. 

G input editing is the same as F input editing. 

The representation on G output editing depends on the magnitude of the datum being edited. Let M be the 
magnitude of the datum being edited. Then G output editing behaves as follows. 

1. If M < 0 . 1 or M >= 10**d, Gw . d output editing is equivalent to kPEw. d output editing 
and Gw. dEe output editing is equivalent to kPEw. dEe output editing where k is the scaling 
factor currently in effect. 

2. If 0 . 1 <= M < 10 * * d , the scale factor has no effect and the value of M determines the 
editing as shown in the following table. 


Magnitude of Datum 

Equivalent Edit Descriptor 

0.1<=M<1 

F<w-n>.d followed by n blanks 

1<=M<10 

F<w-n>.<d-l> followed by n blanks 

10**(d-2)<=M<10**(d-l) 

F<w-n>. 1 followed by n blanks 

10**(d-l)<=M<10**d 

F<w-n>.0 followed by n blanks 


where: 

<w-n> stands for the integer represented by evaluating w-n . 

<d-l> stands for the integer represented by evaluating d-1. 
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n is 4 for Gw. d editing and e+2 for Gw. dEe editing. 

Example: 

PRINT '(1H<,G12.6,1H>,1H<,G12.4E4,1H>)', .5, .5 

END 

The output from the PRINT statement in the previous example is the string: 

<0.500000 ><0.5000 > 

11.7.10.6 Complex Editing 

Since a complex datum consists of a pair of real or double precision data, the editing of a complex datum is 
specified by two successive pairs of F, E, D or G edit descriptors. The two descriptors may be different 
and may be separated by any number of non-repeatable edit descriptors. Double precision complex editing 
is identical to complex editing. 

11.7.11 L Edit Descriptor 

The Lw edit descriptor is used for I/O list items of type logical. The field width is w . 

On input the I/O list item will become defined with a datum of type logical. The input field consists of 
optional blanks, followed by an optional decimal point followed by a T or F for true or false respectively. 
The T and F may be followed by additional characters in the field. Open Watcom FORTRAN 77 allows t 
and f in addition to T and F on input. 

On output, the I/O list item must be defined with a datum of type logical. The output field consists of w-1 
blanks followed by a T for true or F for false. 

Example: 

PRINT '(1H<,L3,L5,1H>)',.TRUE.,.FALSE. 

The output produced by the PRINT statement in the previous example is the string: 

< T F> 

11.1.12 A Edit Descriptor 

The A [ w ] edit descriptor is used for I/O list items of type character. On input, the I/O list item becomes 
defined with character data. On output, the I/O list item must be defined with character data. If w is 
specified in the edit descriptor, the field width is w otherwise the field width is the number of characters in 
the I/O list item. 

Open Watcom FORTRAN 77 also permits I/O list items of non-character data types. On input, the I/O list 
item becomes defined with the binary representation of the character data. On output, the I/O list item is 
assumed to be defined with character data. 

If len is the length of the I/O list item and w is specified in A input editing so that w is greater than len, 
the rightmost len characters of the input field will be taken. If w is less than len, then the w characters in 
the input field will be taken and padded with len-w blanks. 
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If w is specified in A output editing so that w is greater than len, then the output field will consist of 
w-len blanks followed by the len characters of the I/O list item. If w is less than or equal to len, the 
output field will consist of the first w characters of the I/O list item. 

Example: 

PRINT ' (1H<,A5,A8,1H>)','ABCDEFG' , '123' 

The output produced by the PRINT statement in the previous example is the string: 

<ABCDE 123> 

11.7.13 Z Editing (Extension) 

The Zw edit descriptor is used to display the hexadecimal representation of data or read hexadecimal data. 
It is a Open Watcom FORTRAN 77 extension. The Zw edit descriptor can be used for I/O list items of any 
type. The field width is w. 

On output, w must be greater than or equal to twice the size (in bytes) of the I/O list item since each byte is 
represented by two hexadecimal digits. For example, real data requires four bytes. Hence, w must be at 
least eight. 

Example: 

PRINT '(1H<,Z8,1H>)', 256 

The output produced by the PRINT statement in the previous example is the string: 

< 00000100 > 

If w is greater then the number of hexadecimal digits required to represent the data, the leftmost print 
positions of the output field are filled with blanks. 

Example: 

PRINT '(1H<,Z10,1H>)','ABCD' 

The output produced by the PRINT statement in the previous example is the string 

< C1C2C3C4> 

if the EBCDIC character set is being used or 

< 41424344> 

if the ASCII character set is being used. 

On input, if w is greater than twice the size (in bytes) of the I/O list item, the leftmost characters are 
truncated from the input field. For example, if the input field contains the string 

91A2C3D4 

and is read into a character variable whose length is two, the character would contain the hexadecimal data 
C3D4 . If w is less than twice the size (in bytes) of the I/O item, the I/O item is padded to the left with 
hexadecimal zeroes. For example, if the input field contains the string 

81C1 
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and is read into a character variable whose length is four, the character would contain the hexadecimal data 
000081C1. 


11.8 Format-Directed Input/Output 

Format-directed input/output (I/O) is formatted input or output controlled by a format specification. The 
action taken during formatted input or output depends on the next edit descriptor in the format specification 
and the next item in the input/output list if one exists. 

A format specification is processed from left to right. An edit descriptor or a format specification with a 
repeat specification of r is processed as a list of r edit descriptors or format specifications. A repeat 
specification of one is equivalent to no repeat specification. 

For each repeatable edit descriptor in the format specification, there corresponds one item in the I/O list 
except an I/O list item of type complex where two repeatable floating-point edit descriptors are required. 
Non-repeatable edit descriptors do not correspond to any I/O list item; they communicate information 
directly with the record. Whenever a repeatable edit descriptor is encountered in a format specification, 
there must be a corresponding item in the I/O list. The edited information is transmitted appropriately 
between the item and the record. 

Format processing is terminated when any of the following conditions occur. 

1. When an edit descriptor has no corresponding item in the I/O list. 

2. When a colon edit descriptor is encountered and there are no more items in the I/O list. 

3. When the right parenthesis is encountered and there are no more items in the I/O list. 

If the right parenthesis of the complete format specification is encountered and the I/O list has not been 
exhausted, the file is positioned at the next record and format processing resumes at the start of the format 
specification terminated by the last preceding right parenthesis. If there is no such right parenthesis, format 
processing resumes at the start of the complete format specification. The part of the format specification 
that is reused must contain at least one repeatable edit descriptor. If format processing resumes at a left 
parenthesis preceded by a repeat specification, the repeat specification is also reused. The scale factor, sign 
control edit descriptors and blank control edit descriptors are not affected when part of a format 
specification is reused. 

11.9 List-Directed Formatting 

List-directed formatting is input/output without a format specification. 

Example: 

READ ( un, * ) X, Y, Z 

READ( UNIT=un, FMT=* ) X, Y, Z 

READ *, X, Y, Z 

WRITE( un, * ) X, Y, Z 

WRITE( UNIT=un, FMT=* ) X, Y, Z 

PRINT *, X, Y, Z 

In the previous example, an asterisk instead of a format specification indicates list-directed formatting. 
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Omitting the asterisk and format specification also indicates list-directed formatting. 
Example: 

READ, X, Y, Z 
PRINT, X, Y, Z 


Records used during list-directed formatting are called list-directed records. A list-directed record is a 
sequence of values and value separators. Any sequence of blanks is treated as a single blank except when it 
appears in a character constant. The end of a record has the same effect as a blank character. 

A value is one of the following: 

1. A constant. 

2. A null value. 

3. r*c 

4. r* 

where: 

r is an unsigned, nonzero integer constant. 

c is a constant. 

The r*c form is equivalent to r successive occurrences of c . The r* form is equivalent to r successive 
occurrences of the null value. In these two forms, blanks are permitted only where they are allowed in the 
constant c. 

A value separator is one of the following: 

1. A comma preceded and followed by any number of blanks. 

2. A slash preceded and followed by any number of blanks. A slash as a value separator terminates 
the execution of the input statement. The definition status of the remaining input items in the 
input list remains the same as it was prior to the input statement. 

3. Any number of blanks between two values. 

A null value is specified by having no character between successive value separators, no characters 
preceding the first value separator in a record or the r* form. It has no effect on the current value of the 
input item. Note that the end of record following a value separator does not specify a null value. 

11.9.1 List-Directed Input 

The input forms acceptable to format specifications for a given type are also acceptable for list-directed 
formatting with certain exceptions. 

1. Blanks are never used as zeroes and blanks embedded in constants are not allowed except in 
character constants. 

2. An input item of type real or double precision must have an input field suitable for F editing 
except that no fractional digits are assumed unless a decimal point is present in the field. Such a 
field will be called a numeric input field. 
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3. An input item of type complex or double precision complex must consist of a left parenthesis 
followed by two numeric input fields separated by a comma and followed by a right parenthesis. 
The numeric input fields may be preceded or followed by blanks. The end of record can only 
appear between the first numeric field and the comma or between the comma and the second 
numeric field. Note that a null value must not be used as the real or imaginary part but may 
represent the entire complex constant. 

4. An input item of type logical must not include either a slash or a comma among the optional 
characters allowed in L editing. 

5. An input item of type character consists of a non-empty string of characters enclosed in 
apostrophes. Apostrophes in character constants are represented by two consecutive apostrophes 
without a blank or end of record separating them. Character constants may span records. If this 
is the case, the end of record does cause a blanks to be inserted into the character constant. Note 
that a comma or slash in a character constant is not a value separator. A character input field is 
assigned to a character input item as though it were a character assignment. 


11.9.2 List-Directed Output 

The form of the output field produced by list-directed output is similar to the form required by list-directed 
input. The output of a character constant does not include the enclosing quotes and an apostrophe in a 
character constant is output as a single apostrophe. The values are separated by one or more blanks. When 
printed, each record will start with a blank if the file is a carriage-control oriented file. For example, the 
source listing file produced by Open Watcom FORTRAN 77 is such a file. 

11.10 Namelist-Directed Formatting (Extension) 

The READ, WRITE, and PRINT statements may be used to transmit data between a file and the variables 
specified in a NAMELIST statement. 


Example: 


CHARACTER*20 
CHARACTER*20 
CHARACTER*15 
CHARACTER*20 
CHARACTER*20 
CHARACTER*10 
INTEGER AGE 
INTEGER MARKS 
NAMELIST /nl/ 


NAME 

STREET 

CITY 

STATE 

COUNTRY 

ZIP_ CODE 

( 10 ) 

NAME, STREET, 
COUNTRY, ZIP_ 


CITY, 

CODE, 


STATE, 

AGE, MARKS 


READ( un, nl ) 

READ( UNIT=un, FMT=nl ) 
READ nl 

WRITE( un, nl ) 

WRITE( UNIT=un, FMT=nl ) 
PRINT nl 
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11.10.1 Namelist-Directed Input (Extension) 

The input data must be in a special format. The first character in each record must be blank. The second 
character in the first record of a group of data records must be an ampersand (&) or dollar sign ($) 
immediately followed by the NAMELIST name. The NAMELIST name must be followed by a blank and 
must not contain any imbedded blanks. This name is followed by data items, optionally separated by 
commas. The end of a data group is signaled by the character "&" or optionally followed by the string 
"END". If the "&" character was used to start the group, then it must be used to end the group. If the "$" 
character was used to start the group, then it must be used to end the group. 

12345678901234567890... 

&NL 

iteml, item2, item3, 
item4, item5, ... 


The form of the data items in an input record is: 

Name = Constant 

The name may be a variable name, an array element name, or a character substring name. 
The constant may be integer, real, complex, logical or character. Logical constants may be 
in the form "T" or ".TRUE" and "F" or ".FALSE". Character constants must be contained 
within apostrophes. Subscripts and substring indices must be of integer type. 

ArrayName = Set of Constants 

The set of constants consists of constants of the type integer, real, complex, logical or 
character. The constants are separated by commas. The number of constants must be less 
than or equal to the number of elements in the array. Successive occurrences of the same 
constant may be represented in the form r*constant, where r is a non-zero integer 
constant specifying the number of times the constant is to occur. Consecutive commas 
within a list indicate that the values of the array elements remain unchanged. 

The variable and array names specified in the input file must appear in the NAMELIST list, but the order is 
not important. A name that has been made equivalent to a name in the input data cannot be substituted for 
that name in the NAMELIST list. The list can contain names of items in COMMON but must not contain 
dummy argument names. 

Each data record must begin with a blank followed by a complete variable or array name or constant. 
Embedded blanks are not permitted in names or constants. Trailing blanks after integers and exponents are 
treated as zeros. 


Example: 

&PERSON 

NAME = 'John Doe' 

STREET = '22 Main St.' CITY = 'Smallville' 
STATE = 'Texas' COUNTRY = 'U.S.A.' 

ZIP_ CODE = ' 78910-1203' 

MARKS = 73, 82, 3*78, 89, 2*93, 91, 88 
AGE =23 
SEND 


The input forms acceptable to format specifications for a given type are also acceptable for 
namelist-directed formatting with certain exceptions. 
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1. Blanks are never used as zeroes and blanks embedded in constants are not allowed except in 
character constants. 

2. An input item of type real or double precision must have an input field suitable for F editing 
except that no fractional digits are assumed unless a decimal point is present in the field. Such a 
field will be called a numeric input field. 

3. An input item of type complex or double precision complex must consist of a left parenthesis 
followed by two numeric input fields separated by a comma and followed by a right parenthesis. 
The numeric input fields may be preceded or followed by blanks. The end of record can only 
appear between the first numeric field and the comma or between the comma and the second 
numeric field. Note that a null value must not be used as the real or imaginary part but may 
represent the entire complex constant. 

4. An input item of type logical must not include either a slash or a comma among the optional 
characters allowed in L editing. 

5. An input item of type character consists of a non-empty string of characters enclosed in 
apostrophes. Apostrophes in character constants are represented by two consecutive apostrophes 
without a blank or end of record separating them. Character constants may span records. If this 
is the case, the end of record does cause a blank to be inserted into the character constant. Note 
that a comma or slash in a character constant is not a value separator. A character input field is 
assigned to a character input item as though it were a character assignment. 

11.10.2 Namelist-Directed Output 

The form of the data items in an output record is suitable for input using a namelist-directed READ 
statement. 

1. Output records are written using the ampersand character (&), not the dollar sign ($), although 
the dollar sign is accepted as an alternative during input. That is, the output data is preceded by 
"&name" and is followed by "&END". 

2. All variable and array names specified in the NAMELIST list and their values are written out, 
each according to its type. 

3. Character data is enclosed in apostrophes. 

4. The fields for the data are made large enough to contain all the significant digits. 

5. The values of a complete array are written out in columns. 
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12.1 Introduction 

Functions and subroutines are procedures that fall into one of the following categories. 

1. Statement functions 

2. Intrinsic functions 

3. External functions 

4. Subroutines 

First let us introduce some terminology. 

A program unit is a collection of Open Watcom FORTRAN 77 statements and comments that can be either 
a main program or a subprogram. 

A main program identifies the program unit where execution is to begin. A main program is a program 
unit which has as its first statement a PROGRAM statement or one which does not have a PROGRAM, 
FUNCTION, SUBROUTINE or BLOCK DATA statement as its first statement. Complete execution of the 
main program implies the complete execution of the program. Each executable program can contain only 
one main program. 

A subprogram is a program unit that either has a FUNCTION, SUBROUTINE or BLOCK DATA statement 
as its first statement. This chapter will only deal with subprograms that have a FUNCTION or 
SUBROUTINE statement as its first statement. 


12.2 Statement Functions 


A statement function is a procedure defined by a single statement. Its definition must follow all 
specification statements and precede the first executable statement. The statement defining a statement 
function is not an executable statement. 

A statement function has the following form. 


sf ( [d [,d] . . .] ) = e 


where: 

sf is the name of the statement function. 
d is a statement function dummy argument. 
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e is an expression. 

The expression e and the statement function name s f must conform according to the rules of assignment as 
described in the chapter entitled "Assignment Statements" on page 187. 

The statement function dummy arguments are variable names and are used to indicate the order, number 
and type of the arguments of the statement function. A dummy argument name of a statement function 
must only appear once in the dummy argument list of the statement function. Its scope is the statement 
defining the statement function. That is, it becomes defined when the statement function is referenced and 
undefined when execution of the statement function is completed. A name that is a statement function 
dummy argument can also be the name of a variable, a common block, the dummy argument of another 
statement function or appear in the dummy argument list of a FUNCTION, SUBROUTINE or ENTRY 
statement. It cannot be used in any other context. 

The expression e can contain any of the following as operands. 

1. A constant. 

2. A symbolic constant. 

3. A variable reference. This can be a reference to a statement function dummy argument or to a 
variable that appears within the same program unit which defines the statement function. If the 
statement function dummy argument has the same name as a variable in the same program unit, 
the statement function dummy argument is used. The variable reference can also be a dummy 
argument that appears in the dummy argument list of a FUNCTION or SUBROUTINE statement. 
If it is a dummy argument that has appeared in the dummy argument list of an ENTRY statement, 
then the ENTRY statement must have previously appeared. 

4. An array element reference. 

5. An intrinsic function reference. 

6. A reference to a statement function whose defining statement has previously appeared. 

7. An external function reference. 

8. A dummy procedure reference. 

9. An expression enclosed in parentheses which adheres to the rules specified for the expression e . 

12.2.1 Referencing a Statement Function 

A statement function is referenced by its use in an expression. The process of executing a statement 
function involves the following steps. 

1. The expressions that form the actual arguments to the statement function are evaluated. 

2. The dummy arguments of the statement function are associated with the actual arguments. 

3. The expression e is evaluated. 

4. The value of the result is converted to the type of the statement function according to the rules of 
assignment and is available to the expression that contained the reference to the statement 
function. 

The actual arguments must agree in order, number and type with the corresponding dummy arguments. 
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Example: 

SUBROUTINE CALC( U, V ) 

REAL POLY, X, Y, U, V, Z, CONST 

★ 

* Define a Statement Function. 

★ 

POLY(X,Y) = X* *2 + Y* *2 + 2.0*X*Y + CONST 

★ 

* Invoke the Statement Function. 

★ 

CONST =23.5 
Z = POLY( U, V ) 

PRINT *, Z 
END 

In the previous example, note that after the execution of the statement function, the values of X and Y are 
not equal to the value of U and V respectively; they are undefined. 

12.2.2 Statement Function Restrictions 

1. A statement function is local to the program unit in which it is defined. Thus, a statement 
function name is not allowed to appear in an EXTERNAL statement and cannot be passed to 
another procedure as an actual argument. The following example illegally attempts to pass the 
statement function F to the subroutine SAM . 

Example: 

* Illegally passing a statement function 

* to a subroutine. 

PROGRAM MAIN 
F (X) = X 


CALL SAM( F ) 


END 

2. If a statement function F contains a reference to another statement function G, then the 

statement defining G must have previously appeared. In the following example, the expression 
defining the statement function F illegally references a statement function G whose defining 
statement follows the statement defining F . 
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Example: 

* Illegal order of statement functions. 


F (X) = X + G (X) 
G (X) = X + 2 


3. The statement function name must not be the same name of any other entity in the program unit 
except possibly the name of a common block. 

4. If a dummy argument of a statement function is of type CHARACTER, then its length 
specification must be an integer constant expression. The following is illegal. 


Example: 

SUBROUTINE SAM( X ) 

CHARACTER*(*) X 

* Illegal - CHARACTER*!*) dummy argument not 

* allowed in statement function. 

F (X) = X 

PRINT *, F('ABC') 

END 


5. An actual argument to a statement function can be any expression, except character expressions 
involving the concatenation of an operand whose length specification is (*) unless the operand 
is a symbolic constant. 


12.3 Intrinsic Functions 


An intrinsic function is a function that is provided by Open Watcom FORTRAN 77. 

12.3.1 Specific Names and Generic Names of Intrinsic Functions 

All intrinsic functions can be referenced by using the generic name or the specific name of the intrinsic 
function. The specific name uniquely identifies the function to be performed. The type of the result is 
predefined thus its name need not appear in a type statement. For example, CFOG is a specific name of the 
generic FOG function and computes the natural logarithm of a complex number. The type of the result is 
also COMPFEX. 

When the generic name is used, a specific name is selected based on the data type of the actual argument. 
For example, the generic name of the natural logarithm intrinsic function is FOG. To compute the natural 
logarithm of REAF, DOUBFE PRECISION, COMPFEX or DOUBFE PRECISION COMPFEX data, the 
generic name FOG can be used. Generic names simplify the use of intrinsic functions because the same 
name can be used with more than one type of argument. 
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Notes: 

1. It is also possible to pass intrinsic functions to subprograms. When doing so, only the specific 
name of the intrinsic function can be used as an actual argument. The specific name must have 
appeared in an INTRINSIC statement. 

2. If an intrinsic function has more than one argument, each argument must be of the same type. 

3. The generic and specific name of an intrinsic function is the same for some intrinsic functions. 
For example, the specific name of the intrinsic function which computes the sine of an argument 
whose type is REAL is called SIN which is also the generic name of the sine function. 

The following sections present all generic and specific names of intrinsic functions and describe how they 
are used. The following is a guide to interpreting the information presented. 

Data types are represented by letter codes. 

1. CHARACTER is represented by CH. 

2. LOGICAL is represented by L. 

3. INTEGER is represented by I. 

4. INTEGER* 1 is represented by 11. 

5. INTEGER*2 is represented by 12. 

6. REAL (REAL*4) is represented by R. 

7. DOUBLE PRECISION (REAL*8) is represented by D. 

8. Single precision COMPLEX (COMPLEX*8) is represented by C. 

9. Double precision COMPLEX (COMPLEX* 16) is represented by Z. 

The "Definition" description gives the mathematical definition of the function performed by the intrinsic 
function. There are two fields for each intrinsic function. The "Name" field lists the specific and generic 
names of the intrinsic functions. When the name of an intrinsic function is a generic name, it is indicated 
by the word "generic" in parentheses; all other names are specific names. The "Usage" field describes how 
the intrinsic functions are used. "R 4— ATAN2(R,R)" is a typical entry in this field. The name of the 
intrinsic function always follows the " In this example the name of the intrinsic function is ATAN2. 
The data type of the arguments to the intrinsic function are enclosed in parentheses, are separated by 
commas, and always follow the name of the intrinsic function. In this case, ATAN2 requires two 
arguments both of type REAL. The type of the result of the intrinsic function is indicated by the type 
preceding the " 4—". In this case, the result of ATAN2 is of type REAL. 

Open Watcom FORTRAN 77 extensions to the FORTRAN 77 language are flagged by a dagger (f). 
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12.3.2 Type Conversion: Conversion to integer 


Definition: 

int(a) 


Name: 

Usage: 


INT (generic) 

I f-INT(I), I <—INT(R), I <—INT(D), I ^-INT(C), I 

INT(Z) f 

INT 

I INT(R) 


HFIX 

12 <-HFIX(R) f 


IFIX 

I 4-IFIX(R) 


IDINT 

I IDINT(D) 


Notes: 

The value of int(X) is X if X is of type INTEGER. 

If X is of type REAL or DOUBLE 


PRECISION, then int(X) is 0 if IXkl and the integer whose magnitude is the largest 
integer that does not exceed the magnitude of X and has the same sign of X if IXI > 1. 
If X is of type COMPLEX or COMPLEX* 16, int(X) is int(real part of X). 

f is an extension to FORTRAN 77. 

12.3.3 Type Conversion: Conversion to real 


Name: 

Usage: 

REAL (generic) 

R <—REAL(I), R <—REAL(R), R <—REAL(D), R <-REAL(C), R <-REAL(Z) f 

REAL 

R <—REAL(I) 

FLOAT 

R FLOAT(I) 

SNGL 

R SNGL(D ) 

Notes: 

For X of type COMPLEX, REAL(X) is the real part of X. For X of type 
COMPLEX*16, REAL(X) is the single precision representation of the real part of X. 


f is an extension to FORTRAN 77. 
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12.3.4 Type Conversion: Conversion to double precision 

Name: Usage: 

DBLE (generic) D DBLE(I), D <—DBLE(R), D DBLE(D), D <—DBLE(C), D DBLE(Z) f 

DREAL D DREAL(Z) f 

DFLOAT D DFLOAT(I) f 

Notes: For X of type COMPLEX, DBLE(X) is the double precision representation of the real 

part of X. For X of type COMPLEX* 16, DBLE(X) is the real part of X. 

f is an extension to FORTRAN 77. 

12.3.5 Type Conversion: Conversion to complex 

Name: Usage: 

CMPLX (generic) C <b-CMPLX(I), C <-CMPLX(I,I), C <-CMPLX(R), C f-CMPLX(R.R), C 
CMPLX(D), C <-CMPLX(D,D), C <-CMPLX(C), C ^CMPLX(Z) f 

Notes: If X is of type COMPLEX, then CMPLX(X) is X. If X is of type COMPLEX* 16, 

then CMPLX(X) is a complex number whose real part is REAL(real part of X) and 
imaginary part is REAL(imaginary part of X). 

If X is not of type COMPLEX, then CMPLX(X) is the complex number whose real 
part is REAL(X) and imaginary part is REAL(O). CMPLX(X,Y) is the complex 
number whose real part is REAL(X) and whose imaginary part is REAL(Y) for X,Y 
not of type COMPLEX. 

f is an extension to FORTRAN 77. 

12.3.6 Type Conversion: Conversion to double complex 

Name: Usage: 

DCMPLX (generic) T Z ^DCMPLX(I), Z <-DCMPLX(I,I), Z <-DCMPLX(R), Z <-DCMPLX(R,R), Z 
DCMPLX(D), Z <-DCMPLX(D,D), Z ^DCMPLX(C), Z <-DGMPLX(Z) 


Notes: If X is of type COMPLEX*16, then DCMPLX(X) is X. If X is of type COMPLEX, 

then DCMPLX(X) is a COMPLEX* 16 number whose real part is DBLE(real part of 
X) and imaginary part is DBLE(imaginary part of X). 

If X is not of type COMPLEX* 16, then DCMPLX(X) is the COMPLEX* 16 number 
whose real part is DBLE(X) and imaginary part is DBLE(O). DCMPLX(X,Y) is the 
COMPLEX*16 number whose real part is DBLE(X) and whose imaginary part is 
DBLE(Y) for X,Y not of type COMPLEX. 

f is an extension to FORTRAN 77. 
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12.3.7 Type Conversion: Character conversion to integer 

Name: Usage: 

ICHAR I <—ICHAR(CH) 

Notes: ICHAR returns an integer which describes the position of the character in the 

processor collating sequence. The first character in the collating sequence is in 
position 0 and the last character of the collating sequence is in position n—1 where n is 
the number of characters in the collating sequence. The value of ICHAR(X) for X a 
character of length one is such that 0 <= ICHAR(X) <= n—1. For any characters X 
and Y, the following holds true. 

1. X .LT. Y if and only if ICHAR(X) .LT. ICHAR(Y) 

2. X.EQ. Y if and only if ICHAR(X) .EQ. ICHAR(Y) 

CHAR is the inverse of ICHAR. 


12.3.8 Type Conversion: Conversion to character 

Name: Usage: 

CHAR CH CHAR(I) 

Notes: CHAR returns the character in the i'th position of the processor collating sequence. 

The first character in the collating sequence is in position 0 and the last character of 
the collating sequence is in position n—1 where n is the number of characters in the 
collating sequence. The value of CHAR(I) is of type CHARACTER of length one. 
The argument I must be in the range 0 <= I <= n—1. 

ICHAR is the inverse of CHAR. 


12.3.9 Truncation 


Definition: 

Name: 

AINT (generic) 

AINT 

DINT 


int(a) 

Usage: 

R AINT(R), D <—AINT(D) 
R <—AINT(R) 

D <—DINT(D) 


Notes: The value of int(X) is X if X is of type INTEGER. If X is of type REAL or DOUBLE 

PRECISION, then int(X) is 0 if IXkl and the integer whose magnitude is the largest 
integer that does not exceed the magnitude of X and has the same sign of X if IXI > 1. 
If X is of type COMPLEX or COMPLEX* 16, int(X) is int(real part of X). 
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12.3.10 Nearest Whole Number 


Definition: 

Name: 

ANINT (generic) 

ANINT 

DNINT 


int (a+ . 5) if a>=0; int (a- . 5) if a<0 
Usage: 

R 4-ANINT(R), D <-ANINT(D) 

R ANINT(R) 

D <—DNINT(D) 


12.3.11 Nearest Integer 

Definition: int (a+ . 5) if a>=0; int (a- . 5) if a<0 


Name: 


Usage: 


NINT (generic) 

NINT 

IDNINT 


I NINT(R), I <-NINT(D) 
I f-NINT(R) 

I IDNINT(D) 


12.3.12 Absolute Value 


Definition: 

(ar**2+ai**2) **1/2 if a is complex; a otherwise 

Name: 

Usage: 

ABS (generic) 

I <-ABS(I), 11 ABS(Il) f, 12 <-ABS(I2) f, R <-ABS(R), D <-ABS(D), R 
4-ABS(C), D <-ABS(Z) f 

IABS 

I ^IABS(I) 

I1ABS 

11 f-IlABS(Il) f 

I2ABS 

12 <-I2ABS(I2) f 

ABS 

R f-ABS(R) 

DABS 

D DABS(D) 

CABS 

R ^-CABS(C) 

CDABSf 

D CDABS(Z) 

Notes: 

A complex number is an ordered pair of real numbers, (ar, ai) where ar is the real 
part and ai is the imaginary part of the complex number. 

f is an extension to FORTRAN 77. 
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12.3.13 Remainder 

mod(al,a2) = al-int(al/a2)*a2 

Usage: 

I 4—MOD(I,I), II 4-MOD(Il,Il) f, 12 <-MOD(I2,I2) f, R 4-MOD(R,R), D 
4—MOD(D,D), 

I 4—MOD(I,I) 

II 4-IlMOD(Il,Il) f 
12 4—I2MOD(I2,I2) f 
R 4—AMOD(R.R) 

D 4—DMOD(D.D) 

The value of int(X) is X if X is of type INTEGER. If X is of type REAL or DOUBLE 
PRECISION, then int(X) is 0 if IXkl and the integer whose magnitude is the largest 
integer that does not exceed the magnitude of X and has the same sign of X if IXI > 1. 
If X is of type COMPLEX or COMPLEX* 16, int(X) is intfreal part of X). 

The value of MOD, I1MOD, I2MOD, AMOD or DMOD is undefined if the value of 
a2 is 0. 

12.3.14 Transfer of Sign 


Definition: 

sign(al,a2) = | al | if a2>=0; - | al | if a2<0 

Name: 

Usage: 

SIGN (generic) 

I <-SIGN(I,I), 11 4—SIGN(I1,I1) f, 12 4— SIGN(I2,I2) f, R 4-SIGN(R,R), D 
4— SIGN(D.D) 

ISIGN 

1 4— ISIGN(I,I) 

11 SIGN 

11 4— I1SIGN(I1,I1) f 

I2SIGN 

12 4— I2SIGN(I2,I2) f 

SIGN 

R 4-SIGN(R,R) 

DSIGN 

D 4—DSIGN(D,D) 

Notes: 

If the value of al is 0, the result is 0 which has no sign. 


Definition: 

Name: 

MOD (generic) 

MOD 

II MOD 

I2MOD 

AMOD 

DMOD 

Notes: 
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12.3.15 Positive Difference 


Definition: 

al-a2 if al>a2; 0 if al<=a2 

Name: 

Usage: 

DIM (generic) 

I 4—DIM(I,I), 11 <—DIM(I1,I1) f, 12 4—DIM(I2,I2) f, R 4-DIM(R,R), D ^DIM(D.D) 

IDIM 

14—IDIM(I,I) 

I1IDIM 

11 4-IlDIM(Il,Il) f 

I2IDIM 

12 4—I2DIM(I2,I2) f 

DIM 

R 4—DIM(R.R) 

DDIM 

D 4—DDIM(D.D) 


12.3.16 Double Precision Product 

Definition: a 1 * a 2 

Name: Usage: 

DPROD D f-DPROD(R.R) 

12.3.17 Choosing Largest Value 


Definition: 

max(al,a2, . . .) 

Name: 

Usage: 

MAX (generic) 

I 4-MAX(I,...), 11 4-MAX(Il,...) f, 12 4—MAX(I2,...) f, R 4-MAX(R,...), D 
4-MAX(D,...) 

MAXO 

1 4— MAX0(I,...) 

I1MAX0 

11 4— I1MAX0(I1,...) f 

I2MAX0 

12 4— I2MAX0(I2,...) f 

AMAX1 

R 4-AMAXKR,...) 

DMAX1 

D 4— DMAXKD,...) 

AMAXO 

R 4— AMAX0(I,...) 

MAXI 

I 4-MAXKR,...) 
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12.3.18 Choosing Smallest Value 


Definition: 

min(al,a2, . . . ) 

Name: 

Usage: 

MIN (generic) 

I <—MIN(I,...), 11 4—MIN(I1,---) f, 12 4—MIN(I2,...) f, R 4-MIN(R,...), D 4-MIN(D,...) 

MINO 

14—MINO(I,...) 

I1MIN0 

11 4-IlMIN0(Il,...) f 

I2MIN0 

12 4— I2MIN0(I2,...) f 

AMIN1 

R 4-AMINKR,...) 

DMIN1 

D 4—DMINKD,...) 

AMINO 

R 4-AMIN0(I,...) 

MINI 

14—MIN1(R,...) 

12.3.19 Length 

Definition: 

Length of character entity 

Name: 

Usage: 

LEN 

14—LEN(CH) 

Notes: 

The argument to the LEN function need not be defined. 

12.3.20 Length Without Trailing Blanks 

Definition: 

Length of character entity excluding trailing blanks 

Name: 

Usage: 

LENTRIM 

I 4-LENTRIMCCH) 
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12.3.21 Index of a Substring 

Definition: index (al, a2) is location of substring a2 in string al 

Name: Usage: 

INDEX I <—INDEX(CH.CH) 

Notes: INDEX(x,y) returns the starting position of a substring in x which is identical to y. 

The position of the first such substring is returned. If y is not contained in x, zero is 
returned. 

12.3.22 Imaginary Part of Complex Number 

Definition: ai 

Name: Usage: 

IMAG (generic) f R e-IMAG(C), D <-IMAG(Z) 

AIMAG R 4-AIMAG1C) 

DIMAG D DIMAG(Z) f 

Notes: A complex number is an ordered pair of real numbers, (ar, ai) where ar is the real 

part and ai is the imaginary part of the complex number. 

f is an extension to FORTRAN 77. 

12.3.23 Conjugate of a Complex Number 

Definition: (ar, -ai) 

Name: Usage: 

CONJG (generic) f C <-CONJG(C), Z <-CONJG(Z) 

CONJG C CONJG(C) 

DCONJG Z <-DCONJG(Z) f 

Notes: A complex number is an ordered pair of real numbers, (ar, ai) where ar is the real 

part and ai is the imaginary part of the complex number. 

f is an extension to FORTRAN 77. 
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12.3.24 Square Root 


Definition: 

a**l/2 

Name: 

Usage: 

SQRT (generic) 

R 4-SQRT(R), D <—SQRT(D), C f-SQRT(C), Z <-SQRT(Z) f 

SQRT 

R <—SQRT(R) 

DSQRT 

D DSQRT(D) 

CSQRT 

C <-CSQRT(C) 

CDSQRT 

Z CDSQRT(Z) f 

Notes: 

The argument to SQRT must be >= 0. The result of CSQRT and CDSQRT is the 
principal value with the real part >= 0. When the real part of the result is 0, the 
imaginary part is >= 0. 

f is an extension to FORTRAN 77. 

12.3.25 Exponential 

Definition: 

e**a 

Name: 

Usage: 

EXP (generic) 

R <—EXP(R), D <—EXP(D), C ^-EXP(C), Z 4-EXP(Z) f 

EXP 

R EXP(R) 

DEXP 

D DEXP(D ) 

CEXP 

C CEXP(C) 

CDEXP 

Z CDEXP(Z) f 

Notes: 

The result of a complex function is the principal value. 

f is an extension to FORTRAN 77. 
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12.3.26 Natural Logarithm 

Definition: 


log (a) 
e 


Name: Usage: 

LOG (generic ) R <-LOG(R), D 4-LOG(D), C 4-LOGIC), Z f-LOG(Z) f 

ALOG R 4—ALOG(R) 

DLOG D 4— DLOG(D) 

CLOG C 4-CLOG(C) 

CDLOG Z 4— CDLOG(Z) f 

Notes: The value of a must be > 0. The argument of CLOG and CDLOG must not be (0,0). 

The result of CLOG and CDLOG is such that -7Z < imaginary part of the result <= 7t. 
The imaginary part of the result is 7t only when the real part of the argument is < 0 and 
the imaginary part of the argument = 0. 

The result of a complex function is the principal value. 

f is an extension to FORTRAN 77. 

12.3.27 Common Logarithm 

Definition: 


log (a) 
10 


Name: Usage: 

LOG10 ( generic ) R 4-LOG10(R), D 4-LOG 10(D) 

ALOG10 R <—ALOGIO(R) 

DLOG10 D <-DLOG10(D) 
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12.3.28 Sine 

Definition: 

Name: 

SIN (generic) 

SIN 

DSIN 

CSIN 

CDSIN 

Notes: 


12.3.29 Cosine 

Definition: 

Name: 

COS (generic) 

COS 

DCOS 

CCOS 

CDCOS 

Notes: 


sin(a) 

Usage: 

R <-SIN(R), D SIN(D), C f-SIN(C), Z <-SIN(Z) f 
R 4-SIN(R) 

D <—DSIN(D) 

C CSIN(C) 

Z <—CDSIN(Z) f 

All angles are assumed to be in radians. 

The result of a complex function is the principal value, 
f is an extension to FORTRAN 77. 


cos(a) 

Usage: 

R 4-C0S(R), D f-COS(D), C f-COS(C), Z 4-COS(Z) f 
R 4-COS1R) 

D <—DCOS(D) 

C ^-CCOS(C) 

Z CDCOS(Z) f 

All angles are assumed to be in radians. 

The result of a complex function is the principal value, 
f is an extension to FORTRAN 77. 
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12.3.30 Tangent 


Definition: 

tan(a) 

Name: 

Usage: 

TAN (generic) 

R <—TAN(R), D <—TAN(D) 

TAN 

R <—TAN(R) 

DTAN 

D <—DTAN(D) 

Notes: 

All angles are assumed to be in radians. 


12.3.31 Cotangent 

Definition: cotan (a) 

Name: Usage: 

COTAN (generic) f R <-COTAN(R), D <-COTAN(D) 
COTAN R COTAN(R) f 

DCOTAN D DCOTAN(D) f 

Notes: All angles are assumed to be in radians. 

f is an extension to FORTRAN 77. 


12.3.32 Arcsine 


Definition: 

arcsin(a) 

Name: 

Usage: 

ASIN (generic) 

R ASIN(R), D <-ASIN(D) 

ASIN 

R 4-ASIN(R) 

DASIN 

D DASIN(D) 

Notes: 

The absolute value of the argument of ASIN and DASIN must be <= 1. The result is 
such that -7t/2 <= result <= 7t/2. 
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12.3.33 Arccosine 


Definition: 

arccos(a) 

Name: 

Usage: 

ACOS (generic) 

R <—ACOS(R), D ACOS(D) 

ACOS 

R <—ACOS(R) 

DACOS 

D <—DACOS(D) 

Notes: 

The absolute value of the argument of ACOS and DACOS must be <= 1. The result is 
such that 0 <= result <= 71. 

,34 Arctangent 

Definition: 

arctan(a) 

Name: 

Usage: 

ATAN (generic) 

R 4-ATAN1R), D <-ATAN(D) 

ATAN 

R ATAN(R ) 

DATAN 

D <—DATAN(D) 

Definition: 

arctan(al/a2) 

Name: 

Usage: 

ATAN2 (generic) 

R ATAN2(R,R), D ATAN2(D,D) 

ATAN2 

R ATAN2(R,R) 

DATAN2 

D <—DATAN2(D,D) 

Notes: 

The result of ATAN and DATAN is such that -7t/2 <= result <= 7t/2. If the value of 
the first argument of ATAN2 and DATAN2 is positive then the result is positive. If 
the value of the first argument is 0, the result is 0 if the second argument is positive 
and 7t if the second argument is negative. If the value of the first argument is 
negative, the result is negative. If the value of the second argument is 0, the absolute 
value of the result is till. The arguments must not both be 0. The result of ATAN2 
and DATAN2 is such that -7t < result <= 7t. 
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12.3.35 Hyperbolic Sine 

Definition: sinh(a) 

Name: Usage: 

SINH (generic) R <-SINH(R) D <-SINH(D) 
SIND R <—SINH(R) 

I) SI Nil D <—DSINH(D) 

12.3.36 Hyperbolic Cosine 

Definition: cosh (a) 

Name: Usage: 

COSH (generic) R <-COSH(R), D <-COSH(D) 
COSH R COSH(R) 

DCOSH D <—DCOSH(D) 

12.3.37 Hyperbolic Tangent 

Definition: tanh(a) 

Name: Usage: 

TANH (generic) R <—TANH(R), D <—TANH(D) 

TANH R <—TANH(R) 

DTANH D f-DTANH(D) 
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12.3.38 Gamma Function 

Definition: gamma (a) 

Name: Usage: 

GAMMA (generic) R GAMMA(R), D f-GAMMA(D) 

GAMMA R GAMMA(R) 

DGAMMA D e-DGAMMA(D) 


12.3.39 Natural Log of Gamma Function 

Definition: 


log (gamma(a)) 
e 


Name: Usage: 

LGAMMA (generic) R e-LGAMMA(R), D <—LGAMMA(D) 

ALGAMA R e-ALGAMA(R) 

DLGAMA D DLGAMA(D) 


12.3.40 Error Function 


Definition: 

Name: 

ERF (generic) 

ERF 

DERF 


erf(a) 

Usage: 

R <—ERF(R), D <—ERRD) 
R <—ERF(R) 

D <—DERF(D) 
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12.3.41 Complement of Error Function 

Definition: 

1-erf(a) 

Name: 

Usage: 

ERFC (generic) 

R <—ERFC(R), D <—ERFC(D) 

ERFC 

R <—ERFC(R) 

DERFC 

D <—DERFC(D) 

12.3.42 Lexically Greater Than or Equal 

Definition: 

al>=a2 

Name: 

Usage: 

LGE 

L LGE(CH.CH) 

Notes: 

The ASCII collating sequence is used to evaluate the relation. 

12.3.43 Lexically Greater Than 

Definition: 

al>a2 

Name: 

Usage: 

LGT 

L LGT(CH.CH) 

Notes: 

The ASCII collating sequence is used to evaluate the relation. 


12.3.44 Lexically Less Than or Equal 

Definition: al<=a2 

Name: Usage: 

LLE L LLE(CH.CH) 

Notes: The ASCII collating sequence is used to evaluate the relation. 
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12.3.45 Lexically Less Than 

Definition: al<a2 

Name: Usage: 

LLT L 4-LLT(CH,CH) 

Notes: The ASCII collating sequence is used to evaluate the relation. 

12.3.46 Binary Pattern Processing Functions: Boolean AND 

Definition: iand(i, j) Boolean AND 

Name: Usage: 

IAND (generic) I ^IAND(IJ), II 4-IAND(Il,Il), 12 4-IAND(I2,I2) 

I AND I 4 — IAND(I,I) 

HAND II 4-IlAND(Il,Il) 

HAND 12 4 — I2AND(I2,I2) 

12.3.47 Binary Pattern Processing Functions: Boolean Inclusive OR 

Definition: ior (i, j ) Boolean inclusive OR 

Name: Usage: 

IOR (generic) I <-IOR(I,I), II <—IC)R( 11J1), 12 4-IOR(I2,I2) 

IOR I f-IOR(I,I) 

IlOR II <—I10R(I1,I1) 

I20R 12 4 — I20R(I2,I2) 
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12.3.48 Binary Pattern Processing Functions: Boolean Exclusive OR 


Definition: 

ieor (i, j ) Boolean exclusive OR 

Name: 

Usage: 

IEOR (generic) 

I 4—IEOR(IJ), 11 <—TEORCT1 ,T 1), 12 <-IEOR(I2,I2) 

IEOR 

I 4—IEOR(I,I) 

I1EOR 

11 <-IlEOR(Il,Il) 

I2EOR 

12 4—I2EOR(I2,I2) 

12.3.49 Binary Pattern Processing Functions: Boolean Complement 

Definition: 

not(i) Boolean complement 

Name: 

Usage: 

NOT (generic) 

I 4—NOT(I), 11 4—NOT(Il), 12 4—NOT(I2) 

NOT 

I 4—NOT(I) 

I1NOT 

11 4-IlNOT(Il) 

I2NOT 

12 4—I2NOT(I2) 

12.3.50 Binary Pattern Processing Functions: Logical Shift 

Definition: 

i shl ( j, n) Logical shift 

Name: 

Usage: 

ISHL (generic) 

I <—ISHL(I,I), 11 4-ISHL(Il,Il), 12 4-ISHL(I2,I2) 

ISHL 

I 4—ISHL(IJ) 

I1ISHL 

11 <—IlSHL(IUl) 

I2ISHL 

12 4—I2SHL(I2,I2) 
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Definition: ishft(j,n) Logical shift 

Name: Usage: 

ISHFT (generic) I <—ISHFT(I,I), II <—ISHFTfl 1,11), 12 <-ISHFT(I2,I2) 

I <—ISHFTflJ) 

II 4— I1SHFT(I1,I1) 

12 4— I2SHFT(I2,I2) 

There are three shift operations: logical, arithmetic and circular. These shift 
operations are implemented as integer functions having two arguments. The first 
argument, j, is the value to be shifted and the second argument, n, is the number of 
bits to shift. If n is less than 0, a right shift is performed. If n is greater than 0, a left 
shift is performed. If n is equal to 0, no shift is performed. Note that the arguments 
are not modified. 

In a logical shift, bits shifted out from the left or right are lost. Zeros are shifted in 
from the opposite end. 

In an arithmetic shift, j is considered a signed integer. In the case of a right shift, 
zeros are shifted into the left if j is positive and ones if j is negative. Bits shifted out 
of the right are lost. In the case of a left shift, zeros are shifted into the right and bits 
shifted out of the left are lost. 

In a circular shift, bits shifted out one end are shifted into the opposite end. No bits 
are lost. 

12.3.51 Binary Pattern Processing Functions: Arithmetic Shift 

Definition: isha(j,n) Arithmetic shift 

Name: Usage: 

ISHA (generic) I 4-ISHA(I,I), II 4-ISHA(Il,Il), 12 <-ISHA(I2,I2) 

ISHA I 4— ISHA(I,I) 

I1ISHA II <—I1SHA(I1,I1) 

I2ISHA 12 <—I2SHA(I2,I2) 

Notes: There are three shift operations: logical, arithmetic and circular. These shift 

operations are implemented as integer functions having two arguments. The first 
argument, j, is the value to be shifted and the second argument, n, is the number of 
bits to shift. If n is less than 0, a right shift is performed. If n is greater than 0, a left 
shift is performed. If n is equal to 0, no shift is performed. Note that the arguments 
are not modified. 

In a logical shift, bits shifted out from the left or right are lost. Zeros are shifted in 
from the opposite end. 


ISHFT 

I1ISHFT 

I2ISHFT 

Notes: 
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In an arithmetic shift, j is considered a signed integer. In the case of a right shift, 
zeros are shifted into the left if j is positive and ones if j is negative. Bits shifted out 
of the right are lost. In the case of a left shift, zeros are shifted into the right and bits 
shifted out of the left are lost. 

In a circular shift, bits shifted out one end are shifted into the opposite end. No bits 
are lost. 

12.3.52 Binary Pattern Processing Functions: Circular Shift 

Definition: ishc ( j, n) Circular shift 

Name: Usage: 

ISHC (generic) I <-ISHC(I,I), II <-ISHC(Il,Il), 12 <-ISHC(I2,I2) 

ISHC I <—ISHC(I,I) 

I1ISHC II <—I1SHC(I1,I1) 

I2ISIIC 12 <—I2SHC(I2,I2) 

Notes: There are three shift operations: logical, arithmetic and circular. These shift 

operations are implemented as integer functions having two arguments. The first 
argument, j, is the value to be shifted and the second argument, n, is the number of 
bits to shift. If n is less than 0, a right shift is performed. If n is greater than 0, a left 
shift is performed. If n is equal to 0, no shift is performed. Note that the arguments 
are not modified. 

In a logical shift, bits shifted out from the left or right are lost. Zeros are shifted in 
from the opposite end. 

In an arithmetic shift, j is considered a signed integer. In the case of a right shift, 
zeros are shifted into the left if j is positive and ones if j is negative. Bits shifted out 
of the right are lost. In the case of a left shift, zeros are shifted into the right and bits 
shifted out of the left are lost. 

In a circular shift, bits shifted out one end are shifted into the opposite end. No bits 
are lost. 
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12.3.53 Binary Pattern Processing Functions: Bit Testing 


Definition: 

Test bit - a2’th bit of al is tested. If it is 1, .TRUE, is returned. If it is 0, .FALSE, is 
returned. 

Name: 

Usage: 

BTEST (generic) 

L 4-BTESTCU), L f-BTEST(Il,Il), L <-BTEST(I2,I2) 

BTEST 

L BTEST(I,I) 

I1BTEST 

Lf-I1BTEST(I1,I1) 

I2BTEST 

L <-I2BTEST(I2,I2) 


12.3.54 Binary Pattern Processing Functions: Set Bit 

Definition: Set bit - Return al with a2’th bit set. 

Name: Usage: 

IBSET (generic) I ^IBSET(IJ), II <-IBSET(Il,Il), 12 ^-IBSET(I2,I2) 

IBSET I IBSET(I,I) 

I1IBSET II 4-IlBSET(Il,Il) 

I2IBSET 12 f-I2BSET(I2,I2) 

12.3.55 Binary Pattern Processing Functions: Clear Bit 

Definition: Clear bit - Return al with a2’th bit cleared. 

Name: Usage: 

IBCLR (generic) I <-IBCLR(I,I), II <-IBCLR(Il,Il), 12 <-IBCLR(I2,I2) 
IBCLR I IBCLR(I,I) 

I1IBCLR II I1BCLR(I1,I1) 

I2IBCLR 12 f-I2BCLR(I2,I2) 
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12.3.56 Binary Pattern Processing Functions: Change Bit 

Definition: Change bit - Return al with a2’th bit complemented. 

Name: Usage: 

IBCHNG (generic) I <-IBCHNG(I,I), II <—IBCHXGG 1,11), 12 <-IBCHNG(I2,I2) 

IBCHNG 1<-IBCHNG(I,I) 

I1IBCHNG II I1BCHNG(I1,I1) 

I2IBCHNG 12 I2BCHNG(I2,I2) 

12.3.57 Binary Pattern Processing Functions: Arithmetic Shifts 

Definition: 1 shift ( j, n) Arithmetic left shift 

Name: Usage: 

LSHIFT(generic) I <—LSHIFTIIJ), II <s-LSHIFT(Il,Il), 12 <h-LSHIFT(I2,I2) 

LSHIFT I <—LSHIFT(IJ) 

I1LSHIFT II 4-IlLSHIFT(Il,Il) 

I2LSHIFT 12 4—I2LSHIFT(I2,I2) 

Definition: rshift ( j, n) Arithmetic right shift 

Name: Usage: 

RSHIFT (generic) I ^RSHIFT(IJ), II <^RSHIFT(I1,I1), 12 <-RSHIFT(I2,I2) 

RSHIFT I RSHIFT(I,I) 

I1RSHIFT II 11 RSHIFT(11,11) 

I2RSHIFT 12 I2RSHIFT(I2,I2) 

Notes: 

With these shift functions, n must be a non-negative integer. In an arithmetic shift, j 
is considered a signed integer. In the case of a left shift, zeros are shifted into the 
right and bits shifted out of the left are lost. In the case of a right shift, zeros are 
shifted into the left if j is positive and ones if j is negative. Bits shifted out of the 
right are lost. 

If n is equal to 0, no shift is performed. Note that the arguments are not modified. 
These functions are compiled as in-line code unless they are passed as arguments. 
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12.3.58 Allocated Array 

Definition: Is array A allocated? 

Name: Usage: 

ALLOCATED L ALLOCATED(A) 

12.3.59 Memory Location 

Definition: Location of A where A is any variable, array or array element 

Name: Usage: 

LOC I LOC(A) 

12.3.60 Size of Variable or Structure 

Definition: Size of A in bytes where A is any constant, variable, array, or structure 

Name: Usage: 

ISIZEOF I <—ISIZEOF(A) 

Notes: The size reported for a constant or simple variable is based on its type. The size of a 

CHARACTER constant is the number of characters in the constant. The size reported 
for an array is the size of the storage area required for the array. The size reported for 
a structure is the size of the storage area required for the structure. An assumed-size 
CHARACTER variable, assumed-size array, or allocatable array has size 0. 

12.3.61 Volatile Reference 

Definition: A is a volatile reference 

Name: Usage: 

VOLATILE A VOLATILE! A) 

Notes: A volatile reference to a symbol indicates that the value of the symbol may be 

modified in ways that are unknown to the subprogram. For example, a symbol in 
common being referenced in a subprogram may be modified by another subprogram 
that is processing an asynchronous interrupt. Therefore, any subprogram that is 
referencing the symbol to determine its value should reference this symbol using the 
VOLATILE intrinsic function so that the value currently being evaluated agrees with 
the value last stored. 
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12.4 External Functions 


An external function is a program unit that has a FUNCTION statement as its first statement. It is defined 
externally to the program units that reference it. The form of a FUNCTION statement is defined in the 
chapter entitled "FORTRAN Statements" on page 9. 

The name of an external function is treated as if it was a variable. It is through the function name that the 
result of an external function becomes defined. This variable must become defined before the execution of 
the external function is completed. Once defined, it can be referenced or redefined. The value of this 
variable when a RETURN or END statement is executed is the result returned by the external function. 


Example: 

INTEGER FUNCTION VECSUM( A, N ) 
INTEGER A(N), I 
VECSUM = 0 
DO 10 I = 1, N 

VECSUM = VECSUM + A(I) 

10 CONTINUE 
END 


If the variable representing the return value of the external function is of type CHARACTER with a length 
specification of (*) , it must not be the operand of a concatenation operator unless it appears in a character 
assignment statement. 

It is also possible for an external function to return results through its dummy arguments by assigning to 
them. The following example demonstrates this. 
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Example: 

INTEGER MARKS(40) , N 

REAL AVG, STDDEV, MEAN 

PRINT *, 'Enter number of marks' 

READ( 5, * ) N 

PRINT *, 'Enter marks' 

READ ( 5, * ) (MARKS (I), 1 = 1, N) 

AVG = MEAN( MARKS, N, STDDEV ) 

PRINT *, 'Mean = ', AVG, 

$ ' Standard Deviation = ', STDDEV 

END 

★ 

* Define function MEAN to return the average by 

* defining the function name and return the standard 

* deviation by defining a dummy argument. 

* 

REAL FUNCTION MEAN( A, N, STDDEV ) 

INTEGER A, N, I 
REAL STDDEV 
DIMENSION A(N) 

MEAN = 0 
DO 10 I = 1, N 

MEAN = MEAN + A (I) 

10 CONTINUE 

MEAN = MEAN / N 
STDDEV = 0 
DO 20 I = 1, N 

STDDEV = STDDEV + ( A(I) - MEAN ) **2 

20 CONTINUE 

STDDEV = SQRT( STDDEV / (N - 1) ) 

END 


12.4.1 Referencing an External Function 

When an external function is referenced in an expression or a CALL statement, the following steps are 
performed. 

1. The actual arguments are evaluated. 

2. The actual arguments are associated with the corresponding dummy arguments. 

3. The external function is executed. 

The type of the external function reference must be the same as the type of the function name in the 
external function subprogram. If the external function is of type CHARACTER, the length must also 
match. 


12.4.2 Actual Arguments for an External Function 

An actual argument must be one of the following. 

1. Any expression except a character expression involving the concatenation of an operand whose 
length specification is (*) unless the operand is a symbolic constant. 

2. An array name. 

3. An intrinsic function name (must be the specific name) that has appeared in an INTRINSIC 
statement. 
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4. An external procedure name. 

5. A dummy procedure name. 

The actual arguments of an external function reference must match the order, number and type of the 
corresponding dummy arguments. If a subroutine is an actual argument, then type agreement is not 
required since a subroutine has no type. 

12.4.3 External Function Subprogram Restrictions 

1. The name of an external function is a global name and must not be the same as any other global 
name or name local to the subprogram whose name is that of the external function. Note that the 
external function name is treated as a variable within the external function subprogram. 

2. The name of a dummy argument is a name local to the subprogram and must not appear in an 

EQUIVALENCE, PARAMETER, SAVE, INTRINSIC or DATA statement within the same 
subprogram. It may appear in a COMMON statement only as the name of a common block. 

3. The name of the external function can in no way, directly or indirectly, be referenced as a 
subprogram from within the subprogram it defines. It can appear in a type statement to establish 
its type only if the type has not been established in the FUNCTION statement. 


12.5 Subroutines 


A subroutine is a program unit that has a SUBROUTINE statement as it first statement. It is defined 
externally to the program units that reference it. The form of a SUBROUTINE statement can be found in 
the chapter entitled "FORTRAN Statements" on page 9. 

A subroutine differs from a function in that it does not return a result and hence has no type associated with 
it. However, it is possible to return values from a subroutine by defining or redefining the dummy 
arguments of the subroutine. 

12.5.1 Referencing a Subroutine: The CALL Statement 

Unlike a function, a subroutine cannot appear in an expression. Subroutines are referenced by using a 
CALL statement. See the chapter entitled "FORTRAN Statements" on page 9 for details on the CALL 
statement. When a CALL statement is executed, the following steps are performed. 

1. The actual arguments are evaluated. 

2. The actual arguments are associated with the corresponding dummy arguments. 

3. The subroutine is executed. 

A subroutine can be called from any subprogram but must not be called by itself, indirectly or directly. 

12.5.2 Actual Arguments for a Subroutine 

Each actual argument in a subroutine call must be one of the following. 

1. Any expression except a character expression involving the concatenation of an operand whose 

length specification is (*) unless the operand is a symbolic constant. 
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2. An array name. 

3. An intrinsic function name (must be the specific name) that has appeared in an INTRINSIC 
statement. 

4. An external procedure name. 

5. A dummy procedure name. 

6. An alternate return specifier of the form * s where s is a statement number of an executable 
statement in the subprogram which contained the CALL statement. This will be covered in more 
detail when the RETURN statement is discussed. 

The actual arguments must agree in order, number and type with the corresponding dummy arguments. 

The type agreement does not apply to an actual argument which is an alternate return specifier or a 
subroutine name since neither has a type. 

12.5.3 Subroutine Subprogram Restrictions 

1. A subroutine subprogram can contain any statement except a FUNCTION, BLOCK DATA or 
PROGRAM statement. 

2. The name of a subroutine is a global name and must not be used as another global name. 
Furthermore, no local name in the subroutine subprogram can have the same name as the 
subroutine. 

3. The name of a dummy argument is local to the subroutine subprogram and must not appear in an 

EQUIVALENCE, PARAMETER, SAVE, INTRINSIC or DATA statement. It may appear in a 
COMMON statement only as the name of a common block. 


12.6 The ENTRY Statement 


An ENTRY statement allows execution of a subprogram to begin at a particular executable statement within 
the subprogram in which it appears. An ENTRY statement defines an alternate entry point into a 
subprogram and can appear anywhere after the FUNCTION statement in a function subprogram or the 
SUBROUTINE statement in a subroutine subprogram. Also, it must not appear as a statement between the 
beginning and end of a control structure. For example, an ENTRY statement cannot appear between a block 
IF statement and its corresponding END IF statement or between a DO statement and the corresponding 
terminal statement. It is possible to have more than one ENTRY statement in a subprogram. An ENTRY 
statement is a non-executable statement. The form of an ENTRY statement can be found in the chapter 
entitled "FORTRAN Statements" on page 9. 

Each entry name defines an external function if it appears in a function, or an external subroutine if it 
appears in a subroutine and is referenced in the same way as the actual function or subroutine name would 
be referenced. Execution begins at the first executable statement that follows the ENTRY statement. The 
order, number, type and names of the dummy argument lists of an ENTRY statement may be different from 
that of a FUNCTION, SUBROUTINE or other ENTRY statement. However, there must still be agreement 
between the actual argument list used to reference an entry name and the dummy argument list in the 
corresponding ENTRY statement. 
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12.6.1 ENTRY Statements in External Functions 

Entry names may also appear in type statements. Their type may or may not be the same type as other 
entry names or the actual name of the external function unless the function is of type CHARACTER. If the 
function is of type CHARACTER then the type of all the entry names must be of type CHARACTER. 
Conversely, if an entry name is of type CHARACTER, then all other entry names and the function name 
must be of type CHARACTER. An entry name, like external function names, is treated as a variable within 
the subprogram it appears. Within a function subprogram, there is an association between variables whose 
name is an entry name and the variable whose name corresponds to the external function. When such a 
variable becomes defined, all other such variables of the same type also become defined and other such 
variables not of the same type become undefined. This can be best illustrated by an example. 

Example: 

PRINT *, EVAL(2), EVAL3(4.0) 

END 

INTEGER FUNCTION EVAL( X ) 

INTEGER EVAL2, X 
REAL EVAL3, Y 
C = 1 
GOTO 10 

ENTRY EVAL2( X ) 

C = 2 
GOTO 10 

ENTRY EVAL3( Y ) 

C = 3 

10 EVAL2 = C * X 
END 

In the previous example, invoking EVAL would cause the result of 2 to be returned even though EVAL was 
never assigned to in the function EVAL but since EVAL 2 and EVAL are of the same type they are associated 
and hence defining EVAL2 causes EVAL to be defined. However, invoking EVAL3 would cause an 
undefined result to be returned since EVAL3 is of type REAL and EVAL2 is of type INTEGER and hence 
are not associated. EVAL3 does not become defined. 

12.6.2 ENTRY Statement Restrictions 

1. An entry name may not appear in any statement previous to the ENTRY statement containing the 
entry name except in a type statement. 

2. If an entry name in a function is of type CHARACTER, each entry name and the name of the 
function must also be of type CHARACTER. If the name of the function or the name of any 
entry point has a length specification of (*) , then all such entities must have a length 
specification of (*) otherwise they must all have a length specification of the same integer 
value. 

3. If a dummy argument appears in an executable statement, then that statement can be executed 
provided that the dummy argument is in the dummy argument list of the procedure name 
referenced. 

4. A name that appears as a dummy argument in an ENTRY statement must not appear in the 
expression of a statement function unless it is a dummy argument of the statement function, it 
has appeared in the dummy argument list of a FUNCTION or SUBROUTINE statement, or the 
ENTRY statement appears before the statement function statement. 
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5. A name that appears as a dummy argument in an ENTRY statement must not appear in an 
executable statement preceding the ENTRY statement unless it has also appeared in a 
FUNCTION, SUBROUTINE, or ENTRY statement that precedes the executable statement. 


12.7 The RETURN Statement 


A RETURN statement is a way to terminate the execution of a function or subroutine subprogram and return 
control to the program unit that referenced it. As an extension to FORTRAN 77, Open Watcom 
FORTRAN 77 permits the use of the RETURN statement in the main program. A subprogram (or main 
program) may contain more than one RETURN statement or it may contain no RETURN statement. In the 
latter case, the END statement has the same effect as a RETURN statement. 

Execution of a RETURN or END statement causes all local entities to become undefined except for the 
following. 

1. Entities specified in a SAVE statement. 

2. Entities in blank common. 

3. Initially defined entities that have neither been redefined nor become undefined. 

4. Entities in a named common block that appears in the subprogram and in a program unit that 
references the subprogram directly or indirectly. 

12.7.1 RETURN Statement in the Main Program (Extension) 

The form of a RETURN statement in a main program is: 


RETURN 


When a RETURN statement is executed in the main program, program execution terminates in the same 
manner as the STOP or END statement. This is an extension to FORTRAN 77. 

12.7.2 RETURN Statement in Function Subprograms 

The form of a RETURN statement in a function subprogram is: 


RETURN 


When a RETURN statement is executed in a function subprogram, the function value must be defined. 
Control is then passed back to the program unit that referenced it. 
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12.7.3 RETURN Statement in Subroutine Subprograms 

The form of a RETURN statement in a subroutine subprogram is: 


RETURN [ e ] 


where: 

e is an integer expression. 

If the expression e is omitted or has a value less than one or greater than the number of asterisks appealing 
in the dummy argument list of the subroutine or entry name referenced, then control is returned to the next 
executable statement that follows the CALL statement in the referencing program unit. If 1 <= e <= n 
where n is the number of asterisks appearing in the SUBROUTINE or ENTRY statement which contains the 
referenced name, then the expression e identifies the eth asterisk in the dummy argument list. Control is 
returned to the statement identified by the alternate return specified in the CALL statement that corresponds 
to the eth asterisk in the dummy argument list of the referenced subroutine. The following example 
demonstrates the use of alternate return specifiers in conjunction with the RETURN statement. 

Example: 

REAL X, Y 
READ *, X, Y 

CALL CMP ( X, Y, *10, *20 ) 

PRINT *, 'X equals Y' 

GOTO 30 

10 PRINT *, 'X less than Y' 

GOTO 30 

20 PRINT *, 'X greater than Y' 

30 END 

SUBROUTINE CMP( X, Y, *, * ) 

IF ( X .LT. Y )RETURN 1 

IF ( X .GT. Y )RETURN 2 

RETURN 
END 


12.8 Subprogram Arguments 

Arguments provide a means of communication between program units. Arguments are passed to 
subprograms through argument lists and are received by subprograms through argument lists. The 
argument list used to pass arguments to a subprogram is called the actual argument list and the arguments 
are called actual arguments. The argument list of the receiving subprogram is called the dummy argument 
list and the arguments are called dummy arguments. The actual argument list must agree with the dummy 
argument list in number, order and type. 
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12.8.1 Dummy Arguments 

Statement function, external functions and subroutines use dummy arguments to define the type of actual 
arguments they expect. A dummy argument is one of the following. 


1 . 

Variable. 

2. 

Array. 

3. 

Dummy procedure. 

4. 

Notes: 

Asterisk (*) indicating a statement label. 


1. A statement function dummy argument may only be a variable. 

2. An asterisk can only be a dummy argument for a subroutine subprogram. 

Dummy arguments that are variables of type INTEGER can be used in dummy array declarators. No 
dummy argument may appear in an EQUIVALENCE, DATA, PARAMETER, SAVE, INTRINSIC or 
COMMON statement except as a common block name. A dummy argument must not be the same name as 
the subprogram name specified in the FUNCTION, SUBROUTINE or ENTRY statement. Other than these 
restrictions, dummy arguments can be used in the same way an actual name of the same class would be 
used. 

12.8.2 Actual Arguments 

Actual arguments specify the entities that are to be associated with the dummy arguments when referencing 
a subroutine or function. Actual arguments can be any of the following. 

1. Any expression, except character expression involving the concatenation of an operand whose 
length specification is (*) unless the operand is a symbolic constant. 

2. An array name. 

3. An intrinsic function name. 

4. An external function or subroutine name. 

5. A dummy procedure name. 

6. An alternate return specifier of the form * s where s is a statement number of an executable 
statement in the subprogram which contained the CALL statement. 

Notes: 

1. A statement function actual argument can only be a variable or an expression. 

2. An alternate return specifier can only be an actual argument in the actual argument list of a 
subroutine reference. 

12.8.3 Association of Actual and Dummy Arguments 

When a function or subroutine reference is executed, an association is established between the actual 
arguments and the corresponding dummy arguments. The first dummy argument is associated with the first 
actual argument, the second dummy argument is associated with the second actual argument, etc. 
Association requires that the types of the actual and dummy arguments agree. A subroutine has no type and 
when used as an actual argument must be associated with a dummy procedure. An alternate return specifier 
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has no type and must be associated with an asterisk. Arguments can be passed through more than one level 
of procedure reference. In this case, valid association must exist at all intermediate levels as well as the last 
level. Argument association is terminated upon the execution of a RETURN or END statement. 

12.8.3.1 Length of Character Actual and Dummy Arguments 

If a dummy argument is of type CHARACTER, the corresponding actual argument must also be of type 
CHARACTER and the length of the dummy argument must be less than or equal to the length of the actual 
argument. If the length of the dummy argument is len then the len leftmost characters of the actual 
argument are associated with the dummy argument. 

If a dummy argument of type CHARACTER is an array name, then the restriction on the length is on the 
whole array and not for each array element. The length of an array element of the dummy argument may 
be different from the length of the array element of the corresponding actual array, array element, or array 
element substring, but the dummy array argument must not extend beyond the end of the associated actual 
array. 

12.8.3.2 Variables as Dummy Arguments 

A dummy argument that is a variable may be associated with an actual argument that is a variable, array 
element, substring or expression. Only if the actual argument is a variable, array element or substring can 
the corresponding actual argument be redefined. 

12.8.3.3 Arrays as Dummy Arguments 

A dummy argument that is an array may be associated with an actual argument that is an array, array 
element or array element substring. The number and size of the dimensions in the actual argument array 
declarator may be different from the number and size of the dimensions in the dummy argument array 
declarator. 

If the actual argument is a non-character array name, then the size of the dummy argument array must not 
exceed the size of the actual argument array. An element of the actual array becomes associated with the 
element in the dummy array with the same subscript value. Association by array element of character 
arrays exists only if the lengths of the array elements are the same. If their lengths are not the same, the 
dummy and actual array elements will not consist of the same characters. 

If the actual argument is a non-character array element name whose subscript value is asv the size of the 
dummy argument array must not exceed the size of the actual argument array less asv - 1. Furthermore, the 
dummy argument array element whose subscript value is dsv becomes associated with the actual argument 
array element whose subscript value is asv + dsv - 1. Consider the following example. 
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Example: 

DIMENSION A(10) 

CALL SAM( A(3) ) 

END 

SUBROUTINE SAM( B ) 
DIMENSION B(5) 


END 

In the previous example, array A is an actual argument and the array B is the dummy argument. Suppose 
we wanted to know which element of A is associated with the 4th element of B . Then asv would have 
value 3 since the array element A (3) is the actual argument, and dsv is 4. Then the 4th element in B is 3 + 
4 - 1 = 6th element of A. 

If the actual argument is a character array name, character array element name or character array element 
substring which begins at character storage unit ach, then the character storage unit dch of the dummy 
argument array is associated with the character storage unit ach + dch - 1 of the actual array. The size of 
the dummy character array must not exceed the size of the actual argument array. 

12.8.3.4 Procedures as Dummy Arguments 

A dummy argument that is a dummy procedure can only be associated with an actual argument that is one 
of the following. 

1. Intrinsic function. 

2. External function. 

3. External Subroutine. 

4. Another dummy procedure. 

If the dummy argument is used as a subroutine (that is it is invoked using a CALL statement) then the 
corresponding actual argument must either be a subroutine or a dummy procedure. If the dummy argument 
is used as an external function, then the corresponding actual argument must be an intrinsic function, 
external function or dummy procedure. Note that it may not be possible to determine in a given program 
unit whether a dummy procedure is associated with a function or subroutine. In the following example it is 
not possible to tell by looking at this program unit whether PROC is an external subroutine or function. 

Example: 

SUBROUTINE SAM( PROC ) 

EXTERNAL PROC 

CALL SAMI( PROC ) 


END 
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12.8.3.5 Asterisks as Dummy Arguments 

A dummy argument that is an asterisk may only appear in the dummy argument list of a SUBROUTINE 
statement or an ENTRY statement in a subroutine subprogram and may be associated only with an actual 
argument that is an alternate return specifier in a CALL statement which references the subroutine. 

Example: 

CHARACTER*10 RECORD(5) 

1 = 2 

CALL SAM( I, *999, 3HSAM ) 

PRINT *, 'I should be skipped' 

999 PRINT *, 'I should be printed' 

END 

SUBROUTINE SAM( I, *, K) 

CHARACTER*3 K 
PRINT *, K 
RETURN 1 
END 
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A. Open Watcom FORTRAN 77 Extensions to 
Standard FORTRAN 77 


This appendix summarizes the extensions supported by Open Watcom FORTRAN 77. 

1. The INCLUDE statement for embedding source from another file is supported. 

INCLUDE 'SRC' 

2. Symbolic names are unique up to 32 characters. Also, and lowercase letters are allowed 

in symbolic names. 

3. Lowercase and uppercase letters are treated in the same way except in: 

1. character and hollerith constants 

2. apostrophe and H edit descriptors 

4. End-of-line comments are permitted. 

PRINT *, 'Hello world' ! print 'Hello World' 

5. The IMPLICIT NONE statement is supported. 

6. An asterisk enclosed in parentheses is allowed with the type CHARACTER when specified in an 
IMPLICIT statement. 

IMPLICIT CHARACTER*(*) (Z) 

7. Length specifiers are allowed with types specified in IMPLICIT statements. 

IMPLICIT INTEGER*2 (I-N) 

8. Length specifiers are allowed with type specification statements. 

LOGICAL*1, LOGICAL* 4 

INTEGER*1, INTEGER*2, INTEGER*4 

REAL*4, REAL*8 

COMPLEX*8, COMPLEX*16 

Length specifiers are also allowed with the type specified in FUNCTION statements. 

COMPLEX*16 FUNCTION ZADD( X, Y ) 

9. Length specifiers are allowed with symbol names. 

INTEGER 1*2, A*2(10), B(20)*2 
COMPLEX FUNCTION ZADD*16( X, Y ) 
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10. The DOUBLE COMPLEX statement is supported (equivalent to COMPLEX* 16). 

11. Double precision complex constants are allowed. 

Z = (1D0, 2D0) 

12. Mixing operands of type DOUBLE PRECISION and COMPLEX to yield a COMPLEX*16 result 
is allowed. 

DOUBLE PRECISION X 
COMPLEX Y, Z*16 
Z = X + Y 

13. User-defined structures are supported. 

STRUCTURE/END STRUCTURE 
UNION/END UNION 
MAP/END MAP 
RECORD 

14. Both character and non-character data are allowed in the same common block. 

INTEGER X 
CHARACTER C 
COMMON /BLK/ X, C 

15. Data initialization of variables in common without a block data subprogram is allowed. 

16. Equivalencing character to non-character data is permitted. 

INTEGER X 
CHARACTER C 
EQUIVALENCE (X, C) 

17. Single subscripts for multi-dimensional arrays is permitted in EQUIVALENCE statements. 

18. Data initialization in a type specification statement is allowed. 

DOUBLE PRECISION X/4.3D1/ 

19. Data initialization with hexadecimal constants is allowed. 

INTEGER I/Z00000007/ 

20. Initializing character items with numeric data is permitted. 

21. Hexadecimal and octal constants of the form ' abc' x and ' 5 67' o are supported. 

22. A character constant of the form ' abode f' c places a NUL character (CHAR(O)) at the end of 
the character string. 

23. Hollerith constants can be used interchangeably with character constants. 

CHARACTER*10 A, B 
A = '1234567890' 

B = 10H1234567 90 
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24. Several additional intrinsic functions are supported: 


ALGAMA 

ALLOCATED 

CDCOS 

CDSIN 

CDLOG 

COTAN 

DCOTAN 

DERF 

DGAMMA 

DIMAG 

ERF 

ERFC 

I AND 

IBCHNG 

IEOR 

I OR 

ISHFT 

ISHL 

LGAMMA 

LOC 


BTEST 

CDABS 

CDEXP 

CDSQRT 

DCMPLX 

DCONJG 

DERFC 

DFLOAT 

DLGAMA 

DREAL 

GAMMA 

HFIX 

IBCLR 

IBSET 

ISHA 

ISHC 

ISIZEOF 

LENTRIM 

NOT 

VOLATILE 


25. The LOC intrinsic function returns the address of an expression. 

26. The ISIZEOF intrinsic function returns the size of a structure name, the size of an array with a 
constant array declarator, or the size of a variable. 

27. The CHAR intrinsic function is allowed in constant expressions. 

28. The ALLOCATE and DEALLOCATE statements may be used to dynamically allocate and 
deallocate arrays. 

29. The ALLOCATED intrinsic function may be used to determine if an allocatable array is allocated. 

30. The following additional I/O specifiers for the OPEN statement are supported. 

ACTION= 

CARRIAGECONTROL= 

RECORDTYPE= 

RECL= is also allowed for files opened for 
sequential access 
ACCESS='APPEND' 

BLOCKSIZE= 

SHARE= 

31. The following additional I/O specifiers for the INQUIRE statement are supported. 

ACTION= 

CARRIAGECONTROL= 

RECORDTYPE= 

BLOCKSIZE= 

SHARE= 


32. In the INQUIRE statement, character data may also be returned in variables or array elements 
with a substring operation. 

CHARACTER FN*20 

INQUIRE( UNIT=1, FILE=FN(10:20) ) 

33. List-directed I/O is allowed with internal files. 

34. No asterisk is required for list-directed I/O. 

PRINT, X, Y 

35. The NAMELIST statement is supported. 
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36. Non-character arrays are allowed as format specifiers. 

37. The following format edit descriptors are allowed: 

Z for displaying data in hexadecimal format 

Ew.dDe same as Ew.dEe except D is used as exponentiation character 

$ or\ leave cursor at end of line 

38. A repeat count is not required for the X edit descriptor (a repeat count of one is assumed). 

39. Commas are optional between format edit descriptors. 

100 FORMAT( IX 15 ) 

40. It is possible to substring the return values of functions and statement functions. 

CHARACTER*7 F, G 
F() = '1234567' 

PRINT *, F() (1:3), G() (4:7) 

41. Functions may be invoked via the CALL statement. This allows the return value of functions to 
be ignored. 

42. A RETURN statement is allowed in the main program. 

43. Integer constants with more than 5 digits are allowed in the STOP and PAUSE statements. 

PAUSE 123456 
STOP 123456 

44. Multiple assignment is allowed. 

X = Y = Z = 0.0 

45. The . XOR . operator is supported (equivalent to .NEQV.). 

46. The .AND., .OR., .NEQV., . EQV . and .XOR. operators may take integer arguments. They 
can be used to perform bit operations on integers. 

47. Several additional program structure control statements are supported: 
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LOOP-ENDLOOP 

UNTIL (can be used with WHILE and LOOP) 

WHILE-ENDWILE 

GUESS-ADMIT-ENDGUESS 

ATENDDO-ENDATEND 

ATEND 

SELECT-ENDSELECT 

DOWHILE-ENDDO 

DO-ENDDO (no statement number) 

REMOTEBLOCK-ENDBLOCK 

EXECUTE 

QUIT 

EXIT 

CYCLE 


48. Block labels can be used to identify blocks of code. 


LOOP : OUTER_ LOOP 
<statements> 

LOOP : INNER_ LOOP 
<statements> 

IF( X .GT.100 ) 
<statements> 
ENDLOOP 
<statements> 
ENDLOOP 


QUIT : OUTER_ LOOP 


49. An integer expression in an IF, ELSE IF, DO WHILE, WHILE or UNTIL statement is allowed. 
The result of the integer expression is compared for inequality to the integer value 0. 


Open Watcom FORTRAN 77 Extensions to Standard FORTRAN 77 289 





Index 



$ edit descriptor 228, 231 



.AND 288 
.EQV 288 
.NEQV 288 
.OR 288 
.XOR 288 
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A 


A edit descriptor 236 
ABS 251 
access 217 
direct 217, 222 
sequential 217 
ACCESS= 112 
ACOS 260 

actual argument 23, 44, 277 
actual argument list 277 
actual array declarator 164 
adjustable array declarator 162 
ADMIT 12, 83, 122, 206-208 
AIMAG 255 
AINT 250 
ALGAMA 262 

allocatable array declarator 163 
ALLOCATE 13-14, 43-44, 163, 287 
ALLOCATED 270,287 
ALOG 257 
ALOG10 257 

alternate return specifier 23, 274, 278 
AMAX0 253 


AMAX1 253 
AMINO 254 
AMIN1 254 
AMOD 252 
ANINT 251 

apostrophe edit descriptor 229 
argument 

actual 44, 277 

dummy 44, 70, 77-78, 141, 277 
arithmetic assignment statement 187 
arithmetic constant expression 176 
arithmetic expression 175 
factor 175 
primary 174 
term 175 
type of 177 
arithmetic operators 
precedence 174 

arithmetic relational expression 180 
array 

assumed-size 44 
maximum size 160 
array declarator 159 
actual 164 
adjustable 162 
allocatable 163 
assumed-size 162 
constant 162 
dummy 164 

maximum number of elements 160 
array element 160 
array elements 
maximum 160 
ASA 223 
ASIN 259 

ASSIGN 16-17,81, 118, 124, 131, 147, 188,221 
assignment statement 
arithmetic 187 
character 189 
extended 190 
logical 188 
statement label 188 
assumed-size array 44 
assumed-size array declarator 162 
AT END 18,57,208-212 
ATAN 260 
ATAN2 260 
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BACKSPACE 19-20,61,221 

binary operator 173 

blank common block 31 

blank line 4 

BLANK= 114,231-232 

BLOCK DATA 6, 21, 121, 243, 274 

block data subprogram 39 

BLOCKSIZE= 113 

BN edit descriptor 231 

BTEST 268 

BZ edit descriptor 231 


c 


CABS 251 

CALL 23, 272-274, 277-278, 280-281, 288 
carriage control 223 

CASE 25, 66, 115, 122, 137-138, 201, 203-204 
CASEDELAULT 25, 115, 138,201-204 
case list 137 
CCOS 258 
CDABS 251 
CDCOS 258 
CDEXP 256 
CDLOG 257 
CDSIN 258 
CDSQRT 256 
CEXP 256 
CHAR 179,250,287 
CHARACTER 26, 28, 91, 285 
character assignment statement 189 
character constant 155 
character constant expression 179 
character expression 178 
primaries 178 

character relational expression 180 
character set 
FORTRAN 3 
processor 3 
CLOG 257 

CLOSE 29-30, 217, 219-220 
CMPLX 249 
collating sequence 180 
colon edit descriptor 230 
column major 72 


comment line 4 
comments 
end-of-line 4 

COMMON 21, 31-32, 44, 73, 109, 160, 164, 241, 
273-274, 278 
common block 
blank 31 
named 21, 31 
COMPLEX 33-35,286 
complex constant 154 
complex constant expression 176 
complex edit descriptor 236 
COMPLEX* 16 152,286 
CONJG 255 
connection 
file 219 
unit 219 
constant 153 
character 155 
complex 154 
double precision 154 
double precision complex 154 
hexadecimal 156 
hollerith 155 
integer 153 
logical 155 
octal 156 
real 153 
string 155 

constant array declarator 162 
constant expression 185 
continuation line 4 
CONTINUE 36, 48, 196 
COS 258 
COSH 261 
COTAN 259 
CSIN 258 
CSQRT 256 

CYCLE 37, 193, 195-199, 201, 210-211 


D 


D edit descriptor 234-235 
DABS 251 
DACOS 260 
DASIN 259 

data 6-7, 21, 28, 32, 35, 39, 50, 52, 101, 105, 129, 
156, 164, 215, 273-274, 278 
data type 

summary 152 
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DATAN2 260 
DBLE 249 
DCMPLX 249 
DCONJD 255 
DCOS 258 
DCOSH 261 
DCOTAN 259 
DDIM 253 

DEALLOCATE 14, 42, 44, 287 

debug line 4 

DEFAULT 25 

DERF 262 

DERFC 263 

DEXP 256 

D FLOAT 249 

DGAMMA 262 

DIM 253 

DIMAG 255 

DIMENSION 21, 44, 160, 164 

dimension declarator 159 

DINT 250 

DIRECT 95 

direct access 217,222 

disconnection 220 

DLGAMA 262 

DLOG 257 

DLOG10 257 

DMAX1 253 

DMIN1 254 

DMOD 252 

DNINT 251 

DO 6, 36-37, 45-48, 53, 59, 196-197, 210, 274 
DO WHILE 37, 53, 197, 210, 289 
dollar sign ($) 

in symbolic names 151 
DOUBLE COMPLEX 49-50, 152, 286 
DOUBLE PRECISION 51-52, 286 
double precision complex constant 154 
double precision complex constant expression 
177 

double precision constant 154 

double precision constant expression 176 

DPROD 253 

DREAL 249 

DSIGN 252 

DSIN 258 

DSINH 261 

DSQRT 256 

DTAN 259 

DTANH 261 

dummy argument 23, 44, 70, 77-78, 141, 277 
array 279 
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of type CHARACTER 279 
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dummy argument list 277 
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E 
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A 236 
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BN 231 
BZ 231 
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H 229 
L 236 

numeric 232-236 
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D 234-235 
E 234 
F 233 
I 232 
P 230 
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S 230 
slash 230 
SP 230 
SS 230 
Z 237 

ELSE 54-55, 63, 87, 193, 195 
ELSE IF 54-55, 63, 87, 194-195, 289 
END 4, 21, 32, 56, 132, 135, 212, 271, 276, 279 
END AT END 57,212 
END BLOCK 58, 73, 131, 204-205 
END DO 45, 53, 59, 74, 122, 196-198, 208-209 
END GUESS 62,83,206-209 
END IF 6, 54-56, 63, 87-88, 193-195, 208, 274 
END LOOP 64, 74, 106, 122, 198-200, 207-211 
END MAP 65, 107, 169 
END SELECT 25, 66, 115, 137-138, 201-204, 
208 

END STRUCTURE 67, 140, 167 
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END UNION 68, 142, 169 
END WHILE 69, 74, 122, 145, 199-200, 208-209 
end-of-file 216 
end-of-file specifier 223 
end-of-line 
comments 4 

END= 18,211-212,221,223 

ENDFILE 60-61, 217, 219, 221 

endfile record 216 

ENDGUESS 74,209 

ENTRY 6, 27, 70, 121, 244, 274-278, 281 

entry point 274 

EQUIVALENCE 21, 31-32, 71-72, 164, 169, 
273-274, 278, 286 
ERF 262 
ERFC 263 
ERR= 221-222 
error specifier 222 

EXECUTE 58, 73-74, 131, 204-205, 208-209 
EXIT 74, 193, 195-199, 201, 209-210 
EXP 256 
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expression 

arithmetic 175 
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complex constant 176 

double precision complex constant 177 

double precision constant 176 
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factor 175 

integer constant 176 

logical 184 
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real constant 176 

relational 179 

term 175 

extended assignment statement 190 
extension 
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\ edit descriptor 228 
E edit descriptor 227 
X edit descriptor 228 
Z edit descriptor 227 
extensions 

language 285 
summary 285 
EXTERNAL 75, 102, 245 
external file 217 
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name 217 
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record length 218 


external function 271 
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F edit descriptor 233 
file 215, 217 
external 217 
internal 218 
name 217 
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FILE= 93,95,97-98, 112, 114 
FLOAT 248 

FMT= 124, 147, 221-222 
FORM= 112 

format 6, 16, 76, 118, 124, 147, 221, 225, 231 
field 228 
field width 228 

list-directed 118-119, 124-125, 147,222 
namelist-directed 119, 124, 147,222 
repeat specification 227 
see also 226 

edit descriptor 226 
format specification 226 
format specifier 221 
format-directed I/O 238 
FORMATTED 96 
formatted input 125 
formatted input/output 216 
formatted record 216 
FORTRAN 77 

language extensions 285 
FROM 137,201 

function 6, 27, 77-78, 121, 153, 243-244, 271, 
273-276, 278, 285 
external 271 
external name 70 
generic 153 
intrinsic 246 
statement 243 
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AINT 250 
ANINT 251 
ASIN 259 
ATAN 260 
ATAN2 260 
BTEST 268 
CMPLX 249 
CONJG 255 
COS 258 
COSH 261 
COTAN 259 
DBLE 249 
DCMPLX 249 
DIM 253 
ERF 262 
ERFC 263 
EXP 256 
GAMMA 262 
IAND 264 
IBCHNG 269 
IBCLR 268 
IBSET 268 
IEOR 265 
IMAG 255 
INT 248 
IOR 264 
ISHA 266 
ISHC 267 
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ISHL 265 
LOG 257 
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MAX 253 
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MOD 252 
NINT 251 
NOT 265 
REAL 248 
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SIGN 252 
SIN 258 
SINH 261 
SQRT 256 
TAN 259 
TANH 261 

generic name 246 
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I2SHFT 266 

AMINO 254 

I2SHL 265 

AMIN1 254 

12SIGN 252 

AMOD 252 

IABS 251 

ANINT 251 

IAND 264 

ASIN 259 

IBCHNG 269 

ATAN 260 

IBCLR 268 

ATAN2 260 

IBSET 268 

BTEST 268 

ICHAR 250 

CABS 251 

IDIM 253 

CCOS 258 

IDINT 248 

CD ABS 251 

IDNINT 251 

CDCOS 258 

IEOR 265 

CDEXP 256 

IF 6, 9, 54-55, 63, 83-84, 86-87, 193-195, 199, 

CDLOG 257 

208-210, 212-213, 274, 289 

CDSIN 258 

IFIX 248 

CDSQRT 256 

IMPLICIT 6, 21, 26, 33, 49, 51, 89-91, 99, 103, 

CEXP 256 

116, 127, 152-153,285 

CHAR 179,250 

IMPLICIT NONE 91,285 

CLOG 257 

implied-DO list 39 

CMPLX 249 

INCLUDE 6, 285 

CONJG 255 

INDEX 255 

COS 258 
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COSH 261 

input 

COTAN 259 

formatted 125 

CSIN 258 

list-directed 125 

CSQRT 256 

unformatted 126 

DABS 251 

input/output 

DACOS 260 

formatted 216 

DASIN 259 

unformatted 216 

DATAN 260 

INQUIRE 93,97-98,217,219-220,287 

DATAN2 260 

INT 248 

DBLE 249 

INTEGER 91, 99-101 

DCMPLX 249 

integer constant 153 

DCONJG 255 

integer constant expression 176 

DCOS 258 

integer quotient 177 

DCOSH 261 

internal file 218 

DCOTAN 259 

definition 218 

DDIM 253 
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DERF 262 

properties 218 

DERFC 263 

records 218 

DEXP 256 

restrictions 218 

DFLOAT 249 

INTRINSIC 102, 247, 272-274, 278 

DGAMMA 262 

intrinsic function 246 

DIM 253 

ABS 251 

DIMAG 255 
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2 Creating 16 -bit DOS Applications 


This chapter describes how to compile and link 16-bit DOS applications simply and quickly. 


We will illustrate the steps to creating 16-bit DOS applications by taking a small sample application and 
showing you how to compile, link, run and debug it. 

2.1 The Sample Application 

To demonstrate the creation of 16-bit DOS applications using command-line oriented tools, we introduce a 
simple sample program. For our example, we are going to use the "sieve" program. 

* This program computes the prime numbers between 1 and 10,000 

* using the Sieve of Eratosthenes algorithm. 


IMPLICIT NONE 
INTEGER UPBOUND 
PARAMETER (UPBOUND=10000) 

INTEGER I, K, PRIMES 
LOGICAL*1 NUMBERS(2:UPBOUND) 

CHARACTER*11 FORM 

PARAMETER (FORM='(A,15,A,15)') 

DO I = 2, UPBOUND 

NUMBERS(I) = .TRUE. 

ENDDO 

PRIMES = 0 

DO I = 2, UPBOUND 

IF( NUMBERS(I) )THEN 

PRIMES = PRIMES + 1 
DO K = I + I, UPBOUND, I 
NUMBERS(K) = .FALSE. 

ENDDO 
END IF 
ENDDO 

PRINT FORM, 'The Number of Primes between 1 and ', UPBOUND, 
1 ' are: ', PRIMES 

END 


The goal of this program is to count the prime numbers between 1 and 10,000. It uses the famous Sieve of 
Eratosthenes algorithm to accomplish this task. We will take you through the steps necessary to produce 
this result. 


2.2 Building and Running the Sample DOS Application 

To compile and link our example program which is stored in the file sieve . for, enter the following 
command: 

C>wfl -l=dos sieve.for 

The typical messages that appear on the screen are shown in the following illustration. 
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C>wfl -l=dos sieve.for 

Open Watcom F77/16 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
wfc sieve.for 

Open Watcom FORTRAN 77/16 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 21 statements, 311 bytes, 6 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 
creating a DOS executable 

Provided that no errors were encountered during the compile or link phases, the "sieve" program may now 
be run. 

C>sieve 

The Number of Primes between 1 and 10000 are: 1229 

If you examine the current directory, you will find that two files have been created. These are 
sieve . ob j (the result of compiling sieve . for) and sieve . exe (the result of linking sieve . ob j 
with the appropriate Open Watcom FORTRAN 77 libraries). It is sieve . exe that is run by DOS when 
you enter the "sieve" command. 

2.3 Debugging the Sample DOS Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "sieve" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WFL command, this is fairly straightforward. WFL recognizes the Open Watcom F77 
compiler "debug" options and will create the appropriate debug directives for the Open Watcom Linker. 

For example, to compile and link the "sieve" program with debugging information, the following command 
may be issued. 

C>wfl -l=dos -d2 sieve.for 

The typical messages that appear on the screen are shown in the following illustration. 
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C>wfl -l=dos -d2 sieve.for 

Open Watcom F77/16 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
wfc sieve.for -d2 

Open Watcom FORTRAN 77/16 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 21 statements, 392 bytes, 6 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 
creating a DOS executable 

The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom F77 compiler. WFL will make sure that this debugging information is included in the executable 
file that is produced by the linker. 

The "bytes" value is larger than in the previous example since selection of the "d2" option results in fewer 
code optimizations by default. You can request more optimization by specifying the appropriate options. 
However, you do so at the risk of making it more difficult for yourself to determine the relationship 
between the object code and the original source language code. 

To request the Open Watcom Debugger to assist in debugging the application, the following command may 
be issued. 

C>wd sieve 

It would be too ambitious to describe the debugger in this introductory chapter so we refer you to the book 
entitled Open Watcom Debugger User’s Guide. 
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3 Creating 32-bit Phar Lap 386IDOS-Extender 
Applications 


This chapter describes how to compile and link 32-bit Phar Lap 386IDOS-Extender applications simply and 
quickly. 


We will illustrate the steps to creating 32-bit Phar Lap 386IDOS-Extender applications by taking a small 
sample application and showing you how to compile, link, run and debug it. 

3.1 The Sample Application 

To demonstrate the creation of 32-bit Phar Lap 386IDOS-Extender applications using command-line 
oriented tools, we introduce a simple sample program. For our example, we are going to use the "sieve" 
program. 

* This program computes the prime numbers between 1 and 10,000 

* using the Sieve of Eratosthenes algorithm. 


IMPLICIT NONE 
INTEGER UPBOUND 
PARAMETER (UPBOUND=10000) 

INTEGER I, K, PRIMES 
LOGICAL*1 NUMBERS(2:UPBOUND) 

CHARACTER*11 FORM 

PARAMETER (FORM='(A,15,A,15)') 

DO I = 2, UPBOUND 

NUMBERS(I) = .TRUE. 

ENDDO 

PRIMES = 0 

DO I = 2, UPBOUND 

IF( NUMBERS(I) )THEN 

PRIMES = PRIMES + 1 
DO K = I + I, UPBOUND, I 
NUMBERS(K) = .FALSE. 

ENDDO 
END IF 
ENDDO 

PRINT FORM, 'The Number of Primes between 1 and ', UPBOUND, 
1 ' are: ', PRIMES 

END 


The goal of this program is to count the prime numbers between 1 and 10,000. It uses the famous Sieve of 
Eratosthenes algorithm to accomplish this task. We will take you through the steps necessary to produce 
this result. 
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3.2 Building and Running the Sample 386IDOS-Extender 
Application 

To compile and link our example program which is stored in the file sieve . for, enter the following 
command: 

C>wfl386 -l=pharlap sieve.for 
The typical messages that appear on the screen are shown in the following illustration. 

C>wfl386 -l=pharlap sieve.for 

Open Watcom F77/32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 
wfc386 sieve.for 

Open Watcom FORTRAN 77/32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 21 statements, 172 bytes, 6 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Phar Lap simple executable 


Provided that no errors were encountered during the compile or link phases, the "sieve" program may now 
be run. 

C>run386 sieve 

The Number of Primes between 1 and 10000 are: 1229 

If you examine the current directory, you will find that two files have been created. These are 
sieve . ob j (the result of compiling sieve . for) and sieve . exp (the result of linking sieve . ob j 
with the appropriate Open Watcom FORTRAN 77 libraries). It is sieve . exp that is run by DOS when 
you enter the "run386 sieve" command. 

3.3 Debugging the Sample 386IDOS-Extender Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "sieve" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WFL386 command, this is fairly straightforward. WFL386 recognizes the Open Watcom 
F77 compiler "debug" options and will create the appropriate debug directives for the Open Watcom 
Linker. 

For example, to compile and link the "sieve" program with debugging information, the following command 
may be issued. 
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C>wfl386 -l=pharlap -d2 sieve.for 
The typical messages that appear on the screen are shown in the following illustration. 

C>wfl386 -l=pharlap -d2 sieve.for 

Open Watcom F77/32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 
wfc386 sieve.for -d2 

Open Watcom FORTRAN 77/32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 21 statements, 237 bytes, 6 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Phar Lap simple executable 


The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom F77 compiler. WFL386 will make sure that this debugging information is included in the 
executable file that is produced by the linker. 

The "bytes" value is larger than in the previous example since selection of the "d2" option results in fewer 
code optimizations by default. You can request more optimization by specifying the appropriate options. 
However, you do so at the risk of making it more difficult for yourself to determine the relationship 
between the object code and the original source language code. 

To request the Open Watcom Debugger to assist in debugging the application, the following command may 
be issued. 

C>wd /trap=pls sieve 

It would be too ambitious to describe the debugger in this introductory chapter so we refer you to the book 
entitled Open Watcom Debugger User’s Guide. 
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4 Creating 32-bit D0S/4GW Applications 


This chapter describes how to compile and link 32-bit DOS/4GW applications simply and quickly. 


We will illustrate the steps to creating 32-bit DOS/4GW applications by taking a small sample application 
and showing you how to compile, link, run and debug it. 

4.1 The Sample Application 

To demonstrate the creation of 32-bit DOS/4GW applications using command-line oriented tools, we 
introduce a simple sample program. For our example, we are going to use the "sieve" program. 

* This program computes the prime numbers between 1 and 10,000 

* using the Sieve of Eratosthenes algorithm. 


IMPLICIT NONE 
INTEGER UPBOUND 
PARAMETER (UPBOUND=10000) 

INTEGER I, K, PRIMES 
LOGICAL*1 NUMBERS(2:UPBOUND) 

CHARACTER*11 FORM 

PARAMETER (FORM='(A,15,A,15)') 

DO I = 2, UPBOUND 

NUMBERS(I) = .TRUE. 

ENDDO 

PRIMES = 0 

DO I = 2, UPBOUND 

IF( NUMBERS(I) )THEN 

PRIMES = PRIMES + 1 
DO K = I + I, UPBOUND, I 
NUMBERS(K) = .FALSE. 

ENDDO 
END IF 
ENDDO 

PRINT FORM, 'The Number of Primes between 1 and ', UPBOUND, 
1 ' are: ', PRIMES 

END 


The goal of this program is to count the prime numbers between 1 and 10,000. It uses the famous Sieve of 
Eratosthenes algorithm to accomplish this task. We will take you through the steps necessary to produce 
this result. 


4.2 Building and Running the Sample DOS/4GW Application 

To compile and link our example program which is stored in the file sieve . for, enter the following 
command: 

C>wfl386 -l=dos4g sieve.for 


The typical messages that appear on the screen are shown in the following illustration. 
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C>wfl386 -l=dos4g sieve.for 

Open Watcom F77/32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 
wfc386 sieve.for 

Open Watcom FORTRAN 77/32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 21 statements, 172 bytes, 6 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 
creating a DOS/4G executable 

Provided that no errors were encountered during the compile or link phases, the "sieve" program may now 
be run. 

C>sieve 

The Number of Primes between 1 and 10000 are: 1229 

If you examine the current directory, you will find that two files have been created. These are 
sieve . ob j (the result of compiling sieve . for) and sieve . exe (the result of linking sieve . ob j 
with the appropriate Open Watcom FORTRAN 77 libraries). It is sieve . exe that is run by DOS when 
you enter the "sieve" command. 

4.3 Debugging the Sample D0S/4GW Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "sieve" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WFL386 command, this is fairly straightforward. WFL386 recognizes the Open Watcom 
F77 compiler "debug" options and will create the appropriate debug directives for the Open Watcom 
Linker. 

For example, to compile and link the "sieve" program with debugging information, the following command 
may be issued. 

C>wfl386 -l=dos4g -d2 sieve.for 
The typical messages that appear on the screen are shown in the following illustration. 
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C>wfl386 -l=dos4g -d2 sieve.for 

Open Watcom F77/32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 
wfc386 sieve.for -d2 

Open Watcom FORTRAN 77/32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 21 statements, 237 bytes, 6 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 
creating a DOS/4G executable 

The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom F77 compiler. WFL386 will make sure that this debugging information is included in the 
executable file that is produced by the linker. 

The "bytes" value is larger than in the previous example since selection of the "d2" option results in fewer 
code optimizations by default. You can request more optimization by specifying the appropriate options. 
However, you do so at the risk of making it more difficult for yourself to determine the relationship 
between the object code and the original source language code. 

To request the Open Watcom Debugger to assist in debugging the application, the following command may 
be issued. 

C>wd /trap=rsi sieve 

It would be too ambitious to describe the debugger in this introductory chapter so we refer you to the book 
entitled Open Watcom Debugger User’s Guide. 
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5 32-bit Extended DOS Application Development 


5.1 Introduction 


The purpose of this chapter is to anticipate common programming questions for 32-bit extended DOS 
application development. Note that these programming solutions may be DOS-extender specific and 
therefore may not work for other DOS extenders. 

The following topics are discussed in this chapter: 

• How can I write directly to video memory using DOS/4GW? 

• How do I issue interrupts in a DOS/4GW application? 

• How do I get information about free memory with DOS/4GW? 

Please refer to the DOS Protected-Mode Interface (DPMI) Specification for information on DPMI 
services. In the past, the DPMI specification could be obtained free of charge by contacting Intel Literature 
JP26 at 800-548-4725 or by writing to the address below. We have been advised that the DPMI 
specification is no longer available in printed form. 

Intel Literature JP26 
3065 Bowers Avenue 
P.O. Box 58065 
Santa Clara, California 
U.S.A. 95051-8065 

However, the DPMI 1.0 specification can be obtained from the Intel ftp site. Here is the URL. 

ftp: //ftp. intel. com/pub/IAL/software_ specs/dpmivl. zip 


This ZIP file contains a Postscript version of the DPMI 1.0 specification. 

5.2 How can I write directly to video memory using a DOS 
extender? 


Many programmers require access to video RAM in order to directly manipulate data on the screen. Under 
DOS, it was standard practice to use a far pointer, with the segment part of the far pointer set to the screen 
segment. Under DOS extenders, this practice is not so standard. Each DOS extender provides its own 
method for accessing video memory. The following program demonstrates the method used with 


DOS/4GW. 
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* FSCREEN.FOR 

* The following program shows how to access screen memory 

* from a FORTRAN program under the DOS/4GW DOS extender. 

* Compile & Link: wfl386 -l=dos4g fscreen 

program screen 

* Allocatable arrays must be declared by specifying their 

* dimensions using colons only (see Open Watcom FORTRAN 77 

* Language Reference on the ALLOCATE statement for details). 

character*l screen (:, :) 
integer SCRSIZE, i 

parameter ( SCRSIZE = 80*25 ) 

* Under DOS/4GW, the first megabyte of physical memory - the 

* real memory - is mapped as a shared linear address space. 

* This allows your application to access video RAM using its 

* linear address. The DOS segment:offset of B800:0000 

* corresponds to a linear address of B8000. 

allocate ( screen(0:1,0:SCRSIZE-1), location='B8000'x ) 

do i = 0, SCRSIZE - 1 
screen(0,i) = '*' 
enddo 

end 


5.3 How do I issue interrupts in a D0S/4GW application? 

The Open Watcom F77 library files contain the FINTR subroutine which allows the user to perform 
interrupt calls within a FORTRAN 77 program. This subroutine is described in the Subprogram Library 
section of the Open Watcom FORTRAN 77 User’s Guide. 

The following sample program illustrates the use of the FINTR subroutine to set up the register information 
required for Interrupt 21h. The register information is loaded into the regs structure. This structure is 
defined in the DOS.FI file located in the \WATCOM\SRC\FORTRAN\DOS directory. Assign values to 
the register elements according to the interrupt call requirements. For example. Interrupt 21h, function 4Eh 
needs valid values for the AH, ECX, DS and EDX to set up the registers for the Interrupt 21h call. This 
procedure can be used to perform any interrupt calls that are supported in protected mode by DOS/4GW. 

* DTA.FOR 

* This program demonstrates the use of the FINTR 

* function to list the files of the current directory. 

* Interrupt 21 Functions for FIND FIRST, FIND NEXT, 

* and GET DTA are used. 

* Compile & Link: set finclude=\watcom\src\fortran\dos 

* wfl386 -l=dos4g dta 

*$pragma aux GetDS = "mov ax,ds" value [ax] 
program dta 

implicit integer*2 (i-n) 
integer*2 res 
integer*2 GetDS 
integer*4 dir,addr 
integer*l dta(:) 

character fname*l(12), fname2*12 
equivalence (fname, fname2) 
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* DTA is declared as a FAR array. When referencing an array 

* element, the pointer to the array is a FAR pointer. With a 

* character variable, the result is a pointer to a string 

* control block (SCB). The run-time library expects the SCB 

* to contain a near pointer. To get around the problem, we 

* define the DTA as a byte array, then use the CHAR function 

* to get the character equivalent for printing a filename. 

*$pragma array dta far 

include 'dos.fi' 

* 

* Listing of current directory 

★ 

call fsystem( 'dir/w *.*'//char(0) ) 
dir = loc( '*.//char(0) ) 

i = 0 

10 i = i + 1 

if( i .eq. 1 )then 

* 

* Find first file 

* 

AH = '4E'x 
ECX = 0 
DS = GetDS () 

EDX = dir 

else 

* 

* Find next file 

* 

AH = '4F'x 
endif 

call fintr( '21'x, regs ) 
res = AX 

if( res .eq. 0 )then 

* 

* Extract filename from DTA 

* 

AH = '2F'x 

call fintr( '21'x, regs ) 

addr = ISHL( IAND{ INT( ES ), '0000FFFF'x ), 16 ) 
addr = IOR( addr, IAND( INT( BX ), '0000FFFF'x ) ) 

allocate) dta(0:42), location=addr ) 
fname2 = ' ' 

do j = 30, 41 

if ( dta(j) .eq. 0 ) goto 20 
fname(j - 2 9) = chart dta(j) ) 
enddo 

20 print *, fname2 

deallocate( dta ) 
goto 10 
endif 

end 


5.4 How do I get information about free memory in the 32-bit 
environment? 


Under a virtual memory system, programmers are often interested in the amount of physical memory they 
can allocate. Information about the amount of free memory that is available is always provided under a 
DPMI host, however, the manner in which this information is provided may differ under various 
environments. Keep in mind that in a multi-tasking environment, the information returned to your task 
from the DPMI host can easily become obsolete if other tasks allocate memory independently of your task. 
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D0S/4GW provides a DPMI interface through interrupt 0x31. This allows you to use DPMI service 
0x0500 to get free memory information. The following program illustrates this procedure. 

* FMEMORY.FOR 

* This example shows how to get information about free 

* memory using DPMI call 0500h under DOS/4GW using Open Watcom 

* FORTRAN 77. Note that only the first field of the 

* structure is guaranteed to contain a valid value; any 

* field not returned by DOS/4GW is set to -1 (OFFFFFFFFh). 

* Compile & Link: set finclude=\watcom\src\fortran\dos 

* wfl386 -l=dos4g fmemory 

* Pragma to get the default data segment 

*$pragma aux GetDS = "mov ax,ds" value [ax] modify exact [ax] 


program memory 
implicit none 
include 'dos.fi' 


structure /meminfo/ 

integer*4 LargestBlockAvail 
integer*4 MaxUnlockedPage 
integer*4 LargestLockablePage 
integer*4 LinAddrSpace 
integer*4 NumFreePagesAvail 
integer*4 NumPhysicalPagesFree 
integer*4 TotalPhysicalPages 
integer*4 FreeLinAddrSpace 
integer*4 SizeOfPageFile 
integer*4 Reservedl 
integer*4 Reserved2 
end structure 

* Set up the register information for the interrupt call 

record /meminfo/ Meminfo 
integer interrupt_ no 
integer*2 GetDS 

parameter ( interrupt_ no='31'x) 

DS = FS = GS = 0 
EAX = '00000500'x 
ES = GetDS () 

EDI = loc(Meminfo) 


call fintr ( interrupt_ no, regs) 

* Report the information returned by the DPMI host 


print 

print 

& 

print 

& 

print 

& 

print 

& 

print 

& 

print 

& 

print 

& 

print 

& 

print 

& 


* r _ 

*,'Largest available block (in bytes): ', 
Meminfo.LargestBlockAvail 
*,'Maximum unlocked page allocation: ', 
Meminfo.MaxUnlockedPage 
*,'Pages that can be allocated and locked: ', 
Meminfo.LargestLockablePage 
*,'Total linear address space including' // 

' allocated pages:', Meminfo.LinAddrSpace 
*,'Number of free pages available: ', 

Meminfo.NumFreePagesAvail 
*,'Number of physical pages not in use: ', 
Meminfo.NumPhysicalPagesFree 
*,'Total physical pages managed by host: ', 
Meminfo.TotalPhysicalPages 
*,'Free linear address space (pages): ', 
Meminfo.FreeLinAddrSpace 
*,'Size of paging/file partition (pages): ', 
Meminfo.SizeOfPageFile 


end 
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6 The Tenberry Software D0S/4GW DOS Extender 


The chapters in this section describe the 32-bit Tenberry Software DOS/4GW DOS Extender which is 
provided with the Open Watcom F77 package. DOS/4GW is a subset of Tenberry Software’s DOS/4G 
product. DOS/4GW is customized for use with the Open Watcom F77 package. Key differences are: 

• DOS/4GW will only execute programs built with a Open Watcom 32-bit compiler such as Open 
Watcom F77 and linked with its run-time libraries. 

• The DOS/4GW virtual memory manager (VMM), included in the package, is restricted to 32MB of 
memory. 

• DOS/4GW does not provide extra functionality such as TSR capability and VMM performance 
tuning enhancements. 

If your application has requirements beyond those provided by DOS/4GW, you may wish to acquire 
DOS/4GW Professional or DOS/4G from: 

Tenberry Software, Inc. 

PO Box 20050 

Fountain Hills, Arizona 

U.S.A 85269-0050 

WWW: http://www.tenberry.com/dos4g/ 

Email: info@tenberry.com 

Phone: 1.480.767.8868 

Fax: 1.480.767.8709 

Programs developed to use the restricted version of DOS/4GW which is included in the Open Watcom F77 
package can be distributed on a royalty-free basis, subject to the licensing terms of the product. 
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7 Linear Executables 


To build a linear executable, compile and link it as described in the chapter entitled "Creating 32-bit 
DOS/4GW Executables". The resulting file will not run independently: you can run it under the Open 
Watcorn Debugger, Tenberry Software Instant-D debugger, or with the standalone "DOS4GW.EXE". 


7.1 The Linear Executable Format 


DOS/4GW works with files that use the Linear Executable (LE) file format. The format represents a 
protected-mode program in the context of a 32-bit 386 runtime environment with linear to physical address 
translation hardware enabled. It uses a flat address space. 

This file format is similar to the Segmented Executable (NE) format used in OS/2 1.x and MS Windows. 
Both support Dynamic Linking, Resources, and are geared toward protected-mode programs. Both formats 
use tables of "counted ASCII" names, and they use similar relocation formats. 

Both formats begin with a DOS style stub program that sophisticated loaders skip. This stub program 
executes when the DOS/4GW loader is not present, displaying the message. This program cannot run in 
DOS mode. 

When the Open Watcom Linker is used to link a DOS/4GW application, it automatically replaces the 
default stub program with one that calls DOS4GW. 

7.1.1 The Stub Program 

The stub at the beginning of a linear executable is a real-mode program that you can modify as you like. 

For example, you can: 

• make the stub program do a checksum on the "DOS4GW.EXE" file to make sure it’s the correct 
version. 

• copy protect your program. 

• specify a search path for the "DOS4GW.EXE" file. 

• add command line arguments. 

The SRC directory contains source code for a sample stub program. "WSTUB.C" is a simple example, a 
good base to start from when you construct your own stub. Please note that you will require a 16-bit C 
compiler to compile a new stub program. Following is the code in "WSTUB.C": 
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♦include <stdio.h> 

♦include <stdlib.h> 

♦include <process.h> 

♦include <errno.h> 

♦include <string.h> 

/* Add environment strings to be searched here */ 
char *paths_ to_ check [ ] = { 

"D0S4GPATH", 

"PATH"}; 

char *dos4g_ path() 

{ 

static char fullpath[80]; 
int i; 

for( i = 0; 

i < sizeof( paths_ to_ check ) / sizeof( paths_ to_ check[0] ); 

i++ ) { 

_ searchenvl "dos4gw.exe", paths_ to_ check[i], fullpath ); 
if( fullpath[0] ) return] sfullpath ); 

} 

for( i = 0; 

i < sizeof] paths_ to_ check ) / sizeof] paths_ to_ check[0] ); 

i++ ) { 

_ searchenv] "dos4g.exe", paths_ to_ check[i], fullpath ); 
if] fullpath[0] ) return] sfullpath ); 

} 

return] "dos4gw.exe" ); 

} 


main] int argc, char *argv[] ) 

{ 

char *av[4]; 

auto char cmdline[128]; 


av[0] = dos4g_ path(); 
av[1] = argv[0]; 
av[2] = getcmd] cmdline ); 
av[3] = NULL; 

♦ifdef QUIET 

putenv( "DOS4G=QUIET" ); 
♦endif 

execvp( av[0], av ); 
puts] "Stub exec failed:" 
puts ( av[0] ); 
puts( strerror( errno ) ) ; 

exit ( 1 ) ; 

} 


/* Locate the DOS/4G loader */ 
/* name of executable to run */ 
/* command line */ 

/* end of list */ 

/* disables DOS/4G Copyright banner */ 


/* indicate error */ 


If you do not have a C compiler, you can create an assembly language version of the above sample stub 
program and use it to create your own version of the stub program. 

7.2 Memory Use 

This section explains how a DOS/4GW application uses the memory on a 386-based PC/AT. The basic 
memory layout of an AT machine consists of 640KB of DOS memory, 384KB of upper memory, and an 
undetermined amount of extended memory. DOS memory and upper memory together compose real 
memory, the memory that can be addressed when the processor is running in real mode. 
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Figure 1 . Basic Memory Layout 

Under DOS/4GW, the first megabyte of physical memory — the real memory — is mapped as a shared 
linear address space. This allows your application to use absolute addresses in real memory, to access 
video RAM or BIOS ROM, for example. Because the real memory is available to all processes, you are not 
guaranteed to be able to allocate a particular area in real memory: another process may have allocated it 
already. 

Most code and data is placed in a paged linear address space starting at 4MB. The linear address space 
starts at 4MB, the first address in the second page table, to avoid conflicts with VCPI system software. 

This split mapping — an executable that is linked to start at 4MB in the linear address space, with the first 
MB in the address space mapped to the first MB of physical memory — is called a split flat model. 

The illustration below shows the layout of physical memory on the left, and the layout of the linear address 
space on the right. 
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Figure 2. Physical Memory/Linear Address Space 


The 1KB label in the diagram indicates the top of the real-mode interrupt vectors. 4KB marks the end of 
the first page. 
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8 Configuring D0S/4GW 


This chapter explains various options that can be specified with the DOS4G environment variable 
including how to suppress the banner that is displayed by DOS/4GW at startup. It also explains how to use 
the DOS16M environment variable to select the switch mode setting, if necessary, and to specify the range 
of extended memory in which DOS/4GW will operate. DOS/4GW is based on Tenberry Software’s 
DOS/16M 16-bit Protected-Mode support; hence the DOS16M environment variable name remains 
unchanged. 


8.1 The D0S4G Environment Variable 

A number of options can be selected by setting the DOS4G environment variable. The syntax for setting 
options is: 

set D0S4G=optionl,option2, . . . 

Do not insert a space between DOS4G and the equal sign. A space to the right of the equal sign is optional. 
Options: 

QUIET Use this option to suppress the DOS/4GW banner. 

The banner that is displayed by DOS/4GW at startup can be suppressed by issuing the 
following command: 

set DOS4G=quiet 

Note: Use of the quiet switch is only permitted pursuant to the terms and conditions of the 
WATCOM Software License Agreement and the additional redistribution rights described 
in the Getting Started manual. Under these terms, suppression of the copyright by using 
the quiet switch is not permitted for applications which you distribute to others. 

VERBOSE Use this option to maximize the information available for postmortem debugging. 

Before running your application, issue the following command: 

set D0S4G=verbose 

Reproduce the crash and record the output. 

NULLP Use this option to trap references to the first sixteen bytes of physical memory. 

Before running your application, issue the following command: 
set D0S4G=nullp 

To select a combination of options, list them with commas as separators. 
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Example: 

set D0S4G=nullp,verbose 

8.2 Changing the Switch Mode Setting 

In almost all cases, DOS/4GW programs can detect the type of machine that is running and automatically 
choose an appropriate real- to protected-mode switch technique. For the few cases in which this default 
setting does not work we provide the DOS16M DOS environment variable, which overrides the default 
setting. 

Change the switch mode settings by issuing the following command: 
set DOS16M=value 

Do not insert a space between DOS16M and the equal sign. A space to the right of the equal sign is 
optional. 

The table below lists the machines and the settings you would use with them. Many settings have 
mnemonics, listed in the column "Alternate Name", that you can use instead of the number. Settings that 
you must set with the DOS16M variable have the notation req’d in the first column. Settings you may use 
are marked option , and settings that will automatically be set are marked auto. 


Status 

Machine 

Setting 

Alternate 

Name 

Comment 

auto 

386/486 w/ DPMI 

0 

None 

Set automatically if DPMI is active 

req'd 

NEC 98-series 

1 

9801 

Must be set for NEC 98-series 

auto 

PS/2 

2 

None 

Set automatically for PS/2 

auto 

386/486 

3 

386, 80386 

Set automatically for 386 or 486 

auto 

386 

INBOARD 

None 

386 with Intel Inboard 

req’d 

Fujitsu FMR-70 

5 

None 

Must be set for Fujitsu FMR-70 

auto 

386/486 w/ VCPI 

11 

None 

Set automatically if VCPI detected 

req’d 

Hitachi B32 

14 

None 

Must be set for Hitachi B32 

req’d 

OKI if800 

15 

None 

Must be set for OKI if800 

option 

IBM PS/55 

16 

None 

May be needed for some PS/55s 


The following procedure shows you how to test the switch mode setting. 

1. If you have one of the machines listed below, set the DOS16M environment variable to the 
value shown for that machine and specify a range of extended memory. For example, if your 
machine is a NEC 98-series, set DOS16M=1 02M-4M. See the section entitled "Fine Control 
of Memory Usage" on page 31 in this chapter for more information about setting the memory 
range. 
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Machine 

Setting 

NEC 98-series 

1 

Fujitsu FMR-60,-70 

5 

Hitachi B32 

14 

OKI if800 

15 


Before running DOS/4GW applications, check the switch mode setting by following this 
procedure: 

2. Run PMINFO and note the switch setting reported on the last line of the display. (PMINFO, 
which reports on the protected-mode resources available to your programs, is described in more 
detail in the chapter entitled "Utilities" on page 69) 

If PMINFO runs, the setting is usable on your machine. 

3. If you changed the switch setting, add the new setting to your AUTOEXEC.BAT file. 

Note: PMINFO will run successfully on 286 machines. If your DOS/4GW application does not run, and 
PMINFO does, check the CPU type reported on the first line of the display. 

You are authorized (and encouraged) to distribute PMINFO to your customers. You may also include a 
copy of this section in your documentation. 

8.3 Fine Control of Memory Usage 

In addition to setting the switch mode as described above, the DOS16M environment variable enables you 
to specify which portion of extended memory DOS/4GW will use. The variable also allows you to instruct 
DOS/4GW to search for extra memory and use it if it is present. 

8.3.1 Specifying a Range of Extended Memory 

Normally, you don't need to specify a range of memory with the DOS16M variable. You must use the 
variable, however, in the following cases: 

• You are running on a Fujitsu FMR-series, NEC 98-series, OKI if800-series or Hitachi B-series 
machine. 

• You have older programs that use extended memory but don't follow one of the standard disciplines. 

• You want to shell out of DOS/4GW to use another program that requires extended memory. 

If none of these conditions applies to you, you can skip this section. 

The general syntax is: 

set DOS16M= [switch_ mode] [@start_ address [- end_ address] ] [:size] 

In the syntax shown above, start_ address, end_ address andsize represent numbers, expressed 
in decimal or in hexadecimal (hex requires a Ox prefix). The number may end with a K to indicate an 
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address or size in kilobytes, or an M to indicate megabytes. If no suffix is given, the address or size is 
assumed to be in kilobytes. If both a size and a range are specified, the more restrictive interpretation is 
used. 


The most flexible strategy is to specify only a size. However, if you are running with other software that 
does not follow a convention for indicating its use of extended memory, and these other programs start 
before DOS/4GW, you will need to calculate the range of memory used by the other programs and specify a 
range for DOS/4GW programs to use. 


DOS/4GW ignores specifications (or parts of specifications) that conflict with other information about 
extended memory use. Below are some examples of memory usage control: 


set DOS16M= 1 @2m-4m 

set DOS16M= :1M 

set DOS16M= @2m 
set DOS16M= @ 0 - 5m 


Mode 1, for NEC 98-series machines, and use extended memory 
between 2.0 and 4.0MB. 

Use the last full megabyte of extended memory, or as much as 
available limited to 1MB. 

Use any extended memory available above 2MB. 

Use any available extended memory from 0.0 (really 1.0) to 
5.0MB. 


set DOS16M= :0 


Use no extended memory. 


As a default condition DOS/4GW applications take all extended memory that is not otherwise in use. 
Multiple DOS/4GW programs that execute simultaneously will share the reserved range of extended 
memory. Any non-DOS/4GW programs started while DOS/4GW programs are executing will find that 
extended memory above the start of the DOS/4GW range is unavailable, so they may not be able to run. 
This is very safe. There will be a conflict only if the other program does not check the BIOS configuration 
call (Interrupt 15H function 88H, get extended memory size). 


To create a private pool of extended memory for your DOS/4GW application, use the PRIVATXM 
program, described in the chapter entitled "Utilities" on page 69. 


The default memory allocation strategy is to use extended memory if available, and overflow into DOS 
(low) memory. 


In a VCPI or DPMI environment, the start_ address andend_ address arguments are not 
meaningful. DOS/4GW memory under these protocols is not allocated according to specific addresses 
because VCPI and DPMI automatically prevent address conflicts between extended memory programs. 
You can specify a size for memory managed by VCPI or DPMI, but DOS/4GW will not necessarily 
allocate this memory from the highest available extended memory address, as it does for memory managed 
under other protocols. 


8.3.2 Using Extra Memory 

Some machines contain extra non-extended, non-conventional memory just below 16MB. When 
DOS/4GW runs on a Compaq 386, it automatically uses this memory because the memory is allocated 
according to a certain protocol, which DOS/4GW follows. Other machines have no protocol for allocating 
this memory. To use the extra memory that may exist on these machines, set DOS16M with the + option. 

set DOS16M=+ 
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Setting the + option causes DOS/4GW to search for memory in the range from FA0000 to FFFFFF and 
determine whether the memory is usable. DOS/4GW does this by writing into the extra memory and 
reading what it has written. In some cases, this memory is mapped for DOS or BIOS usage, or for other 
system uses. If DOS/4GW finds extra memory that is mapped this way, and is not marked read-only, it will 
write into that memory. This will cause a crash, but won’t have any other effect on your system. 


8.4 Setting Runtime Options 

The DOS16M environment variable sets certain runtime options for all DOS/4GW programs running on the 

same system. 

To set the environment variable, the syntax is: 

set DOS16M= [ switch_ mode_ setting] ''options . 

Note: Some command line editing TSRs, such as CED, use the caret ( A ) as a delimiter. If you want to set 

DOS16M using the syntax above while one of these TSRs is resident, modify the TSR to use a different 

delimiter. 

These are the options: 

0x01 check A20 line — This option forces DOS/4GW to wait until the A20 line is enabled before 

switching to protected mode. When DOS/4GW switches to real mode, this option suspends 
your program’s execution until the A20 line is disabled, unless an XMS manager (such as 
HIMEM.SYS) is active. If an XMS manager is running, your program’s execution is 
suspended until the A20 line is restored to the state it had when the CPU was last in real 
mode. Specify this option if you have a machine that runs DOS/4G W hut is not truly 
AT-compatible. For more information on the A20 line, see the section entitled 
"Controlling Address Line 20" on page 34. 

0x02 prevent initialization ofVCPI — By default, DOS/4GW searches for a VCPI server and, if 

one is present, forces it on. This option is useful if your application does not use EMS 
explicitly, is not a resident program, and may be used with 386-based EMS simulator 
software. 

0x04 directly pass down keyboard status calls — When this option is set, status requests are 

passed down immediately and unconditionally. When disabled, pass-downs are limited so 
the 8042 auxiliary processor does not become overloaded by keyboard polling loops. 

0x10 restore only changed interrupts — Normally, when a DOS/4GW program terminates, all 

interrupts are restored to the values they had at the time of program startup. When you use 
this option, only the interrupts changed by the DOS/4GW program are restored. 

0x20 set new memory to 00 -- When DOS/4GW allocates a new segment or increases the size of a 

segment, the memory is zeroed. This can help you find bugs having to do with 
uninitialized memory. You can also use it to provide a consistent working environment 
regardless of what programs were run earlier. This option only affects segment allocations 
or expansions that are made through the DOS/4GW kerne I (with DOS function 48H or 
4AH). This option does not affect memory allocated with a compiler’s malloc function. 

0x40 set new memory to FF — When DOS/4GW allocates a new segment or increases the size of 

a segment, the memory is set to OxFF bytes. This is helpful in making reproducible cases 
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of bugs caused by using uninitialized memory. This option only affects segment 
allocations or expansions that are made through the DOS/4GW kernel (with DOS function 
48H or 4AH). This option does not affect memory allocated with a compiler’s malloc 
function. 

0x80 new selector rotation — When DOS/4GW allocates a new selector, it usually looks for the 

first available (unused) selector in numerical order starting with the highest selector used 
when the program was loaded. When this option is set, the new selector search begins after 
the last selector that was allocated. This causes new selectors to rotate through the range. 
Use this option to find references to stale selectors, i.e., segments that have been cancelled 
or freed. 


8.5 Controlling Address Line 20 

This section explains how DOS/4GW uses address line 20 (A20) and describes the related DOS16M 
environment variable settings. It is unlikely that you will need to use these settings. 

Because the 8086 and 8088 chips have 20-bit address spaces, their highest addressable memory location is 
one byte below 1MB. If you specify an address at 1MB or over, which would require a twenty-first bit to 
set, the address wraps back to zero. Some parts of DOS depend on this wrap, so on the 286 and 386, the 
twenty-first address bit is disabled. To address extended memory, DOS/4GW enables the twenty-first 
address bit (the A20 line). The A20 line must be enabled for the CPU to run in protected mode, but it may 
be either enabled or disabled in real mode. 

By default, when DOS/4GW returns to real mode, it disables the A20 line. Some software depends on the 
line being enabled. DOS/4GW recognizes the most common software in this class, the XMS managers 
(such as HIMEM.SYS), and enables the A20 line when it returns to real mode if an XMS manager is 
present. For other software that requires the A20 line to be enabled, use the A2 0 option. The A2 0 option 
makes DOS/4GW restore the A20 line to the setting it had when DOS/4GW switched to protected mode. 

Set the environment variable as follows: 

set DOS16M=A20 

To specify more than one option on the command line, separate the options with spaces. 

The DOS16M variable also lets you to specify the length of the delay between a DOS/4GW instruction to 
change the status of the A20 line and the next DOS/4GW operation. By default, this delay is 1 loop 
instruction when DOS/4GW is running on a 386 machine. In some cases, you may need to specify a longer 
delay for a machine that will run DOS/4GW but is not truly AT-compatible. To change the delay, set 
DOS16M to the desired number of loop instructions, preceded by a comma: 

set DOS16M=,loops 
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9 VMM 


The Virtual Memory Manager (VMM) uses a swap file on disk to augment RAM. With VMM you can use 
more memory than your machine actually has. When RAM is not sufficient, part of your program is 
swapped out to the disk file until it is needed again. The combination of the swap file and available RAM 
is the virtual memory. 

Your program can use VMM if you set the DOS environment variable, DOS4GVM, as follows. To set the 
DOS4GVM environment variable, use the format shown below. 

set D0S4GVM= [option[#value]] [option[#value]] 

A "#" is used with options that take values since the DOS command shell will not accept "=". 

If you set DOS4GVM equal to 1, the default parameters are used for all options. 

Example: 

C>set D0S4GVM=1 


9.1 VMM Default Parameters 


VMM parameters control the options listed below. 


MINMEM 

MAXMEM 

SWAPMIN 

SWAPINC 


The minimum amount of RAM managed by VMM. The default is 512KB. 

The maximum amount of RAM managed by VMM. The default is 4MB. 

The minimum or initial size of the swap file. If this option is not used, the size of the 
swap file is based on VIRTUALSIZE (see below). 

The size by which the swap file grows. 


SWAPNAME The swap file name. The default name is "DOS4GVM.SWP". By default the file is in 
the root directory of the current drive. Specify the complete path name if you want to 
keep the swap file somewhere else. 


DELETESWAP Whether the swap file is deleted when your program exits. By default the file is not 
deleted. Program startup is quicker if the file is not deleted. 


VIRTU ALSIZE The size of the virtual memory space. The default is 16MB. 


VMM Default Parameters 
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9.2 Changing the Defaults 

You can change the defaults in two ways. 

1. Specify different parameter values as arguments to the DOS4GVM environment variable, as 
shown in the example below. 

set DOS4GVM=deleteswap maxmem#8192 

2. Create a configuration file with the filetype extension ".VMC", and use that as an argument to 
the DOS4GVM environment variable, as shown below. 

set DOS4GVM=@NEW4G.VMC 

9.2.1 The. VMC File 

A ".VMC" file contains VMM parameters and settings as shown in the example below. Comments are 
permitted. Comments on lines by themselves are preceded by an exclamation point (!). Comments that 
follow option settings are preceded by white space. Do not insert blank lines: processing stops at the first 
blank line. 

!Sample .VMC file 

!This file shows the default parameter values. 

minmem = 512 At least 512K bytes of RAM is required, 

maxmem = 4096 Uses no more than 4MB of RAM 

virtualsize = 16384 Swap file plus allocated memory is 16MB 

!To delete the swap file automatically when the program exits, add 
!deleteswap 

!To store the swap file in a directory called SWAPFILE, add 
!swapname = c:\swapfile\dos4gvm.swp 
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10 Interrupt 21H Functions 


When you call an Interrupt 21H function under DOS/4GW, the 32-bit registers in which you pass values are 
translated into the appropriate 16-bit registers, since DOS works only with 16 bits. However, you can use 
32-bit values in your DOS calls. You can allocate blocks of memory larger than 64KB or use an address 
with a 32-bit offset, and DOS/4GW will translate the call appropriately, to use 16-bit registers. When the 
Interrupt 21H function returns, the value is widened - placed in a 32-bit register, with the high order bits 
zeroed. 

DOS/4GW uses the following rules to manage registers: 

• When you pass a parameter to an Interrupt 21H function that expects a 16-bit quantity in a general 
register (for example, AX), pass a 32-bit quantity in the corresponding extended register (for 
example, EAX). When a DOS function returns a 16-bit quantity in a general register, expect to 
receive it (with high-order zero bits) in the corresponding extended register. 

• When an Interrupt 21H function expects to receive a 16:16 pointer in a segment:general register pair 
(for example, ES:BX), supply a 16:32 pointer using the same segment register and the corresponding 
extended general register (ES:EBX). DOS/4GW will copy data and translate pointers so that DOS 
ultimately receives a 16:16 real-mode pointer in the correct registers. 

• When DOS returns a 16:16 real-mode pointer, DOS/4GW translates the segment value into an 
appropriate protected-mode selector and generates a 32-bit offset that results in a 16:32 pointer to the 
same location in the linear address space. 

• Many DOS functions return an error code in AX if the function fails. DOS/4GW checks the status of 
the carry flag, and if it is set, indicating an error, zero-extends the code for EAX. It does not change 
any other registers. 

• If the value is passed or returned in an 8-bit register (AL or AH, for example), DOS/4GW puts the 
value in the appropriate location and leaves the upper half of the 32-bit register untouched. 

The table below lists all the Interrupt 21h functions. For each, it shows the registers that are widened or 
narrowed. Footnotes provide additional information about some of the interrupts that require special 
handling. Following the table is a section that provides a detailed explanation of interrupt handling under 
DOS/4GW. 
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Function 

Purpose 

Managed Registers 

00H 

Terminate Process 

None 

OlH 

Character Input with Echo 

None 

02H 

Character Output 

None 

03H 

Auxiliary Input 

None 

04H 

Auxiliary Output 

None 

05 H 

Print Character 

None 

06H 

Direct Console I/O 

None 

07H 

Unfiltered Character Input Without Echo 

None 

08H 

Character Input Without Echo 

None 

09H 

Display String 

EDX 

OAH 

Buffered Keyboard Input 

EDX 

OBH 

Check Keyboard Status 

None 

OCH 

Flush Buffer, Read Keyboard 

EDX 

ODH 

Disk Reset 

None 

OEH 

Select Disk 

None 

OFH 

Open File with FCB 

EDX 

10H 

Close File with FCB 

EDX 

11H 

Find First File 

EDX 

12H 

Find Next File 

EDX 

13H 

Delete File 

EDX 

14H 

Sequential Read 

EDX 

15H 

Sequential Write 

EDX 

16H 

Create File with FCB 

EDX 

17H 

Rename File 

EDX 

19H 

Get Current Disk 

None 

1AH 

Set DTA Address 

EDX 

1BH 

Get Default Drive Data 

Returns in EBX, ECX, and EDX 

1CH 

Get Drive Data 

Returns in EBX, ECX, and EDX 

21H 

Random Read 

EDX 

22H 

Random Write 

EDX 

23H 

Get File Size 

EDX 

24H 

Set Relative Record 

EDX 

25H 

Set Interrupt Vector 

EDX 

26H 

Create New Program Segment Prefix 

None 

27H 

Random Block Read 

EDX, returns in ECX 

28H 

Random Block Write 

EDX, returns in ECX 

29H 

Parse Filename ESI, EDI, returns in EAX, ESI and EDI (1.) 

2AH 

Get Date 

Returns in ECX 

2BH 

Set Date 

None 

2CH 

Get Time 

None 

2DH 

Set Time 

None 

2EH 

Set/Reset Verify Flag 

None 

2FH 

Get DTA Address 

Returns in EBX 

30H 

Get MS-DOS Version Number 

Returns in ECX 

31H 

Terminate and Stay Resident 

None 

33H 

Get/Set Control-C Check Flag 

None 

34H 

Return Address of InDOS Flag 

Returns in EBX 

35H 

Get Interrupt Vector 

Returns in EBX 

36H 

Get Disk Free Space 

Returns in EAX, EBX, ECX, and EDX 
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38H 


Get/Set Current Country 

EDX, returns in EBX 

39H 


Create Directory 

EDX 

3AH 


Remove Directory 

EDX 

3BH 


Change Current Directory 

EDX 

3CH 


Create File with Flandle 

EDX, returns in EAX 

3DH 


Open File with Flandle 

EDX, returns in EAX 

3EH 


Close File 

None 

3FH 


Read File or Device 

EBX, ECX, EDX, returns in EAX (2.) 

40H 


Write File or Device 

EBX, ECX, EDX, returns in EAX (2.) 

41H 


Delete File 

EDX 

42H 


Move File Pointer 

Returns in EDX, EAX 

43H 


Get/Set File Attribute 

EDX, returns in ECX 

44H 


IOCTL 

(3.) 


00H 

Get Device Information 

Returns in EDX 


01H 

SetDevice Information 

None 


02H 

Read Control Data from CDD 

EDX, returns in EAX 


03H 

Write Control Data to CDD 

EDX, returns in EAX 


04H 

Read Control Data from BDD 

EDX, returns in EAX 


05 H 

Write Control Data to BDD 

EDX, returns in EAX 


06H 

Check Input Status 

None 


07 H 

Check Output Status 

None 


08H 

Check if Block Device is Removeable 

Returns in EAX 


09H 

Check if Block Device is Remote 

Returns in EDX 


OAH 

Check if Flandle is Remote 

Returns in EDX 


OBH 

Change Sharing Retry Count 

None 


OCH 

Generic I/O Control for Character Devices EDX 


ODH 

Generic I/O Control for Block Devices 

EDX 


OEH 

Get Logical Drive Map 

None 


OFH 

Set Logical Drive Map 

None 

45 H 


Duplicate File Flandle 

Returns in EAX 

46H 


Force Duplicate File Flandle 

None 

47 H 


Get Current Directory 

ESI 

48H 


Allocate Memory Block 

Returns in EAX 

49H 


Free Memory Block 

None 

4AH 


Resize Memory Block 

None 

4BH 


Load and Execute Program (EXEC) 

EBX, EDX (4.) 

4CH 


Terminate Process with Return Code 

None 

4DH 


Get Return Code of Child Process 

None 

4EH 


Find First File 

EDX 

4FH 


Find Next File 

None 


52H Get List of Lists 

54H Get Verify Flag 

56H Rename File 

57H Get/Set Date/Time of File 

58H Get/Set Allocation Strategy 

59H Get Extended Error Information 

5AH Create Temporary File 

5BH Create New File 

5CH Lock/Unlock File Region 

5EH Network Machine Name/Printer Setup 

00H Get Machine Name 
02H Set Printer Setup String 


(not supported) 
None 
EDX, EDI 
Returns in ECX, and EDX 
Returns in EAX 
Returns in EAX 
EDX, returns in EAX and EDX 
EDX, returns in EAX 
None 

EDX 

ESI 
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03H Get Printer Setup String 
5FH Get/Make Assign List Entry 

02H Get Redirection List Entry 
03H Redirect Device 
04H Cancel Device Redirection 


EDI, returns in ECX 

ESI, EDI, returns in ECX 
ESI, EDI 
ESI 


62H Get Program Segment Prefix Address 

63H Get Lead Byte Table (version 2.25 only) 

65H Get Extended Country Information 

66H Get or Set Code Page 

67H Set Handle Count 


Returns in EBX 
Returns in ESI 
EDI 
None 
None 


This list of functions is excerpted from The MS-DOS Encyclopedia, Copyright (c) 1988 by Microsoft Press. 

All Rights Reserved. 

1. For Function 29H, DS:ESI and ES:EDI contain pointer values that are not changed by the call. 

2. You can read and write quantities larger than 64KB with Functions 3FH and 40H. DOS/4GW 
breaks your request into chunks smaller than 64KB, and calls the DOS function once for each 
chunk. 

3. You can’t transfer more than 64KB using Function 44h, subfunctions 02H, 03H, 04H, or 05H. 
DOS/4GW does not break larger requests into DOS-sized chunks, as it does for Functions 3FH 
and 40H. 

4. When you call Function 4B under DOS/4GW, you pass it a data structure that contains 16:32 bit 
pointers. DOS/4GW translates these into 16:16 bit pointers in the structure it passes to DOS. 


10.1 Functions 25H and 35H: Interrupt Handling in Protected 
Mode 


By default, interrupts that occur in protected mode are passed down: the entry in the IDT points to code in 
DOS/4GW that switches the CPU to real mode and resignals the interrupt. If you install an interrupt 
handler using Interrupt 21H, Function 25H, that handler will get control of any interrupts that occur while 
the processor is in protected mode. If the interrupt for which you installed the handler is in the autopassup 
range, your handler will also get control of interrupts signalled in real mode. 

The autopassup range runs from 08H to 2EH inclusive, but excluding 21H. If the interrupt is in the 
autopassup range, the real-mode vector will be modified when you install the protected-mode handler to 
point to code in the DOS/4GW kernel. This code switches the processor to protected mode and resignals 
the interrupt-where your protected-mode handler will get control. 

10.1.132-Bit Gates 

The DOS/4GW kernel always assigns a 32-bit gate for the interrupt handlers it installs. It does not 
distinguish between 16-bit and 32-bit handlers for consistency with DPMI. 

This 32-bit gate points into the DOS/4GW kernel. When DOS/4GW handles the interrupt, it switches to its 
own 16-bit stack, and from there it calls the interrupt handler (yours or the default). This translation is 
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transparent to the handler, with one exception: since the current stack is not the one on which the interrupt 
occurred, the handler cannot look up the stack for the address at which the interrupt occurred. 

10.1.2 Chaining 16-bit and 32-bit Handlers 

If your program hooks an interrupt, write a normal service routine that either handles the interrupt and 
IRETs or chains to the previous handler. As part of handling the interrupt, your handler can PUSHF/CALL 
to the previous handler. The handler must IRET (or IRETD) or chain. 

For each protected-mode interrupt, DOS/4GW maintains separate chains of 16-bit and 32-bit handlers. If 
your 16-bit handler chains, the previous handler is a 16-bit program. If your 32-bit handler chains, the 
previous handler is a 32-bit program. 

If a 16-bit program hooks a given interrupt before any 32-bit programs hook it, the 16-bit chain is executed 
first. If all the 16-bit handlers unhook later and a new 16-bit program hooks the interrupt while 32-bit 
handlers are still outstanding, the 32-bit handlers will be executed first. 

If the first program to hook an interrupt is 32-bit, the 32-bit chain is executed first. 

10.1.3 Getting the Address of the Interrupt Handler 

When you signal Interrupt 21H, Function 35, it always returns a non-null address even if no other program 
of your bitness (i.e., 16-bit or 32-bit) has hooked the interrupt. The address points to a dummy handler that 
looks to you as though it does an IRET to end the chain. This means that you can’t find an unused interrupt 
by looking for a NULL pointer. Since this technique is most frequently used by programs that are looking 
for an unclaimed real-mode interrupt on which to install a TSR, it shouldn’t cause you problems. 
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When a D0S/4GW application runs under a DPMI host, such as Windows 3.1 in enhanced mode, an OS/2 
virtual DOS machine, 386Max (with DEBUG=DPMIXCOPY), or QEMM/QDPMI (with EXTCHKOFF), 
the DPMI host provides the DPMI services, not DOS/4GW. The DPMI host also provides virtual memory, 
if any. Performance (speed and memory use) under different DPMI hosts varies greatly due to the quality 
of the DPMI implementation. 

DPMI services are accessed using Interrupt 31H. 

The following describes the services provided by DOS/4GW and DOS/4GW Professional in the absence of 
a DPMI host. DOS/4GW supports many of the common DPMI system services. Not all of the services 
described below are supported by other DPMI hosts. 

Some of the information in this chapter was obtained from the the DOS Protected-Mode Interface (DPMI) 
specification. It is no longer in print; however the DPMI 1.0 specification can be obtained from the Intel 
ftp site. Here is the URL. 

ftp: //ftp. intel. com/pub/IAL/software_ specs/dpmivl. zip 


This ZIP file contains a Postscript version of the DPMI 1.0 specification. 

11.1 Using Interrupt 31H Function Calls 

Interrupt 31H DPMI function calls can be used only by protected-mode programs. 

The general ground rules for Interrupt 31H calls are as follows: 

• All Interrupt 31H calls modify the AX register. Unsupported or unsuccessful calls return an error 
code in AX. Other registers are saved unless they contain specified return values. 

• All Interrupt 31H calls modify flags: Unsupported or unsuccessful calls return with the carry flag 
set. Successful calls clear the carry flag. Only memory management and interrupt flag management 
calls modify the interrupt flag. 

• Memory management calls can enable interrupts. 

• All calls are reentrant. 

The flag and register information for each call is listed in the following descriptions of supported Interrupt 

31H function calls. 
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11.2 lnt31H Function Calls 

The Interrupt 31H subfunction calls supported by DOS/4GW are listed below by category: 

• Local Descriptor Table (LDT) management services 

• DOS memory management services 

• Interrupt services 

• Translation services 

• DPMI version 

• Memory management services 

• Page locking services 

• Demand paging performance tuning services 

• Physical address mapping 

• Virtual interrupt state functions 

• Vendor specific extensions 

• Coprocessor status 

Only the most commonly used Interrupt 31H function calls are supported in this version. 

11.2.1 Local Descriptor Table (LDT) Management Services 

Function 0000H This function allocates a specified number of descriptors from the LDT and returns the 
base selector. Pass the following information: 

AX = 0000H 

CX = number of descriptors to be allocated 

If the call succeeds, the carry flag is clear and the base selector is returned in AX. If the 
call fails, the carry flag is set. 

An allocated descriptor is set to the present data type, with a base and limit of zero. The 
privilege level of an allocated descriptor is set to match the code segment privilege level of 
the application. To find out the privilege level of a descriptor, use the lar instruction. 

Allocated descriptors must be filled in by the application. If more than one descriptor is 
allocated, the returned selector is the first of a contiguous array. Use Function 0003H to 
get the increment for the next selector in the array. 

Function 0001H This function frees the descriptor specified. Pass the following information: 
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ax = 0001H 

BX = the selector to free 

Use the selector returned with function OOOOh when the descriptor was allocated. To free 
an array of descriptors, call this function for each descriptor. Use Function 0003H to find 
out the increment for each descriptor in the array. 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. 

You can use this function to free the descriptors allocated for the program’s initial CS, DS, 
and SS segments, but you should not free other segments that were not allocated with 
Function OOOOH or Function 000DH. 

Function 0002H This function converts a real-mode segment to a descriptor that a protected-mode 
program can address. Pass the following information: 

AX = 0002H 

BX = real-mode segment address 

If the call succeeds, it clears the carry flag and returns the selector mapped to the real-mode 
segment in AX. If the call fails, the carry flag is set. 

If you call this function more than once with the same real-mode segment address, you get 
the same selector value each time. The descriptor limit is set to 64KB. 

The purpose of this function is to give protected-mode programs easy access to commonly 
used real-mode segments. However, because you cannot modify or free descriptors created 
by this function, it should be used infrequently. Do not use this function to get descriptors 
for private data areas. 

To examine real-mode addresses using the same selector, first allocate a descriptor, and 
then use Function 0007H to change the linear base address. 

Function 0003H This function returns the increment value for the next selector. Use this function to get 
the value you add to the base address of an allocated array of descriptors to get the next 
selector address. Pass the following information: 

AX = 0003H 

This call always succeeds. The increment value is returned in AX. This value is always a 
power of two, but no other assumptions can be made. 

Function 0006H This function gets the linear base address of a selector. Pass the following information: 

AX = 0006H 
BX = selector 

If the call succeeds, the carry flag is clear and CX:DX contains the 32-bit linear base 
address of the segment. If the call fails, it sets the carry flag. 

If the selector you specify in BX is invalid, the call fails. 

Function 0007H This function changes the base address of a specified selector. Only descriptors allocated 
through Function OOOOH should be modified. Pass the following information: 
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AX = 0007H 
BX = selector 

CX:DX = the new 32-bit linear base address for the segment 

If the call succeeds, the carry flag is clear; if unsuccessful, the carry flag is set. 

If the selector you specify in BX is invalid, the call fails. 

Function 0008H This function sets the upper limit of a specified segment. Use this function to modify 
descriptors allocated with Function 0000H only. Pass the following information: 

AX = 0008H 
BX = selector 

CX:DX = 32-bit segment limit 

If the call succeeds, the carry flag is clear; if unsuccessful, the carry flag is set. 

The call fails if the specified selector is invalid, or if the specified limit cannot be set. 

Segment limits greater than 1MB must be page-aligned. This means that limits greater than 
1MB must have the low 12 bits set. 

To get the limit of a segment, use the 32-bit form of lsl for segment limits greater than 
64KB. 

Function 0009H This function sets the descriptor access rights. Use this function to modify descriptors 
allocated with Function 0000H only. To examine the access rights of a descriptor, use the 
lar instruction. Pass the following information: 

AX = 0009H 
BX = selector 

CL = Access rights/type byte 

CH = 386 extended access rights/type byte 

If the call succeeds, the carry flag is clear; if unsuccessful, the carry flag is set. If the 
selector you specify in BX is invalid, the call fails. The call also fails if the access 
rights/type byte does not match the format and meet the requirements shown in the figures 
below. 
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The access rights/type byte passed in CL has the format shown in the figure below. 


p 

DPL 

1 

C/D 

E/C 

W/R 

A 

7 

6 5 

4 

3 

2 

1 

0 


* 

0 => Not accessed 
v 1 => Accessed 

Data: 0 => Read, 1=> R/W 
, r Code: Must be 1 (readable) 

Data: 0=> Exp-up, 1=> Exp-dn 
v Code: Must be 0 (non-conform) 

0 => Data, 1=> Code 


Must be 1 


Must equal caller’s CPL 


0 = > Absent, 1=> Present 


Figure 3. Access Rights/Type 
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The extended access rights/type byte passed in CH has the following format. 


G 

B/D 

0 

Avl 

Reserved 

7 

6 

5 

4 

3 2 10 


Ignored 


▼ 

Can be 0 or 1 

▼ 

Must be 0 

▼ 

0 => Default 16-bit., 1=> Default 32-bit 

T 

0 => Byte Granular, 1=> Page Granular 


Figure 4. Extended Access Rights/Type 

Function 000AH This function creates an alias to a code segment. This function creates a data descriptor 
that has the same base and limit as the specified code segment descriptor. Pass the 
following information: 

AX = 000AH 

BX = code segment selector 

If the call succeeds, the carry flag is clear and the new data selector is returned in AX. If 
the call fails, the carry flag is set. The call fails if the selector passed in BX is not a valid 
code segment. 

To deallocate an alias to a code segment, use Function 0001H. 

After the alias is created, it does not change if the code segment descriptor changes. For 
example, if the base or limit of the code segment change later, the alias descriptor stays the 
same. 

Function 000BH This function copies the descriptor table entry for a specified descriptor. The copy is 
written into an 8-byte buffer. Pass the following information: 

AX = 000BH 
BX = selector 

ES:EDI = a pointer to the 8-byte buffer for the descriptor copy 
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If the call succeeds, the carry flag is clear and ES:ED1 contains a pointer to the buffer that 
contains a copy of the descriptor. If the call fails, the carry flag is set. The call fails if the 
selector passed in BX is invalid or unallocated. 

Function 000CH This function copies an 8-byte buffer into the LDT for a specified descriptor. The 
descriptor must first have been allocated with Function 0000H. Pass the following 
information: 

AX = 000CH 
BX = selector 

ES:EDI = a pointer to the 8-byte buffer containing the descriptor 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. The call fails if 
the descriptor passed in BX is invalid. 

The type byte, byte 5, has the same format and requirements as the access rights/type byte 
passed to Function 0009H in CL. The format is shown in the first figure presented with the 
description of Function 0009H. 

The extended type byte, byte 6, has the same format and requirements as the extended 
access rights/type byte passed to Function 0009H in CH, except that the limit field can have 
any value, and the low order bits marked reserx’ed are used to set the upper 4 bits of the 
descriptor limit. The format is shown in the second figure presented with the description of 
Function 0009H. 

Function 000DH This function allocates a specific LDT descriptor. Pass the following information: 

AX = 000DH 
BX = selector 

If the call succeeds, the carry flag is clear and the specified descriptor is allocated. If the 
call fails, the carry flag is set. 

The call fails if the specified selector is already in use, or if it is not a valid LDT descriptor. 
The first lOh (16 decimal) descriptors are reserved for this function, and should not be used 
by the host. Some of these descriptors may be in use, however, if another client application 
is already loaded. 

To free the descriptor, use Function 0001H. 

11.2.2 DOS Memory Management Services 

Function 0100H This function allocates memory from the DOS free memory pool. This function returns 
both the real-mode segment and one or more descriptors that can be used by 
protected-mode applications. Pass the following information: 

AX = 0100H 

BX = the number of paragraphs (16-byte blocks) requested 

If the call succeeds, the carry flag is clear. AX contains the initial real-mode segment of 
the allocated block and DX contains the base selector for the allocated block. 
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If the call fails, the carry flag is set. AX contains the DOS error code. If memory is 
damaged, code 07H is returned. If there is not enough memory to satisfy the request, code 
08H is returned. BX contains the number of paragraphs in the largest available block of 
DOS memory. 

If you request a block larger than 64KB, contiguous descriptors are allocated. Use 
Function 0003H to find the value of the increment to the next descriptor. The limit of the 
first descriptor is set to the entire block. Subsequent descriptors have a limit of 64KB, 
except for the final descriptor, which has a limit of blocksize MOD 64KB. 

You cannot modify or deallocate descriptors allocated with this function. Function 101H 
deallocates the descriptors automatically. 

Function 0101H This function frees a DOS memory block allocated with function 0100H. Pass the 
following information: 

AX = 0101H 

DX = selector of the block to be freed 

If the call succeeds, the carry flag is clear. 

If the call fails, the carry flag is set and the DOS error code is returned in AX. If the 
incorrect segment was specified, code 09H is returned. If memory control blocks are 
damaged, code 07H is returned. 

All descriptors allocated for the specified memory block are deallocated automatically and 
cannot be accessed correctly after the block is freed. 

Function 0102H This function resizes a DOS memory block allocated with function 0100H. Pass the 
following information: 

AX = 0102H 

BX = the number of paragraphs (16-byte blocks) in the resized block 
DX = selector of block to resize 

If the call succeeds, the carry flag is clear. 

If the call fails, the carry flag is set, the maximum number of paragraphs available is 
returned in BX, and the DOS error code is returned in AX. If memory code blocks are 
damaged, code 07H is returned. If there isn’t enough memory to increase the size as 
requested, code 08H is returned. If the incorrect segment is specified, code 09h is returned. 

Because of the difficulty of finding additional contiguous memory or descriptors, this 
function is not often used to increase the size of a memory block. Increasing the size of a 
memory block might well fail because other DOS allocations have used contiguous space. 
If the next descriptor in the LDT is not free, allocation also fails when the size of a block 
grows over the 64KB boundary. 

If you shrink the size of a memory block, you may also free some descriptors allocated to 
the block. The initial selector remains unchanged, however; only the limits of subsequent 
selectors will change. 
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11.2.3 Interrupt Services 

Function 0200H This function gets the value of the current task’s real-mode interrupt vector for the 
specified interrupt. Pass the following information: 

AX = 0200H 

BL = interrupt number 

This call always succeeds. All 100H (256 decimal) interrupt vectors are supported by the 
host. When the call returns, the carry flag is clear, and the segment: offset of the 
real-mode interrupt handler is returned in CX:DX. 

Because the address returned in CX is a segment, and not a selector, you cannot put it into a 
protected-mode segment register. If you do, a general protection fault may occur. 

Function 0201H This function sets the value of the current task’s real-mode interrupt vector for the 
specified interrupt. Pass the following information: 

AX = 0201H 

BL = interrupt number 

CX:DX = segment:offset of the real-mode interrupt handler 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. 

The address passed in CX:DX should be a real-mode segment: of f set, such as 
function 0200H returns. For this reason, the interrupt handler must reside in DOS 
addressable memory. You can use Function 0100H to allocate DOS memory. This version 
does not support the real-mode callback address function. 

If you are hooking a hardware interrupt, you have to lock all segments involved. These 
segments include the segment in which the interrupt handler runs, and any segment it may 
touch at interrupt time. 

Function 0202H This function gets the processor exception handler vector. This function returns the 
CS:EIP of the current protected-mode exception handler for the specified exception 
number. Pass the following information: 

AX = 0202H 

BL = exception/fault number (OOh - lFh) 

If the call succeeds, the carry flag is clear and the selector: offset of the 
protected-mode exception handler is returned in CX:EDX. If it fails, the carry flag is set. 

The value returned in CX is a valid protected-mode selector, not a real-mode segment. 

Function 0203H This function sets the processor exception handler vector. This function allows 

protected-mode applications to intercept processor exceptions that are not handled by the 
DPMI environment. Programs may wish to handle exceptions such as "not present segment 
faults" which would otherwise generate a fatal error. Pass the following information: 
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AX = 0203H 

BL = exception/fault number (OOh - lFh) 

CX:EDX = selectorroffset of the exception handler 

If the call succeeds, the carry flag is clear. If it fails, the carry flag is set. 

The address passed in CX must be a valid protected-mode selector, such as Function 204H 
returns, and not a real-mode segment. A 32-bit implementation must supply a 32-bit offset 
in the EDX register. If the handler chains to the next handler, it must use a 32-bit interrupt 
stack frame to do so. 

The handler should return using a far return instruction. The original SS:ESP, CS:EIP and 
flags on the stack, including the interrupt flag, will be restored. 

All fault stack frames have an error code. However the error code is only valid for 
exceptions 08h, OAh, OBh, OCh, ODh, and OEh. 

The handler must preserve and restore all registers. 

The exception handler will be called on a locked stack with interrupts disabled. The 
original SS, ESP, CS, and EIP will be pushed on the exception handler stack frame. 

The handler must either return from the call by executing a far return or jump to the next 
handler in the chain (which will execute a far return or chain to the next handler). 

The procedure can modify any of the values on the stack pertaining to the exception before 
returning. This can be used, for example, to jump to a procedure by modifying the CS:EIP 
on the stack. Note that the procedure must not modify the far return address on the stack — 
it must return to the original caller. The caller will then restore the flags, CS:EIP and 
SS:ESP from the stack frame. 

If the DPMI client does not handle an exception, or jumps to the default exception handler, 
the host will reflect the exception as an interrupt for exceptions 0, 1, 2, 3, 4, 5 and 7. 
Exceptions 6 and 8 - lFh will be treated as fatal errors and the client will be terminated. 

Exception handlers will only be called for exceptions that occur in protected mode. 

Function 0204H This function gets the CS:EIP selector: offset of the current protected-mode 
interrupt handler for a specified interrupt number. Pass the following information: 

AX = 0204H 

BL = interrupt number 

This call always succeeds. All 100H (256 decimal) interrupt vectors are supported by the 
host. When the call returns, the carry flag is clear and CX:EDX contains the 
protected-mode selector: offset of the exception handler. 

A 32-bit offset is returned in the EDX register. 

Function 020511 This function sets the address of the specified protected-mode interrupt vector. Pass the 
following information: 
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AX = 0205H 

BL = interrupt number 

CX:EDX = selector:offset of the exception handler 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. 

The address passed in CX must be a valid protected-mode selector, such as Function 204H 
returns, and not a real-mode segment. A 32-bit implementation must supply a 32-bit offset 
in the EDX register. If the handler chains to the next handler, it must use a 32-bit interrupt 
stack frame to do so. 

11.2.4 Translation Services 

These services are provided so that protected-mode programs can call real-mode software that DPMI does 
not support directly. The protected-mode program must set up a data structure with the appropriate register 
values. This "real-mode call structure" is shown below. 
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Offset 

Register 

00H 

EDI 

04H 

ESI 

08H 

EBP 

OCH 

Reserved by system 

10H 

EBX 

14H 

EDX 

18H 

ECX 

1CH 

EAX 

20H 

Flags 

22H 

ES 

24H 

DS 

26H 

FS 

28H 

GS 

2AH 

IP 

2CH 

CS 

2EH 

SP 

3 OH 

SS 


After the call or interrupt is complete, all real-mode registers and flags except SS, SP, CS, and IP will be 
copied back to the real-mode call structure so that the caller can examine the real-mode return values. 

The values in the segment registers should be real-mode segments, not protected-mode selectors. 

The translation services will provide a real-mode stack if the SS:SP fields are zero. However, the stack 
provided is relatively small. If the real-mode procedure/interrupt routine uses more than 30 words of stack 
space then you should provide your own real-mode stack. 

Function 0300H This function simulates a real-mode interrupt. This function simulates an interrupt in real 
mode. It will invoke the CS:IP specified by the real-mode interrupt vector and the handler 
must return by executing an iret. Pass the following information: 
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AX = 0300H 

BL = interrupt number 

BH = flags Bit 0=1 resets the interrupt controller and A20 line. Other flags are 
reserved and must be 0. 

CX = number of words to copy from protected-mode stack to real-mode stack 
ES:EDI = the selectorroffset of real-mode call structure 

If the call fails, the carry flag is set. 

If the call succeeds, the carry flag is clear and ES:EDI contains the selector : offset 
of the modified real-mode call structure. 

The CS:IP in the real-mode call structure is ignored by this service. The appropriate 
interrupt handler will be called based on the value passed in BL. 

The flags specified in the real-mode call structure will be pushed on the real-mode stack 
iret frame. The interrupt handler will be called with the interrupt and trace flags clear. 

It is up to the caller to remove any parameters that were pushed on the protected-mode 
stack. 

The flag to reset the interrupt controller and the A20 line is ignored by DPMI 
implementations that run in Virtual 8086 mode. It causes DPMI implementations that 
return to real mode to set the interrupt controller and A20 address line hardware to its 
normal real-mode state. 

Function 0301H (DOS/4GW Professional only) This function calls a real-mode procedure with a FAR 

return frame. The called procedure must execute a FAR return when it completes. Pass the 
following information: 

AX = 0301H 

BH = flags Bit 0=1 resets the interrupt controller and A20 line. Other flags reserved 
and must be 0. 

CX = Number of words to copy from protected-mode to real-mode stack 
ES:EDI = selectorroffset of real-mode call structure 

If the call succeeds, the carry flag is clear and ES:EDI contains the selector : offset 
of modified real-mode call structure. 

If the call fails, the carry flag is set. 

Notes: 

1. The CS:IP in the real-mode call structure specifies the address of the real-mode 
procedure to call. 

2. The real-mode procedure must execute a FAR return when it has completed. 

3. If the SS:SP fields are zero then a real-mode stack will be provided by the DPMI 
host. Otherwise, the real-mode SS:SP will be set to the specified values before 
the procedure is called. 

4. When the Int 3lh returns, the real-mode call structure will contain the values that 
were returned by the real-mode procedure. 
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5. It is up to the caller to remove any parameters that were pushed on the 
protected-mode stack. 

6. The flag to reset the interrupt controller and A20 line is ignored by DPMI 
implementations that run in Virtual 8086 mode. It causes DPMI 
implementations that return to real mode to set the interrupt controller and A20 
address line hardware to its normal real-mode state. 

Function 0302H (DOS/4GW Professional only) This function calls a real-mode procedure with an iret 
frame. The called procedure must execute an iret when it completes. Pass the following 
information: 

AX = 0302H 

BH = flags Bit 0=1 resets the interrupt controller and A20 line. Other flags reserved 
and must be 0. 

CX = Number of words to copy from protected-mode to real-mode stack 
ES:EDI = selectorroffset of real-mode call structure 

If the call succeeds, the carry flag is clear and ES:EDI contains the selector : offset 
of modified real-mode call structure. 

If the call fails, the carry flag is set. 

Notes: 

1. The CS:IP in the real-mode call structure specifies the address of the real-mode 
procedure to call. 

2. The real-mode procedure must execute an iret when it has completed. 

3. If the SS:SP fields are zero then a real-mode stack will be provided by the DPMI 
host. Otherwise, the real-mode SS:SP will be set to the specified values before 
the procedure is called. 

4. When the Int 3lh returns, the real-mode call structure will contain the values that 
were returned by the real-mode procedure. 

5. The flags specified in the real-mode call structure will be pushed the real-mode 
stack iret frame. The procedure will be called with the interrupt and trace 
flags clear. 

6. It is up to the caller to remove any parameters that were pushed on the 
protected-mode stack. 

7. The flag to reset the interrupt controller and A20 line is ignored by DPMI 
implementations that run in Virtual 8086 mode. It causes DPMI 
implementations that return to real mode to set the interrupt controller and A20 
address line hardware to its normal real-mode state. 

Function 0303H (DOS/4GW Professional only) This function allocates a real-mode callback address. This 
service is used to obtain a unique real-mode SEG:OFFSET that will transfer control from 
real mode to a protected-mode procedure. 
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At times it is necessary to hook a real-mode interrupt or device callback in a 
protected-mode driver. For example, many mouse drivers call an address whenever the 
mouse is moved. Software running in protected mode can use a real-mode callback to 
intercept the mouse driver calls. Pass the following information: 

AX = 0303H 

DS:ESI = selectorroffset of procedure to call 
ES:EDI = selector: offset of real-mode call structure 

If the call succeeds, the carry flag is clear and CX:DX contains the segment: offset of 
real-mode callback address. 

If the call fails, the carry flag is set. 

Callback Procedure Parameters 

Interrupts disabled 

DS:ESI = selector:offset of real-mode SS:SP 
ES:EDI = selector:offset of real-mode call structure 
SS:ESP = Locked protected-mode API stack 
All other registers undefined 

Return from Callback Procedure 

Execute an IRET to return 

ES:EDI = selector:offset of real-mode call structure 
to restore (see note) 


Notes: 

1. Since the real-mode call structure is static, you must be careful when writing 
code that may be reentered. The simplest method of avoiding reentrancy is to 
leave interrupts disabled throughout the entire call. However, if the amount of 
code executed by the callback is large then you will need to copy the real-mode 
call structure into another buffer. You can then return with ES:EDI pointing to 
the buffer you copied the data to — it does not have to point to the original real 
mode call structure. 

2. The called procedure is responsible for modifying the real-mode CS:IP before 
returning. If the real-mode CS:IP is left unchanged then the real-mode callback 
will be executed immediately and your procedure will be called again. Normally 
you will want to pop a return address off of the real-mode stack and place it in 
the real-mode CS:IP. The example code in the next section demonstrates 
chaining to another interrupt handler and simulating a real-mode iret. 

3. To return values to the real-mode caller, you must modify the real-mode call 
structure. 

4. Remember that all segment values in the real-mode call structure will contain 
real-mode segments, not selectors. If you need to examine data pointed to by a 
real-mode seg:offset pointer, you should not use the segment to selector service 
to create a new selector. Instead, allocate a descriptor during initialization and 
change the descriptor’s base to 16 times the real-mode segment’s value. This is 
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important since selectors allocated though the segment to selector service can 
never be freed. 

5. DPMI hosts should provide a minimum of 16 callback addresses per task. 

The following code is a sample of a real-mode interrupt hook. It hooks the DOS Int 21h 
and returns an error for the delete file function (AH=41h). Other calls are passed through 
to DOS. This example is somewhat silly but it demonstrates the techniques used to hook a 
real mode interrupt. Note that since DOS calls are reflected from protected mode to real 
mode, the following code will intercept all DOS calls from both real mode and protected 
mode. 
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• •k'k-k-k-k-k'k'k'k'k'k'k-k-k-k-k-k'k'k'k-k-k'k-k-k'k-k-k-k-k'k-k-k'k'k'k-k-k'k-k'k'k'k'k'k'k'k'k'k'k'k'k-k-k 

; This procedure gets the current Int 21h real-mode 
; Seg:Offset, allocates a real-mode callback address, 

; and sets the real-mode Int 21h vector to the call- 
; back address. 

• •k-k'k'k-k'k'k'k'kic'k'kicic'k-k'k'k'k'k'k-k'k'k'k'k'k'k'k-k'k'k-k-k'k'k-k-kic'k'k-k'k'k'k'k-k'k'k'k'k'k'k'k 

Initialization_ Code: 


; Create a code segment alias to save data in 

mov ax, OOOAh 

mov bx, cs 

int 31h 

j c ERROR 

mov ds, ax 

ASSUMES DS,_ TEXT 


; Get current Int 21h real-mode SEG:OFFSET 


mov 

ax, 0200h 


mov 

bl, 21h 


int 

31h 


jc 

ERROR 


mov 

[Orig_ Real_ 

Seg], cx 

mov 

[Orig_ Real_ 

Offset], 


; Allocate a real-mode callback 


mov ax, 0303h 

push ds 

mov bx, cs 

mov ds, bx 

mov si, OFFSET My_ Int_ 21_ Hook 

pop es 

mov di, OFFSET My_ Real_ Mode_ Call_ St rue 

int 31h 

j c ERROR 

; Hook real-mode int 21h with the callback address 

mov ax, 0201h 

mov bl, 21h 

int 31h 

jc ERROR 

• •k'k'k'k-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k-k'k'k-k'k'k'k'k-k'k'k'k'k'kic-k-k'k'k'k'k'k'k'k-k'k'k'k'k'k'k'kicic 

; This is the actual Int 21h hook code. It will return 
; an "access denied" error for all calls made in real 
; mode to delete a file. Other calls will be passed 
; through to DOS. 

; ENTRY: 

; DS:SI -> Real-mode SS:SP 

; ES:DI -> Real-mode call structure 

; Interrupts disabled 

; EXIT: 

; ES:DI -> Real-mode call structure 

• ******************************************************* 


My_ Int_ 21_ Hook: 

emp es : [di . RealMode_ AH] , 41h 

jne Chain_ To_ DOS 

; This is a delete file call (AH=41h). Simulate an 
; iret on the real-mode stack, set the real-mode 
; carry flag, and set the real-mode AX to 5 to indicate 
; an access denied error. 
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cld 

lodsw 


; Get 

real-mode 

ret 

IP 

mov 

es: 

[di . RealMode_ IP ] , 

ax 



lodsw 


; Get 

real-mode 

ret 

CS 

mov 

es: 

[di . RealMode_ CS ] , 

ax 



lodsw 


; Get 

real-mode 

flags 

or 

ax. 

1 ; Set 

carry flag 


mov 

es: 

[di.RealMode_ Flags 

] , ax 



add 

es: 

[di . RealMode_ SP ] , 

6 



mov 

es: 

[di .RealMode_ AX] , 

5 



jmp 

My_ 

. Hook_ Exit 





; Chain to original Int 21h vector by replacing the 
; real-mode CS:IP with the original Seg:Offset. 

Chain_ To_ DOS: 


mov 

ax, cs : [Orig_Real_ 

Seg] 

mov 

es:[di.RealMode_ CS 

] i ax 

mov 

ax, cs:[Orig_ Real_ 

Offset 

mov 

es:[di.RealMode_ IP 

] t ax 


My_ Hook_ Exit: 

iret 


Function 0304H (DOS/4GW Professional only) This function frees a real-mode callback address that was 
allocated through the allocate real-mode callback address service. Pass the following 
information: 

AX = 0304H 

CX:DX = Real-mode callback address to free 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. 

Notes: 

1. Real-mode callbacks are a limited resource. Your code should free any break 
point that it is no longer using. 


11.2.5 DPMI Version 

Function 0400H This function returns the version of DPMI services supported. Note that this is not 

necessarily the version of any operating system that supports DPMI. It should be used by 
programs to determine what calls are legal in the current environment. Pass the following 
information: 

AX = 0400H 

The information returned is: 

AH = Major version 
AL = Minor version 

BX = Flags Bit 0 = 1 if running under an 80386 DPMI implementation. Bit 1 = 1 if 
processor is returned to real mode for reflected interrupts (as opposed to 
Virtual 8086 mode). Bit 2 = 1 if virtual memory is supported. Bit 3 is 
reserved and undefined. All other bits are zero and reserved for later use. 

CL = Processor type 
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02 = 80286 
03 = 80386 
04 = 80486 
05 = Pentium 

DH = Current value of virtual master PIC base interrupt 
DL = Current value of virtual slave PIC base interrupt 
Carry flag clear (call cannot fail) 

11.2.6 Memory Management Services 

Function 0500H This function gets information about free memory. Pass the following information: 

AX = 0500H 

ES:EDI = the selector:offset of a 30H byte buffer. 

If the call fails, the carry flag is set. 

If the call succeeds, the carry flag is clear and ES:EDI contains the selector : offset 
of a buffer with the structure shown in the figure below. 


Offset 

Description 

00H 

Fargest available block, in bytes 

04H 

Maximum unlocked page allocation 

08H 

Fargest block of memory (in pages) that could 
be allocated and then locked 

0CH 

Total linear address space size, in pages, including 
already allocated pages 

10H 

Total number of free pages and pages currently 
unlocked and available for paging out 

14H 

Number of physical pages not in use 

18H 

Total number of physical pages managed by host 

1CH 

Free linear address space, in pages 

20H 

Size of paging/file partition, in pages 

n 

Reserved 


Only the first field of the structure is guaranteed to contain a valid value. Any field that is 
not returned by DOS/4GW is set to -1 (OFFFFFFFFH). 
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Function 0501H This function allocates and commits linear memory. Pass the following information: 

AX = 0501H 

BX:CX = size of memory to allocate, in bytes. 

If the call succeeds, the carry flag is clear, BX:CX contains the linear address of the 
allocated memory, and SI:DI contains the memory block handle used to free or resize the 
block. If the call fails, the carry flag is set. 

No selectors are allocated for the memory block. The caller must allocate and initialize 
selectors needed to access the memory. 

If VMM is present, the memory is allocated as unlocked, page granular blocks. Because of 
the page granularity, memory should be allocated in multiples of 4KB. 

Function 0502H This function frees a block of memory allocated through function 0501H. Pass the 
following information: 

AX = 0502H 

SI:DI = handle returned with function 0501H when memory was allocated 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. You must also 
free any selectors allocated to point to the freed memory block. 

Function 0503H This function resizes a block of memory allocated through the 0501H function. If you 
resize a block of linear memory, it may have a new linear address and a new handle. Pass 
the following information: 

AX = 0503H 

BX:CX = new size of memory block, in bytes 

SI:DI = handle returned with function 0501H when memory was allocated 

If the call succeeds, the carry flag is clear, BX:CX contains the new linear address of the 
memory block, and SI:DI contains the new handle of the memory block. If the call fails, 
the carry flag is set. 

If either the linear address or the handle has changed, update the selectors that point to the 
memory block. Use the new handle instead of the old one. 

You cannot resize a memory block to zero bytes. 

11.2.7 Page Locking Services 

These services are only useful under DPMI implementations that support virtual memory. Although 
memory ranges are specified in bytes, the actual unit of memory that will be locked will be one or more 
pages. Page locks are maintained as a count. When the count is decremented to zero, the page is unlocked 
and can be swapped to disk. This means that if a region of memory is locked three times then it must be 
unlocked three times before the pages will be unlocked. 
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Function 0600H This function locks a specified linear address range. Pass the following information: 

AX = 0600H 

BX:CX = starting linear address of memory to lock 
SI:DI = size of region to lock (in bytes) 

If the call fails, the carry flag is set and none of the memory will be locked. 

If the call succeeds, the carry flag is clear. If the specified region overlaps part of a page at 
the beginning or end of a region, the page(s) will be locked. 

Function 0601H This function unlocks a specified linear address range that was previously locked using 
the "lock linear region" function (0600h). Pass the following information: 

AX = 0601H 

BX:CX = starting linear address of memory to unlock 
SI:DI = size of region to unlock (in bytes) 

If the call fails, the carry flag is set and none of the memory will be unlocked. An error 
will be returned if the memory was not previously locked or if the specified region is 
invalid. 

If the call succeeds, the carry flag is clear. If the specified region overlaps part of a page at 
the beginning or end of a region, the page(s) will be unlocked. Even if the call succeeds, 
the memory will remain locked if the lock count is not decremented to zero. 

Function 0604H This function gets the page size for Virtual Memory (VM) only. This function returns the 
size of a single memory page in bytes. Pass the following information: 

AX = 0604H 

If the call succeeds, the carry flag is clear and BX:CX = Page size in bytes. 

If the call fails, the carry flag is set. 

11.2.8 Demand Paging Performance Tuning Services 

Some applications will discard memory objects or will not access objects for long periods of time. These 
services can be used to improve the performance of demand paging. 

Although these functions are only relevant for DPMI implementations that support virtual memory, other 
implementations will ignore these functions (it will always return carry clear). Therefore your code can 
always call these functions regardless of the environment it is running under. 

Since both of these functions are simply advisory functions, the operating system may choose to ignore 
them. In any case, your code should function properly even if the functions fail. 

Function 0702H (DOS/4GW Professional only) This function marks a page as a demand paging candidate. 

This function is used to inform the operating system that a range of pages should be placed 
at the head of the page out candidate list. This will force these pages to be swapped to disk 
ahead of other pages even if the memory has been accessed recently. However, all memory 
contents will be preserved. 
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This is useful, for example, if a program knows that a given piece of data will not be 
accessed for a long period of time. That data is ideal for swapping to disk since the 
physical memory it now occupies can be used for other purposes. Pass the following 
information: 

AX = 0702H 

BX:CX = Starting linear address of pages to mark 
SI:DI = Number of bytes to mark as paging candidates 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. 

Notes: 

1. This function does not force the pages to be swapped to disk immediately. 

2. Partial pages will not be discarded. 

Function 0703H (DOS/4GW Professional only) This function discards page contents. This function 
discards the entire contents of a given linear memory range. It is used after a memory 
object that occupied a given piece of memory has been discarded. 

The contents of the region will be undefined the next time the memory is accessed. All 
values previously stored in this memory will be lost. Pass the following information: 

AX = 0703H 

BX:CX = Starting linear address of pages to discard 
SI:DI = Number of bytes to discard 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. 

Notes: 

1. Partial pages will not be discarded. 

11.2.9 Physical Address Mapping 

Memory mapped devices such as network adapters and displays sometimes have memory mapped at 
physical addresses that lie outside of the normal 1Mb of memory that is addressable in real mode. Under 
many implementations of DPMI, all addresses are linear addresses since they use the paging mechanism of 
the 80386. This service can be used by device drivers to convert a physical address into a linear address. 
The linear address can then be used to access the device memory. 

Function 0800H This function is used for Physical Address Mapping. 

Some implementations of DPMI may not support this call because it could be used to 
circumvent system protection. This call should only be used by programs that absolutely 
require direct access to a memory mapped device. 

Pass the following information: 
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AX = 0800H 

BX:CX = Physical address of memory 
SI:DI = Size of region to map in bytes 

If the call succeeds, the carry flag is clear and BX:CX = Linear Address that can be used to 
access the physical memory. 

If the call fails, the carry flag is set. 

Notes: 

1. Under DPMI implementations that do not use the 80386 paging mechanism, the 
call will always succeed and the address returned will be equal to the physical 
address parameter passed into this function. 

2. It is up to the caller to build an appropriate selector to access the memory. 

3. Do not use this service to access memory that is mapped in the first megabyte of 
address space (the real-mode addressable region). 

Function 0801H This function is used to free Physical Address Mapping. Pass the following information: 

AX = 0801H 

BX:CX = Linear address returned by Function 0800H. 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. 

Notes: 

1. The client should call this function when it is finished using a device previously 
mapped to linear addresses with the Physical Address Mapping function 
(Function 0800H). 

11.2.10 Virtual Interrupt State Functions 

Under many implementations of DPMI, the interrupt flag in protected mode will always be set (interrupts 
enabled). This is because the program is running under a protected operating system that cannot allow 
programs to disable physical hardware interrupts. However, the operating system will maintain a "virtual" 
interrupt state for protected-mode programs. When the program executes a CLI instruction, the program’s 
virtual interrupt state will be disabled, and the program will not receive any hardware interrupts until it 
executes an STI to reenable interrupts (or calls service 0901h). 

When a protected-mode program executes a PUSHF instruction, the real processor flags will be pushed 
onto the stack. Thus, examining the flags pushed on the stack is not sufficient to determine the state of the 
program’s virtual interrupt flag. These services enable programs to get and modify the state of their virtual 
interrupt flag. 

The following sample code enters an interrupt critical section and then restores the virtual interrupt state to 
it’s previous state. 
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; Disable interrupts and get previous interrupt state 

mov ax, 0900h 

int 31h 

; At this point AX = 0900h or 0901h 


; Restore previous state (assumes AX unchanged) 
int 31h 

Function 0900H This function gets and disables Virtual Interrupt State. This function will disable the 
virtual interrupt flag and return the previous state of the virtual interrupt flag. Pass the 
following information: 

AX = 0900H 

After the call, the carry flag is clear (this function always succeeds) and virtual interrupts 
are disabled. 

AL = 0 if virtual interrupts were previously disabled. 

AL = 1 if virtual interrupts were previously enabled. 

Notes: 

1. AH will not be changed by this procedure. Therefore, to restore the previous 
state, simply execute an Int 3 lh. 

Function 0901H This function gets and enables the Virtual Interrupt State. This function will enable the 
virtual interrupt flag and return the previous state of the virtual interrupt flag. Pass the 
following information: 

AX = 0901H 

After the call, the carry flag is clear (this function always succeeds) and virtual interrupts 
are enabled. 

AL = 0 if virtual interrupts were previously disabled. 

AL = 1 if virtual interrupts were previously enabled. 

Notes: 

1. AH will not be changed by this procedure. Therefore, to restore the previous 
state, simply execute an Int 3 lh. 

Function 0902H This function gets the Virtual Interrupt State. This function will return the current state of 
the virtual interrupt flag. Pass the following information: 
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AX = 0902H 

After the call, the carry flag is clear (this function always succeeds). 

AL = 0 if virtual interrupts are disabled. 

AL = 1 if virtual interrupts are enabled. 

11.2.11 Vendor Specific Extensions 

Some DOS extenders provide extensions to the standard set of DPMI calls. This call is used to obtain an 
address which must be called to use the extensions. The caller points DS:ESI to a null terminated string 
that specifies the vendor name or some other unique identifier to obtain the specific extension entry point. 

Function 0A00H This function gets Tenberry Software’s API Entry Point. Pass the following information: 

AX = 0A00H 

DS:ESI = Pointer to null terminated string "RATIONAL DOS/4G" 

If the call succeeds, the carry flag is clear and ES:EDI = Extended API entry point. DS, 

FS, GS, EAX, EBX, ECX, EDX, ESI, and EBP may be modified. 

If the call fails, the carry flag is set. 

Notes: 

1. Execute a far call to call the API entry point. 

2. All extended API parameters are specified by the vendor. 

3. The string comparison used to return the API entry point is case sensitive. 

11.2.12 Coprocessor Status 

Function 0E00H This function gets the coprocessor status. Pass the following information: 

AX = 0E00H 

If the call succeeds, the carry flag is clear and AX contains the coprocessor status. 

Bit Significance 

0 MPv (MP bit in the virtual MSW/CRO). 

0 = Numeric coprocessor is disabled for this client. 

1 = Numeric coprocessor is disabled for this client. 

1 EMv (EM bit in the virtual MSW/CRO). 

0 = Client is not emulating coprocessor instructions. 

1 = Client is emulating coprocessor instructions. 

2 MPr (MP bit from the actual MSW/CRO). 

0 = Numeric coprocessor is not present. 

1 = Numeric coprocessor is present. 
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1 EMr (EM bit from the actual MSW/CRO). 

0 = Host is not emulating coprocessor instructions. 

1 = Host is emulating coprocessor instructions. 

4-7 Coprocessor type. 

00H = no coprocessor. 

02H = 80287 

03H = 80387 

04H = 80486 with numeric coprocessor 

05 H = Pentium 

8-15 Not applicable. 

If the call fails, the carry flag is set. 

Notes: 

1. If the real EM (EMr) bit is set, the host is supplying or is capable of supplying 
floating-point emulation. 

2. If the MPv bit is not set, the host may not need to save the coprocessor state for 
this virtual machine to improve system performance. 

3. The MPr bit setting should be consistent with the setting of the coprocessor type 
information. Ignore MPr bit information if it is in conflict with the coprocessor 
type information. 

4. If the virtual EM (EMv) bit is set, the host delivers all coprocessor exceptions to 
the client, and the client is performing its own floating-point emulation (wether 
or not a coprocessor is present or the host also has a floating-point emulator). In 
other words, if the EMv bit is set, the host sets the EM bit in the real CRO while 
the virtual machine is active, and reflects coprocessor not present faults (int 7) to 
the virtual machine. 

5. A client can determine the CPU type with int 31H Function 0400H, but a client 
should not draw any conclusions about the presence or absence of a coprocessor 
based on the CPU type alone. 

Function 0E01H This function sets coprocessor emulation. Pass the following information: 

AX = 0E01H 

BX = coprocessor bits 

Bit Significance 

0 New value of MPv bit for client’s virtual CRO. 

0 = Disable numeric coprocessor for this client. 

1 = Enable numeric coprocessor for this client. 

1 New value of EMv bit for client’s virtual CRO. 

0 = client will not supply coprocessor emulation. 

1 = client will supply coprocessor emulation. 

2-15 Not applicable. 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. 
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This chapter describes the Tenberry Software DOS/4GW utility programs provided with the Open Watcom 

F77 package. Each program is described using the following format: 

Purpose: This is a brief statement of what the utility program does. More specific information is provided 
under "Notes". 

Syntax: This shows the syntax of the program. The fixed portion of each command is in a 

typewriter font, while variable parts of the command are in italics. Optional parts are 
enclosed in [brackets]. 

Notes: These are explanatory remarks noting major features and possible pitfalls. We explain anything 

special that you might need to know about the program. 

See Also: This is a cross-reference to any information that is related to the program. 

Example: You'll find one or more sample uses of the utility program with an explanation of what the 
program is doing. 

Some of the utilities are DOS/4G W-bascd, protected-mode programs. To determine which programs run in 

protected mode and which in real, run the program. If you see the DOS/4GW banner, the program runs in 

protected mode. 


Utilities 69 




The D0S/4GW DOS Extender 


12.1 D0S4GW 


Purpose: Loads and executes linear executables. 

Syntax: linear_executable 

Notes: The stub program at the beginning of the linear executable invokes this program, which loads the 

linear executable and starts up the DOS extender. The stub program must be able to find 
DOS4GW: make sure it is in the path. 
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12.2 PMINFO 

Purpose: Measures the performance of protected/real-mode switching and extended memory. 

Syntax: PMINFO. EXE 

Notes: We encourage you to distribute this program to your users. 

The time-based measurements made by PMINFO may vary slightly from run to run. 

Example: The following example shows the output of the PMINFO program on a 386 AT-compatible 
machine. 


Opminfo 

Protected Mode and Extended Memory Performance Measurement — 5.00 
Copyright (c) Tenberry Software, Inc. 1987 - 1993 


DOS memory Extended memory 


CPU performance equivalent to 67.0 MHz 80486 


736 

640 

651 

22.0 (3.0) 
42.9 (3.0) 


8012 
15360 
7887 
18.9 (4.0) 
37.0 (4.0) 


K bytes configured (according to BIOS). 

K bytes physically present (SETUP). 

K bytes available for DOS/16M programs. 
MB/sec word transfer rate (wait states) . 
MB/sec 32-bit transfer rate (wait states). 


Overall cpu and memory performance (non-floating point) for typical 
DOS programs is 10.36 ae 1.04 times an 8MHz IBM PC/AT. 


Protected/Real switch rate = 36156/sec (27 usec/switch, 15 up + 11 down), 
DOS/16M switch mode 11 (VCPI). 


The top information line shows that the CPU performance is equivalent to a 67.0 MHz 80486. 
Below are the configuration and timings for both the DOS memory and extended memory. If the 
computer is not equipped with extended memory, or none is available for DOS/4GW, the 
extended memory measurements may be omitted 

The line "according to BIOS" shows the information provided by the BIOS (interrupts 12h and 
15h function 88h). The line "SETUP", if displayed, is the configuration obtained directly from 
the CMOS RAM as set by the computer’s setup program. It is displayed only if the numbers are 
different from those in the BIOS line. They will be different for computers where the BIOS has 
reserved memory for itself or if another program has allocated some memory and is intercepting 
the BIOS configuration requests to report less memory available than is physically configured. 
The "DOS/16M memory range", if displayed, shows the low and high addresses available to 
DOS/4GW in extended memory. 

Below the configuration information is information on the memory speed (transfer rate). 
PMINFO tries to determine the memory architecture. Some architectures will perform well 
under some circumstances and poorly under others; PMINFO will show both the best and worst 
cases. The architectures detected are cache, interleaved, page-mode (or static column), and 
direct. Measurements are made using 32-bit accesses and reported as the number of megabytes 
per second that can be transferred. The number of wait states is reported in parentheses. The 
wait states can be a fractional number, like 0.5, if there is a wait state on writes but not on reads. 
Memory bandwidth (i.e., how fast the CPU can access memory) accounts for 60% to 70% of the 
performance for typical programs (that are not heavily dependent on floating-point math). 
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A performance metric developed by Tenberry Software is displayed, showing the expected 
throughput for the computer relative to a standard 8MHz IBM PC/AT (disk accesses and floating 
point are excluded). Finally, the speed with which the computer can switch between real and 
protected mode is displayed, both as the maximum number of round-trip switches that can occur 
per second, and the time for a single round-trip switch, broken out into the real-to-protected (up) 
and protected-to-real (down) components. 
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12.3 PRIVATXM 


Purpose: Creates a private pool of memory for DOS/4GW programs. 

Syntax: PRIVATXM [ —r ] 

Notes: This program may be distributed to your users. 

Without PRIVATXM, a DOS/4GW program that starts up while another DOS/4GW program is 
active uses the pool of memory built by the first program. The new program cannot change the 
parameters of this memory pool, so setting DOS16M to increase the size of the pool has no 
effect. To specify that the two programs use different pools of memory, use PRIVATXM. 

PRIVATXM marks the active DOS/4GW programs as private, preventing subsequent DOS/4GW 
programs from using the same memory pool. The first DOS/4GW program to start after 
PRIVATXM sets up a new pool of memory for itself and any subsequent DOS/4GW programs. 
To release the memory used by the private programs, use the PRIVATXM -r option. 

PRIVATXM is a TSR that requires less than 500 bytes of memory. It is not supported under 
DPMI. 

Example: The following example creates a 512KB memory pool that is shared by two DOS/4GW TSRs. 
Subsequent DOS/4GW programs use a different memory pool. 


C>set DO SI 6M= :512 
C>TSR1 
C>TSR2 
C>PRIVA TXM 
C>set DO SI 6M= 
C>PR OGRAM3 
C>PRIVA TXM -R 


Specifies the size of the memory pool. 

Sets up the memory pool at startup. 

This TSR shares the pool built by TSR1. 

Makes subsequent DOS/4GW programs use a new memory pool. 
Specifies an unlimited size for the new pool. 

This program uses the new memory pool. 

Releases the 512KB memory pool used by the TSRs. (If the TSRs 
shut down, their memory is not released unless PRIVATXM is 
released.) 


PRIVATXM 73 




The D0S/4GW DOS Extender 


12.4 RMINFO 


Purpose: Supplies configuration information and the basis for real/protected-mode switching in your 
machine. 

Syntax: RMINFO. EXE 

Notes: This program may be distributed to your users. 

RMINFO starts up DOS/4GW, but stops your machine just short of switching from real mode to 
protected mode and displays configuration information about your computer. The information 
shown by RMINFO can help determine why DOS/4GW applications won't run on a particular 
machine. Run RMINFO if PMINFO does not run to completion. 

Example: The following example shows the output of the RMINFO program on an 386 AT-compatible 
machine. 


Orminfo 


DOS/16M Real Mode Information Program 5.00 
Copyright (C) Tenberry Software 


Machine and Environment: 
Processor: 

Machine type: 

A20 now: 

A20 switch rigor: 

DPMI host found 
Switching Functions: 

To PM switch: 

To RM switch: 

Nominal switch mode: 
Switch control flags: 
Memory Interfaces: 

DPMI may provide: 
Contiguous DOS memory: 


Inc. 1987 - 1993 


i386, coprocessor present 
10 (AT-compatible) 
enabled 
disabled 


DPMI 

DPMI 

0 

0000 

16384K returnable 
463K 


The information provided by RMINFO includes: 

Machine and Environment: 

Processor: processor type, coprocessor present/not present 

Machine type: 
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(NEC 9801) 

(PS/2-compatible) 

(AT-compatible) 

(FM R) 

(AT&T 6300+) 

(AT-compatible) 

(C&T 230 chipset) 

(AT-compatible) 

(AT-compatible) 

(Acer) 

(Zenith) 

(Hitachi) 

(Okidata) 

(PS/55) 

A20 now: Current state of Address line 20. 

A20 switch rigor: Whether DOS4GW rigorously controls enabling and disabling of Address line 
20 when switching modes. 


PS feature flag 

XMS host found Whether your system has any software using extended memory under the XMS 
discipline. 

VCPI host found Whether your system has any software using extended memory under the 
VCPI discipline. 

page table 0 at: xOOOh 

DPMI host found 

DOS/16M resident with private/public memory 

Switching Functions: 

A20 switching: 

To PM switch: reset catch: 

pre-PM prep: 
post-PM-switch: 

To RM switch: 

pre-RM prep: 
reset method: 
post-reset: 
reset uncatch: 

Nominal switch mode: x 

Switch control flags: xxxxh 
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Memory Interfaces: 

(VCPI remapping in effect) 

DPMI may provide: xxxxxK returnable 

VCPI may provide: xxxxxK returnable 

Top-down 

Other16M 

Forced 

Contiguous DOS memory: 
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13 Error Messages 


The following lists DOS/4G error messages, with descriptions of the circumstances in which the error is 
most likely to occur, and suggestions for remedying the problem. Some error messages pertaining to 
features — like DLLs — that are not supported in DOS/4GW will not arise with that product. In the 
following descriptions, references to DOS/4G, DOS4G, or DOS4G.EXE may be replaced by DOS/4GW, 
DOS4GW, or DOS4GW.EXE should the error message arise when using DOS/4GW. 

13.1 Kernel Error Messages 

This section describes error messages from the DOS/16M kernel embedded in DOS/4G. Kernel error 
messages may occur because of severe resource shortages, corruption of DOS4GW.EXE, corruption of 
memory, operating system incompatibilities, or internal errors in DOS/4GW. All of these messages are 
quite rare. 

0. involuntary switch to real mode 

The computer was in protected mode but switched to real mode without going through DOS/16M. This 
error most often occurs because of an unrecoverable stack segment exception (stack overflow), but can 
also occur if the Global Descriptor Table or Interrupt Descriptor Table is corrupted. Increase the stack 
size, recompile your program with stack overflow checking, or look into ways that the descriptor tables 
may have been overwritten. 

1. not enough extended memory 

2. not a DOS/16M executable <filename> 

DOS4G.EXE, or a bound DOS/4G application, has probably been corrupted in some way. Rebuild or 
recopy the file. 

3. no DOS memory for transparent segment 

4. cannot make transparent segment 

5. too many transparent segments 

6. not enough memory to load program 

There is not enough memory to load DOS/4G. Make more memory available and try again. 

7. no relocation segment 

8. cannot open file <filename> 

The DOS/16M loader cannot load DOS/4G, probably because DOS has run out of file units. Set a 
larger FILES= entry in CONFIG.SYS, reboot, and try again. 
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9. cannot allocate tstack 

There is not enough memory to load DOS/4G. Make more memory available and try again. 

10. cannot allocate memory for GDT 

There is not enough memory to load DOS/4G. Make more memory available and try again. 

11. no passup stack selectors — GDT too small 

This error indicates an internal error in DOS/4G or an incompatibility with other software. 

12. no control program selectors — GDT too small 

This error indicates an internal error in DOS/4G or an incompatibility with other software. 

13. cannot allocate transfer buffer 

There is not enough memory to load DOS/4G. Make more memory available and try again. 

14. premature EOF 

DOS4G.EXE, or a bound DOS/4G application, has probably been corrupted in some way. Rebuild or 
recopy the file. 

15. protected mode available only with 386 or 486 

DOS/4G requires an 80386 (or later) CPU. It cannot run on an 80286 or earlier CPU. 

16. cannot run under OS/2 

17. system software does not follow VCPI or DPMI specifications 

Some memory resident program has put your 386 or 486 CPU into Virtual 8086 mode. This is done to 
provide special memory services to DOS programs, such as EMS simulation (EMS interface without 
EMS hardware) or high memory. In this mode, it is not possible to switch into protected mode unless 
the resident software follows a standard that DOS/16M supports (DPMI, VCPI, and XMS are the most 
common). Contact the vendor of your memory management software. 

18. you must specify an extended memory range (SET DOS16M= ) 

On some Japanese machines that are not IBM AT-compatible, and have no protocol for managing 
extended memory, you must set the DOS16M environment variable to specify the range of available 
extended memory. 

19. computer must be AT- or PS/2- compatible 

20. unsupported DOS16M switchmode choice 

21. requires DOS 3.0 or later 

22. cannot free memory 

This error probably indicates that memory was corrupted during execution of your program. 
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23. no memory for VCPI page table 

There is not enough memory to load DOS/4G. Make more memory available and try again. 

24. VCPI page table address incorrect 
This is an internal error. 

25. cannot initialize VCPI 

This error indicates an incompatibility with other software. DOS/16M has detected that VCPI is 
present, but VCPI returns an error when DOS/16M tries to initialize the interface. 

26. 8042 timeout 

27. extended memory is configured but it cannot be allocated 

28. memory error, avail loop 

This error probably indicates that memory was corrupted during execution of your program. Using an 
invalid or stale alias selector may cause this error. Incorrect manipulation of segment descriptors may 
also cause it. 

29. memory error, out of range 

This error probably indicates that memory was corrupted during execution of your program. Writing 
through an invalid or stale alias selector may cause this error. 

30. program must be built -AUTO for DPMI 

31. protected mode already in use in this DPMI virtual machine 

32. DPMI host error (possibly insufficient memory) 

33. DPMI host error (need 64K XMS) 

34. DPMI host error (cannot lock stack) 

Any of these errors (32, 33, 34) probably indicate insufficient memory under DPMI. Under Windows, 
you might try making more physical memory available by eliminating or reducing any RAM drives or 
disk caches. You might also try editing DEFAULT.PIF so that at least 64KB of XMS memory is 
available to non-Windows programs. Under OS/2, you want to increase the DPMI_MEMORY_FIMIT 
in the DOS box settings. 

35. General Protection Fault 

This message probably indicates an internal error in DOS/4G. Faults generated by your program should 
cause error 2001 instead. 

36. The DOS16M.386 virtual device driver was never loaded 

37. Unable to reserve selectors for DOS16M.386 Windows driver 
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38. Cannot use extended memory: HIMEM.SYS not version 2 

This error indicates an incompatibility with an old version of HIMEM.SYS. 

39. An obsolete version of DOS16M.386 was loaded 

40. not enough available extended memory (XMIN) 

This message probably indicates an incompatibility with your memory manager or its configuration. 
Try configuring the memory manager to provide more extended memory, or change memory managers. 


13.2 D0S/4G Errors 

1000 "can’t hook interrupts" 

A DPMI host has prevented DOS/4G from loading. Please contact Tenberry Technical Support. 

1001 "error in interrupt chain" 

DOS/4G internal error. Please contact Tenberry Technical Support. 

1003 "can’t lock extender kernel in memory" 

DOS/4G couldn’t lock the kernel in physical memory, probably because of a memory shortage. 

1004 "syntax is DOS4G <executable.xxx>" 

You must specify a program name. 

1005 "not enough memory for dispatcher data" 

There is not enough memory for DOS/4G to manage user-installed interrupt handlers properly. Free 
some memory for the DOS/4G application. 

1007 "can’t find file <program> to load" 

DOS/4G could not open the specified program. Probably the file didn't exist. It is possible that 
DOS ran out of file handles, or that a network or similar utility has prohibited read access to the 
program. Make sure that the file name was spelled correctly. 

1008 "can’t load executable format for file <filename> [<error code>]" 

DOS/4G did not recognize the specified file as a valid executable file. DOS/4G can load linear 
executables (LE and LX) and EXPs (BW). The error code is for Tenberry Software’s use. 

1009 "program <filename> is not bound" 

This message does not occur in DOS/4G, only DOS/4GW Professional; the latter requires that the 
DOS extender be bound to the program file. The error signals an attempt to load 

1010 "can’t initialize loader <loader> [<error code>]" 
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D0S/4G could not initialize the named loader, probably because of a resource shortage. Try making 
more memory available. If that doesn’t work, please contact Tenberry Technical Support. The error 
code is for Tenberry Software’ use. 

1011 "VMM initialization error [<error code>]" 

DOS/4G could not initialize the Virtual Memory Manager, probably because of a resource shortage. 
Try making more memory available. If that doesn't work, please contact Tenberry Technical 
Support. The error code is for Tenberry Software’ use. 

1012 "<filename> is not a WATCOMprogram" 

This message does not occur in DOS/4G, only DOS/4GW and DOS/4GW Professional. Those 
extenders only support WATCOM 32-bit compilers. 

1013 "int 31h initialization error" 

DOS/4G was unable to initialize the code that handles Interrupt 31h, probably because of an internal 
error. Please call Tenberry Technical Support. 

1100 "assertion \"<statement>\" failed (<file>:<line>)" 

DOS/4G internal error. Please contact Tenberry Technical Support. 

1200 "invalid EXP executable format " 

DOS/4G tried to load an EXP, but couldn’t. The executable file is probably corrupted. 

1201 "program must be built -AUTO for DPMI" 

Under DPMI, DOS/4G can only load EXPs that have been linked with the GLU -AUTO or -DPMI 
switch. 

1202 "can’t allocate memory for GDT" 

There is not enough memory available for DOS/4G to build a Global Descriptor Table. Make more 
memory available. 

1203 "premature EOF" 

DOS/4G tried to load an EXP but couldn’t. The file is probably corrupted. 

1204 "not enough memory to load program" 

There is not enough memory available for DOS/4G to load your program. Make more memory 
available. 

1301 "invalid linear executable format" 

DOS/4G cannot recognize the program file as a LINEXE format. Make sure that you specified the 
correct file name. 

1304 "file I/O seek error" 
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D0S/4G was unable to seek to a file location that should exist. This usually indicates truncated 
program files or problems with the storage device from which your program loads. Run CHKDSK 
or a similar utility to begin determining possible causes. 

1305 "file I/O read error" 

DOS/4G was unable to read a file location that should contain program data. This usually indicates 
truncated program files or problems with the storage device from which your program loads. Run 
CHKDSK or a similar utility to begin determining possible causes. 

1307 "not enough memory" 

As it attempted to load your program, DOS/4G ran out of memory. Make more memory available, 
or enable VMM. 

1308 "can’t load requested program" 

1309 "can’t load requested program " 

1311 "can’t load requested program " 

1312 "can’t load requested program" 

DOS/4G cannot load your program for some reason. Contact Tenberry Technical Support. 

1313 "can’t resolve external references " 

DOS/4G was unable to resolve all references to DLLs for the requested program, or the program 
contained unsupported fixup types. Use EXEHDR or a similar LINEXE dump utility to see what 
references your program makes and what special fixup records might be present. 

1314 "not enough lockable memory" 

As it attempted to load your program, DOS/4G encountered a refusal to lock a virtual memory 
region. Some memory must be locked in order to handle demand-load page faults. Make more 
physical memory available. 

1315 "can’t load requested program" 

1316 "can’t load requested program" 

DOS/4G cannot load your program for some reason. Contact Tenberry Technical Support. 

1317 "program has no stack" 

DOS/4G reports this error when you try to run a program with no stack. Rebuild your program, 
building in a stack. 

2000 "deinitializing twice" 

DOS/4G internal error. Please contact Tenberry Technical Support. 

2001 "exception <exception_number> (<exception_description>) at <selector:offset>" 
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Your program has generated an exception. For information about interpreting this message, see the 
file COMMON.DOC. 

2002 "transfer stack overflow at <selector:offset>" 

Your program has overflowed the DOS/4G transfer stack. For information about interpreting this 
message, see the file COMMON.DOC. 

2300 " can’t find <DLL>.<ordinal> - referenced from <module>" 

DOS/4G could not find the ordinal listed in the specified DLL, or it could not find the DLL at all. 
Correct or remove the reference, and make sure that DOS/4G can find the DLL. 

DOS/4G looks for DLLs in the following directories: 

• The directory specified by the Libpath32 configuration option (which defaults to the directory 
of the main application file). 

• The directory or directories specified by the LIBPATH32 environment variable. 

• Directories specified in the PATFl. 

2301 "can’t find <DLL>.<name> - referenced from <module>” 

DOS/4G could not find the entry point named in the specified module. Correct or remove the 
reference, and make sure that DOS/4G can find the DLL. 

2302 "DLL modules not supported" 

This DOS/4GW Professional error message arises when an application references or tries to 
explicitly load a DLL. DOS/4GW Professional does not support DLLs. 

2303 "internal LINEXE object limit reached" 

DOS/4G currently handles a maximum of 128 LINEXE objects, including all .DLL and .EXE files. 
Most .EXE or .DLL files use only three or four objects. If possible, reduce the number of objects, or 
contact Tenberry Technical Support. 

2500 "can’t connect to extender kernel" 

DOS/4G internal error. Please contact Tenberry Technical Support. 

2503 "not enough disk space for swapping - <count> byes required" 

VMM was unable to create a swap file of the required size. Increase the amount of disk space 
available. 

2504 "can’t create swap file \<filename>\" " 

VMM was unable to create the swap file. This could be because the swap file is specified for a 
nonexistent drive or on a drive that is read-only. Set the SWAPNAME parameter to change the 
location of the swap file. 


D0S/4G Errors 83 




The D0S/4GW DOS Extender 


2505 "not enough memory for <table>" 

VMM was unable to get sufficient extended memory for internal tables. Make more memory 
available. If <table> is page buffer, make more DOS memory available. 

2506 "not enough physical memory (minmem)" 

There is less physical memory available than the amount specified by the MINMEM parameter. 
Make more memory available. 

2511 "swap out error [<error code>]" 

Unknown disk error. The error code is for Tenberry Software’ use. 

2512 "swap in error [<error code>]" 

Unknown disk error. The error code is for Tenberry Software’ use. 

2514 "can’t open trace file" 

VMM could not open the VMM.TRC file in the current directory for writing. If the directory 
already has a VMM.TRC file, delete it. If not, there may not be enough memory on the drive for the 
trace file, or DOS may not have any more file handles. 

2520 "can’t hook int 3lh" 

DOS/4G internal error. Please contact Tenberry Technical Support. 

2523 "page fault on non-present mapped page" 

Your program references memory that has been mapped to a nonexistent physical device, using 
DPMI function 508h. Make sure the device is present, or remove the reference. 

2524 "page fault on uncommitted page" 

Your program references memory reserved with a call to DPMI function 

504h, but never committed (using a DPMI 507h or 508h call). Commit the memory before you reference 
it. 

3301 "unhandledEMPTYFWD, GATE16, or unknown relocation" 

3302 "unhandled ALIAS 16 reference to unaliased object" 

3304 "unhandled or unknown relocation " 

If your program was built for another platform that supports the LINEXE format, it may contain a 
construct that DOS/4G does not currently support, such as a call gate. This message may also occur 
if your program has a problem mixing 16- and 32-bit code. A linker error is another likely cause. 
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14 D0S/4GW Commonly Asked Questions 


The following information has been provided by Tenberry Software, Inc. for their DOS/4GW and 
DOS/4GW Professional product. The content of this chapter has been edited by Open Watcom. In most 
cases, the information is applicable to both products. 

This chapter covers the following topics: 

• Access to technical support 

• Differences within the DOS/4G product line 

• Addressing 

• Interrupt and exception handling 

• Memory management 

• DOS, BIOS, and mouse services 

• Virtual memory 

• Debugging 

• Compatibility 


14.1 Access to Technical Support 

la. How to reach technical support. 

Here are the various ways you may contact Tenberry Software for technical support. 

WWW: http://www.tenberry.com/dos4g/ 

Email: 4gwhelp@tenberry.com 

Phone: 1.480.767.8868 

Fax: 1.480.767.8709 

Mail: Tenberry Software, Inc. 

PO Box 20050 

Fountain Hills, Arizona 

U.S.A 85269-0050 

PLEASE GIVE YOUR SERIAL NUMBER WHEN YOU CONTACT TENBERRY. 
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lb. When to contact Open Watcom, when to contact Tenberry. 

Since DOS/4GW Professional is intended to be completely compatible with DOS/4GW, you may wish 
to ascertain whether your program works properly under DOS/4GW before contacting Tenberry 
Software for technical support. (This is likely to be the second question we ask you, after your serial 
number.) 

If your program fails under both DOS/4GW and DOS/4GW Professional, and you suspect your own 
code or a problem compiling or linking, you may wish to contact Open Watcom first. Tenberry 
Software support personnel are not able to help you with most programming questions, or questions 
about using the Open Watcom tools. 

If your program only fails with DOS/4GW Professional, you have probably found a bug in DOS/4GW 
Professional, so please contact us right away. 

lc. Telephone support. 

Tenberry Software’s hours for telephone support are 9am-6pm EST. Please note that telephone support 
is free for the first 30 days only. A one-year contract for continuing telephone support on DOS/4GW 
Professional is US$500 per developer, including an update subscription for one year, to customers in the 
United States and Canada; for overseas customers, the price is $600. Site licenses may be negotiated. 

There is no time limit on free support by fax, mail, or electronic means. 

l d. References. 

The DOS/4GW documentation from Open Watcom is the primary reference for DOS/4GW Professional 
as well. Another useful reference is the DPMI specification. In the past, the DPMI specification could 
be obtained free of charge by contacting Intel Literature. We have been advised that the DPMI 
specification is no longer available in printed form. 

However, the DPMI 1.0 specification can be obtained at: 

http://www.delorie.com/djgpp/doc/dpmi/ 


Online HTML as well as a downloadable archive are provided. 


14.2 Differences Within the D0S/4G Product Line 


2a. DOS/4GW Professional versus DOS/4GW 

DOS/4GW Professional was designed to be a higher-performance version of DOS/4GW suitable for 
commercial applications. Here is a summary of the advantages of DOS/4GW Professional with respect 
to DOS/4GW: 

• Extender binds to the application program file 

• Extender startup time has been reduced 

• Support for Open Watcom floating-point emulator has been optimized 

• Virtual memory manager performance has been greatly improved 
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• Under VMM, programs are demand loaded 

• Virtual address space is 4 GB instead of 32 MB 

• Extender memory requirements have been reduced by more than 50K 

• Extender disk space requirements have been reduced by 40K 

• Can omit virtual memory manager to save 50K more disk space 

• Support for INT 3lh functions 301h-304h and 702h-703h 

DOS/4GW Professional is intended to be fully compatible with programs written for DOS/4GW 1.9 and 
up. The only functional difference is that the extender is bound to your program instead of residing in a 
separate file. Not only does this help reduce startup time, but it eliminates version-control problems 
when someone has both DOS/4GW and DOS/4GW Professional applications present on one machine. 

2b. DOS/4GW Professional versus DOS/4G. 

DOS/4GW Professional is not intended to provide any other new DOS extender functionality. Tenberry 
Software’s top-of-the-line 32-bit extender, DOS/4G, is not sold on a retail basis but is of special interest 
to developers who require more flexibility (such as OEMs). DOS/4G offers these additional features 
beyond DOS/4GW and DOS/4GW Professional: 

• Complete documentation 

• DLL support 

• TSR support 

• Support for INT 31h functions 301h-306h, 504h-50Ah, 702h-703h 

•AC language API that offers more control over interrupt handling and program loading, as well 
as making it easier to use the extender 

• An optional (more protected) nonzero-based flat memory model 

• Remappable error messages 

• More configuration options 

• The D32 debugger, GLU linker, and other tools 

• Support for other compilers besides Open Watcom 

• A higher level of technical support 

• Custom work is available (e.g., support for additional executable formats, operating system API 
emulations, mixed 16-bit and 32-bit code) 

Please contact Tenberry Software if you have questions about other products (present or future) in the 
DOS/4G line. 
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2c. DPMI functions supported by DOS/4GW. 

Note that when a DOS/4GW application runs under a DPMI host, such as Windows 3.1 in enhanced 
mode, an OS/2 virtual DOS machine, 386Max (with DEBUG=DPMIXCOPY), or QDPMI (with 
EXTCHKOFF), the DPMI host provides the DPMI services, not DOS/4GW. The DPMI host also 
provides virtual memory, if any. Performance (speed and memory use) under different DPMI hosts 
varies greatly due to the quality of the DPMI implementation. 

These are the services provided by DOS/4GW and DOS/4GW Professional in the absence of a DPMI 
host. 

0000 Allocate LDT Descriptors 

0001 Free LDT Descriptor 

0002 Map Real-Mode Segment to Descriptor 

0003 Get Selector Increment Value 

0006 Get Segment Base Address 

0007 Set Segment Base Address 

0008 Set Segment Limit 

0009 Set Descriptor Access Rights 

000A Create Alias Descriptor 

000B Get Descriptor 

000C Set Descriptor 

000D Allocate Specific LDT Descriptor 

0100 Allocate DOS Memory Block 

0101 Free DOS Memory Block 

0102 Resize DOS Memory Block 

0200 Get Real-Mode Interrupt Vector 

0201 Set Real-Mode Interrupt Vector 

0202 Get Processor Exception Handler 

0203 Set Processor Exception Handler 

0204 Get Protected-Mode Interrupt Vector 

0205 Set Protected-Mode Interrupt Vector 

0300 Simulate Real-Mode Interrupt 

0301 Call Real-Mode Procedure with Far Return Frame (DOS/4GW Professional only) 

0302 Call Real-Mode Procedure with IRET Frame (DOS/4GW Professional only) 

0303 Allocate Real-Mode Callback Address (DOS/4GW Professional only) 

0304 Free Real-Mode Callback Address (DOS/4GW Professional only) 

0400 Get DPMI Version 

0500 Get Free Memory Information 

0501 Allocate Memory Block 

0502 Free Memory Block 

0503 Resize Memory Block 

0600 Lock Linear Region 

0601 Unlock Linear Region 

0604 Get Page Size (VM only) 

0702 Mark Page as Demand Paging Candidate (DOS/4GW Professional only) 
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0703 Discard Page Contents (DOS/4GW Professional only) 

0800 Physical Address Mapping 

0801 Free Physical Address Mapping 

0900 Get and Disable Virtual Interrupt State 

0901 Get and Enable Virtual Interrupt State 

0902 Get Virtual Interrupt State 

OA 00 Get Tenberry Software API Entry Point 

0E00 Get Coprocessor Status 

0E01 Set Coprocessor Emulation 

14.3 Addressing 

3a. Converting between pointers and linear addresses. 

Because DOS/4GW uses a zero-based flat memory model, converting between pointers and linear 
addresses is trivial. A pointer value is always relative to the current segment (the value in CS for a code 
pointer, or in DS or SS for a data pointer). The segment bases for the default DS, SS, and CS are all 
zero. Hence a near pointer is exactly the same thing as a linear address: a null pointer points to linear 
address 0, and a pointer with value 0x10000 points to linear address 0x10000. 

3b. Converting between code and data pointers. 

Because DS and CS have the same base address, they are natural aliases for each other. To create a data 
alias for a code pointer, merely create a data pointer and set it equal to the code pointer. It’s not 
necessary for you to create your own alias descriptor. Similarly, to create a code alias for a data pointer, 
merely create a code pointer and set it equal to the data pointer. 

3c. Converting between pointers and low memory addresses. 

Linear addresses under 1 MB map directly to physical memory. Hence the real-mode interrupt vector 
table is at address 0, the BIOS data segment is at address 0x400, the monochrome video memory is at 
address OxBOOOO, and the color video memory is at address 0xB8000. To read and write any of these, 
you can just use a pointer set to the proper address. You don't need to create a far pointer, using some 
magic segment value. 

3d. Converting between linear and physical addresses. 

Linear addresses at or above 1 MB do not map directly to physical memory, so you can not in general 
read or write extended memory directly, nor can you tell how a particular block of extended memory 
has been used. 

DOS/4GW supports the DPMI call INT 31h/800h, which maps physical addresses to linear addresses. 

In other words, if you have a peripheral device in your machine that has memory at a physical address 
of 256 MB, you can issue this call to create a linear address that points to that physical memory. The 
linear address is the same thing as a near pointer to the memory and can be manipulated as such. 

There is no way in a DPMI environment to determine the physical address corresponding to a given 
linear address. This is part of the design of DPMI. You must design your application accordingly. 
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3e. Null pointer checking. 

D0S/4GW will trap references to the first sixteen bytes of physical memory if you set the environment 
variable DOS4G=NULLP. This is currently the only null-pointer check facility provided by 
DOS/4GW. 

As of release 1.95, DOS/4GW traps both reads and writes. Prior to this, it only trapped writes. 

You may experience problems if you set DOS4G=NULLP and use some versions of the Open Watcom 
Debugger with a 1.95 or later extender. These problems have been corrected in later versions of the 
Open Watcom Debugger. 

14.4 Interrupt and Exception Handling 

4a. Handling asynchronous interrupts. 

Under DOS/4GW, there is a convenient way to handle asynchronous interrupts and an efficient way to 
handle them. 

Because your CPU may be in either protected mode (when 32-bit code is executing) or real mode (a 
DOS or BIOS call) when a hardware interrupt comes in, you have to be prepared to handle interrupts in 
either mode. Otherwise, you may miss interrupts. 

You can handle both real-mode and protected-mode interrupts with a single handler, if 1) the interrupt 
is in the auto-passup range, 8 to 2Eh; and 2) you install a handler with INT 21h/25h or _dos_setvect(); 

3) you do not install a handler for the same interrupt using any other mechanism. DOS/4GW will route 
both protected-mode interrupts and real-mode interrupts to your protected-mode handler. This is the 
convenient way. 

The efficient way is to install separate real-mode and protected-mode handlers for your interrupt, so 
your CPU won't need to do unnecessary mode switches. Writing a real-mode handler is tricky; all you 
can reasonably expect to do is save data in a buffer and IRET. Your protected-mode code can 
periodically check the buffer and process any queued data. (Remember, protected-mode code can 
access data and execute code in low memory, but real-mode code can’t access data or execute code in 
extended memory.) 

For performance, it doesn’t matter how you install the real-mode handler, but we recommend the DPMI 
function INT 31h/201h for portability. 

It does matter how you install the protected-mode handler. You can’t install it directly into the IDT, 
because a DPMI provider must distinguish between interrupts and exceptions and maintain separate 
handler chains. Installing with INT 31h/205h is the recommended way to install your protected-mode 
handler for both performance and portability. 

If you install a protected-mode handler with INT 21h/25h, both interrupts and exceptions will be 
funneled to your handler, to mimic DOS. Since DPMI exception handlers and interrupt handlers are 
called with different stack frames, DOS/4GW executes a layer of code to cover these differences up; the 
same layer is used to support the DOS/4G API (not part of DOS/4GW). This layer is the reason that 
hooking with INT 21h/25h is less efficient than hooking with INT 31h/205h. 
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4b. Handling asynchronous interrupts in the second IRQ range. 

Because the second IRQ range (normally INTs 70h-77h) is outside the DOS/4GW auto-passup range 
(8-2Eh, excluding 2 lh) you may not handle these interrupts with a single handler, as described above 
(the "convenient" method). You must install separate real-mode and protected-mode handlers (the 
"efficient" method). 

DOS/4G does allow you to specify additional passup interrupts, however. 

4c. Asynchronous interrupt handlers and DPMI. 

The DPMI specification requires that all code and data referenced by a hardware interrupt handler 
MUST be locked at interrupt time. A DPMI virtual memory manager can use the DOS file system to 
swap pages of memory to and from the disk; because DOS is not reentrant, a DPMI host is not required 
to be able to handle page faults during asynchronous interrupts. Use INT 31h/600h (Lock Linear 
Region) to lock an address range in memory. 

If you fail to lock all of your code and data, your program may run under DOS/4GW, but fail under the 
DOS/4GW Virtual Memory Manager or under another DPMI host such as Windows or OS/2. 

You should also lock the code and data of a mouse callback function. 

4d. Open Watcom signal() function and Ctrl-Break. 

In earlier versions of the Open Watcom C/C++ library, there was a bug that caused signal(SIGBREAK) 
not to work. Calling signal(SIGBREAK) did not actually install an interrupt handler for Ctrl-Break 
(INT lBh), so Ctrl-Break would terminate the application rather than invoking the signal handler. 

With these earlier versions of the library, you could work around this problem by hooking INT lBh 
directly. With release 10.0, this problem has been fixed. 

4e. More tips on writing hardware interrupt handlers. 

• It’s more like handling interrupts in real mode than not. 

The same problems arise when writing hardware interrupt handlers for protected mode as arise for real 
mode. We assume you know how to write real-mode handlers; if our suggestions don't seem clear, 
you might want to brush up on real-mode interrupt programming. 

• Minimize the amount of time spent in your interrupt handlers. 

When your interrupt handlers are called, interrupts are disabled. This means that no other system tasks 
can be performed until you enable interrupts (an STI instruction) or until your handler returns. In 
general, it’s a good idea to handle interrupts as quickly as possible. 

• Minimize the amount of time spent in the DOS extender by installing separate real-mode and 
protected-mode handlers. 

If you use a passup interrupt handler, so that interrupts received in real mode are resignalled in 
protected mode by the extender, your application has to switch from real mode to protected mode to 
real mode once per interrupt. Mode switching is a time-consuming process, and interrupts are disabled 
during a mode switch. Therefore, if you’re concerned about performance, you should install separate 
handlers for real-mode and protected-mode interrupts, eliminating the mode switch. 
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• If you can’t just set a flag and return, enable interrupts (STI). 

Handlers that do more than just set a flag or store data in a buffer should re-enable interrupts as soon as 
it’s safe to do so. In other words, save your registers on the stack, establish your addressing 
conventions, switch stacks if you’re going to — and then enable interrupts (STI), to give priority to 
other hardware interrupts. 

• If you enable interrupts (STI), you should disable interrupts (CLI). 

Because some DPMI hosts virtualize the interrupt flag, if you do an STI in your handler, you should be 
sure to do a CLI before you return. (CLI, then switch back to the original stack if you switched away, 
then restore registers, then IRET.) If you don't do this, the IRET will not necessarily restore the 
previous interrupt flag state, and your program may crash. This is a difference from real-mode 
programming, and it tends to show up as a problem when you try running your program in a Windows 
or OS/2 DOS box for the first time (but not before). 

• Add a reentrancy check. 

If your handler doesn’t complete its work by the time the next interrupt is signalled, then interrupts can 
quickly nest to the point of overflowing the transfer stack. This is a design flaw in your program, not 
in the DOS extender; a real-mode DOS program can have exactly the same behavior. If you can 
conceive of a situation where your interrupt handler can be called again before the first instance 
returns, you need to code in a reentrancy check of some sort (before you switch stacks and enable 
interrupts (STI), obviously). 

Remember that interrupts can take different amounts of time to execute on different machines; the CPU 
manufacturer, CPU speed, speed of memory accesses, and CMOS settings (e.g. "system BIOS 
shadowing") can all affect performance in subtle ways. We recommend you program defensively and 
always check for unexpected reentry, to avoid transfer stack overflows. 

• Switch to your own stack. 

Interrupt handlers are called on a stack that typically has only a small amount of stack available (512 
bytes or less). If you need to use more stack than this, you have to switch to your own stack on entry 
into the handler, and switch back before returning. 

If you want to use C run-time library functions, which are compiled for flat memory model (SS == DS, 
and the base of CS == the base of DS), you need to switch back to a stack in the flat data segment first. 

Note that switching stacks by itself won’t prevent transfer stack overflows of the kind described above. 

14.5 Memory Management 

5a. Using the realloc() function. 

In versions of Open Watcom C/C++ prior to 9.5b, there was a bug in the library implementation of 
realloc() under DOS/4GW and DOS/4GW Professional. This bug was corrected by Open Watcom in 
the 9.5b release. 
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5b. Using all of physical memory. 

D0S/4GW Professional is currently limited to 64 MB of physical memory. We do not expect to be able 
to fix this problem for at least six months. If you need more than 64 MB of memory, you must use 
virtual memory. 

14.6 DOS, BIOS, and Mouse Services 

6a. Speeding up file I/O. 

The best way to speed up DOS file I/O in DOS/4GW is to write large blocks (up to 65535 bytes, or the 
largest number that will fit in a 16-bit int) at a time from a buffer in low memory. In this case, 
DOS/4GW has to copy the least amount of data and make the fewest number of DOS calls in order to 
process the I/O request. 

Low memory is allocated through INT 31h/0100h, Allocate DOS Memory Block. You can convert the 
real-mode segment address returned by INT 31h/0100h to a pointer (suitable for passing to setvbuf()) by 
shifting it left four bits. 

6b. Spawning. 

It is possible to spawn one DOS/4GW application from another. However, two copies of the DOS 
extender will be loaded into memory. DOS/4G supports loading of multiple programs atop a single 
extender, as well as DLLs. 

6c. Mouse callbacks. 

DOS/4GW Professional now supports the INT 3lh interface for managing real-mode callbacks. 
However, you don’t need to bother with them for their single most important application: mouse 
callback functions. Just register your protected-mode mouse callback function as you would in real 
mode, by issuing INT 33h/OCh with the event mask in CX and the function address in ES:EDX, and 
your function will work as expected. 

Because a mouse callback function is called asynchronously, the same locking requirement exists for a 
mouse callback function as for a hardware interrupt handler. See (4c) above. 

6d. VESA support. 

While DOS/4GW automatically handles most INT lOh functions so that you can you can issue them 
from protected mode, it does not translate the INT lOh VESA extensions. The workaround is to use 
INT 31h/300h (Simulate Real-Mode Interrupt). 


14.7 Virtual Memory 

7a. Testing for the presence of VMM. 

INT 31h/400h returns a value (BX, bit 2) that tells if virtual memory is available. Under a DPMI host 
such as Windows 3.1, this will be the host’s virtual memory manager, not DOS/4GW's. 
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You can test for the presence of a DOS/4G-family DOS extender with INT 31h/0A00h, with a pointer 
to the null-terminated string "RATIONAL DOS/4G" in DS:ESI. If the function returns with carry clear, 
a DOS/4G-family extender is running. 

7b. Reserving memory for a spawned application. 

If you spawn one DOS/4GW application from another, you should set the DELETES WAP 
configuration option (i.e., SET DOS4GVM=deleteswap) so that the two applications don't try to use the 
same swap file. You should also set the MAXMEM option low enough so that the parent application 
doesn't take all available physical memory; memory that’s been reserved by the parent application is 
not available to the child application. 

7c. Instability under VMM. 

A program that hooks hardware interrupts, and works fine without VMM but crashes sporadically with 
it, probably needs to lock the code and data for its hardware interrupt handlers down in memory. 
DOS/4GW does not support page faults during hardware interrupts, because DOS services may not be 
available at that time. See (4c) and (6c) above. 

Memory can be locked down with INT 31h/600h (Lock Linear Region). 

7d. Running out of memory with a huge virtual address space. 

Because DOS/4GW has to create page tables to describe your virtual address space, we recommend that 
you set your VIRTUALSIZE parameter just large enough to accommodate your program. If you set 
your VIRTUALSIZE to 4 GB, the physical memory occupied by the page tables will be 4 MB, and that 
memory will not be available to DOS/4GW. 

7e. Reducing the size of the swap file. 

DOS/4GW will normally create a swap file equal to your VIRTUALSIZE setting, for efficiency. 
However, if you set the SWAPMIN parameter to a size (in KB), DOS/4GW will start with a swap file 
of that size, and will grow the swap file when it has to. The SWAPINC value (default 64 KB) controls 
the incremental size by which the swap file will grow. 

7f Deleting the swap file. 

The DELETESWAP option has two effects: telling DOS/4GW to delete the swap file when it exits, and 
causing DOS/4GW to provide a unique swap file name if an explicit SWAPNAME setting was not 
given. 

DELETESWAP is required if one DOS/4GW application is to spawn another; see (7b) above. 

7g. Improving demand-load performance of large static arrays. 

DOS/4GW demand-loading feature normally cuts the load time of a large program drastically. 

However, if your program has large amounts of global, zero-initialized data (storage class BSS), the 
Open Watcom startup code will explicitly zero it (version 9.5a or earlier). Because the zeroing 
operation touches every page of the data, the benefits of demand-loading are lost. 

Demand loading can be made fast again by taking advantage of the fact that DOS/4GW automatically 
zeroes pages of BSS data as they are loaded. You can make this change yourself by inserting a few 
lines into the startup routine, assembling it (MASM 6.0 will work), and listing the modified object 
module first when you link your program. 
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Here are the changes for \watcom\src:\startup\38 6\cstart3r . asm (startup module from 
the C/C++ 9.5 compiler, library using register calling conventions). You can modify the workaround 
easily for other Open Watcom compilers: 


; cstart3r.asm, circa line 332 
; end of _ BSS segment (start of STACK) 


mov 

ecx,offset 

DGROUP 

_ end 



; 

start of _ BSS segment 

mov 

edi,offset 

DGROUP 

_ edata 

— 


-; 

RSI OPTIMIZATION 

mov 

eax, edi 

; 

minimize _ BSS initialization loop 

or 

eax, OFFFh 

; 

compute address of first page after 

inc 

eax 

; 

start of _ BSS 

cmp 

eax, ecx 

; 

if _ BSS extends onto that page. 

jae 

allzero 

; 

then we can rely on the loader 

mov 

ecx, eax 


zeroing the remaining pages 




END RSI OPTIMIZATION 

sub 

ecx,edi 

; 

calc # of bytes in _ BSS segment 

mov 

dl, cl 

; 

save bottom 2 bits of count in edx 

shr 

ecx, 2 

; 

calc # of dwords 

sub 

eax,eax 

; 

zero the _ BSS segment 

rep 

stosd 

; 


mov 

cl, dl 

; 

get bottom 2 bits of count 

and 

cl, 3 

; 


rep 

stosb 

; 



Note that the 9.5b and later versions of the Open Watcom C library already contain this enhancement. 

7h. How should I configure VM for best performance? 

Here are some recommendations for setting up the DOS/4GW virtual memory manager. 

VIRTUALSIZE Set to no more than twice the total amount of memory (virtual and otherwise) your 

program requires. If your program has 16 MB of code and data, set to 32 MB. (There 
is only a small penalty for setting this value larger than you will need, but your program 
won't run if you set it too low.) See (7d) above. 

MINMEM Set to the minimum hardware requirement for running your application. (If you require 
a 2 MB machine, set to 2048). 

MAXMEM Set to the maximum amount of memory you want your application to use. If you don't 
spawn any other applications, set this large (e.g., 32000) to make sure you can use all 
available physical memory. If you do spawn, see (7b) above. 

SWAPMIN Don’t use this if you want the best possible VM performance. The trade-off is that 
DOS/4GW will create a swap file as big as your VIRTU ALSIZE. 

SWAPINC Don't use this if you want the best possible VM performance. 

DELETESWAP DOS/4GW’s VM will start up slightly slower if it has to create the swap file afresh 
each time. However, unless your swap file is very large, DELETESWAP is a 
reasonable choice; it may be required if you spawn another DOS/4GW program at the 
same time. See (7b) above. 
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14.8 Debugging 

8a. Attempting to debug a bound application. 

You can’t debug a bound application. The 4GWBIND utility (included with DOS/4GW Professional) 
will allow you to take apart a bound application so that you can debug it: 

4GWBIND -U <boundapp.exe> <yourapp.exe> 

8b. Debugging with an old version of the Open Watcom debugger. 

DOS/4GW supports versions 8.5 and up of the Open Watcom C, C++ and FORTRAN compilers. 
However, in order to debug your unbound application with a Open Watcom debugger, you must have 
version 9.5a or later of the debugger. 

If you have an older version of the debugger, we strongly recommend that you contact Open Watcom to 
upgrade your compiler and tools. The only way to debug a DOS/4GW Professional application with an 
old version of the debugger is to rename 4GWPRO.EXE to DOS4GW.EXE and make sure that it’s 
either in the current directory or the first DOS4GW.EXE on the DOS PATH. 

Tenberry will not provide technical support for this configuration; it’s up to you to keep track of which 
DOS extender is which. 

8c. Meaning of "unexpected interrupt" message/error 2001. 

In version 1.95 of DOS/4GW, we revised the "unexpected interrupt" message to make it easier to 
understand. 

For example, the message: 

Unexpected interrupt OE (code 0) at 168:10421034 


is now printed: 

error (2001) : exception OEh (page fault) at 168:10421034 


followed by a register dump, as before. 


This message indicates that the processor detected some form of programming error and signaled an 
exception, which DOS/4GW trapped and reported. Exceptions which can be trapped include: 

OOh divide by zero 

Olh debug exception OR null pointer used 

03h breakpoint 

04h overflow 

05h bounds 

06h invalid opcode 

07h device not available 

08h double fault 

09h overrun 

OAh invalid TSS 

OBh segment not present 

OCh stack fault 

ODh general protection fault 

OEh page fault 


96 


Debugging 




D0S/4GW Commonly Asked Questions 


When you receive this message, this is the recommended course of action: 

1. Record all of the information from the register dump. 

2. Determine the circumstances under which your program fails. 

3. Consult your debugger manual, or an Intel 386, 486 or Pentium Programmer’s Reference 
Manual, to determine the circumstances under which the processor will generate the reported 
exception. 

4. Get the program to fail under your debugger, which should stop the program as soon as the 
exception occurs. 

5. Determine from the exception context why the processor generated an exception in this 
particular instance. 

8d. Meaning of "transfer stack overflow" message/error 2002. 

In version 1.95 of DOS/4GW, we added more information to the "transfer stack overflow" message. 

The message (which is now followed by a register dump) is printed: 

error (2002): transfer stack overflow 

on interrupt <number> at <address> 


This message means DOS/4GW detected an overflow on its interrupt handling stack. It usually 
indicates either a recursive fault, or a hardware interrupt handler that can’t keep up with the rate at 
which interrupts are occurring. The best way to understand the problem is to use the VERBOSE option 
in DOS/4GW to dump the interrupt history on the transfer stack; see (8e) below. 

He. Making the most of a DOS/4GW register dump. 

If you can’t understand your problem by running it under a debugger, the DOS/4GW register dump is 
your best debugging tool. To maximize the information available for postmortem debugging, set the 
environment variable DOS4G to VERBOSE, then reproduce the crash and record the output. 


Here’s a typical register dump with VERBOSE turned on, with annotations. 


1 

2 
3 


4 


5 

6 
7 


DOS/4GW error (2001): exception 


OEh (page fault) 

at 170:0042C1B2 


TSF32 : prev_ tsf32 
SS 178 DS 

EAX 1F000000 EBX 
ESI E EDI 


67D8 

178 ES 
0 ECX 
0 EBP 


CS : IP 170 : 0042C1B2 ID 0E COD 


178 FS 
43201C EDX 
431410 ESP 
0 FLG 


0 GS 
E 

4313FC 

10246 


20 


cs= 

170, 

USE32, 

page 

granular. 

limit 

FFFFFFFF, 

base 

0, 

acc 

CF9B 

ss= 

178, 

USE32, 

page 

granular. 

limit 

FFFFFFFF, 

base 

0, 

acc 

CF93 

DS= 

178, 

USE32, 

page 

granular. 

limit 

FFFFFFFF, 

base 

0, 

acc 

CF93 

ES= 

178, 

USE32, 

page 

granular. 

limit 

FFFFFFFF, 

base 

0, 

acc 

CF93 

FS= 

0, 

USE16, 

byte 

granular. 

limit 

0 f 

base 

15, 

acc 

0 

GS= 

20, 

USE16, 

byte 

granular. 

limit 

FFFF, 

base 

6AA0, 

acc 

93 


CR0: PG:1 ET:1 TS:0 EM:0 MP:0 PE:1 CR2: 1F000000 CR3: 9067 
Crash address (unrelocated) = 1:000001B2 

Opcode stream: 8A 18 31 D2 88 DA EB 0E 50 68 39 00 43 00 E8 ID 
Stack: 


8 0178:004313FC 000E 0000 0000 0000 C2D5 0042 C057 0042 0170 0000 0000 0000 

0178:00431414 0450 0043 0452 0043 0000 0000 1430 0043 CBEF 0042 011C 0000 

0178:0043142c C568 0042 0000 0000 0000 0000 0000 0000 F248 0042 F5F8 0042 

0178:00431444 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 

0178:0043145c 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 

0178:00431474 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 

9 Last 4 ints: 21 @ 170:42CF48/21 @ 170:42CF48/21 @ 170:42CF48/E @ 170:42C1B2/ 
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1. The error message includes a synopsis of the problem. In this case, the processor signaled a 
page fault exception while executing at address 170:0042C1B2. 

2. The prev_tsf32 field is not usually of interest. 

3. These are the register values at the time of the exception. The interrupt number and error 
code (pushed on the stack by the processor for certain exceptions) are also printed. 

4. The descriptors referenced by each segment register are described for your convenience. 
USE32 segments in general belong to your program; USE16 segments generally belong to 
the DOS extender. Here, CS points to your program’s code segment, and SS, DS, and ES 
point to your data segment. FS is NULL and GS points to a DOS extender segment. 

5. The control register information is not of any general interest, except on a page fault, when 
CR2 contains the address value that caused the fault. Since EAX in this case contains the 
same value, an attempt to dereference EAX could have caused this particular fault. 

6. If the crash address (unrelocated) appears, it tells you where the crash occurred relative to 
your program’s link map. You can therefore tell where a crash occurred even if you can’t 
reproduce the crash in a debugger. 

7. The opcode stream, if it appears, shows the next 16 bytes from the code segment at the point 
of the exception. If you disassemble these instructions, you can tell what instructions caused 
the crash, even without using a debugger. In this case, 8A 18 is the instruction mov 

bl, [eax] . 

8. 72 words from the top of the stack, at the point of the exception, may be listed next. You 
may be able to recognize function calls or data from your program on the stack. 

9. The four interrupts least to most recently handled by DOS/4GW in protected mode are listed 
next. In this example, the last interrupt issued before the page fault occurred was an INT 21h 
(DOS call) at address 170:42CF48. Sometimes, this information provides helpful context. 


Here’s an abridged register dump from a stack overflow. 


1 

2 


3 


4 

5 


DOS/4GW error (2002) 


transfer stack overflow 

on interrupt 70h at 170:0042C002 


TSF32: prev_ tsf32 48C8 
SS C8 DS 170 

EAX AAAAAAAA EBX BBBBBBBB 
ESI 51515151 EDI D1D1D1D1 
CS:IP 170:0042C002 ID 70 

Previous TSF: 

TSF32 : prev_ tsf32 498C 
SS C8 DS 170 

EAX AAAAAAAA EBX BBBBBBBB 
ESI 51515151 EDI D1D1D1D1 
CS:IP 170:0042C002 ID 70 

Previous TSF: 

TSF32: prev_ tsf32 67E4 
SS 178 DS 170 

EAX AAAAAAAA EBX BBBBBBBB 
ESI 51515151 EDI D1D1D1D1 
CS:IP 170:0042C039 ID 70 
Opcode stream: CF 66 B8 62 
Last 4 ints: 70 @ 170:42C002/70 @ 170:42C002/70 @ 170:42C002/70 @ 170:42C002/ 


ES 

28 

FS 

0 

GS 

20 

ECX 

CCCCCCCC 

EDX 

DDDDDDDD 



EBP 

B1B1B1B1 

ESP 

4884 



COD 

0 

FLG 

2 



ES 

28 

FS 

0 

GS 

20 

ECX 

CCCCCCCC 

EDX 

DDDDDDDD 



EBP 

B1B1B1B1 

ESP 

4960 



COD 

0 

FLG 

2 



ES 

28 

FS 

0 

GS 

20 

ECX 

CCCCCCCC 

EDX 

DDDDDDDD 



EBP 

B1B1B1B1 

ESP 

42FFE0 



COD 

0 

FLG 

202 



: 25 

66 8C CB 

66 : 

8E DB BA 00 CO 

42 00 


1. We overflowed the transfer stack while trying to process an interrupt 70h at 170:0042C002. 
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2. The entire interrupt history from the transfer stack is printed next. The prev_tsf32 numbers 
increase as we progress from most recent to least recent interrupt. All of these interrupts are 
still pending, which is why we ran out of stack space. 

3. Before we overflowed the stack, we got the same interrupt at the same address. For a 
recursive interrupt situation, this is typical. 

4. The oldest frame on the transfer stack shows the recursion was touched off at a slightly 
different address. Looking at this address may help you understand the recursion. 

5. The opcode stream and last four interrupt information comes from the newest transfer stack 
frame, not the oldest. 


14.9 Compatibility 

9a. Running DOS/4GW applications from inside Lotus 1-2-3. 

In order to run DOS/4GW applications while "shelled out" from Lotus 1-2-3, you must use the 
PR1VATXM program included with your Open Watcom compiler. Otherwise, 1-2-3 will take all of the 
memory on your machine and prevent DOS/4GW from using it. 

Before starting 1-2-3, you must set the DOS16M environment variable to limit Lotus’ memory use (see 
your Open Watcom manual). After shelling out, you must run PRIVATXM, then clear the DOS16M 
environment variable before running your application. 

9b. EMM386.EXE provided with DOS 6.0. 

We know of at least three serious bugs in the EMM386.EXE distributed with MS-DOS 6.0, one 
involving mis-counting the amount of available memory, one involving mapping too little of the High 
Memory Area (HMA) into its page tables, and one involving allocation of EMS memory. Version 1.95 
of DOS/4GW contains workarounds for some of these problems. 

If you are having problems with DOS/4GW and you are using an EMM386.EXE dated 3-10-93 at 
6:00:00, or later, you may wish to try the following workarounds, in sequence, until the problem goes 
away. 


• Configure EMM386 with both the NOEMS and NOVCPI options. 

• Convert the DEVICEHIGH statements in your CONFIG.SYS to DEVICE statements, and 
remove the LH (Load High) commands from your AUTOEXEC.BAT. 

• Run in a Windows DOS box. 

• Replace EMM386 with another memory manager, such as QEMM-386, 386Max, or an older 
version of EMM386. 

• Run with HIMEM.SYS alone. 

You may also wish to contact Microsoft Corporation to inquire about the availability of a fix. 
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9c. Spawning under OS/2 2.1. 

We know of a bug in OS/2 2.1 that prevents one DOS/4GW application from spawning another over 
and over again. The actual number of repeated spawns that are possible under OS/2 varies from 
machine to machine, but is generally about 30. 

This bug also affects programs running under other DOS extenders, and we have not yet found a 
workaround, other than linking your two programs together as a single program. 

9d. "DPMI host error: cannot lock stack". 

This error message almost always indicates insufficient memory, rather than a real incompatibility. If 
you see it under an OS/2 DOS box, you probably need to edit your DOS Session settings and make 
DPMI_MEMORY_LIMIT larger. 

9e. Bug in Novell TCPIP driver. 

Some versions of a program from Novell called TCPIP.EXE, a real-mode program, will cause the high 
words of EAX and EDX to be altered during a hardware interrupt. This bug breaks protected-mode 
software (and other real-mode software that uses the 80386 registers). Novell has released a newer 
version of TCPIP that fixes the problem; contact Novell to obtain the fix. 

9f. Bugs in Windows NT. 

The initial release of Windows NT includes a DPMI host, DOSX.EXE, with several serious bugs, some 
of which apparently cannot be worked around. We cannot warranty operation of DOS/4GW under 
Windows NT at this time, but we are continuing to exercise our best efforts to work around these 
problems. 


You may wish to contact Microsoft Corporation to inquire about the availability of a new version of 
DOSX.EXE. 
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15 Creating 16-bit Windows 3.x Applications 


This chapter describes how to compile and link 16-bit Windows 3.x applications simply and quickly. In 
this chapter, we look at applications written to exploit the Windows 3.x Application Programming Interface 
(API). 


We will illustrate the steps to creating 16-bit Windows 3.x applications by taking a small sample 
application and showing you how to compile, link, run and debug it. 

15.1 The Sample GUI Application 

To demonstrate the creation of 16-bit Windows 3.x applications, we introduce a simple sample program. 
For our example, we are going to use the "sieve" program. 

*$include winapi.fi 
*$noreference 

INTEGER*2 FUNCTION FWINMAIN( hlnstance, hPrevInstance, 

& IpszCmdLine, nCmdShow ) 

*$reference 

IMPLICIT NONE 

INTEGER*2 hlnstance, hPrevInstance, nCmdShow 
INTEGERS IpszCmdLine 
include 'windows.fi' 


* This program computes the prime numbers between 1 and 10,000 

* using the Sieve of Eratosthenes algorithm. 


INTEGER UPBOUND 
PARAMETER (UPBOUND=10000) 

INTEGER I, K, PRIMES 
LOGICAL*1 NUMBERS(2:UPBOUND) 

CHARACTER*11 FORM 
CHARACTER*60 BUFFER 
PARAMETER (FORM='(A,15,A,15)') 

DO I = 2, UPBOUND 

NUMBERS(I) = .TRUE. 

ENDDO 

PRIMES = 0 

DO I = 2, UPBOUND 

IF( NUMBERS(I) )THEN 

PRIMES = PRIMES + 1 
DO K = I + I, UPBOUND, I 
NUMBERS(K) = .FALSE. 

ENDDO 
END IF 
ENDDO 

WRITE(BUFFER, FORM) 'The Number of Primes between 1 and ', 
& UPBOUND, ' are: ', PRIMES 

CALL MessageBox( 0, BUFFER, 

& 'Sieve of Eratosthenes'c, 

& MB_ OK .OR. MB_ TASKMODAL ) 

END 


The goal of this program is to count the prime numbers between 1 and 10,000. It uses the famous Sieve of 
Eratosthenes algorithm to accomplish this task. We will take you through the steps necessary to produce 
this result. 
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15.2 Building and Running the GUI Application 

To compile and link our example program which is stored in the file sieve . for, enter the following 
command: 

C>wfl -l=windows -win sieve.for 
The typical messages that appear on the screen are shown in the following illustration. 

C>wfl -l=windows -win sieve.for 

Open Watcom F77/16 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
wfc sieve.for -win 

Open Watcom FORTRAN 77/16 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 4305 statements, 356 bytes, 1524 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows 16-bit executable 


If you examine the current directory, you will find that two files have been created. These are 

sieve . ob j (the result of compiling sieve . for) and sieve . exe (the result of linking sieve . ob j 

with the appropriate Open Watcom FORTRAN 77 libraries). 

The resultant 16-bit Windows 3.x application SIEVE . EXE can now be run under Windows 3.x. 

15.3 Debugging the GUI Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "sieve" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WFL command, this is fairly straightforward. WFL recognizes the Open Watcom F77 
compiler "debug" options and will create the appropriate debug directives for the Open Watcom Linker. 

For example, to compile and link the "sieve" program with debugging information, the following command 
may be issued. 

C>wfl -l=windows -win -d2 sieve.for 
The typical messages that appear on the screen are shown in the following illustration. 
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C>wfl -l=windows -win -d2 sieve.for 

Open Watcom F77/16 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
wfc sieve.for -win -d2 

Open Watcom FORTRAN 77/16 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 4305 statements, 467 bytes, 1524 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows 16-bit executable 


The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom F77 compiler. WFL will make sure that this debugging information is included in the executable 
file that is produced by the linker. 

The "bytes" value is larger than in the previous example since selection of the "d2" option results in fewer 
code optimizations by default. You can request more optimization by specifying the appropriate options. 
However, you do so at the risk of making it more difficult for yourself to determine the relationship 
between the object code and the original source language code. 

To request the Open Watcom Debugger to assist in debugging the application, select the Open Watcom 
Debugger icon. It would be too ambitious to describe the debugger in this introductory chapter so we refer 
you to the book entitled Open Watcom Debugger User’s Guide. 

There are more extensive examples of Windows applications written in FORTRAN 77 in the 
\WATC0M\SAMPLES\FORTRAN\WIN directory. The example programs are ELLIPSE . FOR and 
FWCOPY.FOR. 
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16 Porting Non-GUI Applications to 16-bit 
Windows 3.x 


Generally, an application that is to run in a windowed environment must be written in such a way as to 
exploit the Windows Application Programming Interface (API). To take an existing character-based (i.e., 
non-graphical) application that ran under a system such as DOS and adapt it to run under Windows can 
require some considerable effort. There is a steep learning curve associated with the API function libraries. 

This chapter describes how to create a Windows application quickly and simply from an application that 
does not use the Windows API. The application will make use of Open Watcom’s default windowing 
support. 

Suppose you have a set of FORTRAN 77 applications that previously ran under a system like DOS and you 
now wish to run them under Windows 3.x. To achieve this, you can simply recompile your application 
with the appropriate options and link with the appropriate libraries. We provide a default windowing 
system that turns your character-mode application into a simple Windows 3.x Graphical User Interface 
(GUI) application. 

Normally, a Windows 3.x GUI application makes use of user-interface tools such as menus, icons, scroll 
bars, etc. However, an application that was not designed as a windowed application (such as a DOS 
application) can run as a GUI application. This is achieved by our default windowing system. The 
following sections describe the default windowing system. 


16.1 Console Device in a Windowed Environment 


In a FORTRAN 77 application that runs under DOS, unit 5 and unit 6 are connected to the standard input 
and standard output devices respectively. It is not a recommended practice to read directly from the 
standard input device or write to the standard output device when running in a windowed environment. For 
this reason, a default windowing environment is created for FORTRAN 77 applications that read from unit 
5 or write to unit 6. When your application is started, a window is created in which output to unit 6 is 
displayed and input from unit 5 is requested. 

In addition to the standard I/O device, it is also possible to perform I/O to the console by explicitly opening 
a file whose name is "CON". When this occurs, another window is created and displayed. This window is 
different from the one created for standard input and standard output. In fact, every time you open the 
console device a different window is created. This provides a simple multi-windowing system for multiple 
streams of data to and from the console device. 
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16.2 The Sample Non-GUI Application 

To demonstrate the creation of 16-bit Windows 3.x applications, we introduce a simple sample program. 
For our example, we are going to use the "sieve" program. 

* This program computes the prime numbers between 1 and 10,000 

* using the Sieve of Eratosthenes algorithm. 


IMPLICIT NONE 
INTEGER UPBOUND 
PARAMETER (UPBOUND=10000) 

INTEGER I, K, PRIMES 
LOGICAL*1 NUMBERS(2:UPBOUND) 

CHARACTER*11 FORM 

PARAMETER (FORM='(A,15,A,15)') 

DO I = 2, UPBOUND 

NUMBERS(I) = .TRUE. 

ENDDO 

PRIMES = 0 

DO I = 2, UPBOUND 

IF( NUMBERS(I) )THEN 

PRIMES = PRIMES + 1 
DO K = I + I, UPBOUND, I 
NUMBERS(K) = .FALSE. 

ENDDO 
END IF 
ENDDO 

PRINT FORM, 'The Number of Primes between 1 and ', UPBOUND, 
1 ' are: ', PRIMES 

END 


The goal of this program is to count the prime numbers between 1 and 10,000. It uses the famous Sieve of 
Eratosthenes algorithm to accomplish this task. We will take you through the steps necessary to produce 
this result. 


16.3 Building and Running the Non-GUI Application 

Very little effort is required to port an existing FORTRAN 77 application to Windows 3.x. 
You must compile and link the file sieve .for specifying the "bw" option. 

C>wfl -l=windows -bw -win sieve.for 
The typical messages that appear on the screen are shown in the following illustration. 
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C>wfl -l=windows -bw -win sieve.for 

Open Watcom F77/16 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
wfc sieve.for -bw -win 

Open Watcom FORTRAN 77/16 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 21 statements, 311 bytes, 6 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows 16-bit executable 


If you examine the current directory, you will find that two files have been created. These are 

sieve . ob j (the result of compiling sieve . for) and sieve . exe (the result of linking sieve . ob j 

with the appropriate Open Watcom FORTRAN 77 libraries). 

The resultant 16-bit Windows 3.x application SIEVE . EXE can now be run under Windows 3.x as a 
Windows GUI application. 

16.4 Debugging the Non-GUI Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "sieve" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WFL command, this is fairly straightforward. WFL recognizes the Open Watcom F77 
compiler "debug" options and will create the appropriate debug directives for the Open Watcom Linker. 

For example, to compile and link the "sieve" program with debugging information, the following command 
may be issued. 

C>wfl -l=windows -bw -win -d2 sieve.for 
The typical messages that appear on the screen are shown in the following illustration. 
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C>wfl -l=windows -bw -win -d2 sieve.for 
Open Watcom F77/16 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

wfc sieve.for -bw -win -d2 
Open Watcom FORTRAN 77/16 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 21 statements, 392 bytes, 6 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows 16-bit executable 


The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom F77 compiler. WFL will make sure that this debugging information is included in the executable 
file that is produced by the linker. 

The "bytes" value is larger than in the previous example since selection of the "d2" option results in fewer 
code optimizations by default. You can request more optimization by specifying the appropriate options. 
However, you do so at the risk of making it more difficult for yourself to determine the relationship 
between the object code and the original source language code. 

To request the Open Watcom Debugger to assist in debugging the application, select the Open Watcom 
Debugger icon. It would be too ambitious to describe the debugger in this introductory chapter so we refer 
you to the book entitled Open Watcom Debugger User’s Guide. 

16.5 Default Windowing Library Functions 

A few library functions have been written to enable some simple customization of the default windowing 
system’s behaviour. The following functions are supplied: 

dwfDeleteOnClose 

integer function dwfDeleteOnClose( unit ) 
integer unit 

This function tells the console window that it should close itself when the file is closed. You must 
pass to it the unit number associated with the opened console. 

dwfSetAboutDlg 

integer function dwfSetAboutDlg( title, text ) 
character*!*) title 
character*!*) text 

This function sets the about dialog box of the default windowing system. The "title" points to the 
string that will replace the current title. If title is CHAR(O) then the title will not be replaced. The 
"text" points to a string which will be placed in the about box. To get multiple lines, embed a new 
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line after each logical line in the string. If "text" is CHAR(O), then the current text in the about 
box will not be replaced. 

dwfSetAppTitle 

integer function dwfSetAppTitle( title ) 
character*!*) title 

This function sets the main window’s title. 

dwfSetConTitle 

integer function dwfSetConTitle( unit, title ) 
integer unit 
character*!*) title 

This function sets the console window’s title which corresponds to the unit number passed to it. 
dwfShutDown 


integer function dwfShutDown!) 

This function shuts down the default windowing I/O system. The application will continue to 
execute but no windows will be available for output. 


dwfYield 

integer function dwfYield!) 

This function yields control back to the operating system, thereby giving other processes a chance 
to run. 

These functions are described more fully in the Open Watcom FORTRAN 77 User’s Guide. 
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17 Creating 32-bit Windows 3.x Applications 


This chapter describes how to compile and link 32-bit Windows 3.x applications simply and quickly. In 
this chapter, we look at applications written to exploit the Windows 3.x Application Programming Interface 
(API). 


We will illustrate the steps to creating 32-bit Windows 3.x applications by taking a small sample 
application and showing you how to compile, link, run and debug it. 

17.1 The Sample GUI Application 

To demonstrate the creation of 32-bit Windows 3.x applications, we introduce a simple sample program. 
For our example, we are going to use the "sieve" program. 

*$include winapi.fi 
*$noreference 

INTEGER*2 FUNCTION FWINMAIN( hlnstance, hPrevInstance, 

& IpszCmdLine, nCmdShow ) 

*$reference 

IMPLICIT NONE 

INTEGER*2 hlnstance, hPrevInstance, nCmdShow 
INTEGERS IpszCmdLine 
include 'windows.fi' 


* This program computes the prime numbers between 1 and 10,000 

* using the Sieve of Eratosthenes algorithm. 


INTEGER UPBOUND 
PARAMETER (UPBOUND=10000) 

INTEGER I, K, PRIMES 
LOGICAL*1 NUMBERS(2:UPBOUND) 

CHARACTER*11 FORM 
CHARACTER*60 BUFFER 
PARAMETER (FORM='(A,15,A,15)') 

DO I = 2, UPBOUND 

NUMBERS(I) = .TRUE. 

ENDDO 

PRIMES = 0 

DO I = 2, UPBOUND 

IF( NUMBERS(I) )THEN 

PRIMES = PRIMES + 1 
DO K = I + I, UPBOUND, I 
NUMBERS(K) = .FALSE. 

ENDDO 
END IF 
ENDDO 

WRITE(BUFFER, FORM) 'The Number of Primes between 1 and ', 
& UPBOUND, ' are: ', PRIMES 

CALL MessageBox( 0, BUFFER, 

& 'Sieve of Eratosthenes'c, 

& MB_ OK .OR. MB_ TASKMODAL ) 

END 


The goal of this program is to count the prime numbers between 1 and 10,000. It uses the famous Sieve of 
Eratosthenes algorithm to accomplish this task. We will take you through the steps necessary to produce 
this result. 
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17.2 Building and Running the GUI Application 

To compile and link our example program which is stored in the file sieve . for, enter the following 
command: 

C>wfl386 -l=win386 sieve.for 

The typical messages that appear on the screen are shown in the following illustration. 

C>wfl386 -l=win386 sieve.for 

Open Watcom F77/32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 
wfc386 sieve.for 

Open Watcom FORTRAN 77/32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 4390 statements, 207 bytes, 1585 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows 32-bit executable 


If you examine the current directory, you will find that two files have been created. These are 
sieve . ob j (the result of compiling sieve . for) and sieve . rex (the result of linking sieve . ob j 
with the appropriate Open Watcom FORTRAN 77 libraries). The ".rex" file must now be combined with 
Open Watcom’ s 32-bit Windows supervisor WIN38 6 . EXT using the Open Watcom Bind utility. 

WBIND . EXE combines your 32-bit application code and data (".rex" file) with the 32-bit Windows 
supervisor. The process involves the following steps: 

1. WBIND copies WIN386.EXT into the current directory. 

2. WBIND . EXE optionally runs the resource compiler on the 32-bit Windows supervisor so that the 
32-bit executable can have access to the applications resources. 

3. WBIND . EXE concatenates WIN386 . EXT and the ".rex" file, and creates a ".exe" file with the 
same name as the ".rex" file. 

The following describes the syntax of the WBIND command. 


WBIND file_spec [-d] [-n] [-q] [-s supervisor] [-R rc_options] 


The square brackets [ ] denote items which are optional. 
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WBIND 

file_spec 

■d 


-q 


-s supervisor 


-R rcjjptions 


is the name of the Open Watcom Bind utility, 
is the name of the 32-bit Windows EXE to bind, 
requests that a 32-bit DLL be built. 

indicates that the resource compiler is NOT to be invoked. 

requests that WBIND run in quiet mode (no informational messages are 
displayed). 

specifies the path and name of the Windows supervisor to be bound with the 
application. If not specified, a search of the paths listed in the PATH 
environment variable is performed. If this search is not successful and the 
WATCOM environment variable is defined, the %WATCOM%\BINW directory is 
searched. 

all options after -R are passed to the resource compiler. 


To bind our example program, the following command may be issued: 
C>wbind sieve -n 


If the "s" option is specified, it must identify the location of the WIN386 . EXT file or the W386DLL . EXT 
file (if you are building a DLL). 

Example: 

C>wbind sieve -n -s c:\watcom\binw\win386.ext 

If the "s" option is not specified, then the WATCOM environment variable must be defined or the "BINW" 
directory must be listed in your PATH environment variable. 

Example: 

C>set watcom=c:\watcom 
or 

Opath c : \watcom\binw; c : \dos; c : \windows 
The resultant 32-bit Windows 3.x application SIEVE . EXE can now be run under Windows 3.x. 


17.3 Debugging the GUI Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "sieve" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WFL386 command, this is fairly straightforward. WFL386 recognizes the Open Watcom 
F77 compiler "debug" options and will create the appropriate debug directives for the Open Watcom 
Linker. 

For example, to compile and link the "sieve" program with debugging information, the following command 
may be issued. 
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C>wfl386 -l=win386 -d2 sieve.for 

The typical messages that appear on the screen are shown in the following illustration. 

C>wfl386 -l=win386 -d2 sieve.for 

Open Watcom F77/32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 
wfc386 sieve.for -d2 

Open Watcom FORTRAN 77/32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 4390 statements, 293 bytes, 1585 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows 32-bit executable 


The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom F77 compiler. WFL386 will make sure that this debugging information is included in the 
executable file that is produced by the linker. 

The "bytes" value is larger than in the previous example since selection of the "d2" option results in fewer 
code optimizations by default. You can request more optimization by specifying the appropriate options. 
However, you do so at the risk of making it more difficult for yourself to determine the relationship 
between the object code and the original source language code. 

Once again, the ".rex" file must be combined with Open Watcom’s 32-bit Windows supervisor 
WIN38 6 . EXT using the Open Watcom Bind utility. This step is described in the previous section. 

To request the Open Watcom Debugger to assist in debugging the application, select the Open Watcom 
Debugger icon. It would be too ambitious to describe the debugger in this introductory chapter so we refer 
you to the book entitled Open Watcom Debugger User’s Guide. 

There are more extensive examples of Windows applications written in FORTRAN 77 in the 
\WATC0M\SAMPLES\FORTRAN\WIN directory. The example programs are ELLIPSE . FOR and 
FWCOPY.FOR. 
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18 Porting Non-GUI Applications to 32-bit 
Windows 3.x 


Generally, an application that is to run in a windowed environment must be written in such a way as to 
exploit the Windows Application Programming Interface (API). To take an existing character-based (i.e., 
non-graphical) application that ran under a system such as DOS and adapt it to run under Windows can 
require some considerable effort. There is a steep learning curve associated with the API function libraries. 

This chapter describes how to create a Windows application quickly and simply from an application that 
does not use the Windows API. The application will make use of Open Watcom’s default windowing 
support. 

Suppose you have a set of FORTRAN 77 applications that previously ran under a system like DOS and you 
now wish to run them under Windows 3.x. To achieve this, you can simply recompile your application 
with the appropriate options and link with the appropriate libraries. We provide a default windowing 
system that turns your character-mode application into a simple Windows 3.x Graphical User Interface 
(GUI) application. 

Normally, a Windows 3.x GUI application makes use of user-interface tools such as menus, icons, scroll 
bars, etc. However, an application that was not designed as a windowed application (such as a DOS 
application) can run as a GUI application. This is achieved by our default windowing system. The 
following sections describe the default windowing system. 


18.1 Console Device in a Windowed Environment 


In a FORTRAN 77 application that runs under DOS, unit 5 and unit 6 are connected to the standard input 
and standard output devices respectively. It is not a recommended practice to read directly from the 
standard input device or write to the standard output device when running in a windowed environment. For 
this reason, a default windowing environment is created for FORTRAN 77 applications that read from unit 
5 or write to unit 6. When your application is started, a window is created in which output to unit 6 is 
displayed and input from unit 5 is requested. 

In addition to the standard I/O device, it is also possible to perform I/O to the console by explicitly opening 
a file whose name is "CON". When this occurs, another window is created and displayed. This window is 
different from the one created for standard input and standard output. In fact, every time you open the 
console device a different window is created. This provides a simple multi-windowing system for multiple 
streams of data to and from the console device. 
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18.2 The Sample Non-GUI Application 

To demonstrate the creation of 32-bit Windows 3.x applications, we introduce a simple sample program. 
For our example, we are going to use the "sieve" program. 

* This program computes the prime numbers between 1 and 10,000 

* using the Sieve of Eratosthenes algorithm. 


IMPLICIT NONE 
INTEGER UPBOUND 
PARAMETER (UPBOUND=10000) 

INTEGER I, K, PRIMES 
LOGICAL*1 NUMBERS(2:UPBOUND) 

CHARACTER*11 FORM 

PARAMETER (FORM='(A,15,A,15)') 

DO I = 2, UPBOUND 

NUMBERS(I) = .TRUE. 

ENDDO 

PRIMES = 0 

DO I = 2, UPBOUND 

IF( NUMBERS(I) )THEN 

PRIMES = PRIMES + 1 
DO K = I + I, UPBOUND, I 
NUMBERS(K) = .FALSE. 

ENDDO 
END IF 
ENDDO 

PRINT FORM, 'The Number of Primes between 1 and ', UPBOUND, 
1 ' are: ', PRIMES 

END 


The goal of this program is to count the prime numbers between 1 and 10,000. It uses the famous Sieve of 
Eratosthenes algorithm to accomplish this task. We will take you through the steps necessary to produce 
this result. 


18.3 Building and Running the Non-GUI Application 

Very little effort is required to port an existing FORTRAN 77 application to Windows 3.x. 


You must compile and link the file sieve .for specifying the "bw" option. 
C>wfl386 -l=win386 -bw sieve.for 


The typical messages that appear on the screen are shown in the following illusttation. 
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C>wfl386 -l=win386 sieve.for 

Open Watcom F77/32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 
wfc386 sieve.for -bw 

Open Watcom FORTRAN 77/32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 21 statements, 172 bytes, 6 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows 32-bit executable 


If you examine the current directory, you will find that two files have been created. These are 
sieve . ob j (the result of compiling sieve . for) and sieve . rex (the result of linking sieve . ob j 
with the appropriate Open Watcom FORTRAN 77 libraries). The ".rex" file must now be combined with 
Open Watcom’s 32-bit Windows supervisor WIN38 6 . EXT using the Open Watcom Bind utility. 

WBIND . EXE combines your 32-bit application code and data (".rex" file) with the 32-bit Windows 
supervisor. The process involves the following steps: 

1. WBIND copies WIN386.EXT into the current directory. 

2. WBIND . EXE optionally runs the resource compiler on the 32-bit Windows supervisor so that the 
32-bit executable can have access to the applications resources. 

3. WBIND . EXE concatenates WIN386 . EXT and the ".rex" file, and creates a ".exe" file with the 
same name as the ".rex" file. 

The following describes the syntax of the WBIND command. 


WBIND file_spec [-d] ]-n] [-q] [-s supervisor] [-R rc_options] 


The square brackets [ ] denote items which are optional. 


WBIND 

file_spec 

-d 


-s supervisor 


is the name of the Open Watcom Bind utility, 
is the name of the 32-bit Windows EXE to bind, 
requests that a 32-bit DLL be built. 

indicates that the resource compiler is NOT to be invoked. 

requests that WBIND run in quiet mode (no informational messages are 
displayed). 

specifies the path and name of the Windows supervisor to be bound with the 
application. If not specified, a search of the paths listed in the PATH 
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environment variable is performed. If this search is not successful and the 
WATCOM environment variable is defined, the %WATCOM%\BINW directory is 
searched. 

-R rc_options all options after -R are passed to the resource compiler. 

To bind our example program, the following command may be issued: 

C>wbind sieve -n 

If the "s" option is specified, it must identify the location of the WIN386 . EXT file or the W386DLL . EXT 
file (if you are building a DLL). 

Example: 

C>wbind sieve -n -s c:\watcom\binw\win386.ext 

If the "s" option is not specified, then the WATCOM environment variable must be defined or the "BINW" 
directory must be listed in your PATH environment variable. 

Example: 

C>set watcom=c:\watcom 
or 

Opath c : \watcom\binw; c : \dos; c : \windows 

The resultant 32-bit Windows 3.x application SIEVE . EXE can now be run under Windows 3.x as a 
Windows GUI application. 


18.4 Debugging the Non-GUI Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "sieve" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WFL386 command, this is fairly straightforward. WFL386 recognizes the Open Watcom 
F77 compiler "debug" options and will create the appropriate debug directives for the Open Watcom 
Linker. 

For example, to compile and link the "sieve" program with debugging information, the following command 
may be issued. 

C>wfl386 -l=win386 -bw -d2 sieve.for 
The typical messages that appear on the screen are shown in the following illustration. 
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C>wfl386 -l=win386 -d2 sieve.for 

Open Watcom F77/32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

wfc386 sieve.for -bw -d2 
Open Watcom FORTRAN 77/32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 21 statements, 237 bytes, 6 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows 32-bit executable 


The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom F77 compiler. WFL386 will make sure that this debugging information is included in the 
executable file that is produced by the linker. 

The "bytes" value is larger than in the previous example since selection of the "d2" option results in fewer 
code optimizations by default. You can request more optimization by specifying the appropriate options. 
However, you do so at the risk of making it more difficult for yourself to determine the relationship 
between the object code and the original source language code. 

Once again, the ".rex" file must be combined with Open Watcom’s 32-bit Windows supervisor 
WIN38 6 . EXT using the Open Watcom Bind utility. This step is described in the previous section. 

To request the Open Watcom Debugger to assist in debugging the application, select the Open Watcom 
Debugger icon. It would be too ambitious to describe the debugger in this introductory chapter so we refer 
you to the book entitled Open Watcom Debugger User’s Guide. 

18.5 Default Windowing Library Functions 

A few library functions have been written to enable some simple customization of the default windowing 
system’s behaviour. The following functions are supplied: 

dwfDeleteOnClose 

integer function dwfDeleteOnClose( unit ) 
integer unit 

This function tells the console window that it should close itself when the file is closed. You must 
pass to it the unit number associated with the opened console. 

dwfSetAboutDlg 

integer function dwfSetAboutDlg( title, text ) 
character*!*) title 
character*!*) text 
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This function sets the about dialog box of the default windowing system. The "title" points to the 
string that will replace the current title. If title is CHAR(O) then the title will not be replaced. The 
"text" points to a string which will be placed in the about box. To get multiple lines, embed a new 
line after each logical line in the string. If "text" is CHAR(O), then the current text in the about 
box will not be replaced. 

dwfSetAppTitle 

integer function dwfSetAppTitle ( title ) 
character*!*) title 

This function sets the main window’s title. 

dwfSetConTitle 

integer function dwfSetConTitle! unit, title ) 
integer unit 
character*!*) title 

This function sets the console window’s title which corresponds to the unit number passed to it. 
dwfShutDown 


integer function dwfShutDown!) 

This function shuts down the default windowing I/O system. The application will continue to 
execute but no windows will be available for output. 


dwfYield 

integer function dwfYield!) 

This function yields control back to the operating system, thereby giving other processes a chance 
to run. 

These functions are described more fully in the Open Watcom FORTRAN 77 User’s Guide. 
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19 The Open Watcom 32-bit Windows 3.x Extender 


Open Watcom FORTRAN 77 contains the necessary tools and libraries to create 32-bit applications for 
Windows 3.x. Using Open Watcom FORTRAN 77 gives the programmer the benefits of a 32-bit flat 
memory model and access to the full Windows API (along with the usual FORTRAN 77 and C library 
functions). 

The general model of the environment is as follows: The 32-bit flat memory model program is linked 
against a special 32-bit Windows library. This library contains the necessary information to invoke special 
16-bit functions, which lie in the supervisor (WIN38 6 . EXT) . The 32-bit program is then bound (using 
WBIND . EXE ) with the supervisor to create a Windows executable. At the same time as the 32-bit 
program is being bound, the resource compiler is run on the supervisor, and all the resources for the 
application are placed there. When the application is started, the supervisor obtains the 32-bit memory, 
relocates the 32-bit application into the memory, and invokes the 32-bit application. 

All Windows functions are invoked from the supervisor, and all callback routines lie within the supervisor. 
The local heap resides within the supervisor as well. 

If you are starting from a 16-bit Windows application, most of the code will not change when you port it to 
the 32-bit Windows environment. However, because of the nature of the Windows API and its implicit 
dependencies on a 16-bit environment, some source changes are necessary. These source changes are 
minimal, and are backwards compatible with the 16-bit environment. 


19.1 Pointers 


Throughout this document, there will be references to both near and far , and 16-bit and 32-bit pointers. 
Since this can rapidly become confusing, some initial explanations will be given here. 

A far pointer is a pointer that is composed of both a selector and an offset. A selector determines a specific 
region of memory, and the offset is relative to the start of this region. A near pointer is a pointer that has 
an offset only, the selector is automatically assumed by the CPU. 

The problem with far pointers is the selector overhead. Using a far pointer is much more expensive than 
using a near pointer. This is the advantage of the 32-bit flat memory model - all pointers within the 
program are near, and yet you can address up to 4 gigabytes of memory. 

A 16-bit near pointer occupies 2 bytes of memory (i.e., the offset is 16 bits long). This pointer can 
reference up to 64K of data. 

A 16-bit far pointer occupies 4 bytes of memory. There is a 16-bit selector and a 16-bit offset. This 
pointer can reference up to 64K of data. 

A 32-bit near pointer occupies 4 bytes of memory (i.e., the offset is 32 bits long). This pointer can 
reference up to 4 gigabytes of data. 

A 32-bit far pointer occupies 6 bytes of memory. There is a 16-bit selector and a 32-bit offset. This 
pointer can reference up to 4 gigabytes of data. 
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Windows, in general, uses 16-bit far pointers to pass information around. These 16-bit far pointers can also 
be used by a 32-bit Windows application. The conversion from a 16-bit pointer to a 32-bit pointer will 
occur automatically when you map a dynamically allocatable array to the memory pointed to by the 16-bit 
pointer using the LOCATION = specifier of the ALLOCATE statement. You must also declare the 
allocatable array as far using the array pragma. The syntax for the array pragma is: 

$*pragma array ARRAY_ NAME far 

where ARRAY_ NAME is the array name. 

19.2 Implementation Overview 

This section provides an overview of the issues that require consideration when creating a 32-bit Windows 
application for a 16-bit Windows environment. 

First, all modules have to be recompiled for the 32-bit flat memory model with a compiler capable of 
generating 32-bit instructions. 

Pointers to data passed to Windows are all far pointers. We will be passing pointers to data in our 32-bit 
flat address space, and these pointers are near pointers. As well, notice that these 32-bit near pointers are 
the same size as as their 16-bit far pointer counterparts (4 bytes). This is good, since all data structures 
containing pointers will remain the same size. 

Windows cannot be called from 32-bit code on a 32-bit stack. This means that in order to call the API 
functions, it is necessary to write a set of cover functions that will accept the parameters, switch into a 
16-bit environment, and then call Windows. There is another issue, though. Windows only understands 
16-bit pointers, so before calling Windows, all pointers being passed to Windows must be converted to 
16-bit far pointers. 

It turns out that Windows can also call back to your application. Windows can only call 16-bit code, 
though, so there is a need for a bridge from the 16-bit side to the 32-bit side. It is necessary to allocate 
16-bit call back routines that can be passed to Windows. These call back routines will then switch into the 
32-bit environment and call whatever 32-bit function is required. The 32-bit call back has to be declared as 
a far function, since it is necessary to issue a far call to enter it from the 16-bit side. If it is a far function, 
then the compiler will generate the appropriate code for it to return from the far call. 

Once Windows calls you back, it can hand you 16-bit far pointers in a long (4 byte) parameter. This 
pointer can only be used in the 32-bit environment if it is a 32-bit far pointer, not a 16-bit far pointer. The 
conversion is simple: the 16-bit offset is extended to a 32-bit offset (the high word is zeroed out). Any far 
pointer that Windows hands to you must be converted in this way. This conversion is performed 
automatically when a dynamically allocatable array is mapped to a 16-bit far pointer using the LOCATION 
specifier of the Open Watcom FORTRAN 77 ALLOCATE statement and the array pragma. The syntax for 
the array pragma is: 

$*pragma array ARRAY_ NAME far 
where ARRAY_ NAME is the array name. 
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Example: 

subroutine DLLSUB( arg_ list ) 
structure /argtypes/ 


integer 

wl 

integer 

w2 

integer 

w3 

integer 

sum 

structure 



record /argtypes/ args(:) 

*$pragma array args far 

integer*4 arg_ list 

allocate ( args(l), location=arg_ list ) 

In the preceding example, arg_ list is a 16-bit far pointer to a structure with the elements described by 
the argtypes structure. The allocatable array args is described as far using the array pragma. 

Sometimes, a Windows application wants to call a procedure in a DLL. The procedure address is a 16-bit 
far pointer. It is not possible to issue an indirect call to this address from the 32-bit environment, so some 
sort of interface is needed. This interface would switch into the 16-bit environment, and then call the 16-bit 
function. 

These issues, along with other minor items, are handled by Open Watcom FORTRAN 77, and are discussed 
in more technical detail in later sections. 


19.3 System Structure 



Figure 5. WIN386 Structure 
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Figure 6. 32-bit Application Structure 

19.4 System Overview 

• WIN38 6 . EXT is the key component of a 32-bit Windows application. It is a 16-bit Windows 
application which contains: 

• All application resources. 

• A 16-bit local heap. 

• A 16-bit stack. 

• W38 6DLL. EXT is similar to WIN38 6 . EXT, only it provides a DLL interface. 

WIN386 . EXT is bound to your 32-bit application to create a 32-bit application that will run under 
Windows 3.x. WIN3 8 6 . EXT provides the following functionality: 

• supervisor to bring the 32-bit application into memory and start it running. 

• "glue" functions to connect to Windows for both API and DOS functionality. This interface is 
designed to transparently set up the calling functions’ pointers and parameters to their 16-bit 
counterparts. 

• "glue-back" functions to allow Windows to call back 32-bit routines. 

• special code to allow debugging of 32-bit applications. 

• A number of files with file extension . f i are located in the \WATCOM\SRC\FORTRAN\WIN 
directory. The file WINAPI .FI describes the calling convention of each Windows API function. 
Other files define Windows constants and data structures. 

• WIN38 6 . LIB contains all the necessary library functions to connect to the 32-bit supervisor 
WIN38 6 . EXT . All Windows API calls and Open Watcom FORTRAN 77 library DOS calls are 
found here. 

• The standard FORTRAN 77 and C library functions, specially modified to run in the 32-bit 
environment, are located in the \WATCOM\LIB386\WIN directory. 

• WBIND . EXE merges your 32-bit executable and the appropriate Supervisor into a single executable. 


126 System Overview 












The Open Watcom 32-bit Windows 3.x Extender 


19.5 Steps to Obtaining a 32-bit Application 

The following is an overview of the procedure for creating a 32-bit Windows Application: 

1. If you are starting with a 16-bit Windows application, you must adapt your source code to the 
32-bit environment. 

2. You must compile the application using a 32-bit compiler. 

3. You must link the application with the 32-bit libraries. 

4. You must bind the 32-bit application with the 32-bit supervisor. 

5. You can then run and/or debug the application. 
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20 Windows 3.x 32-bit Programming Overview 


This chapter includes the following topics: 

• WINAPI.FI and WINDOWS .FI 

• Environment Notes 

• Floating-point Emulation 

• Multiple Instances 

• Pointer Handling 

• When To Convert Incoming Pointers 

• When To Convert Outgoing Pointers 

• SendMessage and SendDlgltemMessage 

• GlobalAlloc and LocalAlloc 

• Callback Function Pointers 

• Window Sub-classing 

• Calling 16-bit DLLs 

• _16 Functions 


20.1 WINAPI.FI 


When developing programs, make sure WINAPI. FI is included at the start of all source files and the 
necessary include files (particularly WINDOWS .FI) are included in each function or subroutine. 

It is especially important to get the correct function and argument typing information for Windows API 
functions. Due to the default typing rules of FORTRAN, many Windows API functions have a default 
result type of REAL when they may in fact return an INTEGER or INTEGER*2 result. By including the 
appropriate include files, you ensure that this never happens. For example, the function CreateDialog 
is described in WINDLG. FI . as a function returning an INTEGER*2 result. 
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Example: 

external CreateDialog 
integer*2 CreateDialog 

Failure to specify the correct type of a function will result in code that looks correct but does not execute 
correctly. Similarly, you should make sure that all symbolic constants are properly defined by including 
the appropriate include files. For example, the constant DEFAULT_ QUALITY is described in 
WINFONT . FI as an INTEGER constant whose value is 0. 

Example: 

integer DEFAULT_ QUALITY 
parameter ( DEFAULT_ QUALITY = 0 ) 

Without this information, DEFAULT_ QUALITY would be assumed to be a REAL variable and would not 
have any assigned value. 

The "EXPLICIT" compiler option is useful in this regard. It requires that all symbols be explicitly typed. 


20.2 Environment Notes 


• The 32-bit Windows Supervisor uses the first 256 bytes of the 32-bit application’s stack to save state 
information. If this is corrupted, your application will abnormally terminate. 

• The 32-bit Windows Supervisor provides resources for up to 512 callback routines. Note that this 
restriction is only on the maximum number of active callbacks. 


20.3 Floating-point Emulation 

The file WEMU387.386 is included to support floating-point emulation for 32-bit applications running 
under Windows. This file is installed in the [386Enh] section of your SYSTEM. INI file. By using the 
floating-point emulator, your application can be compiled with the "fpi87" option to use inline 
floating-point instructions, and it will run on a machine without a numeric coprocessor. 

Only one of WEMU387.386 and WDEBUG .386 may be installed in your [ 3 8 6Enh ] section. 

WEMU 387.386 may be distributed with your application. 


20.4 Multiple Instances 

Since the 32-bit application resides in a flat memory space, it is NOT possible to share code with other 
instances. This means that you must register new window classes with callbacks into the new instance’s 
code space. A simple way of accomplishing this is as follows: 


integer*2 

& 

& 

& 


function FWINMAIN( hlnstance, 

hPrevInstance, 
IpszCmdLine, 
nCmdShow ) 


integer*2 

integer*2 

integer*2 

integer*4 


hlnstance 

hPrevInstance 

nCmdShow 

IpszCmdLine 
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include 

include 

include 

include 

include 

include 

include 

include 

include 


'win386.f i' 

' wincreat.f i' 
' wincurs.f i' 

' windefn.f i' 

' windisp.f i' 

' winmsg.f i' 

'winmsgs.f i' 

'windtool.f i' 
'winutil.f i' 


external WndProc 


integer*2 
record /MSG/ 
record /WNDCLASS/ 
character*14 


hWnd 

msg 

wndclass 

class 


wndclass . style = CS_ HREDRAW .or. CS_ VREDRAW 

wndclass.lpfnWndProc = loc( WndProc ) 

wndclass.cbClsExtra = 0 

wndclass.cbWndExtra = 0 

wndclass.hlnstance = hlnstance 

wndclass .hlcon = NULL_ HANDLE 

wndclass . hCursor = LoadCursor ( NULL_ HANDLE, IDC_ ARROW ) 
wndclass.hbrBackground = GetStockObject( WHITE_ BRUSH ) 
wndclass.IpszMenuName = NULL 

write( class, Ellipses'',i5.5,a)' ) hlnstance, char(O) 

wndclass.IpszClassName = Loc( class ) 
call RegisterClass( wndclass ) 


hWnd = CreateWindow( 

& 

& 

& 

& 

& 

& 

& 

& 

& 

& 


class, 

'Application'c, 

WS_ OVERLAPPEDWINDOW, 
CW_ USEDEFAULT, 

0 , 

CW_ USEDEFAULT, 

0 , 

NULL_ HANDLE, 

NULL_ HANDLE, 
hlnstance, 

NULL ) 


The variable class contains a unique name based on the instance of the application. 


20.5 Pointer Handling 

Windows 3.x is a 16-bit operating system. Function pointers that Windows deals with are 16-bit far 
pointers, and any data you communicate to Windows with are 16-bit far pointers. 16-bit far pointers 
occupy 4 bytes of data, and are capable of addressing up to 64K. For data objects larger than 64K, huge 
pointers are used (a sequence of far pointers that map out consecutive 64K segments for the data object). 
16-bit far pointers are expensive to use due to the overhead of selector loads (each time you use the pointer, 
a segment register must have a value put in it). 16-bit huge pointers are even more expensive: not only is 
there the overhead of selector loads, but a run-time call is necessary to perform any pointer arithmetic. 

In a 32-bit flat memory model, such as that of the Open Watcom F77 for Windows environment, all 
pointers are 32-bit near pointers (occupying 4 bytes of data as well). However, these pointers may access 
objects of up to 4 gigabytes in size, and there is no selector load overhead. 

For a 32-bit environment to communicate with Windows 3.x, there are some considerations. All pointers 
sent to Windows must be converted from 32-bit near pointers to 16-bit far pointers. These conversions are 
handled by the Supervisor. 
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It is important to remember that all API functions which accept pointers (with the exception of functions 
that accept function pointers) accept 32-bit near pointers in this 32-bit model. If you attempt to pass a 
32-bit far pointer, the conversion will not take place correctly. 

16-bit far pointers to data may be passed into the API functions, and the Supervisor will not do any 
conversion. 

Incoming pointers must be converted from 16-bit far pointers to 32-bit far pointers. This conversion is a 
trivial one: the offset portion of the 16-bit far pointer is extended to 32-bits. The pointer conversion will 
occur automatically when you map a dynamically allocatable array to the memory pointed to by the 16-bit 
pointer using the LOCATION= specifier of the ALLOCATE statement. You must also declare the array as 
far using the array pragma. The syntax for the array pragma is: 

$*pragma array ARRAY_ NAME far 

where ARRAY_ NAME is the array name. Pointers from Windows are by their nature far (that is, the data is 
pointed to by its own selector), and must be used as far in the 32-bit environment. Of course, conversions 
are only required if you actually need to reference the pointer. 

Function pointers (i.e., pointers to callback routines) used by Windows are not converted from 32-bit to 
16-bit. Rather, a 16-bit thunking layer that transfers control from the 16-bit environment to the 32-bit 
environment must be used. This thunking layer is provided by the Supervisor. 

20.5.1 When To Convert Incoming Pointers 

Whenever you wish to use a pointer passed to you by Windows, you must map a dynamically allocatable 
array to the memory pointed to by the pointer using the LOCATION specifier of the ALLOCATE 
statement. You must also declare the array as far using the array pragma. The pointer conversion will 
occur automatically. 

Some places where pointer conversion may be required are: 

• LocalLock 

• GlobalLock 

• the IParam in a window callback routine (if it is a pointer) 

20.5.2 When To Convert Outgoing Pointers 

Typically, there is no need to do any kind of conversions on your pointers when passing them to Windows. 
The Supervisor handles all 32-bit to 16-bit translations for you, in the case of the regular Windows API 
functions. However, if you are passing a 32-bit pointer to some other 16-bit application in the Windows 
environment, then pointer conversions must by done. There are two types of "outgoing" pointers: data 
pointers and function pointers. 

Function pointers (to callback routines) must have a thunking layer provided, using the GetProcl6 function 
(this is explained in detail in a later section). 

Data pointers can be translated from 32-bit to 16-bit using the AllocAlias 16 and AllocHugeAlias 16 
functions. These functions create 16-bit far pointers that have the same linear address as the 32-bit near 
pointer that was converted. 
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It is important to remember that when passing a pointer to a data structure in this fashion, any pointers in 
the data structure must also be converted. 

The Supervisor will convert any pointers that it knows about; but there are some complications created by 
the fact that Windows allows you to pass pointers in functions that are prototyped to take a long integer. 

The Windows API functions SendMessage and SendDlgltemMessage rely on other fields determining the 
nature of the long data item that they accept; this is discussed in detail in the next section. 


20.5.2.1 SendMessage and SendDlgltemMessage 

SendMessage and SendDlgltemMessage have special cover functions that determine when the 32-bit 
integer is really a pointer and needs to be converted. These cover functions are used automatically, unless 
the macro NOCOVERSENDS is defined before including WINAPI. FI as in the following example. 

*$define NOCOVERSENDS 
*$include winapi.fi 

SendMessage and SendDlgltemMessage will do pointer conversions automatically using AllocAlias 16 and 
FreeAliasl6 (unless NOCOVERSENDS is defined) for the following message types: 


• combo boxes (CB_ messages) 

• edit controls (EM_ messages) 

• list boxes (LB_ messages) 

• certain windows messages (WM_ messages); 


The messages that are intercepted by the cover functions for SendMessage and SendDlgltemMessage are: 


CB_ ADDSTRING CB_ DIR CB_ FINDSTRING 

CB_ FINDSTRINGEXACT CB_ GETLBTEXT CB_ INSERTSTRING 

CB_ SELECTSTRING 


EM_ GETLINE 
EM_ SETRECT 


EM_ GETRECT EM_ REPLACESEL 

EM_ SETRECTNP EM_ SETTABSTOPS 


LB_ ADDSTRING LB_ DIR 

LB_ FINDSTRINGEXACT LB_ GETITEMRECT 
LB_ GETTEXT LB_ INSERTSTRING 

LB_ SETTABSTOPS 


LB_ FINDSTRING 
LB_ GETSELITEMS 
LB_ SELECTSTRING 


WM_ MDI CREATE 


WM_ NCCALCSIZE 


Note that for SendMessage and SendDlgltemMessage , some of the messages may NOT require pointer 
conversion: 

• CB_ADDSTRING, CB_FINDSTRING, CB_FINDSTRINGEXACT, CB_INSERTSTRING will not 
need a conversion if the combo box was created as owner-draw style without CBS_HASSTRINGS 
style. 

• LB_ADDSTRING, LB_FINDSTRING, LB_FINDSTRINGEXACT, LB JNSERTSTRING will not 
need a conversion if the list box was created as owner-draw style without LBS_HASSTRINGS style. 


The macro NOCOVERSENDS should be defined in modules where messages like these are being sent. 
With these messages, the IParam data item does not contain a pointer, and the automatic pointer conversion 
would be incorrect. By doing 


Pointer Handling 133 




Windows 3.x Programming Guide 


*$define NOCOVERSENDS 
*$include winapi.fi 

modules that send messages like the above will not have the pointer conversion performed. 

20.5.3 GlobalAlloc and LocalAlloc 

The functions GlobalAlloc and LocalAlloc are the typical way of allocating memory in the 16-bit Windows 
environment. In the 32-bit environment, there is no need to use these functions. The only time 
GlobalAlloc is needed is when allocating shared memory, i.e., GMEM_DDESHARE. 

The ALLOCATE and DEALLOCATE statements can be used to allocate memory from your 32-bit near 
heap. By allocating memory in this way, you may create data objects as large as the enhanced mode 
Windows memory manager will permit. 

20.5.4 Callback Function Pointers 

To access a callback function, an instance of it must be created using MakeProcInstance. This creates a 
"thunk" (a special piece of code) that automatically puts the application’s data segment into the AX 
register, and then calls the specified callback function. 

In Windows 3.x, it is not possible to do a MakeProcInstance directly on a 32-bit callback routine, since 
Windows 3.x does not understand 32-bit applications. Therefore, it is necessary to use a 16-bit callback 
routine that passes control to the 32-bit callback routine. This 16-bit callback routine is automatically 
created by the Supervisor when using any of the standard Windows API functions that accept a callback 
routine. 

The 16-bit callback routine for a 32-bit application is a special layer that transfers the parameters from a 
16-bit stack to the 32-bit stack, and then passes control to 32-bit code. These 16-bit callback routines are 
found in the Supervisor. The function GetProcI6 provides pointers to these 16-bit callback routines. 

However, it is not often necessary to use the GetProcl6 function to obtain a 16-bit/32-bit callback interface 
function. 

In the general case, one would have to write code as follows: 
integer*4 pCb, fpProc 

pCb = GetProcl6( A_ Function, GETPROC_ callbacktype ) 
fpProc = MakeProcInstance ( pCb, hlnstance ) 

* do stuff 

call Do_ it( . . . , fpProc, ... ) 

* do more stuff 

call FreeProcInstance( fpProc ) 
call ReleaseProcl6( pCb ) 

It is not necessary to use this general code in the case of the regular Windows API functions. The 
following functions will automatically allocate the correct 16-bit/32-bit callback interface functions: 
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• ChooseColor 

• ChooseFont 

• CreateDialog 

• CreateDialoglndirect 

• CreateDialoglndirectParam 

• CreateDialogParam 

• DialogBox 

• DialogBoxIndirect 

• DialogBoxIndirectParam 

• DialogBoxParam 

• EnumChildWindows 

• EnumFonts 

• EnumMetaFile 

• EnumObjects 

• EnumProps 

• EnumTaskWindows 

• EnumWindows 

• Escape (SETABORTPROC option) 

• FindText 

• GetOpenFileName 

• GetSaveFileName 

• GlobalNotify 

• GrayString 

• LineDDA 

• PrintDlg 

• RegisterClass 

• ReplaceText 

• SetClassLong (GCL_WNDPROC option) 

• SetResourceHandler 

• SetTimer 

• SetWindowLong (GWL_WNDPROC option) 

• SetWindowsHook 

As well, the following functions are covered to provide support for automatic creation of 16-bit callback 
routines: 

• FreeProcInstance 

• MakeProcInstance 

• UnhookWindowsPIook 

If you need to get a callback that is not used by one of the above functions, then you must code the general 
case. Typically, this is required when a DLL needs a callback routine. In modules where this is necessary, 
you define the macro NOAUTOPROCS before you include WINAPI. F I as in the following example. 

*$define NOAUTOPROCS 
*$include winapi.fi 

Be careful of the following when using NOAUTOPROCS. 

1. The call to MakeProcInstance and FreeProcInstance for the callback function occurs in a 
module with NOAUTOPROCS defined. 

2. No Windows API functions (listed above) are used in the module with NOAUTOPROCS 
defined. If they are, you must code the general case to use them. 
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Note that NOAUTOPROCS is in effect on a module-to-module basis only. 

RegisterClass automatically does a GetProcl6 for the callback function, unless the macro NOCOVERRC is 
specified before including WINAPI. FI as in the following example. 

*$define NOCOVERRC 
*$include winapi.fi 

20.5.4.1 Window Sub-classing 

Sub-classing a Windows control in the 32-bit environment is straightforward. In fact, the code is identical 
to the code used in the 16-bit environment. A simple example is: 

*$include winapi.fi 

*$pragma aux (callback) SubClassProc parm( value, value, value, value ) 

integer*4 function SubClassProc( hWnd, msg, wp, lp ) 

integer*2 hWnd 

integer*2 msg 

integer*2 wp 

integer*4 lp 

include 'windows.fi' 

common fpOldProc 
integer*4 fpOldProc 

! code for sub-classing here 

SubClassProc = CallWindowProc( fpOldProc, hWnd, msg, wp, lp ) 
end 

program SubClassDemo 
integer*2 hControl 
common fpOldProc 
integer*4 fpOldProc 
integer*4 fp; 

include 'windows.fi' 

integer*4 SubClassProc 
external SubClassProc 
integer*4 Programlnstance 
external Programlnstance 

! assume hControl gets created in here 

fpOldProc = GetWindowLong( hControl, GWL_ WNDPROC ) 
fp = MakeProcInstance( SubClassProc, Programlnstance ) 
call SetWindowLong( hControl, GWL_ WNDPROC, fp ) 

! set it back 

call SetWindowLong( hControl, GWL_ WNDPROC, fpOldProc ) 
call FreeProcInstance( fp ) 

end 


Note that SetWindowLong is covered to recognize GWL_WNDPROC and automatically creates a 16-bit 
callback for the 32-bit callback. When replacing the callback routine with the original 16-bit routine, the 
covered version of SetWindowLong recognizes that the function is not a 32-bit callback, and so passes the 
pointer right through to Windows unchanged. 
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20.6 Calling 16-bit DLLs 

A 16-bit function in a DLL can be called using the _Calll6 function. The first argument to _Calll6 is the 
address of the 16-bit function. This address is usually obtained by calling GetProcAddress with the name 
of the desired function. The second argument to _Calll6 is a string identifying the types of the parameters 
to be passed to the 16-bit function. 

Character Parameter Type 

c call a ’cdecT function as opposed to a ’pascal’ function (if specified, it must be listed first) 

b unsigned BYTE 

w 16-bit WORD 

d 32-bit DWORD 

/ double precision floating-point 

p 32-bit flat pointer (converted to 16:16 far pointer) 

The 16-bit function must use either the PASCAL or CDECL calling convention. PASCAL calling 
convention is the default. If the function uses the CDECL calling convention, then you must specify the 
letter "c" as the first character of the argument type string. 

Pointer types will automatically be converted from 32-bit near pointers to 16-bit far pointers before the 
function is invoked. Note that this pointer is only valid over the period of the call; after control returns to 
the 32-bit application, the 16-bit pointer created by the Supervisor is no longer valid. 

The return value from _Calll6 is a DWORD. 


*$include winapi.fi 


integer*2 

& 

& 

& 

integer*2 

integer*2 

integer*4 

integer*2 


function FWinMain( 


hlnstance 

hPrevInstance 

IpszCmdLine 

nCmdShow 


hlnstance, 
hPrevInstance, 
IpszCmdLine, 
nCmdShow ) 


include 'windows.fi' 


integer*2 hDrv, hWnd 
integer*4 lpfn, cb 

hDrv = LoadLibrary( 'your.dll'c ) 
if( hDrv .It. 32 )then 
return 
end if 

lpfn = GetProcAddress( hDrv, 'ExtDeviceMode'c ) 
if( lpfn .eq. 0 )then 
return 
end if 

! Invoke the function. 

cb = _Calll6( lpfn, 'wwdppddw'c, 

& hWnd, hDrv, NULL, 

& 'POSTSCRIPT PRINTER'c, 

& 'LPTl'c, 

& NULL, NULL, 0 ) 
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20.7 16 Functions 


Every Windows API function that accepts a pointer has a corresponding _16 function. The _16 version of 
the function will not convert any of the pointers that it accepts; it will assume that all pointers are 16-bit far 
pointers already. This applies to both data and function pointers. 
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21 Windows 32-Bit Dynamic Link Libraries 

21.1 Introduction to 32-Bit DLLs 


Open Watcom FORTRAN 77 allows the creation of 32-bit Dynamic Link Libraries (DLL). In fact, 32-bit 
DLLs are simpler to write than 16-bit DLLs. A 16-bit DLL runs on the caller’s stack, and thus DS != SS. 
This creates difficulties in the small and medium memory models because near pointers to local variables 
are different from near pointers to global variables. The 32-bit DLL runs on its own stack, in the usual flat 
memory space, which eliminates these concerns. 

There is a special version of the supervisor, W386DLL. EXT that performs a similar job to WIN38 6 . EXT . 
However, the 32-bit DLL supervisor is a 16-bit Windows DLL, rather than a 16-bit Windows application. 
On the first use of the 32-bit DLL, the DLL supervisor loads the 32-bit DLL and invokes the 32-bit 
initialization routine (the DLL’s FWinMain routine). The initialization routine declares all entry points 
(via Def ineDLLEntry) and performs any other necessary initialization. An index number in the range 1 
to 128 is used to identify all external 32-bit DLL routines. Def ineDLLEntry is used to assign an index 
number to each routine, as well as to identify the arguments. 

The DLL supervisor contains a general entry point for Windows applications to call into called 
Win386LibEntry . It also contains 128 specific entry points called DLL1 to DLL128 which correspond 
to the entry points established via Def ineDLLEntry (the first argument to Def ineDLLEntry is an 
index number in the range 1 to 128). All applications call into the 32-bit DLL via these entry points. They 
build the necessary stack frame and switch to the 32-bit DLL’s data space. 

If you call via Win386LibEntry then you pass the DLL entry point number or index (1 to 128) as the 
last argument. Win3 8 6LibEntry uses this index number to call the appropriate 32-bit DLL routine. 

From a pseudo-code point of view, the 16-bit supervisor might look like the following: 

DLL1:: set index=l 

invoke 32bitDLLindirect 

DLL2:: set index=2 

invoke 32bitDLLindirect 


DLL128:: set index=128 

invoke 32bitDLLindirect 

Win386LibEntry:: 

set index from index_ argument 
invoke 32bitDLLindirect 

32bitDLLindirect: 

set up stack frame 

switch to 32-bit data space 

call indirect registration_ list[ index ] 
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When you are creating a 32-bit DLL, keep in mind that the entry points you define may be invoked by a 
16-bit application as well as a 32-bit application. It is for this reason that all far pointers passed to a 32-bit 
DLL are 16-bit far pointers. Hence, whenever a pointer is passed as an argument to a 32-bit DLL entry 
point and you wish to access the data it points to, you must convert the pointer appropriately. To do this, 
you must map a dynamically allocatable array to the memory pointed to by the 16-bit far pointer. 

21.2 A Sample 32-bit DLL 

Let us begin our discussion of DLLs by showing the code for a simple DLL. The source code for these 
examples is provided in the \WATCOM\SAMPLES\FORTRAN\WIN\DLL directory. We describe how to 
compile and link the examples in the section entitled "Creating and Debugging Dynamic Link Libraries" on 
page 147. 

*$include winapi.fi 

* WINDLLV.FOR 

* Setup: set finclude=\WATCOM\src\fortran\win 

* Compile and Link: wfl386 windllv -explicit -d2 -bd -l=win386 

* Bind: wbind windllv -d -n 

*$pragma aux (dll_ function) Add3 

integer function Add3( wl, w2, w3 ) 
integer*4 wl, w2, w3 

include 'windows.fi' 

character*128 str 

write( str, '(16hDLL 1 arguments:, 3il0, a)' ) 

& 

call MessageBox( NULL, str, 'DLL Function l'c, 

Add3 = wl + w2 + w3 

end 

*$pragma aux (dll_ function) Add2 

integer function Add2( wl, w2 ) 
integer*4 wl, w2 

include 'windows.fi' 

character*128 str 

write( str, '(16hDLL 2 arguments:, 2il0, a)' ) wl, w2, char(O) 
call MessageBox( NULL, str, 'DLL Function 2'c, MB_ OK ) 

Add2 = wl + w2 

end 

integer*2 function FWinMain( hlnstance, 

& hPrevInstance, 

& IpszCmdLine, 

& nCmdShow ) 

integer*2 hlnstance 
integer*2 hPrevInstance 
integer*4 IpszCmdLine 
integer*2 nCmdShow 

include 'windows.fi' 

external Add3, Add2 
integer rc 


wl, w2, w3, 
char(0) 

MB_ OK ) 
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call Breakpoint 

rc = DefineDLLEntry ( 1 , Add3, DLL_ DWORD, DLL_ DWORD, DLL_ DWORD, 
& DLL_ ENDLIST ) 

if( rc .ne. 0 )then 
FWinMain = 0 
return 
end if 

rc = DefineDLLEntry ( 2, Add2, DLL_ DWORD, DLL_ DWORD, 

& DLL_ ENDLIST ) 

if( rc .ne. 0 )then 
FWinMain = 0 
return 
end if 

call MessageBox( NULL, '32-bit DLL started'c, 

& ' WINDLLV' c, MB_ OK ) 

FWinMain = 1 

end 


There are two entry points defined, Add3 (index number 1) and Add2 (index number 2). Add3 has three 
INTEGER*4 arguments and Add2 has two INTEGER*4 arguments. The argument lists are described by 
calling DefineDLLEntry. All arguments are passed by value. As previously mentioned, all pointers 
passed to 32-bit DLLs are 16-bit far pointers. Since, by default, FORTRAN 77 passes arguments by 
reference (a pointer to the data is passed instead of the actual data), a level of complexity is introduced 
since some pointer conversions must take place when accessing the data pointed to by a 16-bit far pointer in 
a 32-bit environment. We will deal with this problem in a following example. First, let us deal with 
passing arguments by value to 32-bit DLLs from 16 and 32-bit Windows applications. 

Note that each entry name must be given the dll_ function attribute using an auxiliary pragma. This 
alias name is defined in the file WINAPI. FI. 

FWinMain returns zero to notify Windows that the DLL initialization failed, and returns a one if 
initialization succeeds. 

FWinMain accepts the same arguments as the FWinMain procedure of a regular Windows program, 
however, only two arguments are used, hlnstance is the DLL handle and IpszCmdLine is the 
command line passed to the DLL. 

21.3 Calling Functions in a 32-bit DLL from a 16-bit 
Application 

The following is a 16-bit Windows program that demonstrates how to call the two routines defined in our 
DLL example. 

*$include winapi.fi 

* GEN16V.FOR 

* Setup: set finclude=\WATCOM\src\fortran\win 

* Compile and Link: wfl genl6v -explicit -d2 -windows -l=windows 

* -"op desc '16-bit DLL Test'" 

*$pragma aux (dll32_ call) indirect_ 1 \ 

* parm( value*4, value*4, value*4 ) 

*$pragma aux (dll32_ call) indirect_ 2 \ 

* parm( value*4, value*4 ) 
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integer*2 function FWinMain( hlnstance, 

& hPrevInstance, 

& IpszCmdLine, 

& nCmdShow ) 

integer*2 hlnstance 
integer*2 hPrevInstance 
integer*4 IpszCmdLine 
integer*2 nCmdShow 

include 'windows.fi' 

integer*2 hlib 

integer*4 indirect_ 1, indirect_ 2 
integer*4 dll_ 1, dll_ 2, cb 
character*128 str 

hlib = LoadLibrary( 'windllv.dll'c ) 
if( hlib .It. 32 ) then 

call MessageBox( NULL, 'Can''t load WINDLLV'c, 

& ' Genl 6V' c, MB_ OK ) 

stop 
endif 

dll_ 1 = GetProcAddress( hlib, 'DLLl'c ) 
dll_ 2 = GetProcAddress( hlib, 'DLL2'c ) 

cb = indirect_ 1 ( 111, 22222, 3333, dll_ 1 ) 

write ( str, ' (15hDLL 1 returned , ilO, a)' ) cb, char(O) 

call MessageBox( NULL, str, 'Genl6V Test l'c, MB_ OK ) 

cb = indirect_ 2 ( 4444, 55, dll_ 2 ) 

write ( str, ' (15hDLL 2 returned , ilO, a)' ) cb, char(O) 
call MessageBox( NULL, str, 'Genl6V Test 2'c, MB_ OK ) 

FWinMain = 0 

end 


The addresses of the routines DLL1 and DLL2 in the 32-bit DLL are obtained and stored in the variables 
dll_ 1 anddll_ 2 . Since the FORTRAN 77 language does not support indirect function calls, we need a 
mechanism to call these functions indirectly. We do this using the two indirect functions called 
indirect_ 1 andindirect_ 2 . These two functions are given thedll32_ call attribute using an 
auxiliary pragma which is defined in the file WINAPI . FI . Note that the last argument of the calls to 
indirect— 1 orindirect— 2 is the actual address of the DLL routine. 

What you should realize is that the indirect— 1 andindirect_ 2 functions do not really exist. The 
code that is generated for statements like the following is really an indirect call to the function whose 
address is represented in the last argument. 

cb = indirect- 1 ( 111, 22222, 3333, dll_ 1 ) 
cb = indirect— 2 ( 4444, 55, dll_ 2 ) 

This is a result of using the dll32_ call auxiliary pragma attribute to describe bothindirect— 1 and 
indirect— 2 . You can verify this by disassembling the object file that is generated when this code is 
compiled. 
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21.4 Calling Functions in a 32-bit DLL from a 32-bit 
Application 

The following is a 32-bit Windows program that demonstrates how to call the two routines defined in our 
32-bit DLL example. Since this is a 32-bit Windows program, we will use the _ Calll 6 function to call 
functions in our 32-bit DLL. Note that we get to the 32-bit DLL functions by going indirectly through the 
16-bit supervisor that forms the "front end" for our 32-bit DLL. 

*$include winapi.fi 

* GEN32V.FOR 

* Setup: set finclude=\WATCOM\src\fortran\win 

* Compile and Link: wfl386 gen32v -explicit -d2 -l=win386 

* Bind: wbind gen32v -n -D "32-bit DLL Test" 


integer*2 function FWinMain( hlnstance, 

& hPrevInstance, 

& IpszCmdLine, 

& nCmdShow ) 

integer*2 hlnstance 
integer*2 hPrevInstance 
integer*4 IpszCmdLine 
integer*2 nCmdShow 

include 'windows.fi' 

integer*2 hlib 

integer*4 dll_ 1 , dll_ 2 , cb 

character*128 str 

hlib = LoadLibrary( 'windllv.dll'c ) 
if( hlib .It. 32 ) then 

call MessageBox( NULL, 'Can''t load WINDLLV'c, 

& 'Gen32V'c, MB_ OK ) 

stop 
endif 

dll_ 1 = GetProcAddress( hlib, 'DLLl'c ) 
dll_ 2 = GetProcAddress( hlib, 'DLL2'c ) 

cb = _ Calll6 ( dll_ 1, 'ddd'c. 111, 22222, 3333 ) 

write ( str, ' (15hDLL 1 returned , ilO, a)' ) cb, char(O) 

call MessageBox( NULL, str, 'Gen32V Test l'c, MB_ OK ) 

cb = _ Calll6 ( dll_ 2, 'dd'c, 4444, 55 ) 

write ( str, ' (15hDLL 2 returned , ilO, a)' ) cb, char(O) 
call MessageBox( NULL, str, 'Gen32V Test 2'c, MB_ OK ) 

FWinMain = 0 

end 


Note that the first argument of a call to _ Calll 6 is the DLL function address returned by 
GetProcAddress and must be a 32-bit argument. The second argument of a call to _ Calll6 is a 
string describing the types of arguments that will be passed to the DLL function. 
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21.5 A Sample 32-bit DLL Using a Structure 

As previously mentioned, passing pointers from a 16 or 32-bit Windows application to a 32-bit DLL poses 
a problem since all pointers are passed as 16-bit far pointers. The pointer must be converted from a 16-bit 
far pointer to a 32-bit far pointer. This is achieved by mapping a dynamically allocatable array to each 
argument that is passed by reference using the LOCATION specifier of the ALLOCATE statement. 
Furthermore, you must specify the far attribute for each such array using the array pragma. Since this 
is cumbersome if you wish to pass many arguments, it is recommended that a single argument be passed 
that is actually a pointer to a structure that contains the actual arguments. Furthermore, since each call to a 
DLL routine is made indirectly through one of Win386LibEntry or DLL1 through DLL128, you 
should also return any values in the same structure since the return value from any of these functions is only 
32-bits wide. 

The following example is a 32-bit DLL that receives its arguments and returns values using a structure. 

The source code for these examples is provided in the \ WATCOM\SAMPLES\FORTRAN\WIN\DLL 
directory. We describe how to compile and link the examples in the section entitled "Creating and 
Debugging Dynamic Link Libraries" on page 147. 

*$include winapi.fi 
* WINDLL.FOR 


* Setup: set finclude=\WATCOM\src\fortran\win 

* Compile and Link: wfl386 windll -explicit -d2 -bd -l=win386 

* Bind: wbind windll -d -n 

*$pragma aux (dll_ function) Add3 

subroutine Add3 ( arg_ list ) 
integer*4 arg_ list 
structure /argtypes/ 


integer 

wl 

integer 

w2 

integer 

w3 

integer 

sum 


end structure 

record /argtypes/ args (:) 

*$pragma array args far 

include 'windows.fi' 

character*128 str 

allocate ( args(l), location=arg_ list ) 

write( str, '(16hDLL 1 arguments:, 3il0, a)' ) args(l).wl, 
& args (1) .w2, 

& args(1).w3, 

& char(O) 

call MessageBox( NULL, str, 'DLL Function l'c, MB_ OK ) 
args(l).sum = args(l).wl + args(l).w2 + args(l).w3 
deallocate( args ) 

end 
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*$pragma aux (dll_ function) Add2 


subroutine Add2 ( arg_ list ) 
integer*4 arg_ list 
structure /argtypes/ 


real 

wl 

real 

w2 

real 

sum 

end structure 



record /argtypes/ args (:) 
*$pragma array args far 


include 'windows.fi' 


character*128 str 


allocate( args(l), location=arg_ list ) 
write( str, '(16hDLL 2 arguments:, 2fl0.2, a)' 

& 

& 

call MessageBox( NULL, str, 'DLL Function 2'c, 
args(l).sum = args(l).wl + args(l).w2 
deallocate ( args ) 

end 

integer*2 function FWinMain( hlnstance, 

& hPrevInstance, 

& IpszCmdLine, 

& nCmdShow ) 

integer*2 hlnstance 
integer*2 hPrevInstance 
integer*4 IpszCmdLine 
integer*2 nCmdShow 

include 'windows.fi' 

external Add3, Add2 
integer rc 

call Breakpoint 
rc = DefineDLLEntry ( 1, Add3, DLL_ PTR, DLL_ ENDLIST ) 
if( rc .ne. 0 )then 
FWinMain = 0 
return 
end if 

rc = DefineDLLEntry ( 2, Add2, DLL_ PTR, DLL_ ENDLIST ) 
if( rc .ne. 0 )then 
FWinMain = 0 
return 
end if 

call MessageBox( NULL, '32-bit DLL started'c, 

& 'WINDLL'c, MB_ OK ) 

FWinMain = 1 


) args(1).wl, 
args(1).w2, 
char (0) 

MB_ OK ) 


end 


The following example is a 16-bit Windows application that passes arguments to a 32-bit DLL using a 
structure. 

*$include winapi.fi 

* GEN16.FOR 

* Setup: set finclude=\WATCOM\src\fortran\win 

* Compile and Link: wfl genl6 -explicit -d2 -windows -l=windows 

* -"op desc '16-bit DLL Test'" 

*$pragma aux (dll32_ call) indirect_ 1 parm( reference, value*4 ) 

*$pragma aux (dll32_ call) indirect_ 2 parm( reference, value*4 ) 
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integer*2 

& 

& 

& 

integer*2 

integer*2 

integer*4 

integer*2 


function FWinMain( hlnstance, 

hPrevInstance, 
IpszCmdLine, 
nCmdShow ) 

hlnstance 

hPrevInstance 

IpszCmdLine 

nCmdShow 


include 'windows.fi' 


integer*2 hlib 
integer*4 dll_ 1, dll_ 2 


character*128 str 

structure /args. 

_ 1/ 

integer 

wl 

integer 

w2 

integer 

w3 

integer 

sum 


end structure 


structure /args 
real 
real 
real 

end structure 

record /args_ 1/ args_ 1/111, 22222, 3333, 0/ 
record /args_ 2/ args_ 2/714.3, 35.7, 0.0/ 

hlib = LoadLibrary( 'windll.dll'c ) 
if( hlib .It. 32 ) then 

call MessageBox( NULL, 'Can''t load WINDLL'c, 

& ' Genl 6' c, MB_ OK ) 

stop 
endif 

dll_ 1 = GetProcAddress( hlib, 'DLLl'c ) 
dll_ 2 = GetProcAddress( hlib, 'DLL2'c ) 

call indirect_ 1 ( args_ 1, dll_ 1 ) 
write( str, '(15hDLL 1 returned , ilO, a)' ) 

& 

call MessageBox( NULL, str, 'Genl6 Test l'c, 

call indirect_ 2 ( args_ 2, dll_ 2 ) 
write( str, ' (15hDLL 2 returned , fl0.2, a)' ) args_ 2. sum, 
& char(O) 

call MessageBox( NULL, str, 'Genl6 Test 2'c, MB_ OK ) 

FWinMain = 0 


args_ 1.sum, 
char (0) 

MB_ OK ) 


_ 2 / 
wl 
w2 
sum 


end 


The following example is a 32-bit Windows application that passes arguments to a 32-bit DLL using a 
structure. 

*$include winapi.fi 

* GEN32.FOR 

* Setup: set finclude=\WATCOM\src\fortran\win 

* Compile and Link: wfl386 gen32 -explicit -d2 -l=win386 

* Bind: wbind gen32 -n -D "32-bit DLL Test" 
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integer*2 

& 

& 

& 

integer*2 

integer*2 

integer*4 

integer*2 


function FWinMain( hlnstance, 

hPrevInstance, 
IpszCmdLine, 
nCmdShow ) 

hlnstance 

hPrevInstance 

IpszCmdLine 

nCmdShow 


include 'windows.fi' 


integer*2 hlib 

integer*4 dll_ 1 , dll_ 2 , cb 

character*128 str 


structure /args_ 1/ 
integer wl 

integer w2 

integer w3 

integer sum 

end structure 


structure /args_2/ 
real wl 

real w2 

real sum 

end structure 


record /args_ 1/ args_ 1/111, 22222, 3333, 0/ 
record /args_ 2/ args_ 2/714.3, 35.7, 0.0/ 

hlib = LoadLibrary( 'windll.dll'c ) 
if( hlib .It. 32 ) then 

call MessageBox( NULL, 'Can''t load WINDLL'c, 
& ' Gen32' c, MB_ OK ) 

stop 
endif 


dll_ 1 = GetProcAddress( hlib, 'DLLl'c ) 
dll_ 2 = GetProcAddress( hlib, 'DLL2'c ) 


cb = 

_ Calll6( dll_ 1, 

'p' C, 

loc (args_ 1) ) 


write( str, '(15hDLL 1 

returned , ilO, a)' ) 

args_ 1.sum. 

& 




char (0) 

call 

MessageBox( NULL, 

str. 

'Gen32 Test l'c. 

MB_ OK ) 

cb = 

_ Calll6( dll_ 2, 

'P' c. 

loc (args_ 2) ) 


write( str, '(15hDLL 2 

returned , fl0.2, a)' 

) args_ 2 . sum, 

& 




char(0) 

call 

MessageBox( NULL, 

str. 

'Gen32 Test 2'c, 

MB_ OK ) 


FWinMain = 0 
end 


21.6 Creating and Debugging Dynamic Link Libraries 

In the following sections, we will take you through the steps of compiling, linking, and debugging 32-bit 
Dynamic Link Libraries (DLLs). 

We will use example programs that are provided in source-code form in the Open Watcom F77 package. 

The files described in this chapter are located in the directory 

\WATC0M\ SAMPLES\FORTRAN\WIN\DLL . The following files are provided: 
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WINDLLV.FOR is the source code for a simple 32-bit DLL containing two library routines that 

use integer arguments to pass information. 

GEN16V.FOR is the source code for a generic 16-bit Windows application that calls functions 

in the "WINDLLV" 32-bit Windows DLL. 

GEN32V.FOR is the source code for a generic 32-bit Windows application that calls functions 

in the "WINDLLV" 32-bit Windows DLL. 

WINDLL.FOR is the source code for a simple 32-bit DLL containing two library routines that 

use structures to pass information. 

GEN16.FOR is the source code for a generic 16-bit Windows application that calls functions 

in the "WINDLL" 32-bit Windows DLL. 

GEN32.FOR is the source code for a generic 32-bit Windows application that calls functions 

in the "WINDLL" 32-bit Windows DLL. 

MAKEFILE is a makefile for compiling and linking the programs described above. 

21.6.1 Building the Applications 

To create the DLLs and test applications, we will use the WATCOM Open Watcom Make utility and the 
supplied makefile. 

Example: 

C>wmake -f makefile 

21.6.2 Installing the Examples under Windows 

Start up Microsoft Windows 3.x if you have not already done so. Add the GEN16V. EXE and 
GEN32V. EXE files to one of your Window groups using the Microsoft Program Manager. 

1. Select the "New..." entry from the "File" menu of the Microsoft Windows Program Manager. 

2. Select "Program Item" from the "New Program Object" window and press the "OK" button. 

3. Enter "16-bit DLL Test" as a description for the GEN16V program. Enter the full path to the 
GEN16V program as a command line. 

Example: 

Description: 16-bit DLL Test 

Command Line: c:\work\dll\genl6v.exe 

4. Enter "32-bit DLL Test" as a description for the GEN32V program. Enter the full path to the 
GEN32V program as a command line. 
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Example: 

Description: 32-bit DLL Test 

Command Line: c:\work\dll\gen32v.exe 

Use a similar procedure to install the GEN16 . EXE and GEN32 . EXE programs. 

21.6.3 Running the Examples 

Start the 16-bit application by double clicking on its icon. A number of message boxes are presented. You 
may wish to compare the output in each message box with the source code of the program to determine if 
the correct results are being obtained. Click on the "OK" button as each of them are displayed. 

Similarly, start the 32-bit application by double-clicking on its icon and observe the results. 

21.6.4 Debugging a 32-bit DLL 

The Open Watcom Debugger can be used to debug a DLL. To debug a 32-bit DLL, a "breakpoint" 
instruction must be inserted into the source code for the DLL at the "FWinMain" entry point. This is done 
using the "pragma" compiler directive. We have already added the breakpoint to the source code for the 
32-bit DLL. 


integer*2 function FWinMain( 


integer*2 

integer*2 

integer*4 

integer*2 


hlnstance 

hPrevInstance 

IpszCmdLine 

nCmdShow 


hlnstance, 
hPrevInstance, 
IpszCmdLine, 
nCmdShow ) 


include 'windows.fi' 


external Add3, Add2 
integer rc 

call Breakpoint 

rc = DefineDLLEntry ( 1, Add3, DLL_ DWORD, DLL_ DWORD, DLL_ DWORD, 
& DLL_ ENDLIST ) 

if( rc .ne. 0 )then 
FWinMain = 0 
return 
end if 


The pragma for "Breakpoint" is defined in the "WINAPI.FI" file. 

Start up Microsoft Windows 3.x if you have not already done so. Start the debugger by double-clicking on 
the Open Watcom Debugger icon. At the prompt, enter the path specification for the application. When 
the debugger has successfully loaded GEN32v, start execution of the program. When the breakpoint is 
encountered in the 32-bit DLL, the debugger is re-entered. The debugger will automatically skip past the 
breakpoint. 

From this point on, you can symbolically debug the 32-bit DLL. You might, for example, set breakpoints 
at the start of each DLL routine to debug each of them as they are called. 
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21.6.5 Summary 

Note that the "FWinMain" entry point is only called once, at the start of any application requesting it. After 
this, the "FWinMain" entry point is no longer called. You may have to restart Windows to debug this 
section of code a second or third time. 
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22 Interfacing Visual Basic and Open Watcom 
FORTRAN 77 DLLs 


22.1 Introduction to Visual Basic and DLLs 


This chapter describes how to interface Microsoft Visual Basic 3.0 applications and 32-bit Dynamic Link 
Libraries (DLLs) created by Open Watcom FORTRAN 77. It describes how to write functions for a 32-bit 
DLL, how to compile and link them, and how to call these functions from Visual Basic. One of the 
proposed techniques involves the use of a set of cover functions in a 16-bit DLL so, indirectly, this chapter 
also describes interfacing to 16-bit DLLs. 

It is possible to invoke the Win38 6LibEntry function (Open Watcom’s 32-bit function entry point, 
described below) directly from Visual Basic. However, this technique limits the arguments that can be 
passed to a 32-bit DLL. The procedure and problems are explained below. 

To work around the problem, a 16-bit DLL can be created, that covers the 32-bit DLL. Within the 16-bit 
DLL, we will place cover functions that will call the corresponding 32-bit function in the 32-bit DLL. We 
illustrate the creation of the 16-bit DLL using the 16-bit C compiler in Open Watcom C/C++. 

Before we begin our example, there are some important technical issues to consider. 

The discussion in this chapter assumes that you, the developer, have a working knowledge of Visual Basic, 
including how to bring up the general declarations screen, how to create command buttons, and how to 
associate code with command buttons. You must use Visual Basic 3.0 or later. Visual Basic Version 2.x 
will not work because of a deficiency in this product regarding the calling of functions in DLLs. 

For the purposes of the following discussion, you should have installed the 32-bit version of Open Watcom 
FORTRAN 77, as well as version 3.0 or later of Visual Basic. If you also have the 16-bit Open Watcom C 
compiler, you can use this to create a 16-bit DLL containing the 16-bit cover functions. Ensure that the 
PATH amd FINCLLTDE environment variables are defined to include at least the directories indicated. 

We have assumed that Open Watcom FORTRAN 77 is installed in the c : \watcom directory, and Visual 
Basic is in the c:\vb directory: 

set path=c:\watcom\binw;c:\vb;c:\dos;c:\windows 
set finclude=c:\watcom\src\fortran\win 

Open Watcom’s 32-bit DLL supervisor contains a general entry point for Windows applications to call into 
called Win386LibEntry. It also contains 128 specific entry points called DLL1 to DLL128 which 
correspond to the entry points established via Def ineDLLEntry (the first argument to 
Def ineDLLEntry is an index number in the range 1 to 128). All applications call into the 32-bit DLL 
via these entry points. They build the necessary stack frame and switch to the 32-bit DLL’s data space. 

If you call via Win386LibEntry then you pass the DLL entry point number or index (1 to 128) as the 
last argument. Win3 8 6LibEntry uses this index number to call the appropriate 32-bit DLL routine. 

In many languages and programs (such as C and Microsoft Excel), function calls are very flexible. In other 
words, a function can be called with different argument types each time. This is generally necessary for 
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calling Win38 6LibEntry in a 32-bit extended DLL function. The reason is that this function takes the 
same arguments as the function being called, as well as the index number of the called function. After the 
32-bit flat model has been set up, Win38 6LibEntry then calls this function. In Visual Basic, once a 
function is declared as having certain arguments, it cannot be redeclared. For example, suppose we have a 
declaration as follows: 

Example: 

Declare Function Win386LibEntry Lib "c:\path\vbdll32.dll" 

=> (ByVal vl As Long, ByVal v2 As Long, ByVal 

=> v3 As Long, ByVal I As Integer) As Long 

(Note: the => means to continue the statement on the same line.) In this example, we could only call a 
function in any 32-bit extended DLL with three 32-bit integers as arguments. There are three ways to work 
around this deficiency in Visual Basic: 

1. Use the Visual Basic "Alias" attribute to declare Win38 6LibEntry differently for each DLL 
routine. Reference the different DLL routines using these aliases. 

2. Use the specific entry point, one of DLL1 through DLL128, corresponding to the DLL routine 
that you want to call. Each entry point can be described to take different arguments. We can 
still use the "Alias" attribute to make the link between the name we use in the Visual Basic 
function and the name in the 32-bit extended DLL. This is the method that we will use in the 
"Direct Call" technique discussed below. It is simpler to use since it requires one less argument 
(you don't require the index number). 

3. Use a method which involves calling functions in a 16-bit "cover" DLL written in a 
flexible-argument language, which then calls the functions in the 32-bit DLL. This is the 
"Indirect Call" method discussed below. 


22.2 A Working Example 

The best way to demonstrate these techniques is through an example. This example consists of a Visual 
Basic application with 3 push buttons. The first push button invokes a direct call to a 32-bit DLL which 
will display a message window with its arguments, the second push button invokes an indirect call to the 
same function through a 16-bit DLL, and the third button exits the Visual Basic application. 

To create a Visual Basic application: 

(1) Start up a new project folder from the "File" menu. 

(2) Select "View Form" from the "Project" window. 

(3) Draw three command buttons on the form by selecting command buttons from the "Toolbox" 
window. 

(4) Change the caption on each button. To do this, highlight the first button. Then, open the 
"Properties" window. Double click on the "Caption window", and change the caption to "Direct call". 
Highlight the second button, and change its caption to "Indirect call". Highlight the third, changing 
the caption to "Exit". 

Now, your Visual Basic application should have three push buttons, "Direct call", "Indirect call", and 
"Exit". 
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(5) Double click on the "Direct Call" button. 

An edit window will pop up. Enter the following code: 

Sub Commandl_ Click () 

Dim varl, var2, var3, worked As Long 

varl = 230 
var2 = 215 
var3 = 32 

worked = Add3(varl, var2, var3) 

Print worked 

worked = Add2(var2, var3) 

Print worked 
End Sub 

(6) Double click on the "Indirect Call" button. 

Another edit window will pop up. Enter the following code: 

Sub Command2_ Click () 

Dim varl, var2, var3, worked As Long 

varl = 230 
var2 = 215 
var3 = 32 

worked = Functionl(varl, var2, var3) 

Print worked 

worked = Function2(var2, var3) 

Print worked 
End Sub 

(7) Double click on the "Exit" command button and enter the following code in the pop-up window: 

Sub Command3_ Click () 

End 
End Sub 

(8) Select "View Code" from the "Project" window. To interface these Visual Basic functions to the 
DLLs, the following code is needed in the 

Object: [general] Proc: [declarations] 

section of the code. This code assumes that VBDLL32 . DLL and COVER1 6 . DLL are in the 
c : \path directory. Modify the pathnames appropriately if this is not the case. (Note: the => means 
to continue the statement on the same line.) 
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Declare Function Functionl Lib "c:\path\coverl6.dll" 

=> (ByVal vl As Long, ByVal v2 As Long, ByVal v3 As Long) 

=> As Long 

Declare Function Function2 Lib "c:\path\coverl6.dll" 

=> (ByVal vl As Long, ByVal v2 As Long) As Long 

Declare Function Add3 Lib "c:\path\vbdll32.dll" 

=> Alias "DLL1" 

=> (ByVal vl As Long, ByVal v2 As Long, ByVal v3 As Long) 

=> As Long 

Declare Function Add2 Lib "c:\path\vbdll32.dll" 

=> Alias "DLL2" 

=> (ByVal vl As Long, ByVal v2 As Long) As Long 

Now, when all of the code below is compiled correctly, and the Visual Basic program is run, the "Direct 
call" button will call the DLL1 and DLL2 functions directly, aliased as the functions Add3 and Add2 
respectively. The "Indirect call" button will call the 16-bit DLL, which will then call the 32-bit DLL, for 
both Functionl and Function2 . To run the Visual Basic program, select "Start" from the "Run" 
menu. 


22.3 Sample Visual Basic DLL Programs 

The sample programs provided below are for a 32-bit DLL, and a 16-bit cover DLL, which will call the two 
functions contained in the 32-bit DLL. 


22.3.1 Source Code for VBDLL32.DLL 

*$include winapi.fi 

* VBDLL32.FOR 

* Setup: set finclude=\WATCOM\src\fortran\win 

* Compile and Link: wfl386 vbdll32 -explicit -d2 -bd -l=win386 

* Bind: wbind vbdll32 -d -n 

*$pragma aux (dll_ function) Add3 

integer function Add3( wl, w2, w3 ) 
integer wl, w2, w3 

include 'windows.fi' 

character*128 str 

write( str, '(16hDLL 1 

& 

call MessageBox( NULL, 

Add3 = wl + w2 + w3 


arguments:, 3il0, a)' ) wl, w2, w3, 

char(0) 

str, 'F77 VBDLL32'c, MB_ OK ) 


end 
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*$pragma aux (dll_ function) Add2 


integer function Add2( wl, w2 ) 
integer wl, w2 

include 'windows.fi' 

character*128 str 


write( str, '(16hDLL 2 arguments:, 2il0, a)' ) wl, w2, char(O) 
call MessageBox( NULL, str, 'F77 VBDLL32'c, MB_ OK ) 

Add2 = wl + w2 

end 


integer*2 


integer*2 

integer*2 

integer*4 

integer*2 


function FWinMain( hlnstance, 

hPrevInstance, 
IpszCmdLine, 
nCmdShow ) 

hlnstance 

hPrevInstance 

IpszCmdLine 

nCmdShow 


include 'windows.fi' 


external Add3, Add2 
integer rc 


rc = DefineDLLEntry ( 1, Add3, DLL_ DWORD, DLL_ DWORD, DLL_ DWORD, 
& DLL_ ENDLIST ) 

if( rc .ne. 0 )then 
FWinMain = 0 
return 
end if 

rc = DefineDLLEntry ( 2, Add2, DLL_ DWORD, DLL_ DWORD, 

& DLL_ ENDLIST ) 

if( rc .ne. 0 )then 
FWinMain = 0 
return 
end if 

call MessageBox( NULL, '32-bit DLL started'c, 

& ' F77 VBDLL32'c, MB_ OK ) 

FWinMain = 1 


end 


22.3.2 Source code for C0VER16.DLL 

The functions in this 16-bit DLL will call the functions in the 32-bit DLL, VBDLL32 . DLL, shown above, 
with the appropriate Win38 6LibEntry call for each function. 

/* 

* COVERl6.C 
*/ 

♦include <stdio.h> 

#include <windows.h> /* required for all Windows applications */ 

typedef long (FAR PASCAL *FPROC)(); 

FPROC DLL_ 1; 

FPROC DLL_ 2; 
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long FAR PASCAL_export Functionl ( long varl, 

long var2, 
long var3 ) 

{ 

return ( (long) DLL_ 1 ( varl, var2, var3 ) ); 

} 


long FAR PASCAL _export Function2( long varl, long var2 ) 

{ 

return ( (long) DLL_ 2 ( varl, var2 ) ); 

} 


#pragma off (unreferenced); 

BOOL FAR PASCAL LibMain( HANDLE hlnstance, WORD wDataSegment, 

WORD wHeapSize, LPSTR IpszCmdLine ) 
#pragma on (unreferenced); 

{ 

HANDLE hlib; 

/* Do our DLL initialization */ 
hlib = LoadLibrary( "vbdll32.dll" ); 
if( hlib < 32 ) { 

MessageBox( NULL, 

"Make sure your PATH contains VBDLL32.DLL", 
"C0VER16", MB_ OK | MB_ ICONEXCLAMATION ); 
return( FALSE ); 

} 

DLL_ 1 = (FPROC) GetProcAddress( hlib, "DLL1" ); 

DLL_ 2 = (FPROC) GetProcAddress( hlib, "DLL2" ); 
return ( TRUE ); 

} 


22.4 Compiling and Linking the Examples 

To create the 32-bit DLL VBDLL32 . DLL, type the following at the command line (make sure that 
VBDLL32 . for is in your current directory): 

set finclude=c:\watcom\src\fortran\win 

wfl386 vbdll32 -explicit -bd -d2 -l=win386 

wbind vbdll32 -d -n 

To create the 16-bit DLL C0VER16 . DLL, type the following at the command line (make sure that 
C0VER16 . C are in your current directory): 

wcl cover16 -me -bt=windows -bd -zu -d2 -l=windows_ dll 
Notes: 

1. An object file is provided for C0VER16 . C if you do not have access to the 16-bit Open Watcom 
C compiler. In this case, the DLL can be generated from the object file using the following 
command: 

wfl coverl6.obj -d2 -l=windows_ dll 

2. The "me" option selects the compact memory model (small code, big data). The code for 16-bit 
DLLs must be compiled with one of the big data models. 

3. The "bd" option indicates that a DLL will be created from the object files. 

4. The "bt" option selects the "windows" target. This option causes the C or C++ compiler to 
generate Windows prologue/epilogue code sequences which are required for Microsoft Windows 
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applications. It also causes the compiler to use the WINDOWS_INCLUDE environment 
variable for header file searches. It also causes the compiler to define the macro 
_WINDOWS _and, for the 32-bit C or C++ compiler only, the macro_ WINDOWS_ 38 6_ . 

5. The "zu" option is used when compiling 16-bit code that is to be placed in a Dynamic Link 
Library (DLL) since the SS register points to the stack segment of the calling application upon 
entry to the function. 

6. The "d2" option is used to disable optimizations and include debugging information in the object 
file and DLL. The techniques for debugging DLLs are described in the chapter entitled 
"Windows 32-Bit Dynamic Link Libraries" on page 139. 

You are now ready to run the Visual Basic application. 
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23 WIN386 Library Subprograms 


Each special Windows subprogram in the Open Watcom F77 library is described in this chapter. Each 
description consists of a number of subsections: 

Synopsis: This subsection gives the include files that should be included within a source file that references the 
subprogram. It also shows an appropriate declaration for the function or for a function that could be 
substituted for a macro. This declaration is not included in your program; only the include file(s) should be 
included. 

Description: This subsection is a description of the subprogram. 

Returns: This subsection describes the return value (if any) for the subprogram. 

See Also: This optional subsection provides a list of related subprograms. 

Example: This optional subsection consists of one or more examples of the use of the subprogram. The examples are 
often just fragments of code (not complete programs) for illustration purposes. 

Classification: This subsection provides an indication of where the subprogram is commonly found. The subprograms 
in this section are all classified as "WIN386" (i.e., they pertain to 32-bit Windows programming). 
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AllocAlias16 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 


c$include 'winapi.fi' 

integer*4 function AllocAliasl6( ptr ) 
integer*4 ptr 

The AllocAliasl6 function obtains a 16-bit far pointer equivalent of a 32-bit near pointer. These 
pointers are used when passing data pointers to Windows through functions that have INTEGER*4 
arguments, and for any pointers within data structures passed this way. 

The AllocAliasl6 function returns a 16-bit far pointer (as an INTEGER*4) usable by Windows, or 
returns 0 if the alias cannot be allocated. 

FreeAliasl6 

integer*4 mcs_16 

record /MDICREATESTRUCT/ mcs 

mcs.szTitle = AllocAliasl6( loc( 'Title'c ) ) 

mcs.szClass = AllocAliasl6( loc( 'mdichild'c ) ) 

mcs.hOwner = hlnst 

mcs.x = mcs.cx = CW_ USEDEFAULT 

mcs.y = mcs.cy = CW_ USEDEFAULT 

mcs.style = 0 

! Send a message to an MDI client to create a window. 

! Since the pointer to the structure is passed in an 

! argument that may not be a pointer (depending on the 

! type of message), there is no implicit 32 to 16-bit 

! conversion done so the conversion must be done by the 
! programmer. 

mcs_16 = AllocAliasl6( loc( mcs ) ) 

hwnd = SendMessage ( hwndMDI, WM_ MDI CREATE, 0, mcs_16 ) 
FreeAliasl6( mcs_ 16 ) 

FreeAliasl6( mcs.szClass ) 

FreeAliasl6( mcs.szTitle ) 

WIN386 
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AllocHugeAlias16 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 


c$include 'winapi.fi' 

integer*4 function AllocHugeAliasl6( ptr, size ) 
integer*4 ptr, size 

The AllocHugeAliasl6 function obtains a 16-bit far pointer to a 32-bit memory object that is size bytes 
in size. This is similar to the function AllocAliasl 6, except that AllocAliasl 6 will only give 
16-bit far pointers to 32-bit memory objects of up to 64K in size. To get 16-bit far pointers to 32-bit 
memory objects larger than 64K, AllocHugeAliasl 6 should be used. 

The AllocHugeAliasl6 function returns a 16-bit far pointer (as an INTEGER*4) usable by Windows, or 
returns 0 if the alias cannot be allocated. 

AllocAliasl6, FreeAliasl6, FreeHugeAliasl6 

integer ierr, SIZE 
integer*4 alias 
parameter (SIZE=300000) 
integer*! tmp(SIZE) 


allocate ( tmp(SIZE), stat=ierr ) 
if ( ierr ,ne. 0 )then 

alias = AllocHugeAliasl6( loc( tmp ), SIZE ) 

! Windows calls using the alias ... 

call FreeHugeAliasl6( alias, SIZE ) 
endif 

WIN386 
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Call16 


Synopsis: c$include 'winapi.fi' 

integer*4 function _Calll6( lpFunc, fmt, ... ) 
integer*4 lpFunc 
character*(*) fmt 

Description: The _Calll6 function performs the same function as GetlndirectFunctionHandle, 

InvokelndirectFunctionHandle and FreelndirectFunctionHandle but is much 
easier to use. The first argument lpFunc is the address of the 16-bit function to be called. This address 
is usually obtained by calling GetProcAddress with the name of the desired function. The second 
argument fmt is a string identifying the types of the parameters to be passed to the 16-bit function. 

Character Parameter Type 

c call a ’cdecl’ function as opposed to a ’pascal’ function (if specified, it must be listed 

first) 

h unsigned BYTE 

w 16-bit WORD (INTEGER*2) 

d 32-bit DWORD (INTEGER*4, REAL*4) 

/ double precision floating-point (DOUBLE PRECISION, REAL*8) 

p 32-bit flat pointer (converted to 16:16 far pointer) (LOC(x)) 

The 16-bit function must use either the PASCAL or CDECL calling convention. PASCAL calling 
convention is the default. If the function uses the CDECL calling convention, then you must specify the 
letter "c" as the first character of the argument type string. 

Pointer types will automatically be converted from 32-bit near pointers to 16-bit far pointers before the 
function is invoked. Note that this pointer is only valid over the period of the call; after control returns 
to the 32-bit application, the 16-bit pointer created by the Supervisor is no longer valid. 

Returns: The _Calll6 function returns a 32-bit DWORD (as an INTEGER*4) which represents the return value 

from the 16-bit function that was called. 

See Also: GetlndirectFunctionHandle, FreelndirectFunctionHandle 

Example: c$include winapi.fi 

include 'windows.fi' 
integer*2 hlib 
integer*4 dll_l, cb 
character*128 str 

hlib = LoadLibrary( 'windllv.dll'c ) 
dll_ 1 = GetProcAddress( hlib, 'DLLl'c ) 

cb = _ Call16( dll_ 1, 'ddd'c. 111, 22222, 3333 ) 

Classification: WIN386 
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DefineDLLEntry 


Synopsis: 

Description: 


Returns: 

Example: 


c$include 'winapi.fi' 

integer*4 function DefineDLLEntry(index, routine, ...) 
integer*4 index 
external routine 


The DefineDLLEntry function defines an index number for the 32-bit DLL procedure routine. The 
parameter index defines the index number that must be used in order to invoke the 32-bit FAR 
procedure routine. The variable argument list defines the types of parameters that will be received by 
the 32-bit DLL routine. Valid parameter types are: 


DLL_PTR 

DLL_DWORD 

DLLJWORD 

DLLJCHAR 

DLL_ENDLIST 


16-bit far pointer 
32-bits 
16-bits 
8-bits 

Marks the end of the variable argument list. 


In the above synopsis, in the argument list is not valid FORTRAN 77 syntax; it is used only to 
indicate a variable number of arguments. 


Note that all pointers are received as 16-bit far pointers. To access the data from the 32-bit DLL, a 
dynamically allocatable array must be mapped to the memory pointed to by the 16-bit far pointer using 
the LOCATION specifier of the ALLOCATE statement and assigning the FAR attribute to the array using 
the array pragma. 


The DefineDLLEntry function returns zero if successful, and a non-zero value otherwise. 


c$include winapi.fi 

cSpragma aux (dll_ function) DLL_ 1 

integer function DLL_ 1( wl, w2, w3 ) 
integer*4 wl, w2, w3 
include 'win386.fi' 
include 'windefn.fi' 
include 'winerror.fi' 
character*128 str 

write! str, ' (16hDLL 1 arguments:, 3il0, a)' ) wl, 

& w2, w3, char (0) 

call MessageBox( NULL, str, 

& 'DLL Function l'c, MB_ OK ) 

DLL_ 1 = wl + w2 + w3 
end 

integer*2 function FWINMAIN( hlnstance, 

& hPrevInstance, 

& IpszCmdLine, 

& nCmdShow ) 

integer*2 hlnstance, hPrevInstance, nCmdShow 

integer*4 IpszCmdLine 

include 'win386.fi' 

include 'windefn.fi' 

include 'winerror.fi' 

external DLL_ 1 

integer rc 

rc = DefineDLLEntry! 1, DLL_1, DLL_ DWORD, 
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DefineDLLEntry 


& 

& 


& 

& 


if( rc .ne. 0 )then 
FWinMain = 0 


DLL 

DLL 


return 
end if 

call MessageBox( 


NULL, 

'32-bit 
'32-bit 


FWinMain = 1 
end 


Classification: WIN386 


DWORD, DLL_ DWORD, 
ENDLIST ) 


DLL started'c, 
DLL' c, MB_ OK ) 
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DefineUserProcW 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


*$include 'winapi.fi' 

integer*4 function DefineUserProcl6(typ, routine, ...) 
integer*4 typ 
external routine 


The DefineUserProcl6 function defines the arguments accepted by the user defined callback procedure 
routine. There may be up to 32 user defined callbacks. The parameter typ indicates which one of 
GETPROC_ USERDEFINED_ 1 througlGETPROC_ USERDEFINED_ 32 is being defined (see 
GetProcl 6). The callback routine must be declared as FAR PASCAL, or as FAR cdecl. The 
variable argument list defines the types of parameters that will be received by the user defined callback 
procedure routine. Valid parameter types are: 


UDP16_PTR 
UDP16_D WORD 
UDP16WORD 
UDP16CIIAR 
UDP16_CDECL 

UDP16_ENDLIS T 


16-bit far pointer 

32-bits 

16-bits 

8-bits 

callback routine will be declared as type cdecl rather than as type PASCAL. 
This keyword may be placed anywhere before the UDP16_ ENDLIST 
keyword. 

Marks the end of the variable argument list. 


Once the DefineUserProcl6 function has been used to declare the user callback routine, then 
GetProcl 6 may be used to get a 16-bit function pointer that may be used by Windows. 

In the above synopsis, "..." in the argument list is not valid FORTRAN 77 syntax; it is used only to 
indicate a variable number of arguments. 

The DefineUserProcl6 function returns zero if it succeeds; and non-zero if it fails. 


GetProcl6 
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DefineUserProc16 


c$include winapi.fi 

cSpragma aux TestProc parm( value ) 

subroutine TestProc( i ) 
integer i 
character*128 str 

write( str, ' (2hi=, ilO, a)' ) i, char(O) 

call MessageBox( NULL, str, 'TEST'c, MB_ OK ) 
end 

integer function DefineTestO 
integer*4 cb 
external TestProc 

call DefineUserProcl6 ( GETPROC_ USERDEFINED_ 1, 

& TestProc, 

& UDP16_ DWORD, 

& UDP16_ ENDLIST ) 

cb = GetProcl6 ( TestProc, GETPROC_ USERDEFINED_ 1 ) 
! cb may then be used whenever a pointer to the 
! callback is required by 16-bit Windows 
end 


Classification: WIN386 
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FreeAlias16 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 


c$include 'winapi.fi' 

subroutine FreeAliasl6( fpl6 ) 
integer*4 fpl6 

FreeAliasl6 frees a 16-bit far pointer alias for a 32-bit near pointer that was allocated with 
AllocAliasl6. This is important to do when there is no further use for the pointer since there are a 
limited number of 16-bit aliases available (due to limited space in the local descriptor table). 

FreeAliasl6 is a subroutine. 

AllocAliasl6 

integer*4 mcs_16 

record /MDICREATESTRUCT/ mcs 

mcs.szTitle = AllocAliasl6( loc ( 'Title'c ) ) 

mcs.szClass = AllocAliasl6( loc( 'mdichild'c ) ) 

mcs.hOwner = hlnst 

mcs.x = mcs.cx = CW_ USEDEFAULT 

mcs.y = mcs.cy = CW_ USEDEFAULT 

mcs.style = 0 

! Send a message to an MDI client to create a window. 

! Since the pointer to the structure is passed in an 

! argument that may not be a pointer (depending on the 

! type of message), there is no implicit 32 to 16-bit 

! conversion done so the conversion must be done by the 
! programmer. 

mcs_16 = AllocAliasl6( loc( mcs ) ) 

hwnd = SendMessage ( hwndMDI, WM_ MDI CREATE, 0, mcs_16 ) 

FreeAliasl6( mcs_16 ) 

FreeAliasl6( mcs.szClass ) 

FreeAliasl6( mcs.szTitle ) 

WIN386 
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FreeHugeAlias16 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 


c$include 'winapi.fi' 

subroutine FreeHugeAliasl6( fpl6, size ) 
integer*4 fpl6, size 

FreeHugeAliasl6 frees a 16-bit far pointer alias that was allocated with AllocHugeAliasl6. The 
size of the original 32-bit memory object must be specified. It is important to use 
FreeHugeAliasl 6 when there is no further use for the pointer, since there are a limited number of 
16-bit aliases available (due to limited space in the local descriptor table). 

FreeHugeAliasl6 is a subroutine. 

AllocHugeAliasl6, AllocAliasl6, FreeAliasl6 

integer ierr, SIZE 
integer*4 alias 
parameter (SIZE=300000) 
integer*! tmp(SIZE) 


allocate ( tmp(SIZE), stat=ierr ) 
if ( ierr ,ne. 0 )then 

alias = AllocHugeAliasl6( loc( tmp ), SIZE ) 

! Windows calls using the alias ... 

call FreeHugeAliasl6( alias, SIZE ) 
endif 

WIN386 
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FreelndirectFunctionHandle 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 


c$include 'winapi.fi' 

subroutine FreelndirectFunctionHandle( handle ) 
integer*4 handle 

FreelndirectFunctionHandle frees a handle that was obtained using 

GetlndirectFunctionHandle. This is important to do when there is no further use for the 
pointer since there are a limited number of 16-bit aliases available (due to limited space in the local 
descriptor table). 

FreelndirectFunctionHandle is a subroutine. 

_ Calll6,GetIndirectFunctionHandle, InvokelndirectFunction 

c$include winapi.fi 

integer*2 hDrv 
integer*4 lpfn 

hDrv = LoadLibrary( 'your.lib'c ) 
if( hDrv .It. 32 ) return 
lpfn = GetProcAddress( hDrv, 

& 'ExtDeviceMode'c ) 

if( lpfn .eq 0 ) return 

hlndir = GetlndirectFunctionHandle( 


& 

lpfn. 


& 

INDIR_ 

WORD, 

& 

INDIR_ 

WORD, 

& 

INDIR_ 

DWORD, 

& 

INDIR_ 

PTR, 

& 

INDIR_ 

PTR, 

& 

INDIR_ 

DWORD, 

& 

INDIR_ 

DWORD, 

& 

INDIR_ 

WORD, 

& 

INDIR_ 

ENDLIST ) 

cb = 

InvokelndirectFunction( 

& 

hlndir 

t 

& 

hwnd. 


& 

hDrv, 


& 

NULL, 


& 

'POSTSCRIPT PRINTER 

& 

'LPT1' 

c. 

& 

NULL, 


& 

NULL, 


& 

0 ) 



call FreelndirectFunctionHandle( hlndir ) 

WIN386 
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GetlndirectFunctionHandle 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


c$include 'winapi.fi' 

integer*4 function GetlndirectFunctionHandle( prc, ... ) 
integer*4 prc 


The GetlndirectFunctionHandle function gets a handle for a 16-bit procedure that is to be invoked 
indirectly. The procedure is assumed to have PASCAL calling convention, unless the INDIR_ CDECL 
parameter is used, to indicate that Microsoft C calling convention is to be used. The 16-bit far pointer 
prc is supplied to GetlndirectFunctionHandle, and a list of the type of each parameter (in the order that 
they will be passed to the 16-bit function). The parameter types are: 


INDIR_D WORD 
INDIRWORD 
INDIRCIIAR 
INDIR_PTR 

INDIRJCDECL 

INDIR_ENDLIST 


A INTEGER*4 will be passed. 

A INTEGER*2 will be passed. 

A INTEGER* 1 will be passed. 

A pointer will be passed. This is only used if pointer conversion from 32-bit 
to 16-bit is required, otherwise; INDIR_DWORD is specified. 

This option may be included anywhere in the list before the 

INDIR_ ENDLIST keyword. When this is used, the calling convention used 

to invoke the 16-bit function will be the Microsoft C calling convention. 

Marks the end of the parameter list. 


In the above synopsis, "..." in the argument list is not valid FORTRAN 77 syntax; it is used only to 
indicate a variable number of arguments. 


This handle is a data structure that was created using the mal loc function. To free the handle, just use 
one of the FreelndirectFunctionHandle or free functions. 


You may find it easier to use _ Cal 116 rather than GetlndirectFunctionHandle followed by a call to 
InvokeIndirectFunction. 


The GetlndirectFunctionHandle function returns a handle to the indirect function, or NULL if a handle 
could not be allocated. This handle is used in conjunction with InvokelndirectFunction to call 
the 16-bit procedure. 

_ Calll6,FreeIndirectFunctionHandle, InvokelndirectFunction 
c$include winapi.fi 


integer*2 hDrv 
integer*4 lpfn 


hDrv = LoadLibrary( 'your.lib'c ) 
if( hDrv .It. 32 ) return 
lpfn = GetProcAddress( hDrv, 

& ' ExtDeviceMode'c ) 

if( lpfn .eq 0 ) return 
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GetlndirectFunctionHandle 


hlndir 

& 

& 

& 

& 

& 

& 

& 

& 

& 

& 


GetlndirectFunctionHandle ( 
Ipfn, 

INDIR_ WORD, 

INDIR_ WORD, 

INDIR_ DWORD, 

INDIR_ PTR, 

INDIR_ PTR, 

INDIR_ DWORD, 

INDIR_ DWORD, 

INDIR_ WORD, 

INDIR_ ENDLIST ) 


cb = 

& 

& 

& 

& 

& 

& 

& 

& 

& 

call 


InvokelndirectFunction( 
hlndir, 
hwnd, 
hDrv, 

NULL, 

'POSTSCRIPT PRINTER'c, 

'LPT1'c, 

NULL, 

NULL, 

0 ) 

FreelndirectFunctionHandle( hlndir 


) 


Classification: WIN386 


WIN386 Library Subprograms 171 




GetProc16 


Synopsis: c$include 'winapi.fi' 

integer*4 function GetProcl6( fen, type ) 
integer*4 fen, type 

Description: The GetProcl6 function returns a 16-bit far function pointer suitable for use as a Windows callback 

function. This callback function will invoke the 32-bit far procedure specified by fen. The types of 

callback functions that may be allocated are: 

GETPROC JCALLBACK This is the most common form of callback; suitable as the callback routine 
for a window. 

GETPROC_ABORTPROC This is the callback type used for trapping abort requests when printing. 

GETPROC_ENUMCHILDWINDOWS This callback is used with the EnumChildWindows 
Windows function. 

GETPROC_ENUMFONTS This callback type is used with the EnumFonts Windows function. 

GETPROC_ENUMMETAFILE This callback is used with the EnumMetaFile Windows function. 

GETPROC_ENUMOBJECTS This callback is used with the EnumOb jects Windows function. 

GETPROC_ENUMPROPS_FIXED_DS This callback is used with the EnumProps Windows 
function, when the fixed data segments callback is needed. 

GETPROC_ENUMPROPS_MOVEABLE_DS This callback is used with the EnumProps Windows 
function, when the moveable data segments callback is needed. 

GETPROC_ENUMTASKWINDOWS This callback is used with the EnumTaskWindows Windows 
function. 

GETPROC_ENUMWINDOWS This callback is used with the EnumWindows Windows function. 

GETPROCJGLOBALNOTIFY This callback is used with the GlobalNotify Windows function. 

GETPROCJGRAYSTRING This callback is used with the GrayString Windows function. 

GETPROC_LINEDDA This callback is used with the LineDDA Windows function. 

GETPROCJSETRESOURCEHANDLER This callback is used with the SetResourceHandler 
Windows function. 

GETPROCJSETTIMER This callback is used with the SetTimer Windows function. 

GETPROC_SETWINDOWSHOOK This callback is used with the SetWindowsHook Windows 
function. 

GETPROC_USERDEFINED_x This callback is used in conjunction with Def ineUserProcl 6 
function to create a callback routine with an arbitrary set of parameters. Up to 32 user 
defined callbacks are allowed, they are identified by using 

GETPROC_USERDEFINED_ 1 through GETPROC_USERDEFINED_32. The user 
defined callback must be declared as a FAR PASCAL function, or as a FAR cdecl 
function. 
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GetProc16 


Returns: 

See Also: 
Example: 


Classification: 


The GetProcl6 function returns a 16-bit far pointer to a callback procedure. This pointer may then be 
fed to any Windows function that requires a pointer to a function within the 32-bit program. Note that 
the callback function within the 32-bit program must be declared as FAR. 

Re lea seP rod 6 

c$include winapi.fi 

integer*4 cbp 
integer*4 IpProcAbout 

! get a 16-bit callback routine to point at 
! our About dialogue procedure, then create 
! the dialogue. 

cbp = GetProcl6 ( About, GETPROC_ CALLBACK ) 

IpProcAbout = MakeProcInstance( cbp, hlnst ) 
call DialogBox( hlnst, 

& 'AboutBox'c, 

hWnd, 

IpProcAbout ) 

call FreeProcInstance( IpProcAbout ) 
call ReleaseProcl6( cbp ) 

WIN386 


WIN386 Library Subprograms 173 





InvokelndirectFunction 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 


c$include 'winapi.fi' 

integer*4 function InvokelndirectFunction(handle, ...) 
integer*4 handle 

The InvokelndirectFunction function invokes the 16-bit function pointed to by the specified handle. 
The handle must have been previously allocated using the GetlndirectFunctionHandle 
function. The handle is followed by the list of parameters to be passed to the 16-bit function. 

If you specified INDIR_ PTR as a parameter when allocating the handle, then a 16-bit pointer is 
allocated for a 32-bit pointer that you pass. However, this pointer is freed when the 16-bit function 
being invoked returns. 

In the above synopsis, "..." in the argument list is not valid FORTRAN 77 syntax; it is used only to 
indicate a variable number of arguments. 

The InvokelndirectFunction function returns the value which the 16-bit function returned. 


Cal116,FreeIndirectFunctionHandle, GetlndirectFunctionHandle 


c$include winapi.fi 

integer*2 hDrv 
integer*4 lpfn 

hDrv = LoadLibrary( 'your.lib'c ) 
if( hDrv .It. 32 ) return 
lpfn = GetProcAddress( hDrv, 

& 'ExtDeviceMode'c ) 

if( lpfn .eq 0 ) return 


hlndir 

& 

& 

& 

& 

& 

& 

& 

& 

& 

& 


GetlndirectFunctionHandle ( 
lpfn, 

INDIR_ WORD, 

INDIR_ WORD, 

INDIR_ DWORD, 

INDIR_ PTR, 

INDIR_ PTR, 

INDIR_ DWORD, 

INDIR_ DWORD, 

INDIR_ WORD, 

INDIR_ ENDLIST ) 


cb = 

& 

& 

& 

& 

& 

& 

& 

& 

& 

call 


InvokelndirectFunction( 
hlndir, 
hwnd, 
hDrv, 

NULL, 

'POSTSCRIPT PRINTER'c, 

'LPT1'c, 

NULL, 

NULL, 

0 ) 

FreelndirectFunctionHandle( hlndir ) 


WIN386 
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MapAliasToFlat 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 


c$include 'winapi.fi' 

integer*4 function MapAliasToFlat( alias ) 
integer*4 alias 

The MapAliasToFlat function returns a 32-bit near pointer equivalent of a pointer allocated previously 
with AllocAliasl6 or AllocHugeAliasl6. This is useful if you are communicating with a 
16-bit application that is returning pointers that you previously gave it. 

The MapAliasToFlat function returns a 32-bit near pointer (as an INTEGER*4) usable by the 32-bit 
application. 

AllocAliasl6, AllocHugeAliasl6 

c$include winapi.fi 

integer alias 
integer ptr 

alias = AllocAliasl6( loc ( alias ) ) 

alias += 5 

ptr = MapAliasToFlat( alias ) 

if( ptr .eq. loc( alias ) + 5 )then 

call MessageBox( NULL, 'It Worked'c, ''c, MB_ OK ) 

else 

call MessageBox( NULL, 'It Failed'c, ''c, MB_ OK ) 
end if 


WIN386 
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PASS_ WORD_AS_POINTER 


Synopsis: c$include 'winapi.fi' 

integer*4 function PASS_ WORD_ AS_ POINTER ( dw ) 
integer*4 dw 

Description: Some Windows API functions have pointer parameters that do not always take pointers. Sometimes 

these parameters are pure data. In order to stop the supervisor from trying to convert the data into a 
16-bit far pointer, the PASS_WORD_AS_POINTER function is used. 

Returns: The PASS_WORD_AS_POINTER returns a 32-bit "near" pointer, that is really the parameter dw. 

Example: c$include winapi.fi 

call Func ( PASS_ WORD_ AS_ POINTER (1) ) 

Classification: WIN386 
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ReleaseProc16 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 


c$include 'winapi.fi' 

subroutine ReleaseProcl6( cbp ) 
integer*4 cbp 

ReleaseProcl6 releases the callback function allocated by GetProcl 6. Since the callback routines are 
a limited resource, it is important to release the routines when they are no longer required. 

ReleaseProcl6 is a subroutine. 

GetProcl6 

c$include winapi.fi 

integer*4 cbp 
integer*4 IpProcAbout 

! get a 16-bit callback routine to point at 
! our About dialogue procedure, then create 
! the dialogue. 

cbp = GetProcl6 ( About, GETPROC_ CALLBACK ) 

IpProcAbout = MakeProcInstance( cbp, hlnst ) 
call DialogBox( hlnst, 'AboutBox'c, 

& hWnd, IpProcAbout ) 

call FreeProcInstance( IpProcAbout ) 
call ReleaseProcl6( cbp ) 

WIN386 
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24 32-bit Extended Windows Application 
Development 


The purpose of this chapter is to anticipate some common questions about 32-bit Windows application 
development. 

The following topics are discussed in this chapter: 

• Can you call 16-bit code from a 32-bit Windows application? 

• How do I add my Windows resources? 

• All function pointers passed to Windows must be 16-bit far pointers, correct? 

• Why are 32-bit callback routines FAR? 

• Why use the _16 API functions? 

24.1 Can you call 16-bit code from a 32-bit Windows 
application? 

A 32-bit Windows application can make a call to 16-bit code through the use of the Open Watcom 
_ Calll6 orlnvokelndirectFunction procedures. These functions ensure that the Open Watcom 
Windows Supervisor prepares the stack for the 16-bit call and return to the 32-bit code. The 32-bit 
application uses LoadLibrary function to bring the 16-bit DLL into memory and then calls the 16-bit 
procedures. To invoke 16-bit procedures, use GetProcAddress to get the 16-bit far pointer to the 
function. Use the _ Cal 116 procedure to call the 16-bit function since it is simpler to use than the 
GetlndirectFunctionHandle, InvokelndirectFunction, and 
FreelndirectFunctionHandle sequence. An example of this process is provided under the 
_ Calll6 Windows library function description. 

This method can be used to call any 16-bit Dynamic Link Library (DLL) procedure or any 32-bit extended 
DLL procedure from within a 32-bit application, including DLLs that are available as products through 
Independent Software Vendors (ISVs). 

24.2 How do I add my Windows resources? 

The WBIND utility automatically runs the resource compiler to add the resources to the 32-bit Windows 
supervisor (since the supervisor is a 16-bit Windows application). Note that resource compiler options may 
be specified by using the "R" option of WBIND. 
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24.3 All function pointers passed to Windows must be 16-bit 
far pointers, correct? 

All function pointers passed to Windows must be 16-bit far pointers since no translation is applied to any 
function pointers passed to Windows. Translation is often not possible, since any functions that Windows 
is to call back must be exported, and only 16-bit functions can be exported. 

A 16-bit far pointer to a function is obtained in one of two ways: either Windows gives it to you (via 
GetProcAddr, for example), or you obtain a pointer from the supervisor, via GetProcl 6. 

Function pointers obtained from Windows may either be fed into other Windows functions requiring 
function pointers, or called indirectly by using _ Calll6orby using the 
GetlndirectFunctionHandle, InvokelndirectFunction, and 
FreelndirectFunctionHandle sequence. 

The function GetProcl 6 returns a 16-bit far pointer to a callback function that Windows can use. This 
callback function will direct control into the desired 32-bit routine. 


24.4 Why are 32-bit callback routines FAR? 

The callback routines are declared as FAR so that the compiler will generate a far return from the 
procedure. This is necessary since the 32-bit callback routine is "far" called from the supervisor. 

The callback routine is still "near" in the sense that it lies within the 32-bit flat address space of the 
application. This means that GetProcl 6 only needs the offset of the 32-bit callback function in order to 
set up the 16-bit procedure to call back correctly. Thus, GetProcl 6 accepts type PROCPTR which is in 
fact only 4 bytes long. The compiler will provide the offset only, which is, as already stated, all that is 
needed. 


24.5 Why use the_16 API functions? 

The regular Windows API functions used in Open Watcom F77 automatically convert any pointers to 
16-bit far pointers for use by Windows. Sometimes, you may have a set of pointers that are 16-bit far 
pointers already (e.g., obtained from GlobalLock), and do not need any conversion. The "_16..." API 
functions do not convert pointers, they simply pass them on directly to Windows. See the appendix entitled 
"Special Windows API Functions" on page 181 for a list of the "_16..." API functions. 
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25 Special Windows API Functions 


On rare occasions, you want to use 16-bit far pointers directly in a Windows function. Since all Windows 
functions in the 32-bit environment are expecting 32-bit near pointers, you cannot simply use the 16-bit far 
pointer directly in the function. 

The following functions are special versions of Windows API functions that do NOT convert any of the 
pointers from 32-bit to 16-bit. There are _16 versions of all Windows API functions that accept data 
pointers. 

_16 Add Atom 

_ 16 AddFontResource 

_16AdjustWindowRect 

_16AdjustWindowRectEx 

_ 16 AnimateP alette 

_16AnsiLower 

_ 16 AnsiLowerBuff 

_16AnsiToOem 

_16AnsiToOemBuff 

_16AnsiUpper 

_16AnsiUpperBuff 

_ 16BuildCommDCB 

_16CallMsgFilter 

_16ChangeMenu 

_16ClientToScreen 

_16ClipCursor 

_ 16CopyMetaFile 

_16CopyRect 

_16CreateBitmap 

_ 16CreateBitmapIndirect 

_ 16CreateBmshIndirect 

_ 16CreateCursor 

_16CreateDC 

_16CreateDialog 

_ 16CreateDialoglndirect 

_ 16CreateDialogIndirectParam 

_ 16CreateDialogParam 

_ 16CreateDIBitmap 

_ 16CreateEllipticRgnIndirec t 

_16CreateFont 

_ 16CreateFontIndirect 

_16CreateIC 

_16CreateIcon 

_ 16CreateMetaFile 

_16CreatePalette 

_ 16CreatePenIndirect 

_ 16CreatePolygonRgn 

_ 16CreatePolyPolygonRgn 

_16CreateRectRgnIndirect 
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16Create Window 
16Create WindowEx 
16DialogBox 
16DialogBoxIndirect 
16DialogBoxIndirectParam 
16DialogBoxParam 
16DispatchMessage 
16DlgDirList 
16DlgDirListComboBox 
16DlgDirSelect 
16DlgDirSelectComboBox 
16DPtoLP 
16DrawFocusRect 
16DrawText 
16EndPaint 

16EnumChild Windows 

16EnumFonts 

16EnumMetaFile 

16EnumObjects 

16EnumProps 

16EnumTaskWindows 

16EnumWindows 

16EqualRect 

16Escape 

16ExtTextOut 

16FillRect 

16FindAtom 

16FindResource 

16FindWindow 

16FrameRect 

16FreeProcInstance 

16Get AtomN ame 

16GetBitmapBits 

16GetCaretPos 

16GetCharWidth 

16GetClassInfo 

16GetClassN ame 

16GetClientRect 

16GetClipboardFormatN ame 

16GetClipBox 

16GetCodeInfo 

16GetCommError 

16GetCommState 

16GetCursorPos 

16GetDIBits 

16GetDlgItemInt 

16GetDlgItemText 

16GetEnvironment 

16GetKeyboardS tate 

16GetKeyN ameT ext 

16GetMenuString 

16GetMetaFile 

16GetModuleFileN ame 

16GetModuleHandle 
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16GetObject 

16GetPaletteEn tries 

16GetPriorityClipboardFormat 

16GetPri vateProfilelnt 

16GetPrivateProfileString 

16GetProc Address 

16GetProfileInt 

16GetProfileString 

16GetProp 

16GetRgnBox 

16GetScrollRange 

16GetSy stemDirectory 

16GetSy stemPaletteEntries 

16GetT abbedT extExtent 

16GetT empFileN ame 

16GetT extExtent 

16GetTextFace 

16GetT extMetrics 

16GetUpdateRect 

16GetWindo wRect 

16GetWindo wsDirectory 

16GetW indo wText 

16Global Add Atom 

16GlobalFind Atom 

16GlobalGet AtomN ame 

16GlobalNotify 

16GrayString 

16InflateRect 

16IntersectRect 

16InvalidateRect 

16InvertRect 

16IsDialogMessage 

16IsRectEmpty 

16LineDDA 

16 Load Accelerators 

16LoadBitmap 

16LoadCursor 

16LoadIcon 

16LoadLibrary 

16LoadMenu 

16LoadMenuIndirec t 

16LoadModule 

16LoadString 

16LPtoDP 

16MakeProcInstance 

16MapDialogRect 

16MessageBox 

160emToAnsi 

160emTo AnsiBuff 

160ffsetRect 

160penComm 

160penFile 

160utputDebugString 

16PlayMetaFileRecord 
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16Polygon 

16Polyline 

16PolyPolygon 

16PtInRect 

16ReadComm 

16RectInRegion 

16RectVisible 

16RegisterClipboardFormat 

16RegisterWindowMessage 

16RemoveFontResource 

16RemoveProp 

16ScreenToClient 

16ScrollDC 

16Scroll Window 

16SetBitmapBits 

16SetCommState 

16SetDIBits 

16SetDIBitsToDevice 

16SetDlgItemText 

16 S e tEn vironment 

16SetKeyboardState 

16SetPalette Entries 

16SetProp 

16SetRect 

16SetRectEmpty 

16SetResourceHandler 

16SetSysColors 

16SetTimer 

16SetWindowsF[ook 

16SetWindowText 

16StretchDIBits 

16T abbedTextOut 

16TextOut 

16ToAscii 

16TrackPopupMenu 

16Translate Accelerator 

16TranslateMDISys Accel 

16TranslateMessage 

16U nhook W indowsPIook 

16UnionRect 

16UnregisterClass 

16ValidateRect 

16WinExec 

16WinHelp 

16WriteComm 

16 WritePrivateProfileString 

16 WriteProfileString 

16_lread 

16_lwrite 
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26 Windows NT Programming Overview 


Windows NT supports both non-windowed character-mode applications and windowed Graphical User 
Interface (GUI) applications. In addition, Windows NT supports Dynamic Link Libraries and applications 
with multiple threads of execution. 

We have supplied all the necessary tools for native development on Windows NT. You can also cross 
develop for Windows NT using either the DOS-hosted compilers and tools, the Windows 95-hosted 
compilers and tools, or the OS/2-hosted compilers and tools. Testing and debugging of your Windows NT 
application must be done on Windows NT or Windows 95. 

If you are creating a character-mode application, you may also be interested in a special DOS extender 
from Phar Lap (TNT) that can run your Windows NT character-mode application under DOS. 


26.1 Windows NT Character-mode Versus GUI 


Basically, there are two classes of FORTRAN 77 applications that can run in a windowed environment like 

Windows NT. 

The first are those FORTRAN 77 applications that do not use any of the Win32 API functions; they are 

strictly FORTRAN 77 applications that do not rely on the features of a particular operating system. 

• This Application must be created as Windows NT Character-mode Application. 

The second class of FORTRAN 77 applications are those that actually call Win32 API functions directly. 

These are applications that have been tailored for the Win32 operating environment. 

• Open Watcom FORTRAN 77 does not provide direct support for these types of applications. While 
we do provide include files that map out 16-bit Windows structures and the interface to 16-bit 
Windows API calls, we do not provide this for Win32 API. The Win32 application developer must 
create these as required. 

• An alternate solution, for those so-inclined, is to develop the GUI part of the interface in C and call 
these functions from FORTRAN code. 

A subsequent chapters deal with the creation of different application types for Windows NT target. 
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27 Creating Windows NT Character-mode 
Applications 


This chapter describes how to compile and link Windows NT Character-mode applications simply and 
quickly. In this chapter, we look at applications written to exploit the Windows NT Application 
Programming Interface (API). 


We will illustrate the steps to creating Windows NT Character-mode applications by taking a small sample 
application and showing you how to compile, link, run and debug it. 

27.1 The Sample Character-mode Application 

To demonstrate the creation of Windows NT Character-mode applications, we introduce a simple sample 
program. For our example, we are going to use the "sieve" program. 

* This program computes the prime numbers between 1 and 10,000 

* using the Sieve of Eratosthenes algorithm. 


IMPLICIT NONE 
INTEGER UPBOUND 
PARAMETER (UPBOUND=10000) 

INTEGER I, K, PRIMES 
LOGICAL*1 NUMBERS(2:UPBOUND) 

CHARACTER*11 FORM 
CHARACTER*60 BUFFER 
PARAMETER (FORM='(A,15,A,15)') 

DO I = 2, UPBOUND 

NUMBERS(I) = .TRUE. 

ENDDO 

PRIMES = 0 

DO I = 2, UPBOUND 

IF( NUMBERS(I) )THEN 

PRIMES = PRIMES + 1 
DO K = I + I, UPBOUND, I 
NUMBERS(K) = .FALSE. 

ENDDO 
END IF 
ENDDO 

PRINT FORM, 'The Number of Primes between 1 and ', UPBOUND, 
1 ' are: ', PRIMES 

END 


The goal of this program is to count the prime numbers between 1 and 10,000. It uses the famous Sieve of 
Eratosthenes algorithm to accomplish this task. We will take you through the steps necessary to produce 
this result. 
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27.2 Building and Running the Character-mode Application 

To compile and link our example program which is stored in the file sieve . for, enter the following 
command: 

C>wfl386 -l=nt sieve.for 

The typical messages that appear on the screen are shown in the following illustration. 

C>wfl386 -l=nt sieve.for 

Open Watcom F77/32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 
wfc386 sieve.for 

Open Watcom FORTRAN 77/32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 4390 statements, 207 bytes, 1585 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows NT Character-mode executable 


If you examine the current directory, you will find that two files have been created. These are 

sieve . ob j (the result of compiling sieve . for) and sieve . exe (the result of linking sieve . ob j 

with the appropriate Open Watcom FORTRAN 77 libraries). 

The resultant Windows NT Character-mode application SIEVE . EXE can now be run under Windows NT. 

27.3 Debugging the Character-mode Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "sieve" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WFL386 command, this is fairly straightforward. WFL386 recognizes the Open Watcom 
F77 compiler "debug" options and will create the appropriate debug directives for the Open Watcom 
Linker. 

For example, to compile and link the "sieve" program with debugging information, the following command 
may be issued. 

C>wfl386 -l=nt -d2 sieve.for 


The typical messages that appear on the screen are shown in the following illustration. 
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C>wfl386 -l=nt -d2 sieve.for 

Open Watcom F77/32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 
wfc386 sieve.for -d2 

Open Watcom FORTRAN 77/32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 4390 statements, 293 bytes, 1585 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows NT Character-mode executable 


The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom F77 compiler. WFL38 6 will make sure that this debugging information is included in the 
executable file that is produced by the linker. 

The "bytes" value is larger than in the previous example since selection of the "d2" option results in fewer 
code optimizations by default. You can request more optimization by specifying the appropriate options. 
However, you do so at the risk of making it more difficult for yourself to determine the relationship 
between the object code and the original source language code. 

To request the Open Watcom Debugger to assist in debugging the application, select the Open Watcom 
Debugger icon. It would be too ambitious to describe the debugger in this introductory chapter so we refer 
you to the book entitled Open Watcom Debugger User’s Guide. 

There are more extensive examples of Windows applications written in FORTRAN 77 in the 
\WATC0M\SAMPLES\FORTRAN\WIN directory. The example programs are ELLIPSE . FOR and 
FWCOPY.FOR. 
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28 Windows NT Multi-threaded Applications 


This chapter describes how to create multi-threaded applications. A multi-threaded application is one 
whose tasks are divided among several threads of execution. A process is an executing application and the 
resources it uses. A thread is the smallest unit of execution within a process. Each thread has its own stack 
and a set of machine registers and shares all resources with its parent process. The path of execution of one 
thread does not affect that of another; each thread is an independent entity. 

Typically, an application has a single thread of execution. In this type of application, all tasks, once 
initiated, are completed before the next task begins. In contrast, tasks in a multi-threaded application can 
be performed concurrently since more than one thread is executing at once. For example, each thread may 
be designed to perform a separate task. 

28.1 Programming Considerations 

Since a multi-threaded application consists of many threads of execution, there are a number of issues that 
you must consider. 

Since threads share the resources of its parent, it may be necessary to serialize access to these resources. 

For example, if your application contains more than one thread of execution and each thread uses the 
PRINT statement to display output to the console, it would be necessary for the I/O support routines to 
allow only one thread to use the PRINT facility at any time. That is, once a thread issues a PRINT request, 
the I/O support routines should ensure that no other thread displays information until all information for the 
initial thread has been displayed. 

28.2 Creating Threads 

Each application initially contains a single thread. The run-time libraries contain two functions that create 
and terminate threads of execution. The function beginthread creates a thread of execution and the 
function endthread ends a thread of execution. The function threadid can be used to determine the 
current thread identifier. 


WARNING! If any thread uses an I/O statement or calls an intrinsic function, you must use the 
beginthread function to create the thread. Do not use the CreateThread API function. 


28.2.1 Creating a New Thread 

The beginthread function creates a new thread. It is defined as follows. 

integer function beginthread! start_ address, 

stack_ size ) 

integer stack_ size 
end 
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where description: 

start_address is the address of the subroutine that will be called when the newly created thread is 

executed. When the thread returns from that subroutine, the thread will be terminated. 
Note that a call to the endthread subroutine will also terminate the thread. 

stack_size specifies the size of the stack to be allocated by the operating system for the new thread. 
The stack size should be a multiple of 4K. 

If a new thread is successfully created, the thread identifier of the new thread is returned. Otherwise, a 
value of -1 is returned. 

The include file thread, f i contains the definition of the beginthread function. 

Another thread related function for Windows NT is _ beginthreadex. See the Open Watcom C 
Library Reference for more information. 

28.2.2 Terminating the Current Thread 

The endthread subroutine terminates the current thread. It is defined as follows. 

subroutine endthread() 
end 

The include file thread, f i contains the definition of the endthread function. 

28.2.3 Getting the Current Thread Identifier 

The threadid function can be used to determine the current thread identifier. It is defined as follows. 

integer function threadid() 
end 

The include file thread, f i contains the definition of the threadid function. 

28.3 A Multi-threaded Example 

Let us create a simple multi-threaded application. The source code for this example can be found in 
\watcom\samples\fortran\win32. 
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* MTHREAD.FOR 


$pragma aux 
$pragma aux 
$pragma aux 
$pragma aux 
$pragma aux 


(_stdcall) 

(_stdcall) 

(_stdcall) 

(_stdcall) 

(_stdcall) 


Sleep parm( value ) 

InitializeCriticalSection parm( reference ) 
DeleteCriticalSection parm( reference ) 
EnterCriticalSection parm( reference ) 
LeaveCriticalSection parm( reference ) 


structure /RTL_ CRITICAL_ SECTION/ 
integer*4 Debuglnfo 
integer*4 LockCount 
integer*4 RecursionCount 
integer*4 OwningThread 
integer*4 LockSemaphore 
integer*4 Reserved 
end structure 


integer NumThreads 

logical HoldThreads 

volatile HoldThreads, NumThreads 

record /RTL_ CRITICAL_ SECTION/ CriticalSection 

common NumThreads, HoldThreads, CriticalSection 

integer STACK_ SIZE 
parameter (STACK_ SIZE=8192) 
integer NUM_ THREADS 
parameter (NUM_ THREADS=5) 

integer i, threadid, beginthread 
external a_ thread 

print '(''main thread id = '',i4)', threadid() 

NumThreads = 0 
HoldThreads = .true. 

! main thread counts as 1 

call InitializeCriticalSection( CriticalSection ) 
do i = 2, NUM_ THREADS 

if ( beginthread ( a_ thread, STACK_ SIZE ) .eq. -1 ) then 
print '(''creation of thread'',i4,''failed'')', i 

else 

NumThreads = NumThreads + 1 
end if 
end do 

HoldThreads = .false, 
while( NumThreads .ne. 0 ) do 
call Sleep( 1 ) 
end while 

call DeleteCriticalSection( CriticalSection ) 
end 


subroutine a_ thread() 

structure /RTL_ CRITICAL_ SECTION/ 
integer*4 Debuglnfo 
integer*4 LockCount 
integer*4 RecursionCount 
integer*4 OwningThread 
integer*4 LockSemaphore 
integer*4 Reserved 
end structure 


integer NumThreads 
logical HoldThreads 
volatile HoldThreads 

record /RTL_ CRITICAL_ SECTION/ CriticalSection 
common NumThreads, HoldThreads, CriticalSection 

integer threadid 
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while( HoldThreads ) do 
call Sleep( 1 ) 
end while 

print ' (''Hi from thread '', i4)', threadidO 
call EnterCriticalSection( CriticalSection ) 
NumThreads = NumThreads - 1 

call LeaveCriticalSection( CriticalSection ) 

call endthreadO 

end 


Note: 

1. In the subroutine a_ thread,EnterCriticalSection and LeaveCriticalSection 
are called when we modify the variable NumThreads . This ensures that the action of 
extracting the value of NumThreads from memory, incrementing the value, and storing the 
new result into memory, occurs without interruption. If these functions were not called, it would 
be possible for two threads to extract the value of NumThreads from memory before an update 
occurred. 

Let us assume that the file mthread. for contains the above example. Before compiling the file, make 
sure that the WATCOM environment variable is set to the directory in which you installed Open Watcom 
FORTRAN 77. Also, the FINCLUDE environment variable must contain the \watcom\src\fortran 
directory where "YWATCOM" is the name of the directory in which you installed Open Watcom 
FORTRAN 77. 

We can now compile and link the application by issuing the following command. 

C:\>wfl386 -bm -l=nt mthread 

The "bm" option must be specified since we are creating a multi-threaded application. If your 
multi-threaded application contains more than one module, each module must be compiled using the "bm" 
switch. 

The "1" option specifies the target system for which the application is to be linked. The system name nt is 
defined in the file wl system. Ink which is located in the "BINW" subdirectory of the directory in which 
you installed Open Watcom FORTRAN 77. 

The multi-threaded application is now ready to be run. 
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A dynamic link library, like a standard library, is a library of functions. When an application uses functions 
from a standard library, the library functions referenced by the application become part of the executable 
module. This form of linking is called static linking. When an application uses functions from a dynamic 
link library, the library functions referenced by the application are not included in the executable module. 
Instead, the executable module contains references to these functions which are resolved when the 
application is loaded. This form of linking is called dynamic linking. 

Let us consider some of the advantages of using dynamic link libraries over standard libraries. 

1. Functions in dynamic link libraries are not linked into your program. Only references to the 
functions in dynamic link libraries are placed in the program module. These references are 
called import definitions. As a result, the linking time is reduced and disk space is saved. If 
many applications reference the same dynamic link library, the saving in disk space can be 
significant. 

2. Since program modules only reference dynamic link libraries and do not contain the actual 
executable code, a dynamic link library can be updated without re-linking your application. 
When your application is executed, it will use the updated version of the dynamic link library. 

3. Dynamic link libraries also allow sharing of code and data between the applications that use 
them. If many applications that use the same dynamic link library are executing concurrently, 
the sharing of code and data segments improves memory utilization. 

29.1 Creating Dynamic Link Libraries 

Once you have developed the source for a library of functions, a number of steps are required to create a 
dynamic link library containing those functions. 

First, you must compile your source using the "bd" compiler option. This option tells the compiler that the 
module you are compiling is part of a dynamic link library. Once you have successfully compiled your 
source, you must create a linker directive file that describes the attributes of your dynamic link library. The 
following lists the most common linker directives required to create a dynamic link library. 

1. The "SYSTEM" directive is used to specify that a dynamic link library is to be created. 

2. The "EXPORT" directive is used to to specify which functions in the dynamic link library are to 
be exported. 

3. The "OPTION" directive is used to specify attributes such as the name of the dynamic link 
library and how to allocate the automatic data segment when the dynamic link library is 
referenced. 

4. The "SEGMENT" directive is used to specify attributes of segments. For example, a segment 
may be read-only or read-write. 

Once the dynamic link library is created, you must allow access to the dynamic link library to client 
applications that wish to use it. This can be done by creating an import library for the dynamic link library 
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or creating a linker directive file that contains "IMPORT" directives for each of the entry points in the 
dynamic link library. 

29.2 Creating a Sample Dynamic Link Library 

Let us now create a dynamic link library using the following example. The source code for this example 
can be found in \watcom\samples\fortran\win\dll . Unlike applications developed in the C or 
C++ language, the FORTRAN 77 developer must not provide a LibMain entry point. This entry point is 
already defined in the Open Watcom FORTRAN 77 run-time libraries. The run-time system’s LibMain 
provides for the proper initialization of the FORTRAN 77 run-time system and includes hooks to call 
developer-written process attach/detach and thread attach/detach routines. These routines are optional but 
we show skeleton versions in the following example so that you can develop your own if required. 

* DLLSAMP.FOR 


integer function_fdll_ initialize_ () 

Called from LibMain during "DLL PROCESS ATTACH" 

do process initialization 
print *, 'Hi from process attach' 

returning 0 indicates failure 

_fdll_ initialize_ = 1 

return 

end 

integer function_fthrd_ initialize_ () 

Called from LibMain during "DLL THREAD ATTACH" 

do thread initialization 
print *, 'Hi from thread attach' 

returning 0 indicates failure 

_fthrd_ initialize_ = 1 

return 

end 

integer function_fthrd_ terminate_ () 

Called from LibMain during "DLL THREAD DETACH" 

do thread cleanup 

print *, 'Hi from thread detach' 

returning 0 indicates failure 

_fthrd_ terminate_ = 1 

return 

end 

integer function_fdll_ terminate_ () 

Called from LibMain during "DLL PROCESS DETACH" 

do process cleanup 

print *, 'Hi from process detach' 

returning 0 indicates failure 

_fdll_ terminate_ = 1 

return 

end 

subroutine dll_ entry_ 1 () 
print *, 'Hi from dll entry #1' 
end 

subroutine dll_ entry_ 2 () 
print *, 'Hi from dll entry #2' 
end 
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Here are some explanatory notes on this example. 

Function Description 

FDLL INITIALIZE This function is called when the DLL is attaching to the address space of the 
current process as a result of the process starting up or as a result of a call to 
LoadLibrary. A DLL can use this opportunity to initialize any instance data. 

During initial process startup or after a call to LoadLibrary, the operating system scans 
the list of loaded DLLs for the process. For each DLL that has not already been called with 
the DLL_ PROCESS_ ATTACH value, the system calls the DLL’LibMain entry-point (in 
the Open Watcom FORTRAN 77 run-time system). This call is made in the context of the 
thread that caused the process address space to change, such as the primary thread of the 
process or the thread that called LoadLibrary. 

_ FTHRD_INITIALIZE_ This function is called when the current process is creating a new thread. When 

this occurs, the system calls the LibMain entry-point (in the Open Watcom FORTRAN 77 
run-time system) of all DLLs currently attached to the process. The call is made in the 
context of the new thread. DLLs can use this opportunity to initialize thread specific data. 

A thread calling the DLL’s LibMain with the DLL_ PROCESS_ ATTACH value does not 
call LibMain with the DLL_ THREAD_ ATTACH value. Note thaLibMain is called with 
this value only by threads created after the DLL is attached to the process. When a DLL is 
attached by LoadLibrary, existing threads do not call the LibMain entry-point of the 
newly loaded DLL. 

_ FTHRD_TERMINATE_ This function is called when a thread is exiting normally. The DLL uses this 

opportunity to do thread specific termination such as closing files that were opened by the 
thread. The operating system calls the LibMain entry-point (in the Open Watcom 
FORTRAN 77 run-time system) of all currently loaded DLLs with this value. The call is 
made in the context of the exiting thread. There are cases in which LibMain is called for 
a terminating thread even if the DLL never attached to the thread. For example, LibMain 
is never called with the DLL_ THREAD_ ATTACH value in the context of the thread in either 
of these two situations: 

• The thread was the initial thread in the process, so the system called LibMain with 
the DLL_ PROCESS_ ATTACH value. 

• The thread was already running when a call to the LoadLibrary function was 
made, so the system never called LibMain for it. 

FDLL TERMINATE This function is called when the DLL is detaching from the address space of the 
calling process as a result of either a normal termination or of a call to FreeLibrary. 
When a DLL detaches from a process as a result of process termination or as a result of a 
call to FreeLibrary, the operating system does not call the DLL’s LibMain with the 
DLL_ THREAD_ DETACH value for the individual threads of the process. The DLL is only 
given DLL_ PROCESS_ DETACH notification. DLLs can take this opportunity to clean up 
all resources for all threads attached and known to the DLL. 

Note: These functions return 1 if initialization succeeds or 0 if initialization fails. Subsequently, 

this value will be returned by the run-time system’s LibMain function. 

If the return value is 0 when LibMain is called because the process uses the 
LoadLibrary function, LoadLibrary returns NULL. 
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If the return value is 0 when LibMain is called during process initialization, the process 
terminates with an error. 

DLL_ENTRY_1, DLL_ENTRY_2 These are sample DLL entry points that we will call from our simple 
test program. 

Some further explanation and an example are provided in a later section. 

Assume the above example is contained in the file dllsamp. for . We can compile the file using the 
following command. Note that we must specify the "bd" compiler option. 

C:\>wfc386 -bd dllsamp 

Before we can link our example, we must create a linker directive file that describes the attributes and entry 
points of our dynamic link library. The following is a linker directive file, called dllsamp. Ink, that 
can be used to create the dynamic link library. 

system nt_ dll initinstance terminstance 
export DLL_ ENTRY_ 1 
export DLL_ ENTRY_ 2 
file dllsamp 

Notes: 

1. The "SYSTEM" directive specifies that we are creating a Windows NT dynamic link library. 

2. When a dynamic link library uses the Open Watcom FORTRAN 77 run-time libraries, an 
automatic data segment is created each time a new process accesses the dynamic link library. 

For this reason, initialization code must be executed when a process accesses the dynamic link 
library for the first time. To achieve this, "INITINSTANCE" must be specified in the 
"SYSTEM" directive. Similarly, "TERMINSTANCE" must be specified so that the termination 
code is executed when a process has completed its access to the dynamic link library. If the 
Open Watcom FORTRAN 77 run-time libraries are not used, these options are not required. 

3. The "EXPORT" directive specifies the entry points into the dynamic link library. Note that in 
Open Watcom FORTRAN 77, names of all symbols are uppercased. Regardless of the case used 
in source files, linker directives must use uppercased symbol names. The linker is case sensitive 
by default, although the "OP NOCASEEXACT" directive may be used to override this. 

We can now create our dynamic link library by issuing the following command. 

C:\>wlink @dllsamp 

A file called dllsamp. dll will be created. 

29.3 Using Dynamic Link Libraries 

Once we have created a dynamic link library, we must allow other applications to access the functions 
available in the dynamic link library. There are two ways to achieve this. 

The first method is to create a linker directive file which contains an "IMPORT" directive for all entry 
points in the dynamic link library. The "IMPORT" directive provides the name of the entry point and the 
name of the dynamic link library. When creating an application that references a function in the dynamic 
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link library, this linker directive file would be included as part of the linking process that created the 
application. 

The second method is to use import libraries. An import library is a standard library that is created from a 
dynamic link library by using the Open Watcom Library Manager. It contains object modules that describe 
the entry points in a dynamic link library. The resulting import library can then be specified in a 
"LIBRARY" directive in the same way one would specify a standard library. 

Using an import library is the preferred method of providing references to functions in dynamic link 
libraries. When a dynamic link library is modified, typically the impoit library corresponding to the 
modified dynamic link library is updated to reflect the changes. Hence, any directive file that specifies the 
import library in a "LIBRARY" directive need not be modified. However, if you are using "IMPORT" 
directives, you may have to modify the "IMPORT" directives to reflect the changes in the dynamic link 
library. 

Let us create an import library for our sample dynamic link library we created in the previous section. We 
do this by issuing the following command. 

C:\>wlib dllsamp +dllsamp.dll 

A standard library called dllsamp. lib will be created. 

Suppose the following sample program, contained in the file dlltest. for, calls the functions from our 
sample dynamic link library. 

* DLLTEST.FOR 

call dll_ entry_ 1() 
call dll_ entry_ 2() 
end 


We can compile and link our sample application by issuing the following command. 

C:\>wfl386 -l=nt dlltest dllsamp.lib 

If we had created a linker directive file of "IMPORT" directives instead of an import library for the 
dynamic link library, the linker directive file, say dllimps . Ink, would be as follows. 

import DLL_ ENTRY_ 1 dllsamp 
import DLL_ ENTRY_ 2 dllsamp 

To compile and link our sample application, we would issue the following command. 

C:\>wfl386 -l=nt dlltest -"Sdllimps" 

29.4 The Dynamic Link Library Data Area 

The Open Watcom FORTRAN 77 32-bit run-time library does not support the general case operation of 
DLLs in an execution environment where there is only one instance of the DATA segment (DGROUP) for 
that DLL. 

There are two cases that can lead to a DLL executing with only one instance of the DGROUP. 

1. DLLs linked for 32-bit OS/2 without the MANY AUTODATA option. 
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2. DLLs linked for the Win32 API and executing under Win32s. 

In these cases the run-time library startup code detects that there is only one instance of the DGROUP when 
a second process attempts to attach to the DLL. At that point, it issues a diagnostic for the user and then 
notifies the operating system that the second process cannot attach to the DLL. 

Developers who require DLLs to operate when there is only one instance of the DGROUP can suppress the 
function which issues the diagnostic and notifies the operating system that the second process cannot attach 
to the DLL. 

Doing so requires good behaviour on the part of processes attaching to the DLL. This good behaviour 
consists primarily of ensuring that the first process to attach to the DLL is also the last process to detach 
from the DLL thereby ensuring that the DATA segment is not released back to the free memory pool. 

To suppress the function which issues the diagnostic and notifies the operating system that the second 
process cannot attach to the DLL, the developer must provide a replacement entry point with the following 
prototype: 

int_disallow_ single_ dgroup ( int ) ; 

This function should return zero to indicate that the detected single copy of the DATA segment is allowed. 

29.5 Dynamic Link Library Initialization/Termination 

Each dynamic link library (DLL) has an initialization and termination routine associated with it. The 
initialization routine can either be called the first time any process accesses the DLL ("INITGLOBAL" is 
specified at link time) or each time a process accesses the DLL ("INITINSTANCE" is specified at link 
time). Similarly, the termination routine can either be called when all processes have completed their 
access of the DLL ("TERMGLOBAL" is specified at link time) or each time a process completes its access 
of the DLL ("TERMINSTANCE" is specified at link time). 

For a DLL that uses the FORTRAN 77 run-time libraries, initialization and termination of the FORTRAN 
77 run-time environment is performed automatically. It is also possible for a DLL to do its own special 
initialization and termination process. 

The FORTRAN 77 run-time environment provides a method for calling user-written DLL initialization and 

termination code. The_fdll_ initialize_ routine is called for DLL process initialization. The 

_fthrd_ initialize_ routine is called for DLL thread initialization. The_ fthrd_ terminate. 

routine is called for DLL thread termination. The_f dll_ terminate_ routine is called for DLL 

process termination. Default stub versions of these routines are included in the run-time library. If you 
wish to perform additional initialization/termination processing that is specific to your dynamic link library, 
you may write your own versions of these routines. 

When a process first attaches to the DLL, the FORTRAN 77 run-time environment is initialized and then 

the routine_fdll_ initialize_ is called. When a thread is started, the routine 

_fthrd_ initialize_ is called. When a thread is terminated, the routine_ fthrd_ terminate_ 

is called. When the main process relinquishes the DLL, the routine_f dll_ terminate_ is called and 

then the FORTRAN 77 run-time environment is terminated. 

The initialization and termination routines return an integer. A value of 0 indicates failure; a value of 1 
indicates success. The following example illustrates sample initialization/termination routines. 
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* DLLINIT.FOR 

integer function_fdll_ initialize_ () 

integer_fthrd_ initialize_ ,_fthrd_ terminate_ 

integer_fdll_ terminate_ , dll_ entry 

integer WORKING_ SIZE 

parameter ( WORKING. SIZE = 16*1024 ) 
integer ierr, WorkingStorage 
dimension WorkingStorage(:) 

allocate( WorkingStorage(WORKING. SIZE) , stat=ierr ) 
if( ierr .eq. 0 )then 

_fdll. initialize. = 1 

else 

_fdll. initialize. = 0 

endif 

return 

entry_fthrd. initialize. () 

_fthrd. initialize. = 1 

return 

entry_fthrd. terminate. () 

_fthrd. terminate. = 1 

return 

entry_fdll. terminate. () 

* Note: no run-time calls allowed under OS/2 Warp 

deallocate( WorkingStorage ) 

_fdll. terminate. = 1 

return 

entry dll. entry () 

! use WorkingStorage 
return 

end 

In the above example, the process initialization routine allocates storage that the dynamic link library needs, 
the routine dll_ entry uses the storage, and the process termination routine frees the storage allocated in 
the initialization routine. 
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30 Creating 16-bit OS/21.x Applications 


An OS/2 application can be one of the following; a fullscreen application, a PM-compatible application, or 
a Presentation Manager application. A fullscreen application runs in its own screen group. A 
PM-compatible application will run in an OS/2 fullscreen environment or in a window in the Presentation 
Manager screen group but does not take direct advantage of menus, mouse or other features available in the 
Presentation Manager. A Presentation Manager application has full access to the complete set of 
user-interface tools such as menus, icons, scroll bars, etc. 

This chapter deals with the creation of OS/2 fullscreen applications. For information on creating 
Presentation Manager applications, refer to the section entitled "Programming for OS/2 Presentation 
Manager" on page 225. 

We will illustrate the steps to creating 16-bit OS/2 1.x applications by taking a small sample application 
and showing you how to compile, link, run and debug it. 

30.1 The Sample Application 

To demonstrate the creation of 16-bit OS/2 1.x applications using command-line oriented tools, we 
introduce a simple sample program. For our example, we are going to use the "sieve" program. 

* This program computes the prime numbers between 1 and 10,000 

* using the Sieve of Eratosthenes algorithm. 

IMPLICIT NONE 
INTEGER UPBOUND 
PARAMETER (UPBOUND=10000) 

INTEGER I, K, PRIMES 
LOGICAL*1 NUMBERS(2:UPBOUND) 

CHARACTER*11 FORM 

PARAMETER (FORM='(A,15,A,15)') 

DO I = 2, UPBOUND 

NUMBERS(I) = .TRUE. 

ENDDO 

PRIMES = 0 

DO I = 2, UPBOUND 

IF( NUMBERS(I) )THEN 

PRIMES = PRIMES + 1 
DO K = I + I, UPBOUND, I 
NUMBERS(K) = .FALSE. 

ENDDO 
END IF 
ENDDO 

PRINT FORM, 'The Number of Primes between 1 and ', UPBOUND, 

1 ' are: ', PRIMES 

END 

The goal of this program is to count the prime numbers between 1 and 10,000. It uses the famous Sieve of 
Eratosthenes algorithm to accomplish this task. We will take you through the steps necessary to produce 
this result. 
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30.2 Building and Running the Sample OS/21.x Application 

To compile and link our example program which is stored in the file sieve . for, enter the following 
command: 

[C:\]wfl -l=os2 sieve.for 

The typical messages that appear on the screen are shown in the following illustration. 

[C:\]wfl -l=os2 sieve.for 

Open Watcom F77/16 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
wfc sieve.for 

Open Watcom FORTRAN 77/16 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 21 statements, 311 bytes, 6 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating an OS/2 16-bit executable 


Provided that no errors were encountered during the compile or link phases, the "sieve" program may now 
be run. 

[C:\]sieve 

The Number of Primes between 1 and 10000 are: 1229 

If you examine the current directory, you will find that two files have been created. These are 
sieve . ob j (the result of compiling sieve . for) and sieve . exe (the result of linking sieve . ob j 
with the appropriate Open Watcom FORTRAN 77 libraries). It is sieve . exe that is run by OS/2 when 
you enter the "sieve" command. 

30.3 Debugging the Sample OS/2 1.x Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "sieve" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WFL command, this is fairly straightforward. WFL recognizes the Open Watcom F77 
compiler "debug" options and will create the appropriate debug directives for the Open Watcom Linker. 

For example, to compile and link the "sieve" program with debugging information, the following command 
may be issued. 

[C:\]wfl -l=os2 -d2 sieve.for 
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The typical messages that appear on the screen are shown in the following illustration. 

[C:\]wfl -l=os2 -d2 sieve.for 
Open Watcom F77/16 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
wfc sieve.for -d2 

Open Watcom FORTRAN 77/16 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 21 statements, 392 bytes, 6 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating an OS/2 16-bit executable 


The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom F77 compiler. WFL will make sure that this debugging information is included in the executable 
file that is produced by the linker. 

The "bytes" value is larger than in the previous example since selection of the "d2" option results in fewer 
code optimizations by default. You can request more optimization by specifying the appropriate options. 
However, you do so at the risk of making it more difficult for yourself to determine the relationship 
between the object code and the original source language code. 

For OS/2, you should also include the BINP \DLL directory in the "LIBPATH" directive of the system 
configuration file CONFIG. SYS . It contains the Open Watcom Debugger Dynamic Link Libraries 
(DLLs). 


Example: 

libpath=c:\watcom\binp\dll 

To request the Open Watcom Debugger to assist in debugging the application, the following command may 
be issued. 

[C:\]wd sieve 

It would be too ambitious to describe the debugger in this introductory chapter so we refer you to the book 
entitled Open Watcom Debugger User’s Guide. 
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31 Creating 32-bit OS/2 Applications 


An OS/2 application can be one of the following; a fullscreen application, a PM-compatible application, or 
a Presentation Manager application. A fullscreen application runs in its own screen group. A 
PM-compatible application will run in an OS/2 fullscreen environment or in a window in the Presentation 
Manager screen group but does not take direct advantage of menus, mouse or other features available in the 
Presentation Manager. A Presentation Manager application has full access to the complete set of 
user-interface tools such as menus, icons, scroll bars, etc. 


This chapter deals with the creation of OS/2 fullscreen applications. For information on creating 
Presentation Manager applications, refer to the section entitled "Programming for OS/2 Presentation 
Manager" on page 225. 


We will illustrate the steps to creating 32-bit OS/2 applications by taking a small sample application and 
showing you how to compile, link, run and debug it. 

31.1 The Sample Application 

To demonstrate the creation of 32-bit OS/2 applications using command-line oriented tools, we introduce a 
simple sample program. For our example, we are going to use the "sieve" program. 

* This program computes the prime numbers between 1 and 10,000 

* using the Sieve of Eratosthenes algorithm. 


IMPLICIT NONE 
INTEGER UPBOUND 
PARAMETER (UPBOUND=10000) 

INTEGER I, K, PRIMES 
LOGICAL*1 NUMBERS(2:UPBOUND) 

CHARACTER*11 FORM 

PARAMETER (FORM='(A,15,A,15)') 

DO I = 2, UPBOUND 

NUMBERS(I) = .TRUE. 

ENDDO 

PRIMES = 0 

DO I = 2, UPBOUND 

IF( NUMBERS(I) )THEN 

PRIMES = PRIMES + 1 
DO K = I + I, UPBOUND, I 
NUMBERS(K) = .FALSE. 

ENDDO 
END IF 
ENDDO 

PRINT FORM, 'The Number of Primes between 1 and ', UPBOUND, 
1 ' are: ', PRIMES 

END 


The goal of this program is to count the prime numbers between 1 and 10,000. It uses the famous Sieve of 
Eratosthenes algorithm to accomplish this task. We will take you through the steps necessary to produce 
this result. 
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31.2 Building and Running the Sample OS/2 Application 

To compile and link our example program which is stored in the file sieve . for, enter the following 
command: 

[C:\]wfl386 -1=os2v2 sieve.for 
The typical messages that appear on the screen are shown in the following illustration. 

[C:\]wfl386 -1=os2v2 sieve.for 
Open Watcom F77/32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 
wfc386 sieve.for 

Open Watcom FORTRAN 77/32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 21 statements, 172 bytes, 6 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating an OS/2 32-bit executable 


Provided that no errors were encountered during the compile or link phases, the "sieve" program may now 
be run. 

[C:\]sieve 

The Number of Primes between 1 and 10000 are: 1229 

If you examine the current directory, you will find that two files have been created. These are 
sieve . ob j (the result of compiling sieve . for) and sieve . exe (the result of linking sieve . ob j 
with the appropriate Open Watcom FORTRAN 77 libraries). It is sieve . exe that is run by OS/2 when 
you enter the "sieve" command. 

31.3 Debugging the Sample OS/2 Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "sieve" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WFL386 command, this is fairly straightforward. WFL386 recognizes the Open Watcom 
F77 compiler "debug" options and will create the appropriate debug directives for the Open Watcom 
Linker. 

For example, to compile and link the "sieve" program with debugging information, the following command 
may be issued. 

[C:\]wfl386 -1=os2v2 -d2 sieve.for 
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The typical messages that appear on the screen are shown in the following illustration. 

[C:\]wfl386 -1=os2v2 -d2 sieve.for 
Open Watcom F77/32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1990-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 
wfc386 sieve.for -d2 

Open Watcom FORTRAN 77/32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

sieve.for: 21 statements, 237 bytes, 6 extensions, 0 warnings, 0 errors 
Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating an OS/2 32-bit executable 


The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom F77 compiler. WFL38 6 will make sure that this debugging information is included in the 
executable file that is produced by the linker. 

The "bytes" value is larger than in the previous example since selection of the "d2" option results in fewer 
code optimizations by default. You can request more optimization by specifying the appropriate options. 
However, you do so at the risk of making it more difficult for yourself to determine the relationship 
between the object code and the original source language code. 

To request the Open Watcom Debugger to assist in debugging the application, the following command may 
be issued. 

[C:\]wd sieve 

It would be too ambitious to describe the debugger in this introductory chapter so we refer you to the book 
entitled Open Watcom Debugger User’s Guide. 
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32 OS/2 2.x Multi-threaded Applications 


This chapter describes how to create multi-threaded applications. A multi-threaded application is one 
whose tasks are divided among several threads of execution. A process is an executing application and the 
resources it uses. A thread is the smallest unit of execution within a process. Each thread has its own stack 
and a set of machine registers and shares all resources with its parent process. The path of execution of one 
thread does not affect that of another; each thread is an independent entity. 

Typically, an application has a single thread of execution. In this type of application, all tasks, once 
initiated, are completed before the next task begins. In contrast, tasks in a multi-threaded application can 
be performed concurrently since more than one thread is executing at once. For example, each thread may 
be designed to perform a separate task. 

32.1 Programming Considerations 

Since a multi-threaded application consists of many threads of execution, there are a number of issues that 
you must consider. 

Since threads share the resources of its parent, it may be necessary to serialize access to these resources. 

For example, if your application contains more than one thread of execution and each thread uses the 
PRINT statement to display output to the console, it would be necessary for the I/O support routines to 
allow only one thread to use the PRINT facility at any time. That is, once a thread issues a PRINT request, 
the I/O support routines should ensure that no other thread displays information until all information for the 
initial thread has been displayed. 

32.2 Creating Threads 

Each application initially contains a single thread. The run-time libraries contain two functions that create 
and terminate threads of execution. The function beginthread creates a thread of execution and the 
function endthread ends a thread of execution. The function threadid can be used to determine the 
current thread identifier. 


WARNING! If any thread uses an I/O statement or calls an intrinsic function, you must use the 
beginthread function to create the thread. Do not use the DosCreateThread API function. 


32.2.1 Creating a New Thread 

The beginthread function creates a new thread. It is defined as follows. 

integer function beginthread! start_ address, 

stack_ size ) 

integer stack_ size 
end 
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where description: 

start_address is the address of the subroutine that will be called when the newly created thread is 

executed. When the thread returns from that subroutine, the thread will be terminated. 
Note that a call to the endthread subroutine will also terminate the thread. 

stack_size specifies the size of the stack to be allocated by the operating system for the new thread. 
The stack size should be a multiple of 4K. 

If a new thread is successfully created, the thread identifier of the new thread is returned. Otherwise, a 
value of -1 is returned. 

The include file thread, f i contains the definition of the beginthread function. 

32.2.2 Terminating the Current Thread 

The endthread subroutine terminates the current thread. It is defined as follows. 

subroutine endthread() 
end 

The include file thread, f i contains the definition of the endthread function. 

32.2.3 Getting the Current Thread identifier 

The threadid function can be used to determine the current thread identifier. It is defined as follows. 

integer function threadid() 
end 

The include file thread, f i contains the definition of the threadid function. 


32.3 A Multithreaded Example 

Let us create a simple multi-threaded application. The source code for this example can be found in 
\watcom\samples\fortran\os2. 

* MTHREAD. FOR 

*$pragma aux DosSleep parm( value ) [] caller 

integer NumThreads 
logical HoldThreads 
common NumThreads, HoldThreads 

integer STACK_ SIZE 
parameter (STACK_ SIZE=32768) 
integer NUM_ THREADS 
parameter (NUM_ THREADS=5) 

integer i, threadid, beginthread 
external a_ thread 
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print ' (''main thread id = '', i4)', threadid() 

NumThreads = 0 
HoldThreads = .true. 

! main thread counts as 1 
do i = 2, NUM_ THREADS 

if ( beginthread ( a_ thread, STACK_ SIZE ) .eq. -1 ) then 
print '(''creation of thread'', i4, ''failed'')', i 

else 

NumThreads = NumThreads + 1 
end if 
end do 

HoldThreads = .false, 
while( NumThreads .ne. 0 )do 
call DosSleep( 1 ) 
end while 
end 

subroutine a_ thread() 
integer NumThreads 
logical HoldThreads 
common NumThreads, HoldThreads 
integer threadid 
while( HoldThreads )do 
call DosSleep( 1 ) 
end while 

call DosEnterCritSec() 

print '(''Hi from thread '', i4)', threadid() 

NumThreads = NumThreads - 1 
call DosExitCritSec() 
call endthreadO 
end 


Note: 


1. In the subroutine a_ thread,DosEnterCritSec and DosExitCritSec are called when 
we modify the variable NumThreads . This ensures that the action of extracting the value of 
NumThreads from memory, incrementing the value, and storing the new result into memory, 
occurs without interruption. If these functions were not called, it would be possible for two 
threads to extract the value of NumThreads from memory before an update occurred. 

Let us assume that the file mthread. for contains the above example. Before compiling the file, make 
sure that the WATCOM environment variable is set to the directory in which you installed Open Watcom 
FORTRAN 77. Also, the FINCLLTDE environment variable must contain the 

\watcom\src\fortran\os2 directory where "YWATCOM" is the name of the directory in which you 
installed Open Watcom FORTRAN 77. 

We can now compile and link the application by issuing the following command. 

[C:\]wfl386 -bm -1=os2v2 mthread 

The "bm" option must be specified since we are creating a multi-threaded application. If your 
multi-threaded application contains more than one module, each module must be compiled using the "bm" 
switch. 

The "1" option specifies the target system for which the application is to be linked. The system name 
os2v2 is defined in the file wlsystem. Ink which is located in the "BINW" subdirectory of the 
directory in which you installed Open Watcom FORTRAN 77. 

The multi-threaded application is now ready to be run. 
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32.4 Thread Limits 


There is a limit to the number of threads an application can create under 16-bit OS/2. The default limit is 

32. This limit can be adjusted by defining the integer function_getmaxthreads which returns the 

new thread limit. 

Under 32-bit OS/2, there is no limit to the number of threads an application can create. However, due to 
the way in which multiple threads are supported in the Open Watcom libraries, there is a small performance 
penalty once the number of threads exceeds the default limit of 32 (this number includes the initial thread). 
If you are creating more than 32 threads and wish to avoid this performance penalty, you can redefine the 
threshold value of 32. You can statically initialize the global variable_ MaxThreads . 

This limit can be adjusted by defining the integer function_getmaxthreads which returns the new 

thread limit. By defining_getmaxthreads as follows, the new threshold value will be set to 48. 

integer function _getmaxthreads() 

_getmaxthreads = 48 

end 

This version of_getmaxthreads will replace the default function that is included in the run-time 

library. The default function simply returns the current value of the internal variable_MaxThreads . 

Your version of this function will return a new value for this variable. Internally, the run-time system 
executes code similar to the following: 


MaxThreads =_getmaxthreads() 


Thus, the default_ getmaxthreads function does not alter the value of_ MaxThreads but your 

version will. 
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33 OS/2 2.x Dynamic Link Libraries 


A dynamic link library, like a standard library, is a library of functions. When an application uses functions 
from a standard library, the library functions referenced by the application become part of the executable 
module. This form of linking is called static linking. When an application uses functions from a dynamic 
link library, the library functions referenced by the application are not included in the executable module. 
Instead, the executable module contains references to these functions which are resolved when the 
application is loaded. This form of linking is called dynamic linking. 

Let us consider some of the advantages of using dynamic link libraries over standard libraries. 

1. Functions in dynamic link libraries are not linked into your program. Only references to the 
functions in dynamic link libraries are placed in the program module. These references are 
called import definitions. As a result, the linking time is reduced and disk space is saved. If 
many applications reference the same dynamic link library, the saving in disk space can be 
significant. 

2. Since program modules only reference dynamic link libraries and do not contain the actual 
executable code, a dynamic link library can be updated without re-linking your application. 
When your application is executed, it will use the updated version of the dynamic link library. 

3. Dynamic link libraries also allow sharing of code and data between the applications that use 
them. If many applications that use the same dynamic link library are executing concurrently, 
the sharing of code and data segments improves memory utilization. 

33.1 Creating Dynamic Link Libraries 

Once you have developed the source for a library of functions, a number of steps are required to create a 
dynamic link library containing those functions. 

First, you must compile your source using the "bd" compiler option. This option tells the compiler that the 
module you are compiling is part of a dynamic link library. Once you have successfully compiled your 
source, you must create a linker directive file that describes the attributes of your dynamic link library. The 
following lists the most common linker directives required to create a dynamic link library. 

1. The "SYSTEM" directive is used to specify that a dynamic link library is to be created. 

2. The "EXPORT" directive is used to to specify which functions in the dynamic link library are to 
be exported. 

3. The "OPTION" directive is used to specify attributes such as the name of the dynamic link 
library and how to allocate the automatic data segment when the dynamic link library is 
referenced. 

4. The "SEGMENT" directive is used to specify attributes of segments. For example, a segment 
may be read-only or read-write. 

Once the dynamic link library is created, you must allow access to the dynamic link library to client 
applications that wish to use it. This can be done by creating an import library for the dynamic link library 
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or creating a linker directive file that contains "IMPORT" directives for each of the entry points in the 
dynamic link library. 

33.2 Creating a Sample Dynamic Link Library 

Let us now create a dynamic link library using the following example. The source code for this example 
can be found in \watcom\samples\fortran\os2\dll. Unlike applications developed in the C or 
C++ language, the FORTRAN 77 developer must not provide a LibMain entry point. This entry point is 
already defined in the Open Watcom FORTRAN 77 run-time libraries. The run-time system’s LibMain 
provides for the proper initialization of the FORTRAN 77 run-time system and includes hooks to call 
developer-written process attach/detach and thread attach/detach routines. These routines are optional but 
we show skeleton versions in the following example so that you can develop your own if required. 

* DLLSAMP.FOR 


integer function_fdll_ initialize_ () 

Called from LibMain during "DLL PROCESS ATTACH" 

do process initialization 
print *, 'Hi from process attach' 

returning 0 indicates failure 

_fdll_ initialize_ = 1 

return 

end 

integer function_fdll_ terminate_ () 

Called from LibMain during "DLL PROCESS DETACH" 

do process cleanup 

print *, 'Hi from process detach' 

returning 0 indicates failure 

_fdll_ terminate_ = 1 

return 

end 

subroutine dll_ entry_ 1 () 
print *, 'Hi from dll entry #1' 
end 

subroutine dll_ entry_ 2 () 
print *, 'Hi from dll entry #2' 
end 


Assume the above example is contained in the file dllsamp. for . We can compile the file using the 
following command. Note that we must specify the "bd" compiler option. 

[C:\]wfc386 -bd dllsamp 

Before we can link our example, we must create a linker directive file that describes the attributes and entry 
points of our dynamic link library. The following is a linker directive file, called dllsamp. Ink, that 
can be used to create the dynamic link library. 

system os2v2 dll initinstance terminstance 

option manyautodata 

export DLL_ ENTRY_ 1 

export DLL_ ENTRY_ 2 

file dllsamp 
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Notes: 

1. The "SYSTEM" directive specifies that we are creating a 32-bit OS/2 dynamic link library. 

2. The "MANYAUTODATA" option specifies that the automatic data segment is allocated for 
every instance of the dynamic link library. This option must be specified only for a dynamic link 
library that uses the Open Watcom FORTRAN 77 run-time libraries. If the Open Watcom 
FORTRAN 77 run-time libraries are not used, this option is not required. Our example does use 
the Open Watcom FORTRAN 77 run-time libraries so we must specify the 

"MANYAUTODATA" option. 

As was just mentioned, when a dynamic link library uses the Open Watcom FORTRAN 77 
run-time libraries, an automatic data segment is created each time a process accesses the 
dynamic link library. For this reason, initialization code must be executed when a process 
accesses the dynamic link library for the first time. To achieve this, "INITINSTANCE" must be 
specified in the "SYSTEM" directive. Similarly, "TERMINSTANCE" must be specified so that 
the termination code is executed when a process has completed its access to the dynamic link 
library. If the Open Watcom FORTRAN 77 run-time libraries are not used, these options are not 
required. 

3. The "EXPORT" directive specifies the entry points into the dynamic link library. Note that in 
Open Watcom FORTRAN 77, names of all symbols are uppercased. Regardless of the case used 
in source files, linker directives must use uppercased symbol names. The linker is case sensitive 
by default, although the "OP NOCASEEXACT" directive may be used to override this. 

We can now create our dynamic link library by issuing the following command. 

[C:\]wlink Sdllsamp 
A file called dll samp. dll will be created. 


33.3 Using Dynamic Link Libraries 

Once we have created a dynamic link library, we must allow other applications to access the functions 
available in the dynamic link library. There are two ways to achieve this. 

The first method is to create a linker directive file which contains an "IMPORT" directive for all entry 
points in the dynamic link library. The "IMPORT" directive provides the name of the entry point and the 
name of the dynamic link library. When creating an application that references a function in the dynamic 
link library, this linker directive file would be included as part of the linking process that created the 
application. 

The second method is to use import libraries. An impoit library is a standard library that is created from a 
dynamic link library by using the Open Watcom Library Manager. It contains object modules that describe 
the entry points in a dynamic link library. The resulting impoit library can then be specified in a 
"LIBRARY" directive in the same way one would specify a standard library. 

Using an import library is the preferred method of providing references to functions in dynamic link 
libraries. When a dynamic link library is modified, typically the impoit library corresponding to the 
modified dynamic link library is updated to reflect the changes. Hence, any directive file that specifies the 
import library in a "LIBRARY" directive need not be modified. However, if you are using "IMPORT" 
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directives, you may have to modify the "IMPORT" directives to reflect the changes in the dynamic link 
library. 

Let us create an import library for our sample dynamic link library we created in the previous section. We 
do this by issuing the following command. 

[C:\]wlib dllsamp +dllsamp.dll 

A standard library called dllsamp. lib will be created. 

Suppose the following sample program, contained in the file dlltest. for, calls the functions from our 
sample dynamic link library. 

* DLLTEST.FOR 

call dll_ entry_ 1() 
call dll_ entry_ 2 () 
end 


We can compile and link our sample application by issuing the following command. 

[C:\]wfl386 -1=os2v2 dlltest dllsamp.lib 

If we had created a linker directive file of "IMPORT" directives instead of an import library for the 
dynamic link library, the linker directive file, say dllimps . Ink, would be as follows. 

import DLL_ ENTRY_ 1 dllsamp 
import DLL_ ENTRY_ 2 dllsamp 

To compile and link our sample application, we would issue the following command. 
[C:\]wfl386 -1=os2v2 dlltest -"@dllimps" 


33.4 The Dynamic Link Library Data Area 

The Open Watcom FORTRAN 77 32-bit run-time library does not support the general case operation of 
DLLs in an execution environment where there is only one instance of the DATA segment (DGROUP) for 
that DLL. 

There are two cases that can lead to a DLL executing with only one instance of the DGROUP. 

1. DLLs linked for 32-bit OS/2 without the MANY AUTODATA option. 

2. DLLs linked for the Win32 API and executing under Win32s. 

In these cases the run-time library startup code detects that there is only one instance of the DGROUP when 
a second process attempts to attach to the DLL. At that point, it issues a diagnostic for the user and then 
notifies the operating system that the second process cannot attach to the DLL. 

Developers who require DLLs to operate when there is only one instance of the DGROUP can suppress the 
function which issues the diagnostic and notifies the operating system that the second process cannot attach 
to the DLL. 
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Doing so requires good behaviour on the part of processes attaching to the DLL. This good behaviour 
consists primarily of ensuring that the first process to attach to the DLL is also the last process to detach 
from the DLL thereby ensuring that the DATA segment is not released back to the free memory pool. 

To suppress the function which issues the diagnostic and notifies the operating system that the second 
process cannot attach to the DLL, the developer must provide a replacement entry point with the following 
prototype: 

int_disallow_ single_ dgroup ( int ) ; 

This function should return zero to indicate that the detected single copy of the DATA segment is allowed. 


33.5 Dynamic Link Library Initialization/Termination 

Each dynamic link library (DLL) has an initialization and termination routine associated with it. The 
initialization routine can either be called the first time any process accesses the DLL ("INITGLOBAL" is 
specified at link time) or each time a process accesses the DLL ("INITINSTANCE" is specified at link 
time). Similarly, the termination routine can either be called when all processes have completed their 
access of the DLL ("TERMGLOBAL" is specified at link time) or each time a process completes its access 
of the DLL ("TERMINSTANCE" is specified at link time). 

For a DLL that uses the FORTRAN 77 run-time libraries, initialization and termination of the FORTRAN 
77 run-time environment is performed automatically. It is also possible for a DLL to do its own special 
initialization and termination process. 

The FORTRAN 77 run-time environment provides a method for calling user-written DLL initialization and 

termination code. The_ fdll_ initialize_ routine is called for DLL process initialization. The 

_fdll_ terminate_ routine is called for DLL process termination. Default stub versions of these 

routines are included in the run-time library. If you wish to perform additional initialization/termination 
processing that is specific to your dynamic link library, you may write your own versions of these routines. 

Once the FORTRAN 77 run-time environment is initialized, the routine_fdll_ initialize_ is 

called. After the FORTRAN 77 run-time environment is terminated, the routine_ f dll_ terminate. 

is called. This last point is important since it means that you cannot do any run-time calls in the termination 
routine. 

The initialization and termination routines return an integer. A value of 0 indicates failure; a value of 1 
indicates success. The following example illustrates sample initialization/termination routines. 

* DLLINIT.FOR 

integer function_fdll_ initialize_ () 

integer_fdll_ terminate_ , dll_ entry 

integer WORKING_ SIZE 

parameter ( WORKING_ SIZE = 16*1024 ) 
integer ierr, WorkingStorage 
dimension WorkingStorage(:) 

allocate ( WorkingStorage (WORKING_ SIZE) , stat=ierr ) 
if( ierr .eq. 0 )then 

_fdll_ initialize_ = 1 

else 

_fdll_ initialize_ = 0 

endif 

return 


Dynamic Link Library Initialization/Termination 223 





OS/2 Programming Guide 


entry_fdll_ terminate_ () 

* Note: no run-time calls allowed under OS/2 Warp 
deallocate( WorkingStorage ) 

_fdll_ terminate_ = 1 

return 

entry dll_ entry () 

! use WorkingStorage 
return 

end 


In the above example, the process initialization routine allocates storage that the dynamic link library needs, 
the routine dll_ entry uses the storage, and the process termination routine frees the storage allocated in 
the initialization routine. 
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34 Programming for OS/2 Presentation Manager 


Basically, there are two classes of FORTRAN 77 applications that can run in a windowed environment. 

The first are those FORTRAN 77 applications that do not use any of the Presentation Manager API 
functions; they are strictly FORTRAN 77 applications that do not rely on the features of a particular 
operating system. 

The second class of FORTRAN 77 applications are those that actually call Presentation Manager API 
functions directly. These are applications that have been tailored for the Presentation Manager operating 
environment. 

It is assumed that the reader is familiar with the concepts of Presentation Manager programming. 

34.1 Porting Existing FORTRAN 77 Applications 

Suppose you have a set of FORTRAN 77 applications that previously ran under DOS and you now wish to 
run them under OS/2. To achieve this, simply recompile your application and link with the appropriate 
libraries. Depending on the method with which you linked your application, it can run in an OS/2 
fullscreen environment, a PM-compatible window, or as a Presentation Manager application. An OS/2 
fullscreen application runs in its own screen group. A PM-compatible application will run in an OS/2 
fullscreen environment or in a window in the Presentation Manager screen group but does not take direct 
advantage of menus, mouse or other features available in the Presentation Manager. A Presentation 
Manager application has full access to the complete set of user-interface tools such as menus, icons, scroll 
bars, etc. However, porting a console oriented application to Presentation Manager often requires 
significant effort and a substantial redesign of the application. 

34.1.1 An Example 

Very little effort is required to port an existing FORTRAN 77 application to OS/2. Let us try to run the 
following sample program (contained in the file hello . for). 

print *, 'Hello world!' 
end 

First we must compile the file hello . for by issuing the following command. 

[C:\]wfc386 hello 

Once we have successfully compiled the file, we can link it by issuing the following command. 

[C:\]wlink sys os2v2 file hello 
It is also possible to compile and link in one step, by issuing the following command. 

[C:\]wf1386 -1=os2v2 hello 
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This will create a PM-compatible application. If you wish to create a fullscreen application, link with the 
following command. 

[C:\]wlink sys os2v2 fullscreen file hello 

34.2 Calling Presentation Manager API Functions 

It is also possible for a FORTRAN 77 application to create its own windowing environment. This is 
achieved by calling PM API functions directly from your FORTRAN 77 program. The techniques for 
developing these applications can be found in the OS/2 Technical Library. 

A number of FORTRAN 77 include files (files with extension . f i or . fap) are provided which define 
Presentation Manager data structures and constants. They are located in the 

\watcom\src\fortran\os2 directory. These include files are equivalent to the C header files that 
are available with the IBM OS/2 Developer’s Toolkit. 

A sample FORTRAN 77 Presentation Manager application is also located in the 
\watcom\samples\fortran\os2 directory. It is contained in the files f shapes . for and 
f shapes . f i . The file fshapes . for contains the following. 

c$def ine INCL_ WINFRAMEMGR 
c$def ine INCL_ WINMESSAGEMGR 
c$def ine INCL_ WINWINDOWMGR 
c$def ine INCL_ WINTIMER 
c$define INCL_ GPIPRIMITIVES 
c$include os2.fap 

program fshapes 


integer style 

record /QMSG/ qmsg 


character*7 watcom 

parameter (watcom='WATCOM'c) 

include 'fshapes.fi' 


AnchorBlock = Winlnitialize( 0 ) 
if( AnchorBlock .eq. 0 ) stop 

hMessageQueue = WinCreateMsgQueue( AnchorBlock, 0 ) 
if( hMessageQueue .eq. 0 ) stop 

if( WinRegisterClass( AnchorBlock, watcom, MainDriver, 

+ CS_ SIZEREDRAW, 0 ) .eq. 0 ) stop 

style = FCF_ TITLEBAR .or. FCF_ SYSMENU .or. FCF_ SIZEBORDER .or. 
+ FCF_ MINMAX .or. FCF_ SHELLPOSITION .or. FCF_ TASKLIST 

FrameHandle = WinCreateStdWindow ( HWND_ DESKTOP, WS_ VISIBLE, 

+ style, watcom, 

+ char(0), 0, NULL, 

+ 0, WinHandle ) 

if( FrameHandle .eq. 0 ) stop 


while( WinGetMsg( AnchorBlock, qmsg, NULL, 0, 0 ) ) do 

call WinDispatchMsg( AnchorBlock, qmsg ) 
end while 


call WinDestroyWindow( FrameHandle ) 
call WinDestroyMsgQueue( hMessageQueue ) 
call WinTerminate( AnchorBlock ) 

end 
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function MainDriver( hwnd, msg, mpl, mp2 ) 

integer hwnd 
integer msg 
integer mpl 
integer mp2 

include 'fshapes.fi' 

integer ps 

record /RECTL/ rcl 

select case ( msg ) 
case ( WM_ CREATE ) 

WinHandle = hwnd 

call WinStartTimer( AnchorBlock, WinHandle, 1, 150 ) 
case ( WM_ TIMER ) 

call DrawEllipse() 

MainDriver = 0 
return 

case ( WM_ SIZE ) 

SizeX = SHORT1FROMMP( mp2 ) 

SizeY = SHORT2FROMMP( mp2 ) 

MainDriver = 0 
return 

case ( WM_ PAINT ) 

ps = WinBeginPaint( WinHandle, NULL, NULL_ POINTER ) 
call WinQueryWindowRect( WinHandle, rcl ) 
call WinFillRect ( ps, rcl, CLR_ WHITE ) 
call WinEndPaint( ps ) 

MainDriver = 0 
return 
end select 

MainDriver = WinDefWindowProc( WinHandle, msg, mpl, mp2 ) 
return 

end 

subroutine DrawEllipse 


record /POINTL/ ptl 

integer ps 

integer Odd /0/ 

integer parml 

integer parm2 


include 'fshapes.fi' 

ps = WinGetPS( WinHandle ) 
ptl.x = Random( SizeX ) 
ptl.y = Random( SizeY ) 
call GpiMove( ps, ptl ) 
ptl.x = Random( SizeX ) 
ptl.y = Random( SizeY ) 
parml = Random( 32767 ) 
parm2 = Random( 32767 ) 
if( Random( 10 ) .ge. 5 ) then 
execute NewColor 

call GpiBox ( ps, DRO_ FILL, ptl, 0, 0 ) 
execute NewColor 

call GpiBox ( ps, DRO_ OUTLINE, ptl, 0, 0 ) 

else 

execute NewColor 

call GpiBox ( ps, DRO_ FILL, ptl, parml, parm2 ) 
execute NewColor 

call GpiBox ( ps, DRO_ OUTLINE, ptl, parml, parm2 ) 
end if 
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Odd = Odd + 1 

Odd = Odd .and. 1 

call WinReleasePS( ps ) 

remote block NewColor 

call GpiSetColor( ps. Random( 15 ) + 1 ) 
end block 

end 

integer function Random( high ) 
integer high 

external urand 

real urand 

integer seed /75347/ 

Random = urand( seed ) * high 

end 


The include file f shapes . f i contains the following. 



include 'os2.fi' 



integer SizeX 

integer SizeY 



integer FrameHandle 

integer WinHandle 

integer hMessageQueue 

integer AnchorBlock 


common /globals/ 


+ 

SizeX, 


+ 

SizeY, 


+ 

FrameHandle, 


+ 

WinHandle, 


+ 

hMe s s ageQueue, 


+ 

AnchorBlock 



external 

Random 


integer 

Random 


external 

MainDriver 


integer 

MainDriver 

c$pragma aux (FNWP) 

MainDriver 


Notes: 

1. Include files with extension . fap define the calling conventions for each of the OS/2 API 
functions. These files must be included at the top of each FORTRAN 77 source module. 

2. Include files with extension . f i define the data structures and constants used by the OS/2 API 
functions. These files must be included in each subprogram that requires them. 

3. Each call-back function (i.e. window procedure) must be defined using the following pragma. 

c$pragma aux (FNWP) WindowProc 

4. The include file os 2 . fap is included at the beginning of the source file and os2 . f i is 
included in each subprogram. Also note that a number of macros were defined at the top of the 
file. By defining these macros, only those components of the OS/2 API required by the module 
will be compiled. 

You can compile, link and run this demonstration by issuing the following commands. 
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[C:\]set finclude=\watcom\src\fortran\os2 
[C:\]wfl386 -1=os2v2_ pm fshapes 
[C:\]fshapes 
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35 Creating NetWare 386 NLM Applications 


Open Watcom FORTRAN 77 supports version 4.0 of the Netware 386 API. We include the following 
components: 

header files Header files for the Netware 4.0 API are located in the \WATCOM\NOVH directory. 

import libraries 

Import libraries for the Netware 4.0 API are located in the \WATCOM\NOVI directory. 

libraries The FORTRAN 77 libraries for Netware 4.0 is located in the \WATCOM\LIB38 6 and 

\WATCOM\LIB386\NETWARE directories. 

debug servers Servers for remote debugging of Netware 4.0 NLMs are located in the \WATCOM\NLM 
directory. The same directory also contains the Open Watcom Execution Sampler for 
NLMs. 

Applications built for version 4.0 will run on 4.1. We do not include support for any API specific to 
version 4.1. Netware developers must use the support included with Open Watcom FORTRAN 77 version 
10.0 or greater since the version supplied by Novell only works with Open Watcom FORTRAN 77 version 
9.5. Netware 4.1 support requires modification to the header files supplied by Novell. Contact Novell for 
more information. 

The following special notes apply to developing applications for NetWare. 

1. You must compile your source files with the small memory model option ("ms"). 

2. You must compile your source files with the stack-based calling convention option ("sc"). 

3. You must specify 

system NETWARE 

when linking an NLM. This is automatic if you are using WLL386 and the "-1=NETWARE" 
option. 
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36 Inter-Language calls: C and FORTRAN 


The purpose of this chapter is to anticipate common questions about mixed-language development using 
Open Watcom C/C++ and Open Watcom FORTRAN 77. 

The following topics are discussed in this chapter: 

• Symbol Naming Convention 

• Argument Passing Convention 

• Memory Model Compatibility 

• Integer Type Compatibility 

• How do I pass integers from C to a FORTRAN function? 

• How do I pass integers from FORTRAN to a C function? 

• How do I pass a string from a C function to FORTRAN? 

• How do I pass a string from FORTRAN to a C function? 

• How do I access a FORTRAN common block from within C? 

• How do I call a C function that accepts a variable number of arguments? 

36.1 Symbol Naming Convention 

The symbol naming convention describes how a symbol in source form is mapped to its object form. 
Because of this mapping, the name generated in the object file may differ from its original source form. 

Default symbol naming conventions vary between compilers. Open Watcom C/C++ prefixes an underscore 
character to the beginning of variable names and appends an underscore to the end of function names 
during the compilation process. Open Watcom FORTRAN 77 converts symbols to upper case. Auxiliary 
pragmas can be used to resolve this inconsistency. 

Pragmas are compiler directives which can provide several capabilities, one of which is to provide 
information used for code generation. When calling a FORTRAN subprogram from C, we want to instruct 
the compiler NOT to append the underscore at the end of the function name and to convert the name to 
upper case. This is achieved by using the following C auxiliary pragma: 

♦pragma aux ftnname " A "; 

The " A " character tells the compiler to convert the symbol name "ftnname" to upper case; no underscore 
character will be appended. This solves potential linker problems with "ftnname" since (by C convention) 
the linker would attempt to resolve a reference to "ftnname_". 
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When calling C functions from FORTRAN, we need to instruct the compiler to add the underscore at the 
end of the function name, and to convert the name to lower case. Since the FORTRAN compiler 
automatically converts identifiers to uppercase, it is necessary to force the compiler to emit an equivalent 
lowercase name. Both of these things can be done with the following FORTRAN auxiliary pragma: 

*$pragma aux CNAME "!_ " 

There is another less convenient way to do this as shown in the following: 

*$pragma aux CNAME "cname_ " 

In the latter example, the case of the name in quotation marks is preserved. 

Use of these pragmas resolves the naming differences, however, the issue of argument passing must still be 
resolved. 


36.2 Argument Passing Convention 

In general, C uses call-by-value (passes argument values) while FORTRAN uses call-by-reference (passes 
pointers to argument values). This implies that to pass arguments to a FORTRAN subprogram we must 
pass the addresses of arguments rather than their values. C uses the "&" character to signify "address of". 

Example: 

result = ftnname( &arg ) ; 

When calling a C function from FORTRAN, the pragma used to correct the naming conventions must also 
instruct the compiler that the C function is expecting values, not addresses. 

*$pragma aux CNAME "!_ " parm (value) 

The "parm (value)" addition instructs the FORTRAN compiler to pass values, instead of addresses. 

Character data (strings) are an exception to the general case when used as arguments. In C, strings are not 
thought of as a whole entity, but rather as an "array of characters". Since strings are not considered scalar 
arguments, they are referenced differently in both C and FORTRAN. This is described in more detail in a 
following section. 


36.3 Memory Model Compatibility 

While it is really not an issue with the 32-bit compilers (both use the default "flat" memory model), it is 
important to know that the default memory model used in Open Watcom FORTRAN 77 applications is the 
"large" memory model ("ml") with "medium" and "huge" memory models as options. Since the 16-bit 
Open Watcom C/C++ default is the "small" memory model, you must specify the correct memory model 
when compiling your C/C++ code with the 16-bit C or C++ compiler. 
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36.4 Linking Considerations 

When both C/C++ and FORTRAN object files are combined into an executable program or dynamic link 
library, it is important that you list a least one of the FORTRAN object files first in the Open Watcom 
Linker (WLINK) "FILES" directive to guarantee the proper search order of the FORTRAN and C run-time 
libraries. If you place a C/C++ object file first, you may inadvertently cause the wrong version of run-time 
initialization routines to be loaded by the linker. 

36.5 Integer Type Compatibility 

In general, the number of bytes used to store an integer type is implementation dependent. In FORTRAN, 
the default size of an integer type is always 4 bytes, while in C/C++, the size is architecture dependent. The 
size of an "int" is 2 bytes for the 16-bit Open Watcom C/C++ compilers and 4 bytes for the 32-bit 
compilers while the size of a "long" is 4 bytes regardless of architecture. It is safest to prototype the 
function in C, specifying exactly what size integers are being used. The byte sizes are as follows: 

1. LONG-4 bytes 

2. SHORT - 2 bytes 

Since FORTRAN uses a default of 4 bytes, we should specify the "long" keyword in C for integer types. 
Example: 

long int ftnname( long int *, long int *, long int * ); 

In this case, "ftnname" takes three "pointers to long ints" as arguments, and returns a "long int". By 
specifying that the arguments are pointers, and not values, and by specifying "long int" for the return type, 
this prototype has solved the problems of argument passing and integer type compatibility. 


36.6 How do I pass integers from Ctoa FORTRAN function? 

The following Open Watcom C/C++ routine passes three integers to a FORTRAN function that returns an 
integer value. 


/* MIX1C.C - This C program calls a FORTRAN function to 

* compute the max of three numbers. 

★ 


* Compile/Link: 

★ 

*/ 


wcl /ml 
wcl386 


mixlc mixlf.obj 
mixlc mixlf.obj 


/fe=mixl 
/fe=mixl 


♦include <stdio.h> 


♦pragma aux tmax3 " A "; 

long int tmax3( long int *, long int *, 


long int * ); 
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void main() 

{ 

long int result; 
long int i, j, k; 

1 = -i; 
j = 12; 
k = 5; 

result = tmax3( &i, &j, &k ); 
printf ( "Maximum is %ld\n", result ); 

} 

The FORTRAN function: 

* MIX1F.F0R - This FORTRAN function accepts three integer 

* arguments and returns their maximum. 

* Compile: wfc[386] mixlf.for 

integer function tmax3( arga, argb, argc ) 
integer arga, argb, argc 

tmax3 = arga 

if ( argb .gt. tmax3 ) tmax3 = argb 
if ( argc .gt. tmax3 ) tmax3 = argc 
end 


36.7 How do I pass integers from FORTRAN to a C function? 

The following Open Watcom FORTRAN 77 routine passes three integers to a Open Watcom C/C++ 
function that returns an integer value. 

* MIX2F.F0R - This FORTRAN program calls a C function to 

* compute the max of three numbers. 

* 

* Compile/Link: wfl[386] mix2f mix2c.obj /fe=mix2 

*$pragma aux tmax3 "!_ " parm (value) 

program mix2f 

integer*4 tmax3 
integer*4 result 
integer*4 i, j, k 

i = -1 

j = 12 

k = 5 

result = tmax3( i, j, k ) 
print *, 'Maximum is ', result 
end 

The C function "tmax3" is shown below. 
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/* MIX2C.C - This C function accepts 3 integer arguments 

* and returns their maximum. 

★ 

* Compile: wcc /ml mix2c 

* wcc386 mix2c 
*/ 


long int tmax3( 

long int 

arga. 



long int 

argb. 

{ 

long int 


long int 

argc ) 


result; 


result = 

arga; 


if( argb 

> 

result ) 

result = argb; 

if( argc 

> 

result ) 

result = argc; 


return( result ) ; 

} 


36.8 How do I pass a string from a C function to FORTRAN? 

Character strings are referenced differently in C and FORTRAN. The C language terminates its strings 
with a null character as an End-Of-String (EOS) marker. In this case, C need not store the length of the 
string in memory. FORTRAN, however, does not use any EOS marker; hence it must store each string’s 
length in memory. 

The structure FORTRAN uses to keep track of character data is called a "string descriptor" which consists 
of a pointer to the character data (2, 4, or 6 bytes, depending on the data model) followed by an unsigned 
integer length (2 bytes or 4 bytes, depending on the data model). 


system option size of pointer size of length 


16-bit 

/MM 

16 bits 

16 

bits 

16-bit 

/ML 

32 bits 

16 

bits 

32-bit 

/MF 

32 bits 

32 

bits 

32-bit 

/ML 

48 bits 

32 

bits 


In order to access character data, FORTRAN needs to have access to the data’s string descriptor. Hence, 
FORTRAN expects a pointer to a string descriptor to be passed as an argument for character data. 

Passing string arguments between C and FORTRAN is a simple task of describing a struct type in C 
containing the two fields described above. The first field must contain the pointer to the character data, and 
the second field must contain the length of the string being passed. A pointer to this structure can then be 
passed to FORTRAN. 

* MIX3F.F0R - This FORTRAN program calls a function written 

* in C that passes back a string. 

* 

* Compile/Link: wfl[386] mix3f mix3c.obj /fe=mix3 

program mix3f 

character*80 sendstr 
character*80 cstring 
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cstring = sendstr() 

print *, cstring(1:lentrim(cstring)) 
end 

The C function "sendstr" is shown below. 

/* MIX3C.C - This C function passes a string back to its 

* calling FORTRAN program. 

★ 

* Compile: wcc /ml mix3c 

* wcc386 mix3c 
*/ 

♦include <string.h> 

♦pragma aux sendstr " A "; 

typedef struct descriptor { 
char *addr; 

unsigned len; 

} descriptor; 

void sendstr( descriptor *ftn_ str_ desc ) 

{ 

ftn_ str_ desc->addr = "This is a C string"; 

ftn_ str_ desc->len = strlen ( ftn_ str_ desc->addr ); 

} 


36.9 How do I pass a string from FORTRAN toaC function? 

By default, FORTRAN passes the address of the string descriptor when passing strings. If the C function 
knows it is being passed a string descriptor address, then it is very similar to the above example. If the C 
function is expecting normal C-type strings, then a FORTRAN pragma can be used to pass the string 
correctly. When the Open Watcom FORTRAN 77 compiler pragma to pass by value is used for strings, 
then just a pointer to the string is passed. 

Example: 

*$pragma aux cname "!_ " parm (value) 

The following example FORTRAN mainline defines a string, and passes it to a C function that prints it out. 

* MIX4F.F0R - This FORTRAN program calls a function written 

* in C and passes it a string. 

* 

* Compile/Link: wfl[386] mix4f mix4c.obj /fe=mix4 
*$pragma aux cstr "!_ " parm (value) 
program mix4f 
character*80 forstring 

forstring = 'This is a FORTRAN string'//char(0) 

call cstr ( forstring ) 

end 
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The C function: 

/* MIX4C.C - This C function prints a string passed from 

* FORTRAN. 

★ 

* Compile: wcc /ml mix4c 

* wcc386 mix4c 
*/ 

♦include <stdio.h> 

void cstr( char *instring ) 

{ 

printf( "%s\n", instring ); 

} 

36.10 How do I access a FORTRAN common block from 
within C? 

The following code demonstrates a technique for accessing a FORTRAN common block in a C routine. 
The C routine defines an extern struct to correspond to the FORTRAN common block. 

* MIX5F.F0R - This program shows how a FORTRAN common 

* block can be accessed from C. 

* 

* Compile/Link: wfl[386] mix5f mix5c.obj /fe=mix5 

program mix5f 
external put 
common/cblk/i,j 

i=12 

j=10 

call put 

print *, 'i = ', i 
print *, ' j = ' , j 
end 

The C function: 

/* MIX5C.C - This code shows how to access a FORTRAN 

* common block from C. 

* 

* Compile: wcc /ml mix5c 

* wcc386 mix5c 
*/ 

♦include <stdio.h> 

♦pragma aux put " A "; 

♦pragma aux cblk " A "; 
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#ifdef _ 386_ 

♦define FAR 
♦ else 

♦define FAR far 
♦endif 


extern struct cb { 
long int i,j; 

} FAR cblk; 

void put( void ) 

{ 

printf ( "i = %ld\n", cblk.i ); 
printf ( "j = %ld\n", cblk.j ); 
cblk.i++; 
cblk.j++; 

} 


For the 16-bit C compiler, the common block "cblk" is described as far to force a load of the segment 
portion of the address. Otherwise, since the object is smaller than 32K (the default data threshold), it is 
assumed to be located in the DGROUP group which is accessed through the SS segment register. 


36.11 How do I call a C function that accepts a variable 
number of arguments? 

One capability that C possesses is the ability to define functions that accept variable number of arguments. 
This feature is not present, however, in the definition of the FORTRAN 77 language. As a result, a special 
pragma is required to call these kinds of functions. 

*$pragma aux printf "!_ " parm (value) caller [] 

The "caller" specifies that the caller will pop the arguments from the stack. The "[]" indicates that there are 
no arguments passed in registers because the printf function takes a variable number of arguments 
passed on the stack. The following example is a FORTRAN function that uses this pragma. It calls the 
printf function to print the value 47 on the screen. 

* MIX6.F0R - This FORTRAN program calls the C 

* printf function. 

* Compile/Link: wfl[386] mix6 

*$pragma aux printf "!_ " parm (value) caller [] 
program mix6 

character cr/zOd/, nullchar/zOO/ 

call printf ( 'Value is %ld.'//cr//nullchar, 47 ) 
end 

For more information on the pragmas that are used extensively during inter-language programming, please 
refer to the chapter entitled "Pragmas" in both the Open Wcitcom C/C++ User’s Guide and the Open 
Watcom FORTRAN 77 User’s Guide. 
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37 Commonly Asked Questions and Answers 


As with any sophisticated piece of software, there are topics that are not directly addressed by the 
descriptive portions of the manuals. The purpose of this chapter is to anticipate common questions 
concerning Open Watcom F77. It is difficult to predict what topics will prove to be useful but with that in 
mind, we hope that this chapter will help our customers make full use of Open Watcom F77. 

A number of example programs are presented throughout. The source text for these files can be found in 
the \WATCOM\SAMPLES\GOODIES directory. 

The purpose of this chapter is to present some of the more commonly asked questions from our users and 
the answers to these questions. The following topics are discussed: 

• How do I determine my current patch level? 

• How do I convert to Open Watcom F77? 

• What should I know about optimization? 

• How do I read a stream of binary data from a file? 

• How do I redefine math error handling with Open Watcom F77? 

• Why can’t the compiler find my include files? 

• Why does the linker report a "stack segment not found" error? 

• How do I resolve an "Undefined Reference" linker error? 

• Why aren't local variable values maintained between subprogram calls? 

• What does "Stack Overflow!" mean? 

• What are the probable causes of a General Protection Fault in 32-bit applications? 

• Which floating-point compiler option should I use for my application? 

• How can I open more than 20 files at a time? 

• How can I see my source files in the debugger? 

• What is the difference between the "dl" and "d2" compiler options? 

• What is the difference between the "debug" and "d2" compiler options? 

37.1 Determining my current patch level 

In an effort to immediately correct any problems discovered in the originally shipped product. Open 
Watcom provides patches as a continued service to its customers. To determine the current patch level of 
your Open Watcom software, a TECHINFO utility program has been provided. This program will display 
your current environment variables, the patch level of various Open Watcom software programs, and other 
pertinent information, such as your AUTOEXEC. BAT and CONFIG. SYS files. This information proves to 
be very useful when reporting a problem to the Technical Support team. 

To run TECHINFO, you must ensure the Open Watcom environment variable has been set to the directory 
where your Open Watcom software has been installed. TECHINFO will pause after each screenful of 
information. The output is also placed in the file TECHINFO. OUT. 

Below is an example of some partial output produced by running the TECHINFO utility: 
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Example: 

WATCOM's Techinfo Utility, Version 1.4 
Current Time: Thu Oct 27 15:58:34 1994 


WATCOM 

415 Phillip St. 
Waterloo, Ontario 
CANADA N2L 3X2 


Phone: (519) 884-0702 
Fax: (519) 747-4971 


-WATCOM C Environment Variables - 

WATCOM=<c:\watcom> 

EDPATH=<c:\watcom\eddat> 

INCLUDE=<c:\watcom\h;c:\watcom\h\os2> 

FINCLUDE=<c:\watcom\src\fortran;c:\watcom\src\fortran\win> 
LIBOS2=<c:\watcom\lib28 6\os2;c:\watcom\lib28 6> 

PATH=<c:\dos;c:\windows;c:\watcom\binw> 

TMP=<h:\temp> 

File 'c:\watcom\binw\wcc386.exe' has been patched to level ' .d' 

...etc... 


In this example, the software has been patched to level "d". In most cases, all tools will share a common 
patch level. However, there are instances where certain tools have been patched to one level while others 
are patched to a different level. For example, the compiler may be patched to level "d" while the debugger 
is only patched to level "c". Basically, this means that there were no debugger changes in the D-level 
patches. 

If you run the TECHINFO utility, and determine that you are not at the current patch level, it is 
recommended that you update your software. Patches are available on Open Watcom’s bulletin board. 
Open Watcom’s FTP site and CompuServe. They are available 24 hours a day. Patches are also available 
on the current release CD-ROM. Each patch will include a batch file that allows you to apply the patches 
to your existing software. Note that patches must be applied in sequential order, as each patch depends on 
the previous one. 


37.2 Converting to Open Watcom F77 

Applications written in ANSI standard FORTRAN 77 code usually only need to be recompiled with the 
Open Watcom F77 compiler. In addition to the ANSI standard, many compilers support specific 
extensions. If you are porting code from a UNIX platform or other DOS compilers, check Appendix A - 
Extensions to Standard FORTRAN 77 of the Open Watcom FORTRAN 77 Language Reference, to 
determine which FORTRAN 77 extensions are supported. 

By default, most FORTRAN 77 compilers preserve the values of local variables in a subprogram between 
calls. With Open Watcom F77, local variables are kept on the stack and their values are popped from the 
stack when exiting a subprogram. To preserve local variables, use the FORTRAN 77 SAVE statement for 
variables that you wish to preserve, or the "save" compiler option to preserve all local variables. Note that 
the use of the "save" compiler option causes an overall performance degradation. 

Open Watcom F77 uses register-based parameter passing as a default, however, the compiler is flexible 
enough to use different calling conventions on a per function basis. Auxiliary pragmas can be used to 
specify the calling convention that is to be used to interface with assembler code. This enables you to 
explicitly state how parameters are to be passed to the assembler code. This topic is described in the 
"Pragmas" chapter of the Open Watcom F77 User’s Guide under "Describing Argument Information". See 
also the chapter entitled "Inter-Language calls: C and FORTRAN" on page 237. 
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37.3 What you should know about optimization 

The Open Watcom F77 User’s Guide contains a detailed description for each of the optimization options 
supported by the compiler. These options allow you to customize the type of code optimizations that are 
performed. For instance, the "OS" option can be used to reduce the size of your code, but this may affect 
the execution speed. To ensure that the speed of the code is optimized, possibly at the cost of code size, use 
the "OT" option. The "OX" option, intended for the maximum number of optimizations, generates code 
that is a combination of "OM" (inline math functions), "OL" (loop), "OT" (time) and the "OR" (instruction 
scheduling) optimization options. Note that when you are using the "OM" option to generate inline math 
functions no argument validation will be done for the intrinsic math functions such as "sin" or "cos". 
Consider the needs of your application and select the optimization options that best meet your 
requirements. 


Hint: The definitive reference on compiler design is the "dragon" book "Compilers - Principles, 
Techniques, and Tools", Alfred V. Aho, Ravi Sethi, and Jeffrey D. Ullman, published by 
Addison-Wesley, Reading, Massachusetts, 1986. The authors of the "dragon" book advocate a 
conservative approach to code generation where optimizations must preserve the semantics of the 
original program. The conservative approach is used throughout the Open Watcom F77 compiler to 
ensure that programmers can use the compiler without worrying about the semantics of their program 
being changed. 


There are certain pieces of information which the compiler cannot derive from the source code. The 
"*$pragma" compiler directive is used to provide extra information to the compiler. It is necessary to have 
a complete understanding of both FORTRAN 77 and the machine architecture (i.e., 80x86) before using the 
powerful pragma compiler directives. See the "Pragmas" chapter in the Open Watcom F77 User’s Guide 
for more details. 

Debugging optimized programs is difficult because variables can be assigned to different locations (i.e., 
memory or registers) in different parts of the function. The "d2" compiler option will restrict the amount of 
optimization so that variables occupy one location and can be easily displayed. It follows that the "d2" 
option is useful for initial development but production programs should be compiled with only the "dl" 
option for the best code quality. Before you distribute your application to others, you may wish to use the 
Open Watcom Strip Utility (WSTRIP) to remove debugging information from the executable image on disk 
thereby reducing disk space requirements. 


Hint: The "d2" compiler option will generate symbolic information (for every local variable) and line 
number information for the source file. The "dl" compiler option will only generate line number 
information for the source file. The use of these options determines what kind of information will be 
available for the particular module during the debugging session. 


37.4 Reading a stream of binary data from a file 

The Open Watcom F77 allows for three types of binary data file formats: 
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* Variable length, unformatted sequential access binary records, 

* Fixed length, unformatted direct access binary records, and 

* Unformatted, sequential, binary data with a fixed record type. 

Variable length binary records are preceded by a four byte descriptor that indicates the length of the record 
in bytes. The end of the binary record is also marked by another descriptor tag specifying the length. 
Binary records that are of a fixed length are kept in a direct access, unformatted file. Refer to the Open 
Watcom F77 User’s Guide section on File Handling for more information on file formats. 

Binary data files that have no structure or record length information may be read if you open the file as a 
sequential, unformatted file with a fixed record type. This allows you to read files that contain a stream of 
binary data without any inherent record format. If you know the type of data that is contained in the binary 
file, you may then read the binary data directly into variables. The following program provides an example 
of reading binary stream data. 

* BINDATA.FOR - This program demonstrates how to read a 

* binary data file that does not have any defined records. 

program bindata 

integer BinArray(20) 
integer i 

open( unit=l, file='bindata.fil', 

+ access='sequential', 

+ form='unformatted' , 

+ recordtype='fixed' ) 

* Read 20 integers from the binary data file 

do i = 1, 20 

read( 1 ) BinArray( i ) 
end do 

* Write the extracted values to standard output 

do i = 1, 20 

write( *, * ) BinArray! i ) 
end do 
end 


37.5 Redefining math error handling with Open Watcom F77 

If you wish to customize math error handling for your application, you can create your own math error 
handling procedure. The following illustrates the procedures for trapping errors by way of an example. 

See the Open Watcom F77 User’s Guide for a description of the f signal subroutine and math library 
error handling. 

The main program example "MATHDEMO" is a FORTRAN program that contains a floating-point divide 
by zero error, a floating-point overflow error, a floating-point underflow error, and an invalid argument to a 
math library function. 
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program mathdemo 

* MATHDEMO.FOR - This program forms part of a collection of FORTRAN 

* code that demonstrates how to take over control of 

* math error handling from the run-time system. 

* Compile: wfl[386] mathdemo cw87 _ matherr 

* Notes: 

* (1) We call "cw87" to enable underflow exceptions which are 

* masked (ignored) by default. 

* (2) The signal handler must be re-installed after each signal 

* (it can also be re-installed even when there is no signal). 

* (3) To prevent compile-time constant folding in expressions, 

* we add log(1.0) which is 0. We do this for the sake of 

* demonstrating exception handling. 

implicit none 

double precision x, y, z 

call cw87 ! init 80x87 control word 

call resetFPE ! install signal handler 

print *, ' ' 

print *, 'Divide by zero will be attempted' 
x = l.OdO + DLOG( l.OdO ) 
y = O.OdO 
z = x / y 

call chkFPE ! check for exception 

print *, z 

call resetFPE ! install signal handler 

print *, ' ' 

print *, 'Overflow will be attempted' 
x = 1.2d300 + DLOG( l.OdO ) 
y = 1.2d300 
z = x * y 

call chkFPE ! check for exception 

print *, z 

call resetFPE ! install signal handler 

print *, ' ' 

print *, 'Underflow will be attempted' 
x = 1.14d-300 + DLOG( l.OdO ) 
y = 2.24d-308 
z = x * y 

call chkFPE ! check for exception 

print *, z 

call resetFPE ! install signal handler 

print *, ' ' 

print *, 'Math error will be attempted' 
x = -12.0 

! an exception will not be generated since the intrinsic function 
! will validate the argument - if you compile with /om, the "fsqrt 
! 80x87 instruction will be generated in-line and an exception 
! will occur 
y = SQRT( x ) 

call chkFPE ! check for exception 

print *, x, y 

end 
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subroutine resetFPE 

include 'fsignal.fi' 

external fpe_ handler 

logical fpe_ flag 

integer fpe_ sig, fpe_ fpe 

common fpe_ flag, fpe_ sig, fpe_ fpe 

fpe_ flag = .false. 

call fsignal ( SIGFPE, fpe_ handler ) 
end 

*$pragma aux fpe_ handler parm ( value ) 

subroutine fpe_ handler ( sig, fpe ) 

integer sig, fpe 

logical fpe_ flag 

integer fpe_ sig, fpe_ fpe 

common fpe_ flag, fpe_ sig, fpe_ fpe 

fpe_ flag = .true. 

fpe_ sig = sig 

fpe_ fpe = fpe 

end 

*$pragma aux fwait = "fwait" 

subroutine chkFPE 

include 'fsignal.fi' 

logical fpe_ flag 

integer fpe_ sig, fpe_ fpe 

common fpe_ flag, fpe_ sig, fpe_ fpe 

* Notes: 

* (1) An fwait is required to make sure that the last 

* floating-point instruction has completed. 

* (2) "volatile" is not needed here but would be 

* needed in main program if it references "fpe_ flag" 
call fwait() 

if( volatile ( fpe_ flag ) ) then 

print *, '*ERROR* exception occurred', 

& fpe_ sig, fpe_ fpe 

if ( fpe_ fpe .eq. FPE_ INVALID ) then 
print *, 'Invalid' 

else if ( fpe_ fpe .eq. FPE_ DENORMAL ) then 
print *, 'Denormalized operand error' 
else if ( fpe_ fpe .eq. FPE_ ZERODIVIDE ) then 
print *, 'Divide by zero error' 
else if ( fpe_ fpe .eq. FPE_ OVERFLOW ) then 
print *, 'Overflow error' 
else if ( fpe_ fpe .eq. FPE_ UNDERFLOW ) then 
print *, 'Underflow error' 
else if ( fpe_ fpe .eq. FPE_ INEXACT ) then 

print *, 'Inexact result (precision)then error' 
else if ( fpe_ fpe .eq. FPE_ UNEMULATED ) then 
print *, 'Unemulated instruction error' 
else if ( fpe_ fpe .eq. FPE_ SQRTNEG ) then 

print *, 'Square root of a negative number error' 
else if ( fpe_ fpe .eq. FPE_ STACKOVERFLOW ) then 
print *, 'NDP stack overflow error' 
else if ( fpe_ fpe .eq. FPE_ STACKUNDERFLOW ) then 
print *, 'NDP stack underflow error' 
else if ( fpe_ fpe .eq. FPE_ EXPLICITGEN ) then 
print *, 'SIGFPE signal raised (software)' 
else if ( fpe_ fpe .eq. FPE_ IOVERFLOW ) then 
print *, 'Integer overflow error' 
endif 
else 

print *, ' *OK* no exception occurred' 
endif 
end 


The following subroutine illustrates how to enable or disable particular types of floating-point exceptions. 
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subroutine cw87 

* CW87.FOR 

* This subroutine uses the C Library routine control87" 

* to modify the math coprocessor exception mask. 

* Compile: wfc[386] cw87 

include 'fsignal.fi' 

character*9 status(0:1)/' disabled',' enabled'/ 
integer fp_ cw, fp_ mask, bits, i 

* Enable floating-point underflow since default is disabled. 

* The mask defines which bits we want to change (1 means change, 

* 0 means do not change). The corresponding bit in the control 

* word (fp_ cw) is set to 0 to enable the exception or 1 to disable 

* the exception. In this example, we change only the underflow 

* bit and leave the others unchanged. 

fp_ mask = EM_ UNDERFLOW ! mask for the bits to set/reset 
fp_ cw = '0000'x ! new bit settings (0=enable/l=disable) 

fp_ cw = _ control87 ( fp_ cw, fp_ mask ) 

* Now get up-to-date setting 

fp_ cw = _ control87(0,0) 
bits = I AND ( fp_ cw, MCW_ EM ) 

print '(a,lx,z4)', 'Interrupt Exception Mask', bits 
i = 0 

if ( IAND (fp_ cw, EM_ INVALID) .eq. 0 ) i = 1 
print *, ' Invalid Operation exception', status(i) 
i = 0 

if ( IAND (fp_ cw, EM_ DENORMAL) .eq. 0 ) i = 1 
print *, ' Denormalized exception', status (i) 
i = 0 

if ( IAND (fp_ cw, EM_ ZERODIVIDE) .eq. 0 ) i = 1 
print *, ' Divide-By-Zero exception', status(i) 
i = 0 

if ( IAND (fp_ cw, EM_ OVERFLOW) .eq. 0 ) i = 1 
print *, ' Overflow exception', status (i) 
i = 0 

if ( IAND (fp_ cw, EM_ UNDERFLOW) .eq. 0 ) i = 1 
print *, ' Underflow exception', status (i) 
i = 0 

if ( IAND (fp_ cw, EM_ PRECISION) .eq. 0 ) i = 1 
print *, ' Precision exception', status (i) 
end 


The following subroutine illustrates how to replace the run-time system’s math error handler. Source code 
similar to this example is provided with the software (look for the file _ matherr . for). 

★ 

* _ MATHERR.FOR : math error handler 

* Compile: wfc[386] _ matherr 


*$pragma aux 
*$pragma aux 
*$pragma aux 
*$pragma aux 
*$pragma aux 
*$pragma aux 
*$pragma aux 


imath2err "*_ " parm( value, reference, reference ) 

amathlerr " parm( value, reference ) 

amath2err " parm( value, reference, reference ) 

mathlerr "*_ " parm( value, reference ) 
math2err " parm( value, reference, reference ) 

zmath2err " parm( value, reference, reference ) 

qmath2err " parm( value, reference, reference ) 


Redefining math error handling with Open Watcom F77 253 




Common Problems 


integer function_imath2err ( err_ info, argi, arg2 ) 

integer err_ info 
integer argi, arg2 
include 'mathcode.fi' 

argi = argi ! to avoid unreferenced warning message 

arg2 = arg2 ! to avoid unreferenced warning message 

if ( ( err_ info .and. M_ DOMAIN ) .ne. 0 ) then 
select ( err_ info .and. FUNC_ MASK ) 
case ( FUNC_ POW ) 

print *, 'arg2 cannot be <= 0' 
case ( FUNC_ MOD ) 

print *, 'arg2 cannot be 0' 
end select 
end if 

_ imath2err = 0 

end 


real function_amathlerr ( err_ info, argi ) 

integer err_ info 
real argi 

include 'mathcode.fi' 

argi = argi ! to avoid unreferenced warning message 

if ( ( err_ info .and. M_ DOMAIN ) .ne. 0 ) then 
select ( err_ info .and. FUNC_ MASK ) 
case ( FUNC_ COTAN ) 

print *, 'overflow' 
end select 
end if 

_amathlerr = 0.0 

end 


real function_amath2err ( err_ info, argi, arg2 ) 

integer err_ info 
real argi, arg2 
include 'mathcode.fi' 

argi = argi ! to avoid unreferenced warning message 

arg2 = arg2 ! to avoid unreferenced warning message 

if ( ( err_ info .and. M_ DOMAIN ) .ne. 0 ) then 
select ( err_ info .and. FUNC_ MASK ) 
case ( FUNC_ MOD ) 

print *, 'arg2 cannot be 0' 
end select 
end if 

_amath2err = 0.0 

end 


double precision function_mathlerr ( err_ info, argi ) 

integer err_ info 

double precision argi, _math2err 

_mathlerr =_math2err ( err_ info, argi, argi ) 

end 


double precision function_math2err ( err_ info, argi, arg2 ) 

integer err_ info 

double precision argi, arg2 

include 'mathcode.fi' 

argi = argi ! to avoid unreferenced warning message 

arg2 = arg2 ! to avoid unreferenced warning message 


254 Redefining math error handling with Open Watcom F77 




Commonly Asked Questions and Answers 


if ( ( err_ info .and. M_ DOMAIN ) .ne. 0 ) then 
select ( err_ info .and. FUNC_ MASK ) 
case ( FUNC_ SQRT ) 

print *, 'argument cannot be negative' 
case ( FUNC_ASIN, FUNC_ ACOS ) 

print *, 'argument must be less than or equal to one' 
case ( FUNC_ AT AN2 ) 

print *, 'both arguments must not be zero' 
case ( FUNC_ POW ) 

if( argl .eq. 0.0 )then 

print *, 'a zero base cannot be raised to a ', 

& 'negative power' 

else ! base < 0 and non-integer power 

print *, 'a negative base cannot be raised to a ', 

& 'non-integral power' 

endif 

case ( FUNC_ LOG, FUNC_ LOGIO ) 

print *, 'argument must not be negative' 
end select 

else if ( ( err_ info .and. M_ SING ) .ne. 0 ) then 

if ( ( ( err_ info .and. FUNC_ MASK ) .eq. FUNC_ LOG ) .or. 

& ( ( err_ info .and. FUNC_ MASK ) .eq. FUNC_ LOGIO ) ) then 

print *, 'argument must not be zero' 
endif 

else if ( ( err_ info .and. M_ OVERFLOW ) .ne. 0 ) then 

print *, 'value of argument will cause overflow condition' 
else if ( ( err_ info .and. M_ UNDERFLOW ) .ne. 0 ) then 
print *, 'value of argument will cause underflow ', 

& 'condition - return zero' 

end if 

_ math2err = 0 

end 


complex function_zmath2err ( err_ info, argl, arg2 ) 

integer err_ info 
complex argl, arg2 
include 'mathcode.fi' 

argl = argl ! to avoid unreferenced warning message 

arg2 = arg2 ! to avoid unreferenced warning message 

if ( ( err_ info .and. M_ DOMAIN ) .ne. 0 ) then 
select ( err_ info .and. FUNC_ MASK ) 
case ( FUNC_ POW ) 

! argl is (0,0) 

if( imag( arg2 ) .ne. 0 )then 

print *, 'a zero base cannot be raised to a', 
& ' complex power with non-zero imaginary part' 

else 

print *, 'a zero base cannot be raised to a', 
& ' complex power with non-positive real part' 

endif 
end select 
end if 

_zmath2err = (0,0) 

end 
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double complex function_qmath2err ( err_ info, argl, arg2 ) 

integer err_ info 
double complex argl, arg2 
include 'mathcode.fi' 

argl = argl ! to avoid unreferenced warning message 

arg2 = arg2 ! to avoid unreferenced warning message 

if ( ( err_ info .and. M_ DOMAIN ) .ne. 0 ) then 
select ( err_ info .and. FUNC_ MASK ) 
case ( FUNC_ POW ) 

! argl is (0,0) 

if( imag( arg2 ) .ne. 0 )then 

print *, 'a zero base cannot be raised to a', 

& ' complex power with non-zero imaginary part' 

else 

print *, 'a zero base cannot be raised to a', 

& ' complex power with non-positive real part' 

endif 
end select 
end if 

_qmath2err = (0,0) 

end 


37.6 The compiler cannot find my include files 

In order to locate your INCLUDE files, the compiler first searches your current directory, then each 
directory listed in the FINCLUDE environment variable (in the order that they are specified). If the 
compiler reports that it is unable to find one of your include files, change the FINCLLTDE environment 
variable by adding the directory path to your include files. For more information on setting the 
environment variable, refer to the "Compiling an Application" chapter of the Open Watcom F77 User’s 
Guide. 


37.7 The linker reports a “stack segment not found" error 

The linker usually reports the error "1014: stack segment not found" when it is unable to find the run-time 
libraries required to link your application. To ensure you are linking with the correct run-time libraries, 
check to see that your link command contains the correct "SYSTEM" directive. As well, the WATCOM 
environment variable should be pointing to the directory containing the Open Watcom F77 software. For a 
Open Watcom F77 application, if this error is followed by the error "1023: no starting address found", it 
may indicate that you are attempting to link code that does not have a main program procedure. Ensure that 
you include your main program object module with your linker directives. 

With FORTRAN 77, "STACK" is a reserved word. If you use "STACK" as the name of a common block, 
this may also result in the "Stack Segment Not Found" error. Check the names of your common blocks and 
rename them if necessary. 

37.8 Resolving an "Undefined Reference" linker error 

The Open Watcom Linker builds an executable file by a process of resolving references to functions or data 
items that are declared in other source files. Certain conditions arise that cause the linker to generate an 
"Undefined Reference" error message. An "Undefined Reference" error message will be displayed by the 
linker when it cannot find a function or data item that was referenced in the program. Verify that you have 
included all the required object modules in the linker command and that you are linking with the correct 
libraries. 
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The "SYSTEM" linker directive should be used to indicate the target environment for the executable. This 
directive specifies the format of the executable and the libraries for the target environment. Verify that the 
WATCOM environment variable is set to the directory that Open Watcom F77 was installed in since it is 
used to complete the library path in the "SYSTEM" directive. You may also explicitly include a library 
using the "LIBRARY" linker directive. 

If the linker reports an unresolved reference for "_cstart_", this indicates that the linker could not find the 
FORTRAN 77 run-time libraries. In 16-bit applications, the FORTRAN 77 run-time libraries for the 
medium memory model (/mm) and the floating-point calls floating-point model (/fpc) would be 
f libm. lib. In 32-bit applications, the FORTRAN 77 run-time libraries for the flat memory model 
would be f 1 ib . 1 ib . Verify that the "LIB" environment variable has been set to point to the correct 
WATCOM library directories and that the library corresponds to the memory and floating-point model that 
you selected. 

37.9 Why local variable values are not maintained between 
subprogram calls 

By default, the local variables for a subprogram are stored on the stack and are not initialized. When the 
subprogram returns, the variables are popped off the stack and their values are lost. If you want to preserve 
the value of a local variable, after the execution of a RETURN or END statement in a subprogram, the 
FORTRAN 77 SAVE statement or the "save" compiler option can be used. 

Using the FORTRAN 77 SAVE statement in your program allows you to explicitly select which values you 
wish to preserve. The SAVE statement ensures that space is allocated for a local variable from static 
memory and not the stack. Include a SAVE statement in your FORTRAN 77 code for each local variable 
that you wish to preserve. 

To automatically preserve all local variables, you can use the "save" compiler option. This option adds 
code to initialize and allocate space for each local variable in the program. This is equivalent to specifying 
a SAVE statement. The "save" option makes it easier to ensure that all the variables are preserved during 
program execution, but it increases the size of the code that is generated. You may wish to use this option 
during debugging to help diagnose bugs caused by corrupted local values. Usually, it is more efficient to 
use SAVE statements rather than the general "save" compiler option. You should selectively use the SAVE 
statement for each subprogram variable that you want to preserve until the next call. This leads to smaller 
code than the "save" option and avoids the overhead of allocating space and initializing values 
unnecessarily. 


37.10 What “Stack Overflow!" means 


The memory used for local variables is allocated from the function call stack although the Open Watcom 
compilers will often use registers for local variables. The size of the function call stack is limited at 
link-time and it is possible to exceed the amount of stack space during execution. 

There are various ways of protecting against stack overflow errors. First, one should minimize the number 
of recursive functions used in an application program. This can be done by recoding recursive functions to 
use loops. 

The user may also optionally force the compiler to use static storage for all local variables (Open Watcom 
F77 "save" option). This would eliminate most stack problems for FORTRAN programs. These 
techniques will reduce the amount of stack space required but there still may be times where the default 
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amount of stack space is insufficient. The Open Watcom Linker (WLINK) allows the user to set the 
amount of stack space at link-time through the directive "OPTION STACK=size" where size may be 
specified in bytes with an optional "k" suffix for kilobytes (1024 bytes). 

Example: 

option stack=9k 

Note that with the Open Watcom F77 run-time system, the I/O routines require 4k of stack space. If your 
application requires 5K of stack space, set aside 9K to allow for 4K of I/O stack space in addition to the 
stack space required by the application. 

Debugging a program that reports a stack overflow error can be accomplished with the following sequence. 

1. Load your application into the debugger 

2. Set a breakpoint at_ STKOVERFLOW 

3. Run the application until the breakpoint at_ STKOVERFLOW is triggered 

4. Issue the debugger "show calls" command. This will display a stack traceback giving you the 
path of calls that led up to the stack overflow situation. 

The solution to the stack overflow problem at this point depends on the programmer. 

37.11 What are the probable causes of a General Protection 
Fault in 32-bit applications? 

If you are running a 32-bit application using DOS/4GW, a program crash may report an "Unexpected 
Interrupt 0D" general protection fault error. The Phar Lap DOS extender would report an "Abnormal 
Program Termination" general protection fault error. This often indicates that something in your program 
has tried to access an invalid memory location. In a Open Watcom F77 application, the most likely causes 
of a general protection fault are: 

• Attempting to access an array out of bounds. 

• Running out of stack space. 

• Passing incorrect parameter types to a function. 

To help locate the cause of the protection fault, compile your program with the "debug" and "stack" 
options. With these options, code will be added to your application to help identify these problems and 
generate run-time error messages when they are encountered. In addition, the "stack" option checks for 
stack overflow conditions by including code at the beginning of each subprogram. 

If you still encounter general protection faults after compiling with "debug" and "stack", then debug the 
program using the debugger. This will help to identify the location of the crash and the state of your 
parameters and variables at the time of the crash. 
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37.12 Which floating-point compiler option should I use for 
my application? 

The answer to this question depends on the expected target machines for your application. If you know that 
a co-processor will be available, use the "fpi87" compiler option to optimize the run-time performance of 
the application. 

When you are running a FORTRAN 77 application on a machine with or without a co-processor and you 
want to favour the use of emulation libraries over code size, use the "fpc" option. The "fpc" option will 
also take advantage of an 80x87 co-processor if it is available. If your application needs to be flexible 
enough to run either with or without a co-processor, the "fpc" option is recommended. 

The "fpi" option is the default floating-point option and can be used with or without a co-processor. On 
machines that do not have a co-processor, you may notice that programs compiled using "fpc" run faster 
than those compiled with "fpi". This occurs because the "fpc" option uses the floating-point libraries 
directly whereas the "fpi" option interfaces with an emulator interrupt handler. Although the "fpi" option is 
slower than "fpc" without a co-processor, the code that it generates is smaller. 

When you are running an application that has been compiled with "fpi", the startup code checks to 
determine whether a math co-processor is present. If it is not present, the emulator hook is installed at the 
INT 7h interrupt to manage the co-processor requests and convert them to the emulation library calls. Each 
time a floating-point operation is requested, the processor issues an INT 7h. 

For 16-bit applications, the interrupt handler overhead accounts for the performance discrepancy between 
the "fpc" and "fpi" options. 

For 32-bit applications, the manner in which this interrupt is handled depends on the DOS extender. 
Depending on the DOS extender, there are two methods of managing floating-point instructions through the 
interrupt handler. The DOS extender will either pass the interrupt directly to the INT 7h handler or it will 
perform some intermediary steps. Similarly, there is a delay after the interrupt as control is passed back 
through the DOS extender. Passing floating-point handling from the DOS extender to the interrupt handler 
results in the performance degradation. This performance degradation may vary across DOS extenders. It 
is the overhead of transferring the call through an interrupt that leads to the speed difference between "fpi" 
and "fpc". If you need to run an application on machines without math co-processors, and you want to 
ensure that your performance is optimal, build your application using the "fpc" option rather than "fpi". 

In a Windows environment, both the "fpi87" and the "fpi" options will use floating-point emulation if a 
co-processor is not available. Windows floating-point emulation is provided through Open Watcom’s 
"WEMU387.386". "WEMU387.386" is royalty free and may be redistributed with your application. For 
machines that do not have a math co-processor, install "WEMU387.386" as a device in the [386Enh] 
section of the Windows SYSTEM.INI file to handle the floating-point operations. Note that the speed of 
code using "WEMU387.386" on machines without a co-processor will be much slower than code compiled 
with the "fpc" option that always uses floating-point libraries. 
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37.13 How more than 20 files at a time can be opened 

The number of file handles allowed by Open Watcom F77 is initialized to 20 in stdio . h, but this can be 
changed by the application developer. To change the number of file handles allowed with Open Watcom 
F77, follow the steps outlined below. 

1. Let n represent the number of files the application developer wishes to have open. Ensure that 
the stdin, stdout, stderr, stdaux, and stdprn files are included in the count. 

2. Change the CONFIG. SYS file to include "files=n" where "n" is the number of file handles 
required by the application plus an additional 5 handles for the standard files (this applies to 
DOS 5.0). The number "n" may vary depending on your operating system and version. If you 
are running a network such as Novell's NetWare, this will also affect the number of available 
file handles. In this case, you may have to increase the number specified in the "files=n" 
statement. 

3. Add a call to GROWHANDLES in your application. 

The following example illustrates the use of GROWHANDLES . 

Example: 

* FHANDLES.FOR 

★ 

* This FORTRAN program grows the number of file handles so 

* more than 16 files can be opened. This program 

* illustrates the interaction between GROWHANDLES and 

* the DOS 5.0 file system. If you are running a network 

* such as Novell's NetWare, this will also affect the 

* number of available file handles. In the actual trial, 

* FILES=40 was specified in CONFIG.SYS. 


* Compile/Link: set finclude=\watcom\src\fortran 

* wfl[386] fhandles 

* Get proper typing information from include file 
include 'fsublib.fi' 

integer i, j, maxh, maxo 
integer tmpfile 
integer units (7:57) 


do i = 25, 40 

Count 5 for stdin, stdout, stderr, stdaux, 

and stdprn 

print 100, 5 + i 

maxh = growhandles( 5 + i ) 

print *, 'Growhandles=',maxh 

maxo = 0 
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do j = 7, 7 + maxh 

print *, 'Attempting file', j 
units (j) = tmpfile(j) 
if( units(j) .eq. 0 )goto 10 
maxo = maxo + 1 
enddo 


10 print 101, maxo, maxh 

do j = 7, 7 + maxo 

close( units(j) ) 

enddo 
enddo 

100 format('Trying for ',12,' handles... ',$) 

101 format(12,'/',12,' temp files opened') 
end 


integer function tmpfile( un ) 
integer un, ios 

open( unit=un, status=' SCRATCH' , iostat=ios ) 
if( ios .eq. 0 )then 

write ( unit=un, fmt=' (12)', err=20 ) un 
tmpfile = un 
return 
endif 

20 tmpfile = 0 
end 


37.14 How source files can be seen in the debugger 

The selection and use of debugging information is important for getting the most out of the Open Watcom 
Debugger. If you are not able to see your source code in the Open Watcom Debugger source window, 
there are three areas where things may have gone wrong, namely: 

1. using the correct option for the Open Watcom F77. 

2. using the correct directives for the Open Watcom Linker. 

3. using the right commands in the Open Watcom Debugger. 

The Open Watcom F77 compiler takes FORTRAN 77 source and creates an object file containing the 
generated code. By default, no debugging information is included in the object file. The compiler will 
output debugging information into the object file if you specify a debugging option during the compile. 
There are two levels of debugging information that the compiler can generate: 

1. Line numbers and local variables ("d2" option) 

2. Line numbers ("dl" option) 

The options are used to determine how much debugging information will be visible when you are 
debugging a particular module. If you use the "d2" option, you will be able to see your source file and 
display your local variables. The "dl" option will display the source but will not give you access to local 
variable information. 

The Open Watcom Linker (WLINK) is the tool that puts together a complete program and sets up the 
debugging information for all the modules in the executable file. There is a linker directive that indicates to 
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the linker when it should include debugging information from the modules. There are five levels of 
debugging information that can be collected during the link. These are: 

1. global names (DEBUG) 

2. global names, line numbers (DEBUG LINE) 

3. global names, types (DEBUG TYPES) 

4. global names, local variables (DEBUG LOCALS) 

5. all of the above (DEBUG ALL) 

Notice that global names will always be included in any request for debugging information. The debugging 
options can be combined 

DEBUG LINE, TYPES 

with the above directive resulting in full line number and typing information being available during 
debugging. The directives are position dependent so you must precede any object files and libraries with 
the debugging directive. For instance, if the file my link. Ink contained: 

# 

# invoke with: wlink Smylink 

# 

file main 

debug line 

file input, output 

debug all 

file process 

then the modules input and output will have global names and source line information available during 
debugging. All debugging information in the module process will be available during debugging. 


Hint: A subtle point to debugging information is that all the modules will have global names available 
if any debugging directive is used. In the above example, the module main will have global name 
information even though it does not have a DEBUG directive preceding it. 


It is preferable to have one DEBUG directive before any FILE and LIBRARY directives. You might 
wonder if this increases the size of the executable file so that it will occupy too much memory during 
debugging. The debugging information is loaded "on demand" by the debugger during the debugging 
session. A small amount of memory (40k default, selectable with the Open Watcom Debugger "dynamic" 
command line option) is used to hold the most recently used module debugging information. In practice, 
this approach saves a lot of memory because most debugging information is never used. The overhead of 
accessing the disk for debugging information is negligible compared to accessing the source file 
information. In other words, you can have as much debugging information as you want included in the 
executable file without sacrificing memory required by the program. See the section entitled "The DEBUG 
Directive" in the Open Watcom Linker User’s Guide for more details. 

If the previous steps have been followed, you should be well on your way to debugging your programs with 
source line information. There are instances where the Open Watcom Debugger cannot find the 
appropriate source file even though it knows all the line numbers. The problem that has surfaced involves 
how the source file is associated with the debugging information of the module. The original location of 
the source file is included in the debugging information for a module. The name that is included in the 
debugging information is the original name that was on the Open Watcom F77 command line. If the 
original filename is no longer valid (i.e., you have moved the executable to another directory), the Open 
Watcom Debugger must be told where to find the source files. The Open Watcom Debugger "Source Path" 
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menu item (under "File") can be used to supply new directories to search for source files. If your source 
files are located in two directories, the following paths can be added in the Open Watcom Debugger: 

c:\program\fortran\*.for 
c:\program\new\fortran\*.for 

The character indicates where the module name will be inserted while the Open Watcom Debugger is 
searching for the source file. See the description of the "Source Path" menu item in the Open Watcom 
Debugger User’s Guide for more details. 

37.15 The difference between the "dl" and "d2" compiler 
options 

The reason that there are two levels of debugging information available is that the code optimizer can 
perform many more optimizations and still maintain "dl" (line) information. The "d2" option forces the 
code optimizer to ensure that any local variable can be displayed at any time in the function. 

The "d2" option will always generate code and debugging information so that you can print the value of 
any variable during the execution of the function. In order to get the best code possible and still see your 
source file while debugging, the "dl" option only generates line number information into the object file. 
With line number information, much better code can be generated. The debugging of programs that have 
undergone extensive optimization can be difficult, but with the source line information it is much easier. 

To summarize, use the "d2" compiler option if you are developing a module and you would like to be able 
to display each local variable. The "dl" compiler option will give you line number information and the best 
generated code possible. There is absolutely no reason not to specify the "dl" option because the code 
quality will be identical to code generated without the "dl" option. 

37.16 The difference between the "debug" and "d2" compiler 
options 

The "d2" (and "dl") compiler options are used to add debugging information to your executable. The "d2" 
option makes line numbering, local symbol and typing information available to the debugger whereas "dl" 
only provides line number debugging information to the debugger. This information is used during a 
debugging session to examine the state of variables and to provide the source code display. 

The "debug" option provides run-time error messages that are independent of the Open Watcom Debugger. 
The "debug" option causes the generation of run-time error checking code. This includes subscript and 
substring bounds checking as well as code that allows a run-time traceback to be issued when an error 
occurs. During the execution of the application, if an error occurs, the code added with the "debug" option 
will halt the program and provide an informative error message. 
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1 The Open Watcom FORTRAN 77 Compile and 
Link Utility 


The Open Watcom FORTRAN 77 Compile and Link Utility is designed for generating applications, simply 
and quickly, using a single command line. On the command line, you can list source file names as well as 
object file names. Source files are compiled; object files and libraries are simply included in the link phase. 
Options can be passed on to both the compiler and linker. 


1.1 WFL/WFL386 Command Line Format 

The format of the command line is: 


WFL [files] [options] 
WFL386 [files] [options] 


The square brackets [ ] denote items which are optional. 

WFL is the name of the Open Watcom Compile and Link utility that invokes the 16-bit compiler. 

WFL386 is the name of the Open Watcom Compile and Link utility that invokes the 32-bit compiler. 

The files and options may be specified in any order. The Open Watcom Compile and Link utility uses the 
extension of the file name to determine if it is a source file, an object file, or a library file. Files with 
extensions of "OBJ" and "LIB" are assumed to be object files and library files respectively. Files with any 
other extension, including none at all, are assumed to be FORTRAN 77 source files and will be compiled. 
Pattern matching characters ("*" and "?") may be used in the file specifications. If no file extension is 
specified for a file name then "FOR" is assumed. 

Options are prefixed with a slash (!) or a dash (—) and may be specified in any order. Options can include 
any of the Open Watcom F77 compiler options plus some additional options specific to the Open Watcom 
Compile and Link utility. Certain options can include a "NO" prefix to disable an option. A summary of 
options is displayed on the screen by simply entering the "WFL" or "WFL386" command with no 
arguments. 


1.2 Open Watcom Compile and Link Options Summary 

General options: Description: 

C compile the files only, do not link them 

Y ignore the WFL/WFL386 environment variable 
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Compiler options: 

0 

1 

2 

3 

4 

5 

6 

[NO]ALign 
[NO]Automatic 
BD 
BM 

[NOJBOunds 

BW 

[NO ICC 

CHInese 

[NOJCOde 

D1 

D2 

[NO]DEBug 
DEFine=<macro> 
[NO[DEPendency 
[NO [DEScriptor 
Disk 

DT=<size> 

[NO[ERrorfile 
[NO[EXPlicit 
[NO]Extensions 
[NO]EZ 

FO=<obj_default> 

[NO [EORmat 

FPC 

FPD 

FPI 

FPI87 

FPR 

FP2 

FP3 

FP5 

FP6 

[NOJFSjloats 

[NO [GSfloots 

HC 

HD 

HW 

[NO]INCList 
INC Path =[d: [path 
[NO [I Promote 
Japanese 
KOrean 
[NO[LFwithff 


Description: 

(16-bit only) assume 8088/8086 processor 
(16-bit only) assume 188/186 processor 
(16-bit only) assume 286 processor 
assume 386 processor 
assume 486 processor 
assume Pentium processor 
assume Pentium Pro processor 
align COMMON segments 
all local variables on the stack 
(32-bit only) dynamic link library 
(32-bit only) multithread application 
generate subscript bounds checking code 
(32-bit only) default windowed application 

carriage control recognition requested for output devices such as the console 

Chinese character set 

constants in code segment 

include line # debugging information 

include full debugging information 

perform run-time checking 

define macro 

generate file dependencies 

pass character arguments using string descriptor 

write listing file to disk 

set data threshold 

generate an error file 

declare type of all symbols 

issue extension messages 

(32-bit only) Easy OMF-386 object files 

set default object file name 

relax format type checking 

generate calls to floating-point library 

enable generation of Pentium FDIV bug check code 

generate inline 80x87 instructions with emulation 

generate inline 80x87 instructions 

floating-point backward compatibility 

generate inline 80x87 instructions 

generate inline 80387 instructions 

optimize floating-point for Pentium 

optimize floating-point for Pentium Pro 

FS not fixed 

GS not fixed 

CodeView debugging information 
DWARF debugging information 
Open Watcom debugging information 
write content of INCLUDE files to listing 
[d:]path... path for INCLUDE files 

promote INTEGER* 1 and INTEGER*2 arguments to INTEGER*4 
Japanese character set 
Korean character set 
LF with FF 
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[NOJLIBinfo 

include default library information in object file 

[NOJLISt 

generate a listing file 

[NOJMAngle 

mangle COMMON segment names 

MC 

(32-bit only) compact memory model 

MF 

(32-bit only) flat memory model 

MH 

(16-bit only) huge memory model 

ML 

large memory model 

MM 

medium memory model 

MS 

(32-bit only) small memory model 

OB 

(32-bit only) base pointer optimizations 

OBP 

branch prediction 

OC 

do not convert "call" followed by "ret" to "jmp" 

OD 

disable optimizations 

ODO 

DO-variables do not overflow 

OF 

always generate a stack frame 

OH 

enable repeated optimizations (longer compiles) 

OI 

generate statement functions in-line 

OK 

enable control flow prologues and epilogues 

OL 

perform loop optimizations 

OL+ 

perform loop optimizations with loop unrolling 

OM 

generate floating-point 80x87 math instructions in-line 

ON 

numeric optimizations 

OP 

precision optimizations 

OR 

instruction scheduling 

OS 

optimize for space 

OT 

optimize for time 

OX 

equivalent to OBP, ODO, OI, OK, OL, OM, OR, and OT (16-bit) or OB, OBP, ODO, 
OI, OK, OL, OM, OR, and OT (32-bit) 

PRint 

write listing file to printer 

[NOJQuiet 

operate quietly 

[NOJReference 

issue unreferenced warning 

[NO IRESource 

messages in resource file 

[NOJSAve 

SAVE local variables 

[NOJSC 

(32-bit only) stack calling convention 

[NO[SEpcomma 

allow comma separator in formatted input 

[NO]SG 

(32-bit only) automatic stack growing 

[NO]SHort 

set default INTEGER/LOGICAL size to 2/1 bytes 

[NO]SR 

save/restore segment registers 

[NOJSSfloats 

(16-bit only) SS is not default data segment 

[NO]S Tack 

generate stack checking code 

[NOJSYntax 

syntax check only 

[NO ITErminal 

messages to terminal 

[NO]TRace 

generate code for run-time traceback 

TYpe 

write listing file to terminal 

[NO] WArn ings 

issue warning messages 

[NO]WILd 

relax wild branch checking 

[NO [Windows 

(16-bit only) compile code for Windows 

[NO]XFloat 

extend floating-point precision 

[NOJXLine 

extend line length to 132 
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Linker options: Description: 

FD[=<directive Jile>] keep directive file and, optionally, rename it (default name is "_WFL_.LNK"). 

FE=<executable> name executable file 

FI=<fn> include additional directive file 

FM[=<map_Jile>] generate map file and, optionally, name it 
K=<stack_size> set stack size 

LP (16-bit only) create an OS/2 protected-mode program 

LR (16-bit only) create a DOS real-mode program 

L=<system_name> link a program for the specified system. Among the supported systems are: 

286 16-bit DOS executables (synonym for "DOS") under DOS and NT 

hosted platforms; 16-bit OS/2 executables (synonym for "OS2") under 
32-bit OS/2 hosted OS/2 session. 

386 32-bit DOS executables (synonym for "DOS4G") under DOS; 32-bit 

NT character-mode executables (synonym for "NT") under Windows 
NT; 32-bit OS/2 executables (synonym for "OS2V2") under 32-bit 
OS/2 hosted OS/2 session. 

COM 16-bit DOS "COM" files 

DOS 16-bit DOS executables 

DOS4G 32-bit Tenberry Software DOS Extender executables 

DOS4GNZ 32-bit Tenberry Software DOS Extender non-zero base executables 

NETWARE 32-bit Novell NetWare 386 NLMs 

NOVELL 32-bit Novell NetWare 386 NLMs (synonym for NETWARE) 

NT 32-bit Windows NT character-mode executables 

NT_DLL 32-bit Windows NT DLLs 

NT_WIN 32-bit Windows NT windowed executables 

OS2 16-bit OS/2 Vl.x executables 

OS2_DLL 16-bit OS/2 DLLs 

OS2_PM 16-bit OS/2 PM executables 

OS2V2 32-bit OS/2 executables 

OS2V2_DLL 32-bit OS/2 DLLs 

OS2V2_PM 32-bit OS/2 PM executables 

PHARLAP 32-bit PharLap DOS Extender executables 

QNX 16-bit QNX executables 

QNX386 32-bit QNX executables 

TNT 32-bit Phar Lap TNT DOS-style executable 

WIN386 32-bit extended Windows 3.x executables/DLLs 

WIN95 32-bit Windows 9x executables/DLLs 

WINDOWS 16-bit Windows executables 

WINDOWS_DLL 16-bit Windows Dynamic Link Libraries 
X32R 32-bit FlashTek (register calling convention) executables 

X32RV 32-bit FlashTek Virtual Memory (register calling convention) 

executables 

X32S 32-bit FlashTek (stack calling convention) executables 

X32SV 32-bit FlashTek Virtual Memory (stack calling convention) 

executables 

These names are among the systems identified in the Open Watcom Linker 
initialization file, "WLSYSTEM.LNK". The Open Watcom Linker "SYSTEM" 
directives, found in this file, are used to specify default link options for particular 
(operating) systems. Users can augment the Open Watcom Linker initialization file 
with their own system definitions and these may be specified as an argument to the 
"1=" option. The "system_name" specified in the "1=" option is used to create a 
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"SYSTEM system_name" Open Watcom Linker directive when linking the 
application. 

"-clinker directives>" specify additional linker directives 
A summary of the option defaults follows: 


0 

5 

ALign 

NO Automatic 

NOBOunds 

NOCC 

NOCOde 

NODEBug 

DEPendency 

DEScriptor 

DT=256 

ERrorfile 

NOEXPlicit 

NOEXtensions 

NOEZ 

NOFORmat 

FPI 

FP2 

FP3 

NOFPD 

FSfloats 

NOFSfloats 

GSfloats 

NOINCList 

NOIPromote 

NOLFwithff 

LIBinfo 

NOLISt 

NOMAngle 

ML 

MF 

NOQuiet 

Reference 

NORESource 

NOSAve 

NOSC 

NOSEpcomma 

NOSG 

NOSHort 

NOSR 

NOSSfloats 

NOSTack 

NOSYntax 

TErminal 

NOTRace 

WArnings 


16-bit only 
32-bit only 


32-bit only 


16-bit only 
32-bit only 

all but flat memory model 
flat memory model only 


16-bit only 
32-bit only 

32-bit only 
32-bit only 

16-bit only 
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NOWILd 

NOWIndows 16-bit only 

NOXFloat 

NOXLine 


1.3 WFUWFL386 Environment Variables 


The WFL environment variable can be used to specify commonly used WFL options. The WFL386 
environment variable can be used to specify commonly used WFL386 options. These options are 
processed before options specified on the command line. 

Example: 

C>set wfl=-dl -ot 
C>set wfl386=-dl -ot 

The above example defines the default options to be "dl" (include line number debugging information in 
the object file), and "ot" (favour time optimizations over size optimizations). 

Whenever you wish to specify an option that requires the use of an "=" character, you can use the "#" 
character in its place. This is required by the syntax of the "SET" command. 

Once the appropriate environment variable has been defined, those options listed become the default each 
time the WFL or WFL386 command is used. 

The WFL environment variable is used by WFL only. The WFL386 environment variable is used by 
WFL386 only. Both WFL and WFL386 pass the relevant options to the Open Watcom F77 compiler and 
linker. This environment variable is not examined by the Open Watcom F77 compiler or the linker when 
invoked directly. 


Hint: If you are running DOS and you use the same WFL or WFL386 options all the time, you may 
find it handy to place the "SET WFL" or "SET WFL386" command in your DOS system initialization 
file, AUTOEXEC . BAT . If you are running OS/2 and you use the same WFL or WFL386 options all 
the time, you may find it handy to place the "SET WFL" or "SET WFL386" command in your OS/2 
system initialization file, CONFIG. SYS . 


1.4 WFUWFL386 Command Line Examples 

For most small applications, the WFL or WFL386 command will suffice. We have only scratched the 
surface in describing the capabilities of the WFL and WFL386 commands. The following examples 
describe the WFL and WFL386 commands in more detail. 

Suppose that your application is contained in three files called apdemo .for, aputils .for, and 
apdata. for. We can compile and link all three files with one command. 

Example 1: 

C>wfl -d2 apdemo.for aputils.for apdata.for 
C>wfl386 -d2 apdemo.for aputils.for apdata.for 
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The executable program will be stored in apdemo . exe since apdemo appeared first in the list. Each of 
the three files is compiled with the "d2" debug option. Debugging information is included in the executable 
file. 

We can issue a simpler command if the current directory contains only our three FORTRAN 77 source 
files. 

Example 2: 

C>wfl -d2 *.for 
C>wf1386 -d2 *.for 

WFL or WFL386 will locate all files with the ".for" filename extension and compile each of them. The 
name of the executable file will depend on which of the FORTRAN 77 source files is found first. Since 
this is a somewhat haphazard approach to naming the executable file, WFL and WFL386 have an option, 
"fe", which will allow you to specify the name to be used. 

Example 3: 

C>wfl -d2 -fe=apdemo *.for 
C>wfl386 -d2 -fe=apdemo *.for 

By using the "fe" option, the executable file will always be called apdemo. exe regardless of the order of 
the FORTRAN 77 source files in the directory. 

If the directory contains other FORTRAN 77 source files which are not part of the application then other 
tricks may be used to identify a subset of the files to be compiled and linked. 

Example 4: 

C>wfl -d2 -fe=apdemo ap*.for 
C>wfl386 -d2 -fe=apdemo ap*.for 

Here we compile only those FORTRAN 77 source files that begin with the letters "ap". 

In our examples, we have recompiled all the source files each time. In general, we will only compile one of 
them and include the object code for the others. 

Example 5: 

C>wfl -d2 -fe=apdemo aputils.for ap*.obj 
C>wfl386 -d2 -fe=apdemo aputils.for ap*.obj 

The source file aputils . for is recompiled and apdemo . ob j and apdata. ob j are included when 
linking the application. The ".obj" filename extension indicates that this file need not be compiled. 

Example 6: 

C>wfl -fe=demo *.for utility.obj 
C>wfl386 -fe=demo *.for utility.obj 

All of the FORTRAN 77 source files in the current directory are compiled and then linked with 
utility . obj to generate demo.exe. 
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Example 7: 

C>set wfl=-mm -dl -op -k=4096 

C>wfl -fe=grdemo gr*.for graph.lib -fd=grdemo 
C>set wfl386=-dl -op -k=4096 

C>wfl386 -fe=grdemo gr*.for graph.lib -fd=grdemo 

All FORTRAN 77 source files beginning with the letters "gr" are compiled and then linked with 
graph. lib to generate grdemo . exe which uses a 4K stack. The temporary linker directive file that is 
created by WFL or WFL386 will be kept and renamed to grdemo . Ink . 

Example 8: 

C>set libos2=c:\watcom\lib2 86\os2 ; c:\os2 
C>set lib=c:\watcom\lib286\dos 
C>set wfl=-mm -lp 

C>wfl grdemol \watcom\lib286\os2\graphp.obj phapi.lib 

The file grdemol is compiled for the medium memory model and then linked with graphp. ob j and 
phapi . lib to generate grdemol. exe which is to be used with Phar Lap’s 286 DOS Extender. The 
"lp" option indicates that an OS/2 format executable is to be created. The file graphp. ob j in the 
directory "\WATCOM\LIB286\OS2" contains special initialization code for Phar Lap’s 286 DOS Extender. 
The file phapi . lib is part of the Phar Lap 286 DOS Extender package. The LIBOS2 environment 
variable must include the location of the OS/2 libraries and the LIB environment variable must include the 
location of the DOS libraries (in order to locate graph. lib). The LIBOS2 environment variable must 
also include the location of the OS/2 file doscalls . lib which is usually "C:\OS2". 

For more complex applications, you should use the "Make" utility. 
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2 The Open Watcom Assembler 


2.1 Introduction 

This chapter describes the Open Watcom Assembler. It takes as input an assembler source file (a file with 
extension ".asm") and produces, as output, an object file. 

The Open Watcom Assembler command line syntax is the following. 

WASM [options] [d:][path]filename[.ext] [options] [@env_var] 

The square brackets [ ] denote items which are optional. 

WASM is the name of the Open Watcom Assembler. 

d: is an optional drive specification such as "A:", "B:", etc. If not specified, the default drive 

is assumed. 

path is an optional path specification such as "\PROGRAMS\ASM\". If not specified, the 

current directory is assumed. 

filename is the file name of the assembler source file to be assembled. 

ext is the file extension of the assembler source file to be assembled. If omitted, a file 

extension of ".asm" is assumed. If the period "." is specified but not the extension, the file 
is assumed to have no file extension. 

options is a list of valid options, each preceded by a slash ("/") or a dash Options may be 

specified in any order. 

The options supported by the Open Watcom Assembler are: 

{0,l,2,3,4,5,6}{p}{r,s} 

0 same as ".8086" 

1 same as ".186" 

2{p} same as ".286" or ”.286p" 

3{p} same as ".386" or ".386p" (also defines "_386_" and changes the default 

USE attribute of segments from "USE16" to "USE32") 

4{p} same as ".486" or ".486p" (also defines "_386_" and changes the default 

USE attribute of segments from "USE16" to "USE32") 

5{p} same as ".586" or ".586p" (also defines "_386_" and changes the default 

USE attribute of segments from "USE16" to "USE32") 

6{p} same as ".686" or ".686p" (also defines "_386_" and changes the default 

USE attribute of segments from "USE16" to "USE32") 
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p 

protect mode 

add r 

defines "_REGISTER_" 

add s 

defines "_STACK_" 

Example: 

-2 

-3p -4pr -5p 


bt=<os> defines "_<os>_" and checks the "<os>_INCLUDE" environment variable for include 

files 

c do not output OMF COMENT records that allow WDISASM to figure out when data bytes 

have been placed in a code segment 
d<name>[=text] define text macro 
dl line number debugging support 

e stop reading assembler source file at END directive. Normally, anything following the 

END directive will cause an error. 
e<number> set error limit number 

fe=<file_name> set error file name 
fo=<file_name> set object file name 
fi=<file_name> force <file_name> to be included 


fpc 

same as ".no87" 

fpi 

inline 80x87 instructions with emulation 

fpi87 

inline 80x87 instructions 

fpO 

same as ".8087" 

fp2 

same as ".287" or ”.287p" 

fp3 

same as ".387" or ”.387p" 

fp5 

same as ".587" or ”.587p" 

fp6 

same as ".687" or ”.687p" 


i=<directory> add directory to list of include directories 

j or s force signed types to be used for signed values 

m{t,s,m,c,l,hj} memory model: (Tiny, Small, Medium, Compact, Large, Huge, Flat) 


-mt 

Same as ".model tiny" 

-ms 

Same as ".model small" 

-mm 

Same as ".model medium" 

-me 

Same as ".model compact" 

-ml 

Same as ".model large" 

-mh 

Same as ".model huge" 

-mf 

Same as ".model flat" 


Each of the model directives also defines "_<model>_" (e.g., ".model small" defines 

"_SMALL_"). They also affect whether something like "foo proc" is considered a "far" 

or "near" procedure. 

set data segment name 

set module name 

set name of text segment 

allow C form of octal constants 

set compatibility mode - watcom, masm or tasm, if <mode> is not specified then masm is 
used, default mode is watcom 
remove file dependency information 
operate quietly 

remove "@size" from STDCALL function names 

don't mangle STDCALL symbols (WASM backward compatible) 

print this message 


nd=<name> 

nm=<name> 

nt—<name> 

o 

zcm=<mode> 

zld 

zq or q 

zz 

zzo 

? or h 
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w<number> set warning level number 

we treat all warnings as errors 

wx set warning level to maximum setting 

2.2 Assembler Directives, Operators and Assembly Opcodes 

It is not the intention of this chapter to describe assembly-language programming in any detail. You should 
consult a book that deals with this topic. However, we present an alphabetically ordered list of the 
directives, opcodes and register names that are recognized by the assembler. 


.186 

.286 

.287 

.386 

.486 

. 48 6p 

. 686 

. 68 6p 

addr 

alias 

and 

assume 

casemap 

catstr 

comment 

.const 

. data 

.data? 

df 

.dosseg 

dq 

dt 

dword 

echo 

elseif 

end 

endm 

endp 

eq 

equ 

. errb 

.errdef 

. erre 

.erridn 

.errndef 

.errnz 

exitm 

extern 

far 

.fardata 

fore 

fword 

group 

gt 

. if 

if 

ifb 

if def 

ife 

if idn 

ifndef 

include 

irp 

irpe 

le 

length 

. list 

.listall 

.listmacroall 

local 

lroffset 

It 

.mmx 

mod 

ne 

near 

.nolist 

offset 

org 

oword 

proc 

proto 

purge 

pushcontext 

.radix 

record 

. sail 

sbyte 

segment 

. seq 

sizeof 

.stack 

struct 

subtitle 

tbyte 

textequ 

title 

typedef 

uses 

.while 


,286c 

. 28 6p 

. 386p 

.387 

.586 

. 586p 

.8086 

.8087 

align 

.alpha 

.break 

byte 

. code 

comm 

. continue 

. cref 

db 

dd 

dosseg 

dp 

dup 

dw 

. else 

else 

.endif 

endif 

ends 

. endw 

equ2 

. err 

.errdif 

.errdifi 

.erridni 

.errnb 

even 

. exit 

externdef 

extrn 

.fardata? 

for 

ge 

global 

high 

highword 

if 1 

if 2 

ifdif 

ifdifi 

ifidni 

if nb 

includelib 

invoke 

. k3d 

label 

lengthof 

. Ifcond 

. listif 

.listmacro 

low 

lowword 

macro 

mask 

.model 

name 

. no87 

. nocref 

opattr 

option 

page 

popcontext 

ptr 

public 

pword 

qword 

.repeat 

repeat 

sdword 

seg 

.sfcond 

size 

. startup 

struc 

subttl 

sword 

. tfcond 

this 

union 

. until 

width 

word 
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.xcref 

.xlist 

. xmm3 


aaa 

aad 

adc 

add 

addsd 

addss 

and 

andnpd 

andps 

arpl 

bsf 

bsr 

btc 

btr 

calif 

cbw 

cld 

elflush 

cmc 

cmova 

cmovbe 

cmovc 

cmovge 

cmovl 

cmovnae 

cmovnb 

cmovne 

cmovng 

cmovnle 

cmovno 

cmovnz 

cmovo 

cmovpo 

cmovs 

cmpeqpd 

cmpeqps 

cmplepd 

cmpleps 

cmpltpd 

cmpltps 

cmpneqpd 

cmpneqps 

cmpnlepd 

cmpnleps 

cmpnltpd 

cmpnltps 

cmpordpd 

cmpordps 

cmppd 

cmpps 

cmpsd 

cmpss 

cmpunordps 

cmpunordsd 

cmpxchg8b 

comisd 

cvtdq2pd 

cvtdq2ps 

cvtpd2ps 

cvtpi2pd 

cvtps2pd 

cvtps2pi 

cvtsi2sd 

cvtsi2ss 

cvttpd2dq 

cvttpd2pi 

cvttsd2si 

cvttss2si 

daa 

das 

divpd 

divps 

emms 

enter 

f add 

f addp 

f chs 

f clex 

fcmove 

fcmovnb 

fcmovnu 

fcmovu 

fcomip 

f comp 

fdecstp 

fdisi 

f divr 

fdivrp 

f f ree 

f iadd 

f idiv 

fidivr 

fincstp 

finit 

fisttp 

f isub 

fid 

fldl 

fldenvd 

fldenvw 

fldlg2 

fldln2 

fmul 

fmulp 

f neni 

fninit 

fnrstord 

fnrstorw 

fnsavew 

fnstcw 

fnstenvw 

fnstsw 


. xmm . xmm2 


aam 

aas 

addpd 

addps 

addsubpd 

addsubps 

andnps 

andpd 

bound 

bp 

bswap 

bt 

bts 

call 

cdq 

clc 

cli 

cits 

cmovae 

cmovb 

cmove 

cmovg 

cmovle 

cmovna 

cmovnbe 

cmovnc 

cmovnge 

cmovnl 

cmovnp 

cmovns 

cmovp 

cmovpe 

cmovz 

cmp 

cmpeqsd 

cmpeqss 

cmplesd 

cmpless 

cmpltsd 

cmpltss 

cmpneqsd 

cmpneqss 

cmpnlesd 

cmpnless 

cmpnltsd 

cmpnltss 

cmpordsd 

cmpordss 

cmps 

cmpsb 

cmpsw 

cmpunordpd 

cmpunordss 

cmpxchg 

comiss 

cpuid 

cvtpd2dq 

cvtpd2pi 

cvtpi2ps 

cvtps2dq 

cvtsd2si 

cvtsd2ss 

cvtss2sd 

cvtss2si 

cvttps2dq 

cvttps2pi 

cwd 

cwde 

dec 

div 

divsd 

divss 

f 2 xml 

f abs 

fbld 

fbstp 

fcmovb 

fcmovbe 

fcmovnbe 

fcmovne 

f com 

f comi 

fcompp 

f cos 

fdiv 

fdivp 

f emms 

feni 

f icom 

ficomp 

fild 

f imul 

fist 

f istp 

fisubr 

flat 

f ldcw 

fldenv 

fldl2e 

fldl2t 

f 1dpi 

f ldz 

fnclex 

fndisi 

f nop 

fnrstor 

fnsave 

fnsaved 

fnstenv 

fnstenvd 

fpatan 

fprem 
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fpreml 

fptan 

frndint 

frstor 

frstord 

frstorw 

f save 

fsaved 

fsavew 

fscale 

fsetpm 

f sin 

fsincos 

f sqrt 

f St 

f stew 

fstenv 

f stenvd 

fstenvw 

f stp 

f stsw 

f sub 

f subp 

f subr 

fsubrp 

ftst 

fucom 

fucomi 

fucomip 

fucomp 

fucompp 

fwait 

f xam 

fxch 

fxrstor 

fxsave 

fxtract 

fyl2x 

fyl2xpl 

haddpd 

haddps 

hit 

hsubpd 

hsubps 

idiv 

imul 

in 

inc 

ins 

insb 

insd 

insw 

int 

into 

invd 

invlpg 

iret 

iretd 

iretdf 

iretf 

ja 

jae 

jb 

jbe 

jc 

jcxz 

je 

jeexz 

jg 

jge 

jl 

jle 

jmp 

jmpf 

jna 

jnae 

jnb 

jnbe 

jnc 

jne 

jng 

jnge 

jnl 

jnle 

jno 

jnp 

jns 

jnz 

jo 

jP 

jpe 

jpo 

js 

jz 

lahf 

lar 

lddqu 

ldmxcsr 

Ids 

lea 

leave 

les 

Ifence 

lfs 

lgdt 

lgs 

lidt 

lldt 

lmsw 

lock 

lods 

lodsb 

lodsd 

lodsw 

loop 

loopd 

loope 

looped 

loopew 

loopne 

loopned 

loopnew 

loopnz 

loopnzd 

loopnzw 

loopw 

loopz 

loopzd 

loopzw 

lsl 

lss 

ltr 

maskmovdqu 

maskmovq 

maxpd 

maxps 

maxsd 

maxss 

mfence 

minpd 

minps 

minsd 

minss 

monitor 

mov 

movapd 

movaps 

movd 

movddup 

movdq2q 

movdqa 

movdqu 

movhlps 

movhpd 

movhps 

movlhps 

movlpd 

movlps 

movmskpd 

movmskps 

movntdq 

movnti 

movntpd 

movntps 

movntq 

movq 

movq2dq 

movs 

movsb 

movsd 

movshdup 

movsldup 

movss 

movsw 

movsx 

movupd 

movups 

movzx 

mul 

mulpd 

mulps 

mulsd 

mulss 

mwait 

near 

neg 

nop 

not 

or 

orpd 

orps 

out 

outs 

outsb 

outsd 

outsw 

packssdw 

packsswb 

packuswb 

paddb 

paddd 

paddq 

paddsb 

paddsw 

paddusb 

paddusw 

paddw 

pand 

pandn 

pause 

pavgb 

pavgusb 

pavgw 

pempeqb 

pempeqd 

pempeqw 

pcmpgtb 

pcmpgtd 

pcmpgtw 

pextrw 

pf 2id 

pf 2iw 

pf acc 

pf add 

pfcmpeq 

pfempge 

pfempgt 

pfmax 

pfmin 

pfmul 

pfnacc 

pfpnacc 

pf rep 

pfrcpitl 

pfrcpit2 

pfrsqitl 


Assembler Directives, Operators and Assembly Opcodes 1 7 




The Open Watcom Assembler 


pfrsqrt 

pf sub 

pi2fw 

pinsrw 

pmaxub 

pminsw 

pmulhrw 

pmulhuw 

pmuludq 

pop 

popf 

popf d 

prefetchnta 

prefetchtO 

prefetchw 

psadbw 

pshuflw 

pshufw 

psllq 

psllw 

psrld 

psrldq 

psubb 

psubd 

psubsw 

psubusb 

pswapd 

punpckhbw 

punpckhwd 

punpcklbw 

punpcklwd 

push 

pushd 

pushf 

pxor 

rcl 

rcr 

rdmsr 

rep 

repe 

rept 

repz 

retf 

retf d 

ror 

rsm 

sahf 

sal 

seas 

scasb 

seta 

setae 

setc 

sete 

setl 

setle 

setnb 

setnbe 

setng 

setnge 

setno 

setnp 

seto 

setp 

sets 

setz 

shl 

shld 

shrd 

shufpd 

sldt 

smsw 

sqrtps 

sqrtsd 

std 

sti 

stosb 

stosd 

sub 

subpd 

subss 

sysenter 

ucomisd 

ucomiss 

unpcklpd 

unpcklps 

wait 

wbinvd 

xchg 

xlat 

xorpd 

xorps 

ah 

al 

bl 

bx 

crO 

cr2 

cs 

cx 

dl 

drO 

dr3 

dr 6 

dx 

eax 

ecx 

edi 

esi 

esp 

mmO 

mml 

mm4 

mm 5 

si 

ss 


pfsubr 

pi2fd 

pmaddwd 

pmaxsw 

pminub 

pmovmskb 

pmulhw 

pmullw 

popa 

popad 

por 

prefetch 

prefetchtl 

prefetcht2 

pshufd 

pshufhw 

pslld 

pslldq 

psrad 

psraw 

psrlq 

psrlw 

psubq 

psubsb 

psubusw 

psubw 

punpekhdq 

punpckhqdq 

punpckldq 

punpcklqdq 

pusha 

pushad 

pushfd 

pushw 

repps 

repss 

rdpmc 

rdtsc 

repne 

repnz 

ret 

retd 

retn 

rol 

rsqrtps 

rsqrtss 

sar 

sbb 

scasd 

scasw 

setb 

setbe 

setg 

setge 

setna 

setnae 

setnc 

setne 

setnl 

setnle 

setns 

setnz 

setpe 

setpo 

sfence 

sgdt 

short 

shr 

shufps 

sidt 

sp 

sqrtpd 

sqrtss 

stc 

stmxcsr 

stos 

stosw 

str 

subps 

subsd 

sysexit 

test 

unpekhpd 

unpekhps 

verr 

verw 

wrmsr 

xadd 

xlatb 

xor 


ax 

bh 

eh 

cl 

cr3 

cr4 

dh 

di 

drl 

dr2 

dr7 

ds 

ebp 

ebx 

edx 

es 

f s 

gs 

mm2 

mm3 

mm6 

mm 7 

St 

stO 
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stl 

st2 

st3 

st4 

st5 

st6 

st7 

tr3 

tr4 

tr5 

tr 6 

tr7 

xmmO 

xmml 

xmm2 

xmm3 

xmm4 

xmm5 

xmm6 

xmm7 

i supported Directives 



Other assemblers support directives that this assembler does not. 

The following is a list of directives that 

are ignored by the Open Watcom Assembler (use of these directives results in a warning message). 

.alpha 

. cref 

. Ifcond 

. list 

. listall 

. listif 

.listmacro 

.listmacroall 

.nocref 

. nolist 

page 

. sail 

. seq 

.sfcond 

subtitle 

subttl 

.tfcond 

title 

.xcref 

.xlist 

The following is a list of directives that are flagged by the Open Watcom Assembler (use of these directives 

results in an error message). 



addr 

.break 

casemap 

catstr 

. continue 

echo 

. else 

endmacro 

.endif 

. endw 

. exit 

high 

highword 

. if 

invoke 

low 

lowword 

lroffset 

mask 

opattr 

option 

popcontext 

proto 

purge 

pushcontext 

.radix 

record 

.repeat 

. startup 

this 

typedef 

union 


. until 


.while 


width 


2.4 Open Watcom Assembler Specific 

There are a few specific features in Open Watcom Assembler 


2.4.1 Naming convention 


Convention 


Procedure 

Name 


Variable 

Name 


C 

WATCOM_ C 

SYSCALL 

STDCALL 

STDCALL 

STDCALL 

BASIC 

FORTRAN 

PASCAL 


*' 


*' 


see section Open Watcom 

' *' 

*@nn' 

’ *' 


' -k ' 
r a r 
r a r 
r a r 


r * r 
r * r 

r * f 

r * r 


name mangier 


r a r 
r a r 
r a r 


see note 1 
see note 2 
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Notes: 

1. In STDCALL procedures name ’nn’ is overall parametrs size in bytes. ’@nn’ is suppressed 
when -zz command line option is used (WATCOM 10.0 compatibility). 

2. STDCALL symbols mangling is suppressed by -zzo command line option (WASM backward 
compatible). 


2.4.2 Open Watcom "C" name mangier 

Command line Procedure Variable 

option Name Name 


0 , 1,2 

3,4,5,6 with r 
3,4,5,6 with s 


2.4.3 Calling convention 


Convention 

Vararg 

Parameters 
passed by 

Parameters 

order 

Cleanup caller 
stack 

C 

yes 

stack 

right to left 

no 

WATCOM_ C 

yes 

registers 

right to left 

see note 1 


yes 

stack 

right to left 

no 

SYSCALL 

yes 

stack 

right to left 

no 

STDCALL 

yes 

stack 

right to left 

yes see note 2 

BASIC 

no 

stack 

left to right 

yes 

FORTRAN 

no 

stack 

left to right 

yes 

PASCAL 

no 

stack 

left to right 

yes 


Notes: 

1. If any parameter is passed on the stack then WASM automaticaly cleanup caller stack. 

2. For STDCALL procedures WASM automaticaly cleanup caller stack, except case when vararg 
parameter is used. 

2.5 Open Watcom Assembler Diagnostic Messages 

1 Size doesn’t match with previous definition 

2 Invalid instruction with current CPU setting 

3 LOCK prefix is not allowed on this instruction 

4 REP prefix is not allowed on this instruction 

5 Invalid memory pointer 

6 Cannot use 386 addressing mode with current CPU setting 
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7 Too many base registers 

8 Invalid index register 

9 Scale factor must be 1, 2, 4 or 8 

10 invalid addressing mode with current CPU setting 

11 ESP cannot be used as index 

12 Too many base/index registers 

13 Memory offset cannot reference to more than one label 

14 Offset must be relocatable 

15 Memory offset expected 

16 Invalid indirect memory operand 

17 Cannot mix 16 and 32-bit registers 

18 CPU type already set 

19 Unknown directive 

20 Expecting comma 

21 Expecting number 

22 Invalid label definition 

23 Invalid use of SHORT, NEAR, FAR operator 

24 No memory 

25 Cannot use 386 segment register with current CPU setting 

26 POP CS is not allowed 

27 Cannot use 386 register with current CPU setting 

28 Only MOV can use special register 

29 Cannot use TR3, TR4, TR5 in current CPU setting 

30 Cannot use SHORT with CALL 

31 Only SHORT displacement is allowed 

32 Syntax error 

33 Prefix must be followed by an instruction 
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34 No size given before ’PTR’ operator 

35 Invalid IMUL format 

36 Invalid SHLD/SHRD format 

37 Too many commas 

38 Syntax error: Unexpected colon 

39 Operands must be the same size 

40 Invalid instruction operands 

41 Immediate constant too large 

42 Can not use short or near modifiers with this instruction 

43 Jump out of range 

44 Displacement cannot be larger than 32k 

45 Initializer value too large 

46 Symbol already defined 

47 Immediate data too large 

48 Immediate data out of range 

49 Can not transfer control to stack symbol 

50 Offset cannot be smaller than WORD size 

51 Can not take offset of stack symbol 

52 Can not take segment of stack symbol 

53 Segment too large 

54 Offset cannot be larger than 32k 

55 Operand 2 too big 

56 Operand 1 too small 

57 Too many arithmetic operators 

58 Too many open square brackets 

59 Too many close square brackets 

60 Too many open brackets 
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61 Too many close brackets 

62 Invalid number digit 

63 Assembler Code is too long 

64 Brackets are not balanced 

65 Operator is expected 

66 Operand is expected 

67 Too many tokens in a line 

68 Bracket is expected 

69 Illegal use of register 

70 Illegal use of label 

71 Invalid operand in addition 

72 Invalid operand in subtraction 

73 One operand must be constant 

74 Constant operand is expected 

75 A constant operand is expected in addition 

76 A constant operand is expected in subtraction 

77 A constant operand is expected in multiplication 

78 A constant operand is expected in division 

79 A constant operand is expected after a positive sign 

80 A constant operand is expected after a negative sign 

81 Label is not defined 

82 More than one override 

83 Label is expected 

84 Only segment or group label is allowed 

85 Only register or label is expected in override 

86 Unexpected end of file 

87 Label is too long 
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88 This feature has not been implemented yet 

89 Internal Error #1 

90 Can not take offset of group 

91 Can not take offset of segment 

92 Invalid character found 

93 Invalid operand size for instruction 

94 This instruction is not supported 

95 size not specified — BYTE PTR is assumed 

96 size not specified — WORD PTR is assumed 

97 size not specified — DWORD PTR is assumed 

500 Segment parameter is defined already 

501 Model parameter is defined already 

502 Syntax error in segment definition 

503 ’AT’ is not supported in segment definition 

504 Segment definition is changed 

505 Lname is too long 

506 Block nesting error 

507 Ends a segment which is not opened 

508 Segment option is undefined 

509 Model option is undefined 

510 No segment is currently opened 

511 Lname is used already 

512 Segment is not defined 

513 Public is not defined 

514 Colon is expected 

515 A token is expected after colon 

516 Invalid qualified type 
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51 7 Qualified type is expected 

518 External definition different from previous one 

519 Memory model is not found in .MODEL 

520 Cannot open include file 

521 Name is used already 

522 Library name is missing 

523 Segment name is missing 

524 Group name is missing 

525 Data emitted with no segment 

526 Seglocation is expected 

527 Invalid register 

528 Cannot address with assumed register 

529 Invalid start address 

530 Label is already defined 

531 Token is too long 

532 The line is too long after expansion 

533 A label is expected after colon 

534 Must be associated with code 

535 Procedure must have a name 

536 Procedure is alreadly defined 

537 Language type must be specified 

538 End of procedure is not found 

539 Local variable must immediately follow PROC or MACRO statement 

540 Extra character found 

541 Cannot nest procedures 

542 No procedure is currently defined 

543 Procedure name does not match 
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544 Vararg requires C calling convention 

545 Model declared already 

546 Model is not declared 

547 Backquote expected 

548 COMMENT delimiter expected 

549 End directive required at end of file 

550 Nesting level too deep 

551 Symbol not defined 

552 Insert Stupid warning #1 here 

553 Insert Stupid warning #2 here 

554 Spaces not allowed in command line options 

555 Error: 

556 Source File 

557 No filename specified. 

558 Out of Memory 

559 Cannot Open File - 

560 Cannot Close File - 

561 Cannot Get Start of Source File - 

562 Cannot Set to Start of Source File - 

563 Command Line Contains More Than 1 File To Assemble 

564 include path %s. 

565 Unknown option %s. Use /? for list of options. 

566 read more command tine from %s. 

567 Internal error in %s(%u) 

568 OBJECT WRITE ERROR !! 

569 NO LOR PHARLAP !! 

570 Parameter Required 
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571 Expecting closing square bracket 

572 Expecting file name 

573 Floating point instruction not allowed with /fpc 

574 Too many errors 

575 Build target not recognised 

576 Public constants should be numeric 

577 Expecting symbol 

578 Do not mix simplified and full segment definitions 

579 Parms passed in multiple registers must be accessed separately, use %s 

580 Ten byte variables not supported in register calling convention 

581 Parameter type not recognised 

582 forced error: 

583forced error: Value not equal to 0 : %d 
584forced error: Value equal to 0: %d 
585forced error: symbol defined: %s 
586forced error: symbol not defined: %s 
587forced error: string blank : <%s> 

588forced error: string not blank : <%s> 

589forced error: strings not equal: <%s> : <%s> 

590forced error: strings equal: <%s> : <%s> 

591 included by file %s(%d) 

592 macro called from file %s(%d) 

593 Symbol %s not defined 

594 Extending jump 

595 Ignoring inapplicable directive 

596 Unknown symbol class ’%s ’ 

597 Symbol class for ’%s ’ already established 
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598 number must be a power of 2 

599 alignment request greater than segment alignment 

600 ’%s ’ is already defined 

601 %u unclosed conditional directive(s) detected 
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3 The Open Watcom Library Manager 

3.1 Introduction 


The Open Watcom Library Manager can be used to create and update object library files. It takes as input 
an object file or a library file and creates or updates a library file. For OS/2, Winl6 and Win32 
applications, it can also create impoit libraries from Dynamic Link Libraries. 

An object library is essentially a collection of object files. These object files generally contain utility 
routines that can be used as input to the Open Watcom Linker to create an application. The following are 
some of the advantages of using library files. 

1. Only those modules that are referenced will be included in the executable file. This eliminates 
the need to know which object files should be included and which ones should be left out when 
linking an application. 

2. Libraries are a good way of organizing object files. When linking an application, you need only 
list one library file instead of several object files. 

The Open Watcom Library Manager currently runs under the following operating systems. 

•DOS 

•OS/2 

• QNX 

• Windows 


3.2 The Open Watcom Library Manager Command Line 

The following describes the Open Watcom Library Manager command line. 


WLIB [options_1 ] lib_file [options_2] [cmdjist] 


The square brackets "[]" denote items which are optional. 

lib_Jile is the file specification for the library file to be processed. If no file extension is specified, 

a file extension of "lib" is assumed. 

options_l is a list of valid options. Options may be specified in any order. If you are using a DOS, 
OS/2 or Windows-hosted version of the Open Watcom Library Manager, options are 
preceded by a "/" or "—" character. If you are using a UNIX-hosted version of the Open 
Watcom Library Manager, options are preceded by a "—" character. 
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options_2 is a list of valid options. These options are only permitted if you are running a DOS, OS/2 

or Windows-hosted version of the Open Watcom Library Manager and must be preceded 
by a "/" character. The "—" character cannot be used as an option delimiter for options 
following the library file name since it will be interpreted as a delete command. 

cmd_list is a list of commands to the Open Watcom Library Manager specifying what operations are 

to be performed. Each command in cmdjist is separated by a space. 

The following is a summary of valid options. Items enclosed in square brackets "[]" are optional. Items 
separated by an or-bar "I" and enclosed in parentheses "()" indicate that one of the items must be specified. 
Items enclosed in angle brackets "<>" are to be replaced with a user-supplied name or value (the "<>" are 
not included in what you specify). 

? display the usage message 

b suppress creation of backup file 

c perform case sensitive comparison 

d=<output_directory> 

directory in which extracted object modules will be placed 
fa output AR format library (host default ar format) 

fab output AR format library (BSD ar format) 

fac output AR format library (COFF ar format) 

fag output AR format library (GNU ar format) 

fm output MLIB format library 

fo output OMF format library 

li display the usage message 

ia generate AXP import records 

ii generate X86 import records 

ip generate PPC import records 

ie generate ELF import records 

ic generate COFF import records 

io generate OMF import records 

i(r\n)(n\o) imports for the resident/non-resident names table are to be impoited by name/ordinal. 
l[=<list_file>] create a listing file 
m display C++ mangled names 

n always create a new library 

o=<output_file> 

set output file name for library 
p=<record_size> 

set library page size (supported for "OMF" library format only) 
pa set optimal library page size automaticaly (supported for "OMF" library format only) 

q suppress identification banner 

s strip line number records from object files (supported for "OMF" library format only) 

t remove path information from module name specified in THEADR records (supported for 

"OMF" library format only) 
v do not suppress identification banner 

x extract all object modules from library 

zld strip file dependency info from object files (supported for "OMF" library format only) 

The following sections describe the operations that can be performed on a library file. Note that before 
making a change to a library file, the Open Watcom Library Manager makes a backup copy of the original 
library file unless the "o" option is used to specify an output library file whose name is different than the 
original library file, or the "b" option is used to suppress the creation of the backup file. The backup copy 
has the same file name as the original library file but has a file extension of "bak". Hence, Iib_file should 
not have a file extension of "bak". 
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3.3 Open Watcom Library Manager Module Commands 

The following is a summary of basic Open Watcom Library Manager module manipulation commands: 

+ add module to a library 

remove module from a library 

* or: extract module from a library (: is used with a UNIX-hosted version of the Open Watcom 

Library Manager, otherwise * is used) 

++ add import library entry 

3.4 Adding Modules to a Library File 

An object file can be added to a library file by specifying a +obj_file command where obj_file is the file 
specification for an object file. If you are using a DOS, OS/2 or Windows-hosted version of the Open 
Watcom Library Manager, a file extension of "obj" is assumed if none is specified. If you are using a 
UNIX-hosted version of the Open Watcom Library Manager, a file extension of "o" is assumed if none is 
specified. If the library file does not exist, a warning message will be issued and the library file will be 
created. 

Example: 

wlib mylib +myobj 

In the above example, the object file "myobj" is added to the library file "mylib.lib". 

When a module is added to a library, the Open Watcom Library Manager will issue a warning if a symbol 
redefinition occurs. This will occur if a symbol in the module being added is already defined in another 
module that already exists in the library file. Note that the module will be added to the library in any case. 

It is also possible to combine two library files together. The following example adds all modules in the 
library "newlib.lib" to the library "mylib.lib". 

Example: 

wlib mylib +newlib.lib 

Note that you must specify the "lib" file extension. Otherwise, the Open Watcom Library Manager will 
assume you are adding an object file. 

3.5 Deleting Modules from a Library File 

A module can be deleted from a library file by specifying a -mod_name command where mod_name is the 
file name of the object file when it was added to the library with the directory and file extension removed. 
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Example: 

wlib mylib -myobj 

In the above example, the Open Watcom Library Manager is instructed to delete the module "myobj" from 
the library file "mylib.lib". 

It is also possible to specify a library file instead of a module name. 

Example: 

wlib mylib -oldlib.lib 

In the above example, all modules in the library file "oldlib.lib" are removed from the library file 
"mylib.lib". Note that you must specify the "lib" file extension. Otherwise, the Open Watcom Library 
Manager will assume you are removing an object module. 

3.6 Replacing Modules in a Library File 

A module can be replaced by specifying a -+mod_name or +-mod_name command. The module 
mod_name is deleted from the library. The object file "mod_name" is then added to the library. 

Example: 

wlib mylib —l-myobj 

In the above example, the module "myobj" is replaced by the object file "myobj". 

It is also possible to merge two library files. 

Example: 

wlib mylib —Hupdlib.lib 

In the above example, all modules in the library file "updlib.lib" replace the corresponding modules in the 
library file "mylib.lib". Any module in the library "updlib.lib" not in library "mylib.lib" is added to the 
library "mylib.lib". Note that you must specify the "lib" file extension. Otherwise, the Open Watcom 
Library Manager will assume you are replacing an object module. 


3.7 Extracting a Module from a Library File 

A module can be extracted from a library file by specifying a *mod_name |=file_name] command for a 
DOS, OS/2 or Windows-hosted version of the Open Watcom Library Manager or a :mod_name 
[=file_name] command for a UNIX-hosted version of the Open Watcom Library Manager. The module 
mod_name is not deleted but is copied to a disk file. If mod_name is preceded by a path specification, the 
output file will be placed in the directory identified by the path specification. If mod_name is followed by 
a file extension, the output file will contain the specified file extension. 
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Example: 

wlib mylib *myobj DOS, OS/2 or Windows-hosted 

or 

wlib mylib :myobj UNIX-hosted 

In the above example, the module "myobj" is copied to a disk file. The disk file will be an object file with 
file name "myobj". If you are running a DOS, OS/2 or Windows-hosted version of the Open Watcom 
Library Manager, a file extension of "obj" will be used. If you are running a UNIX-hosted version of the 
Open Watcom Library Manager, a file extension of "o" will be used. 

Example: 

wlib mylib *myobj.out DOS, OS/2 or Windows-hosted 

or 

wlib mylib :myobj.out UNIX-hosted 

In the above example, the module "myobj" will be extracted from the library file "mylib.lib" and placed in 
the file "myobj.out" 

The following form of the extract command can be used if the module name is not the same as the output 
file name. 

Example: 

wlib mylib *myobj=newmyobj.out DOS, OS/2 or Windows-hosted 
or 

wlib mylib :myobj=newmyobj.out UNIX-hosted 

You can extract a module from a file and have that module deleted from the library file by specifying a 
*-mod_name command for a DOS, OS/2 or Windows-hosted version of the Open Watcom Library 
Manager or a :-mod_name command for a UNIX-hosted version of the Open Watcom Library Manager. 
The following example performs the same operations as in the previous example but, in addition, the 
module is deleted from the library file. 

Example: 

wlib mylib *-myobj.out DOS, OS/2 or Windows-hosted 
or 

wlib mylib :-myobj.out UNIX-hosted 
Note that the same result is achieved if the delete operator precedes the extract operator. 


3.8 Creating Import Libraries 

The Open Watcom Library Manager can also be used to create import libraries from Dynamic Link 
Libraries. Import libraries are used when linking OS/2, Winl6 or Win32 applications. 

Example: 

wlib implib +dynamic.dll 

In the above example, the following actions are performed. For each external symbol in the specified 
Dynamic Link Library, a special object module is created that identifies the external symbol and the actual 
name of the Dynamic Link Library it is defined in. This object module is then added to the specified 
library. The resulting library is called an import library. 
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Note that you must specify the "dll" file extension. Otherwise, the Open Watcom Library Manager will 
assume you are adding an object file. 

3.9 Creating Import Library Entries 

An import library entry can be created and added to a library by specifying a command of the following 
form. 

++sym.dll_ name[.[altsym].export_ name][.ordinal] 

where description: 

sym is the name of a symbol in a Dynamic Link Library. 

dlljmme is the name of the Dynamic Link Library that defines sym. 

altsym is the name of a symbol in a Dynamic Link Library. When omitted, the default symbol 

name is sym. 

export jiame is the name that an application that is linking to the Dynamic Link Library uses to reference 
sym. When omitted, the default export name is sym. 

ordinal is the ordinal value that can be used to identify sym instead of using the name 

export_ name. 

Example: 

wlib math ++_ sin.trig.sin.1 

In the above example, an import library entry will be created for symbol sin and added to the library 

"math.lib". The symbol sin is defined in the Dynamic Link Library called "trig.dll" as_sin . When an 

application is linked with the library "math.lib", the resulting executable file will contain an import by 
ordinal value 1. If the ordinal value was omitted, the resulting executable file would contain an import by 
name sin. 


3.10 Commands from a File or Environment Variable 


The Open Watcom Library Manager can be instructed to process all commands in a disk file or 
environment variable by specifying the @name command where name is a file specification for the 
command file or the name of an environment variable. A file extension of "lbc" is assumed for files if none 
is specified. The commands must be one of those previously described. 

Example: 

wlib mylib gmycmd 

In the above example, all commands in the environment variable "mycmd" or file "mycmd.lbc" are 
processed by the Open Watcom Library Manager. 
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3.11 Open Watcom Library Manager Options 

The following sections describe the list of options allowed when invoking the Open Watcom Library 
Manager. 

3.11.1 Suppress Creation of Backup File - "b" Option 

The "b" option tells the Open Watcom Library Manager to not create a backup library file. In the following 
example, the object file identified by "new" will be added to the library file "mylib.lib". 

Example: 

wlib -b mylib +new 

If the library file "mylib.lib" already exits, no backup library file ("mylib.bak") will be created. 

3.11.2 Case Sensitive Symbol Names - "c" Option 

The "c" option tells the Open Watcom Library Manager to use a case sensitive compare when comparing a 
symbol to be added to the library to a symbol already in the library file. This will cause the names "myrtn" 
and "MYRTN" to be treated as different symbols. By default, comparisons are case insensitive. That is the 
symbol "myrtn" is the same as the symbol "MYRTN". 

3.11.3 Specify Output Directory - "d" Option 

The "d" option tells the Open Watcom Library Manager the directory in which all extracted modules are to 
be placed. The default is to place all extracted modules in the current directory. 

In the following example, the module "mymod" is extracted from the library "mylib.lib". If you are 
running a DOS, OS/2 or Windows-hosted version of the Open Watcom Library Manager, the module will 
be placed in the file "\obj\mymod.obj". If you are running a UNIX-hosted version of the Open Watcom 
Library Manager, the module will be placed in the file "/o/mymod.o". 

Example: 

wlib -d=\obj mymod DOS, OS/2 or Windows-hosted 

or 

wlib -d=/o mymod UNIX-hosted 

3.11.4 Specify Output Format ■ "f" Option 

The "f" option tells the Open Watcom Library Manager the format of the output library. The default output 
format is determined by the type of object files that are added to the library when it is created. The possible 
output format options are: 


fa output AR format library, host OS default ar format 

fab output AR format library, BSD ar format 

fac output AR format library, COFF ar format 
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fag 

output 

fin 

output 

fo 

output 


AR format library, GNU ar format 
MLIB format library 
OMF format library 


3.11.5 Generating Imports -"/" Option 

The "i" option can be used to describe type of import library to create. 
id generate AXP import records 

ii generate X86 import records 

ip generate PPC import records 

ie generate ELF import records 

ic generate COFF import records 

io generate OMF import records 


When creating import libraries from Dynamic Link Libraries, import entries for the names in the resident 
and non-resident names tables are created. The "i" option can be used to describe the method used to 
import these names. 

iro Specifying "iro" causes imports for names in the resident names table to be imported by 

ordinal. 

irn Specifying "irn" causes imports for names in the resident names table to be imported by 

name. This is the default. 

it to Specifying "ino" causes imports for names in the non-resident names table to be imported 

by ordinal. This is the default. 

inn Specifying "inn" causes imports for names in the non-resident names table to be imported 

by name. 

Example: 

wlib -iro -inn implib +dynamic.dll 

Note that you must specify the "dll" file extension for the Dynamic Link Library. Otherwise an object file 
will be assumed. 

3.11.6 Creating a Listing File - "I" Option 

The "1" (lower case "L") option instructs the Open Watcom Library Manager to produce a list of the names 
of all symbols that can be found in the library file to a listing file. The file name of the listing file is the 
same as the file name of the library file. The file extension of the listing file is "1st". 
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Example: 

wlib -1 mylib 

In the above example, the Open Watcom Library Manager is instructed to list the contents of the library file 
"mylib.lib" and produce the output to a listing file called "mylib.1st". 

An alternate form of this option is -l=list_ f ile . With this form, you can specify the name of the 
listing file. When specifying a listing file name, a file extension of "1st" is assumed if none is specified. 

Example: 

wlib -l=mylib.out mylib 

In the above example, the Open Watcom Library Manager is instructed to list the contents of the library file 
"mylib.lib" and produce the output to a listing file called "mylib.out". 

You can get a listing of the contents of a library file to the terminal by specifying only the library name on 
the command line as demonstrated by the following example. 

Example: 

wlib mylib 

3.11.7 Display C++ Mangled Names - "m" Option 

The "m" option instructs the Open Watcom Library Manager to display C++ mangled names rather than 
displaying their demangled form. The default is to interpret mangled C++ names and display them in a 
somewhat more intelligible form. 

3.11.8 Always Create a New Library - "n" Option 

The "n" option tells the Open Watcom Library Manager to always create a new library file. If the library 
file already exists, a backup copy is made (unless the "b" option was specified). The original contents of 
the library are discarded and a new library is created. If the "n" option was not specified, the existing 
library would be updated. 

Example: 

wlib -n mylib +myobj 

In the above example, a library file called "mylib.lib" is created. It will contain a single object module, 
namely "myobj", regardless of the contents of "mylib.lib" prior to issuing the above command. If 
"mylib.lib" already exists, it will be renamed to "mylib.bak". 

3.11.9 Specifying an Output File Name - "o" Option 

The "o" option can be used to specify the output library file name if you want the original library to remain 
unchanged and a new library created. 
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Example: 

wlib -o=newlib libl +lib2.1ib 

In the above example, the modules from "libl.lib" and "lib2.1ib" are added to the library "newlib.lib". Note 
that since the original library remains unchanged, no backup copy is created. Also, if the "1" option is used 
to specify a listing file, the listing file will assume the file name of the output library. 

3.11.10 Specifying a Library Record Size - "p" and "pa" Options 

The "p" option specifies the record size in bytes for each record in the library file. The record size must be 
a power of 2 and in the range 16 to 32768. If the record size is less than 16, it will be rounded up to 16. If 
the record size is greater than 16 and not a power of 2, it will be rounded up to the nearest power of 2. The 
default record size is 256 bytes. 

Each entry in the dictionary of a library file contains an offset from the start of the file which points to a 
module. The offset is 16 bits and is a multiple of the record size. Since the default record size is 256, the 
maximum size of a library file for a record size of 256 is 256*64K. If the size of the library file increases 
beyond this size, you must increase the record size. 

Example: 

wlib -p=512 libl +lib2.1ib 

In the above example, the Open Watcom Library Manager is instructed to create/update the library file 
"libl.lib" by adding the modules from the library file "lib2.1ib". The record size of the resulting library file 
is 512 bytes. 

The "pa" option specifies the record size is determined automaticaly to be minimal in size. 

Example: 

wlib -pa libl +lib2.1ib 

In the above example, the Open Watcom Library Manager is instructed to create/update the library file 
"libl.lib" by adding the modules from the library file "lib2.1ib". The record size of the resulting library file 
is optimal (minimal) regardles of what each library page size is. 

3.11.11 Operate Quietly - "q" Option 

The "q" option suppressing the banner and copyright notice that is normally displayed when the Open 
Watcom Library Manager is invoked. 

Example: 

wlib -q -1 mylib 

3.11.12 Strip Line Number Records - "s" Option 

The "s" option tells the Open Watcom Library Manager to remove line number records from object files 
that are being added to a library. Line number records are generated in the object file if the "dl" option is 
specified when compiling the source code. 
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Example: 

wlib -s mylib +myobj 

3.11.13 Trim Module Name - "t" Option 

The "t" option tells the Open Watcom Library Manager to remove path information from the module name 
specified in THEADR records in object files that are being added to a library. The module name is created 
from the file name by the compiler and placed in the THEADR record of the object file. The module name 
will contain path information if the file name given to the compiler contains path information. 

Example: 

wlib -t mylib +myobj 

3.11.14 Operate Verbosely - "v" Option 

The "v" option enables the display of the banner and copyright notice when the Open Watcom Library 
Manager is invoked. 

Example: 

wlib -v -1 mylib 

3.11.15 Explode Library File - "x" Option 

The "x" option tells the Open Watcom Library Manager to extract all modules from the library. Note that 
the modules are not deleted from the library. Object modules will be placed in the current directory unless 
the "d" option is used to specify an alternate directory. 

In the following example all modules will be extracted from the library "mylib.lib" and placed in the 
current directory. 

Example: 

wlib -x mylib 

In the following example, all modules will be extracted from the library "mylib.lib". If you are running a 
DOS, OS/2 or Windows-hosted version of the Open Watcom Library Manager, the module will be placed 
in the "\obj" directory. If you are running a UNIX-hosted version of the Open Watcom Library Manager, 
the module will be placed in the file "/o" directory. 

Example: 

wlib -x -d=\obj mylib DOS, OS/2 or Windows-hosted 
or 

wlib -x -d=/o mylib UNIX-hosted 


3.12 Librarian Error Messages 

The following messages may be issued by the Open Watcom Library Manager. 


Librarian Error Messages 


41 




Object File Utilities 


Error! Could not open object file ’%s’. 

Object file ’%s’ could not be found. This message is usually issued when an attempt is 
made to add a non-existent object file to the library. 

Error! Could not open library file ’%s ’. 

The specified library file could not be found. This is usually issued for input library files. 
For example, if you are combining two library files, the library file you are adding is an 
input library file and the library file you are adding to or creating is an output library file. 

Error! Invalid object module in file ’%.v ’ not added. 

The specified file contains an invalid object module. 

Error! Dictionary too large. Recommend split library into two libraries. 

The size of the dictionary in a library file cannot exceed 64K. You must split the library 
file into two separate library files. 

Error! Redefinition of module ’%.v ’ in file ’%s ’. 

This message is usually issued when an attempt is made to add a module to a library that 
already contains a module by that name. 

Warning! Redefinition of symbol ’%.v ’ in file ’%.v ’ ignored. 

This message is issued if a symbol defined by a module already in the library is also 
defined by a module being added to the library. 

Error! Library too large. Recommend split library into two libraries or try a larger page_bound than 
%xH. The record size of the library file does not allow the library file to increase beyond its 

current size. The record size of the library file must be increased using the "p" option. 

Error! Expected ’%s ’ in ’%s ’ but found ’%s’. 

An error occurred while scanning command input. 

Warning! Could not find module ’%s’ for deletion. 

This message is issued if an attempt is made to delete a module that does not exist in the 
library. 

Error! Could not find module ’%s’ for extraction. 

This message is issued if an attempt is made to extract a module that does not exist in the 
library. 

Error! Could not rename old library for backup. 

The Open Watcom Library Manager creates a backup copy before making any changes 
(unless the "b" option is specified). This message is issued if an error occurred while trying 
to rename the original library file to the backup file name. 

Warning! Could not open library ’%.v ’: will be created. 

The specified library does not exist. It is usually issued when you are adding to a 
non-existent library. The Open Watcom Library Manager will create the library. 

Warning! Output library name specification ignored. 

This message is issued if the library file specified by the "o" option could not be opened. 

Warning! Could not open library ’%s ’ and no operations specified: will not be created. 

This message is issued if the library file specified on the command line does not exist and 
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no operations were specified. For example, asking for a listing file of a non-existent library 
will cause this message to be issued. 

Warning! Could not open listing file ’%s 

The listing file could not be opened. For example, this message will be issued when a "disk 
full" condition is present. 

Error! Could not open output library. 

The output library could not be opened. 

Error! Unable to write to output library. 

An error occurred while writing to the output library. 

Error! Unable to write to extraction file ’%s’. 

This message is issued when extracting an object module from a library file and an error 
occurs while writing to the output file. 

Error! Out of Memory. 

There was not enough memory to process the library file. 

Error! Could not open file ’%s’. 

This message is issued if the output file for a module that is being extracted from a library 
could not be opened. 

Error! Library ’%.v ’ is invalid. Contents ignored. 

The library file does not contain the correct header information. 

Error! Library ’%s ’ has an invalid page size. Contents ignored. 

The library file has an invalid record size. The record size is contained in the library header 
and must be a power of 2. 

Error! Invalid object record found in file ’%s 

The specified file contains an invalid object record. 

Error! No library specified on command line. 

This message is issued if a library file name is not specified on the command line. 

Error! Expecting library name. 

This message is issued if the location of the library file name on the command line is 
incorrect. 

Warning! Invalid file name ’%s ’. 

This message is issued if an invalid file name is specified. For example, a file name longer 
that 127 characters is not allowed. 

Error! Could not open command file ’%s ’. 

The specified command file could not be opened. 

Error! Could notread from file ’%s ’. Contents ignored as command input. 

An error occurred while reading a command file. 
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4 The Object File Disassembler 


4.1 Introduction 

This chapter describes the Open Watcom Disassembler. It takes as input an object file (a file with 
extension ".obj") and produces, as output, the Intel assembly language equivalent. The Open Watcom 
compilers do not produce an assembly language listing directly from a source program. Instead, the Open 
Watcom Disassembler can be used to generate an assembly language listing from the object file generated 
by the compiler. 

The Open Watcom Disassembler command line syntax is the following. 

WDIS [options] [d:][path]filename[.ext] [options] 


The square brackets [ ] denote items which are optional. 

WDIS is the name of the Open Watcom Disassembler. 

d: is an optional drive specification such as "A:", "B:", etc. If not specified, the default drive 

is assumed. 

path is an optional path specification such as "\PROGRAMS\OBJ\". If not specified, the current 

directory is assumed. 

filename is the file name of the object file to disassemble. 

ext is the file extension of the object file to disassemble. If omitted, a file extension of ".obj" is 

assumed. If the period "." is specified but not the extension, the file is assumed to have no 
file extension. 


options is a list of valid options, each preceded by a slash ("/") or a dash Options may be 

specified in any order. 

The options supported by the Open Watcom Disassembler are: 


a 

e 

ff 

fi 

fp 

fr 

/« 

i=<char> 
l[=<list_file>] 


write assembly instructions only to the listing file 

include list of external names 

print FPU emulator fixups as comment line 

use alternate indexing format [80(x)86 only] 

do not use instruction name pseudonyms 

do not use register name pseudonyms [Alpha only] 

instructions/registers in upper case 

redefine the initial character of internal labels (default: L) 
create a listing file 
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m leave C++ names mangled 

p include list of public names 

s[=<source _Jile>] 

using object file source line information, imbed original source lines into the output file 
The following sections describe the list of options. 

4.2 Changing the Internal Label Character - "i=<char>" 

The "i" option permits you to specify the first character to be used for internal labels. Internal labels take 
the form "Ln" where "n" is one or more digits. The default character "L" can be changed using the "i" 
option. The replacement character must be a letter (a-z, A-Z). A lowercase letter is converted to 
uppercase. 

Example: 

C>wdis calendar -i=x 


4.3 The Assembly Format Option ■ “a" 

The "a" option controls the format of the output produced to the listing file. When specified, the Open 
Watcom Disassembler will produce a listing file that can be used as input to an assembler. 

Example: 

C>wdis calendar -a -l=calendar.asm 

In the above example, the Open Watcom Disassembler is instructed to disassemble the contents of the file 
calendar . ob j and produce the output to the file calendar. asm so that it can be assembled by an 
assembler. 


4.4 The External Symbols Option - "e" 

The "e" option controls the amount of information produced in the listing file. When specified, a list of all 
externally defined symbols is produced in the listing file. 


Example: 

C>wdis calendar -e 


In the above example, the Open Watcom Disassembler is instructed to disassemble the contents of the file 
calendar . ob j and produce the output, with a list of all external symbols, on the screen. A sample list 
of external symbols is shown below. 

List of external symbols 
Symbol 


CALENDAR 

CLEARSCREEN 

GETDAT 

POSCURSOR 


OOOOOOcf 0000008b 00000047 
0000000a 
00000018 
000000e8 
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Each externally defined symbol is followed by a list of location counter values indicating where the symbol 
is referenced. 

The "e" option is ignored when the "a" option is specified. 

4.5 The FPU emulator fixups Option ■ "ff" 

The "ff' option causes the FPU emulator fixups will be printed as comment line before Intel FPU 
instruction. 


; FPU fixup FIDRQQ 

fid tbyte ptr [bx] 

4.6 The Alternate Addressing Form Option ■ "fi" 

The "fi" option causes an alternate syntactical form of the based or indexed addressing mode of the 80x86 
to be used in an instruction. For example, the following form is used by default for Intel instructions. 

mov ax,-2[bp] 

If the "fi" option is specified, the following form is used, 
mov ax,[bp-2] 

4.7 The No Instruction Name Pseudonyms Option ■ "fp" 

By default, AXP instruction name pseudonyms are emitted in place of actual instruction names. The Open 
Watcom AXP Assembler accepts instruction name pseudonyms. The "fp" option instructs the Open 
Watcom Disassembler to emit the actual instruction names instead. 


4.8 The No Register Name Pseudonyms Option - "fr" 

By default, AXP register names are emitted in pseudonym form. The Open Watcom AXP Assembler 
accepts register pseudonyms. The "fr" option instructs the Open Watcom Disassembler to display register 
names in their non-pseudonym form. 

4.9 The Uppercase Instructions/Registers Option ■ "fu" 

The "fu" option instructs the Open Watcom Disassembler to display instruction and register names in 
uppercase characters. The default is to display them in lowercase characters. 
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4.10 The Listing Option - “l[=<list_file>]“ 

By default, the Open Watcom Disassembler produces its output to the terminal. The "1" (lowercase L) 
option instructs the Open Watcom Disassembler to produce the output to a listing file. The default file 
name of the listing file is the same as the file name of the object file. The default file extension of the 
listing file is . 1st. 

Example: 

C>wdis calendar -1 

In the above example, the Open Watcom Disassembler is instructed to disassemble the contents of the file 
calendar . ob j and produce the output to a listing file called calendar . 1st. 

An alternate form of this option is "l=<list_file>". With this form, you can specify the name of the listing 
file. When specifying a listing file, a file extension of ,1st is assumed if none is specified. 

Example: 

C>wdis calendar -l=calendar.lis 

In the above example, the Open Watcom Disassembler is instructed to disassemble the contents of the file 
calendar . ob j and produce the output to a listing file called calendar . lis . 

4.11 The Public Symbols Option ■ "p" 

The "p" option controls the amount of information produced in the listing file. When specified, a list of all 
public symbols is produced in the listing file. 


Example: 

C>wdis calendar -p 


In the above example, the Open Watcom Disassembler is instructed to disassemble the contents of the file 
calendar . ob j and produce the output, with a list of all exported symbols, to the screen. A sample list 
of public symbols is shown below. 

List of public symbols 

SYMBOL GROUP SEGMENT ADDRESS 


BOX 

CALENDAR 

CLEARSCREEN 

FMAIN 

LINE 

POSCURSOR 


BOX_ TEXT 00000000 
CALENDAR_ TEXT 00000000 
CLEARSCREEN_ TEXT 00000000 
FMAIN_ TEXT 00000000 
LINE_ TEXT 00000000 
POSCURSOR_ TEXT 00000000 


The "p" option is ignored when the "a" option is specified. 
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4.12 Retain C++ Mangled Names - "m" 

The "m" option instructs the Open Watcom Disassembler to retain C++ mangled names rather than 
displaying their demangled form. The default is to interpret mangled C++ names and display them in a 
somewhat more intelligible form. 

4.13 The Source Option ■ "s[=<source_file>]" 

The "s" option causes the source lines corresponding to the assembly language instructions to be produced 
in the listing file. The object file must contain line numbering information. That is, the "dl" or "d2" option 
must have been specified when the source file was compiled. If no line numbering information is present in 
the object file, the "s" option is ignored. 

The following defines the order in which the source file name is determined when the "s" option is 
specified. 

1. If present, the source file name specified on the command line. 

2. The name from the module header record. 

3. The object file name. 

In the following example, we have compiled the source file mysrc. for with "dl" debugging information. 
We then disassemble it as follows: 

Example: 

C>wdis mysrc -s -1 

In the above example, the Open Watcom Disassembler is instructed to disassemble the contents of the file 
mysrc . ob j and produce the output to the listing file mysrc . 1st. The source lines are extracted from 
the file mysrc . for . 

An alternate form of this option is "s=<source_file>". With this form, you can specify the name of the 
source file. 

Example: 

C>wdis mysrc -s=myprog.for -1 

The above example produces the same result as in the previous example except the source lines are 
extracted from the file myprog. f or . 


4.14 An Example 

Consider the following program contained in the file hello . for . 


program main 

print *, 'Hello world' 

end 
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Compile it with the "dl" option. An object file called hello. ob j will be produced. The "dl" option 
causes line numbering information to be generated in the object file. We can use the Open Watcom 
Disassembler to disassemble the contents of the object file by issuing the following command. 

C>wdis hello -1 -e -p -s -fu 


The output will be written to a listing file called hello . 1st (the "1" option was specified"). It will 
contain a list of external symbols (the "e" option was specified), a list of public symbols (the "p" option was 
specified) and the source lines corresponding to the assembly language instructions (the "s" option was 
specified). The source input file is called hello . for . The register names will be displayed in upper 
case (the "fu" option was specified). The output, shown below, is the result of using the Open Watcom F77 
compiler. 

Module: hello.for 

Group: 'DGROUP' CONST,_ DATA,_ BSS 

Group: 'FLAT' 

Segment: ' FMAIN_ TEXT' BYTE USE32 00000014 bytes 


program main 

print *, 'Hello world' 


0000 

e8 00 00 

00 

00 FMAIN 

call 

RT@IOWrite 

0005 

b8 00 00 

00 

00 

mov 

EAX,offset L2 

000a 

e8 00 00 

00 

00 

call 

RT@OutCHAR 

OOOf 

e9 00 00 

00 

00 

jmp 

RT@EndIO 

No disassembly errors 




List of external symbols 


Symbol 


RT@EndIO 00000010 
RT@IOWrite 00000001 
RTSOutCHAR 0000000b 


Segment: 'CONST' WORD USE32 0000000b bytes 
0000 48 65 6c 6c 6f 20 77 6f LI - Hello wo 

0008 72 6c 64 - rid 

No disassembly errors 


Segment: '_ DATA' WORD USE32 00000008 bytes 
0000 00 00 00 00 L2 DD DGROUP:LI 

0004 0b 00 00 00 - _ 

No disassembly errors 


List of public symbols 


SYMBOL 

GROUP 

SEGMENT 

ADDRESS 

FMAIN 


FMAIN_ TEXT 

00000000 
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Let us create a form of the listing file that can be used as input to an assembler. 
C>wdis hello -l=hello.asm -r -a 


The output will be produced in the file hello . asm. The output, shown below, is the result of using the 
Open Watcom F77 compiler. 


.387 


. 386p 



PUBLIC 

FMAIN 


EXTRN 

'RT@IOWrite':BYTE 


EXTRN 

'RTQOutCHAR':BYTE 


EXTRN 

'RT@EndIO':BYTE 


EXTRN 

_init_ error:BYTE 


EXTRN 

_init_ english:BYTE 


EXTRN 

_init_ 387_ emulator:BYTE 


EXTRN 

_ cstart_ : BYTE 

DGROUP 

GROUP 

CONST,_ DATA,_ BSS 

CONST 

SEGMENT 

PARA PUBLIC USE32 'DATA' 

L$ 1: 


DB 

0x48, 0x65, 0x6c, 0x6c, 0x6f, 


DB 

0x72, 0x6c, 0x64 

CONST 

ENDS 


_ DATA 

SEGMENT 

PARA PUBLIC USE32 'DATA' 

L$2 : 


DD 

L$ 1 


DB 

0x0b, 0x00, 0x00, 0x00 

_ DATA 

ENDS 


_ BSS 

SEGMENT 

PARA PUBLIC USE32 'BSS' 

_ BSS 

ENDS 


_ TEXT 

SEGMENT 

BYTE PUBLIC USE32 'CODE' 


ASSUME CSTEXT, DS:DGROUP, SS:DGROUP 

FMAIN: 

CALL 

near ptr 

'RT@IOWrite' 

MOV 

EAX,offset L$2 

CALL 

near ptr 

'RT@OutCHAR' 

JMP 

near ptr 

'RTSEndlO' 

_ TEXT 

ENDS 

END 



0x20, 


0x77, 


0x6f 
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5 Optimization of Far Calls 


Optimization of far calls can result in smaller executable files and improved performance. It is most useful 
when the automatic grouping of logical segments into physical segments takes place. Note that, by default, 
automatic grouping is performed by the Open Watcom Linker. 

The Open Watcom C, C++ and FORTRAN 77 compilers automatically enable the far call optimization. 

The Open Watcom Linker will optimize far calls to procedures that reside in the same physical segment as 
the caller. For example, a large code model program will probably contain many far calls to procedures in 
the same physical segment. Since the segment address of the caller is the same as the segment address of 
the called procedure, only a near call is necessary. A near call does not require a relocation entry in the 
relocation table of the executable file whereas a far call does. Thus, the far call optimization will result in 
smaller executable files that will load faster. Furthermore, a near call will generally execute faster than a 
far call, particularly on 286 and 386-based machines where, for applications running in protected mode, 
segment switching is fairly expensive. 

The following describes the far call optimization, 
following sequences of code. 

push cs seg 

call near label push 

nop call 

Notes: 

1. The nop or seg ss instruction is present since a call far label instruction is five bytes. The push 
cs instruction is one byte and the call near label instruction is three bytes. The seg ss instruction 
is used because it is faster than the nop instruction. 

2. The called procedure will still use a retf instruction but since the code segment and the near 
address are pushed on the stack, the far return will execute correctly. 

3. The position of the padding instruction is chosen so that the return address is word aligned. A 
word aligned return address improves performance. 

4. When two consecutive call far label instructions are optimized and the first call far label 
instruction is word aligned, the following sequence replaces both call far label instructions. 


push 

CS 


call 

near 

labell 

seg 

ss 


push 

cs 


seg 

cs 


call 

near 

label2 


5. If your program contains only near calls, this optimization will have no effect. 

A far jump optimization is also performed by the Open Watcom Linker. This has the same benefits as the 
far call optimization. A jmp far label instruction to a location in the same segment will be replaced by the 
following sequence of code. 


The call far label instruction is converted to one of the 


ss 

cs 

near label 
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jmp near label 

mov ax,ax 

Note that for 32-bit segments, this instruction becomes mov eax, eax. 


5.1 Far Call Optimizations for Non-Open Watcom Object 
Modules 


The far call optimization is automatically enabled when object modules created by the Open Watcom C, 
C++, or FORTRAN 77 compilers are linked. These compilers mark those segments in which this 
optimization can be performed. The following utility can be used to enable this optimization for object 
modules that have been created by other compilers or assemblers. 

5.1.1 The Open Watcom Far Call Optimization Enabling Utility 

Only DOS, OS/2 and Windows-hosted versions of the Open Watcom Far Call Optimization Enabling 
Utility are available. A QNX-hosted version is not necessary since QNX-hosted development tools that 
generate object files, generate the necessary information that enables the far call optimization. 

The format of the Open Watcom Far Call Optimization Enabling Utility is as follows. Items enclosed in 
square brackets are optional; items enclosed in braces may be repeated zero or more times. 


FCENABLE { [option] [file] } 


where description: 

option is an option and must be preceded by a dash (’-’) or slash (’/’). 

file is a file specification for an object file or library file. If no file extension is specified, a file 

extension of "obj" is assumed. Wild card specifiers may be used. 

The following describes the command line options. 

b Do not create a backup file. By default, a backup file will be created. The backup file 

name will have the same file name as the input file and a file extension of "bob" for object 
files and "bak" for library files. 

c Specify a list of class names, each separated by a comma. This enables the far call 

optimization for all segments belonging to the specified classes. 

s Specify a list of segment names, each separated by a comma. This enables the far call 

optimization for all specified segments. 

x Specify a list of ranges, each separated by a comma, for which no far call optimizations are 

to be made. A range has the following format. 
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seg_ name start-end 
or 

seg_ name start:length 

seg_name is the name of a segment, start is an offset into the specified segment defining 
the start of the range, end is an offset into the specified segment defining the end of the 
range, length is the number of bytes from start to be included in the range. All values are 
assumed to be hexadecimal. 


Notes: 

1. If more than one class list or segment list is specified, only the last one is used. A class or 
segment list applies to all object and library files regardless of their position relative to the class 
or segment list. 

2. A range list applies only to the first object file following the range specification. If the object 
file contains more than one module, the range list will only apply to the first module in the object 
file. 

The following examples illustrate the use of the Open Watcom Far Call Optimization Enabling Utility. 
Example: 

fcenable -c code *.obj 

In the above example, the far call optimization will be enabled for all segments belonging to the "code" 
class. 

Example: 

fcenable -s _ text *.obj 

In the above example, the far call optimization will be enabled for all segments with name "_text". 

Example: 

fcenable -x special 0:400 asmfile.obj 

In the above example, the far call optimization will be disabled for the first lk bytes of the segment named 
"special" in the object file "asmfile". 

Example: 

fcenable -x special 0-ffffffff asmfile.obj 

In the above example, the far call optimization will be disabled for the entire segment named "special" in 
the object file "asmfile". 
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6 The Open Watcom Exe2bin Utility 


The exe2bin utility strips off the header of a DOS executable file and applies any necessary fixups. In 
addition, it is able to display the header and relocations of an executable file in human readable format. 

When DOS executes a program (supplied as an ".exe" file) it first reads the header of the executable file 
and ensures there is enough memory to load the program. If there is, DOS loads the file — excluding the 
header — to memory. Before jumping to the entry point, DOS has to adjust a number of certain locations 
that depend on the load address of the program. These adjustments consist of the addition of the load 
address to each entry in the above mentioned list of relocations. These relocations are part of the header of 
an executable file. The load address may vary from invocation to invocation, this creates the need for the 
existence of relocations. 

As exe2bin strips the executable header, the relocations are lost (among other things). This would render 
the resulting output useless, if exe2bin were not to apply the relocations as part of the conversion process. 
Just like DOS, exe2bin therefore needs to know the load address. This is supplied via an argument to 
exe2bin. 

Some programs do not rely on the address they are being loaded at, and consequently do not contain any 
relocations. In this case exe2bin merely copies the contents of the input file (apart from the header) to the 
output file. 

The phrase "binary part" (also "binary data") is used as a technical term in the documentation of exe2bin. It 
denotes the data following the header. The length of the binary data is determined by the header entries 
"Size mod 512", "Number of pages" and "Size of header". It is not directly related to the actual size of the 
input file. 


Note: Although Open Watcom Exe2bin is capable of producing DOS ".COM" executables, this 
functionality is only provided for compatibility with other tools. The preferred way of generating 
".COM" executables is to use the Open Watcom Linker with directive "format dos com". Refer 
to the Open Watcom Linker Guide for details. 


6.1 The Open Watcom Exe2bin Utility Command Line 

The format of the Open Watcom Exe2bin command line is as follows. Items enclosed in square brackets 
("[ ]") are optional. 


EXE2BIN [options] exe_Jile [bin _Jile] 
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where 

options 


exe _Jile 


description: 


is a list of options, each preceded by a dash On non-UNIX platforms, a slash ("/") 

may be also used instead of a dash. Options may be specified in any order. Supported 
options are: 

li display the executable file header 

r display the relocations of the executable file 

l=<seg> specify the load address of the binary file 


x 


enable extended capabilities of Open Watcom Exe2bin 


is a file specification for a 16-bit DOS executable file used as input. If no file extension is 
specified, a file extension of ".exe" is assumed. Wild card specifiers may not be used. 


bin _file 


is an optional file specification for a binary output file. If no file name is given, the 
extension of the input file is replaced by "bin" and taken as the name for the binary output 
file. 


Description: 

1. If are any relocations in the input file, the -1 option becomes mandatory (and is useless 
otherwise). 

2. If exe2bin is called without the -x option, certain restrictions to the input file apply (apart from 
being a valid DOS executable file): 

• the size of the binary data must be <= 64 KByte 

• no stack must be defined, i.e. ss:sp = 0x0000:0x0000 

• the code segment must be always zero, i.e. cs = 0x0000 

• the initial instruction pointer must be either ip = 0x0000 or ip = 0x0100 
None of the above restrictions apply if the -x option is supplied. 

3. If cs:ip = 0x0000:0x0100 and the -x option is not specified, no relocations are allowed in the 
input file. Furthermore, exe2bin skips another 0x100 bytes following the header (in addition to 
the latter). 

This behaviour allows the creation of DOS ".COM" executables and is implemented for 
backward compatibility. It is however strongly suggested to use the Open Watcom Linker 
instead (together with directive " format dos com"). 

The examples below illustrate the use of Open Watcom Exe2bin. 
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Example: 

exe2bin prog.exe 

Strips off the executable header from prog. exe and writes the binary part to prog. bin . If there are 
any relocations in prog. exe or if the input file violates any of the restrictions listed above, the execution 
of exe2bin fails. 

Example: 

exe2bin -x prog.exe 

Same as above but the "-x" option relaxes certain restrictions. 


Note: Even if exe2bin is sucessfully invoked with identical input files as in the preceding examples (i.e. 
with vs. without -x) the output files may differ. This happens when cs:ip = 0x0000:0x0100 causes 
exe2bin to skip additional 0x100 bytes from the input file, if the user did not specify -x. 


Example: 

exe2bin -h prog.exe test.bin 

Displays the header of prog. exe , strips it off and copies the binary part to test. bin . 

Example: 

exe2bin -h -r -x -l=0xE000 bios.exe bios.rom 

Displays the header and the relocations (if any) of bios . exe strips the header and applies any fixups to 
(i.e. relocates) bios . exe as if it were to be loaded at OxEOOO:0x0000. The result will be written to 
bios.rom 

The above command line may serve as an example of creating a 128 KByte BIOS image for the PC-AT 
architecture. 


6.2 Exe2bin Messages 

This is a list of the diagnostic messages exe2bin may display, accompanied by more verbose descriptions 
and some possible causes. 

Error opening %s for reading. 

The input executable file could not be opened for reading. 

Check that the input file exists and exe2bin has read permissions. 

Error opening %s for writing. 

The output binary file could not be opened for writing. 

Make sure the media is not write protected, has enough free space to hold the output file, 
and exe2bin has write permissions. 

Error allocating file I/O buffer. 

There is not enough free memory to allocate a file buffer. 
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Error reading while copying data. 

An error occured while reading the binary part of the input file. 

This is most likely due to a corrupted executable header. Run exe2bin with the -h option 
and check the size reported. The size of the input file must be at least ("Number of pages" - 
1) * 512 + "Size mod 512". Omit decrementing the number of pages if "Size mod 512" 
happens to equal zero. 

Error writing while copying data. 

The output binary file can not be written to. 

Make sure the media has enough free space to hold the output file and is not removed while 
writing to it. 

Error. %s has no valid executable header. 

The signature (the first two bytes of the input file) does not match "MZ". 

exe2bin can only use valid DOS executable files as input. 

Error allocating/reading reloc-table. 

There is either not enough free memory to allocate a buffer for the relocations (each 
relocation takes about 4 bytes) or there was an error while reading from the input file. 

Error. Option "-l=<seg>" mandatory (there are relocations). 

The executable file contains relocations. Therefore, exe2bin needs to know the segment the 
binary output file is supposed to reside at. 

Either provide a segment as an argument to the -1 option or rewrite your executable file to 
not contain any relocations. 

Error: Binary part exceeds 64 KBytes. 

The binary part of the input file is larger than 64 KBytes. 

The restriction applies because the -x option was not specified. Check if the extended 
behaviour is suitable or rewrite the program to shorten the binary part. 

Error: Stack segment defined. 

The header defines an initial stack, i.e. ss:sp != 0x0000:0x0000. 

The restriction applies because the -x option was not specified. Check if the extended 
behaviour is suitable or rewrite the program to not have a segment of class "stack". 

Error: CS.IP neither 0x0000:0x0000 nor 0x0000:0x0100. 

The header defines an initial cs:ip not matching any of the two values. 

The restriction applies because the -x option was not specified. Check if the extended 
behaviour is suitable or rewrite the program to have a different entry point (cf. Open 
WatcomLinker "option start" ). 

Error: corn-file must not have relocations. 

Although the binary part is <= 64 KByte in length, there is no stack defined and the cs:ip is 
0x0000:0x0100, i.e. exe2bin assumes you try to generate a ".COM" executable, there are 
relocations in the input file. 
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".COM" files are not allowed to contain relocations. Either produce an ".EXE" file instead 
or rewrite the program to avoid the need for relocations. In order to do the latter, look for 
statements that refer to segments or groups such as mov ax, _ TEXT ormov ax, 
DGROUP. 
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7 The Open Watcom Patch Utility 


7.1 Introduction 


The Open Watcom Patch Utility is a utility program which may be used to apply patches or bug fixes to 
Open Watcom’s compilers and its associated tools. As problems are reported and fixed, patches are created 
and made available on Open Watcom’s BBS, Open Watcom’s FTP site, or CompuServe for users to 
download and apply to their copy of the tools. 

7.2 Applying a Patch 

The format of the BPATCH command line is: 


BP A TCH [options ] patch _Jile 


The square brackets [ ] denote items which are optional. 
where description: 

options is a list of valid Open Watcom Patch Utility options, each preceded by a dash 

Options may be specified in any order. The possible options are: 

-p Do not prompt for confirmation 

-b Do not create a .BAK file 

-q Print current patch level of file 

patch_Jile is the file specification for a patch file provided by Open Watcom. 

Suppose a patch file called "wlink.a" is supplied by Open Watcom to fix a bug in the file "WLINK.EXE". 
The patch may be applied by typing the command: 

bpatch wlink.a 

The Open Watcom Patch Utility locates the file C : \WATCOM\BINW\WLINK. EXE using the PATH 
environment variable. The actual name of the executable file is extracted from the file wlink . a . It then 
verifies that the file to be patched is the correct one by comparing the size of the file to be patched to the 
expected size. If the file sizes match, the program responds with: 

Ok to modify 'C:\WATCOM\BINW\WLINK.EXE'? [y|n] 

If you respond with "yes", BPATCH will modify the indicated file. If you respond with "no", BPATCH 
aborts. Once the patch has been applied the resulting file is verified. First the file size is checked to make 
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sure it matches the expected file size. If the file size matches, a check-sum is computed and compared to 
the expected check-sum. 

Notes: 

1. If an error message is issued during the patch process, the file that you specified to be patched 
will remain unchanged. 

2. If a sequence of patch files exist, such as "wlink.a", "wlink.b" and "wlink.c", the patches must be 
applied in order. That is, "wlink.a" must be applied first followed by "wlink.b" and finally 
"wlink.c". 


7.3 Diagnostic Messages 

If the patch cannot be successfully applied, one of the following error messages will be displayed. 

Usage: BPATCH j-p} {-q} j-bj <file> 

-p = Do not prompt for confirmation 
-b = Do not create a .BAKfile 
-q = Print current patch level of file 
The command line was entered with no arguments. 

not been patched 

This message is issued when the "-q" option is used and the file has not been patched. 
been patched to level ’%s ’ 

This message is issued when the "-q" option is used and the file has been patched to the 
indicated level. 

already been patched to level ’%s ’ - skipping 
This message is issued when the file has already been patched to the same level or higher. 

Command line may only contain one file name 

More than one file name is specified on the command line. Make sure that"/" is not used 
as an option delimiter. 

Command line must specify a file name 

No file name has been specified on the command line. 

’%s ’ is not a Open Watcom patch file 

The patch file is not of the required format. The required header information is not present. 
’%.v ’ is not a valid Open Watcom patch file 

The patch file is not of the required format. The required header information is present but 
the remaining contents of the file have been corrupted. 

’%.v ’ is the wrong size (%lul). Should be (%lu2) 

The size of the file to be patched (%lul) is not the same as the expected size (%lu2). 

Cannot find ’%s ’ 

Cannot find the executable to be patched. 


File ’%s ’ has 

File ’%s ’ has 

File ’%s ’ has 
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Cannot open ’%.v ’ 

An error occurred while trying to open the patch file, the file to be patched or the resulting 
file. 

Cannot read ’%s’ 

An input error occurred while reading the old version of the file being patched. 

Cannot rename ’%s’ to ’%s ’ 

The file to be patched could not be renamed to the backup file name or the resulting file 
could not be renamed to the name of the file that was patched. 

Cannot write to ’%s’ 

An output error occurred while writing to the new version of the file to be patched. 

I/O error processing file ’%s ’ 

An error occurred while seeking in the specified file. 

No memory for %s 

An attempt to allocate memory dynamically failed. 

Patch program aborted! 

This message is issued if you answered no to the "OK to modify" prompt. 

Resulting file has wrong checksum (%lu) - Should be (%lu2) 

The check-sum of the resulting file (%lu) does not match the expected check-sum (%lu2). 
This message is issued if you have patched the wrong version. 

Resulting file has wrong size (%lul) - Should be (%lu2) 

The size of the resulting file (%lul) does not match the expected size (%lu2). This 
message is issued if you have patched the wrong version. 
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8 The Open Watcom Strip Utility 

8.1 Introduction 


The Open Watcom Strip Utility may be used to manipulate information that is appended to the end of an 
executable file. The information can be either one of two things: 

1. Symbolic debugging information 

2. Resource information 

This information can be added or removed from the executable file. Symbolic debugging information is 
placed at the end of an executable file by the Open Watcom Linker or the Open Watcom Strip Utility. 
Resource information is placed at the end of an executable by a resource compiler or the Open Watcom 
Strip Utility. 

Once a program has been debugged, the Open Watcom Strip Utility allows you to remove the debugging 
information from the executable file so that you do not have to remove the debugging directives from the 
linker directive file and link your program again. Removal of the debugging information reduces the size 
of the executable image. 

All executable files generated by the Open Watcom Linker can be specified as input to the Open Watcom 
Strip Utility. Note that for executable files created for Novell’s NetWare operating system, debugging 
information created using the "NOVELL" option in the "DEBUG" directive cannot be removed from the 
executable file. You must remove the "DEBUG" directive from the directive file and re-link your 
application. 

The Open Watcom Strip Utility currently runs under the following operating systems. 

•DOS 

•OS/2 

• QNX 

• Windows NT/2000/XP 

• Windows 95/98/Me 


8.2 The Open Watcom Strip Utility Command Line 

The Open Watcom Strip Utility command line syntax is: 
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WSTRIP [options] input Jile [output_file] [info_file] 


where: 


[] The square brackets denote items which are optional. 

options 

-n (noerrors) Do not issue any diagnostic message. 

-q (quiet) Do not print any informational messages. 

-r (resources) Process resource information rather than debugging 

information. 

-a (add) Add information rather than remove information. 


input_file 


is a file specification for the name of an executable file. If no file extension is specified, 
the Open Watcom Strip Utility will assume one of the following extensions: "exe", "dll", 
"exp", "rex", "nlm", "dsk", "lan", "nam", "msl", "cdm", "ham",''qnx" or no file extension. 
Note that the order specified in the list of file extensions is the order in which the Open 
Watcom Strip Utility will select file extensions. 


output_file is an optional file specification for the output file. If no file extension is specified, the file 

extension specified in the input file name will be used for the output file name. Ifis 
specified, the input file name will be used. 


info_file is an optional file specification for the file in which the debugging or resource information 

is to be stored (when removing information) or read (when adding information). If no file 
extension is specified, a file extension of "sym" is assumed for debugging information and 
"res" for resource information. To specify the name of the information file but not the 
name of an output file, a "." may be specified in place of output Jile. 


Description: 

1. If the "r" (resource) option is not specified then the default action is to add/remove symbolic 
debugging information. 

2. If the "a" (add) option is not specified then the default action is to remove information. 

3. If output_file is not specified, the debugging or resource information is added to or removed 
from input_file. 

4. If output_file is specified, input Jile is copied to output_file and the debugging or resource 
information is added to or removed from output Jile. input Jile remains unchanged. 

5. If info Jile is specified then the debugging or resource information that is added to or removed 
from the executable file is read from or written to this file. The debugging or resource 
information may be appended to the executable by specifying the "a" (add) option. Also, the 
debugging information may be appended to the executable by concatenating the debugging 
information file to the end of the executable file (the files must be treated as binary files). 
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6. During processing, the Open Watcom Strip Utility will create a temporary file, ensuring that a 
file by the chosen name does not already exist. 

8.3 Strip Utility Messages 

The following messages may be issued by the Open Watcom Strip Utility. 

Usage: WST RIP [options] inputJile [outputJile] [info_file] 
options: (-option is also accepted) 

In don’t print warning messages 
/q don’t print informational messages 

lr process resource information rather than debugging information 
/a add information rather than delete information 
input_file: executable file 
output Jile: optional output executable or ’ 
info Jile: optional output debugging or resource information file 
or input debugging or resource informational file 
The command line was entered with no arguments. 

Too low on memory 

There is not enough free memory to allocate file buffers. 

Unable to find ’%s ’ 

The specified file could not be located. 

Cannot create temporary file 

All the temporary file names are in use. 

Unable to open ’%s ’ to read 

The input executable file cannot be opened for reading. 

’%s’ is not a valid executable file 

The input file has invalid executable file header information. 

’%s’ does not contain debugging information 

There is nothing to strip from the specified executable file. 

Seek error on ’%s ’ 

An error occurred during a seek operation on the specified file. 

Unable to create output file ’%s ’ 

The output file could not be created. Check that the output disk is not write-protected or 
that the specified output file is not marked "read-only". 

Unable to create symbol file ’%s’ 

The symbol file could not be created. 

Error reading ’%s ’ 

An error occurred while reading the input executable file. 

Error writing to ’%s ’ 

An error occurred while writing the output executable file or the symbol file. Check the 
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amount of free space on the output disk. If the input and output files reside on the same 
disk, there might not be enough room for a second copy of the executable file during 
processing. 

Cannot erase file ’%s ’ 

The input executable file is probably marked "read-only" and therefore could not be erased 
(the input file is erased whenever the output file has the same name). 

Cannot rename file ’%s’ 

The output executable file could not be renamed. Ordinarily, this should never occur. 
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9 The Open Watcom Make Utility 


9.1 Introduction 


The Open Watcom Make utility is useful in the development of programs and text processing but is general 
enough to be used in many different applications. Make uses the fact that each file has a time-stamp 
associated with it that indicates the last time the file was updated. Make uses this time-stamp to decide 
which files are out of date with respect to each other. For instance, if we have an input data file and an 
output report file we would like the output report file to accurately reflect the contents of the input data file. 
In terms of time-stamps, we would like the output report to have a more recent time-stamp than the input 
data file (we will say that the output report file should be "younger" than the input data file). If the input 
file had been modified then we would know from the younger time-stamp (in comparison to the report file ) 
that the report file was out of date and should be updated. Make may be used in this and many other 
situations to ensure that files are kept up to date. 

Some readers will be quite familiar with the concepts of the Make file maintenance tool. Open Watcom 
Make is patterned after the Make utility found on UNIX systems. The next major section is simply 
intended to summarize, for reference purposes only, the syntax and options of Make’s command line and 
special macros. Subsequent sections go into the philosophy and capabilities of Open Watcom Make. If 
you are not familiar with the capabilities of the Make utility, we recommend that you skip to the next major 
section entitled "Dependency Declarations" and read on. 


9.2 Open Watcom Make Reference 

The following sub-sections serve as a reference guide to the Open Watcom Make utility. 

9.2.1 Open Watcom Make Command Line Format 

The formal Open Watcom Make command line syntax is shown below. 


WMAKE [options] [macro _defs] [targets] 


As indicated by the square brackets [ ], all items are optional. 

options is a list of valid Open Watcom Make options, each preceded by a slash ("/") or a dash ("—"). 

Options may be specified in any order. 

macro_defs is a list of valid Open Watcom Make macro definitions. Macro definitions are of the form: 

A=B 


and are readily identified by the presence of the "=" (the "#" character may be used instead 
of the "=" character if necessary). Surround the definition with quotes (") if it contains 
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blanks (e.g., "debug_opt=debug all"). The macro definitions specified on the command 
line supersede any macro definitions defined in makefiles. Macro names are 
case-insensitive unless the "ms" option is used to select Microsoft NMAKE mode. 

targets is one or more targets described in the makefile. 

9.2.2 Open Watcom Make Options Summary 

In this section, we present a terse summary of the Open Watcom Make options. This summary is displayed 
on the screen by simply entering "WMAKE ?" on the command line. 

Example: 

C>wmake ? 

-a make all targets by ignoring time-stamps 

-b block/ignore all implicit rules 

-c do not verify the existence of files made 

-d debug mode - echo all work as it progresses 

-e always erase target after error/interrupt (disables prompting) 

-/ the next parameter is a name of dependency description file 

-h do not print out Make identification lines (no header) 

-i ignore return status of all commands executed 

-k on error/interrupt: continue on next target 

-/ the next parameter is the name of a output log file 

-m do not search for MAKEINIT file 

-ms Microsoft NMAKE mode 

-n no execute mode - print commands without executing 

-o use circular implicit rule path 

-p print the dependency tree as understood from the file 

-q query mode - check targets without updating them 

-r do not use default definitions 

-s silent mode - do not print commands before execution 

-sn noisy mode - always print commands before execution 

-t touch files instead of executing commands 

-u UNIX compatibility mode 

-v verbose listing of inline files 

-y show why a target will be updated 

-z do not erase target after error/interrupt (disables prompting) 

9.2.3 Command Line Options 

Command line options, available with Open Watcom Make, allow you to control the processing of the 
makefile. 


a 

make all targets by ignoring time-stamps 

The "a" option is a safe way to update every target. For program maintenance, it is the preferred method 
over deleting object files or touching source files. 
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b 

block/ignore all implicit rules 

The "b" option will indicate to Make that you do not want any implicit rule checking done. The "b" option 
is useful in makefiles containing double colon explicit rules because an implicit rule search is 
conducted after a double colon target is updated. Including the directive . BLOCK in a makefile also 
will disable implicit rule checking. 

c 

do not verify the existence of files made 

Make will check to ensure that a target exists after the associated command list is executed. The target 
existence checking may be disabled with the "c" option. The "c" option is useful in processing makefiles 
that were developed with other Make utilities. The . NOCHECK directive is used to disable target existence 
checks in a makefile. 

d 

debug mode - echo all work as it progresses 

The "d" option will print out information about the time-stamp of files and indicate how the makefile 
processing is proceeding. 

e 

always erase target after error/interrupt (disables prompting) 

The "e" option will indicate to Make that, if an error or interrupt occurs during makefile processing, the 
current target being made may be deleted without prompting. The . ERASE directive may be used as an 
equivalent option in a makefile. 

f 

the next parameter is a name of dependency description file 

The "f" option specifies that the next parameter on the command line is the name of a makefile which must 
be processed. If the "f" option is specified then the search for the default makefile named "MAKEFILE" is 
not done. Any number of makefiles may be processed with the "f" option. 

Example: 

wmake /f myfile 

wmake /f myfilel /f myfile2 

h 

do not print out Make identification lines (no header) 

The "h" option is useful for less verbose output. Combined with the "q" option, this allows a batch file to 
silently query if an application is up to date. Combined with the "n" option, a batch file could be produced 
containing the commands necessary to update the application. 

/ 

ignore return status of all commands executed 
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The "i" option is equivalent to the . IGNORE directive. 


k 

on error/interrupt: continue on next target 

Make will stop updating targets when a non-zero status is returned by a command. The "k" option will 
continue processing targets that do not depend on the target that caused the error. The . CONTINUE 
directive in a makefile will enable this error handling capability. 

/ 

the next parameter is the name of a output log file 

Make will output an error message when a non-zero status is returned by a command. The "1" option 
specifies a file that will record all error messages output by Make during the processing of the makefile. 

m 

do not search for the MAKEINIT file 

The default action for Make is to search for an initialization file called "MAKEINIT" or "TOOLS.INI" if 
the "ms" option is set. The "m" option will indicate to Make that processing of the MAKEINIT file is not 
desired. 

ms 

Microsoft NMAKE mode 

The default action for Make is to process makefiles using Open Watcom syntax rules. The "ms" option will 
indicate to Make that it should process makefiles using Microsoft syntax rules. For example, the line 
continuation in NMAKE is a backslash ("\") at the end of the line. 

n 

no execute mode - print commands without executing 

The "n" option will print out what commands should be executed to update the application without actually 
executing them. Combined with the "h" option, a batch file could be produced which would contain the 
commands necessary to update the application. 

Example: 

wmake /h /n >update.bat 
update 

This is useful for applications which require all available resources (memory and devices) for executing the 
updating commands. 

0 

use circular implicit rule path 

When this option is specified. Make will use a circular path specification search which may save on disk 
activity for large makefiles. The "o" option is equivalent to the . OPTIMIZE directive. 
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P 

print out makefile information 

The "p" option will cause Make to print out information about all the explicit rules, implicit rules, and 
macro definitions. 


query mode - check targets without updating them 

The "q" option will cause Make to return a status of 1 if the application requires updating; it will return a 
status of 0 otherwise. Here is a example batch file using the "q" option: 

Example: 

wmake /q 

if errorstatus 0 goto noupdate 
wmake /q /h /n >\tmp\update.bat 
call \tmp\update.bat 
: noupdate 


do not use default definitions 
The default definitions are: 

_ MAKEOPTS_ = <options passed to WMAKE> 

_MAKEFILES_ = <list of makefiles> 

_ VERSION_ = <version number> 

_ LOADDLL_ = defined if DLL loading supported 

_MSDOS_ = defined if MS/DOS version 

_NT_ = defined if Windows NT version 

_NT386_ = defined if x86 Windows NT version 

_ OS2 = defined if OS/2 version 

_ QNX = defined if QNX version 

_ LINUX_ = defined if Linux version 

_LINUX386_ = defined if x86 Linux version 

_ UNIX_ = defined if QNX or Linux version 

MAKE = <name of file containing WMAKE> 

#endif 

# clear .EXTENSIONS list 
.EXTENSIONS: 

# In general, 

# set .EXTENSIONS list as follows 
.EXTENSIONS: .exe .nlm .dsk .lan .exp & 

.lib .obj & 

. i & 

.asm .c .cpp .cxx .cc .for .pas .cob & 

.h .hpp .hxx .hh . fi .mif .inc 

For Microsoft NMAKE compatibility (when you use the "ms" option), the following default definitions are 
established. 
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# For Microsoft NMAKE compatibility switch, 

# set .EXTENSIONS list as follows 
.EXTENSIONS: .exe .obj .asm ,c .cpp .cxx & 

.bas .cbl .for .f ,f90 .pas .res 


%MAKEFLAGS = $(%MAKEFLAGS) $ (_MAKEOPTS_) 

MAKE=<name of file containing WMAKE> 

AS=ml 


BC=bc 

CC=cl 

COBOL=cobol 

CPP=cl 

CXX=cl 

FOR=f1 

PASCAL=pl 

RC=rc 

.asm.exe: 

$(AS) $(AFLAGS) 
.asm.obj: 

$(AS) $(AFLAGS) 
.c.exe: 

$(CC) $(CFLAGS) 
. c . ob j : 

$(CC) $(CFLAGS) 


$* . asm 
/c $*.asm 
$* . c 
/c $* . c 


.cpp.exe: 

$(CPP) $(CPPFLAGS) $ *.cpp 
. cpp.obj: 

$(CPP) $(CPPFLAGS) /c $ *.cpp 


.cxx.exe: 


$(CXX) $(CXXFLAGS) $*.cxx 
. cxx.obj: 

$(CXX) $(CXXFLAGS) $*.cxx 
. bas.obj: 

$ (BC) $(BFLAGS) $*.bas 


. cbl.exe: 

$(COBOL) $(COBFLAGS) $*.cbl, $*.exe; 
. cbl.obj: 

$(COBOL) $(COBFLAGS) $*.cbl; 

.f.exe: 

$(FOR) $(FFLAGS) $*.f 
. f . ob j : 

$(FOR) /c $ (FFLAGS) $*.f 
.f90.exe: 

$(FOR) $(FFLAGS) $*.f90 
.f90.obj: 

$(FOR) /c $(FFLAGS) $*.f90 
.for.exe: 

$(FOR) $(FFLAGS) $*.for 
. for.obj: 

$(FOR) /c $(FFLAGS) $*.for 
.pas.exe: 

$(PASCAL) $(PFLAGS) $*.pas 
.pas.obj: 

$(PASCAL) /c $(PFLAGS) $*.pas 
.rc.res: 

$(RC) $(RFLAGS) /r $* 


. rc 


80 Open Watcom Make Reference 




The Open Watcom Make Utility 


For OS/2, the_ MSDOS _macro will be replaced by_ OS2 _and for Windows NT, the_ MSDOS. 

macro will be replaced by_ NT_. 

For UNIX make compatibility (when you use the "u" option), the following default definition is 
established. 

.EXTENSIONS: .exe ,obj .c ,y .1 .f 

%MAKEFLAGS = $(%MAKEFLAGS) $ (_MAKEOPTS_) 

MAKE=<name of file containing WMAKE> 

YACC=yacc 

YFLAGS= 

LEX=lex 

LFLAGS= 

LDFLAGS= 

CC=cl 
FC=f 1 


. asm.exe: 


$ (AS) 

$(AFLAGS) 

$*.asm 



c .exe: 





$ (CC) 

$ (CFLAGS) 

$(LDFLAGS) 

-o $@ 

$< 

f.exe: 





$ (FC) 

$ (FFLAGS) 

$(LDFLAGS) 

-o $@ 

$< 

c . ob j : 





$ (CC) 

$ (CFLAGS) 

1 

o 

<r> 

A 



f . ob j : 





$ (FC) 

$ (FFLAGS) 

-c $< 




.y.obj : 

$(YACC) $(YFLAGS) $< 

$(CC) $(CFLAGS) -c y.tab.c 

del y.tab.c 

move y.tab.obj $@ 

. 1. ob j : 

$(LEX) $(LFLAGS) $< 

$(CC) $(CFLAGS) -c lex.yy.c 

del lex.yy.c 

move lex.yy.obj $@ 

.y.c: 

$(YACC) $(YFLAGS) $< 
move y.tab.c $@ 

. 1. c : 

$(LEX) $(LFLAGS) $< 
move lex.yy.c $@ 


The "r" option will disable these definitions before processing any makefiles. 


silent mode - do not print commands before execution 
The "s" option is equivalent to the . SILENT directive. 


noisy mode - always print commands before execution 

The "sn" option overrules all silencing controls. It can be used to assist in debugging a makefile. 
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t 

touch files instead of executing commands 

Sometimes there are changes which are purely cosmetic (adding a comment to a source file) that will cause 
targets to be updated needlessly thus wasting computer resources. The "t" option will make files appear 
younger without altering their contents. The "t" option is useful but should be used with caution. 

U 

UNIX compatibility mode 

The "u" option will indicate to Make that the line continuation character should be a backslash "\" rather 
than an ampersand "&". 

V 

The "v" option enables a verbose listing of inline temporary files. 

y 

The "y" option enables the display of a progress line denoting which dependent file has caused a target to 
be updated. This is a useful option for helping to debug makefiles. 

Z 

do not erase target after error/interrupt (disables prompting) 

The "z" option will indicate to Make that if an error or interrupt occurs during makefile processing then the 
current target being made should not be deleted. The . HOLD directive in a makefile has the same effect as 
the "z" option. 

9.2.4 Special Macros 

Open Watcom Make has many different special macros. Here are some of the simpler ones. 


Macro 

Expansion 

$$ 

represents the character "$" 

$# 

represents the character "#" 

$@ 

full file name of the target 

$* 

target with the extension removed 

$< 

list of all dependents 

$? 

list of dependents that are younger than the target 


The following macros are for more sophisticated makefiles. 

Macro Expansion 

_MSDOS _ This macro is defined in the MS/DOS environment. 

_NT_ This macro is defined in the Windows NT environment. 

_OS2 _ This macro is defined in the OS/2 environment. 
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_LINUX_ 

_QNX_ 

_UNIX_ 

_MAKEOPTS_ 

_MAKEFILES. 

MAKE 

VERSION 


This macro is defined in the Linux environment. 

This macro is defined in the QNX environment. 

This macro is defined in the Linux or QNX environment. 

contains all of the command line options that WMAKE was invoked with except 
for any use of the "f" or "n" options. 

contains the names of all of the makefiles processed at the time of expansion 
(includes the file currently being processed) 

contains the full name of the file that contains WMAKE 

contains the wmake version. 


The next three tables contain macros that are valid during execution of command lists for explicit rules, 
implicit mles, and the . ERROR directive. The expansion is presented for the following example: 

Example: 

a:\dir\target.ext : b:\dirl\depl.exl c:\dir2\dep2.ex2 


Macro 

Expansion 

$ A @ 

a:\dir\target.ext 

$ A * 

a:\dir\target 

$ A & 

target 

$ A . 

target.ext 

$ A : 

a:\dir\ 

Macro 

Expansion 

$[@ 

b:\dirl\depl.exl 

$[* 

b:\dirl\depl 

$[& 

depl 

$[. 

depl.exl 

$[: 

b:\dir 1\ 

Macro 

Expansion 

$]@ 

c:\dir2\dep2.ex2 

$]* 

c:\dir2\dep2 

$]& 

dep2 

$]. 

dep2.ex2 

$]: 

c:\dir2\ 
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9.3 Dependency Declarations 

In order for Open Watcom Make to be effective, a list of file dependencies must be declared. The 
declarations may be entered into a text file of any name but Make will read a file called "MAKEFILE" by 
default if it is invoked as follows: 

Example: 

C>wmake 

If you want to use a file that is not called "MAKEFILE" then the command line option "f" will cause Make 
to read the specified file instead of the default "MAKEFILE". 

Example: 

C>wmake /f myfile 

We will now go through an example to illustrate how Make may be used for a simple application. Suppose 
we have an input file, a report file, and a report generator program then we may declare a dependency as 
follows: 

# 

# (a comment in a makefile starts with a "#") 

# simple dependency declaration 

# 

balance.1st : ledger.dat 
doreport 

Note that the dependency declaration starts at the beginning of a line while commands always have at least 
one blank or tab before them. This form of a dependency declaration is called an explicit rule. The file 
"BALANCE.LST" is called the target of the rule. The dependent of the rule is the file "LEDGER.DAT" 
while "DOREPORT" forms one line of the rule command list. The dependent is separated from the target 
by a colon. 


Hint: A good habit to develop is to always put spaces around the colon so that it will not be confused 
with drive specifications (e.g., a:). 


The explicit rule declaration indicates to Make that the program "DOREPORT" should be executed if 
"LEDGER.DAT" is younger than "BALANCE.LST" or if "BALANCE.LST" does not yet exist. In 
general, if the dependent file has a more recent modification date and time than the target file then Open 
Watcom Make will execute the specified command. 


Note: The terminology employed here is used by S.I.Feldman of Bell Laboratories in Make - A 
Program for Maintaining Computer Programs. 

http://www.softlab.ntua.gr/facilities/documentation/unix/docs/make.txt has a copy of this seminal 
article. Confusion often arises from the use of the word "dependent". In this context, it means "a 
subordinate part". In the example, "LEDGER.DAT" is a subordinate part of the report 
"BALANCE.LST". 
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9.4 Multiple Dependents 

Suppose that our report "BALANCE.LST" becomes out-of-date if any of the files "LEDGER.DAT", 
"SALES.DAT" or "PURCHASE.DAT" are modified. We may modify the dependency rule as follows: 

# 

# multiple dependents rule 

# 

balance.1st : ledger.dat sales.dat purchase.dat 
doreport 

This is an example of a rule with multiple dependents. In this situation, the program "DOREPORT" should 
be executed if any of "LEDGER.DAT", "SALES.DAT" or "PURCHASE.DAT" are younger than 
"BALANCE.LST" or if "BALANCE.LST" does not yet exist. In cases where there are multiple 
dependents, if any of the dependent files has a more recent modification date and time than the target file 
then Open Watcom Make will execute the specified command. 


9.5 Multiple Targets 

Suppose that the "DOREPORT" program produces two reports. If both of these reports require updating as 
a result of modification to the dependent files, we could change the rule as follows: 

# 

# multiple targets and multiple dependents rule 

# 

balance.1st summary.1st : ledger.dat sales.dat purchase.dat 
doreport 

Suppose that you entered the command: 
wmake 

which causes Make to start processing the rules described in "MAKEFILE". In the case where multiple 
targets are listed in the makefile. Make will, by default, process only the first target it encounters. In the 
example. Make will check the date and time of "BALANCE.LST" against its dependents since this is the 
first target listed. 

To indicate that some other target should be processed, the target is specified as an argument to the Make 
command. 

Example: 

wmake summary.1st 

There are a number of interesting points to consider: 

1. By default. Make will only check that the target file exists after the command ( "DOREPORT" in 
this example) is executed. It does not check that the target’s time-stamp shows it to be younger. 
If the target file does not exist after the command has been executed, an error is reported. 

2. There is no guarantee that the command you have specified does update the target file. In other 
words, simply because you have stated a dependency does not mean that one exists. 
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3. Furthermore, it is not implied that other targets in our list will not be updated. In the case of our 
example, you can assume that we have designed the "doreport" command to update both targets. 


9.6 Multiple Rules 

A makefile may consist of any number of rules. Note that the following: 

targetl target2 : dependentl dependents dependents 
command list 

is equivalent to: 

targetl : dependentl dependent2 dependents 
command list 

target2 : dependentl dependent2 dependents 
command list 

Also, the rules may depend on the targets of other rules. 

# 

# rule 1: this rule uses rule 2 

# 

balance.1st summary.1st : ledger.dat sales.dat purchase.dat 
doreport 

# 

# rule 2: used by rules 1 and 3 

# 

sales.dat : canada.dat england.dat usa.dat 
dosales 


# 

# rule 3: this rule uses rule 2 

# 

year.1st : ledger.dat sales.dat purchase.dat 
doyearly 

The dependents are checked to see if they are the targets of any other rules in the makefile in which case 
they are updated. This process of updating dependents that are targets in other rules continues until a rule is 
reached that has only simple dependents that are not targets of rules. At this point, if the target does not 
exist or if any of the dependents is younger than the target then the command list associated with the rule is 
executed. 


Hint: The term "updating", in this context, refers to the process of checking the time-stamps of 
dependents and running the specified command list whenever they are out-of-date. Whenever a 
dependent is the target of some other rule, the dependent must be brought up-to-date first. Stated 
another way, if "A" depends on "B" and "B" depends on "C" and "C" is younger than "B" then we must 
update "B" before we update "A". 


Make will check to ensure that the target exists after its associated command list is executed. The target 
existence checking may be disabled in two ways: 
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1. use the command line option "c" 

2. use the . NOCHECK directive. 

The rule checking returns to the previous rule that had the target as a dependent. Upon returning to the 
rule, the command list is executed if the target does not exist or if any of the updated dependents are now 
younger than the target. If you were to type: 

wmake 

here are the steps that would occur with the previous makefile: 
update(balance.1st) (rule 1) 


update(ledger.dat) 

(not 

a 

target 

update(sales.dat) 

(found 

rule 2 

update(Canada.dat) 

(not 

a 

target 

update(england.dat) 

(not 

a 

target 

update(usa.dat) 

(not 

a 

target 


IF sales.dat does not exist OR 

any of (Canada.dat,england.dat, usa.dat) 
is younger than sales.dat 
THEN execute "dosales" 

update(purchase.dat) (not a target) 

IF balance.1st does not exist OR 

any of (ledger.dat,sales.dat,purchase.dat) 
is younger than (balance.1st) 

THEN execute "doreport" 

The third rule in the makefile will not be included in this update sequence of steps. Recall that the default 
target that is "updated" is the first target in the first rule encountered in the makefile. This is the default 
action taken by Make when no target is specified on the command line. If you were to type: 

wmake year.1st 

then the file "YEAR.LST" would be updated. As Make reads the rules in "MAKEFILE", it discovers that 
updating "YEAR.LST" involves updating "SALES.DAT". The update sequence is similar to the previous 
example. 


9.7 Command Lists 

A command list is a sequence of one or more commands. Each command is preceded by one or more 
spaces or tabs. Command lists may also be used to construct inline files "on the fly". Macros substitute in 
command lists and in inline files. An inline file is introduced by "«" in a command in a command list. 
Data to insert into that file is placed (left-justified) in the command list. The data is terminated by "«" in 
the first column. It is not possible to place a line which starts "«" in an inline file. More than one inline 
file may be created in a command. Data for each is placed in order of reference in the command. 

In building the Open Watcom system, it is sometimes necessary to do some text substitution with a program 
called vi. This needs a file of instructions. The following simplifies an example used to build Open 
Watcom so that inline files may be shown. Without inline files, this is done as: 
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$(dllname).imp : $(dllname).lbc ../../trimlbc.vi 
cp $(dllname).lbc $(dllname).imp 
$(vi) -s ../../trimlbc.vi $(dllname).imp 

where trimlbc.vi consists of 
set magic 

set magicstring = () 
atomic 

%s/\ .dll'/'/ 

% s / A (\+\ + ') (.*) ('\.' .*')\. [0-9]+$/\l\2\3. .'\2'/ 
x 

A doubled "$" to produce a single dollar is notable when an inline file is used: 

$(dllname).imp : $(dllname).lbc 

cp $(dllname).lbc $(dllname).imp 
$(vi) -s << $(dllname).imp 
set magic 

set magicstring = () 
atomic 

%s/\ .dll'/'/ 

% s / A (\ + \ + ') (.*) ('\.' .*')\. [0-9]+$$/\l\2\3. .'\2'/ 
x 

<< 

A filename may follow a "«" on a command line to cause a file with that name to be created. (Otherwise, 
’WMAKE’ chooses a name.) "keep" or "nokeep" may follow a terminating "«" to show what to do with 
the file after usage. The default is "nokeep" which zaps it. 

9.8 Final Commands (.AFTER) 

The . AFTER directive specifies commands for Make to run after it has done all other commands. See the 
section entitled "Command List Directives" on page 126 for a full description of its use. 

9.9 Ignoring Dependent Timestamps (.ALWAYS) 

The . ALWAYS directive indicates to Make that the target should always be updated regardless of the 
timestamps of its dependents. 

# 

# .always directive 

# 

foo : bar .always 
wtouch $@ 

foo is updated each time Make is run. 
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9.10 Automatic Dependency Detection (.AUTODEPEND) 

Explicit listing of dependencies in a makefile can often be tedious in the development and maintenance 
phases of a project. The Open Watcom F77 compiler will insert dependency information into the object 
file as it processes source files so that a complete snapshot of the files necessary to build the object file are 
recorded. Since all files do not have dependency information contained within them in a standard form, it 
is necessary to indicate to Make when dependencies are present. 

To illustrate the use of the . AUTODEPEND directive, we will show its use in an implicit rule and in an 
explicit rule. 

# 

# .AUTODEPEND example 

# 

.for.obj: .AUTODEPEND 

wfc386 $[* $(compile_ options) 

test.exe : a.obj b.obj c.obj test.res 
wlink FILE a.obj, b.obj, c.obj 
wrc /q /bt=windows test.res test.exe 

test.res : test.rc test.ico .AUTODEPEND 

wrc /ad /q /bt=windows /r $[@ $~@ 

In the above example. Make will use the contents of the object file to determine whether the object file has 
to be built during processing. The Open Watcom Resource Compiler can also insert dependency 
information into a resource file that can be used by Make. 

9.11 Initial Commands (.BEFORE) 

The . BEFORE directive specifies commands for Make to run before it does any other command. See the 
section entitled "Command List Directives" on page 126 for a full description of its use. 

9.12 Disable Implicit Rules (.BLOCK) 

The . BLOCK directive and the "b" command line option are alternative controls to cause implicit rules to 
be ignored. See the section entitled "Command Line Options" on page 76 for a full description of its use. 

9.13 Ignoring Errors (.CONTINUE) 

The . CONTINUE directive and the "b" command line option are alternative controls to cause failing 
commands to be ignored. See the section entitled "Command Line Options" on page 76 for a full 
description of its use. 
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# 

# .continue example 

# 

.continue 

all: bad good 
@%null 


bad: 

false 

good: 

touch $@ 

Although the command list for bad fails, that for good is done. Without the directive, good is not built. 


9.14 Default Command List (.DEFAULT) 

The . DEFAULT directive provides a default command list for those targets which lack one. See the section 
entitled "Command List Directives" on page 126 for a full description of its use. 

# 

# .default example 

# 

.default 

Secho Using default rule to update target "$@" 

Secho because of dependent(s) "$<" 

wtouch $@ 

all: foo 

f oo: 

wtouch foo 

"all" has no command list. The one supplied to the default directive is executed instead. 


9.15 Erasing Targets After Error (.ERASE) 

Most operating system utilities and programs have special return codes that indicate error conditions. Open 
Watcom Make will check the return code for every command executed. If the return code is non-zero. 
Make will stop processing the current rule and optionally delete the current target being updated. By 
default. Make will prompt for deletion of the current target. The . ERASE directive indicates to Make that 
the target should be deleted if an error occurs during the execution of the associated command list. No 
prompt is issued in this case. Here is an example of the . ERASE directive: 

# 

# .ERASE example 

# 

.ERASE 

balance.1st : ledger.dat sales.dat purchase.dat 
doreport 
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If the program "DOREPORT" executes and its return code is non-zero then Make will attempt to delete 
"BALANCE.LST". 


9.16 Error Action (.ERROR) 

The . ERROR directive supplies a command list for error conditions. See the section entitled "Command 
List Directives" on page 126 for a full description of its use. 

# 

# .error example 

# 

.error: 

@echo it is good that "$@" is known 

all : .symbolic 
false 


9.17Ignoring Target Timestamp (.EXISTSONLY) 

The . EXISTSONLY directive indicates to Make that the target should not be updated if it already exists, 
regardless of its timestamp. 

# 

# .existsonly directive 

# 

foo: .existsonly 
wtouch $@ 

If absent, this file creates foo; if present, this file does nothing. 


9.18 Specifying Explicitly Updated Targets (.EXPLICIT) 

The . EXPLICIT directive may me used to specify a target that needs to be explicitly updated. Normally, 
the first target in a makefule will be implicitly updated if no target is specified on Make command line. 
The . EXPLICIT directive prevents this, and is useful for instance when creating files designed to be 
included for other make files. 

# 

# .EXPLICIT example 

# 

target : .symbolic .explicit 

@echo updating first target 

next : .symbolic 

@echo updating next target 

In the above example. Make will not automatically update "target", despite the fact that it is the first one 
listed. 
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9.19 Defining Recognized File Extensions (.EXTENSIONS) 

The . EXTENSIONS directive and its synonym, the . SUFFIXES directive declare which extensions are 
allowed to be used in implicit rules and how these extensions are ordered. . EXTENSIONS is the 
traditional Watcom name; . SUFFIXES is the corresponding POSIX name. The default .EXTENSIONS 
declaration is: 

.EXTENSIONS: 

.EXTENSIONS: .exe .nlm .dsk .lan .exp .lib .obj & 

.i .asm .c .cpp .cxx .cc .for .pas .cob & 

.h .hpp .hxx .hh .fi .mif .inc 

A .EXTENSIONS directive with an empty list will clear the . EXTENSIONS list and any previously 
defined implicit rules. Any subsequent . EXTENSIONS directives will add extensions to the end of the list. 


Hint: The default . EXTENSIONS declaration could have been coded as: 

.EXTENSIONS 


.EXTENSIONS 

.exe 

.EXTENSIONS 

.nlm .dsk .lan .exp 

.EXTENSIONS 

.lib 

.EXTENSIONS 

•obj 

.EXTENSIONS 

.i .asm .c .cpp .cxx .cc 

.EXTENSIONS 

.for .pas .cob 

.EXTENSIONS 

.h .hpp .hxx .hh .fi .mif .inc 

.EXTENSIONS 

.inc 

with identical results. 


Make will not allow any implicit rule declarations that use extensions that are not in the current 
.EXTENSIONS list. 

# 

# .extensions and .suffixes directives 

# 

.suffixes : # Clear list 
.extensions : .foo .bar 

.bar.foo: 

copy $< $@ 

fubar.foo: 

fubar.bar: .existsonly 
wtouch $@ 

The first time this example runs. Make creates fubar.foo. This example always ensures that fubar.foo is a 
copy of fubar.bar. Note the implicit connection beween the two files. 
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9.20 Approximate Timestamp Matching (.FUZZY) 

The . FUZZY directive allows . AUTODEPEND times to be out by a minute without considering a target out 
of date. It is only useful in conjunction with the . JUST_ ENOUGH directive when Make is calculating the 
timestamp to set the target to. 

9.21 Preserving Targets After Error (.HOLD) 

Most operating system utilities and programs have special return codes that indicate error conditions. Open 
Watcom Make will check the return code for every command executed. If the return code is non-zero. 
Make will stop processing the current rule and optionally delete the current target being updated. By 
default. Make will prompt for deletion of the current target. The . HOLD directive indicates to Make that 
the target should not be deleted if an error occurs during the execution of the associated command list. No 
prompt is issued in this case. The . HOLD directive is similar to . PRECIOUS but applies to all targets 
listed in the makefile. Here is an example of the . HOLD directive: 

# 

# .HOLD example 

# 

.HOLD 

balance.1st : ledger.dat sales.dat purchase.dat 
doreport 

If the program "DOREPORT" executes and its return code is non-zero then Make will not delete 
"BALANCE.LST". 


9.22 Ignoring Return Codes (.IGNORE) 

Some programs do not have meaningful return codes so for these programs we want to ignore the return 
code completely. There are different ways to ignore return codes namely, 

1. use the command line option "i" 

2. put a " in front of specific commands, or 

3. use the . IGNORE directive. 

In the following example, the rule: 

# 

# ignore return code example 

# 

balance.1st : ledger.dat sales.dat purchase.dat 
-doreport 

will ignore the return status from the program "DOREPORT". Using the dash in front of the command is 
the preferred method for ignoring return codes because it allows Make to check all the other return codes. 

The . IGNORE directive is used as follows: 


Ignoring Return Codes (.IGNORE) 
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# 

# .IGNORE example 

# 

.IGNORE 

balance.1st : ledger.dat sales.dat purchase.dat 
doreport 

Using the . IGNORE directive will cause Make to ignore the return code for every command. The "i" 
command line option and the . IGNORE directive prohibit Make from performing any error checking on the 
commands executed and, as such, should be used with caution. 

Another way to handle non-zero return codes is to continue processing targets which do not depend on the 
target that had a non-zero return code during execution of its associated command list. There are two ways 
of indicating to Make that processing should continue after a non-zero return code: 

1. use the command line option "k" 

2. use the . CONTINUE directive. 


9.23 Minimising Target Timestamp (.JUST_ENOUGH) 

The . JUST_ ENOUGH directive is equivalent to the "j" command line option. The timestamps of created 
targets are set to be the same as those of their youngest dependendents. 

# 

# .JUST_ ENOUGH example 

# 

.just_ enough 
.c.exe: 

wcl386 -zq $< 
hello.exe: 

hello.exe is given the same timestamp as hello.c, and not the usual timestamp corresponding to when 
hello.exe was built. 


9.24 Updating Targets Multiple Times (.MULTIPLE) 

The . MULTIPLE directive is used to update a target multiple times. Normally, Make will only update 
each target once while processing a makefile. The . MULTIPLE directive is useful if a target needs to be 
updated more than once, for instance in case the target is desUoyed during processing of other targets. 
Consider the following example: 
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# 

# example not using .multiple 

# 

all: targl targ2 

target: 

wtouch target 

targl: target 

rm target 
wtouch targl 

targ2: target 

rm target 
wtouch targ2 

This makefile will fail because "target" is destroyed when updating "targl", and later is implicitly expected 
to exist when updating "targ2". Using the . MULTIPLE directive will work around this problem: 

# 

# .MULTIPLE example 

# 

all : targl targ2 

target : .multiple 

wtouch target 

targl : target 

rm target 
wtouch targl 

targ2 : target 

rm target 
wtouch targ2 


Now Make will attempt to update "target" again when updating "targ2", discover that "target" doesn't exist, 
and recreate it. 


9.25 Ignoring Target Timestamp (.NOCHECK) 

The . NOCHECK directive is used to disable target existence checks in a makefile. See the section entitled 
"Command Line Options" on page 76 for a full description of its use. 

9.26 Cache Search Path (.OPTIMIZE) 

The . OPTIMIZE directive and the equivalent "o" command line option cause Make to use a circular path 
search. If a file is found in a particular directory, that directory will be the first searched for the next file. 
See the section entitled "Command Line Options" on page 76 for a full description of its use. 
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9.27 Preserving Targets (.PRECIOUS) 

Most operating system utilities and programs have special return codes that indicate error conditions. Open 
Watcom Make will check the return code for every command executed. If the return code is non-zero. 
Make will stop processing the current rule and optionally delete the current target being updated. If a file is 
precious enough that this treatment of return codes is not wanted then the .PRECIOUS directive may be 
used. The . PRECIOUS directive indicates to Make that the target should not be deleted if an error occurs 
during the execution of the associated command list. Here is an example of the .PRECIOUS directive: 

# 

# .PRECIOUS example 

# 

balance summary : sales.dat purchase.dat .PRECIOUS 
doreport 


If the program "DOREPORT" executes and its return code is non-zero then Make will not attempt to delete 
"BALANCE" or "SUMMARY". If only one of the files is precious then the makefile could be coded as 
follows: 

# 

# .PRECIOUS example 

# 

balance : .PRECIOUS 

balance summary : sales.dat purchase.dat 
doreport 

The file "BALANCE.LST" will not be deleted if an error occurs while the program "DOREPORT" is 
executing. 

9.28 Name Command Sequence (PROCEDURE) 

The . PROCEDURE directive may be used to construct "procedures" in a makefile. 

# 

# .procedure example 

# 

all: .symbolic 
@%make proc 

proc: .procedure 

@echo Executing procedure "proc" 

9.29 Re-Checking Target Timestamp (RECHECK) 

Make will re-check the target’s timestamp, rather than assuming it was updated by its command list. This 
is useful if the target is built by another make- style tool, as in the following example: 
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# 

# .RECHECK example 

# 

foo.gz : foo 

gzip foo 

foo : .ALWAYS .RECHECK 

nant -buildfile:foo.build 

foo’s command list will always be run, but foo will only be compressed if the timestamp is actually 
changed. 

9.30 Suppressing Terminal Output (.SILENT) 

As commands are executed. Open Watcom Make will print out the current command before it is executed. 
It is possible to execute the makefile without having the commands printed. There are three ways to inhibit 
the printing of the commands before they are executed, namely: 

1. use the command line option "s" 

2. put an in front of specific commands, or 

3. use the . SILENT directive. 

In the following example, the rule: 

# 

# silent command example 

# 

balance summary : ledger.dat sales.dat purchase.dat 
@doreport 

will prevent the string "doreport" from being printed on the screen before the command is executed. 

The . SILENT directive is used as follows: 

# 

# .SILENT example 

# 

.SILENT 

balance summary : ledger.dat sales.dat purchase.dat 
doreport 

Using the . SILENT directive or the "s" command line option will inhibit the printing of all commands 
before they are executed. The "sn" command line option can be used to veto any silencing control. 

At this point, most of the capability of Make may be realized. Methods for making makefiles more 
succinct will be discussed. 
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9.31 Defining Recognized File Extensions (.SUFFIXES) 

The . SUFFIXES directive declares which extensions are allowed to be used in implicit rules and how 
these extensions are ordered. It is a synonym for the . EXTENSIONS directive. See the section entitled 
"Defining Recognized File Extensions (.EXTENSIONS)" on page 92 for a full description of both 
directives. 


9.32 Targets Without Any Dependents (.SYMBOLIC) 

There must always be at least one target in a rule but it is not necessary to have any dependents. If a target 
does not have any dependents, the command list associated with the rule will always be executed if the 
target is updated. 

You might ask, "What may a rule with no dependents be used for?". A rule with no dependents may be 
used to describe actions that are useful for the group of files being maintained. Possible uses include 
backing up files, cleaning up files, or printing files. 

To illustrate the use of the . SYMBOLIC directive, we will add two new rules to the previous example. 
First, we will omit the . SYMBOLIC directive and observe what will happen when it is not present. 

# 

# rule 4: backup the data files 

# 

backup : 

echo "insert backup disk" 
pause 

copy *.dat a: 

echo "backup complete" 

# 

# rule 5: cleanup temporary files 

# 

cleanup : 

del *.tmp 
del \tmp\*.* 

and then execute the command: 

wmake backup 

Make will execute the command list associated with the "backup" target and issue an error message 
indicating that the file "BACKUP" does not exist after the command list was executed. The same thing 
would happen if we typed: 

wmake cleanup 

In this makefile we are using "backup" and "cleanup" to represent actions we want performed. The names 
are not real files but rather they are symbolic names. This special type of target may be declared with the 
. SYMBOLIC directive. This time, we show rules 4 and 5 with the appropriate addition of . SYMBOLIC 
directives. 
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# 

# rule 4: backup the data files 

# 

backup : .SYMBOLIC 

echo "insert backup disk" 
pause 

copy *.dat a: 

echo "backup complete" 

# 

# rule 5: cleanup temporary files 

# 

cleanup : .SYMBOLIC 
del *.tmp 
del \tmp\*.* 


The use of the . SYMBOLIC directive indicates to Make that the target should always be updated internally 
after the command list associated with the rule has been executed. A short form for the common idiom of 
singular . SYMBOLIC targets like: 

target : .SYMBOLIC 
commands 


is: 


target 

commands 

This kind of target definition is useful for many types of management tasks that can be described in a 
makefile. 


9.33 Macros 


Open Watcom Make has a simple macro facility that may be used to improve makefiles by making them 
easier to read and maintain. A macro identifier may be composed from a string of alphabetic characters and 
numeric characters. The underscore character is also allowed in a macro identifier. If the macro identifier 
starts with a "%" character, the macro identifier represents an environment variable. For instance, the 
macro identifier "%path" represents the environment variable "path". 


Macro identifiers Valid? 

2morrow yes 

stitch_in_9 yes 

invalided no 

2b_or_not_2b yes 

%path yes 

reports yes 

!@#*% no 


We will use a programming example to show how macros are used. The programming example involves 
four FORTRAN 77 source files and two include files. Flere is the initial makefile (before macros): 
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# 

# programming example 

# (before macros) 

# 

plot.exe : main.obj input.obj calc.obj output.obj 
wlink @plot 

main.obj : main.for defs.fi globals.fi 
wfc386 main /mf /dl /warn 

calc.obj : calc.for defs.fi globals.fi 
wfc386 calc /mf /dl /warn 

input.obj : input.for defs.fi globals.fi 
wfc386 input /mf /dl /warn 

output.obj : output.for defs.fi globals.fi 
wfc386 output /mf /dl /warn 

Macros become useful when changes must be made to makefiles. If the programmer wanted to change the 
compiler options for the different compiles, the programmer would have to make a global change to the 
makefile. With this simple example, it is quite easy to make the change but try to imagine a more complex 
example with different programs having similar options. The global change made by the editor could cause 
problems by changing the options for other programs. A good habit to develop is to define macros for any 
programs that have command line options. In our example, we would change the makefile to be: 

# 

# programming example 

# (after macros) 

# 

link_ options = 

compiler = wfc386 

compile_ options = /mf /dl /warn 

plot.exe : main.obj input.obj calc.obj output.obj 
wlink $ (link_ options) Splot 

main.obj : main.for defs.fi globals.fi 

$(compiler) main $(compile_ options) 

calc.obj : calc.for defs.fi globals.fi 

$(compiler) calc $(compile_ options) 

input.obj : input.for defs.fi globals.fi 

$(compiler) input $(compile_ options) 

output.obj : output.for defs.fi globals.fi 

$(compiler) output $(compile_ options) 

A macro definition consists of a macro identifier starting on the beginning of the line followed by an "=" 
which in turn is followed by the text to be replaced. A macro may be redefined, with the latest declaration 
being used for subsequent expansions (no warning is given upon redefinition of a macro). The replacement 
text may contain macro references. 
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A macro reference may occur in two forms. The previous example illustrates one way to reference macros 
whereby the macro identifier is delimited by "$(" and ")". The parentheses are optional so the macros 
"compiler" and "compile_options" could be referenced by: 

main.obj : main.for defs.fi globals.fi 

$compiler main $compile_ options 

Certain ambiguities may arise with this form of macro reference. For instance, examine this makefile 
fragment: 

Example: 

temporary_ dir = \tmp\ 

temporary_ file = $temporary_ dirtmpOOO.tmp 

The intention of the declarations is to have a macro that will expand into a file specification for a temporary 
file. Make will collect the largest identifier possible before macro expansion occurs. The macro reference 
is followed by text that looks like part of the macro identifier ("tmpOOO") so the macro identifier that will 
be referenced will be "temporary_dirtmpOOO". The incorrect macro identifier will not be defined so an 
error message will be issued. 

If the makefile fragment was: 

temporary_ dir = \tmp\ 

temporary_ file = $(temporary_ dir)tmpOOO.tmp 

there would be no ambiguity. The preferred way to reference macros is to enclose the macro identifier by 
"$(" and ")". 

Macro references are expanded immediately on dependency lines (and thus may not contain references to 
macros that have not been defined) but other macro references have their expansion deferred until they are 
used in a command. In the previous example, the macros "link_options", "compiler", and 
"compile_options" will not be expanded until the commands that reference them are executed. 

Another use for macros is to replace large amounts of text with a much smaller macro reference. In our 
example, we only have two include files but suppose we had very many include files. Each explicit rule 
would be very large and difficult to read and maintain. We will use the previous example makefile to 
illustrate this use of macros. 

# 

# programming example 

# (with more macros) 

# 

link_ options = 

compiler = wfc386 

compile_ options = /mf /dl /warn 

include_ files = defs.fi globals.fi 
object_ files = main.obj input.obj calc.obj & 
output.obj 

plot.exe : $(object_ files) 

wlink $ (link_ options) Splot 

main.obj : main.for $(include_ files) 

$(compiler) main $(compile_ options) 
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calc.obj : calc.for $(include_ files) 

$(compiler) calc $(compile_ options) 

input.obj : input.for $(include_ files) 

$(compiler) input $(compile_ options) 

output.obj : output.for $(include_ files) 

$(compiler) output $(compile_ options) 

Notice the ampersand ("&") at the end of the macro definition for "object_files". The ampersand indicates 
that the macro definition continues on the next line. In general, if you want to continue a line in a makefile, 
use an ampersand ("&") at the end of the line. 

There are special macros provided by Make to access environment variable names. To access the PATH 
environment variable in a makefile, we use the macro identifier "%path". For example, if we have the 
following line in a command list: 

Example: 

echo $(%path) 

it will print out the current value of the PATH environment variable when it is executed. 

There are two other special environment macros that are predefined by Make. The macro identifier 
"%cdrive" will expand into one letter representing the current drive. Note that it is operating system 
dependent whether the cd command changes the current drive. The macro identifier "%cwd" will expand 
into the current working directory. These macro identifiers are not very useful unless we can specify that 
they be expanded immediately. The complementary macros "$+" and respectively turn on and turn 
off immediate expansion of macros. The scope of the "$+" macro is the current line after which the default 
macro expansion behaviour is resumed. A possible use of these macros is illustrated by the following 
example makefile. 

# 

# $(%cdrive), $(%cwd), $+, and $- example 

# 

dirl = $(%cdrive):$(%cwd) 
dir2 = $+ $(dirl) $- 
example : .SYMBOLIC 

cd . . 

echo $(dirl) 
echo $(dir2) 

Which would produce the following output if the current working directory is 
C:\WATCOM\SOURCE\EXAMPLE: 

Example: 

(command output only) 

C:\WATCOM\SOURCE 
C:\WATCOM\SOURCE\EXAMPLE 

The macro definition for "dir2" forces immediate expansion of the "%cdrive" and "%cwd" macros thus 
defining "dir2" to be the current directory that Make was invoked in. The macro "dirl" is not expanded 
until execution time when the current directory has changed from the initial directory. 

Combining the $+ and $- special macros with the special macro identifiers "%cdrive" and "%cwd" is a 
useful makefile technique. The $+ and $- special macros are general enough to be used in many different 
ways. 
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Constructing other macros is another use for the $+ and $- special macros. Make allows macros to be 
redefined and combining this with the $+ and $- special macros, similar looking macros may be 
constructed. 

# 

# macro construction with $+ and $- 

# 

template = filel.$(ext) file2.$(ext) file3.$(ext) file4.$(ext) 
ext = dat 

data_ files = $+ $(template) $- 
ext = 1st 

listing_ files = $+ $ (template) $- 

example : .SYMBOLIC 

echo $(data_ files) 
echo $(listing_ files) 

This makefile would produce the following output: 

Example: 

filel.dat file2.dat file3.dat file4.dat 
filel.lst file2.1st file3.1st file4.1st 

Adding more text to a macro can also be done with the $+ and $- special macros. 

# 

# macro addition with $+ and $- 

# 

objs = filel.obj file2.obj file3.obj 
objs = $+$(objs)$- file4.obj 
objs = $+$(objs)$- file5.obj 

example : .SYMBOLIC 
echo $(objs) 

This makefile would produce the following output: 

Example: 

filel.obj file2.obj file3.obj file4.obj file5.obj 

Make provides a shorthand notation for this type of macro operation. Text can be added to a macro by 
using the "+=" macro assignment. The previous makefile can be written as: 


# 

# macro addition with += 

# 

objs = filel.obj file2.obj file3.obj 
objs += file4.obj 
objs += file5.obj 

example : .SYMBOLIC 
echo $ (objs) 

and still produce the same results. The shorthand notation "+=" supported by Make provides a quick way 
to add more text to macros. 

Make provides the "linject" preprocessor directive to append a "word" (one or more graphic characters) to 
one or more macros. The previous makefile is adapted to show the usage: 
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# 

# macro construction with !inject 

# 

linject filel.obj objs objsl2 objsl3 
linject file2.obj objs objsl2 objsl3 
linject file3.obj objs objsl3 

linject file4.obj objs 
linject file5.obj objs 

example : .SYMBOLIC 
echo $ (objs) 
echo $ (objsl2) 
echo $ (objsl3) 
echo $ (objsl4) 
echo $(objsl5) 

This makefile would produce the following output: 

Example: 

filel.obj file2.obj file3.obj file4.obj file5.obj 
filel.obj file2.obj 
filel.obj file2.obj file3.obj 
filel.obj file2.obj file3.obj file4.obj 
filel.obj file2.obj file3.obj file4.obj file5.obj 

The "linject" preprocessor directive supported by Make provides a way to append a word to several macros. 

There are instances when it is useful to have macro identifiers that have macro references contained in 
them. If you wanted to print out an informative message before linking the executable that was different 
between the debugging and production version, we would express it as follows: 

# 

# programming example 

# (macro selection) 

# 

version = debugging # debugging version 

msg_ production = linking production version ... 
msg_ debugging = linking debug version ... 

link_ options_ production = 

link_ options_ debugging = debug all 

link_ options = $ (link_ options_ $ (version) ) 

compiler = wfc386 

compile_ options_ production = /mf /warn 
compile_ options_ debugging = /mf /dl /warn 
compile_ options = $ (compile_ options_ $ (version) ) 


objsl4 objsl5 
objsl4 objsl5 
objsl4 objsl5 
objsl4 objsl5 
objsl5 
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include_ files = defs.fi globals.fi 
object_ files = main.obj input.obj calc.obj & 
output.obj 

plot.exe : $(object_ files) 

echo $(msg_ $(version)) 
wlink $(link_ options) Splot 

main.obj : main.for $(include_ files) 

$(compiler) main $(compile_ options) 

calc.obj : calc.for $(include_ files) 

$(compiler) calc $(compile_ options) 

input.obj : input.for $(include_ files) 

$(compiler) input $(compile_ options) 

output.obj : output.for $(include_ files) 

$(compiler) output $(compile_ options) 

Take notice of the macro references that are of the form: 

$ (<partial_ macro_ identifier>$ (version) ) 

The expansion of a macro reference begins by expanding any macros seen until a matching right 
parenthesis is found. The macro identifier that is present after the matching parenthesis is found will be 
expanded. The other form of macro reference namely: 

$<macro_ identifier> 

may be used in a similar fashion. The previous example would be of the form: 

$<partial_ macro_ identifier>$version 

Macro expansion occurs until a character that cannot be in a macro identifier is found (on the same line as 
the "$") after which the resultant macro identifier is expanded. If you want two macros to be concatenated 
then the line would have to be coded: 

$(macrol)$(macro2) 

The use of parentheses is the preferred method for macro references because it completely specifies the 
order of expansion. 

In the previous example, we can see that the four command lines that invoke the compiler are very similar 
in form. We may make use of these similarities by denoting the command by a macro reference. We need 
to be able to define a macro that will expand into the correct command when processed. Fortunately, Make 
can reference the first member of the dependent list, the last member of the dependent list, and the current 
target being updated with the use of some special macros. These special macros have the form: 

$<file_ specifier><form_ qualifier> 

where <file_specifier> is one of: 
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" A " represents the current target being updated 

"[" represents the first member of the dependent list 

"]" represents the last member of the dependent list 

and <form_qualifier> is one of: 

full file name 

file name with extension removed 
"&" file name with path and extension removed 

file name with path removed 
path of file name 

If the file "D:\DIR1\DIR2\NAME.EXT" is the current target being updated then the following example will 
show how the form qualifiers are used. 


Macro 

Expansion for D:\DIR1\DIR2\NAME.EXT 

$ A @ 

D:\DIR1\DIR2\NAME.EXT 

$ A * 

D:\DIR1\DIR2\NAME 

$ A & 

NAME 

$ A . 

NAME.EXT 

$ A : 

D:\DIR1\DIR2\ 


These special macros provide the capability to reference targets and dependents in a variety of ways. 
# 

# programming example 

# (more macros) 

# 

version = debugging # debugging version 

msg_ production = linking production version ... 
msg_ debugging = linking debug version ... 

link_ options_ production = 

link_ options_ debugging = debug all 

link_ options = $ (link_ options_ $ (version) ) 
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compile_ options_ production = /mf /warn 
compile_ options_ debugging = /mf /dl /warn 
compile_ options = $ (compile_ options_ $ (version) ) 

compiler_ command = wfc386 $[* $ (compile_ options) 

include_ files = defs.fi globals.fi 
object_ files = main.obj input.obj calc.obj & 
output.obj 

plot.exe : $(object_ files) 

echo $(msg_ $(version)) 
wlink $ (link_ options) @$ A * 

main.obj : main.for $(include_ files) 

$(compiler_ command) 

calc.obj : calc.for $(include_ files) 

$ (compiler_ command) 

input.obj : input.for $(include_ files) 

$ (compiler_ command) 

output.obj : output.for $(include_ files) 

$ (compiler_ command) 

This example illustrates the use of the special dependency macros. Notice the use of "$ A *" in the linker 
command. The macro expands into the string "plot" since "plot.exe" is the target when the command is 
processed. The use of the special dependency macros is recommended because they make use of 
information that is already contained in the dependency rule. 

At this point, we know that macro references begin with a "$" and that comments begin with a "#". What 
happens if we want to use these characters without their special meaning? Make has two special macros 
that provide these characters to you. The special macro "$$" will result in a "$" when expanded and "$#" 
will expand into a "#". These special macros are provided so that you are not forced to work around the 
special meanings of the "$" and "#" characters. 

There is also a simple macro text substitution facility. We have previously seen that a macro call can be 
made with $(macroname). The construct $(macroname:stringl=string2) substitutes macroname with each 
occurrence of stringl replaced by string2. We have already seen that it can be useful for a macro to be a set 
of object file names separated by spaces. The file directive in wlink can accept a set of names separated by 
commas. 

# 

# programming example 

# (macro substitution) 

# 

. c . ob j : 

wfc386 -zq $*.c 

object_ files = main.obj input.obj calc.obj output.obj 

plot.exe : $(object_ files) 

wlink name $@ file $(object_ files: =,) 
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Note that macro substitution cannot be used with special macros. 

It is also worth noting that although the above example shows a valid approach, the same problem, that is, 
providing a list of object files to wlink, can be solved without macro subsitutions. The solution is using the 
{} syntax of wlink, as shown in the following example. Refer to the Open Watcom Linker Guide for 
details. 

# 

# programming example 

# (not using macro substitution) 

# 


.c.obj: 

wfc386 -zq $*.c 

object_ files = main.obj input.obj calc.obj output.obj 

plot.exe : $(object_ files) 

wlink name $@ file { $ (object_ files) } 


9.34 Implicit Rules 

Open Watcom Make is capable of accepting declarations of commonly used dependencies. These 
declarations are called "implicit rules" as opposed to "explicit rules" which were discussed previously. 
Implicit rules may be applied only in instances where you are able to describe a dependency in terms of file 
extensions. 


Hint: Recall that a file extension is the portion of the file name which follows the period. In the file 
specification: 

c:\dos\ansi.sys 

the file extension is "SYS". 


An implicit rule provides a command list for a dependency between files with certain extensions. The form 
of an implicit rule is as follows: 

. <dependent_ extension> . <target_ extension>: 

<command_ list> 

Implicit rules are used if a file has not been declared as a target in any explicit rule or the file has been 
declared as a target in an explicit rule with no command list. For a given target file, a search is conducted 
to see if there are any implicit rules defined for the target file’s extension in which case Make will then 
check if the file with the dependent extension in the implicit rule exists. If the file with the dependent 
extension exists then the command list associated with the implicit rule is executed and processing of the 
makefile continues. 

Other implicit rules for the target extension are searched in a similar fashion. The order in which the 
dependent extensions are checked becomes impoitant if there is more than one implicit rule declaration for 
a target extension. If we have the following makefile fragment: 
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Example: 

.pas.obj: 

(command list) 

.for.obj: 

(command list) 

an ambiguity arises. If we have a target file "TEST.OBJ" then which do we check for first, "TEST.PAS" or 
"TEST.FOR"? Make handles this with the previously described . EXTENSIONS directive. Returning to 
our makefile fragment: 

.pas.obj: 

(command list) 

.for.obj: 

(command list) 

and our target file "TEST.OBJ", we know that the . EXTENSIONS list determines in what order the 
dependents "TEST.PAS" and "TEST.FOR" will be tried. If the .EXTENSIONS declaration is: 

Example: 

.EXTENSIONS: 

.EXTENSIONS: .exe .obj .asm .pas .for .c .cob 

we can see that the dependent file "TEST.PAS" will be tried first as a possible dependent with 
"TEST.FOR" being tried next. 

One apparent problem with implicit rules and their associated command lists is that they are used for many 
different targets and dependents during the processing of a makefile. The same problem occurs with 
commands constructed from macros. Recall that there is a set of special macros that start with "$ A ", "$[", 
or "$]" that reference the target, first dependent, or last dependent of an explicit dependency rule. In an 
implicit rule there may be only one dependent or many dependents depending on whether the rule is being 
executed for a target with a single colon ":" or double colon dependency. If the target has a single 
colon or double colon dependency, the "$ A ", "$[", and "$]" special macros will reflect the values in the rule 
that caused the implicit rule to be invoked. Otherwise, if the target does not have a dependency rule then 
the "$[" and "$]" special macros will be set to the same value, namely, the file found in the implicit rule 
search. 

We will use the last programming example to illustrate a possible use of implicit rules. 

# 

# programming example 

# (implicit rules) 

# 

version = debugging # debugging version 

msg_ production = linking production version ... 
msg_ debugging = linking debug version ... 

link_ options_ production = 

link_ options_ debugging = debug all 

link_ options = $ (link_ options_ $ (version) ) 
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compiler = wfc386 

compile_ options_ production = /mf /warn 
compile_ options_ debugging = /mf /dl /warn 
compile_ options = $(compile_ options_ $(version) ) 

include_ files = defs.fi globals.fi 
object_ files = main.obj input.obj calc.obj & 
output.obj 

plot.exe : $(object_ files) 

echo $(msg_ $(version)) 
wlink $ (link_ options) @$ /v * 


.for.obj: 

$ (compiler) $[* $ (compile_ options) 

main.obj : main.for $(include_ files) 

calc.obj : calc.for $ (include_ files) 

input.obj : input.for $(include_ files) 

output.obj : output.for $(include_ files) 

As this makefile is processed, any time an object file is found to be older than its associated source file or 
include files then Make will attempt to execute the command list associated with the explicit rule. Since 
there are no command lists associated with the four object file targets, an implicit rule search is conducted. 
Suppose "CALC.OBJ" was older than "CALC.FOR". The lack of a command list in the explicit rule with 
"CALC.OBJ" as a target causes the ".for.obj" implicit rule to be invoked for "CALC.OBJ". The file 
"CALC.FOR" is found to exist so the commands 

wfc386 calc /mf /dl /warn 
echo linking debug version ... 
wlink debug all @plot 


are executed. The last two commands are a result of the compilation of "CALC.FOR" producing a 
"CALC.OBJ" file that is younger than the "PLOT.EXE" file that in turn must be generated again. 

The use of implicit rules is straightforward when all the files that the makefile deals with are in the current 
directory. Larger applications may have files that are in many different directories. Suppose we moved the 
programming example files to three sub-directories. 


Files 


Sub-directory 


include files 
source files 
rest 


\EXAMPLE\INC 
\EXAMPLE\SRC 
\EXAMPLE\0 


Now the previous makefile (located in the \EXAMPLE\O sub-directory) would look like this: 
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# 

# programming example 

# (implicit rules) 

# 

i_ dir = \example\inc\ #sub-directory containing include files 

s_ dir = \example\src\ #sub-directory containing source files 

version = debugging # debugging version 

msg_ production = linking production version ... 
msg_ debugging = linking debug version ... 

link_ options_ production = 

link_ options_ debugging = debug all 

link_ options = $ (link_ options_ $ (version) ) 

compiler = wfc386 

compile_ options_ production = /mf /warn 
compile_ options_ debugging = /mf /dl /warn 
compile_ options = $ (compile_ options_ $ (version) ) 

include_ files = $ (i_ dir) defs . fi $ (i_ dir) globals . fi 
object_ files = main.obj input.obj calc.obj & 
output.obj 

plot.exe : $(object_ files) 

echo $ (msg_ $ (version) ) 
wlink $(link_ options) 


.for.obj: 

$ (compiler) $[* $ (compile_ options) 
main.obj : $ (s_ dir)main. for $ (include_ files) 
calc.obj : $ (s_ dir) calc. for $ (include_ files) 
input, obj : $ (s_ dir) input. for $ (include_ files) 
output, obj : $ (s_ dir) output. for $ (include_ files) 

Suppose "\EXAMPLE\0\CALC.OBJ" was older than "\EXAMPLE\SRC\CALC.FOR". The lack of a 
command list in the explicit rule with "CALC.OBJ" as a target causes the ".for.obj" implicit rule to be 
invoked for "CALC.OBJ". At this time, the file "\EXAMPLE\O\CALC.FOR" is not found so an error is 
repotted indicating that "CALC.OBJ" could not be updated. How may implicit rules be useful in larger 
applications if they will only search the current directory for the dependent file? We must specify more 
information about the dependent extension (in this case ".FOR"). We do this by associating a path with the 
dependent extension as follows: 

. <dependent_ extension> : <path_ specif ication> 

This allows the implicit rule search to find the files with the dependent extension. 


Hint: A valid path specification is made up of directory specifications separated by semicolons 
Here are some path specifications: 

D :;C:\DOS;C:\UTILS;C:\WC 
C:\SYS 
A:\BIN;D: 

Notice that these path specifications are identical to the form required by the operating system shell's 
"PATH" command. 
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Our makefile will be correct now if we add the new declaration as follows: 

# 

# programming example 

# (implicit rules) 

# 

i_ dir = \example\inc\ #sub-directory containing include files 

s_ dir = \example\src\ #sub-directory containing source files 

version = debugging # debugging version 

msg_ production = linking production version ... 
msg_ debugging = linking debug version ... 

link_ options_ production = 

link_ options_ debugging = debug all 

link_ options = $ (link_ options_ $ (version) ) 

compiler = wfc386 

compile_ options_ production = /mf /warn 
compile_ options_ debugging = /mf /dl /warn 
compile_ options = $ (compile_ options_ $ (version) ) 

include_ files = $ (i_ dir) defs . fi $ (i_ dir) globals . fi 
object_ files = main.obj input.obj calc.obj & 
output.obj 

plot.exe : $(object_ files) 

echo $ (msg_ $(version)) 
wlink $ (link_ options) @$ A * 

. for: $ (s_ dir) 

.for.obj: 

$ (compiler) $[* $ (compile_ options) 
main.obj : $ (s_ dir)main. for $ (include_ files) 
calc.obj : $ (s_ dir) calc. for $ (include_ files) 
input, obj : $ (s_ dir) input. for $ (include_ files) 
output, obj : $ (s_ dir) output. for $ (include_ files) 

Suppose "\EXAMPLE\O\CALC.OBJ" is older than "\EXAMPLE\SRC\CALC.FOR". The lack of a 
command list in the explicit rule with "CALC.OBJ" as a target will cause the ".for.obj" implicit rule to be 
invoked for "CALC.OBJ". The dependent extension ".FOR" has a path associated with it so the file 
"\EXAMPLEVSRC\CALC.FOR" is found to exist. The commands 

wfc386 \EXAMPLE\SRC\CALC /mf /dl /warn 
echo linking debug version ... 
wlink debug all @plot 

are executed to update the necessary files. 

If the application requires many source files in different directories Make will search for the files using 
their associated path specifications. For instance, if the current example files were setup as follows: 

Sub-directory Contents 

\EXAMPLE\INC 

DEFS.FI, GLOBALS.FI 

\EXAMPLE\SRC\PROGRAM 

MAIN.FOR, CALC.FOR 
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\EXAMPLE\SRC\SCREEN 

INPUT.FOR, OUTPUT.FOR 


\EXAMPLE\O 

PLOT.EXE, MAKEFILE, MAIN.OBJ, CALC.OBJ, INPUT.OBJ, OUTPUT.OBJ 

the makefile would be changed to: 

# 

# programming example 

# (implicit rules) 

# 

i_ dir = ..\inc\ # sub-directory with include files 

# sub-directories with FORTRAN 77 source files 
program_ dir = ..\for\program\ # - MAIN.FOR, CALC.FOR 
screen, dir = ..\for\screen\ # - INPUT.FOR, OUTPUT.FOR 

version = debugging # debugging version 

msg_ production = linking production version ... 
msg_ debugging = linking debug version ... 

link_ options_ production = 

link_ options_ debugging = debug all 

link_ options = $ (link_ options_ $ (version) ) 

compiler = wfc386 

compile_ options_ production = /mf /warn 
compile_ options_ debugging = /mf /dl /warn 
compile_ options = $ (compile_ options_ $ (version) ) 

include_ files = $ (i_ dir) defs . fi $ (i_ dir) globals . fi 
object_ files = main.obj input.obj calc.obj & 
output.obj 

plot.exe : $(object_ files) 

echo $ (msg_ $(version)) 
wlink $ (link_ options) @$ A * 

. for: $ (program_ dir) ; $ (screen, dir) 

.for.obj: 

$ (compiler) $[* $ (compile_ options) 
main.obj : $ (program_ dir)main. for $ (include_ files) 
calc.obj : $ (program_ dir) calc. for $ (include_ files) 
input, obj : $ (screen, dir) input. for $ (include_ files) 
output, obj : $ (screen, dir) output. for $ (include_ files) 


Suppose that there is a change in the "DEFS.FI" file which causes all the source files to be recompiled. The 
implicit rule ".for.obj" is invoked for every object file so the corresponding ".FOR" file must be found for 
each ".OBJ" file. We will show where Make searches for the FORTRAN 77 source files. 


update main.obj 

test ..\for\program\main.for 

execute wfc386 ..\for\program\main /mf /dl 


(it does exist) 
/ warn 


update calc.obj 

test ..\for\program\calc.for 

execute wfc386 ..\for\program\calc /mf /dl 


(it does exist) 
/ warn 
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update input.obj 

test ..\for\program\input.for (it does not exist) 

test ..\for\screen\input.for (it does exist) 

execute wfc386 ..\for\screen\input /mf /dl /warn 

update output.obj 

test ..\for\program\output.for (it does not exist) 

test ..\for\screen\output.for (it does exist) 

execute wfc386 ..\for\screen\output /mf /dl /warn 

etc. 

Notice that Make checked the sub-directory ”..\SRC\PROGRAM" for the files "INPUT.FOR" and 
"OUTPUT.FOR". Make optionally may use a circular path specification search which may save on disk 
activity for large makefiles. The circular path searching may be used in two different ways: 

1. use the command line option "o" 

2. use the . OPTIMIZE directive. 

Make will retain (for each suffix) what sub-directory yielded the last successful search for a file. The 
search for a file is resumed at this directory in the hope that wasted disk activity will be minimized. If the 
file cannot be found in the sub-directory then Make will search the next sub-directory in the path 
specification (cycling to the first sub-directory in the path specification after an unsuccessful search in the 
last sub-directory). 

Changing the previous example to include this feature, results in the following: 

# 

# programming example 

# (optimized path searching) 

# 

.OPTIMIZE 

i_ dir = ..\inc\ # sub-directory with include files 

# sub-directories with FORTRAN 77 source files 
program_ dir = ..\for\program\ # - MAIN.FOR, CALC.FOR 
screen, dir = ..\for\screen\ # - INPUT.FOR, OUTPUT.FOR 

version = debugging # debugging version 

msg_ production = linking production version ... 
msg_ debugging = linking debug version ... 

link_ options_ production = 

link_ options_ debugging = debug all 

link_ options = $ (link_ options_ $ (version) ) 

compiler = wfc386 

compile_ options_ production = /mf /warn 
compile_ options_ debugging = /mf /dl /warn 
compile_ options = $ (compile_ options_ $ (version) ) 

include_ files = $ (i_ dir) defs . fi $ (i_ dir) globals . fi 
object_ files = main.obj input.obj calc.obj & 
output.obj 

plot.exe : $(object_ files) 

echo $ (msg_ $(version)) 
wlink $ (link_ options) @$ A * 

. for: $ (program_ dir) ; $ (screen, dir) 

.for.obj: 

$ (compiler) $[* $ (compile_ options) 
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main.obj : $ (program_ dir)main. for $ (include_ files) 
calc.obj : $ (program_ dir) calc. for $ (include_ files) 
input, obj : $ (screen, dir) input. for $ (include_ files) 
output, obj : $ (screen_ dir) output. for $ (include_ files) 


Suppose again that there is a change in the "DEFS.FI" file which causes all the source files to be 
recompiled. We will show where Make searches for the FORTRAN 77 source files using the optimized 
path specification searching. 


update 

test 

execute 

update 

test 

execute 

update 

test 

test 

execute 

update 

test 

execute 

etc. 


main.obj 

..\for\program\main.for (it does exist) 

wfc386 ..\for\program\main /mf /dl /warn 

calc.obj 

..\for\program\calc.for (it does exist) 

wfc386 ..\for\program\calc /mf /dl /warn 

input.obj 

..\for\program\input.for (it does not exist) 

..\for\screen\input.for (it does exist) 

wfc386 ..\for\screen\input /mf /dl /warn 

output.obj 

..\for\screen\output.for (it does exist) 

wfc386 ..\for\screen\output /mf /dl /warn 


Make did not check the sub-directory "..\SRC\PROGRAM" for the file "OUTPUT.FOR" because the last 
successful attempt to find a ".FOR" file occurred in the "..\SRC\SCREEN" sub-directory. In this small 
example, the amount of disk activity saved by Make is not substantial but the savings become much more 
pronounced in larger makefiles. 


Hint: The simple heuristic method that Make uses for optimizing path specification searches namely, 
keeping track of the last successful sub-directory, is very effective in reducing the amount of disk 
activity during the processing of a makefile. A pitfall to avoid is having two files with the same name 
in the path. The version of the file that is used to update the target depends on the previous searches. 
Care should be taken when using files that have the same name with path specifications. 


Farge makefiles for projects written in FORTRAN 77 may become difficult to maintain with all the include 
file dependencies. Ignoring include file dependencies and using implicit rules may reduce the size of the 
makefile while keeping most of the functionality intact. The previous example may be made smaller by 
using this idea. 
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# 

# programming example 

# (no include dependencies) 

# 

.OPTIMIZE 

i_ dir = ..\inc\ # sub-directory with include files 

# sub-directories with FORTRAN 77 source files 
program_ dir = ..\for\program\ # - MAIN.FOR, CALC.FOR 
screen, dir = ..\for\screen\ # - INPUT.FOR, OUTPUT.FOR 

version = debugging # debugging version 

msg_ production = linking production version ... 
msg_ debugging = linking debug version ... 

link_ options_ production = 

link_ options_ debugging = debug all 

link_ options = $ (link_ options_ $ (version) ) 

compiler = wfc386 

compile_ options_ production = /mf /warn 
compile_ options_ debugging = /mf /dl /warn 
compile_ options = $ (compile_ options_ $ (version) ) 

object_ files = main.obj input.obj calc.obj & 
output.obj 

plot.exe : $(object_ files) 

echo $ (msg_ $(version)) 
wlink $ (link_ options) 

. for: $ (program_ dir) ; $ (screen, dir) 

.for.obj: 

$ (compiler) $[* $ (compile_ options) 

Implicit rules are very useful in this regard providing you are aware that you have to make up for the 
information that is missing from the makefile. In the case of FORTRAN 77 programs, you must ensure 
that you force Make to compile any programs affected by changes in include files. Forcing Make to 
compile programs may be done by touching source files (not recommended), deleting object files, or using 
the "a" option and targets on the command line. Here is how the files "INPUT.OBJ" and "MAIN.OBJ" 
may be recompiled if a change in some include file affects both files. 

Example: 

del input.obj 
del main.obj 
wmake 

or using the "a" option 
Example: 

wmake /a input.obj main.obj 

The possibility of introducing bugs into programs is present when using this makefile technique because it 
does not protect the programmer completely from object modules becoming out-of-date. The use of 
implicit rules without header file dependencies is a viable makefile technique but it is not without its 
pitfalls. 
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9.35 Double Colon Explicit Rules 

Single colon explicit rules are useful in many makefile applications. However, the single colon rule has 
certain restrictions that make it difficult to express more complex dependency relationships. The 
restrictions imposed on single colon explicit rules are: 

1. only one command list is allowed for each target 

2. after the command list is executed, the target is considered up to date 

The first restriction becomes evident when you want to update a target in different ways (i.e., when the 
target is out of date with respect to different dependents). The double colon explicit rule removes this 
restriction. 

# 

# multiple command lists 

# 

targetl :: dependentl dependent2 
commandl 

targetl :: dependents dependent4 
command2 

Notice that if "targetl" is out of date with respect to either "dependentl" or "dependent2" then "commandl" 
will be executed. The double colon explicit rule does not consider the target (in this case "targetl") up 
to date after the command list is executed. Make will continue to attempt to update "targetl". Afterwards 
"command2" will be executed if "targetl" is out of date with respect to either "dependent3" or 
"dependent4". It is possible that both "commandl" and "command2" will be executed. As a result of the 
target not being considered up to date, an implicit rule search will be conducted on "targetl" also. Make 
will process the double colon explicit rules in the order that they are encountered in the makefile. 

9.36 Preprocessing Directives 

One of the primary objectives in using a make utility is to improve the development and maintenance of 
projects. A programming project consisting of many makefiles in different sub-directories may become 
unwieldy to maintain. The maintenance problem stems from the amount of duplicated information 
scattered throughout the project makefiles. Make provides a method to reduce the amount of duplicated 
information present in makefiles. Preprocessing directives provide the capability for different makefiles to 
make use of common information. 

9.36.1 File Inclusion 

A common solution to the "duplicated information" problem involves referencing text contained in one file 
from many different files. Make supports file inclusion with the ! include preprocessing directive. The 
development of object libraries, using 16-bit Open Watcom FORTRAN 77, for the different 80x86 16-bit 
memory models provides an ideal example to illustrate the use of the ! include preprocessing directive. 
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Sub-directory Contents 

\ WINDOW WINDOW. CMD, WINDOW.MIF 

\WINDOW\INC 

proto.fi, globals.fi, bios_def.fi 

\WINDOW\SRC 

WINDOW.FOR, KEYBOARD.FOR, MOUSE.FOR, BIOS.FOR 

\WINDOW\BCSD 

medium model object files, MAKEFILE, WINDOW_ M. LIB 

\WINDOW\BCBD 

large model object files, MAKEFILE, WINDOW_ L . LIB 

\WINDOW\BCHD 

huge model object files, MAKEFILE, WINDOW_ L . LIB 

The WLIB command file "WINDOW.CMD" contains the list of library operations required to build the 
libraries. The contents of "WINDOW.CMD" are: 

-+window 
-+bios 
-+keyboard 
—hmouse 

The library manager command indicates to WLIB that the object file should be replaced in the library. 

The file "WINDOW.MIF" contains the makefile declarations that are common to every memory model. 

The ".MIF" extension will be used for all the Make Include Files discussed in this manual. This extension 
is also in the default extension list so it is a recommended extension for Make include files. The contents of 
the "WINDOW.MIF" file is as follows: 

# 

# example of a Make Include File 

# 

common = /dl /warn # common options 

objs = window.obj bios.obj keyboard.obj mouse.obj 

.for: ..\src 

.for.obj: 

wfc $[* $(common) $ (local) /m$(model) 

window_ $(model).lib : $(objs) 

wlib window_ $(model) @..\window 

The macros "model" and "local" are defined by the file "MAKEFILE" in each object directory. An 
example of the file "MAKEFILE" in the medium memory model object directory is: 

# 

# !include example 

# 

model = m # memory model required 

local = # memory model specific options 

[include ..\window.mif 
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Notice that changes that affect all the memory models may be made in one file, namely "WINDOW.MIF". 
Any changes that are specific to a memory model may be made to the "MAKEFILE" in the object 
directory. To update the medium memory model library, the following commands may be executed: 

Example: 

C>cd \window\bcsd 
C>wmake 

A DOS ".BAT" or OS/2 ".CMD" file may be used to update all the different memory models. If the 
following DOS "MAKEALL.BAT" (OS/2 "MAKEALL.CMD") file is located somewhere in the "PATH", 
we may update all the libraries. 

cd \window\bcsd 

wmake "si "6 2 "6 3 "6 4 "65 ^6 7 *6 S ^9 

cd \window\bcbd 

wmake "si "6 2 "6 3 "6 4 "65 ^6 7 *63 9 

cd \window\bchd 

wmake "si "6 2 "6 3 "s4 "sS 6 7 "oB ^9 

The batch file parameters are useful if you want to specify options to Make. For instance, a global 

recompile may be done by executing: 

Example: 

C>makeall /a 

The ! include preprocessing directive is a good way to partition common information so that it may be 
maintained easily. 

Another use of the ! include involves program generated makefile information. For instance, if we have 
a program called "WMKMK" that will search through source files and generate a file called 
"WMKMK.MIF" that contains: 

# 

# program generated makefile information 

# 

FOR_ to_ OBJ = $ (compiler) $[* $ (compile_ options) 

OBJECTS = WINDOW.OBJ BIOS.OBJ KEYBOARD.OBJ MOUSE.OBJ 

WINDOW.OBJ : ..\SRC\WINDOW.FOR ..\INC\PROTO.FI ..\INC\GLOBALS-FI 

$ (FOR_ to_ OBJ) 

BIOS.OBJ : . .\SRC\BIOS . FOR . .\INC\BIOS_ DEF.FI . . \INC\GLOBALS . FI 

$ (FOR_ to_OBJ) 

KEYBOARD.OBJ : ..\SRC\KEYBOARD.FOR ..\INC\PROTO.FI ..\INC\GLOBALS.FI 

$ (FOR_ to_ OBJ) 

MOUSE.OBJ : ..\SRC\MOUSE.FOR ..\INC\PROTO.FI ..\INC\GLOBALS-FI 

$ (FOR_ to_OBJ) 

In order to use this program generated makefile information, we use a "MAKEFILE" containing: 
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# 

# makefile that makes use of generated makefile information 

# 

compile_ options = /mf /dl /warn 

first_ target : window.lib .SYMBOLIC 
echo done 

!include wmkmk.mif 

window.lib : $(OBJECTS) 

wlib window $(OBJECTS) 

make : .SYMBOLIC 

wmkmk /r ..\src\*.for+..\inc 

Notice that there is a symbolic target "first_target" that is used as a "place holder". The default behaviour 
for Make is to "make" the first target encountered in the makefile. The symbolic target "first_target" 
ensures that we have control over what file will be updated first (in this case "WINDOW.LIB"). The use of 
the ! include preprocessing directive simplifies the use of program generated makefile information 
because any changes are localized to the file "MAKEFILE". As program development continues, the file 
"WMKMK.MIF" may be regenerated so that subsequent invocations of WMAKE benefit from the new 
makefile information. The file "MAKEFILE" even contains the command to regenerate the file 
"WMKMK.MIF". The symbolic target "make" has an associated command list that will regenerate the file 
"WMKMK.MIF". The command list can be executed by typing the following command: 

Example: 

C>wmake make 

The use of the ! include preprocessing directive is a simple way to reduce maintenance of related 
makefiles. 


Hint: Macros are expanded on ! include preprocessor control lines. This allows many benefits like: 
!include $(%env_var) 

so that the files that Make will process can be controlled through many different avenues like internal 
macros, command line macros, and environment variables. 

Another way to access files is through the suffix path feature of Make. A definition like 
. mif: c:\mymifs;d:\some\more\mifs 

will cause Make to search different paths for any make include files. 


9.36.2 Conditional Processing 

Open Watcom Make has conditional preprocessing directives available that allow different declarations to 
be processed. The conditional preprocessing directives allow the makefile to 

1. check whether a macro is defined, and 

2. check whether a macro has a certain value. 

The macros that can be checked include 
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1. normal macros "$(<macro_identifier>)" 

2. environment macros "$(%<environment_var>)" 

The conditional preprocessing directives allow a makefile to adapt to different external conditions based on 
the values of macros or environment variables. We can define macros on the WMAKE command line as 
shown in the following example. 

Example: 

C>wmake "macro=some text with spaces in it" 

Alternatively, we can include a makefile that defines the macros if all the macros cannot fit on the 
command line. This is shown in the following example: 

Example: 

C>wmake /f macdef.mif /f makefile 

Also, environment variables can be set before WMAKE is invoked. This is shown in the following 
example: 

Example: 

C>set macro=some text with spaces in it 
C>wmake 

Now that we know how to convey information to Make through either macros or environment variables, we 
will look at how this information can be used to influence makefile processing. 

Make has conditional preprocessing directives that are similar to the C preprocessor directives. Make 
supports these preprocessor directives: 

! ifeq 
! ifneq 
!ifeqi 
! ifneqi 
! ifdef 
! ifndef 

along with 

! else 
! endif 

Together these preprocessor directives allow selection of makefile declarations to be based on either the 
value or the existence of a macro. 

Environment variables can be checked by using an environment variable name prefixed with a A 
common use of a conditional preprocessing directive involves setting environment variables. 

# 

# setting an environment variable 

# 

!ifndef %lib 
.BEFORE 

set lib=c:\watcom\lib386\dos 

!endif 
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If you are writing portable applications, you might want to have: 
# 

# checking a macro 

# 

[include version.mif 
!ifdef 0S2 


machine = 

/ 2 

# 

compile 

for 286 

! else 





machine = 

/O 

# 

default: 

8086 


!endif 

The ! if def ("if defined") and ! ifndef ("if not defined") conditional preprocessing directives are useful 
for checking boolean conditions. In other words, the ! ifdef and ! ifndef are useful for "yes-no" 
conditions. There are instances where it would be useful to check a macro against a value. In order to use 
the value checking preprocessor directives, we must know the exact value of a macro. A macro definition 
is of the form: 

<macro_ identifier> = <text> <comment> 

Make will first strip any comment off the line. The macro definition will then be the text following the 
equal "=" sign with leading and trailing blanks removed. Initially this might not seem like a sensible way 
to define a macro but it does lend itself well to defining macros that are common in makefiles. For 
instance, it allows definitions like: 

# 

# sample macro definitions 

# 

link_ options = debug line # line number debugging 

compile_ options = /dl /nostack # line numbers, no stack checking 

These definitions are both readable and useful. A makefile can handle differences between compilers with 
the lifeq, lifneq, lifeqiand ! ifneqi conditional preprocessing directives. The first two 
perform case sensitive comparisons while the last two perform case insensitive comparisons. One way of 
setting up adaptive makefiles is: 

# 

# options made simple 

# 

compiler = wfc386 

stack_ overflow = No # yes -> check for stack overflow 

line_ info = Yes # yes -> generate line numbers 

!ifeq compiler wfc386 
lifneqi stack_ overflow yes 

stack_ option = /nostack 

! endif 

lifeqi line_ info yes 

line_ option = /dl 

! endif 
! endif 
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!ifeq compiler fl32 
!ifeqi stack_ overflow yes 

stack_ option = -Ge 

!endif 

!ifeqi line_ info yes 

line_ option = -Zd 

!endif 
!endif 
# 


# make sure the macros are defined 

# 

lifndef stack_ option 
stack_ option = 

! endif 

lifndef line_ option 
line_ option = 

! endif 

example : .SYMBOLIC 

echo $ (compiler) $ (stack_ option) $(line_ option) 

The conditional preprocessing directives can be very useful to hide differences, exploit similarities, and 
organize declarations for applications that use many different programs. 

Another directive is the ! define directive. This directive is equivalent to the normal type of macro 
definition (i.e., macro = text) but will make C programmers feel more at home. One important distinction 
is that the ! define preprocessor directive may be used to reflect the logical structure of macro definitions 
in conditional processing. For instance, the previous makefile could have been written in this style: 

lifndef stack_ option 
1 define stack_ option 
1endif 

lifndef line_ option 
1 define line_ option 
1endif 

The "1" character must be in the first column but the directive keyword can be indented. This freedom 
applies to all of the preprocessing directives. The 1 else preprocessing directive benefits from this type of 
style because 1 else can also check conditions like: 

lelse ifeq 
lelse ifneq 
lelse ifeqi 
lelse ifneqi 
lelse ifdef 
lelse ifndef 

so that logical structures like: 
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lifdef %version 
! ifeq %version debugging 
! define option debug all 

! else ifeq %version beta 
! define option debug line 

! else ifeq %version production 
! define option debug 

! else 

! error invalid value in VERSION 

! endif 
!endif 

can be used. The above example checks the environment variable "VERSION" for three possible values 
and acts accordingly. 

Another derivative from the C language preprocessor is the ! error directive which has the form of 
! error <text> 

in Make. This directive will print out the text and terminate processing of the makefile. It is very useful in 
preventing errors from macros that are not defined properly. Here is an example of the ! error 
preprocessing directive. 

Iifndef stack_ option 

! error stack_ option is not defined 
!endif 

Iifndef line_ option 

! error line_ option is not defined 
!endif 

There is one more directive that can be used in a makefile. The ! undef preprocessing directive will clear 
a macro definition. The ! undef preprocessing directive has the form: 

!undef <macro_ identifier> 

The macro identifier can represent a normal macro or an environment variable. A macro can be cleared 
after it is no longer needed. Clearing a macro will reduce the memory requirements for a makefile. If the 
macro identifier represents an environment variable (i.e., the identifier has a prefix) then the 
environment variable will be deleted from the current environment. The ! undef preprocessing directive 
is useful for deleting environment variables and reducing the amount of internal memory required during 
makefile processing. 

9.36.3 Loading Dynamic Link Libraries 

Open Watcom Make supports loading of Dynamic Link Library (DLL) versions of Open Watcom software 
through the use of the ! loaddll preprocessing directive. This support is available on Win32 and 32-bit 
OS/2 platforms. Performance is greatly improved by avoiding a reload of the software for each file to be 
processed. The syntax of the ! loaddll preprocessing directive is: 

!loaddll $(exename) $(dllname) 

where $ (exename) is the command name used in the makefile and $ (dllname) is the name of the 
DLL to be loaded and executed in its place. Lor example, consider the following makefile which contains a 
list of commands and their corresponding DLL versions. 
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# Default compilation macros for sample programs 

# 

# Compile switches that are enabled 


CFLAGS = -dl 

CC = wpp386 $(CFLAGS) 

LFLAGS = DEBUG ALL 

LINK = wlink $(LFLAGS) 


ifdef_LOADDLL 


loaddll 

wcc 

weed 

loaddll 

wccaxp 

weedaxp 

loaddll 

wcc38 6 

wccd38 6 

loaddll 

wpp 

wppdi8 6 

loaddll 

wppaxp 

wppdaxp 

loaddll 

wpp38 6 

wppd38 6 

loaddll 

wlink 

wlinkd 

loaddll 

wlib 

wlibd 


endif 


. c . ob j : 

$(CC) $*.c 


The_ LOADDLL _symbol is defined for versions of Open Watcom Make that support th&oaddll 

preprocessing directive. The ! ifdef_LOADDLL _construct ensures that the makefile can be 

processed by an older version of Open Watcom Make. 

Make will look up the wpp3 8 6 command in its DLL load table and find a match. It will then attempt to 
load the corresponding DLL (i.e., wppd3 8 6.dll) and pass it the command line for processing. The 
lookup is case insensitive but must match in all other respects. For example, if a path is included with the 
command name then the same path must be specified in the ! loaddll preprocessing directive. This 
problem can be avoided through the use of macros as illustrated below. 
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# Default 

# 

# Compile 

# 

cc286 = 

cc286d = 
cc386 = 

cc386d = 
linker = 
linkerd = 


compilation macros for sample programs 

switches that are enabled 

wpp 

wppdi8 6 
wpp38 6 
wppd38 6 
wlink 
wlinkd 


CFLAGS = -dl 

CC = $ (cc386) $(CFLAGS) 


DEBUG ALL 
wlink $(LFLAGS) 


LFLAGS 

LINK 

!ifdef _ 
!loaddll 
!loaddll 
!loaddll 
!endif 


_ LOADDLL, 
$(cc286) 

$(cc386) 

$(linker) 


$ (cc286d) 

$ (cc386d) 

$(linkerd) 


. c . ob j : 

$(CC) $*.c 


A path and/or extension may be specified with the DLL name if desired. 


9.37 Command List Directives 


Open Watcom Make supports special directives that provide command lists for different purposes. If a 
command list cannot be found while updating a target then the directive . DEFAULT may be used to 
provide one. A simple . DEFAULT command list which makes the target appear to be updated is: 

.DEFAULT 

wtouch $ A @ 

The Open Watcom Touch utility sets the time-stamp on the file to the current time. The effect of the above 
rule will be to "update" the file without altering its contents. 

In some applications it is necessary to execute some commands before any other commands are executed 
and likewise it is useful to be able to execute some commands after all other commands are executed. 

Make supports this capability by checking to see if the . BEFORE and . AFTER directives have been used. 

If the . BEFORE directive has been used, the . BEFORE command list is executed before any commands are 
executed. Similarly the . AFTER command list is executed after processing is finished. It is important to 
note that if all the files are up to date and no commands must be executed, the . BEFORE and . AFTER 
command lists are never executed. If some commands are executed to update targets and errors are 
detected (non-zero return status, macro expansion errors), the . AFTER command list is not executed (the 
. ERROR directive supplies a command list for error conditions and is discussed in this section). These two 
directives may be used for maintenance as illustrated in the following example: 
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# 

# .BEFORE and .AFTER example 

# 

.BEFORE 

echo .BEFORE command list executed 

.AFTER 

echo .AFTER command list executed 

# 

# rest of makefile follows 

# 


If all the targets in the makefile are up to date then neither the . BEFORE nor the . AFTER command lists 
will be executed. If any of the targets are not up to date then before any commands to update the target are 
executed, the . BEFORE command list will be executed. The . AFTER command list will be executed only 
if there were no errors detected during the updating of the targets. The .BEFORE, .DEFAULT, and 
.AFTER command list directives provide the capability to execute commands before, during, and after the 
makefile processing. 


Make also supports the . ERROR directive. The . ERROR directive supplies a command list to be executed 
if an error occurs during the updating of a target. 


# 

# .ERROR example 

# 

.ERROR 


beep 

# 

# rest of makefile 

# 


follows 


The above makefile will audibly signal you that an error has occurred during the makefile processing. If 
any errors occur during the . ERROR command list execution, makefile processing is terminated. 


9.38 MAKEINIT File 


As you become proficient at using Open Watcom Make, you will probably want to isolate common 
makefile declarations so that there is less duplication among different makefiles. Make will search for a 
file called "MAKEINIT" (or "TOOLS.INI" when the "ms" option is set) and process it before any other 
makefiles. The search for the "MAKEINIT" file will occur along the current "PATH". If the file 
"MAKEINIT" is not found, processing continues without any errors. By default. Make defines a set of data 
described at the "r" option. The use of a "MAKEINIT" file will allow you to reuse common declarations 
and will result in simpler, more maintainable makefiles. 
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9.39 Command List Execution 


Open Watcom Make is a program which must execute other programs and operating system shell 
commands. There are three basic types of executable files in DOS. 

1. .COM files 

2. . EXE files 

3. .BAT files 

There are two basic types of executable files in Windows NT. 

1. .EXE files 

2. . BAT files 

There are two basic types of executable files in OS/2. 

1. .EXE files 

2. . CMD files 

The . COM and . EXE files may be loaded into memory and executed. The . BAT files must be executed by 
the DOS command processor or shell, "COMMAND.COM". The . CMD files must be executed by the 
OS/2 command processor or shell, "CMD.EXE" Make will search along the "PATH" for the command and 
depending on the file extension the file will be executed in the proper manner. 

If Make detects any input or output redirection characters (these are ">", "<", and "I") in the command, it 
will be executed by the shell. 

Under DOS, an asterisk prefix (*) will cause Make to examine the length of the command argument. If it is 
too long (> 126 characters), it will take the command argument and stuff it into a temporary environment 
variable and then execute the command with "@env_var" as its argument. Suppose the following sample 
makefile fragment contained a very long command line argument. 

# 

# Asterisk example 

# 

*foo myfile /a /b /c ... /x /y /z 

Make will perform something logically similar to the following steps. 

set TEMPVAR001=myfile /a /b /c ... /x /y /z 
too @TEMPVAR0 01 

The command must, of course, support the "@env_var" syntax. Typically, DOS commands do not support 
this syntax but many of the Open Watcom tools do. 

The exclamation mark prefix (!) will force a command to be executed by the shell. Also, the command will 
be executed by the shell if the command is an internal shell command from the following list: 


break 

(check for Ctrl+Break) 

call 

(nest batch files) 

chdir 

(change current directory) 

cd 

(change current directory) 
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els 

(clear the screen) 

cmd 

(start NT or OS/2 command processor) 

command 

(start DOS command processor) 

copy 

(copy or combine files) 

ctty 

(DOS redirect input/output to COM port) 

d: 

(change drive where "d" represents a drive specifier) 

date 

(set system date) 

del 

(erase files) 

dir 

(display contents in a directory) 

echo 

(display commands as they are processed) 

erase 

(erase files) 

for 

(repetitively process commands, intercepted by WMAKE) 

if 

(allow conditional processing of commands) 

md 

(make directory) 

mkdir 

(make directory) 

path 

(set search path) 

pause 

(suspend batch operations) 

prompt 

(change command prompt) 

ren 

(rename files) 

rename 

(rename files) 

rmdir 

(remove directory) 

rd 

(remove directory) 

rm 

(erase files or directories, intercepted by WMAKE) 

set 

(set environment variables, intercepted by WMAKE) 

time 

(set system time) 

type 

(display contents of a file) 

ver 

(display the operating system version number) 

verify 

(set data verification) 

vol 

(display disk volume label) 


The operating system shell "SET" command is intercepted by Make. The "SET" command may be used to 
set environment variables to values required during makefile processing. The environment variable 
changes are only valid during makefile processing and do not affect the values that were in effect before 
Make was invoked. The "SET" command may be used to initialize environment variables necessary for the 
makefile commands to execute properly. The setting of environment variables in makefiles reduces the 
number of "SET" commands required in the system initialization file. Here is an example with the Open 
Watcom F77 compiler. 

# 

# SET example 

# 

.BEFORE 

set finclude=c:\special\inc;$(%finclude) 
set lib=c:\watcom\lib386\dos 

# 

# rest of makefile follows 

# 


The first "SET" command will set up the FINCLUDE environment variable so that the Open Watcom F77 
compiler may find header files. Notice that the old value of the FINCLUDE environment variable is used 
in setting the new value. 
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The second "SET" command indicates to the Open Watcom Linker that libraries may be found in the 
indicated directories. 

Environment variables may be used also as dynamic variables that may communicate information between 
different parts of the makefile. An example of communication within a makefile is illustrated in the 
following example. 

# 

# internal makefile communication 

# 

.BEFORE 

set message=message text 1 
echo *$(%message)* 
set message= 
echo *$(%message)* 

.example : another_ target .SYMBOLIC 
echo *$(%message)* 

another_ target : .SYMBOLIC 

set message=message text 2 

The output of the previous makefile would be: 

(command output only) 

‘message text 1* 

★ ★ 

‘message text 2* 

Make handles the "SET" command so that it appears to work in an intuitive manner similar to the operating 
system shell's "SET" command. The "SET" command also may be used to allow commands to relay 
information to commands that are executed afterwards. 

The DOS "FOR" command is intercepted by Make. The reason for this is that DOS has a fixed limit for the 
size of a command thus making it unusable for large makefile applications. One such application that can 
be done easily with Make is the construction of a WLINK command file from a makefile. The idea behind 
the next example is to have one file that contains the list of object files. Anytime this file is changed, say, 
after a new module has been added, a new linker command file will be generated which in turn, will cause 
the linker to relink the executable. First we need the makefile to define the list of object files, this file is 
"OBJDEF.MIF" and it declares a macro "objs" which has as its value the list of object files in the 
application. The content of the "OBJDEF.MIF" file is: 

# 

# list of object files 

# 

objs = & 

window.obj & 
bios.obj & 
keyboard.obj & 
mouse.obj 

The main makefile ("MAKEFILE") is: 
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# 

# FOR command example 

# 

[include objdef.mif 

plot.exe : $ (objs) plot.Ink 
wlink @plot 

plot.Ink : objdef.mif 

echo NAME $ A & >$ A @ 
echo DEBUG all »$ A @ 

for %i in ($(objs)) do echo FILE %i >>$ A @ 

This makefile would produce a file "PLOT.LNK" automatically whenever the list of object files is changed 
(anytime "OBJDEF.MIF" is changed). For the above example, the file "PFOT.FNK" would contain: 

NAME plot 
DEBUG all 
FILE window.obj 
FILE bios.obj 
FILE keyboard.obj 
FILE mouse.obj 

The "rm" command is intercepted by Make. The reason for this is the need of being available on all 
supported platforms. The "rm" internal command is simplified implementation of the POSIX rm command. 
It supports following options. 

-f force deletion of read-only files, no diagnostics messages about missing items 

-r deletion of directories 

-v verbose operation 

Make supports nine internal commands: 


1. %abort 

2. %append 

3. %create 

4. %erase 

5. %make 

6. %null 

7. %quit 

8. %stop 

9. %write 


The %abort and %quit internal commands terminate execution of Make and return to the operating 
system shell: %abort sets a non-zero exit code; %quit sets a zero exit code. 

# 

# %abort and %quit example 

# 

done_ enough : 

%quit 

suicide : 

%abort 
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The %append, %create, %erase, and %write internal commands allow WMAKE to generate files 
under makefile control. This is useful for files that have contents that depend on makefile contents. 
Through the use of macros and the "for" command. Make becomes a very powerful tool in maintaining lists 
of files for other programs. 

The %append internal command appends a text line to the end of a file (which is created if absent) while 
the %write internal command creates or truncates a file and writes one line of text into it. Both 
commands have the same form, namely: 

%append <file> <text> 

%write <file> <text> 

where <f ile> is a file specification and <text> is arbitrary text. 

The %create internal command will create or truncate a file so that the file does not contain any text 
while the %erase internal command will delete a file. Both commands have the same form, namely: 

%create <file> 

%erase <file> 


where <file>isa file specification. 


Full macro processing is performed on these internal commands so the full power of WMAKE can be used. 
The following example illustrates a common use of these internal commands. 

# 

# %append, %create, %erase, and %write example 

# 

[include objdef.mif 

plot.exe : $ (objs) plot.Ink 
wlink @plot 


plot.Ink : objdef.mif 
%create $ A @ 

%append $ A @ NAME $ A & 

# Next line equivalent to previous 
%create $ A @ NAME $ A & 

%append $ A @ DEBUG all 

for %i in ($ (objs)) do %append $ A @ 


two lines. 


FILE %i 


clean : .SYMBOLIC 

%erase plot.Ink 


The above code demonstrates a valuable technique that can generate directive files for WLINK, WLIB, and 
other utilities. 


The %make internal command permits the updating of a specific target and has the form: 
%make <target> 

where <target> is a target in the makefile. 
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# 

# %make example 

# 

[include objdef.mif 

plot.exe : $ (objs) 

%make plot.Ink 
wlink @plot 

plot.Ink : objdef.mif 
%create $~@ 

%append $~@ NAME $''& 

%append $^@ DEBUG all 

for %i in ($(objs)) do %append $^@ FILE %i 

There seem to be other ways of doing the same thing. Among them is putting plot.lnk into the list of 
dependencies: 

# 

# %make counter-example 

# 

[include objdef.mif 

plot.exe : $ (objs) plot.lnk 
wlink @plot 

plot.lnk : objdef.mif 
%create $ A @ 

%append $ A @ NAME $ A & 

%append $^@ DEBUG all 

for %i in ($(objs)) do %append $ A @ FILE %i 
and using a make variable: 

# 

# %make counter-example 

# 

[include objdef.mif 
plot.exe : $(objs) 

wlink NAME $^& DEBUG all FILE { $(objs) } 

The %null internal command does absolutely nothing. It is useful because Make demands that a 
command list be present whenever a target is updated. 
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# 

# %null example 

# 

all : application! application2 .SYMBOLIC 
%null 

applicationl : appll.exe .SYMBOLIC 
%null 

application2 : appl2.exe .SYMBOLIC 
%null 

appll.exe : (dependents ...) 

(commands) 

appl2.exe : (dependents ...) 

(commands) 

Through the use of the %null internal command, multiple application makefiles may be produced that are 
quite readable and maintainable. 

The %stop internal command will temporarily suspend makefile processing and print out a message 
asking whether Makefile processing should continue. Make will wait for either the "y" key (indicating that 
the Makefile processing should continue) or the "n" key. If the "n" key is pressed, makefile processing will 
stop. The %stop internal command is very useful for debugging makefiles but it may be used also to 
develop interactive makefiles. 

# 

# %stop example 

# 

all : appll.exe .SYMBOLIC 
%null 

appll.exe : (dependents ...) 

@echo Are you feeling lucky? Punk! 

@%stop 
(commands) 

9.40 Compatibility Between Open Watcom Make and UNIX 
Make 

Open Watcom Make was originally based on the UNIX Make utility. The PC’s operating environment 
presents a base of users which may or may not be familiar with the UNIX operating system. Make is 
designed to be a PC product with some UNIX compatibility. The line continuation in UNIX Make is a 
backslash ("\") at the end of the line. The backslash ("\") is used by the operating system for directory 
specifications and as such will be confused with line continuation. For example, you could type: 

cd \ 

along with other commands ... and get unexpected results. However, if your makefile does not contain 
path separator characters ("\") and you wish to use "\" as a line continuation indicator then you can use the 
Make "u" (UNIX compatibility mode) option. 
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Also, in the UNIX operating system there is no concept of file extensions, only the concept of a file suffix. 
Make will accept the UNIX Make directive . SUFFIXES for compatibility with UNIX makefiles. The 
UNIX compatible special macros supported are: 

Macro Expansion 

$@ full name of the target 

$* target with the extension removed 

$< list of all dependents 

$? list of dependents that are younger than the target 

The extra checking of makefiles done by Make will require modifications to UNIX makefiles. The UNIX 
Make utility does not check for the existence of targets after the associated command list is executed so the 
"c" or the . NOCHECK directive should be used to disable this checking. The lack of a command list to 
update a target is ignored by the UNIX Make utility but Open Watcom Make requires the special internal 
command %null to specify a null command list. In summary. Make supports many of the features of the 
UNIX Make utility but is not 100% compatible. 

9.41 Open Watcom Make Diagnostic Messages 

This section lists the various warning and error messages that may be issued by the Open Watcom Make. 

In the messages below, %? character sequences indicate places in the message that are replaced with some 
other string. 

1 Out of memory 

2 Make execution terminated 

3 Option %c%c invalid 

4 %c%c must be followed by a filename 

5 No targets specified 

6 Ignoring first target in MAKEINIT 

7 Expecting a %M 

8 Invalid macro name %E 

9 Ignoring out of place %M 

10 Macros nested too deep 

11 Unknown internal command 

12 Program name is too long 

13 No control characters allowed in options 

14 Cannot execute %E: %Z 
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15 Syntax error in %s command 

16 Nested %s loops not allowed 

17 Token too long, maximum size is %d chars 

18 Unrecognized or out of place character ’%C’ 

19 Target %E already declared %M 

20 Command list does not belong to any target 

21 Extension(s) %E not defined 

22 No existing file matches %E 

23 Extensions reversed in implicit rule 

24 More than one command list found for %E 

25 Extension %E declared more than once 

26 Unknown preprocessor directive: %s 

27 Macro %E is undefined 

28 !If statements nested too deep 

29 !%s has no matching !if 

30 Skipping !%1 block after !%2 

31 %1 not allowed after !%2 

32 Opening file %E: %Z 

34 !%s pending at end of file 

35 Trying to !%s an undefined macro 

36 Illegal attempt to update special target %E 

37 Target %E is defined recursively 

38 %E does not exist and cannot be made from existing files 

39 Target %E not mentioned in any makefile 

40 Could not touch %E 

41 No %s commands for making %E 

42 Last command making (%L) returned a bad status 
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43 Deleting %E: %Z 

44 %s command returned a bad status 

45 Maximum string length exceeded 

46 Illegal character value %xH in file 

47 Assuming target(s) are .%s 

48 Maximum %%make depth exceeded 

49 Opening (%s) for write: %Z 

50 Unable to write: %Z 

51 CD ’ing to %E: %Z 

52 Changing to drive %C: 

53 DOS memory inconsistency detected! System may halt ... 

53 OS corruption detected 

54 While reading (%s): %Z 

59 !IF Parse Error 

60 TMP Path/File Too Long 

61 Unexpected End of File 

62 Only NO(KEEP) allowed here 

63 Non-matching " 

64 Invalid String Macro Substitution 

65 File Name Length Exceeded 

66 Redefinition of .DEFAULT Command List 

67 Non-matching {In Implicit Rule 

68 Invalid Implicit Rule Definition 

69 Path Too Long 

70 Cannot Load/Unload DLL %E 

71 Initialization of DLL %E returned a bad status 

72 DLL %E returned a bad status 
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73 Illegal Character %C in macro name 

74 in closing file %E 

75 in opening file %E 

76 in writing file %E 

77 User Break Encountered 

78 Error in Memory Tracking Encountered 

79 Makefile may be Microsoft try /ms switch 
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10.1 Introduction 


This chapter describes the Open Watcom Touch utility. Open Watcom Touch will set the time-stamp (i.e., 
the modification date and time) of one or more files. The new modification date and time may be the 
current date and time, the modification date and time of another file, or a date and time specified on the 
command line. This utility is normally used in conjunction with the Open Watcom Make utility. The 
rationale for bringing a file up-to-date without altering its contents is best understood by reading the 
chapter which describes the Make utility. 

The Open Watcom Touch command line syntax is: 


WTOUCH [options] file_spec [file_spec...] 


The square brackets [ ] denote items which are optional. 

options is a list of valid options, each preceded by a slash ("/") or a dash Options may be 

specified in any order. 

file_spec is the file specification for the file to be touched. Any number of file specifications may be 

listed. The wild card characters "*" and "?" may be used. 

The following is a description of the options available. 


c 

d <date> 

f<file> 

i 

q 

r 

t <time> 
u 
? 


do not create an empty file if the specified file does not exist 

specify the date for the file time-stamp in "mm-dd-yy" format 

use the time-stamp from the specified file 

increment time-stamp before touching the file 

suppress informational messages 

touch file even if it is marked read-only 

specify the time for the file time-stamp in "hh:mm:ss" format 

use USA date/time format regardless of country 

display help screen 


10.2 WTOUCH Operation 

WTOUCH is used to set the time-stamp (i.e., the modification date and time) of a file. The contents of the 
file are not affected by this operation. If the specified file does not exist, it will be created as an empty file. 
This behaviour may be altered with the "c" option so that if the file is not present, a new empty file will not 
be created. 
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Example: 

(will not create myfile.dat) 

Owtouch /c myfile.dat 

If a wild card file specification is used and no files match the pattern, no files will have their time-stamps 
altered. The date and time that all the specified files are set to is determined as follows: 

1. The current date and time is used as a default value. 

2. A time-stamp from an "age file" may replace the current date and time. The "f" option is used to 
specify the file that will supply the time-stamp. 

Example: 

(use the date and time from file "last.tim") 

Owtouch /f last.tim file*.dat 

3. The date and/or time may be specified from the command line to override a part of the 
time-stamp that will be used. The "d" and "t" options are used to override the date and time 
respectively. 

Example: 

(use current date but use different time) 

Owtouch /t 2:00p file*.dat 
(completely specify date and time) 

Owtouch /d 10-31-90 /t 8:00:00 file*.dat 
(use date from file "last.tim" but set time) 

Owtouch /f last.tim /t 12:00 file*.dat 

The format of the date and time on the command line depends on the country information 
provided by the host operating system. Open Watcom Touch should accept dates and times in a 
similar format to any operating system utilities (i.e., the DATE and TIME utilities provided by 
DOS). The "a" and "p" suffix is an extension to the time syntax for specifying whether the time 
is A.M. or P.M., but this is only available if the operating system is not configured for military 
or 24-hour time. 
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11 The IDE2MAKE Utility 

11.1 Introduction 


This chapter describes the IDE2MAKE utility. 1DE2MAKE loads an IDE project file and, using the 
associated .tgt files, generates make files that can be invoked with WMAKE. If the .wpj file does not exist, 
a default project is used. If any tgtfile(s) are specified, they are used as the targets in creating the make 
files. 

The IDE2MAKE command line syntax is: 


ide2make [options] [tgtfile] 


The square brackets [ ] denote items which are optional. At least one item must be specified, otherwise the 
program usage is shown. 

options is a list of valid options, each preceded by a slash ("/") or a dash Options may be 

specified in any order. 

tgtfile is the file specification for the targetfile to be used. Any number of file specifications may 

be listed. 


The following is a description of the options available. 


P <wpjfile> 
c <cfgfile> 
i 


d 

l 


r 

li <number> 


loads wpjfile.wpj (project.wpj by default) 

loads cfgfile instead of ide.cfg 

directory to search configuration files 

generate makefiles using development switch set 

generate makefiles with long lines (no length limit) 

generate makefiles using release switch set 

generate makefiles for selected host OS (default is current host) 

0 - Windows 3.x 

1 - OS/2 PM 

2 - Windows NT 

3 - Win-OS/2 

4 - Windows 95 

5 - Japanese Windows 3.x on an IBM 

6 - Japanese Windows 3.x on a Nec98 

7 - Dec Alpha (Windows NT) 

8 - DOS 

9 - Linux 
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11.2 IDE2MAKE Operation 

IDE2MAKE is used to create makefiles from IDE project and targetfiles. If no targetfile is specified, 
makefiles for all targets are generated. 
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1 About This Manual 


This manual contains the following chapters: 

Chapter 1 — "About This Manual". 

This chapter provides an overview of the contents of this guide. 

Chapter 2 — "Open Watcom FORTRAN 77 Compiler Options" on page 5. 

This chapter also provides a summary and reference section for the valid compiler options. 

Chapter 3 — "The Open Watcom FORTRAN 77 Compiler" on page 23. 

This chapter describes how to compile an application from the command line, describes 
compiler environment variables, provides examples of command line use of the compiler, 
and and describes compiler diagnostics. 

Chapter 4 — "The Open Watcom FORTRAN 77 Libraries" on page 29. 

This chapter describes the Open Watcom FORTRAN 77 run-time libraries. 

Chapter 5 — "Open Watcom FORTRAN 77 Compiler Directives" on page 33. 

This chapter describes compiler directives including INCLUDE file processing. 

Chapter 6 — "Open Watcom FORTRAN 77 File Handling" on page 39. 

This chapter describes run-time file handling. 

Chapter 7 — "The Open Watcom F77 Subprogram Library" on page 59. 

This chapter describes subprograms available for special operations. 

Chapter 8 — "16-bit Memory Models" on page 97. 

This chapter describes the Open Watcom FORTRAN 77 memory models (including code 
and data models), the tiny memory model, the mixed memory model, linking applications 
for the various memory models, creating a tiny memory model application, and memory 
layout in an executable. 

Chapter 9 — "16-bit Assembly Language Considerations" on page 101. 

This chapter describes issues relating to 16-bit interfacing such as parameter passing 
conventions. 

Chapter 10 — "16-bit Pragmas" on page 115. 

This chapter describes the use of pragmas with the 16-bit compilers. 
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Chapter 11 


Chapter 12 


Chapter 13 


Appendix A. 


Appendix B. 


"32-bit Memory Models" on page 147. 

This chapter describes the Open Watcom FORTRAN 77 memory models (including code 
and data models), the flat memory model, the mixed memory model, linking applications 
for the various memory models, and memory layout in an executable. 

"32-bit Assembly Language Considerations" on page 151. 

This chapter describes issues relating to 32-bit interfacing such as parameter passing 
conventions. 

"32-bit Pragmas" on page 165. 

This chapter describes the use of pragmas with the 32-bit compilers. 

- "Use of Environment Variables" on page 199. 

This appendix describes all the environment variables used by the compilers and related 
tools. 

- "Open Watcom F77 Diagnostic Messages" on page 209. 

This appendix lists all of the Open Watcom F77 diagnostic messages with an explanation 
for each. 
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2 Open Watcom FORTRAN 77 Compiler Options 


Source files can be compiled using either the IDE, command-line compilers or IBM WorkFrame/2. This 
chapter describes all the compiler options that are available. 

For information about compiling applications from the IDE, see the Open Watcom Graphical Tools User’s 
Guide. 

For information about compiling applications from the command line, see the chapter entitled "The Open 
Watcom FORTRAN 77 Compiler" on page 23. 

For information about creating applications using IBM WorkFrame/2, refer to IBM’s OS/2 Programming 
Guide for more information. 


2.1 Open Watcom F77 Options Summary 

In this section, we present a terse summary of the Open Watcom F77 options. The next section describes 
these options in more detail. This summary is displayed on the screen by simply entering the "WFC" or 
"WFC386" command with no arguments. 


Compiler options: Description: 


0 

1 

2 

3 

4 

5 

6 

[NOJALign 
[NO[Automatic 
BD 
BM 

[NO]BOunds 

BW 

[NO]CC 
CHInese 
[NO[COde 
D1 
D2 

[NO]DEBug 
DEFine=<macro> 
[NO[DEPendency 
[NO jDEScriptor 
Disk 


(16-bit only) assume 8088/8086 processor 
(16-bit only) assume 188/186 processor 
(16-bit only) assume 286 processor 
assume 386 processor 
assume 486 processor 
assume Pentium processor 
assume Pentium Pro processor 
align COMMON segments 
all local variables on the stack 
(32-bit only) dynamic link library 
(32-bit only) multithread application 
generate subscript bounds checking code 
(32-bit only) default windowed application 

carriage control recognition requested for output devices such as the console 

Chinese character set 

constants in code segment 

include line # debugging information 

include full debugging information 

perform run-time checking 

define macro 

generate file dependencies 

pass character arguments using string descriptor 

write listing file to disk 
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DT=<size> 

[NO[ERrorfile 
[NO[EXPlicit 
[NO]Extensions 
[NOJEZ 

FO=<obj_default> 

[NO jEORmat 

FPC 

FPD 

FPI 

FPI87 

FPR 

FP2 

FP3 

FP5 

FP6 

[NOJFSfloats 

[NO]GSfloats 

HC 

HD 

HW 

[NO /INCList 

INC Path =[d: [path 

[NOJIPromote 

Japanese 

KOrean 

[NO]LFwithff 

[NO]LIBinfo 

[NOJLISt 

[NO]MAngle 

MC 

MF 

MH 

MF 

MM 

MS 

OB 

OBP 

OC 

OD 

ODO 

OF 

OH 

OI 

OK 

OF 

OF+ 

OM 

ON 

OP 

OR 

OS 


set data threshold 

generate an error file 

declare type of all symbols 

issue extension messages 

(32-bit only) Easy OMF-386 object files 

set default object file name 

relax format type checking 

generate calls to floating-point library 

enable generation of Pentium FDIV bug check code 

generate inline 80x87 instructions with emulation 

generate inline 80x87 instructions 

floating-point backward compatibility 

generate inline 80x87 instructions 

generate inline 80387 instructions 

optimize floating-point for Pentium 

optimize floating-point for Pentium Pro 

FS not fixed 

GS not fixed 

CodeView debugging information 
DWARF debugging information 
Open Watcom debugging information 
write content of INCLUDE files to listing 
[d:]path... path for INCLUDE files 

promote INTEGER* 1 and INTEGER*2 arguments to INTEGER*4 
Japanese character set 
Korean character set 
LF with FF 

include default library information in object file 

generate a listing file 

mangle COMMON segment names 

(32-bit only) compact memory model 

(32-bit only) flat memory model 

(16-bit only) huge memory model 

large memory model 

medium memory model 

(32-bit only) small memory model 

(32-bit only) base pointer optimizations 

branch prediction 

do not convert "call" followed by "ret" to "jmp" 

disable optimizations 

DO-variables do not overflow 

always generate a stack frame 

enable repeated optimizations (longer compiles) 

generate statement functions in-line 

enable control flow prologues and epilogues 

perform loop optimizations 

perform loop optimizations with loop unrolling 

generate floating-point 80x87 math instructions in-line 

numeric optimizations 

precision optimizations 

instruction scheduling 

optimize for space 
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OT 

optimize for time 

OX 

equivalent to OBP, ODO, OI, OK, OL, OM, OR, and OT (16-bit) or OB, OBP, ODO, 


OI, OK, OL, OM, OR, and OT (32-bit) 

PRint 

write listing file to printer 

[NO]Quiet 

operate quietly 

[ NO 1 Reference 

issue unreferenced warning 

[NOJRESource 

messages in resource file 

[NOJSAve 

SAVE local variables 

[NO]SC 

(32-bit only) stack calling convention 

[NO[SEpcomma 

allow comma separator in formatted input 

[NO]SG 

(32-bit only) automatic stack growing 

[NO IS IIart 

set default INTEGER/LOGICAL size to 2/1 bytes 

[NO]SR 

save/restore segment registers 

[NO [SSfloats 

(16-bit only) SS is not default data segment 

[NO]STack 

generate stack checking code 

[NO/SYntax 

syntax check only 

[NOJTErminal 

messages to terminal 

[NOJTRace 

generate code for run-time traceback 

TYpe 

write listing file to terminal 

[NO] WArn ings 

issue warning messages 

[NO]WILd 

relax wild branch checking 

[NO [Windows 

(16-bit only) compile code for Windows 

[NO]XFloat 

extend floating-point precision 

[NO]XLine 

extend line length to 132 

A summary of the option defaults follows: 

0 

16-bit only 

5 

32-bit only 

ALign 


NO Automatic 


NOBOunds 


NOCC 


NOCOde 


NODEBug 


DEPendency 


DEScriptor 


DT=256 


ERrorfile 


NOEXPlicit 


NOEXtensions 


NOEZ 

32-bit only 

NOFORmat 


FPI 


FP2 

16-bit only 

FP3 

32-bit only 

NOFPD 


FSfloats 

all but flat memory model 

NOFSfloats 

flat memory model only 

GSfloats 


NOINCList 


NOIPromote 
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NOLFwithff 

LIBinfo 

NOLISt 

NOMAngle 


ML 

16-bit only 

MF 

NOQuiet 

Reference 

NORESource 

NOSAve 

32-bit only 

NOSC 

NOSEpcomma 

32-bit only 

NOSG 

NOSHort 

NOSR 

32-bit only 

NOSSfloats 

NOSTack 

NOSYntax 

TErminal 

NOTRace 

WArnings 

NOWILd 

16-bit only 

NOWIndows 

NOXFloat 

NOXLine 

16-bit only 


2.2 Compiler Options 

Compiler options may be entered in one of two places. They may be included in the options list of the 
command line or they may be included as comments of the form "C$option", "c$option", or "*$option" in 
the source input stream. The compiler recognizes these special comments as compiler directives. 

Some options may only be specified in the options list of the command line. Unless otherwise stated, an 
option can appear on the command line only. We also indicate what the default is for an option or group of 
options. 

When specifying options in the source file, it is possible to specify more than one option on a line. For 
example, the following source line tells Open Watcom F77 to not issue any warning or extension messages. 

Example: 

*$nowarn noext 

Note that only the first option must contain the "C$", or "c$" prefix. 

Short forms are indicated by upper case letters. 

Option: Description: 

0 (16-bit only) Open Watcom F77 will make use of only 8088/8086 instructions in the 

generated object code. The resulting code will run on 8086 and all upward compatible 
processors. This is the default option for the 16-bit compiler. 
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1 (16-bit only) Open Watcom F77 will make use of 188/186 instructions in the generated 
object code whenever possible. The resulting code probably will not run on 8086 
compatible processors but it will run on 186 and all upward compatible processors. 

2 (16-bit only) Open Watcom F77 will make use of 286 instructions in the generated object 
code whenever possible. The resulting code probably will not run on 8086 or 186 
compatible processors but it will run on 286 and all upward compatible processors. 

3 Open Watcom F77 will assume a 386 processor and will generate instructions based on 386 
instruction timings. 

4 Open Watcom F77 will assume a 486 processor and will generate 386 instructions based on 
486 instruction timings. The code is optimized for 486 processors rather than 386 
processors. 

5 Open Watcom F77 will assume a Pentium processor and will generate 386 instructions 
based on Pentium instruction timings. The code is optimized for Pentium processors rather 
than 386 processors. This is the default option for the 32-bit compiler. 

6 Open Watcom F77 will assume a Pentium Pro processor and will generate 386 instructions 
based on Pentium Pro instruction timings. The code is optimized for Pentium Pro 
processors rather than 386 processors. 

[NOJALign The "align" option tells the compiler to allocate all COMMON blocks on paragraph 

boundaries (multiples of 16). If you do not want COMMON blocks to be aligned, specify 
"noalign". The default is "align". 


[NOJAUtomcitic 

The "automatic" option tells the compiler to allocate all local variables, including arrays, on 
the stack. This is particularly useful for recursive functions or subroutines that require a 
new set of local variables to be allocated for each recursive invocation. Note that the 
"automatic" option may significantly increase the stack requirements of your application. 
You can increase your stack size by using the "STACK" option when you link your 
application. 

BD (32-bit only, OS/2 and Windows NT only) This option causes the compiler to imbed the 

appropriate DLL library name in the object file and to include the appropriate DLL 
initialization code sequence when the application is linked. 

BM (32-bit only, OS/2 and Windows NT only) This option causes the compiler to imbed the 

appropriate multi-thread library name in the object file. 

[NO]BOunds The "bounds" option causes the generation of code that performs array subscript and 

character substring bounds checking. Note that this option may significantly reduce the 
performance of your application but is an excellent way to eliminate many programming 
errors. The default option is "nobounds". 

BW (OS/2, Windows 3.x, and Windows NT only) This option causes the compiler to import a 

special symbol so that the default windowing library code is linked into your application. 

[NO]CC The "cc" option specifies that the output to devices contains carriage control information 

that is to be interpreted appropriately for the output device (e.g., console device). ASA 
carriage control characters are converted to ASCII vertical spacing control characters. 
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Note that a blank carriage control character will automatically be generated for list-directed 
output and will be interpreted as a single-line spacing command. 

CHInese This option is part of the national language support provided by Open Watcom F77. It 

instructs the compiler that the source code contains characters from the Traditional Chinese 
character set. This includes double-byte characters. This option enables the use of Chinese 
variable names. The compiler’s run-time system will ensure that character strings are not 
split in the middle of a double-byte character when output spans record boundaries (as can 
happen in list-directed output). 

[NO]COde The "code" option causes the code generator to place character and numeric constants in 
code segment. Data generated for FORMAT statements will also be placed in the code 
segment. The default option is "nocode". 

D1 Line number information is included in the object file ("type 1 debugging information"). 

This option provides additional information to Open Watcom Debugger (at the expense of 
larger object files and executable files). Line numbers are handy when debugging your 
application with Open Watcom Debugger. 

D2 In addition to line number information, local symbol and data type information is included 

in the object file ("type 2 debugging information"). Although global symbol information 
can be made available to Open Watcom Debugger through a Open Watcom Linker option, 
local symbol and typing information must be requested when the source file is compiled. 

This option provides additional information to Open Watcom Debugger (at the expense of 
larger object files and executable files). However, it will make the debugging chore 
somewhat easier. 

[NOJDEBug The "debug" option causes the generation of run-time checking code. This includes 

subscript and substring bounds checking as well as code that allows a run-time traceback to 
be issued when an error occurs. The default option is "nodebug". 

DEFine=<macro> 

This option is equivalent to specifying the following "define" compiler directive. 

*$define <macro> 

The macro specified by the "define" option or compiler directive becomes defined. The 
definition status of the specified macro can be checked using the "ifdef", "ifndef", 

"elseifdef" or "elseifndef" compiler directives. This allows source code to be conditionally 
compiled depending on the definition status of the macro. 

The macro_i 8 6_is a special macro that is defined by the compiler and identifies the 

target as a 16-bit Intel 80x86 compatible environment. 

The macro_ 38 6_is a special macro that is defined by the compiler and identifies the 

target as a 32-bit Intel 386 compatible environment. 

The macro_stack_ conventions_is a special macro that is defined by the 32-bit 

compiler when the "sc" compiler option is specified to indicate that stack calling 
conventions are to be used for code generation. 

The macro_fpi_is a special macro that is defined by the compiler when one of the 

following floating-point options is specified: "fpi" or "fpi87". 
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[NO[DEPendency 

The "dependency" option specifies that file dependencies are to be included in the object 
file. This is the default option. This option is used by the Open Watcom Integrated 
Development Environment to determine if an object file is up-to-date with respect to the 
source files used to build it. You can specify the "nodependency" option if you do not want 
file dependencies to be included in the object file. 

[NOJDEScriptor 

The "descriptor" option specifies that string descriptors are to be passed for character 
arguments. This is the default option. You can specify the "nodescriptor" option if you do 
not want string descriptors to be passed for character arguments. Instead, the pointer to the 
actual character data and the length will be passed as two arguments. The arguments for 
the length will be passed as additional arguments following the normal argument list. For 
character functions, the pointer to the data and the length of the character function will be 
passed as the first two arguments. 

Disk When this option is used in conjunction with the "list" option, the listing file is written to 

the current directory of the default disk. The listing file name will be the same as the 
source file name but the file extension will be ,1st. By default, listing files are written to 
disk. The "disk" option will override any previously specified "type" or "print" option. 

DT=<size> The "data threshold" option is used to set the minimum size for data objects to be included 
in the default data segment. Normally, all data objects smaller than 256 bytes in size are 
placed in the default data segment. When there is a large amount of static data, it is often 
useful to set the data threshold size so that all objects of the specified size or larger are 
placed into another segment. For example, the option: 

/DT=100 

causes all data objects of 100 bytes or more to be placed in a far data segment. The "data 
threshold" only applies to the large and huge memory models where there can be more than 
one data segment. The default data threshold value is 256. 

[NO]ERrorfile This option is used to control whether error messages are output to a separate error file. 

The error file is a disk file of type .err and is produced if any diagnostic messages are 
issued by the compiler. Specifying "noerrorfile" prevents the creation of an error file. By 
default, an error file is created. 

If an error file exists before compilation begins, it will be erased. If no diagnostic messages 
are produced then an error file will not be created even though the "errorfile" option is 
selected. This option has no effect on the inclusion of diagnostic messages in the source 
listing file or the production of diagnostic messages on the screen. 

[NO]EXPlicit The "explicit" option requires the type of all symbols to be explicitly declared. An error 
message will be issued by the compiler if a symbol that does not appear in a type 
declaration statement is encountered. Specifying this option is equivalent to using the 
IMPLICIT NONE statement. By default, symbols do not have to be explicitly typed. 

[NO'].Extensions 

This option is used to control the printing of extension messages. This option may be 
specified on the command line or it may be placed anywhere in the source input stream. In 
a source file, the option appears as a comment line and takes the following form. 

*$[NO]Extensions 
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The "extensions" option enables the printing of extension messages, while "noextensions" 
disables the printing of these messages. By default, extension messages are not printed. 

[NOJEZ (32-bit only) Open Watcom F77 will generate an object file in Phar Lap Easy OMF-386 

(object module format) instead of the default Microsoft OMF. The default option is 
"noez". 

FO=<obj_default> 

By default, the object file name is constructed from the source file name. Using the "fo" 
option, the default object file drive, path, file name and extension can be specified. 

Example: 

C>wfc386 report /fo=d:\programs\obj\ 

A trailing "\" must be specified for directory names. If, for example, the option was 
specified as "/fo=d:\programs\obj" then the object file would be called 
D:\PROGRAMS\OBJ.OBJ. 

A default extension must be preceded by a period ("."). 

Example: 

C>wfc386 report /fo=d:\programs\obj\.dbo 

[NOJFORmat The "format" option suppresses the run-time checking that ensures that the type of an 
input/output list item matches the format edit descriptor in a format specification. This 
allows an input/output list item of type INTEGER to be formatted using an F, E or D edit 
descriptor. It also allows an input/output list item of a floating-point type to be formatted 
using an I edit descriptor. Normally, this generates an error. The "format" option is 
particularly useful for applications that use integer arrays to store integer and floating-point 
data. The default option is "noformat". 

FPC All floating-point arithmetic is done with calls to a floating-point emulation library. This 

option should be used when speed of floating-point emulation is favoured over code size. 

FPI (16-bit only) Open Watcom F77 will generate in-line 80x87 numeric data processor 

instructions into the object code for floating-point operations. Depending on which library 
the code is linked against, these instructions will be left as is or they will be replaced by 
special interrupt instructions. In the latter case, floating-point will be emulated if an 80x87 
is not present. This is the default floating-point option if none is specified. 

(32-bit only) Open Watcom F77 will generate in-line 80x87 numeric data processor 
instructions into the object code for floating-point operations. When any module 
containing floating-point operations is compiled with the "fpi" option, coprocessor 
emulation software will be included in the application when it is linked. Thus, an 80x87 
coprocessor need not be present at run-time. This is the default floating-point option if 
none is specified. 

FPI87 (16-bit only) Open Watcom F77 will generate in-line 80x87 numeric data processor 

instructions into the object code for floating-point operations. An 80x87 coprocessor must 
be present at run-time. If the "2" option is used in conjunction with this option. Open 
Watcom F77 will generate 287/387 compatible instructions; otherwise Open Watcom F77 
will generate 8087 compatible instructions. 
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FP2 


FP3 


FP5 


FP6 


(32-bit only) Open Watcom F77 will generate in-line 80x87 numeric data processor 
instructions into the object code for floating-point operations. When the "fpi87" option is 
used exclusively, coprocessor emulation software is not included in the application when it 
is linked. A 80x87 coprocessor must be present at run-time. 

16-bit Notes: 

1. When any module in an application is compiled with a particular "floating-point" 
option, then all modules must be compiled with the same option. 

2. Different math libraries are provided for applications which have been compiled 
with a particular floating-point option. See the chapter entitled "The Open 
Watcom FORTRAN 77 Libraries" on page 29. 

32-bit Notes: 

1. When any module in an application is compiled with the "fpc" option, then all 
modules must be compiled with the "fpc" option. 

2. When any module in an application is compiled with the "fpi" or "fpi87" option, 
then all modules must be compiled with one of these two options. 

3. If you wish to have floating-point emulation software included in the 
application, you should select the "fpi" option. A 387 coprocessor need not be 
present at run-time. 

4. Different math libraries are provided for applications which have been compiled 
with a particular floating-point option. See the chapter entitled "The Open 
Watcom FORTRAN 77 Libraries" on page 29. 

Open Watcom F77 will generate in-line 80x87 numeric data processor instructions into the 
object code for floating-point operations. For Open Watcom compilers generating 16-bit, 
this is the default. For 32-bit applications, use this option if you wish to support those few 
386 systems that are equipped with an 80287 numeric data processor ("fp3" is the default 
for Open Watcom compilers generating 32-bit code). However, for 32-bit applications, the 
use of this option will reduce execution performance. 

Open Watcom F77 will generate in-line 387-compatible numeric data processor 
instructions into the object code for floating-point operations. For 16-bit applications, the 
use of this option will limit the range of systems on which the application will run but there 
are execution performance improvements. 

Open Watcom F77 will generate in-line 387-compatible numeric data processor 
instructions into the object code for floating-point operations. The sequence of 
floating-point instructions will be optimized for greatest possible performance on the Intel 
Pentium processor. For 16-bit applications, the use of this option will limit the range of 
systems on which the application will run but there are execution performance 
improvements. 

Open Watcom F77 will generate in-line 387-compatible numeric data processor 
instructions into the object code for floating-point operations. The sequence of 
floating-point instructions will be optimized for greatest possible performance on the Intel 
Pentium Pro processor. For 16-bit applications, the use of this option will limit the range of 
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[NOJFPD 


FPR 


[NOJFSfloats 


[NOJGSfloats 


HC 


HD 


systems on which the application will run but there are execution performance 
improvements. 

A subtle problem was detected in the FDIV instruction of Intel’s original Pentium CPU. In 
certain rare cases, the result of a floating-point divide could have less precision than it 
should. Contact Intel directly for more information on the issue. 

As a result, the run-time system startup code has been modified to test for a faulty Pentium. 
If the FDIV instruction is found to be flawed, the low order bit of the run-time system 
variable_chipbug will be set. 

If the FDIV instruction does not show the problem, the low order bit will be clear. If the 
Pentium FDIV flaw is a concern for your application, there are two approaches that you 
could take: 

1. You may test the_chipbug variable in your code in all floating-point and 

memory models and take appropriate action (such as display a warning message 
or discontinue the application). 

2. Alternately, you can use the "fpd" option when compiling your code. This 
option directs the compiler to generate additional code whenever an FDIV 

instruction is generated which tests the low order bit of_chipbug and, if on, 

calls the software workaround code in the math libraries. If the bit is off, an 
in-line FDIV instruction will be performed as before. 

If you know that your application will never run on a defective Pentium CPU, or your 
analysis shows that the FDIV problem will not affect your results, you need not use the 
"fpd" option. 

Use this option if you want to generate floating-point instructions that will be compatible 
with version 9.0 or earlier of the compilers. For more information on floating-point 
conventions see the sections entitled "Using the 80x87 to Pass Arguments" on page 140 and 
"Using the 80x87 to Pass Arguments" on page 192. 

The "fsfloats" option enables the use of the FS segment register in the generated code. This 
is the default for all but the flat memory model. In the flat memory model, the default is 
"nofsfloats" (the FS segment register is not used in the generated code). 

The "gsfloats" option enables the use of the GS segment register in the generated code. 

This is the default. If you would like to prevent the use of the GS segment register in the 
the generated code, specify the "nogsfloats" option. 

The type of debugging information that is to be included in the object file is "CodeView". 

The default type of debugging information is "Dwarf" (HD). If you wish to use the 
Microsoft CodeView debugger, then choose the "HC" option. When linking the 
application, you must also choose the appropriate Open Watcom Linker DEBUG directive. 
See the Open Watcom Linker User’s Guide for more information. 

The type of debugging information that is to be included in the object file is "Dwarf". This 
is the default type of debugging information. If you wish to use the Microsoft CodeView 
debugger, then choose the "HC" option. When linking the application, you must also 
choose the appropriate Open Watcom Linker DEBUG directive. See the Open Watcom 
Linker User’s Guide for more information. 
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HW The type of debugging information that is to be included in the object file is "Open 

Watcom". The default type of debugging information is "Dwarf" (HD). If you wish to use 
the Microsoft CodeView debugger, then choose the "HC" option. When linking the 
application, you must also choose the appropriate Open Watcom Linker DEBUG directive. 
See the Open Watcom Linker User’s Guide for more information. 

[NO]INCList This option is used to control the listing of the contents of INCLUDE files to the listing 
file. The "inclist" option enables the listing of INCLUDE files, while "noinclist" disables 
the listing of these files. The default option is "noinclist". 

INC Path =[d: ]path 

[d:]path... This option is used to specify directories that are to be searched for include files. 
Each path is separated from the previous by a semicolon These directories are 
searched in the order listed before those in the FINCLUDE environment variable. 

[NO]IPromote The "ipromote" option causes the compiler to promote the INTEGER* 1 and INTEGER*2 
arguments of some INTEGER*4 intrinsics without issuing an error diagnostic. This allows 
code such as the following to be compiled without error: 

Example: 

INTEGER 1*1, J*2 
1 = 1 
J = 2 

PRINT *, IDIM( I, J ) 

END 

This works for the following intrinsic functions: ABS(), IABS(), DIM(), IDIM(), SIGN(), 
ISIGN(), MAX(), AMAX0(), MAXOQ, MIN(), AMIN0(), and MIN0(). When the 
"ipromote" option is specified, all integer arguments that are passed to these functions are 
promoted to INTEGER*4. 

Japanese This option is part of the national language support provided by Open Watcom F77. It 

instructs the compiler that the source code contains characters from the Japanese character 
set. This includes double-byte characters. This option enables the use of Japanese variable 
names. The compiler’s run-time system will ensure that character strings are not split in the 
middle of a double-byte character when output spans record boundaries (as can happen in 
list-directed output). 

KORean This option is part of the national language support provided by Open Watcom F77. It 

instructs the compiler that the source code contains characters from the Korean character 
set. This includes double-byte characters. This option enables the use of Korean variable 
names. The compiler’s run-time system will ensure that character strings are not split in the 
middle of a double-byte character when output spans record boundaries (as can happen in 
list-directed output). 

[NOJLFwithff This option is used to control whether a line-feed character (LF=CHAR( 10)) is to be 

emitted before a form-feed character (FF=CHAR(12)) is emitted. This option applies to 
carriage control handling. Normally, the run-time system will emit only a form-feed 
character to cause a page eject when the ASA control character " 1" is found in the first 
column of a record. The "lfwithff" option will cause the run-time system to emit a 
line-feed character and then a form-feed character. 
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[NO I LIB info 


[NOJLISt 


[NO]MAngle 


MC 


MF 


MH 


ML 


The "lfwithff" option will have little effect on printers, but it will change the appearance of 
output to the screen by eliminating overwritten text when form-feed characters are not 
handled by the output device. The default option is "nolfwithff". 

This option is used to control the inclusion of default library information in the object file. 
The "libinfo" option enables the inclusion of default library information, while "nolibinfo" 
disables the inclusion of this information. The default option is "libinfo". 

This option may be specified on the command line or it may be placed anywhere in the 
source input stream. On the command line, this option is used to control the creation of a 
listing file. The "list" option causes a listing file to be created while "nolist" requests that 
no listing file be created. The default option is "nolist". 

In a source file, the option appears as a comment line and takes the following form. 

*$[NO]LISt 

Specifying *$LIST causes the source lines that follow this option to be listed in the source 
listing file while *$NOLIST disables the listing of the source lines that follow. This option 
cannot appear on the same source line with other options. 

This option is used to alter COMMON block segment and class names. 

Example: 

REAL R, S 

COMMON /BLK/ R, S 

END 

For a named COMMON block called "BLK", the default convention is to name the 
segment "BLK" and the class "BLK". 

BLK SEGMENT PARA COMMON USE32 'BLK' 

When you use the "mangle" option, the segment is named "_COMMON_BLK" and the 
class is named "_COMMON_BLK_DATA". 

_ COMMON_ BLK SEGMENT PARA COMMON USE32 ' _ COMMON_ BLK_ DATA' 

(32-bit only) The "compact" memory model (small code, big data) is selected. The various 
models supported by Open Watcom F77 are described in the chapters entitled "16-bit 
Memory Models" on page 97 and "32-bit Memory Models" on page 147. 

(32-bit only) The "flat" memory model (code and data up to 4 gigabytes) is selected. The 
various models supported by Open Watcom F77 are described in the chapters entitled 
"16-bit Memory Models" on page 97 and "32-bit Memory Models" on page 147. This is 
the default memory model option. 

(16-bit only) The "huge" memory model (big code, huge data) is selected. The various 
models supported by Open Watcom F77 are described in the chapters entitled "16-bit 
Memory Models" on page 97 and "32-bit Memory Models" on page 147. 

The "large" memory model (big code, big data) is selected. The various models supported 
by Open Watcom F77 are described in the chapters entitled "16-bit Memory Models" on 
page 97 and "32-bit Memory Models" on page 147. This is the default 16-bit memory 
model option. 
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MM The "medium" memory model (big code, small data) is selected. The various models 

supported by Open Watcom F77 are described in the chapters entitled "16-bit Memory 
Models" on page 97 and "32-bit Memory Models" on page 147. 

MS (32-bit only) The "small" memory model (small code, small data) is selected. The various 

models supported by Open Watcom F77 are described in the chapters entitled "16-bit 
Memory Models" on page 97 and "32-bit Memory Models" on page 147. 

OB (32-bit only) This option allows the use of the ESP register as a base register to reference 

local variables and subprogram arguments in the generated code. This can reduce the size 
of the prologue/epilogue sequences generated by the compiler thus improving overall 
performance. Note that when this option is specified, the compiler will abort when there is 
not enough memory to optimize the subprogram. By default, the code generator uses more 
memory-efficient algorithms when a low-on-memory condition is detected. 

OBP This option causes the code generator to try to order the blocks of code emitted such that 

the "expected" execution path (as determined by a set of simple heuristics) will be straight 
through, with other cases being handled by jumps to separate blocks of code "out of line". 
This will result in better cache utilization on the Pentium. If the heuristics do not apply to 
your code, it could result in a performance decrease. 

OC This option may be used to disable the optimization where a "CALL" followed by a "RET" 

(return) is changed into a "JMP" (jump) instruction. This option is required if you wish to 
link an overlayed program using the Microsoft DOS Overlay Linker. The Microsoft DOS 
Overlay Linker will create overlay calls for a "CALL" instruction only. This option is not 
required when using the Open Watcom Linker. This option is not assumed by default. 

OD Non-optimized code sequences are generated. The resulting code will be much easier to 

debug when using Open Watcom Debugger. By default. Open Watcom L77 will select 
"od" if "d2" is specified. 

ODO Optimized DO-loop iteration code is generated. Caution should be exercised with the use 

of this option since the case of an iterating value overflowing is assumed to never occur. 
The following example should not be compiled with this option since the terminal value of 
IX wraps from a positive integer to a negative integer. 

Example: 

INTEGER*2 IX 
DO IX=32766,32767 


ENDDO 

The values of IX are 32766, 32767, -32768, -32767, ... since IX is INTEGER*2 (a 16-bit 
signed value) and it never exceeds the terminal value. 

OF This option selects the generation of traceable stack frames for those functions that contain 

calls or require stack frame setup. To use Open Watcom’s "Dynamic Overlay Manager" 
(DOS only), you must compile all modules using the "of' option. Lor near functions, the 
following function prologue sequence is generated. 

16-bit: 
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push BP 
mov BP,SP 

32-bit: 

push EBP 
mov EBP,ESP 

For far functions, the following function prologue sequence is generated. 

16-bit: 

inc BP 
push BP 
mov BP,SP 

32-bit: 

inc EBP 
push EBP 
mov EBP,ESP 

The BP/EBP value on the stack will be even or odd depending on the code model. For 
16-bit DOS systems, the Dynamic Overlay Manager uses this information to determine if 
the return address on the stack is a short address (16-bit offset) or long address (32-bit 
segment:offset). This option is not assumed by default. 

OH This option enables repeated optimizations (which can result in longer compiles). 

OI This option causes code for statement functions to be generated in-line. 

OK This option enables flowing of register save (from prologue) down into the subprogram’s 

flow graph. 

OL Loop optimizations are performed. This includes moving loop-invariant expressions 

outside the loops. This option is not assumed by default. 

OL+ Loop optimizations are performed including loop unrolling. This includes moving 

loop-invariant expressions outside the loops and can cause loops to be turned into 
straight-line code. This option is not assumed by default. 

OM Generate inline 80x87 code for math functions like sin, cos, tan, etc. If this option is 

selected, it is the programmer’s responsibility to make sure that arguments to these 
functions are within the range accepted by the fsin, fcos, etc. instructions since no 
run-time check is made. 

If the "ot" option is also specified, the exp function is generated inline as well. This option 
is not assumed by default. 

ON This option allows the compiler to perform certain numerical calculations in a more 

efficient manner. Consider the following example. 

Z1 = XI / Y 
Z2 = X2 / Y 
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OR 

os 

or 

ox 

PRint 


If the "on" option is specified, the code generator will generate code that is equivalent to 
the following. 

T = 1 / Y 
Z1 = XI * T 
Z2 = X2 * T 

Since floating-point multiplication is more efficient that division, the code generator 
decided to first compute the reciprocal of Y and then multiply XI and X2 by the reciprocal 
of Y. 

Note that this optimization may produce less slightly different results since some, for 
certain values, precision is lost when computing the reciprocal. By using this option, you 
are indicating that you are willing to accept the loss in precision for the gain in 
performance. 

By default, floating-point variables may be cached in 80x87 floating-point registers across 
statements when compiling with the "fpi" or "fpi87" options. Floating-point register 
temporaries use 64 bits of precision in the mantissa whereas single and double-precision 
variables use fewer bits of precision in the mantissa. The use of this option will force the 
result to be stored in memory after each FORTRAN statement is executed. This will 
produce less accurate but more predictable floating-point results. The code produced will 
also be less efficient when the "op" option is used. 

Example: 

XMAX = X + Y / Z 
YMAX = XMAX + Q 

When the "op" option is used in conjunction with the "fpi" or "fpi87" option, the compiler’s 
code generator will update XMAX before proceeding with the second statement. In the 
second statement, the compiler will reload XMAX from memory rather than using the result 
of the previous statement. The effect of the "op" option on the resulting code can be seen 
by the increased code size statistic as well as through the use of the Open Watcom 
Disassembler. This option is not assumed by default. 

This option enables reordering of instructions (instruction scheduling) to achieve better 
performance on pipelined architectures such as the 486. Selecting this option will make it 
slightly more difficult to debug because the assembly language instructions generated for a 
source statement may be intermixed with instructions generated for surrounding statements. 
This option is not assumed by default. 

Space is favoured over time when generating code (smaller code but possibly slower 
execution). By default. Open Watcom F77 selects a balance between "space" and "time". 

Time is favoured over space when generating code (faster execution but possibly larger 
code). By default. Open Watcom F77 selects a balance between "space" and "time". 

Specifying the "ox" option is equivalent to specifying the "ob" (32-bit only), "obp", "odo", 
"oi", "ok", "ol", "om", "or", and "ot" options. 

This option is used to direct the listing file to the printer (device name "PRN") instead of 
the disk. The "print" option will override any previously specified "type" or "disk" option. 
The default is to create a listing file on the disk. 
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[NOjQuiet The "quiet" option suppresses the banner and summary information produced by the 

compiler. Only diagnostic messages will be displayed. The default option is "noquiet". 


[NO]Reference 

When the "reference" option is specified, warning messages will be issued for all 
unreferenced symbols. In a source file, the option appears as a comment line and takes the 
following form. 

*$[NO]Reference 

This option is most useful when used in an include file that is included by several 
subprograms. Consider an include file that defines many parameter constants and only a 
few are referenced by any one subprogram. If the first line of the include file is 

*$noreference 

and the last line is 

*$reference 

warning messages for all unused parameter constants in the include file would be 
suppressed. The default option is "reference". 


[NOJRESource 

The "resource" option specifies that the run-time error messages are contained as resource 
information in the executable file. All messages will be extracted from the resource area of 
the executable file when they are required; no messages will be linked with the application. 
The default option is "noresource". 

[NOJSAve The "save" option is used to instruct Open Watcom F77 to "save" all local variables of 
subprograms. All local variables are treated as if they had appeared in FORTRAN 77 
SAVE statements. By default, local variables are not saved unless named in a SAVE 
statement (i.e., "nosave" is the default option). 

[NO]SC (32-bit only) If the "sc" option is used. Open Watcom F77 will pass all arguments on the 

stack. The resulting code will be larger than that which is generated for the register method 
of passing arguments. The default option is "nose". 

[NO[SEpcomma 

The "sepcomma" option allows the comma (",") to be used as field separator in formatted 
input. Thus the following code would work with the input described. 

Example: 

REAL R, S 

READ(5,21) R, S 
PRINT *, R, S 
21 FORMAT(2F11.3) 

END 

Normally the following input would result in a run-time error message. 

0.79,0.21 


20 


Compiler Options 




Open Watcom FORTRAN 77 Compiler Options 


[NO]SG (32-bit only) The "sg" option is useful for 32-bit OS/2 multi-threaded applications. It 

requests the code generator to emit a run-time call at the start of any function that has more 
than 4K bytes of automatic variables (variables located on the stack). Under 32-bit OS/2, 
the stack is grown automatically in 4K pages using the stack "guard page" mechanism. The 
stack consists of in-use committed pages topped off with a special guard page. A memory 
reference into the 4K guard page causes OS/2 to grow the stack by one 4K page and to add 
a new 4K guard page. This works fine when there is less than 4K of automatic variables in 
a function. When there is more than 4K of automatic data, the stack must be grown in an 
orderly fashion, 4K bytes at a time, until the stack has grown sufficiently to accommodate 
all the automatic variable storage requirements. 

The "stack growth" run-time routine is called_ GRO. 

The default option is "nosg". 

[NOISflort The "short" option is used to instruct Open Watcom F77 to set the default INTEGER size to 

2 bytes and the default LOGICAL size to 1 bytes. As required by the FORTRAN 77 
language standard, the default INTEGER size is 4 bytes and the default LOGICAL size is 4 
bytes. The default option is "noshort". 

[NOJSR The "sr" option instructs Open Watcom F77 to generate subprogram prologue and epilogue 

sequences that save and restore any segment registers that are modified by the subprogram. 
Caution should be exercised when using this option. If the value of the segment register 
being restored matches the value of a segment that was freed within the subprogram, a 
general protection fault will occur in protected-mode environments. The default, "nosr", 
does not save and restore segment registers. 

[NOJSSfloats (16-bit only) The "ssfloats" option specifies that the segment register SS does not 

necessarily point to the default data segment. The "ssfloats" option must be specified when 
compiling a module that is part of an OS/2 multi-threaded application or dynamic link 
library. By default, it is assumed that the SS segment register contains the segment address 
of the default data segment (i.e., "nossfloats"). 

[NOJSTack If "stack" is specified. Open Watcom F77 will emit code at the beginning of every 

subprogram that will check for the "stack overflow" condition. By default, stack overflow 
checking is omitted from the generated code ("nostack"). 

[NOJSYntax If "syntax" is specified. Open Watcom F77 will check the source code only and omit the 
generation of object code. Syntax checking, type checking, and so on are performed as 
usual. By default, code is generated if there are no source code errors (i.e., "nosyntax" is 
the default). 

[NOJTErminal The "noterminal" option may be used to suppress the display of diagnostic messages to the 
screen. By default, diagnostic messages are displayed. 

[NOJTRace The "trace" option causes the generation of code that allows a traceback to be issued when 
an error occurs during the execution of your program. The default option is "notrace". 

TYpe This option is used to direct the listing file to the terminal (device name "CON") instead of 

the disk. The "type" option will override any previously specified "print" or "disk" option. 
The default is to create a listing file on the disk. 

[NO] WArn ings 

This option is used to control the printing of warning messages. By default, warning 
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[NOJWILd 


[NOJWIndows 


[NO jXFloat 


[NOJXline 


messages are printed. This option may be specified on the command line or it may be 
placed anywhere in the source input stream. In a source file, the option appears as a 
comment line and takes the following form. 

*$[NOJWArnings 

The "warnings" option enables the printing of warning messages, while "nowarnings" 
disables the printing of these messages. 

The "wild" option suppresses the compile-time checking that normally causes an error to be 
issued when an attempt is made to transfer control into a block structure from outside the 
block structure and vice versa. For example, this option will allow a transfer of control into 
an IF-block from outside the IF-block (which is normally prohibited). The default option is 
"nowild". 

Extreme caution should be exercised when using this option. For example, transfer of 
control into a DO-loop from outside the DO-loop can cause unpredictable results. This 
programming style is not encouraged by this option. The option has been made available 
so that existing programs that do not adhere to the branching restrictions imposed by the 
FORTRAN 77 standard (i.e. mainframe applications that are being ported to the PC 
environment), can be compiled by Open Watcom FORTRAN 77. 

(16-bit only) The "windows" option causes the compiler to generate the prologue/epilogue 
code sequences necessary for use in Microsoft Windows applications. The default option is 
"nowindows". 

The "xfloat" option specifies that all REAL variables are treated as if they had been 
declared as "DOUBLE PRECISION". This effectively increases the precision of REAL 
variables. Note that the "xfloat" option has implications on the alignment of variables in 
common blocks. The default option is "noxfloat". 

The "xline" option informs the Open Watcom F77 compiler to extend the last column of the 
statement portion of a line to column 132. The default is 72. 
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3 The Open Watcom FORTRAN 77 Compiler 


This chapter describes the following topics: 

• Command line syntax (see "Open Watcom FORTRAN 77 Command Line Format") 

• Environment variables used by the compilers (see "WFC/WFC386 Environment Variables" on page 
24) 

• Examples of command line syntax (see "Open Watcom FORTRAN 77 Command Line Examples" 
on page 24) 

• Interpreting diagnostic messages (see "Compiler Diagnostics" on page 25) 

• Include file handling (see "Open Watcom FORTRAN 77 INCLUDE File Processing" on page 27) 

3.1 Open Watcom FORTRAN 77 Command Line Format 

The formal Open Watcom FORTRAN 77 command line syntax is shown below. 

WFC [options] [d:][path]filename[.ext] [options] 

WFC386 [options] [d:][path]filename[. ext] [options] 

The square brackets [ ] denote items which are optional. 

WFC is the name of the 16-bit Open Watcom F77 compiler. 

WFC386 is the name of the 32-bit Open Watcom F77 compiler. 

d: is an optional drive specification such as "A:", "B:", etc. If not specified, the default drive 

is assumed. 

path is an optional path specification such as \PROGRAMS\SRC\ . If not specified, the current 

directory is assumed. 

filename is the file name of the file to be compiled. 

ext is the file extension of the file to be compiled. If omitted, a file extension of "FOR" is 

assumed. If the period "." is specified but not the extension, the file is assumed to have no 
file extension. 

options is a list of valid Open Watcom F77 options, each preceded by a slash ("/") or a dash ("—"). 

Certain options can include a "no" prefix to disable an option. Options may be specified in 
any order, with the rightmost option taking precedence over any conflicting options 
specified to its left. 
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3.2 WFC/WFC386 Environment Variables 


The WFC environment variable can be used to specify commonly used WFC options. The WFC386 
environment variable can be used to specify commonly used WFC386 options. These options are 
processed before options specified on the command line. 

Example: 

C>set wfc=-dl -ot 
C>set wfc386=-dl -ot 

The above example defines the default options to be "dl" (include line number debugging information in 
the object file), and "ot" (favour time optimizations over size optimizations). 

Whenever you wish to specify an option that requires the use of an "=" character, you can use the "#" 
character in its place. This is required by the syntax of the "SET" command. 

Once a particular environment variable has been defined, those options listed become the default each time 
the associated compiler is used. The compiler command line can be used to override any options specified 
in the environment string. 

These environment variables are not examined by the Open Watcom Compile and Link utilities. Since the 
Open Watcom Compile and Link utilities pass the relevant options found in their associated environment 
variables to the compiler command line, their environment variable options take precedence over the 
options specified in the environment variables associated with the compilers. 


Hint: If you are running DOS and you use the same compiler options all the time, you may find it 
handy to define the environment variable in your DOS system initialization file, AUTOEXEC . BAT . 

If you are running Windows NT, use the "System" icon in the Control Panel to define environment 
variables. 

If you are running OS/2 and you use the same compiler options all the time, you may find it handy to 
define the environment variable in your OS/2 system initialization file, CONFIG. SYS . 


3.3 Open Watcom FORTRAN 77 Command Line Examples 

The following are some examples of using Open Watcom LORTRAN 77 to compile LORTRAN 77 source 
programs. 

Example 1: 

C>wfc386 report /dl /stack 

The 32-bit Open Watcom L77 compiler processes REPORT . FOR producing an object file which contains 
source line number information. Stack overflow checking code is included in the object code. 
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Example 2: 

C>wfc kwikdraw /2 /fpi87 

The 16-bit Open Watcom F77 compiler processes KWIKDRAW. FOR producing object code for an Intel 286 
system equipped with an Intel 287 numeric data processor (or any upward compatible 386/387, 486 or Intel 
Pentium system). While the choice of these options narrows the number of microcomputer systems where 
this code will execute, the resulting code will be highly optimized for this type of system. 

Example 3: 

C>wfc ..\source\modabs /d2 

The 16-bit Open Watcom F77 compiler processes . . \SOURCE\MODABS . FOR (a file in a directory which 
is adjacent to the current one). The object file is placed in the current directory. Included with the object 
code and data is information on local symbols and data types. The code generated is straight-forward, 
unoptimized code which can be readily debugged with Open Watcom Debugger. 

Example 4: 

C>wfc386 /mf calc 

The 32-bit Open Watcom F77 compiler compiles CALC . FOR for the "flat" memory model. 32-bit memory 
models are described in the chapter entitled "32-bit Memory Models" on page 147. 32-bit argument 
passing conventions are described in the chapter entitled "32-bit Assembly Language Considerations" on 
page 151. 

Example 5: 

C>wfc386 kwikdraw /fpi87 

The 32-bit Open Watcom F77 compiler processes KWIKDRAW. FOR producing object code for an Intel 386 
system equipped with an Intel 80x87 numeric data processor. 

Example 6: 

C>set wfc=/short /d2 /fo#*.dbj 
C>wfc ..\source\modabs 

The options / short, /d2 and /fo=* .dbj are established as defaults using the WFC environment 
variable. The 16-bit compiler processes . . \SOURCE\MODABS . FOR (a file in a directory which is 
adjacent to the current one). The object file is placed in the current directory and it will have a default file 
extension of "DBJ". All INTEGER and LOGICAL variables will have a default type of INTEGER*2 and 
LOGICAL* 1 unless explicitly typed as INTEGER*4 or LOGICAL*4. Source line number and local 
symbol information are included with the object file. 

3.4 Compiler Diagnostics 

If the Open Watcom F77 compiler prints diagnostic messages to the screen, it will also place a copy of 
these messages in a file in your current directory (unless the "noerrorfile" option is specified). The file will 
have the same file name as the source file and an extension of "err". The compiler issues three types of 
diagnostic messages, namely extensions, warnings and errors. An extension message indicates that you 
have used a feature which is supported by Open Watcom F77 but that is not part of the FORTRAN 77 
language standard. A warning message indicates that the compiler has found a questionable problem in the 
source code (e.g., an unreachable statement, an unreferenced variable or statement number, etc.). A 
warning message does not prevent the production of an object file. An error message indicates that a 
problem is severe enough that it must be corrected before the compiler will produce an object file. The 
error file is a handy reference when you wish to correct the errors in the source file. 
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Just to illustrate the diagnostic features of Open Watcom F77, we will compile the following program 
called "DEMOl". 

* This program demonstrates the following features of 

* Open Watcom's FORTRAN 77 compiler: 

* 1. Extensions to the FORTRAN 77 standard are flagged. 

* 

* 2. Compile time error diagnostics are extensive. As many 

* errors as possible are diagnosed. 

* 

* 3. Warning messages are displayed where potential problems 

* can arise. 

* 

PROGRAM MAIN 
DIMENSION A(10) 

DO 1=1,10 

A (I) = I 
1 = 1 + 1 
ENDLOOP 
GO TO 30 
J = J + 1 

30 END 

If we compile this program with the "extensions" option, the following output appears on the screen. 

C>wfc demol /exten 

WATCOM FORTRAN 77/16 Optimizing Compiler Version 2.0 1997/07/16 09:22:47 
Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

demol.for(14): *EXT* DO-05 this DO loop form is not FORTRAN 77 standard 
demol.for(16): *ERR* DO-07 column 13, DO variable cannot be redefined 
while DO loop is active 

demol.for(17): *ERR* SP-19 ENDLOOP statement does not match with DO 
statement 

demol.for(19): *WRN* ST-08 this statement will never be executed due to 
the preceding branch 

demol.for: 9 statements, 0 bytes, 1 extensions, 1 warnings, 2 errors 

Here we see an example of the three types of messages, extension (*EXT*), error (*ERR*) and warning 
(*WRN*). 

Diagnostic messages are also included in the listing file if the "list" option is specified. If we recompile our 
program and include the "list" option, a listing file will be created. 

C>wfc demol /exten/list 
or 

C>wfc386 demol /exten/list 
The contents of the listing file are: 
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WATCOM FORTRAN 77/16 Optimizing Compiler Version 2.0 1997/07/16 09:22:47 
Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

Options: list,disk,errorfile,extensions,reference,warnings,fpi,oc,of,om, 
os,ot,ox,ml,0,terminal,dependency,fsfloats,gsfloats,libinfo,dt=256, 
align 


1 * This program demonstrates the following features of 

2 * Open Watcom's FORTRAN 77 compiler: 

3 * 

4 * 1. Extensions to the FORTRAN 77 standard are flagged. 

5 * 

6 * 2. Compile time error diagnostics are extensive. As many 

7 * errors as possible are diagnosed. 

8 * 


9 * 

3. Warning messages 

10 * 

can arise. 

11 * 


12 

PROGRAM MAIN 

13 

DIMENSION A(10) 

14 

DO 1=1,10 

DO-05 

this DO loop form is 

15 

A (I) = I 

16 

1 = 1 + 1 


are displayed where potential problems 


not FORTRAN 77 standard 


*ERR* DO-07 

17 

*ERR* SP-19 

18 

19 

*WRN* ST-08 

20 30 


$ 

DO variable cannot be redefined while DO loop is active 
ENDLOOP 

ENDLOOP statement does not match with DO statement 
GO TO 30 
J = J + 1 

this statement will never be executed due to the preceding branch 
END 


Code size (in bytes): 

Compile time (in seconds): 
Number of statements compiled: 


0 Number of errors: 

0 Number of warnings: 

9 Number of extensions: 


2 

1 

1 


As part of the diagnostic capability of Open Watcom F77, a "$" is often used to indicate the particular place 
in the source line where an error has been detected. 


The complete list of Open Watcom F77 diagnostic messages is presented in the appendix entitled "Open 
Watcom F77 Diagnostic Messages" on page 209. 


3.5 Open Watcom FORTRAN 77 INCLUDE File Processing 

For information on include file processing, see the section entitled "The INCLUDE Compiler Directive" on 
page 34 in the chapter entitled "Open Watcom FORTRAN 77 Compiler Directives" 


Open Watcom FORTRAN 77 INCLUDE File Processing 


27 




Open Watcom FORTRAN 77 User’s Guide 


28 Open Watcom FORTRAN 77 INCLUDE File Processing 




4 The Open Watcom FORTRAN 77 Libraries 


The Open Watcom FORTRAN 77 library routines (intrinsic functions) are described in the Open Watcom 
FORTRAN 77 Language Reference manual. Additional run-time routines are described in the chapter 
entitled "The Open Watcom F77 Subprogram Library" on page 59. Since Open Watcom FORTRAN 77 
supports two major architectures, the 286 architecture (which includes the 8088) and the 386 architecture 
(which includes the 486 and Pentium processors), libraries are grouped under two major directories. 

For the 286 architecture, the processor dependent libraries are placed under the \WATCOM\LIB2 8 6 
directory. 

For the 386 architecture, the processor dependent libraries are placed under the \WATCOM\LIB3 8 6 
directory. 

Since Open Watcom FORTRAN 77 also supports several operating systems, including DOS, Windows 3.x, 
Windows 95, Windows NT, OS/2 and NetWare, system-dependent libraries are grouped under different 
directories underneath the processor-dependent directories. 

System 16-bit applications 32-bit applications 

DOS \WATCOM\LIB2 8 6\DOS \WATCOM\LIB386\DOS 

OS/2 \WATCOM\LIB286\OS2 \WATCOM\LIB386\OS2 

Windows 3.x \WATCOM\LIB286\WIN \WATCOM\LIB386\WIN 

Windows NT \WATCOM\LIB386\NT 

Windows 95 

NetWare \WATCOM\LIB386\NETWARE 


\watcom 

. - + - . 

Iib286 lib386 

. - + - . . - . - + - . - . 

dos os2 win dos os2 win nt netware 


Due to the many code generation strategies possible in the 80x86 family of processors, a number of 
versions of the libraries are provided. You must use the libraries which coincide with the particular 
architecture, operating system, and code generation strategy or model that you have selected. For the type 
of code generation strategy or model that you intend to use, refer to the description of the "m?" memory 
model compiler option in the chapter entitled "Open Watcom FORTRAN 77 Compiler Options" on page 5. 
The various code models supported by Open Watcom FORTRAN 77 are described in the chapters entitled 
"16-bit Memory Models" on page 97 and "32-bit Memory Models" on page 147. 
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We have selected a simple naming convention for the libraries that are provided with Open Watcom 

FORTRAN 77. Letters are affixed to the file name to indicate the particular strategy with which the 

modules in the library have been compiled. 

M denotes a version of the 16-bit Open Watcom FORTRAN 77 libraries which have been 

compiled for the "medium" memory model (big code, small data). 

L denotes a version of the 16-bit Open Watcom FORTRAN 77 libraries which have been 

compiled for the "large" or "huge" memory models (big code, big data or huge data). 

7 denotes a version of the Open Watcom FORTRAN 77 libraries which should be used when 

compiling with the "fpi" or "fpi87" option. Otherwise the libraries have been compiled 
using the "fpc" compiler option. 

S denotes a version of the 32-bit Open Watcom FORTRAN 77 libraries which have been 

compiled using the "sc" option (stack calling conventions). 

The 16-bit Open Watcom FORTRAN 77 libraries are listed below by directory. 


Under \WATCOM\LIB286\DOS 


FLIBM.LIB 
FLIB7M.LIB 
FLIBL.LIB 
FLIB7L.LIB 
CLIBM.LIB 
CLIBL.LIB 
GRAPH.LIB 


(DOS medium model) 

(DOS medium model, in-line 80x87) 

(DOS large/huge model) 

(DOS large/huge model, in-line 80x87) 
(DOS i/o system medium model) 

(DOS i/o system large/huge model) 

(DOS graphics support) 


Under \WATCOM\LIB286\WIN 


FLIBM.LIB 
FLIB7M.LIB 
FLIBL.LIB 
FLIB7L.LIB 
CLIBM.LIB 
CLIBL.LIB 
WINDOWS.LIB 


(Windows 

(Windows 

(Windows 

(Windows 

(Windows 

(Windows 

(Windows 


medium model) 

medium model, in-line 80x87) 
large/huge model) 
large/huge model, in-line 80x87) 
i/o system medium model) 
i/o system large/huge model) 

API library) 


Under \WATCOM\LIB286\OS2 


FLIBM.LIB 
FLIB7M.LIB 
FLIBL.LIB 
FLIB7L.LIB 
CLIBM.LIB 
CLIBL.LIB 
DOSPMM.LIB 
DOSPML.LIB 


(OS/2 medium model) 

(OS/2 medium model, in-line 80x87) 
(OS/2 large/huge model) 

(OS/2 large/huge model, in-line 80x87) 
(OS/2 i/o system medium model) 

(OS/2 i/o system large/huge model) 
(Phar Lap 286 PM medium model) 

(Phar Lap 286 PM large/huge model) 


The 32-bit Open Watcom FORTRAN 77 libraries are listed below. 
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Under \WATCOM\LIB386\DOS 

FLIB.LIB (floating-point calls) 

FLIB7.LIB (in-line 80x87) 

FLIBS.LIB (floating-point calls, stack conventions) 

FLIB7S.LIB (in-line 80x87, stack conventions) 

CLIB3R.LIB (i/o system) 

CLIB3S.LIB (i/o system, stack conventions) 

GRAPH.LIB (DOS graphics support) 

The graphics library GRAPH. LIB is independent of the argument passing conventions or floating-point 
model. 

Under \WATCOM\LIB386\WIN 

FLIB.LIB (floating-point calls) 

FLIB7.LIB (in-line 80x87) 

FLIBS.LIB (floating-point calls, stack conventions) 

FLIB7S.LIB (in-line 80x87, stack conventions) 

CLIB3R.LIB (i/o system) 

CLIB3S.LIB (i/o system, stack conventions) 

WIN386.LIB (32-bit Windows API) 

Under \WATCOM\LIB386\OS2 

FLIB.LIB (floating-point calls) 

FLIB7.LIB (in-line 80x87) 

FLIBS.LIB (floating-point calls, stack conventions) 

FLIB7S.LIB (in-line 80x87, stack conventions) 

CLIB3R.LIB (i/o system) 

CLIB3S.LIB (i/o system, stack conventions) 

Under \WATCOM\LIB386\NT 

FLIB.LIB (floating-point calls) 

FLIB7.LIB (in-line 80x87) 

FLIBS.LIB (floating-point calls, stack conventions) 

FLIB7S.LIB (in-line 80x87, stack conventions) 

CLIB3R.LIB (i/o system) 

CLIB3S.LIB (i/o system, stack conventions) 


4.1 Open Watcom FORTRAN 77 80x87 Emulator Libraries 

One of the following libraries must be used if any of the modules of your application were compiled with 
the "fpi" option. 

16-bit Libraries 

NOEMU87.LIB 

DOS\EMU87.LIB (DOS dependent) 

WIN\EMU87.LIB (Windows dependent) 

OS2\EMU87.LIB (OS/2 dependent) 
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32-bit Libraries 

NOEMU387.LIB 

DOS\EMU387.LIB (DOS dependent) 

WIN\EMU387.LIB (Windows dependent) 

OS2\EMU387.LIB (OS/2 dependent) 

NT\EMU387.LIB (Windows NT dependent) 

The "fpi" option causes an 80x87 numeric data processor emulator to be linked into your application. This 
emulator will decode and emulate 80x87 instructions when an 80x87 is not present in the system or if the 
environment variable N087 has been set (this variable is described below). 

If you have compiled your application using the "fpi" option, you can also link with the 16-bit 
"noemu87.1ib" or 32-bit "noemu387.1ib" library, depending on which compiler you are using. However, 
your application will only run on a machine equipped with a 80x87 numeric data processor since the actual 
emulator is not linked into your application. 

When the "fpi87" option is used exclusively, the emulator is not included. In this case, the application must 
be run on personal computer systems equipped with the numeric data processor. 


4.2 The "N087" Environment Variable 


If you have a math coprocessor in your system but you wish to test a version of your application that will 
use floating-point emulation ("fpi" option) or simulation ("fpc" option), you can define the N087 
environment variable. The 16-bit application must be compiled using the "fpc" (floating-point calls) option 
and linked with the appropriate f lib? . lib library or the "fpi" option (default) and linked with the 
appropriate f lib7 ? . lib and emu8 7 . lib libraries. The 32-bit application must be compiled using the 
"fpc" (floating-point calls) option and linked with the appropriate f lib? . lib library or the "fpi" option 
(default) and linked with the appropriate flib7? . lib and emu387 . lib libraries. Using the "SET" 
command, define the environment variable as follows: 

C>SET N087=l 

Now, when you run your application, the 80x87 will be ignored. To undefine the environment variable, 
enter the command: 

C>SET N087= 
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5 Open Watcom FORTRAN 77 Compiler Directives 


5.1 Introduction 


A number of compiler directives are available that allow, for example, conditional compilation of source 
code and the inclusion of source code from other files. A compiler directive is specified by placing a 
comment character (’c’, ’C’, or ’*’) in column one followed by a dollar sign (’$’) immediately followed by 
the compiler directive. The following lists all of the compiler directives available with Open Watcom F77. 


1. EJECT 

2. INCLUDE 

3. PRAGMA 

4. DEFINE 

5. UNDEFINE 

6. IFDEF 

7. IFNDEF 

8. ENDIF 

9. ELSE 

10. ELIFDEF 

11. ELIFNDEF 


These compiler directives will be described in the following sections. 

In addition to the above compiler directives, it is also possible to specify certain compiler options in the 
same way. The following lists these options. 

1. [NO]EXTENSIONS 

2. [NO]LIST 

3. [NO]REFERENCE 

4. [NO]WARNINGS 

For more information on these options, see the the chapter entitled "Open Watcom FORTRAN 77 Compiler 
Options" on page 5. 


5.2 The EJECT Compiler Directive 

This compiler directive causes a form-feed to be generated in the listing file. The listing file is a 
carriage-control file that is created by the compiler when the "list" compiler option is specified. In the 
following example, a form-feed character will be generated immediately before the source for subroutine 
sub2 and immediately before the source for subroutine sub3 . 
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Example: 

subroutine subl 
! source code 
end 
*$eject 

subroutine sub2 
! source code 
end 
*$eject 

subroutine sub3 
! source code 
end 


5.3 The INCLUDE Compiler Directive 

The INCLUDE compiler directive or INCLUDE statement may be used to imbed source code into the file 
being compiled. Either form may be used. 

Example: 

* $INCLUDE DOS.FI 

INCLUDE 'DOS.FI' 

When the INCLUDE statement is used the name of the file must be placed inside single quotes 
(apostrophes). The file name may include drive, path, and file extension. The default file extension is 
. for. 

It is not necessary to include the drive and path specifiers in the file specification when the file resides on a 
different drive or in a different directory. Open Watcom F77 provides a mechanism for looking up include 
files which may be located in various directories and disks of the computer system. When the drive and 
path are omitted from a file specification. Open Watcom F77 searches directories for include files in the 
following order. 

1. First, the current directory is searched. 

2. Secondly, each directory listed with the "INCPath" option is searched (in the order that they 
were specified). 

3. Thirdly, each directory listed in the FINCLUDE environment variable is searched (in the order 
that they were specified). 

The compiler will search the directories listed with the "INCPath" option or in the FINCLUDE 
environment variable in a manner analogous to that which used by the operating system when searching for 
programs by using the PATH environment variable. 

The "INCPath" option takes the following form. 

-INCPath=[d:]path;[d:]path... 

The "SET" command is used to define an FINCLUDE environment variable that contains a list of 
directories. A command of the form 

SET FINCLUDE= [d:] path; [d: ]path... 

is issued before running Open Watcom F77 the first time. The brackets indicate that the drive d: is 
optional and the ellipsis indicates that any number of paths may be specified. 
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We illustrate the use of the INCLUDE statement in the following example. 


subroutine ClearScreen() 

implicit none 

include 'dos.fi' 

integer VIDEO_ CALL, SCROLL_ UP 

parameter (VIDEO_ CALL=16, SCROLL_ UP=6) 


DS = ES = FS = GS = 0 

AH = SCROLL_ UP 

AL = 0 

CX = 0 

DX = 24*256 + 80 
BH = 7 

call f intr ( VIDEO_ CALL, 
end 


! for safety on 386 DOS extender 
! scroll up 
! blank entire window 
! set row,column of upper left 
! set row,column of lower right 
! attribute "white on black" 
regs ) 


The third line of this subroutine contains an INCLUDE statement for the file DOS . FI . If the above 
source code is stored in the file CLRSCR. FOR in the current directory then we can issue the following 
commands to compile the application. 

C>set finclude=c:\watcom\src\fortran\dos 

C>wfc clsscr 

In the above example, the "SET" command is used to define the FINCLUDE environment variable. It 
specifies that the \WATCOM\SRC\FORTRAN\DOS directory is to be searched for include files that cannot 
be located in the current directory and that have no drive or path specified. The advantage of the 
FINCLUDE environment variable is that drives and paths can be omitted from the INCLUDE file 
specifications in the source code. This allows the source code to be independent of the disk/directory 
structure of your computer system. 


5.4 The PRAGMA Compiler Directive 

This compiler directive is described in the chapters entitled "16-bit Pragmas" on page 115 and "32-bit 
Pragmas" on page 165. 


5.5 The DEFINE Compiler Directive 

The DEFINE compiler directive sets the definition status of a macro to defined. If a macro does not appear 
in a DEFINE directive, its definition status is undefined. 

Example: 

*$define debug 

In the above example, the macro debug is defined. 

The DEFINE compiler option can also be used to define a macro. 
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Example: 

C>wfc /define=debug test 
C>wfc386 /define=debug test 


5.6 The UNDEFINE Compiler Directive 

The UNDEFINE compiler directive sets the definition status of a macro to undefined. 
Example: 

*$undefine debug 

In the above example, the definition status of the macro debug is set to undefined. 


5.7 The IFDEF, IFNDEF and ENDIF Compiler Directive 

The IFDEF and IFNDEF compiler directives check the definition status of a macro. If the macro appearing 
in an IFDEF directive is defined or the macro appearing in an IFNDEF directive is not defined, then all 
source code up to the corresponding ENDIF compiler directive will be compiled. Otherwise, it will be 
ignored. 

In the following example, the FORTRAN 77 statements represented by <debugging_ statements> 
will be compiled. 

Example: 

*$define debug 

*$ifdef debug 

<debugging_ statements> 

*$endif 

In the following example, the FORTRAN 77 statements represented by <debugging_ statements> 
will not be compiled. 

Example: 

*$undefine debug 

*$ifdef debug 

<debugging_ statements> 

*$endif 

In the following example, the FORTRAN 77 statements represented by <debugging_ statements> 
will be compiled. 

Example: 

*$undefine debug 

*$ifndef debug 

<debugging statements> 

*$endif 
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5.8 The ELSE Compiler Directive 

The ELSE compiler directive must be preceded by an IFDEF, IFNDEF, ELSEIFDEF or ELSEIFNDEF 
compiler directive. If the condition of the preceding compiler directive was satisfied, then all source code 
between the ELSE compiler directive and the corresponding ENDIF compiler directive will be ignored. If 
the condition of the preceding compiler directive was not satisfied, then all source code between the ELSE 
compiler directive and the corresponding ENDIF compiler directive will be compiled. 

In the following example, the FORTRAN 77 statements represented by 
<debugging_ level_ 2_ statements> will be compiled. 

Example: 

*$undefine debug_ level_ 1 

*$ifdef debug_ level_ 1 

<debugging_ level_ 1_ statements> 

*$else 

<debugging_ level_ 2_ statements> 

*$endif 


5.9 The ELSEIFDEF and ELSEIFNDEF Compiler Directive 

The ELSEIFDEF and ELSEIFNDEF compiler directives must be preceded by an IFDEF, IFNDEF, 
ELSEIFDEF or ELSEIFNDEF compiler directive. If the condition of the preceding compiler directive was 
satisfied, then all source code between the ELSEIFDEF or ELSEIFNDEF compiler directive and the 
corresponding ENDIF compiler directive will be ignored. If the condition of the preceding compiler 
directive was not satisfied, then the definition status of the macro specified in the ELSEIFDEF or 
ELSEIFNDEF compiler directive is checked. If the macro appearing in the ELSEIFDEF compiler directive 
is defined, or the macro appearing in the ELSEIFNDEF compiler directive is not defined, then all source up 
to the next ELSEIFDEF, ELSEIFNDEF, ELSE or ENDIF compiler directive will be compiled. 

In the following example, the FORTRAN 77 statements represented by 
<debugging_ level_ 2_ statements> will be compiled. 

Example: 

*$define debug_ level_ 2 

*$ifdef debug_ level_ 1 

<debugging_ level_ 1_ statements> 

*$elseifdef debug_ level_ 2 

<debugging_ level_ 2_ statements> 

*$endif 


5.10 Debugging statements (“D“ in Column 1) 

If the character "D" or "d" appears in column 1, that line will be conditionally compiled depending on the 

definition status of the macro_debug_. Statements that contain a "D" or "d" in column 1 are called 

debugging statements. If the_debug_macro is defined, the line will be compiled; otherwise it will be 

ignored. The_debug_macro can be defined by using the DEFINE compiler directive or the "define" 

option. In the following example, the "define" option is used to force compilation of debugging statements. 
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Example: 

C>wfc /def=_debug_test 

C>wfc38 6 /def=_debug_test 


5.11 General Notes About Compiler Directives 

1. Compiler directives must not contain embedded blanks. The following is not a valid ENDIF 
compiler directive. 

Example: 

*$end if 

2. Nesting is allowed up to a maximum of 16 levels. 

Example: 

*$ifdef syml 

<statements> 

*$ifdef sym2 

<statements> 

*$endif 

*$endif 

3. The macro_i8 6_is a special macro that is defined by the compiler and identifies the target 

as a 16-bit Intel 80x86 compatible environment. 

4. The macro_ 38 6_is a special macro that is defined by the compiler and identifies the target 

as a 32-bit Intel 80386 compatible environment. 

5. The macro_stack_ conventions_is a special macro that is defined by the 32-bit 

compiler when stack conventions are used for code generation. Stack conventions are used 
when the "sc" or "3s" compiler options are specified. 

6. The macro_fpi_is a special macro that is defined by the compiler when one of the 

following floating-point options is specified: "fpi" or "fpi87". 

7. The macro_debug_is a special macro that can be used to conditionally compile debugging 

statements. A debugging statement is one that contains the character "D" or "d" in column one. 
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6 Open Watcom FORTRAN 77 File Handling 


This chapter describes the file handling and naming conventions of Open Watcom F77. We discuss /i7e.v 
and devices which are used to store, retrieve and display data. For example, a disk can be used to store a 
file of student marks. This file is accessible by other programs in order to produce summaries of the data 
such as marks reports. A device such as a printer can also be treated as if it were a file, although it is only 
useful for displaying data; an attempt to read information from this device is invalid. 

In the following sections, we shall describe: 

1. the techniques that Open Watcom F77 adopts for implementing FORMATTED and 
UNFORMATTED records and SEQUENTIAL and DIRECT access to these records, 

2. the handling of "print" files, 

3. file naming conventions, 

4. logical file names, 

5. the preconnection of files to units, and 

6. special device support. 

6.1 Record Access 


Two types of record access are supported by Open Watcom F77: 

Sequential Sequential access means that records in a file are accessed in order, starting with the first 
record in the file and proceeding to the last. Sequential access is permitted to records in 
both variable-length and fixed-length record files. 

Direct Direct access means that records in a file are accessed in random order. For example, the 

fifth record could be accessed, then the second, and then the tenth. Direct access is 
permitted for fixed-length record files only. 

The access method is described using the ACCESS= specifier of the FORTRAN OPEN statement. The 

default access is "SEQUENTIAL". 


6.2 Record Format 


There are two record formats, "FORMATTED" and "UNFORMATTED", which are supported by Open 
Watcom F77. The record format is described using the FORM= specifier of the FORTRAN OPEN 
statement. The default format is "FORMATTED" for files connected for sequential access and 
"UNFORMATTED" for files connected for direct access. 

In describing these two formats, we also refer to the two methods of record access, "SEQUENTIAL" and 
"DIRECT", which are supported by Open Watcom F77. 


Record Format 39 




Open Watcom FORTRAN 77 User’s Guide 


6.2.1 FORMATTED Records 

A FORMATTED record is one that contains an arbitrary number of ASCII characters. The end of a record 
is marked by an ASCII "LF" (line feed) character optionally preceded by an ASCII "CR" (carriage return) 
character. Thus this special sequence may not appear in the middle of a record. 

FORMATTED records may vary in length. If all the records in the file have the same length then the 
records may be accessed both "sequentially" and "directly". If the records vary in length then it is only 
possible to access the records sequentially. 

For direct access, the length of the records is specified by the RECL= specifier of the FORTRAN OPEN 
statement. The specified length must not include the record separator since it does not form part of the 
record. 

As an extension to the FORTRAN 77 language standard. Open Watcom F77 also supports the use of the 
RECL= specifier for sequential access. The maximum length of the records may be specified by the 
RECL= specifier of the FORTRAN OPEN statement. The specified length must not include the record 
separator since it does not form part of the record. The length is used to allocate a record buffer for 
sequential access. If the record length is not specified, a default maximum length of 1024 characters is 
assumed. 


6.2.2 UNFORMATTED Records 


An UNFORMATTED record is one that contains an arbitrary number of binary storage units. The 
interpretation of the data in such a record depends on the FORTRAN program that is processing the record. 
An UNFORMATTED record may contain integers, real numbers, character strings, or any other type of 
FORTRAN data. 

UNFORMATTED records may also vary in length. If all records in the file have the same length then the 
records may be accessed both "sequentially" and "directly". If the records vary in length then it is only 
possible to access the records sequentially. 

When a file containing UNFORMATTED records is accessed sequentially, each record must begin and end 
with a descriptor that contains the length of the record. The length of the record is represented in 32 bits or 
4 bytes (INTEGER*4). The UNFORMATTED records of a file which are written using sequential access 
will be automatically supplied with the appropriate length descriptors. When such a file is read, it is 
assumed that each record has the appropriate length descriptors. 

Depending on the record length, the output produced by a single unformatted sequential WRITE statement 
may cause multiple records to be written. As previously mentioned, each record begins and ends with a 
length descriptor. The length descriptors for the first record contain the length of the record. The length 
descriptors for the remaining records contain the length of the record with the high bit (bit 31) set to one. 

In this way, an unformatted sequential file can be viewed as a number of logical records (a logical record 
corresponding to the output produced by a WRITE statement) with each logical record composed of a 
number of physical records. Files created in this way cannot be accessed directly unless each logical record 
is composed of a single physical record and each record is the same size. 

As an extension to the FORTRAN 77 language standard. Open Watcom F77 also supports the use of the 
RECL= specifier for sequential access. The maximum length of the records may be specified by the 
RECL= specifier of the FORTRAN OPEN statement. The specified length must not include the length 
descriptors since they do not form part of the record. The length is used to allocate a record buffer for 
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sequential access. If the record length is not specified, a default maximum length of 1024 characters is 
assumed. 

When a file containing UNFORMATTED records is accessed directly, each record must be the same 
length. In this case, the length of the records is specified by the RECL= specifier of the FORTRAN OPEN 
statement. If the file was originally created with sequential access then the specified length must include 
any length descriptors which form part of the record. In the direct access mode, no interpretation is placed 
on any of the data in an UNFORMATTED record and the programmer must account for any record length 
descriptors which may form part of the record. 

Any records which are written using direct access must include record length descriptors if the file is to be 
accessed sequentially at a later time. As an alternative, you may specify RECORDTYPE='VARIABLE' in 
the FORTRAN OPEN statement. This specifier is an extension to the FORTRAN 77 language standard 
and will cause length descriptors to be generated automatically. In this case, the record length should not 
include the record length descriptors. 

6.2.3 Files with no Record Structure 

Certain files, for example a file created by a program written in another language, do not have any internal 
record structure that matches any of the record structures supported by Open Watcom F77. These files are 
simply streams of data. There are two ways in which these files can be processed. 

1. You can use unformatted direct access. In this case, the value specified by the RECL= specifier 
in the OPEN statement determines the amount of data read or written by a READ or WRITE 
statement. 

2. Alternatively, you can use unformatted sequential access. In this case, the amount of data read 
or written to the file is determined by the items in the input/output list of the READ or WRITE 
statement. When using unformatted sequential access, you must specify 
RECORDTYPE=' FIXED' to indicate that no record boundaries are present. Otherwise, the 
default value of ' VARIABLE' will be used. 


6.3 Attributes of Files 


The file system does not retain any information on the contents of a file. Unlike more sophisticated file 
systems, it cannot report whether a file consists of fixed-length or variable-length records, how records are 
delimited in a file, the maximum length of the records, etc. Therefore, we have provided a mechanism 
which will allow you to specify additional information about a file. This mechanism should be used when 
the default assumptions about records in a file are not true for the file in question. 

The RECORDTYPE= specifier of the FORTRAN OPEN statement can be used to specify additional 
information about the type of records in the file. This specifier is an extension to the FORTRAN 77 
language standard. 

The RECL= specifier of the FORTRAN OPEN statement can be used to specify additional information 
about the length of records in the file. When used with sequential access, this specifier is an extension to 
the FORTRAN 77 language standard. 

The CARRIAGECONTROL= specifier of the FORTRAN OPEN statement can be used to specify 
additional information about the handling of ASA carriage control characters for an output file. This 
specifier is an extension to the FORTRAN 77 language standard. 
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The BLOCKSIZE= specifier of the FORTRAN OPEN statement can be used to specify the size of the 
internal input/output buffer. A buffer reduces the number of system input/output calls during input/output 
to a particular file and hence improves the overall performance of a program. The default buffer size is 4K. 
This specifier is an extension to the FORTRAN 77 language standard. 

The following sections describe the attributes of records supported by the Open Watcom F77 run-time 
system. 

6.3.1 Record Type 

The RECORDTYPE= specifier of the FORTRAN OPEN statement can be used to specify additional 
information about the type of records in the file. This specifier is an extension to the FORTRAN 77 
language standard. The following types may be specified. 

RECORDTYPE='TEXT' 

RECORDTYPE='VARIABLE' 

RECORDTYPE='FIXED' 

TEXT indicates that the file contains variable-length or fixed-length records of ASCII characters 

separated by an ASCII "LF" (line feed) character optionally preceded with an ASCII "CR" 
(carriage return) character. By default, the Open Watcom F77 run-time system assumes 
that FORMATTED records are of TEXT format in both the sequential and direct access 
modes. 

By default, the Open Watcom F77 run-time system uses variable-length record TEXT files 
to implement FORMATTED records in the sequential access mode. Of course, all records 
may be the same length. The record separator is not included in calculating the maximum 
size of records in the file. 

By default, the Open Watcom F77 run-time system uses fixed-length record TEXT files to 
implement FORMATTED records in the direct access mode. Each record must be the 
same length. The record separator is not included in calculating the size of records in the 
file. 

VARIABLE indicates that the file contains variable-length or fixed-length records in which special 

descriptors are employed to describe the length of each record. The length of each record is 
contained in a doubleword (INTEGER*4 item) at the beginning and end of the record. 
These descriptors determine the bounds of the records. 

By default, the Open Watcom F77 run-time system uses VARIABLE format files to 
implement UNFORMATTED records in the sequential access mode. The length 
descriptors are required to support the FORTRAN BACKSPACE statement since no other 
method exists for determining the bounds of a variable-length unformatted record in a file. 

FIXED indicates that the file contains no extra information that determines the record structure. If 

the file is a direct access file, the value specified by the RECL= specifier determines the 
size of each record in the file. 

By default, the Open Watcom F77 run-time system uses FIXED format files to implement 
UNFORMATTED records in the direct access mode. 

If you specify FIXED with an unformatted sequential file, the size of the records is 
determined by the items in the input/output list. 
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6.3.2 Record Size 

When access is direct, the record length must be specified in the RECL= specifier of the FORTRAN 
OPEN statement. 

OPEN( UNIT=1, FILE='TEST.DAT', ACCESS='DIRECT', RECL=size, ... ) 

As an extension to the FORTRAN 77 language standard, the record length may also be specified when the 
access is sequential. This should be done whenever access is "sequential" and the maximum record length 
is greater than the default. 

OPEN( UNIT=1, FILE='TEST.DAT', ACCESS='SEQUENTIAL', RECL=size, ... ) 

The record length specified by size should not include record separators such as CR and LF, nor should it 
include record length descriptors when sequentially accessing a file containing unformatted records. 
However, for all files, records longer than the size specified will be truncated. The default record size is 
1024. The maximum record size is 65535 for the 16-bit run-time system. Since record buffers are 
allocated in the dynamic storage region, the size will be restricted to the amount of dynamic storage 
available. 

6.3.3 Print File Attributes 

When the first character of each record written to a file will contain an ASA (American Standards 
Association) carriage control character, the CARRIAGECONTROL= specifier of the FORTRAN OPEN 
statement should be used. This specifier is an extension to the FORTRAN 77 language standard. The ASA 
character is used for vertical spacing control. The valid characters and their interpretation are: 

"1" Advance to Top of Page 

"+" Advance Zero Lines (overprint) 

" " Advance 1 Line 

"0" Advance 2 Lines 

Advance 3 Lines 

If CARRIAGECONTROL=' YES' is specified then the Open Watcom F77 run-time system will 
automatically allocate an extra character at the beginning of a record for the vertical spacing control. 

Upon transmitting a record to a file which has the "carriage" attribute, the Open Watcom F77 run-time 
system will substitute the appropriate ASCII carriage control characters as follows. 

"1" Substitute a FF (form feed) for the "1". 

"+" Append only a CR (carriage return ) to the previous record. 

" " Throw away the blank character. 

"0" Substitute CR (carriage return) and LF (line feed) for the "0". 

Substitute two pairs of CR and LF for the 
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Any other character in this position will be treated as if a blank character had been found 
(i.e., it will be discarded). 

If the "carriage" attribute is not specified for a file then records will be written to the file without placing 
any interpretation on the first character position of the record. 

6.3.4 Input/Output Buffer Size 

The BLOCKSIZE= specifier is optional. However if you would like to change the default buffer size of 
16K for 32-bit applications and 4K for 16-bit applications, you must specify the buffer size in the 
BLOCKSIZE= specifier of the OPEN statement. 

OPEN( UNIT=1, FILE='TEST.DAT', BLOCKSIZE=1024, ... ) 


6.3.5 File Sharing 

On systems that support multi-tasking or networking, it is possible for for a file to be accessed 
simultaneously by more that one process. There are two specifiers in the OPEN statement that can be used 
to control the way in which files are shared between processes. 

The ACTION= specifier indicates the way in which the file is initially accessed. That is, the way in which 
the first process to open the file accesses the file. The values allowed for the ACTION= specifier are the 
following. 

’READ’ the file is opened for read-only access 

’WRITE’ the file is opened for write-only access 

’READWRITE’ the file is opened for both read and write access 

The SHARE= specifier can be used to indicate the manner in which subsequent processes are allowed to 
access the file while the file is open. The values allowed for the SHARE= specifier are the following. 


’COMPAT’ 

’DENYRW’ 

’DENYWR’ 

’DENYRD’ 


no other process may open the file 

other processes are denied read and write access 

other process are denied write access (allowed read-only access) 

other process are denied read access (allowed write-only access) 


’DENYNONE’ other processes are allowed read and write access 


Let us consider the following scenario. Suppose you want several processes to read a file and prevent any 
process that is reading the file from changing its contents. We first must establish the method of access for 
the first process that opens the file. In this case, we want read-only access so the ACTION=' READ' 
specifier must be used. Next, we must establish the method of access for subsequent processes. In our 
example, we do not want any process to make changes to the file. Therefore, we use the 
SHARE=' DENYWR' specifier. The file would be opened using the following OPEN statement. 

OPEN( UNIT=1, FILE='TEST.DAT', ACTION='READ', SHARE='DENYWR', ... ) 
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6.4 File Names in the FAT File System 

The FAT file system is supported by DOS and OS/2. OS/2 also supports the High Performance File 
System (HPFS) which will be discussed in a later section. File naming conventions are used to form file 
designations in a given file system. The file designation for a FAT file system has the following form. 

[d:][path]filename[.ext] 

[] The square brackets denote items which are optional. 

d: is the drive name. If omitted, the default drive is assumed. 

Examples of drive names are: a:, b :, c :, and d:. 

path is called a "path" specification. The path may be used to refer to files that are stored in 

sub-directories of the disk. The complete file specification (including drive, path and file 
name) cannot exceed 143 characters. 

Some examples of path specifications are: 

\plot\ 

\bench\tools\ 

\fortran\pgms\ 

Your operating system manuals can tell you more about directories: how to create them, 
how to store files in them, how to specify a path, etc. 

filename is the main part of the file’s name. The filename can contain up to 8 characters. If more 

than 8 characters are used, only the first 8 are meaningful. For example, "COUNTRIES" 
and "COUNTRIE" are treated as the same name for a file. 

ext is an optional extension consisting of 1 to 3 characters (e.g., DOC). If an extension is 

specified, it is separated from the filename by a period. Extensions are normally used to 
indicate the type of information stored in the file. For example, a file extension of for is a 
common convention for FORTRAN programs. 

Note: The file specification is case insensitive in that upper and lower case letters can be used 
interchangeably. 


6.4.1 Special DOS Device Names 

Certain file names are reserved for devices. These special device names are: 
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CON the console (or terminal) 

AUX the serial port 

COM1 another name for the serial port 

COM2 a second serial port 

PRN the parallel printer 

LPT1 another name for the printer 

LPT2 a second parallel printer 

LPT3 a third parallel printer 

NUL nonexistent device 

When using one of these special device names, no other part of the file designation should be specified. A 
common mistake is to attempt to create a disk file such as PRN. DAT and attempt to write records to it. If 
you do not have a parallel printer attached to your PC, there may be a long delay before the output 
operation times out. 

6.4.2 Examples of FAT File Specifications 

The following are some examples of valid file specifications. 

1. The following file designation refers to a file in the current directory of the default disk. 

OPEN( UNIT=1, FILE='DATA.FIL' , ... ) 

2. The following file designation refers to a print file in the current directory of drive c :. ASA 
carriage control characters will be converted to the appropriate ASCII control codes. 

open ( unit= 2 , file=' c : report. 1st', 

CARRIAGECONTROL=' YES' , . . . ) 

3. The file specification below indicates that the file is to have fixed format records of length 80. 

open< unit=3, file=' final.tst', 

RECL=80, RECORDTYPE='FIXED', ... ) 

4. The file specification below indicates that the file is to have variable format records of maximum 
length 145. 

open< unit=4, file=' term, rpt', 

RECL=145, RECORDTYPE='VARIABLE', ... ) 

5. The file designation below indicates that the file resides in the records directory of drive b:. 

open< unit=5, file=' b: \ records \ customers . dat', ... ) 

Note that the trailing "S" in the file name will be ignored. Thus the following designation is 
equivalent. 

open< unit=5, file=' b:\records\customer. dat', ... ) 

6. The file designation below refers to the second serial port. 

OPEN( UNIT=6, FILE='COm2', ... ) 

7. The file designation below refers to a second parallel printer. 

OPEN( UNIT=7, file=' lpt2', ... ) 
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6.5 File Names in the High Performance File System 

OS/2, in addition to supporting the FAT file system, also supports the High Performance File System 
(HPFS). The rules for forming file names in the High Performance File System are different from those 
used to form file names in the FAT file system. In HPFS, file names and directory names can be up to 254 
characters in length. However, the complete path (including drive, directories and file name) cannot exceed 
259 characters. The period is a valid file name character and can appear in a file name or directory name as 
many times as required; HPFS file names do not require file extensions as in the FAT file system. 

However, many applications still use the period to denote file extensions. 

The HPFS preserves case in file names only in directory listings but ignores case in file searches and other 
system operations. For example, a directory cannot have more than one file whose names differ only in 
case. 


6.5.1 Special OS/2 Device Names 

The OS/2 operating system has reserved certain file names for character devices. These special device 
names are: 


CLOCK$ 

Clock 

COM1 

First serial port 

COM2 

Second serial port 

COM3 

Third serial port 

COM4 

Fourth serial port 

CON 

Console keyboard and screen 

KBD$ 

Keyboard 

LPT1 

First parallel printer 

LPT2 

Second parallel printer 

LPT3 

Third parallel printer 

MOUSE$ 

Mouse 

NUL 

Nonexistent (dummy) device 

POINTER$ 

Pointer draw device (mouse screen support) 

PRN 

The default printer, usually LPT1 

SCREEN$ 

Screen 


When using one of these special device names, no other part of the file designation should be specified. 


6.5.2 Examples of HPFS File Specifications 

The following are some examples of valid file specifications. 

1. The following file designation refers to a file in the current directory of the default disk. 

OPEN( UNIT=1, FILE='DATA.FIL' , ... ) 

2. The following file designation refers to a print file in the current directory of drive c :. ASA 
carriage control characters will be converted to the appropriate ASCII control codes. 

open ( unit =2 , file=' c : report . 1st' , 

CARRIAGECONTROL=' YES' , . . . ) 

3. The file specification below indicates that the file is to have fixed format records of length 80. 
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OPEN ( UNIT=3, FILE='final . tSt', 

RECL=80, RECORDTYPE='FIXED', ... ) 


4. The file specification below indicates that the file is to have variable format records of maximum 
length 145. 

open{ unit=4 , FiLE='term. rpt', 

RECL=145, RECORDTYPE='VARIABLE', ... ) 

5. The file designation below indicates that the file resides in the records directory of drive b :. 

open ( unit=5, FiLE='b:\records\customers .dat', ... ) 

Note that the trailing "S" in the file name is not ignored as is the case in a FAT fde system. 

6. The file designation below refers to the second serial port. 

OPEN( UNIT=6, FILE='COm2', ... ) 

7. The file designation below refers to a second parallel printer. 

OPEN( UNIT=7, FILE=' lpt2', ... ) 


6.6 Establishing Connections Between Units and Files 

Using Open Watcom F77, FORTRAN unit numbers may range from 0 to 999. Input/output statements 
such as READ and WRITE refer to files by a unit number. All input/output statements except OPEN, 
CLOSE, and INQUIRE must refer to a unit that is connected to a file. The Open Watcom F77 run-time 
system automatically establishes the connection of a unit to a file if no connection previously existed. Any 
connection between a unit and a file that is established before execution begins is called a preconnection. 

The Open Watcom F77 run-time system defines a preconnection of the unit designated by "*" to the 
standard input and output devices (by this we generally mean the keyboard and screen of the personal 
computer but input/output can be redirected from/to a file using the standard input/output redirectors "<" 
and ">" on the command line). This preconnection cannot be altered in any way. Unit is explicitly or 
implicitly referred to by the following input statements: 

READ, ... 

READ *, ... 

READ format-spec, .. . 

READ(*,...) ... 

READ(UNIT=*, . . . ) ... 

Unit is explicitly or implicitly referred to by the following output statements: 

PRINT, . . . 

PRINT *, ... 

PRINT format-spec, .. . 

WRITE(*,...) ... 

WRITE(UNIT=*,...) ... 

The Open Watcom F77 run-time system also defines a preconnection of unit 5 to the standard input device 
(by this we generally mean the keyboard of the personal computer but input can be redirected from a file 
using the standard input redirector "<" on the command line). 
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The Open Watcom F77 run-time system also defines a preconnection of unit 6 to the standard output device 
(by this we generally mean the screen of the personal computer but output can be redirected to a file using 
the standard output redirector ">" on the command line). 


For all other allowable units, a default preconnection between unit number "nnn" and the file FORnnn is 
assumed when no connection between a unit and a file has been established, nnn is a three-digit 
FORTRAN unit number. Unit 0 is "000", unit 1 is "001", unit 2 is "002", and so on. There is no file 
extension in this case. In other words, a default file name is constructed for any unit number for which no 
other connection has been established. Input/output statements of the following forms refer to these units. 


CLOSE(nnn, . . . ) 

CLOSE(UNIT=nnn, . . . ) 
BACKSPACE nnn 
BACKSPACE(nnn) 
BACKSPACE(UNIT=nnn) 
ENDFILE nnn 
ENDFILE(nnn) 

ENDFILE(UNIT=nnn) 
INQUIRE(nnn,...) 
INQUIRE(UNIT=nnn, . . . ) 


OPEN(nnn,...) 

OPEN(UNIT=nnn, . . . ) 
READ(nnn,...) 

READ(UNIT=nnn,...) 
REWIND nnn 
REWIND(nnn) 

REWIND(UNIT=nnn) 
WRITE(nnn, . . . ) ... 

WRITE(UNIT=nnn,...) 


Of course, it is unlikely that one would be satisfied with using such undistinguished file names such as 
forOOO, forOOl, and so on. Therefore, the Open Watcom F77 run-time system provides additional 
ways of establishing a preconnection between a FORTRAN UNIT and a file. 

The Open Watcom F77 run-time system supports the use of the "SET" command to establish a connection 
between a unit and a file. The "SET" command is used to create, modify and remove "Environment 
Variables". The "SET" command must be issued before running a program. The format for a 
preconnection using the "SET" command is: 

SET unit=file_ spec 

where description: 

unit is a FORTRAN unit number in the range 0 to 999. 

If this form of the "SET" command is used then FORTRAN unit number unit is 
preconnected to the specified file. FORTRAN input/output statements which refer to the 
unit number will access the records in the specified file. 

file_spec is the file specification of the preconnected file. 

Here are some sample "SET" commands. 

Example: 

C>set l=input.dat 

C>set 2=output.dat 

C>set 3=d:\database\customer.fil 


The above example establishes the following preconnections: 

1. Between unit 1 and the file input. dat which resides (or will reside) in the current directory. 

2. Between unit 2 and the file output. dat which resides (or will reside) in the current directory. 
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3. Between unit 3 and the file d: \database\customer. f il which resides (or will reside) in 
another disk and directory. 

Any FORTRAN input/output statements which refer to units 1, 2 or 3 will act upon one of these 3 data 
files. 

Notes: 

1. The "SET" command must be issued before running the program. 

2. No spaces should be placed before or after the "=" in the "SET" command. The following two 
examples are quite distinct from each other: 

Example: 

C>set 55=testbed.dat 
C>set 55 = testbed.dat 

To verify this, simply enter the two commands and then enter the "SET" command again with no 
arguments. The current environment strings will be displayed. You should find two entries, one 
for "55" and one for "55 ". 

3. Since the number in front of the "=" is simply a character string, you should not specify any 
leading zeroes either. 

Example: 

C>set 01=input.dat 
C>set l=input.dat 

In this case, we again have two distinct environment variables. The variable "01" will be 
ignored by the Open Watcom F77 run-time system. 

4. An environment variable will remain in effect until you explicitly remove it or you turn off the 
personal computer. To discontinue the preconnection between a unit number and a file, you 
must issue a "SET" command of the following form. 

C>set <unit>= 

In the above command, <unit> is the unit number for which the preconnection is to be 
discontinued. 

By omitting the character string after the "=", the environment variable will be removed. For 
example, to remove the environment variable "01" from the list, reenter the "SET" command 
specifying everything up to and including the "=" character. 

Example: 

C>set 01= 

5. Any time you wish to see the current list of environment strings, simply enter the "SET" 
command with no arguments. 
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Example: 

C>set 

PROMPT=$d $t $p$_ $n$g 
COMSPEC=d:\dos\command.com 

PATH=G:\;E:\CMDS;C:\WATCOM\BIN;D:\DOS;D:\BIN 
LIB=c:\watcom\lib286\dos 
l=input.dat 
2=output.dat 

3=d:\database\customer.fil 

6. An alternative to preconnecting files is provided by the FORTRAN OPEN statement which 
allows files to be connected at execution time. 

7. The preconnection of units 5 and 6 may be overridden using preconnection specifications or the 
FORTRAN OPEN statement. The precedence of a connection between a unit number and a file 
is as follows: 

Precedence: User option: 

Lowest Preconnection Specifications 

Highest OPEN statement 

In other words, the OPEN statement overrides a preconnection. 


6.7 A Preconnection Tutorial 


In this section, we will look at some examples of how to establish the link between a file and a FORTRAN 
unit. 

Exhibit 1: 


Consider the following example which reads pairs of numbers from a file and writes out the numbers and 
their sum. 

* File 'iodemo.for' 

10 READ( 1, *, END=99 ) XI, X2 

WRITE( 6, 20 ) XI, X2, XI + X2 
GO TO 10 

20 FORMAT( 3F6.2 ) 

99 END 

The FORTRAN READ statement will read records from a file connected to unit 1. The FORTRAN 
WRITE statement will write records to a file connected to unit 6. As we described in the previous section, 
unit 6 is preconnected by the Open Watcom F77 run-time system to the screen. 


What file will be read when the READ statement refers to unit 1? By default, we know that it will read a 
file called for001. However, suppose the data was actually stored in the file called numbers . dat. We 
can direct the program to read the data in this file by using a "SET" command before running the program. 
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Example: 


C>set 1= 

numbers. 

. dat 

Oiodemo 




1 

.40 

2. 

.50 

3. 

. 90 

3 

. 90 

8. 

.70 

12. 

. 60 

1 

. 10 

9. 

. 90 

11. 

. 00 

8 

.30 

7 . 

. 10 

15. 

.40 

8 

.20 

3. 

.50 

11. 

.70 


Exhibit 2: 


Suppose that we now wish to write the output from the above program to a disk file instead of the screen. 
We can do this without modifying the program. Since we know that the WRITE statement refers to unit 6, 
we can alter the default preconnection of unit 6 to the screen by issuing another "SET" command. 


Example: 

C>set 6=numbers.rpt 
Oiodemo 

C>type numbers.rpt 
1.40 2.50 3.90 

3.90 8.70 12.60 

1.10 9.90 11.00 

8.30 7.10 15.40 

8.20 3.50 11.70 

Now any time a program writes or prints to unit 6, the output will be written to the disk file 
numbers . rpt. If you are going to run other programs, it would be wise to remove the connection 
between unit 6 and this file so that it is not accidentally overwritten. This can be done by issuing the 
following command. 


Example: 

C>set 6= 


You should also do the same for unit 1. 


Exhibit 3: 


Must we always use "SET" commands to establish the connection between a unit and a file? Suppose that 
you want to run the program quite often and that you do not want to issue "SET" commands every time. 

We can do this by modifying the program to include FORTRAN OPEN statements. 

* File 'iodemo.for' 

OPEN( 1, FILE='NUMBERS.DAT' ) 

OPEN( 6, FILE='NUMBERS.RPT' ) 

10 READ( 1, *, END=99 ) XI, X2 

WRITE( 6, 20 ) XI, X2, XI + X2 
GO TO 10 

20 FORMAT( 3F6.2 ) 

99 END 

This is an example of a connection that is established at execution time. The connection that is established 
by the OPEN statement overrides any preconnection that we might have established using a "SET" 
command. We say that the OPEN statement has a higher precedence. However, even the OPEN statement 
does not have the final word on which files will be accessed. You may wish to read the next section on the 
Open Watcom F77 run-time system logical file name support to find out why this is so. 
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6.8 Logical File Name Support 

The Open Watcom F77 run-time system supports logical or symbolic file names using the "SET" 
command. The "SET" command may be used to define a logical file name and its corresponding actual file 
name. The format for defining a logical file name is as follows: 

SET name=file_ spec 

where description: 

name is any character string. The letters in "name" may be specified in upper or lower case. 

Lower case letters are treated as if they had been specified in upper case. Thus 
"SYSINPUT" and "sysinput" are equivalent. Note, however, that blank characters must not 
be specified before and after the "=" character. 

file_spec is the file specification of logical file. 


Notes and Examples: 


1. A logical file name may be used in the FILE= specifier of the FORTRAN OPEN and INQUIRE 
statements. 


Example: 

* File 'iodemo.for' 

OPEN( 1, FILE='SYSINPUT' ) 

10 READ( 1, *, END=99 ) XI, X2 

WRITE( 6, 20 ) XI, X2, XI + X2 
GO TO 10 

20 FORMAT( 3F6.2 ) 

99 END 


In the following example, we define the logical file name "SYSINPUT" to correspond to the file 
numbers.dat. 


Example: 

C>set sysinput=numbers.dat 


Oiodemo 





1 

.40 

2. 

.50 

3. 

. 90 

3 

. 90 

8. 

.70 

12. 

. 60 

1 

. 10 

9. 

. 90 

11. 

. 00 

8 

.30 

7 . 

. 10 

15. 

.40 

8 

.20 

3. 

.50 

11. 

.70 


2. If the name in a FILE= specifier is not included in one of the environment variable names then it 
is assumed to be the actual name of a file. 
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Example: 

OPEN( 2, FILE='SYSOUT' ) 

3. The logical file name feature can also be used to provide additional information regarding the 
file name at execution time. 


Example: 

* File 'iodemo.for' 

OPEN( 1, FILE='numbers.dat' ) 
10 READ( 1, *, END=99 ) XI, X2 

WRITE( 6, 20 ) XI, X2, XI + X2 
GO TO 10 

20 FORMAT( 3F6.2 ) 

99 END 


In the following example, the actual location (and name) of the file numbers . dat is described 
through the use of an environment variable. 


Example: 

C>set numbers.dat=b:\data\input.dat 
Oiodemo 

As you can see, a logical file name can resemble an actual file name. 

Of course, the entire file name could have been specified in the FORTRAN program. 


Example: 

OPEN( 1, FILE='b:\data\input.dat' ) 

4. Only one level of lookup is performed. 


Example: 


★ 

File ' iodemo 

. for' 



OPEN( 1, 

FILE=' 

sysinput' ) 

10 

READ ( 1, 

*, END 

=99 ) XI, X2 


WRITE ( 6 
GO TO 10 

, 20 ) 

XI, X2, XI + 

20 

FORMAT( 

3F6.2 ) 


99 

END 




This is illustrated by the following commands. 


Example: 

C>set sysinput=datafile 
C>set datafile=input.dat 
Oiodemo 

In the above example, unit 1 is connected to the file datafile and not the file input. dat. 

5. Logical file names can be used to direct output normally intended for one device to another 
device. Consider the following examples. 
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Example: 

C>set lptl=lpt2 

If the FORTRAN program specifies the name "LPT1" in an OPEN or INQUIRE statement, the 
Open Watcom F77 run-time system will map this name to "LPT2". In an INQUIRE statement, 
the NAME= specifier will return the name "LPT2". 

6. As we mentioned earlier, the case of the name does not matter. Upper or lower case can be used 
interchangeably. 

Example: 

C>set sysinput=b:\data\input.dat 
C>set SYSINPUT=b:\data\input.dat 

7. No spaces should be placed before or after the "=" in the "SET" command. The following two 
examples are considered quite distinct from each other: 

Example: 

C>set sysinput=testbed.dat 
C>set sysinput = testbed.dat 

This example will define two variables, "SYSINPUT" and "SYSINPUT ", 

8. An environment variable will remain in effect until you explicitly remove it or you turn off the 
personal computer. To remove an environment variable from the list, reenter the "SET" 
command specifying everything up to and including the "=" character. For example, to remove 
the definition for "SYSINPUT", the following command can be issued. 

Example: 

C>set sysinput= 

9. Any time you wish to see the current list of environment strings, simply enter the "SET" 
command with no arguments. 

Example: 

C>set 

PROMPT=$d $t $p$_ $n$g 
COMSPEC=d:\dos\command.com 

PATH=G:\;E:\CMDS;C:\WATCOM\BIN;D:\DOS;D:\BIN 
LIB=c:\watcom\lib286\dos 
l=input.dat 
2=output.dat 

3=d:\database\customer.fil 
SYSINPUT=b:\data\input.dat 
LPTl=lpt2 


6.9 Terminal or Console Device Support 

Input can come from the console or output can be written to the console by using the console device name 
con as the file name. The console can be specified in a "SET" command or through the FILE= specifier of 
the FORTRAN OPEN statement. 

The default action for any file is to open the file for both read and write access (i.e., 

ACTION=’READ WRITE'). Under Win32, there is a problem accessing the console device con for both 
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read and write access. This problem is overcome by using the ACTION= specifier in the OPEN statement. 
The ACTION= specifier indicates the way in which the file is initially accessed. The values allowed for the 
ACTION = specifier are the following. 

’READ’ the file is opened for read-only access 

’WRITE’ the file is opened for write-only access 

’READWRITE’ the file is opened for both read and write access 

To open the console device under Win32, you must specify whether you are going to "READ" or "WRITE" 
to the file. If you wish to do both reading and writing, then you must use two separate units. 

Example: 

OPEN( UNIT=1, FILE='CON', ACTION='READ') 

OPEN( UNIT=2, FILE='CON', ACTION='WRITE' ) 

The console can be treated as a carriage control device. This is requested by using the 
CARRIAGECONTROL=' YES' specifier of the FORTRAN OPEN statement. 

Example: 

OPEN( UNIT=1, FILE=' con' , CARRIAGECONTROL='YES' ) 

Carriage control handling is described in the section entitled "Print File Attributes" on page 43. 

The console is not capable of supporting carriage control in a fashion identical to a printer. For example, 
overprinting of records on the console is destructive in that the previous characters are erased. 

End of file is signalled by first pressing the Ctrl/Z key combination and then the line entering key. End of 
file may be handled by using the END= specification of the FORTRAN READ statement. 

Example: 

READ ( UNIT=*, FMT=*, END=100 ) X, Y 


100 code to handle "End of File" 

End of file may also be handled by using the IOSTAT= specifier of the FORTRAN READ statement. 
Example: 

READ( UNIT=*, FMT=*, IOSTAT=IOS ) X, Y 

IF( IOS .NE. 0 )THEN 

code to handle "End of File" 

END IF 


6.10 Printer Device Support 

Output can be written to a printer by using a printer device name as the file name. A printer can be 
specified in a "SET" command or through the FILE= specifier of the FORTRAN OPEN statement. 
Several device names may be used: 
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prn or lptl 

lpt2 

lpt3 

The printer can be treated as a carriage control device. This is requested by using the 
CARRIAGECONTROL=' YES' specifier of the FORTRAN OPEN statement. 

Example: 

OPEN( UNIT=1, FILE='prn', CARRIAGECONTROL='YES' ) 

Carriage control handling is described in the section entitled "Print File Attributes" on page 43. 


6.11 Serial Device Support 

Output can be written to a serial port by using a serial device name as the file name. A serial device can be 
specified in a "SET" command or through the FILE= specifier of the FORTRAN OPEN statement. Three 
device names may be used: 

aux or coml 
com2 

The serial device can be treated as a carriage control device. This is requested by using the 
CARRIAGECONTROL=' YES' specifier of the FORTRAN OPEN statement. 

Example: 

OPEN( UNIT=1, FILE='coml', CARRIAGECONTROL='YES' ) 

Carriage control handling is described in the section entitled "Print File Attributes" on page 43. 

To set serial characteristics such as speed, parity, and word length, the "MODE" command may be used. 
Example: 

C>mode coml:9600,n, 8,1 

The above example sets serial port 1 to a speed of 9600 BAUD with no parity, a word length of 8 and 1 
stop bit. 

6.12 File Handling Defaults 

The following defaults apply to file specifications: 

• The following table indicates the default record type for the allowable access methods and forms. 


File Form 

Access Formatted Unformatted 



+-- 

— 

—+- 

— 

-+ 

Sequential 

+-- 

Text 

—+- 

Variable 

-+ 

Direct 

+-- 

Text 

—+- 

Fixed 

-+ 
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Unless the record type of the file does not correspond to the default assumed by Open Watcom F77, 
the record type attribute should not be specified. 

• Unless otherwise stated, the default record length for a file is 1024 characters. When access is 
"direct", the record length must be specified in the RECL= specifier of the FORTRAN OPEN 
statement. The record length may also be specified when the access is "sequential". This should be 
done whenever access is "sequential" and the maximum record length is greater than the default. 

• The default record access is "sequential". 

• When reading from or writing to a unit for which no preconnection has been specified or no 
"FILE=" form of the FORTRAN OPEN statement has been executed, the default file name takes the 
form: 


FORnnn 

nnn is a three-digit FORTRAN unit number. Unit 0 is "000", unit 1 is "001", unit 2 is "002", and so 
on. There is no file extension in this case. 

• If the connection between a unit number and a file is discontinued through use of the FORTRAN 
CLOSE statement, the same rule for constructing a file name will apply on the next attempt to read 
from or write to the specified unit. 
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7 The Open Watcom F77 Subprogram Library 


Open Watcom FORTRAN 77 includes additional FORTRAN subprograms which can be called from 
programs compiled by Open Watcom F77. The following sections describe these subprograms. 


7.1 Subroutine FEXIT 


The subroutine FEXIT allows an application to terminate execution with a return code. It requires one 
argument of type INTEGER that represents the value to be returned to the system. 


Example: 

INCLUDE 'FSUBLIB.FI' 

CALL FEXIT( -1 ) 

END 

Notes: 

1. The FORTRAN include file f sublib. fi, located in the \watcom\src\fortran 
directory, contains typing and calling information for this subprogram. The 
\watcom\src\fortran directory should be included in the FINCLUDE environment 
variable so that the compiler can locate the include file. 


7.2 INTEGER Function FGETCMD 


The INTEGER function FGETCMD allows an application to obtain the command line from within an 
executing program. 

The function FGETCMD requires one argument of type CHARACTER and returns the length of the 
command line. 


Example: 

INCLUDE 'FSUBLIB.FI' 

INTEGER CMDLEN 
CHARACTER*128 CMDLIN 

CMDLEN = FGETCMD( CMDLIN ) 

PRINT *, 'Command length = ', CMDLEN 
PRINT *, 'Command line = ' , CMDLIN 
END 

Notes: 

1. The FORTRAN include file fsublib . fi, located in the \watcom\src\fortran 
directory, contains typing and calling information for this subprogram. The 
\watcom\src\fortran directory should be included in the FINCLUDE environment 
variable so that the compiler can locate the include file. 
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2. If the argument to FGETCMD is not long enough then only the first part of the command line is 
returned. 


7.3 INTEGER Function FGETENV 


The INTEGER function FGETENV allows an application to obtain the value of an environment string from 
within an executing program. 

The function FGETENV requires two arguments of type CHARACTER. The first argument is the character 
string to look for. FGETENV places the associated environment string value in the second argument and 
returns the length of the environment string. If no such string is defined, the length returned is zero. 


Example: 

INCLUDE 'FSUBLIB.FI' 

INTEGER STRLEN 
CHARACTER*80 STRVAL 

STRLEN = FGETENV( 'PATH', STRVAL ) 

PRINT *, 'Environment string length = ', STRLEN 
PRINT *, 'Environment string value = ', STRVAL 
END 

Notes: 

1. The FORTRAN include file f sublib . fi, located in the \watcom\src\fortran 
directory, contains typing and calling information for this subprogram. The 
\watcom\src\fortran directory should be included in the FINCLUDE environment 
variable so that the compiler can locate the include file. 

2. If the second argument to FGETENV is not long enough then only the first part of the value is 
returned. 


7.4 INTEGER Function FILESIZE 


The INTEGER function FILESIZE allows an application to determine the size of a file connected to a 
specified unit. 


The function FILESIZE requires one argument of type INTEGER, the unit number and returns the size, in 
bytes, of the file. If no file is connected to the specified unit, a value of -1 is returned. 

Example: 

INCLUDE 'FSUBLIB.FI' 

OPEN( UNIT=1, FILE='sample.fil' ) 

PRINT *, FILESIZE( 1 ) 

END 
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Notes: 

1. The FORTRAN include file f sublib . f i, located in the \watcom\src\fortran 
directory, contains typing and calling information for this subprogram. The 
\watcom\src\fortran directory should be included in the FINCLUDE environment 
variable so that the compiler can locate the include file. 


7.5 Subroutine FINTR 


The subroutine FINTR allows the user to execute any software interrupt from a FORTRAN 77 program. 


Note: This subroutine is only supported by the DOS and Windows libraries. 


The subroutine FINTR requires two arguments. 

1. The first argument is an interrupt number. The subroutine FINTR will generate the software 
interrupt given by the first argument. The type of this argument must be INTEGER. 

2. The second argument is an INTEGER array of ten elements. 

When FINTR is called, the array contains the values to be assigned to the registers prior to issuing the 
software interrupt. When control is returned from FINTR, it contains the values of the registers after the 
software interrupt has completed. The registers are mapped onto the array REGS as follows. 


31 0 


REGS 

(1) 

EAX 

REGS 

(2) 

EBX 

REGS 

(3) 

ECX 

REGS 

(4) 

EDX 

REGS 

(5) 

EBP 

REGS 

(6) 

ESI 

REGS 

(7) 

EDI 

REGS 

(8) 

FS 

DS 

REGS 

(9) 

GS 

ES 

REGS 

(10) 

eflags 


For 16-bit systems (e.g., 8088, 8086, 186, 286), only the low-order 16 bits of each register contain 
meaningful results. 


31 0 


REGS 

(1) 

AX 

REGS 

(2) 

BX 

REGS 

(3) 

CX 

REGS 

(4) 

DX 

REGS 

(5) 

BP 

REGS 

(6) 

SI 

REGS 

(7) 

DI 

REGS 

(8) 

DS 

REGS 

(9) 

ES 

REGS 

(10) 

flags 


The file dos . f i, located in the \WATCOM\src\fortran\dos directory, defines a set of equivalences 
for ease of use. The contents of this file are reproduced below. 
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* Define registers: These correspond to the element of an 

* array which is to contain the values of the registers. 

integer*4 regd(10), regs(10) 
integer*2 regw(2*10) 
integer*! regb(4*4) 


integer*4 EAX,EBX,ECX,EDX,EBP,EDI,ESI,EFLAGS 
integer*2 AX,BX,CX,DX,BP,DI,SI,DS,ES,FS,GS,FLAGS 
integer*! AH,AL,BH,BL,CH,CL,DH,DL 


equivalence (regd,regs),(regd,regw),(regd,regb), 


1(EAX,regd(1)), 
2(EBP,regd(5)), 

3 (AX, regw (1) ) , 

4 (BP, regw (9) ) , 

5(FS, regw(16)), 

6 (AL, regb (1) ) , 

7 (CL, regb (9) ) , 


(EBX,regd (2)), 
(EDI,regd(6)), 
(BX,regw (3)) , 
(DI, regw (11) ) , 
(ES, regw(17)), 
(AH, regb (2) ) , 
(CH,regb(10)), 


(ECX,regd(3)), 
(ESI,regd(7)), 
(CX,regw (5)), 
(SI,regw(13)), 
(GS,regw (18)), 
(BL,regb (5)) , 
(DL,regb(13)), 


(EDX,regd(4)), 
(EFLAGS,regd(10)), 
(DX, regw (7) ) , 

(DS, regw(15)), 
(FLAGS,regw(19)), 
(BH, regb (6) ) , 

(DH,regb(14)) 


The following is extracted from the "CALENDAR" program. It demonstrates the use of the FINTR 
subroutine. 


subroutine ClearScreen() 

*$noextensions 

implicit none 

include 'dos.fi' 

* Define BIOS functions. 

integer VIDE0_ CALL, SCROLL 
parameter (VIDE0_ CALL=16 

DS = ES = FS = GS = 0 

AH = SCR0LL_ UP 

AL = 0 

CX = 0 

DX = 24*256 + 80 
BH = 7 

call f intr ( VIDEO_ CALL 
end 


UP 

SCROLL_ UP=6) 


scroll up 

blank entire window 
set row,column of upper left 
set row,column of lower right 
attribute "white on black" 
regs ) 


7.6 INTEGER Function FLUSHUNIT 


The INTEGER function FLUSHUNIT flushes the internal input/output buffer for a specified unit. Each 
file, except special devices such as con, has an internal buffer. Buffered input/output is much more 
efficient since it reduces the number of system calls which are usually quite expensive. For example, many 
WRITE operations may be required before filling the internal file buffer and data is physically transferred 
to the file. 

This function is particularly useful for applications that call non-FORTRAN subroutines or functions that 
wish to perform input/output to a FORTRAN file. 

The function FLUSHUNIT requires one argument, the unit number, of type INTEGER. It returns an 
INTEGER value representing the return code of the input/output operation. A return value of 0 indicates 
success; otherwise an error occurred. 

The following example will flush the contents of the internal input/output buffer for unit 7. 
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Example: 

INCLUDE 'FSUBLIB. FI' 

INTEGER ISTAT 

ISTAT = FLUSHUNIT( 7 ) 

IF( ISTAT .NE. 0 )THEN 

PRINT *, 'Error in FLUSHUNIT' 

END IF 

END 

Notes: 

1. The FORTRAN include file f sublib. fi, located in the \watcom\src\fortran 
directory, contains typing and calling information for this subprogram. The 
\watcom\src\fortran directory should be included in the FINCLUDE environment 
variable so that the compiler can locate the include file. 


7.7 INTEGER Function FNEXTRECL 


The INTEGER function FNEXTRECL reports the record length of the next unformatted record to be read 
sequentially from the specified unit. 

The function FNEXTRECL requires one argument, the unit number, of type INTEGER. It returns an 
INTEGER value representing the size of the next record to be read. 

The following example creates an unformatted file and then reads the records in the file sequentially. 
Example: 
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INCLUDE 'FSUBLIB.FI' 

CHARACTER*80 INPUT 

OPEN(UNIT=2, FILE='UNFORM.TXT' , FORM=' UNFORMATTED' , 

& ACCESS='SEQUENTIAL' ) 

WRITE( UNIT=2 ) 'A somewhat longish first record' 

WRITE( UNIT=2 ) 'A short second record' 

WRITE( UNIT=2 ) 'A very, very much longer third record' 
CLOSE ( UNIT=2 ) 

OPEN(UNIT=2, FILE='UNFORM.TXT', FORM='UNFORMATTED', 

& ACCESS='SEQUENTIAL' ) 

I = FNEXTRECL( 2 ) 

PRINT *, 'Record length=', I 
READ( UNIT=2 ) INPUT(1:1) 

PRINT *, INPUT(1:1) 

I = FNEXTRECL( 2 ) 

PRINT *, 'Record length=', I 
READ( UNIT=2 ) INPUT(1:1) 

PRINT *, INPUT(1:1) 

I = FNEXTRECL( 2 ) 

PRINT *, 'Record length=', I 
READ( UNIT=2 ) INPUT(1:1) 

PRINT *, INPUT(1:1) 

CLOSE ( UNIT=2 ) 

END 


Notes: 

1. The FORTRAN include file f sublib . fi, located in the \watcom\src\fortran 
directory, contains typing and calling information for this subprogram. The 
\watcom\src\fortran directory should be included in the FINCLUDE environment 
variable so that the compiler can locate the include file. 


7.8 INTEGER Function FSIGNAL 


The INTEGER function FSIGNAL allows your application to respond to certain events that occur during 
execution. 

Event Meaning 

SIGBREAK an interactive attention (Ctrl/Break on keyboard) is signalled 

SIGFPE an erroneous floating-point operation occurs (such as division by zero, overflow and 

underflow) 

SIGILL illegal instruction encountered 

SIGINT an interactive attention (Ctrl/C on keyboard) is signalled 
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SIGSEGV an illegal memory reference is detected 

SIGTERM a termination request is sent to the program 

SIGIDIVZ integer division by zero 

SIGIOVFL integer overflow 

The function FSIGNAL requires two arguments. The first argument is an INTEGER argument and must be 
one of the events described above. The second argument, called the handler, is one of the following. 


1. a subprogram that is called when the event occurs 

2. the value SIG_DFL, causing the default action to be taken when the event occurs 

3. the value SIG_IGN, causing the event to be ignored 

FSIGNAL returns SIG_ERR if the request could not be processed, or the previous event handler. 


Example: 

INCLUDE 'FSIGNAL.FI' 

EXTERNAL BREAK_ HANDLER 
LOGICAL BREAK_ FLAG 
COMMON BREAK_ FLAG 
BREAK_ FLAG = .FALSE. 

CALL FSIGNAL ( SIGBREAK, BREAK_ HANDLER ) 

WHILE ( .NOT. VOLATILE ( BREAK_ FLAG ) ) CONTINUE 

PRINT *, 'Program Interrupted' 

END 

SUBROUTINE BREAK_ HANDLER () 

LOGICAL BREAK_ FLAG 
COMMON BREAK_ FLAG 
BREAK_ FLAG = . TRUE . 

END 

Notes: 

1. The FORTRAN include file fsignal.fi contains typing and calling information for 
FSIGNAL and should be included when using this function. This file is located in the 
\watcom\src\fortran directory. The \watcom\src\fortran directory should be 
included in the FINCLUDE environment variable so that the compiler can locate the include 
file. 

2. The intrinsic function VOLATILE is used to indicate that the reference to the variable 
break_ flag is volatile. A volatile reference prevents the compiler from caching a variable in 
a register. In this case, we want to retrieve the value of break_ flag from memory each time 
the loop is iterated. 
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7.9 INTEGER Function FSPAWN 


The INTEGER function FSPAWN allows an application to run another program as a subprocess. When the 
program completes, execution is returned to the invoking application. There must be enough available free 
memory to start the subprocess. 

The function FSPAWN requires two arguments of type CHARACTER. The first argument is a character 
string representing the name of the program to be run. The string must end in a NULL character (i.e., a 
character with the binary value 0). 

The second argument is a character string argument list to be passed to the program. The first character of 
the second argument must contain, in binary, the length of the remainder of the argument list. For example, 
if the argument is the string "HELLO" then the first character would be CHAR(5) and the remaining 
characters would be "HELLO" (see the example below). 

FSPAWN returns an INTEGER value representing the status of subprocess execution. If the value is 
negative then the program could not be run. If the value is positive then the value represents the program’s 
return code. 


Example: 

INCLUDE 'FSUBLIB.FI' 

INTEGER CMDLEN, STATUS 
CHARACTER CMD*128, CMDLIN*128 

* COMSPEC will tell us where DOS 'COMMAND.COM' is hiding 
CMDLEN = FGETENV( 'COMSPEC', CMD ) 

CMD(CMDLEN+1:CMDLEN+1) = CHAR( 0 ) 

CMDLIN = '/c dir *.for' 

CMDLIN(13:13) = CHAR( 0 ) 

STATUS = FSPAWN( CMD, CMDLIN ) 

PRINT *, 'Program status = ', STATUS 
END 


Notes: 

1. The FORTRAN include file f sublib . f i, located in the \watcom\src\fortran 
directory, contains typing and calling information for this subprogram. The 
\watcom\src\fortran directory should be included in the FINCLUDE environment 
variable so that the compiler can locate the include file. 

2. The INTEGER function FSYSTEM, which is described in a later section, implements a more 
general form of the example given above. We recommend its use. 


7.10 INTEGER Function FSYSTEM 


The INTEGER function FSYSTEM allows an application to run another program or execute an operating 
system command. 

The function FSYSTEM requires one argument of type CHARACTER. This argument represents a 
operating system command or a program name together with any arguments. FSYSTEM returns an 
INTEGER value representing the status of subprocess execution. If the value is negative, the operating 
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system command interpreter or shell could not be run (an attempt is made to invoke the system command 
interpreter to run the program). If the value is positive, the value represents the program’s return code. 

In the following example, a "COPY" command is executed and then a hypothetical sorting program is run. 


Example: 

INCLUDE 'FSUBLIB.FI' 

INTEGER STATUS 

STATUS = FSYSTEM( 'COPY *.FOR \BACKUP\FOR\SRC' ) 

PRINT *, 'Status of COPY command = ', STATUS 

STATUS = FSYSTEM( 'SORTFILE/IN=INP.DAT/OUT=OUT.DAT' ) 

PRINT *, 'Status of SORT program = ', STATUS 
END 

Notes: 

1. The FORTRAN include file f sublib . f i, located in the \watcom\src\fortran 
directory, contains typing and calling information for this subprogram. The 
\watcom\src\fortran directory should be included in the FINCLUDE environment 
variable so that the compiler can locate the include file. 


7.11 Subroutine FTRACEBACK 


The subroutine FTRACEBACK allows your application to generate a run-time traceback. The application 
must be compiled with the "DEBUG" or "TRACE" option. It is useful when you wish to disclose a 
problem in an application and provide an informative report of where the problem occurred in the 
application. 

The FTRACEBACK subroutine requires no arguments. The FTRACEBACK subroutine does not terminate 
program execution. 


Example: 

SUBROUTINE READREC( UN ) 

INCLUDE 'FSUBLIB.FI' 

INTEGER UN 
INTEGER RLEN 
CHARACTER*35 INPUT 

RLEN = FNEXTRECL( UN ) 

IF( RLEN .GT. 35 )THEN 

PRINT *, 'Error: Record too long', RLEN 
CALL FTRACEBACK 
STOP 
ELSE 

PRINT *, 'Record length=', RLEN 
READ( UNIT=UN ) INPUT(1:RLEN) 

PRINT *, INPUT(1:RLEN) 

END IF 
END 
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Notes: 

1. The FORTRAN include file f sublib . fi, located in the \watcom\src\fortran 
directory, contains typing and calling information for this subprogram. The 
\watcom\src\fortran directory should be included in the FINCLUDE environment 
variable so that the compiler can locate the include file. 


7.12 Subroutine GETDAT 


The subroutine GETDAT allows an application to obtain the current date. 

The subroutine GETDAT has three arguments of type INTEGER*2 . When control is returned from 
GETDAT, they contain the year, month and day of the current date. 

The following program prints the current date in the form "YY-MM-DD". 


Example: 

INCLUDE 'FSUBLIB.FI' 

INTEGER*2 YEAR, MONTH, DAY 
CALL GETDAT( YEAR, MONTH, DAY ) 

PRINT 100, YEAR, MONTH, DAY 
100 FORMAT( IX, 14, 12.2, 12.2 ) 

END 


Notes: 

1. The FORTRAN include file fsublib . fi, located in the \watcom\src\fortran 
directory, contains typing and calling information for this subprogram. The 
\watcom\src\fortran directory should be included in the FINCLUDE environment 
variable so that the compiler can locate the include file. 

2. The arguments to GETDAT must be of type INTEGER*2 in order to obtain correct results. 


7.13 Subroutine GETTIM 


The subroutine GETTIM allows an application to obtain the current time. 

The subroutine GETTIM has four arguments of type INTEGER*2 . When control is returned from 
GETTIM, they contain the hours, minutes, seconds, and hundredths of seconds of the current time. 

The following program prints the current time in the form "HH:MM:SS.TT". 


Example: 

INCLUDE 'FSUBLIB.FI' 

INTEGER*2 HRS, MINS, SECS, HSECS 
CALL GETTIM( HRS, MINS, SECS, HSECS ) 

PRINT 100, HRS, MINS, SECS, HSECS 
100 FORMAT( IX, 12.2, 12.2, 12.2, '.', 12.2 ) 

END 
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Notes: 

1. The FORTRAN include file f sublib . f i, located in the \watcom\src\fortran 
directory, contains typing and calling information for this subprogram. The 
\watcom\src\fortran directory should be included in the FINCLUDE environment 
variable so that the compiler can locate the include file. 

2. The arguments to GETTIM must be of type INTEGER*2 in order to obtain correct results. 


7.14 INTEGER Function GROWHANDLES 


The INTEGER function GROWHANDLES allows an application to increase the maximum number of files 
that can be opened. It requires one argument of type INTEGER representing the maximum number of files 
that can be opened and returns an INTEGER value representing the actual limit. The actual limit may 
differ from the specified limit. For example, memory constraints or system parameters may be such that 
the request cannot be satisfied. 

The following example attempts to increase the limit on the number of open files to sixty-four. 

Example: 

INCLUDE 'FSUBLIB.FI' 

INTEGER NEW_ LIMIT 

NEW_ LIMIT = GROWHANDLES( 64 ) 

END 


Notes: 

1. The FORTRAN include file f sublib . fi, located in the \watcom\src\fortran 
directory, contains typing and calling information for this subprogram. The 
\watcom\src\fortran directory should be included in the FINCLUDE environment 
variable so that the compiler can locate the include file. 


7.15 Functions IARGC and IGETARG 


The function IARGC allows an application to determine the number of arguments (including the program 
name) used to invoke the program. The function IGETARG can be used to retrieve an argument. 

Arguments supplied to a program are assigned indices. Argument zero is the program name, argument one 
is the first argument, etc. The function IGETARG requires two arguments. The first argument is the index 
of the argument to retrieve and is of type INTEGER. The second argument is of type CHARACTER and is 
used to return the argument. The size of the argument (number of characters) is returned. 
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Example: 

INCLUDE 'FSUBLIB.FI' 

CHARACTER*128 ARG 
INTEGER ARGC, ARGLEN 

ARGC = IARGC() 

ARGLEN = IGETARG( 0, ARG ) 

PRINT *, 'Program name is ARG(1:ARGLEN) 

DO I = 1, ARGC - 1 

ARGLEN = IGETARG( I, ARG ) 

PRINT '(A, 12, 2A)', 'Argument I, ' is ' , 

1 ARG(1:ARGLEN) 

END DO 
END 

Notes: 

1. The FORTRAN include file f sublib. fi, located in the \watcom\src\fortran 
directory, contains typing and calling information for this subprogram. The 
\watcom\src\fortran directory should be included in the FINCLUDE environment 
variable so that the compiler can locate the include file. 


7.16 Math Error Functions 


Math error functions are called when an error is detected in a math library function. For example, if the 
second argument to the AMOD intrinsic function is zero, a math error function will be called. A number of 
math error functions are defined in the FORTRAN run-time libraries and perform default actions when an 
error is detected. These actions typically produce an error message to the screen. 

It is possible to replace the FORTRAN run-time library version of the math error functions with your own 
versions. The file _ matherr . for located in the\watcom\src\fortran directory can be used as a 
template for defining your own math error functions. The following functions represent the set of math 
error functions. 

1. The function_imath2err is called for math functions of type INTEGER that take two 

arguments of type INTEGER. The first argument represents the error information and is an 
argument of type INTEGER that is passed by value. The second argument is a pointer to the 
first argument passed to the math function and the third argument is a pointer to the second 
argument passed to the math function. The error function returns a value that is then used as the 
return value for the math function. 

2. The function_amathlerr is called for math functions of type REAL that take one argument 

of type REAL. The first argument represents the error information and is an argument of type 
INTEGER that is passed by value. The second argument is a pointer to the argument passed to 
the math function. The error function returns a value that is then used as the return value for the 
math function. 

3. The function_amath2err is called for math functions of type REAL that take two arguments 

of type REAL. The first argument represents the error information and is an argument of type 
INTEGER that is passed by value. The second argument is a pointer to the first argument passed 
to the math function and the third argument is a pointer to the second argument passed to the 
math function. The error function returns a value that is then used as the return value for the 
math function. 

4. The function_mathlerr is called for math functions of type DOUBLE PRECISION that 

take one argument of type DOUBLE PRECISION. The first argument represents the error 
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information and is an argument of type INTEGER that is passed by value. The second argument 
is a pointer to the argument passed to the math function. The error function returns a value that 
is then used as the return value for the math function. 

5. The function_math2err is called for math functions of type DOUBLE PRECISION that 

take two arguments of type DOUBLE PRECISION. The first argument represents the error 
information and is an argument of type INTEGER that is passed by value. The second argument 
is a pointer to the first argument passed to the math function and the third argument is a pointer 
to the second argument passed to the math function. The error function returns a value that is 
then used as the return value for the math function. 

6. The function_zmath2err is called for math functions of type COMPLEX that take two 

arguments of type COMPLEX. The first argument represents the error information and is an 
argument of type INTEGER that is passed by value. The second argument is a pointer to the 
first argument passed to the math function and the third argument is a pointer to the second 
argument passed to the math function. The error function returns a value that is then used as the 
return value for the math function. 

7. The function_qmath2err is called for math functions of type DOUBLE COMPLEX that 

take two arguments of type DOUBLE COMPLEX. The first argument represents the error 
information and is an argument of type INTEGER that is passed by value. The second argument 
is a pointer to the first argument passed to the math function and the third argument is a pointer 
to the second argument passed to the math function. The error function returns a value that is 
then used as the return value for the math function. 

The include file mathcode . f i is included by the file _ matherr . for and is located in the 
\watcom\src\fortran directory. It defines the information that is contained in the error information 
argument that is passed to all math error functions. 


7.17 INTEGER Function SEEKUNIT 


The INTEGER function SEEKUNIT permits seeking to a particular byte offset within a file connected to a 
FORTRAN unit. The file must be opened with the following attributes: 

FORM=’ UNFORM ATTED ’ 

ACCESS='SEQUENTIAL’ 

RECORDTYPE=’FIXED’ 

The function SEEKUNIT requires three arguments of type INTEGER, the unit number, the offset to seek, 
and the type of positioning to do. The seek positioning may be absolute (indicated by 0) or relative to the 
current position (indicated by 1). It returns an INTEGER value representing the new offset in the file. A 
returned value of -1 indicates that the function call failed. 

This function is particularly useful for applications that wish to change the input/output position for a file 
connected to a unit. 

The following example will set the current input/output position of the file connected to the specified unit. 
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Example: 

EXTERNAL SEEKUNIT 
INTEGER SEEKUNIT 
INTEGER SEEK_ SET, SEEK_ CUR 
PARAMETER (SEEK_SET=0, SEEK_CUR=1) 

INTEGER POSITION 
CHARACTER*80 RECORD 

OPEN( UNIT=8, FILE=' file', FORM='UNFORMATTED', 

1 ACCESS = 'SEQUENTIAL', RECORDTYPE='FIXED' ) 

POSITION = SEEKUNIT( 8, 10, SEEK_ SET ) 

IF ( POSITION .NE. -1 )THEN 

PRINT *, 'New position is', POSITION 
READ( UNIT=8 ) RECORD 
PRINT *, RECORD 
END IF 
END 

Notes: 

1. The FORTRAN include file f sublib . f i, located in the \watcom\src\fortran 
directory, contains typing and calling information for this subprogram. The 
\watcom\src\fortran directory should be included in the FINCLUDE environment 
variable so that the compiler can locate the include file. 


2. A value of -1 is returned if the requested positioning cannot be done. 

7.18 INTEGER Function SETJMP/Subroutine LONGJMP 


The INTEGER function SET JMP saves the current executing environment, making it possible to restore 
that environment by subsequently calling the LONGJMP subroutine. For example, it is possible to 
implement error handling by using SET JMP to record the point to which a return will occur following an 
error. When an error is detected in a called subprogram, that subprogram uses LONGJMP to jump back to 
the recorded position. The original subprogram which called SET JMP must still be active (it cannot have 
returned to the subprogram which called it). 

The SET JMP function requires one argument. The argument is a structure of type jmp_ buf and is used to 
save the current environment. The return value is an integer and is zero when initially called. It is non-zero 
if the return is the result of a call to the LONGJMP subroutine. An IF statement is often used to handle 
these two cases. This is demonstrated in the following example. 

Example: 
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include 'fsignal.fi' 
include 'setjmp.fi' 
record /jmp_buf/ jmp_ buf 
common jmp_ buf 
external break_ handler 
integer rc 

call fsignal ( SIGBREAK, break_ handler ) 
rc = setjmp( jmp_ buf ) 
if( rc .eq. 0 )then 
call do_ it() 

else 

print *, 'abnormal termination:', rc 
endif 
end 

subroutine do_ it () 
loop 

end loop 
end 

subroutine break_ handler() 

include 'setjmp.fi' 

record /jmp_buf/ jmp_ buf 

common jmp_ buf 

call long jmp ( jmp_ buf, -1 ) 

end 


Notes: 

1. The FORTRAN include file set jmp. f i contains typing and calling information for SETJMP 
and LONGJMP and must be included. Similarly, fsignal. f i must be included when using 
the FSIGNAL function. These files are located in the \watcom\src\fortran directory. 
The \watcom\src\fortran directory should be included in the FINCLUDE environment 
variable so that the compiler can locate these include files. 


7.19 INTEGER Function SETSYSHANDLE 


The INTEGER function SETSYSHANDLE allows an application to set the system file handle for a specified 
unit. 

The function SETSYSHANDLE requires an argument of type INTEGER, the unit number, and an argument 
of type INTEGER*2, the handle, and returns an INTEGER value representing the success or fail status of 
the function call. A returned value of -1 indicates that the function call failed and 0 indicates that the 
function call succeeded. 

This function is particularly useful for applications that wish to set the system file handle for a unit. The 
system file handle may have been obtained from a non-FORTRAN subroutine or function. 

The following example will set the system file handle for a paricular unit. 
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Example: 

INCLUDE 'FSUBLIB.FI' 

INTEGER STDIN, STDOUT 
PARAMETER (STDIN=0, STDOUT=l) 

OPEN( UNIT=8, FORM='FORMATTED' ) 

I = SYSHANDLE( 8 ) 

PRINT *, 'Old handle was', I 
I = SETSYSHANDLE( 8, STDOUT ) 

IF( I .EQ. 0 )THEN 

WRITE( UNIT=8, FMT=* ) 'Output to UNIT 8 which is stdout' 
ENDIF 
END 


Notes: 

1. The FORTRAN include file f sublib . f i, located in the \watcom\src\fortran 
directory, contains typing and calling information for this subprogram. The 
\watcom\src\fortran directory should be included in the FINCLUDE environment 
variable so that the compiler can locate the include file. 

2. A value of -1 is returned if the unit is not connected to a file. 

3. Units 5 and 6 are preconnected to the standard input and standard output devices respectively. 


7.20 INTEGERS Function SYSHANDLE 


The INTEGER*2 function SYSHANDLE allows an application to obtain the system file handle for a 
specified unit. 

The function SYSHANDLE requires one argument of type INTEGER, the unit number, and returns an 
INTEGER*2 value representing the system file handle. 

This function is particularly useful for applications that wish to pass the system file handle to 
non-FORTRAN subroutines or functions that wish to perform input/output to a FORTRAN 77 file. 

The following example will print the system file handles for the standard input and standard output devices. 

Example: 

INCLUDE 'FSUBLIB.FI' 

PRINT *, 'Unit 5 file handle is', SYSHANDLE( 5 ) 

PRINT *, 'Unit 6 file handle is', SYSHANDLE( 6 ) 

END 


Notes: 

1. The FORTRAN include file f sublib. fi, located in the \watcom\src\fortran 
directory, contains typing and calling information for this subprogram. The 
\watcom\src\fortran directory should be included in the FINCLUDE environment 
variable so that the compiler can locate the include file. 

2. A value of -1 is returned if the unit is not connected to a file. 

3. Units 5 and 6 are preconnected to the standard input and standard output devices respectively. 
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7.21 REAL Function URAND 


The REAL function URAND returns pseudo-random numbers in the range (0,1). 

The function URAND requires one argument of type INTEGER, the initial seed. The seed can contain any 
integer value. URAND returns a REAL value which is a pseudo-random number in the range (0.0,1.0). 

In the following example, 100 random numbers are printed. 

Example: 

REAL URAND 
INTEGER SEED 

SEED = 75347 
DO I = 1, 100 

PRINT *, URAND( SEED ) 

ENDDO 

END 

Notes: 

1. Upon each invocation of URAND , the seed argument is updated by the random number 

generator. Therefore, the argument must not be a constant and, once the seed value has been set, 
it must not be modified by the programmer. 

7.22 Default Windowing Functions 

The functions described in the following sections provide the capability to manipulate attributes of various 
windows created by Open Watcom’s default windowing system for Microsoft Windows 3.x, Windows 95, 
Windows NT, and IBM OS/2. A simple default windowing FORTRAN application can be built using the 
following command(s): 

16-bit Windows C>wfl [fnl] [fn2] ... /bw /windows /l=windows 

32-bit Windows C>wfl386 [fnl] [fn2] ... /bw /l=win386 

C>wbind -n [fnl] 

32-bit Windows NT or Windows 95 


C>wf138 6 [fnl] 

[fn2] .. 

/bw 

/l=nt_ win 

32-bit OS/2 Presentation Manager 

C>wf138 6 [fnl] 

[fn2] .. 

/bw 

/1=os2v 2_ pm 


Note: At present, a restriction in Windows NT prevents you from opening the console device 

(CON) for both read and write access. Therefore, it is not possible to open additional 
windows for both input and output under Windows NT. They must be either read-only or 
write-only windows. 
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7.22.1 dwfDeleteOnClose 


integer function dwfDeleteOnClose( unit ) 
integer unit 

The dwfDeleteOnClose function tells the console window that it should close itself when the corresponding 
file is closed. The argument unit is the unit number associated with the opened console. 

This function is one of the support functions that can be called from an application using Open Watcom’s 
default windowing support. 

The dwfDeleteOnClose function returns 1 if it was successful and 0 if not. 


Example: 

PROGRAM main 
INCLUDE 'FSUBLIB. FI' 


INTEGER rc 
CHARACTER response 


100 


1 

2 


rc = dwfSetAboutDlg( 'Hello World About Dialog', 

'About Hello World'//CHAR(13)// 
'Copyright 1994 by WATCOM'//CHAR(13) 
rc = dwfSetAppTitle( 'Hello World Application Title' ) 
rc = dwfSetConTitle( 5, 'Hello World Console Title' ) 

PRINT *, 'Hello World' 

OPEN( unit=3, file='CON' ) 

rc = dwfSetConTitle( 3, 'Hello World Second Console Title' 
rc = dwfDeleteOnClose( 3 ) 

WRITE( unit=3, fmt=* ) 'Hello to second console' 

WRITE( unit=3, fmt=* ) 'Press Enter to close this console' 
READ( unit=3, fmt='(A)', end=100, err=100 ) response 
CLOSE( unit=3 ) 

END 


) 


7.22.2 dwfSetAboutDIg 

integer function dwfSetAboutDlg( title, text ) 
character* (*) title 
character* (*) text 

The dwfSetAboutDIg function sets the "About" dialog box of the default windowing system. The argument 
title is a character string that will replace the current title. If title is CHAR(O) then the title will not 
be replaced. The argument text is a character string which will be placed in the "About" box. To get 
multiple lines, embed a new line character (CHAR(13)) after each logical line in the string. If text is 
CHAR(O), then the current text in the "About" box will not be replaced. 

This function is one of the support functions that can be called from an application using Open Watcom’s 
default windowing support. 

The dwfSetAboutDIg function returns 1 if it was successful and 0 if not. 
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Example: 

PROGRAM main 
INCLUDE 'FSUBLIB. FI' 

INTEGER rc 
CHARACTER response 

rc = dwfSetAboutDlg( 'Hello World About Dialog', 

1 'About Hello World'//CHAR(13)// 

2 'Copyright 1994 by WATCOM'//CHAR(13) ) 
rc = dwfSetAppTitle( 'Hello World Application Title' ) 

rc = dwfSetConTitle( 5, 'Hello World Console Title' ) 

PRINT *, 'Hello World' 

OPEN( unit=3, file='CON' ) 

rc = dwfSetConTitle( 3, 'Hello World Second Console Title' ) 
rc = dwfDeleteOnClose( 3 ) 

WRITE( unit=3, fmt=* ) 'Hello to second console' 

WRITE( unit=3, fmt=* ) 'Press Enter to close this console' 
READ( unit=3, fmt='(A)', end=100, err=100 ) response 
100 CLOSE( unit=3 ) 

END 


7.22.3 dwfSetAppTitle 

integer function dwfSetAppTitle( title ) 
character* (*) title 

The dwfSetAppTitle function sets the main window’s title. The argument title is a character string that 
will replace the current title. 

This function is one of the support functions that can be called from an application using Open Watcom’s 
default windowing support. 

The dwfSetAppTitle function returns 1 if it was successful and 0 if not. 

Example: 

PROGRAM main 
INCLUDE 'FSUBLIB.FI' 

INTEGER rc 
CHARACTER response 

rc = dwfSetAboutDlg( 'Hello World About Dialog', 

1 'About Hello World'//CHAR(13)// 

2 'Copyright 1994 by WATCOM'//CHAR(13) ) 
rc = dwfSetAppTitle( 'Hello World Application Title' ) 

rc = dwfSetConTitle( 5, 'Hello World Console Title' ) 

PRINT *, 'Hello World' 

OPEN( unit=3, file='CON' ) 

rc = dwfSetConTitle( 3, 'Hello World Second Console Title' ) 
rc = dwfDeleteOnClose( 3 ) 

WRITE( unit=3, fmt=* ) 'Hello to second console' 

WRITE( unit=3, fmt=* ) 'Press Enter to close this console' 

READ( unit=3, fmt='(A)', end=100, err=100 ) response 
100 CLOSE( unit=3 ) 

END 
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7.22.4 dwfSetConTitle 


integer function dwfSetConTitle( unit, title ) 
integer unit 
character*(*) title 

The dwfSetConTitle function sets the console window’s title which corresponds to the unit number passed 
to it. The argument unit is the unit number associated with the opened console. The argument title is 
the character string that will replace the current title. 

This function is one of the support functions that can be called from an application using Open Watcom’s 
default windowing support. 

The dwfSetConTitle function returns 1 if it was successful and 0 if not. 


Example: 

PROGRAM main 
INCLUDE 'FSUBLIB. FI' 


INTEGER rc 
CHARACTER response 


100 


1 

2 


rc = dwfSetAboutDlg( 'Hello World About Dialog', 

'About Hello World'//CHAR(13)// 
'Copyright 1994 by WATCOM'//CHAR(13) 
rc = dwfSetAppTitle( 'Hello World Application Title' ) 
rc = dwfSetConTitle( 5, 'Hello World Console Title' ) 

PRINT *, 'Hello World' 

OPEN( unit=3, file='CON' ) 

rc = dwfSetConTitle( 3, 'Hello World Second Console Title' 
rc = dwfDeleteOnClose( 3 ) 

WRITE( unit=3, fmt=* ) 'Hello to second console' 

WRITE( unit=3, fmt=* ) 'Press Enter to close this console' 
READ( unit=3, fmt='(A)', end=100, err=100 ) response 
CLOSE( unit=3 ) 

END 


) 


7.22.5 dwfShutDown 


integer function dwfShutDown() 

The dwfShutDown function shuts down the default windowing I/O system. The application will continue 
to execute but no windows will be available for output. Care should be exercised when using this function 
since any subsequent output may cause unpredictable results. 

When the application terminates, it will not be necessary to manually close the main window. 

This function is one of the support functions that can be called from an application using Open Watcom’s 
default windowing support. 

The dwfShutDown function returns 1 if it was successful and 0 if not. 
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Example: 

PROGRAM main 
INCLUDE 'FSUBLIB. FI' 


INTEGER rc 
CHARACTER response 


100 


1 

2 


rc = dwfSetAboutDlg( 'Hello World About Dialog', 

'About Hello World'//CHAR(13)// 
'Copyright 1994 by WATCOM'//CHAR(13) 
rc = dwfSetAppTitle( 'Hello World Application Title' ) 
rc = dwfSetConTitle( 5, 'Hello World Console Title' ) 

PRINT *, 'Hello World' 

OPEN( unit=3, file='CON' ) 

rc = dwfSetConTitle( 3, 'Hello World Second Console Title' 
rc = dwfDeleteOnClose( 3 ) 

WRITE( unit=3, fmt=* ) 'Hello to second console' 

WRITE( unit=3, fmt=* ) 'Press Enter to close this console' 
READ( unit=3, fmt='(A)', end=100, err=100 ) response 
CLOSE( unit=3 ) 


rc = dwfShutDown() 


) 


* do more computing that does not involve console input/output 

* 
ik 
* 


END 


7.22.6 dwfYield 

integer function dwf veld() 

The dwfYield function yields control back to the operating system, thereby giving other processes a chance 
to run. 

This function is one of the support functions that can be called from an application using Open Watcom’s 
default windowing support. 

The dwfYield function returns 1 if it was successful and 0 if not. 
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Example: 

PROGRAM main 
INCLUDE 'FSUBLIB. FI' 

INTEGER rc 
CHARACTER response 
INTEGER i 

rc = dwfSetAboutDlg( 'Hello World About Dialog', 

1 'About Hello World'//CHAR(13)// 

2 'Copyright 1994 by WATCOM'//CHAR(13) ) 

rc = dwfSetAppTitle( 'Hello World Application Title' ) 

rc = dwfSetConTitle( 5, 'Hello World Console Title' ) 

PRINT *, 'Hello World' 

OPEN( unit=3, file='CON' ) 

rc = dwfSetConTitle( 3, 'Hello World Second Console Title' ) 
rc = dwfDeleteOnClose( 3 ) 

WRITE( unit=3, fmt=* ) 'Hello to second console' 

WRITE( unit=3, fmt=* ) 'Press Enter to close this console' 
READ( unit=3, fmt='(A)', end=100, err=100 ) response 
100 CLOSE( unit=3 ) 

DO i = 0, 1000 

rc = dwfYield() 

* do CPU-intensive calculation 

* 

* 

* 

ENDDO 
PRINT *, i 

END 
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8 Data Representation On x86-based Platforms 


This chapter describes the internal or machine representation of the basic types supported by Open Watcom 
F77. The following table summarizes these data types. 


Data Type 

Size 

(in bytes) 

FORTRAN 77 

Standard 

LOGICAL 

4 


LOGICAL* 1 

1 

(extension) 

LOGICAL*4 

4 

(extension) 

INTEGER 

4 


INTEGER* 1 

1 

(extension) 

INTEGER*2 

2 

(extension) 

INTEGER*4 

4 

(extension) 

REAL 

4 


REAL*4 

4 

(extension) 

REAL* 8 

8 

(extension) 

DOUBLE PRECISION 

8 


COMPLEX 

8 


COMPLEX*8 

8 

(extension) 

COMPLEX*16 

16 

(extension) 

DOUBLE COMPLEX 

16 

(extension) 

CHARACTER 

1 


CHARACTER*!! 

n 



8.1 LOGICAL*1 Data Type 

An item of type LOGICAL*l occupies 1 byte of storage. It can only have two values, namely .TRUE, (a 
value of 1) and .FALSE, (a value of 0). 

8.2 LOGICAL and L0GICAL*4 Data Types 

An item of type LOGICAL or LOGICAL*4 occupies 4 bytes of storage. It can only have two values, 
namely .TRUE, (a value of 1) and .FALSE, (a value of 0). 
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8.3 INTEGERS Data Type 

An item of type INTEGER*1 occupies 1 byte of storage. Its value is in the following range. An integer n 
can be represented in 1 byte if 

-128 <= n <= 127 

8.4 INTEGER*2 Data Type 

An item of type INTEGER*2 occupies 2 bytes of storage. An integer n can be represented in 2 bytes if 
-32768 <= n <= 32767 


8.5 INTEGER and INTEGERS Data Types 

An item of type INTEGER or INTEGER*4 occupies 4 bytes of storage (one numeric storage unit). An 
integer n can be represented in 4 bytes if 

-2147483648 <= n <= 2147483647 

8.6 REAL and REAL*4 Data Types 

An item of type REAL or REAL*4 is an approximate representation of a real number and occupies 4 bytes 
(one numeric storage unit). If m is the magnitude of a real number x, then x can be approximated if 

-126 128 
2 <= m < 2 

or in more approximate terms if 

1.175494e-38 <= m <= 3.402823e38 

Items of type REAL or REAL*4 are represented internally as follows. Note that bytes are stored in 
memory with the least significant byte first and the most significant byte last. 


s 

Biased 

Significand 


Exponent 


31 

30-23 

22-0 


S 


S = Sign bit (0=positive, l=negative) 


Exponent The exponent bias is 127 (i.e., exponent value 1 represents 2**-126; exponent value 127 
represents 2**0; exponent value 254 represents 2**127; etc.). The exponent field is 8 bits 
long. 

Significand The leading bit of the significand is always 1, hence it is not stored in the significand field. 
Thus the significand is always "normalized". The significand field is 23 bits long. 
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Zero A real zero quantity occurs when the sign bit, exponent, and significand are all zero. 

Infinity When the exponent field is all 1 bits and the significand field is all zero bits then the 

quantity represents positive or negative infinity, depending on the sign bit. 

Not Numbers When the exponent field is all 1 bits and the significand field is non-zero then the quantity 
is a special value called a NAN (Not-A-Number). 

When the exponent field is all 0 bits and the significand field is non-zero then the quantity 
is a special value called a "denormal" or nonnormal number. 

8.7 DOUBLE PRECISION and REAL*8 Data Types 

An item of type DOUBLE PRECISION or REAL*8 is an approximate representation of a real number, 
occupies 8 bytes (two numeric storage units) and has precision greater than or equal to that of an item of 
type REAL or REAL*4. If m is the magnitude of a real number x, then x can be approximated if 

-1022 1024 

2 <= m < 2 

or in more approximate terms if 

2,2250738585072e-308 <= m <= 1.79769313486232e308 

Items of type DOUBLE PRECISION or REAL*8 are represented internally as follows. Note that bytes 
are stored in memory with the least significant byte first and the most significant byte last. 


s 

Biased 

Significand 


Exponent 


63 

62-52 

51-0 


S 


S = Sign bit (0=positive, l=negative) 


Exponent The exponent bias is 1023 (i.e., exponent value 1 represents 2**-1022; exponent value 

1023 represents 2**0; exponent value 2046 represents 2**1023; etc.). The exponent field 
is 11 bits long. 

Significand The leading bit of the significand is always 1, hence it is not stored in the significand field. 
Thus the significand is always "normalized". The significand field is 52 bits long. 

Zero A double precision zero quantity occurs when the sign bit, exponent, and significand are all 

zero. 


Infinity When the exponent field is all 1 bits and the significand field is all zero bits then the 

quantity represents positive or negative infinity, depending on the sign bit. 

Not Numbers When the exponent field is all 1 bits and the significand field is non-zero then the quantity 
is a special value called a NAN (Not-A-Number). 

When the exponent field is all 0 bits and the significand field is non-zero then the quantity 
is a special value called a "denormal" or nonnormal number. 
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8.8 COMPLEX, C0MPLEX*8, and DOUBLE COMPLEX Data 
Types 


An item of type COMPLEX or COMPLEX*8 is an approximate representation of a complex number. 

The representation is an ordered pair of real numbers, the first representing the real part of the complex 
number and the second representing the imaginary part of the complex number. Each item of type 
COMPLEX or COMPLEX*8 occupies 8 bytes (two consecutive numeric storage units), the first being the 
real part and the second the imaginary part. The approximation of the real and imaginary parts of a 
complex number is the same degree of approximation used for items of type REAL. 

8.9 C0MPLEX*16 Data Type 

An item of type COMPLEX*16 is an approximate representation of a complex number. The 
representation is an ordered pair of real numbers, the first representing the real part of the complex number 
and the second representing the imaginary part of the complex number. Each item of type COMPLEX*16 
occupies 16 bytes (four consecutive numeric storage units), the first two being the real part and the last two 
the imaginary part. The approximation of the real and imaginary parts of a complex number is the same 
degree of approximation used for items of type DOUBLE PRECISION. 

8.10 CHARACTER Data Type 

An item of type CHARACTER represents a sequence of characters. Each character occupies 1 byte of 
storage (1 character storage unit). The length of an item of type CHARACTER is the number of 
characters it contains. Each character is assigned an integer that represents its position. Characters are 
numbered from 1 to n starting from the left, n being the number of characters. 

Items of type CHARACTER are represented by a string descriptor. A string descriptor has the following 
format. 


0 


4 


The pointer to the actual data is a 32-bit offset in the default data segment. The length is represented as a 
32-bit unsigned integer. 

8.11 Storage Organization of Data Types 

The following illustrates the relative size of the data types in terms of bytes. LOGICAL is equivalent to 
LOGICAL*4, INTEGER is equivalent to INTEGER S, DOUBLE PRECISION is equivalent to 
REAL*8, and COMPLEX is equivalent to COMPLEX*8. If the "short" option is used, LOGICAL is 
equivalent to LOGICAL*! and INTEGER is equivalent to INTEGER*2. 


Offset 


pointer to data 


length of data 
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Offset 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 



8.12 Floating-point Accuracy On x86-based Platforms 

There are a number of issues surrounding floating-point accuracy, calculations, exceptions, etc. on the 
x86-based personal computer platform that we will address in the following sections. Some result from 
differences in the behaviour of standard-conforming FORTRAN 77 compilers. Other result from 
idiosyncrasies of the IEEE Standard 754 floating-point that is supported on the x86 platform. 

Some FORTRAN 77 compilers extend the precision of single-precision constants in DATA statement 
initialization lists when the corresponding variable is double precision. This is permitted by the FORTRAN 
77 Standard. Open Watcom FORTRAN 77, however, does not do this. This is illustrated by the following 
example. 

Example: 

double precision pil, pi2 
data pil /3.141592653589793/ 
data pi2 /3.141592653589793d0/ 

write(unit=*,fmt='(lx,zl6,lx,fl8.15)') pil, pil 
write(unit=*,fmt='(lx,zl6,lx,fl8.15)') pi2, pi2 
end 

The output produces two very different results for our pi variables. The variable P11 is initialized with a 
single precision (i.e., REAL) constant. 

400921FB60000000 3.141592741012573 

400921FB54442D18 3.141592653589793 

A single precision datum has 23 bits in the mantissa; a double precision datum has 52 bits in the mantissa. 
Hence P11 has 29 fewer bits of accuracy in the mantissa (the difference between 52 and 23) since it is 
initialized with a single precision constant. You can verify this by examining the hexadecimal output of the 
two pi’s. The bottom 29 bits of the mantissa in Pil are all zero. 
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To be on the safe side, the rule is always use double precision constants (even in DATA statements) if you 
want as much accuracy as possible. 

This behaviour treats DATA statement initialization as equivalent to simple assignment as shown in the 
following example. 

Example: 

double precision pil, pi2 
pil = 3.141592653589793 
pi2 = 3.141592653589793d0 

write(unit=*,fmt='(lx,zl6,lx,fl8.15)') pil, pil 
write(unit=*,fmt='(lx,zl6,lx,fl8.15)') pi2, pi2 
end 

The output follows: 

400921FB60000000 3.141592741012573 

400921FB54442D18 3.141592653589793 

A second consideration is illustrated by the next example. On some computer architectures, there is no 
difference in the exponent range between single and double precision floating-point representation. One 
such architecture is the IBM mainframe computer (e.g., IBM System/370). When a double precision result 
is assigned to a single precision (REAL) variable, only precision in the mantissa is lost. 

The x86 platform uses the IEEE Standard 754 floating-point representation. In this representation, the 
range of exponent values is greater in double precision than in single precision. As described in the section 
entitled "REAL and REAL*4 Data Types" on page 82, the range for single precision (REAL, REAL*4) 
numbers is: 

1.175494e-38 <= m <= 3.402823e38 

On the other hand, the range for double precision (DOUBLE PRECISION, REAL*8) numbers is: 

2,2250738585072e-308 <= m <= 1.79769313486232e308 

Double precision is described in the section entitled "DOUBLE PRECISION and REAL*8 Data Types" on 
page 83. So you can see that a number like 1.0E234 can easily be represented in double precision but not in 
single precision since the maximum positive exponent value for single precision is 38. 

8.13 Floating-point Exceptions On x86-based Platforms 

The following types of exceptions can be enabled/disabled on PC's with an 80x87 floating-point unit 
(either a real FPU or a true emulator). 

DENORMAL The result has become denormalized. When the exponent field is all 0 bits and the 

significand field is non-zero then the quantity is a special value called a "denormal" or 
nonnormal number. By providing a significand with leading zeros, the range of possible 
negative exponents can be extended by the number of bits in the significand. Each 
leading zero is a bit of lost accuracy, so the extended exponent range is obtained by 
reducing significance. 

ZERODIVIDE A division by zero was attempted. A real zero quantity occurs when the sign bit, 
exponent, and significand are all zero. 
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OVERFLOW The result has overflowed. The correct answer is finite, but has a magnitude too great to 
be represented in the destination floating-point format. 

UNDERFLOW The result has numerically underflowed. The correct answer is non-zero but has a 
magnitude too small to be represented as a normal number in the destination 
floating-point format. IEEE Standard 754 specifies that an attempt be made to represent 
the number as a denormal. This denormalization may result in a loss of significant bits 
from the significand. 


PRECISION A calculation does not return an exact answer. This exception is usually masked 

(disabled) and ignored. It is used in extremely critical applications, when the user must 
know if the results are exact. The precision exception is called "inexact" in IEEE 
Standard 754. 

INVALID This is the exception condition that covers all cases not covered by the other exceptions. 

Included are FPU stack overflow and underflow, NAN inputs, illegal infinite inputs, 
out-of-range inputs, and inputs in unsupported formats. 

Which exceptions does Open Watcom FORTRAN 77 catch and which ones does it ignore by default? We 
can determine the answer to this with the following program. 

* This program uses the C Library routine control87" 

* to obtain the math coprocessor exception mask. 

implicit none 
include 'fsignal.fi' 

character*8 status 
integer fp_ cw, bits 

fp_ cw = _ control87(0,0) 
bits = I AND ( fp_ cw, MCW_ EM ) 

print '(a,lx,z4)', 'Interrupt exception mask', bits 

print *,'Invalid operation exception ', status(bits, EM_ INVALID) 

print *,'Denormalized exception ', status(bits, EM_ DENORMAL) 

print *,'Divide by 0 exception ', status(bits, EM_ ZERODIVIDE) 

print *,'Overflow exception ', status(bits, EM_ OVERFLOW) 

print *,'Underflow exception ', status(bits, EM_ UNDERFLOW) 

print *,'Precision exception ', status(bits, EM_ PRECISION) 

end 

character*8 function status( bits, mask ) 
integer bits, mask 

if( IAND(bits,mask) .eq. 0 ) then 
status = 'enabled' 
else 

status = 'disabled' 
endif 
end 


If you compile and run this program, the following output is produced. 

Interrupt exception mask 0032 
Invalid operation exception enabled 
Denormalized exception disabled 
Divide by 0 exception enabled 
Overflow exception enabled 
Underflow exception disabled 
Precision exception disabled 
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So, by default, the Open Watcom FORTRAN 77 run-time system will catch "invalid operation", "divide by 
0", and "overflow" exceptions. It ignores "denormal", "underflow", and "precision" exceptions. Thus 
calculations that produce very small results trend towards zero. Also, calculations that produce inexact 
results (a very common occurrence in floating-point calculations) are allowed to continue. 

Suppose that you were interested in flagging calculations that result in denormalized or underflowed 
results. To do this, we need to enable both DENORMAL and UNDERFLOW exceptions. This following 
program illustrates how to do this. 

*$ifdef_ 386_ 

*$ifdef_stack_ conventions_ 

*$pragma aux _ clear87 "!" 

*$else 

*$pragma aux _ clear87 "!_ " 

*$endif 

*$else 

*$pragma aux _ clear87 "!_ " 

*$endif 

implicit none 
include 'fsignal.fi' 

character*8 status 

integer fp_ cw, fp_ mask, bits 

* get rid of any errors so we don't cause an instant exception 
call _ clear87 

* fp_ mask determines the bits to enable and/or disable 
fp_ mask = 0 

1 + EM_ DENORMAL 

2 + EM_ UNDERFLOW 

* fp_ cw determines whether to enable(0) or disable(1) 

* (in this case, nothing is disabled) 
fp_ cw = ' 0 0 0 0'x 

fp_ cw = _ control87 ( fp_ cw, fp_ mask ) 
bits = I AND ( fp_ cw, MCW_ EM ) 

print '(a,lx,z4)', 'Interrupt exception mask', bits 

print *,'Invalid operation exception ', status(bits, EM_ INVALID) 

print *,'Denormalized exception ', status(bits, EM_ DENORMAL) 

print *,'Divide by 0 exception ', status (bits, EM_ ZERODIVIDE) 

print *, 'Overflow exception ', status(bits, EM_ OVERFLOW) 

print *, 'Underflow exception ', status(bits, EM_ UNDERFLOW) 

print *,'Precision exception ', status(bits, EM_ PRECISION) 

end 

character*8 function status( bits, mask ) 
integer bits, mask 

if( IAND(bits,mask) .eq. 0 ) then 
status = 'enabled' 
else 

status = 'disabled' 
endif 
end 


If you compile and run this program, the following output is produced. 
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Interrupt exception mask 0020 
Invalid operation exception enabled 
Denormalized exception enabled 
Divide by 0 exception enabled 
Overflow exception enabled 
Underflow exception enabled 
Precision exception disabled 


8.14 Compiler Options Relating to Floating-point 

Let us take the program that we developed in the previous section and test it out. If you introduce the 
variable FLT to the program and calculate the expression "2e-38 x 2e-38", you would expect to see 0.0 
printed when underflow exceptions are disabled and a run-time diagnostic when underflow exceptions are 
enabled. The statements that you would add are show in the following. 

real fit 

flt=2e-38 
print *, flt*flt 

* code to enable exceptions goes here 
print *, flt*flt 
end 


If you compile the modified program with default options and run it, the result is as follows. 

0.0000000 

Interrupt exception mask 0020 
Invalid operation exception enabled 
Denormalized exception enabled 
Divide by 0 exception enabled 
Overflow exception enabled 
Underflow exception enabled 
Precision exception disabled 
0.0000000 

This is not what we expected. Evaluation of the second expression did not produce the run-time diagnostic 
that we expected. The reason this happened is related to the compiler’s processing of the source code. By 
default, the compiler optimized the generated code by evaluating the expression "2e-38 x 2e-38" at compile 
time producing 0.0 as the result (due to the underflow). 

flt=2e-38 
print *, flt*flt 

reduces to 

print *, 2e-28*2e-38 
which further reduces to 
print *, 0.0 

Recompile the program using the "OP" option and run it. The result is as follows. 
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0.0000000 

Interrupt exception mask 0020 
Invalid operation exception enabled 
Denormalized exception enabled 
Divide by 0 exception enabled 
Overflow exception enabled 
Underflow exception enabled 
Precision exception disabled 
*ERR* KO-03 floating-point underflow 

The use of the "OP" option will force the result to be stored in memory after each FORTRAN statement is 
executed. Thus, the source code is not optimized across statements. Compile-time versus run-time 
evaluation of expressions can lead to different results. It is very instructive to compile and then run your 
application with a variety of compile-time options to see the effect of optimizations. See the chapter 
entitled "Open Watcom FORTRAN 77 Compiler Options" on page 5 for more information on compiler 
options. 

Before we end this section, there is another important aspect of floating-point exceptions to consider. A 
floating-point exception is triggered upon the execution of the next FPU instruction following the one that 
caused the exception. 

implicit none 

real*4 a 
real*8 b 

b=12.0dl23 

a=b*b 

b=l. 0 

a=b/2.0 

print *, a, b 

end 


Compile this program with the "OP" and "DEBUG" options and then run it. The result is displayed next. 

*ERR* KO-02 floating-point overflow 
- Executing line 9 in file pi4.for 

Line 9 is the line containing the statement a=b/2.0 which could not possibly be responsible for an 
overflow. However, it contains the first floating-point instruction following the instruction in line 7 where 
the overflow actually occurred. To see this, it helps to disassemble the object file. 


a=b*b 


0029 

B8 

07 

00 

00 

00 


mov 

002E 

E8 

00 

00 

00 

00 


call 

0033 

DD 

45 

F4 




fid 

0036 

D8 

C8 





fmul 

0038 

D9 

5D 

FC 




f Stp 


b=l. 0 






003B 

B8 

09 

00 

00 

00 


mov 

0040 

E8 

00 

00 

00 

00 


call 

0045 

31 

DB 





xor 

0047 

89 

5D 

F4 




mov 

004A 

C7 

45 

F8 

00 

00 

F0 

3F 








mov 


a=b/ 2 

:.o 






0051 

B8 

0A 

00 

00 

00 


mov 

0056 

E8 

00 

00 

00 

00 


call 

005B 

DD 

45 

F4 




fid 

005E 

DC 

0D 

08 

00 

00 

00 









fmul 

0064 

D9 

5D 

FC 




f stp 


eax,0x00000007 
RTSSetLine 
qword ptr -0xc[ebp] 
st, st 

dword ptr -0x4[ebp] 

eax,0x00000009 
RT@SetLine 
ebx,ebx 
-Oxc[ebp],ebx 

dword ptr -0x8[ebp],0x3ff00000 

eax,0x0000000a 

RTSSetLine 

qword ptr -Oxc[ebp] 

qword ptr L$2 
dword ptr -0x4[ebp] 
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The overflow occurred when the "fstp" was executed but is signalled when the subsequent "fid" is 
executed. The overflow could also be signalled while executing down in a run-time routine. This 
behaviour of the FPU can be somewhat exasperating. 

8.15 Floating-point Exception Handling 

In certain situations, you want to handle floating-point exceptions in the application itself rather than let the 
run-time system terminate your application. The following example illustrates how to do this by installing 
a FORTRAN subroutine as a floating-point exception handler. 
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implicit none 
include 'fsignal.fi' 

real fit 

external fpehandler 

integer signal_ count, signal_ number, signal_ type 

common /fpe/ signal_ count, signal_ number, signal_ type 

* begin the signal handling process for floating-point exceptions 
call fsignal( SIGFPE, fpehandler ) 

* 

* main body of application goes here 

* 

fit = 2.0 

print *, 'number of signals', volatile( signal_ count ) 
print *, fit / 0.0 

print *, 'number of signals', volatile( signal_ count ) 
end 

*$ifdef_ 386_ 

*$ifdef_stack_ conventions_ 

*$pragma aux _ clear87 "!" 

*$else 

*$pragma aux _ clear87 " !_ " 

*$endif 

*$else 

*$pragma aux _ clear87 " !_ " 

*$endif 

*$pragma aux fpehandler parm( value, value ) 

subroutine fpehandler ( sig_ num, fpe_ type ) 
implicit none 

* sig_ num and fpe_ type are passed by value, not by reference 
integer sig_ num, fpe_ type 

include 'fsignal.fi' 

integer signal_ count, signal_ number, signal_ type 

common /fpe/ signal_ count, signal_ number, signal_ type 

* we could add this to our common block 

integer signal_ split ( FPE_ INVALID : FPE_ IOVERFLOW ) 

signal_ count = signal_ count + 1 
signal_ number = sig_ num 
signal_ type = fpe_ type 

* floating-point exception types 


k 

FPE_ 

INVALID 

= 

129 

(0) 

k 

FPE_ 

DENORMAL 

= 

130 

(1) 

k 

FPE_ 

ZERODIVIDE 

= 

131 

(2) 

k 

FPE_ 

OVERFLOW 

= 

132 

(3) 

k 

FPE_ 

UNDERFLOW 

= 

133 

(4) 

k 

FPE_ 

INEXACT 

= 

134 

(5) 

k 

FPE_ 

UNEMULATED 

= 

135 

(6) 

k 

FPE_ 

SQRTNEG 

= 

136 

(7) 

k 

undefined 

= 

138 

(8) 

k 

FPE_ 

STACKOVERFLOW 

= 

137 

(9) 

k 

FPE_ 

STACKUNDERFLOW 

= 

138 

(10) 

k 

FPE_ 

EXPLICITGEN 

= 

139 

(11) 

k 

FPE_ 

IOVERFLOW 

= 

140 

(12) 

k 

log 

the type of error 

for 

interest 


signal_ split ( fpe_ type ) = 
lsignal_ split ( fpe_ type ) + 1 

get rid of any errors 
call _ clear87 


92 


Floating-point Exception Handling 




Data Representation On x86-based Platforms 


resignal for more exceptions 
call fsignal( SIGFPE, fpehandler ) 

if we don't then a subsequent exception will 
cause an abnormal program termination 

end 


Note the use of the VOLATILE intrinsic function to obtain up-to-date contents of the variable 
SIGNAL_ COUNT. 
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916-bit Memory Models 


9.1 Introduction 


This chapter describes the various 16-bit memory models supported by Open Watcom F77. Each memory 
model is distinguished by two properties; the code model used to implement subprogram calls and the data 
model used to reference data. 


9.216-bit Code Models 

There are two code models; 

1. the small code model and 

2. the big code model. 

A small code model is one in which all calls to subprograms are made with near calls. In a near call, the 
destination address is 16 bits and is relative to the segment value in segment register CS. Hence, in a small 
code model, all code comprising your program, including library subprograms, must be less than 64K. 
Open Watcom F77 does not support the small code model. 

A big code model is one in which all calls to subprograms are made with far calls. In a far call, the 
destination address is 32 bits (a segment value and an offset relative to the segment value). This model 
allows the size of the code comprising your program to exceed 64K. 

9.3 16-bit Data Models 


There are three data models; 

1. the small data model, 

2. the big data model and 

3. the huge data model. 

A small data model is one in which all references to data are made with near pointers. Near pointers are 16 
bits; all data references are made relative to the segment value in segment register DS. Hence, in a small 
data model, all data comprising your program must be less than 64K. 

A big data model is one in which all references to data are made with far pointers. Far pointers are 32 bits 
(a segment value and an offset relative to the segment value). This removes the 64K limitation on data size 
imposed by the small data model. However, when a far pointer is incremented, only the offset is adjusted. 
Open Watcom F77 assumes that the offset portion of a far pointer will not be incremented beyond 64K. 

The compiler will assign an object to a new segment if the grouping of data in a segment will cause the 
object to cross a segment boundary. Implicit in this is the requirement that no individual object exceed 64K 
bytes. For example, an array containing 40,000 integers does not fit into the big data model. An object 
such as this should be described as huge. 
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A huge data model is one in which all references to data are made with far pointers. This is similar to the 
big data model. However, in the huge data model, incrementing a far pointer will adjust the offset and the 
segment if necessary. The limit on the size of an object pointed to by a far pointer imposed by the big data 
model is removed in the huge data model. 

Notes: 

1. The huge data model has the same characteristics as the big data model, but formal array 
arguments are assumed to exceed 64K bytes. You should use the huge data model whenever any 
arrays in your application exceed 64K bytes in size. 

2. If your program contains less than 64K of data, you should use the small data model. This will 
result in smaller and faster code since references using near pointers produce fewer instructions. 

3. The huge data model should be used only if needed. The code generated in the huge data model 
is not very efficient since a run-time routine is called in order to increment far pointers. This 
increases the size of the code significantly and increases execution time. 

9.4 Summary of 16-bit Memory Models 

As previously mentioned, a memory model is a combination of a code model and a data model. The 
following table describes the memory models supported by Open Watcom F77. 


Memory 

Model 

Code 

Model 

Data 

Model 

Default 

Code 

Pointer 

Default 

Data 

Pointer 

medium 

big 

small 

far 

near 

large 

big 

big 

far 

far 

huge 

big 

huge 

far 

huge 


9.5 Mixed 16-bit Memory Model 

A mixed memory model application combines elements from the various code and data models. A mixed 
memory model application might be characterized as one that includes arrays which are larger than 64K 
bytes. 

For example, a medium memory model application that uses some arrays which exceed 64K bytes in total 
size can be described as a mixed memory model. In an application such as this, most of the data is in a 64K 
segment (DGROUP) and hence can be referenced with near pointers relative to the segment value in 
segment register DS. This results in more efficient code being generated and better execution times than 
one can expect from a big data model. 
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9.6 Linking Applications for the Various 16-bit Memory 
Models 


Each memory model requires different run-time and floating-point libraries. Each library assumes a 
particular memory model and should be linked only with modules that have been compiled with the same 
memory model. The following table lists the libraries that are to be used to link an application that has 
been compiled for a particular memory model. 


Library 

Memory 

model 


Floating-point 

model 

flibm.lib 

/mm 



/ fpc 


flibl.lib 

/ml. 

/mh 


/ fpc 


flib7m.lib 

/mm 



/ fpi. 

/fpi87 

flib71.lib 

/ml. 

/mh 


/ fpi. 

/fpi87 

clibm.lib 

/mm 



/fpc. 

/fpi, /fpi87 

clibl.lib 

/ml. 

/mh 


/fpc. 

/fpi, /fpi87 

mathm.lib 

/mm. 



/fpc 


mathl.lib 

/ml. 

/mh 


/fpc 


math87m.lib 

/mm. 



/ fpi. 

/fpi87 

math871.lib 

/ml. 

/mh 


/ fpi. 

/fpi87 

emu87.lib 

/mm. 

/ml. 

/mh 

/fpi 


noemu87.lib 

/mm. 

/ml. 

/mh 

/fpi87 



9.7 Memory Layout 

The following describes the segment ordering of an application linked by the Open Watcom Linker. Note 
that this assumes that the "DOSSEG" linker option has been specified. 

1. all segments not belonging to group "DGROUP" with class "CODE" 

2. all other segments not belonging to group "DGROUP" 

3. all segments belonging to group "DGROUP" with class "BEGDATA" 

4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

5. all segments belonging to group "DGROUP" with class "BSS" 

6. all segments belonging to group "DGROUP" with class "STACK" 

A special segment belonging to class "BEGDATA" is defined when linking with Open Watcom run-time 
libraries. This segment is initialized with the hexadecimal byte pattern "01" and is the first segment in 
group "DGROUP" so that storing data at location 0 can be detected. 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 

In addition to these special segments, the following conventions are used by Open Watcom F77. 
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1. The "CODE" class contains the executable code for your application. In a small code model, this 
consists of the segment "_TEXT". In a big code model, this consists of the segments 
"<subprogram>_TEXT" where <subprogram> is the name of a subprogram. 

2. The "FAR_DATA" class consists of the following: 

(a) arrays whose size exceeds the data threshold in large data memory models (the 
data threshold is 256 bytes unless changed using the "dt" compiler option) 

(b) equivalenced variables in large data memory models 
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10.1 Introduction 

This chapter will deal with the following topics. 

1. The memory layout of a program compiled by Open Watcom F77. 

2. The method for passing arguments and returning values. 

3. The two methods for passing floating-point arguments and returning floating-point values. 

One method is used when one of the Open Watcom F77 "fpi", "fpi87" or "fpi387" options is 
specified for the generation of in-line 80x87 instructions. When the "fpi" option is specified, an 
80x87 emulator is included from a math library if the application includes floating-point 
operations. When the "fpi87" or "fpi387" option is used exclusively, the 80x87 emulator will not 
be included. 

The other method is used when the Open Watcom F77 "fpc" option is specified. In this case, the 
compiler generates calls to floating-point support routines in the alternate math libraries. 

An understanding of the Intel 80x86 architecture is assumed. 

10.2 Calling Conventions 

The following sections describe the method used by Open Watcom F77 to pass arguments. 

The FORTRAN 77 language specifically requires that arguments be passed by reference. This means that 
instead of passing the value of an argument, its address is passed. This allows a called subprogram to 
modify the value of the actual arguments. The following illustrates the method used to pass arguments. 
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Type of Argument 

Method Used to Pass Argument 

non-character constant 

address of constant 

non-character expression 

address of value of expression 

non-character variable 

address of variable 

character constant 

address of string descriptor 

character expression 

address of string descriptor 

character variable 

address of string descriptor 

non-character array 

address of array 

non-character array element 

address of array 

character array 

address of string descriptor 

character array element 

address of string descriptor 

character substring 

address of string descriptor 

subprogram 

address of subprogram 

alternate return specifier 

no argument passed 

user-defined structure 

address of structure 


When passing a character array as an argument, the string descriptor contains the address of the first 
element of the array and the length of an element of the array. 

The address of arguments are either passed in registers or on the stack. The registers used to pass the 
address of arguments to a subprogram are AX, BX, CX and DX. The address of arguments are passed in 
the following way. 

1. For memory models with a big data model, address of arguments consist of a 16-bit offset and a 
16-bit segment. Hence, two registers are required to pass the address of an argument. The first 
argument will be passed in registers DX:AX with register DX containing the segment and 
register AX containing the offset. The second argument will be passed in registers CX:BX with 
register CX containing the segment and register BX containing the offset. 

2. For memory models with a small data model, address of arguments consists of only a 16-bit 
offset into the default data segment. Hence, only a single register is required to pass the address 
of an argument. The first argument is passed in register AX, the second argument is passed in 
register DX, the third argument is passed in register BX, and the fourth argument is passed in 
register CX. 

3. For any remaining arguments, their address is passed on the stack. Note that addresses of 
arguments are pushed on the stack from right to left. 

10.2.1 Processing Function Return Values with no 80x87 

The way in which function values are returned is also dependent on the data type of the function. The 
following describes the method used to return function values. 

1. LOGICAL*l values are returned in register AL. 

2. LOGICAL*4 values are returned in registers DX:AX. 

3. INTEGER*1 values are returned in register AL. 

4. INTEGER*2 values are returned in register AX. 
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5. INTEGER*4 values are returned in registers DX:AX. 

6. REAL*4 values are returned in registers DX:AX. 

7. REAL*8 values are returned in registers AX:BX:CX:DX. 

8. For COMPLEX*8 functions, space is allocated on the stack by the caller for the return value. 
Register SI is set to point to the destination of the result. The called function places the result at 
the location pointed to by register SI. 

9. For COMPLEX*16 functions, space is allocated on the stack by the caller for the return value. 
Register SI is set to point to the destination of the result. The called function places the result at 
the location pointed to by register SI. 

10. For CHARACTER functions, an additional argument is passed. This argument is the address of 

the string descriptor for the result. Note that the address of the string descriptor can be passed in 
any of the registers that are used to pass actual arguments. 

11. For functions that return a user-defined structure, space is allocated on the stack by the caller for 
the return value. Register SI is set to point to the destination of the result. The called function 
places the result at the location pointed to by register SI. Note that a structure of size 1, 2 or 4 
bytes is returned in register AL, AX or DX:AX respectively. 

10.2.2 Processing Function Return Values Using an 80x87 

The following describes the method used to return function values when your application is compiled using 
the "fpi87" or "fpi" option. 

1. For REAL*4 functions, the result is returned in floating-point register ST(0). 

2. For REAL*8 functions, the result is returned in floating-point register ST(0). 

3. All other function values are returned in the way described in the previous section. 

10.2.3 Processing Alternate Returns 

Alternate returns are processed by the caller and are only allowed in subroutines. The called subroutine 
places the value specified in the RETURN statement in register AX. Note that the value returned in 
register AX is ignored if there are no alternate return specifiers in the actual argument list. 

10.2.4 Alternate Method of Passing Character Arguments 

As previously described, character arguments are passed using string descriptors. Recall that a string 
descriptor contains a pointer to the actual character data and the length of the character data. When passing 
character data, both a pointer and length are required by the subprogram being called. When using a string 
descriptor, this information can be passed using a single argument, namely the pointer to the string 
descriptor. 

An alternate method of passing character arguments is also supported and is selected when the 
"nodescriptor" option is specified. In this method, the pointer to the character data and the length of the 
character data are passed as two separate arguments. The character argument lengths are appended to the 
end of the actual argument list. 
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Let us consider the following example. 

INTEGER A, C 

CHARACTER B, D 

CALL SUB( A, B, C, D ) 

In the above example, the first argument is of type INTEGER, the second argument is of type 
CHARACTER, the third argument is of type INTEGER, and the fourth argument is of type CHARACTER. 
If the character arguments were passed by descriptor, the argument list would resemble the following. 

1. The first argument would be the address of A. 

2. The second argument would be the address of the string descriptor for B. 

3. The third argument would be the address of C . 

4. The fourth argument would be the address of the string descriptor for D . 

If we specified the "nodescriptor" option, the argument list would be as follows. 

1. The first argument would be the address of A. 

2. The second argument would be the address of the character data for B. 

3. The third argument would be the address of C . 

4. The fourth argument would be the address of the character data for D . 

5. A hidden argument for the length of B would be the fifth argument. 

6. A hidden argument for the length of D would be the sixth argument. 

Note that the arguments corresponding to the length of the character arguments are passed as INTEGER*2 
arguments. 

10.2.4.1 Character Functions 

By default, when a character function is called, a hidden argument is passed at the end of the actual 
argument list. This hidden argument is a pointer to the string descriptor used for the return value of the 
character function. When the alternate method of passing character arguments is specified by using the 
"nodescriptor" option, the string descriptor for the return value is passed to the function as two hidden 
arguments, similar to the way character arguments were passed. However the two hidden arguments for the 
return value of the character function are placed at the beginning of the actual argument list. The first 
argument is the the pointer to the storage immediately followed by the size of the storage. 

10.3 Memory Layout 

The following describes the segment ordering of an application linked by the Open Watcom Linker. Note 
that this assumes that the "DOSSEG" linker option has been specified. 

1. all segments not belonging to group "DGROUP" with class "CODE" 

2. all other segments not belonging to group "DGROUP" 

3. all segments belonging to group "DGROUP" with class "BEGDATA" 

4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

5. all segments belonging to group "DGROUP" with class "BSS" 
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6. all segments belonging to group "DGROUP" with class "STACK" 

A special segment belonging to class "BEGDATA" is defined when linking with Open Watcom run-time 
libraries. This segment is initialized with the hexadecimal byte pattern "01" and is the first segment in 
group "DGROUP" so that storing data at location 0 can be detected. 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 

In addition to these special segments, the following conventions are used by Open Watcom F77. 

1. The "CODE" class contains the executable code for your application. In a small code model, this 
consists of the segment "_TEXT". In a big code model, this consists of the segments 
"<subprogram>_TEXT" where <subprogram> is the name of a subprogram. 

2. The "FAR_DATA" class consists of the following: 

(a) arrays whose size exceeds the data threshold in large data memory models (the 
data threshold is 256 bytes unless changed using the "dt" compiler option) 

(b) equivalenced variables in large data memory models 


10.4 Writing Assembly Language Subprograms 

When writing assembly language subprograms, use the following guidelines. 

1. All used registers must be saved on entry and restored on exit except those used to pass 
arguments and return values. Note that segment registers only have to be saved and restored if 
you are compiling your application with the "sr" option. 

2. The direction flag must be clear before returning to the caller. 

3. In a small code model, any segment containing executable code must belong to the segment 
"_TEXT" and the class "CODE". The segment "_TEXT" must have a "combine" type of 
"PUBLIC". On entry, register CS contains the segment address of the segment "_TEXT". In a 
big code model there is no restriction on the naming of segments which contain executable code. 

4. In a small data model, segment register DS contains the segment address of the default data 
segment (group "DGROUP"). In a big data model, segment register SS (not DS ) contains the 
segment address of the default data segment (group "DGROUP"). 

5. When writing assembly language subprograms for the small code model, you must declare them 
as "near". If you wish to write assembly language subprograms for the big code model, you 
must declare them as "far". 

6. Use the ".8087" pseudo-op so that floating-point constants are in the correct format. 

7. The called subprogram must remove arguments that were passed on the stack in the "ret" 
instruction. 


Writing Assembly Language Subprograms 105 




16-bit Topics 


8. In general, when naming segments for your code or data, you should follow the conventions 
described in the section entitled "Memory Layout" in this chapter. 


Consider the following example. 



GETTIM is an assembly language subroutine that gets the current time. It requires four integer arguments. 
The arguments are passed by reference so that the subroutine can return the hour, minute, seconds and 
hundredths of a second for the current time. These arguments will be passed to GETTIM in the following 
way. 

1. The address of the first argument will be passed in registers DX:AX. 

2. The address of the second argument will be passed in registers CX:BX. 

3. The address of the third argument will be passed on the stack. 

4. The address of the fourth argument will be passed on the stack. 

The following is an assembly language subprogram which implements GETTIM. 


Large Memory Model (big code, big data) 

GETTIM_ TEXT segment byte public 'CODE' 
assume CS:GETTIM_ TEXT 

public GETTIM 

GETTIM proc far 

push DI ; save register(s) 

push ES ; ... 

push DS ; ... 

push BP ; get addressability to arguments 

mov BP,SP ; . . . 

mov ES,DX ; ES:DI points to hours 

mov DI,AX ; ... 

mov DS,CX ; DS:BX points to minutes 

mov AH,2ch ; set DOS "get time" function 

int 21h ; issue DOS function call 

mov AL,CH ; get hours 

cbw ; ... 

mov ES:[DI],AX ; return hours 

sub AX,AX ; ... 

mov ES:2[DI],AX ; ... 

mov AL,CL ; get minutes 

cbw ; ... 

mov [BX],AX ; return minutes 

sub AX,AX ; ... 

mov 2[BX],AX ; ... 

mov DS,14[BP] ; get address of seconds 

mov DI,12[BP] ; ... 

mov AL,DH ; get seconds 

cbw ; ... 

mov [DI],AX ; return seconds 

sub AX,AX ; ... 

mov 2[DI],AX ; ... 

mov DS,18[BP] ; get address of ticks 

mov DI,16[BP] ; ... 

mov AL,DL ; get ticks 

cbw ; ... 
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GETTIM 

GETTIM. 


cwd 


; 

mov 

[DI],AX 

; return ticks 

mov 

2 [DI],DX 

; ... 

pop 

BP 

; restore register(s) 

pop 

DS 

; ... 

pop 

ES 

; ... 

pop 

DI 

; ... 

ret 

8 

; return 

endp 



TEXT 

ends 


end 




Notes: 

1. Two arguments were passed on the stack so a "ret 8" instruction is used to return to the caller. 

2. Registers AX, BX, CX and DX were not saved and restored since they were used to pass 
arguments. However, registers DS, ES, DI and BP were modified in the subprogram and hence 
must be saved and restored. 

Let us look at the stack upon entry to GETTIM. 

Large Model (big code, big data) 


Offset 

0 H-1- <- SP points here 

| return address | 

4 +-+ 

| argument #3 

8 + - + 

| argument #4 
12 +-+ 


Notes: 

1. The top element of the stack is a segment/offset pair forming a 32-bit return address. Hence, the 
third argument will be at offset 4 from the top of the stack and the fourth argument at offset 8. 

Register SP cannot be used as a base register to address the arguments on the stack. Register BP is 
normally used to address arguments on the stack. Upon entry to the subroutine, registers that are modified 
(except those used to pass arguments) are saved and register BP is set to point to the stack. After 
performing this prologue sequence, the stack looks like this. 
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Large Model (big code, big data) 


Offset 

0 H-H <- BP and SP point here 

| saved BP 

2 +-+ 

| saved DS 

4 +-+ 

| saved ES 

6 +-+ 

| saved DI 

8 +-+ 

| return address | 

12 +-+ 

| argument #3 

16 +-+ 

| argument #4 
20 +-+ 


As the above diagram shows, the third argument is at offset 12 from register BP and the fourth argument is 
at offset 16. 


10.4.1 Returning Values from Assembly Language Functions 

The following illustrates the way function values are to be returned from assembly language functions. 
1. A LOGICAL*l function. 

Ll_ TEXT segment byte public 'CODE' 



assume 

CS:L1 


public 

LI 

LI 

proc 

far 


mov 

AL, 1 


ret 


LI 

endp 


Ll_ 

. TEXT ends 



end 

2. A LOGICAL*4 function. 

L4_ TEXT segment byte public 'CODE' 



assume 

CS:L4 


public 

L4 

L4 

proc 

far 


mov 

AX, 0 


cwd 



ret 


L4 

endp 


L4_ 

. TEXT ends 



end 

3. An INTEGER* 1 function. 

Il_ TEXT segment byte public 'CODE' 
assume CS:I1_TEXT 
public II 
II proc far 
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mov AL,7 3 

ret 

II endp 

Il_ TEXT ends 
end 


4. An INTEGER*2 function. 

I2_ TEXT segment byte public 'CODE' 



assume 

CS : I2_ 1 


public 

12 

12 

proc 

far 


mov 

AX,7143 


ret 


12 

endp 


I2_ 

. TEXT ends 



end 


5. An INTEGER*4 function. 

I4_ TEXT segment byte public 'CODE' 



assume 

CS : I4_ 


public 

14 

14 

proc 

far 


mov 

AX,383 


cwd 



ret 


14 

endp 


I4_ 

TEXT ends 



end 



6. A REAL*4 function. 

.8087 

DGROUP group R4_ DATA 


R4_ TEXT segment byte public 'CODE' 



assume 

CS: R4_ TEXT 


assume 

SS:DGROUP 


public 

R4 

R4 

proc 

far 


mov 

AX,word ptr SS:R4Val 


mov 

DX,word ptr SS:R4Val+2 


ret 


R4 

endp 


R4_ 

TEXT ends 


R4_ 

DATA segment 

byte public 'DATA' 

R4Val dd 1314. 

3 


R4_ DATA ends 


end 


7. A REAL*8 function. 

.8087 


DGROUP group R8_ DATA 


R8_ 


R8 


TEXT segment byte public 'CODE' 
assume CS:R8_TEXT 
assume SS:DGROUP 
public R8 
proc far 

mov DX,word ptr SS:R8Val 
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mov CX,word ptr SS:R8Val+2 

mov BX,word ptr SS:R8Val+4 

mov AX,word ptr SS:R8Val+6 

ret 

R8 endp 

R8_ TEXT ends 

R8_ DATA segment byte public 'DATA' 
R8Val dq 103.3 
R8_ DATA ends 

end 


8. A COMPLEX*8 function. 

.8087 

DGROUP group C8_ DATA 

C8_ TEXT segment byte public 'CODE' 


assume 

CS: C8_ TEXT 

assume 

SS:DGROUP 

public 

C8 

proc 

far 

push 

DI 

push 

ES 

xchg 

DI, SI 

push 

SS 

pop 

ES 

mov 

SI,offset SS:C8Val 

movsw 


movsw 


movsw 


movsw 


pop 

ES 

pop 

DI 

ret 


endp 



C8_ TEXT ends 

C8_ DATA segment byte public 'DATA' 
C8Val dd 2.2 
dd 2.2 

C8_ DATA ends 
end 


9. A COMPLEX*16 function. 

.8087 

DGROUP group Cl 6_ DATA 

Cl6_ TEXT segment byte public 'CODE' 


assume 

CS : Cl 6_ TEXT 

assume 

SS:DGROUP 

public 

Cl 6 

proc 

far 

push 

DI 

push 

ES 

push 

CX 

xchg 

DI, SI 

push 

SS 

pop 

ES 

mov 

SI,offset SS:C16Val 

mov 

CX, 8 

repe 

movsw 

pop 

CX 

pop 

ES 

pop 

ret 

DI 
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Cl 6 endp 

Cl 6_ TEXT ends 

Cl6_ DATA segment byte public 'DATA' 

C16Val dq 3.3 
dq 3.3 
Cl 6_ DATA ends 

end 

10. A CHARACTER function. 

CHR_ TEXT segment byte public 'CODE' 
assume CS:CHR_TEXT 
public CHR 

CHR proc far 

push DI 

push ES 

mov ES,DX 

mov DI,AX 

les DI,ES:[DI] 

mov byte ptr ES:[DI],'F' 

pop ES 

pop DI 

ret 

CHR endp 

CHR_ TEXT ends 

end 

11. A function returning a user-defined structure. 

DGROUP group STRUCT_ DATA 

STRUCT_ TEXT segment byte public 'CODE' 
assume CS : STRUCT_ TEXT 
assume SS:DGROUP 

public C16 
STRUCT proc far 
push DI 
push ES 
push CX 
xchg DI,SI 

push SS 
pop ES 

mov SI,offset SS:StructVal 

mov CX,4 

repe movsw 

pop CX 

pop ES 

pop DI 

ret 

STRUCT endp 
STRUCT_ TEXT ends 

STRUCT_ DATA segment byte public 'DATA' 

StructVal dd 7 
dd 3 

STRUCT_ DATA ends 
end 

If you are using an 80x87 to return floating-point values, only assembly language functions of type 
REAL*4 and REAL*8 need to be modified. 

1. A REAL*4 function using an 80x87. 
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.8087 

DGROUP group R4_ DATA 


R4_ 

TEXT segment 

byte public 'CODE' 


assume 

CS: R4_ TEXT 


assume 

SS:DGROUP 


public 

R4 

R4 

proc 

far 


fid 

dword ptr SS:R4Val 


ret 


R4 

endp 


R4_ 

TEXT ends 



R4_ DATA segment byte public 'DATA' 
R4Val dd 1314.3 
R4_ DATA ends 

end 

2. A REAL*8 function using an 80x87. 

.8087 


DGROUP group R8_ DATA 


R8_ 

TEXT segment 

byte public 'CODE' 


assume 

CS :R8_ TEXT 


assume 

SS:DGROUP 


public 

R8 

R8 

proc 

far 


fid 

ret 

qword ptr SS:R8Val 

R8 

endp 


R8_ 

TEXT ends 



R8_ DATA segment byte public 'DATA' 

R8Val dq 103.3 
R8_ DATA ends 

end 

Notes: 

1. The ".8087" pseudo-op must be specified so that all floating-point constants are generated in 
8087 format. 

2. When returning values on the stack, remember to use a segment override to the stack segment 
(SS). 

The following is an example of a Open Watcom F77 program calling the above assembly language 
subprograms. 
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logical 11*1, 14*4 
integer il*l, i2*2, i4*4 
real r4*4, r8*8 
complex c8*8, cl6*16 
character chr 
structure /coord/ 
integer x, y 
end structure 
record /coord/ struct 
print *, 11 () 
print *, 14 () 
print *, il () 
print *, i2 () 
print *, i4 () 
print *, r4() 
print *, r8 () 
print *, c8 () 
print *, cl 6 () 
print *, chr() 
print *, struct() 
end 
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11.1 Introduction 

A pragma is a compiler directive that provides the following capabilities. 

• Pragmas can be used to direct the Open Watcom F77 code generator to emit specialized sequences 
of code for calling functions which use argument passing and value return techniques that differ from 
the default used by Open Watcom F77. 

• Pragmas can be used to describe attributes of functions (such as side effects) that are not possible at 
the FORTRAN 77 language level. The code generator can use this information to generate more 
efficient code. 

• Any sequence of in-line machine language instructions, including DOS and BIOS function calls, can 
be generated in the object code. 

Pragmas are specified in the source file using the pragma directive. The following notation is used to 
describe the syntax of pragmas. 

keywords A keyword is shown in a mono-spaced courier font. 

program-item A program-item is shown in a roman bold-italics font. A program-item is a symbol name 
or numeric value supplied by the programmer. 

punctuation A punctuation character shown in a mono-spaced courier font must be entered as 
is. 

A punctuation character shown in a roman bold-italics font is used to describe syntax. 

The following syntactical notation is used. 

[abc] The item abc is optional. 

{abc} The item abc may be repeated zero or more times, 

alblc One of a, b or c may be specified, 

a ::= b The item a is defined in terms of b. 

(a) Item a is evaluated first. 

The following classes of pragmas are supported. 

• pragmas that specify default libraries 

• pragmas that provide auxiliary information used for code generation 
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11.2 Using Pragmas to Specify Default Libraries 

Default libraries are specified in special object module records. Library names are extracted from these 
special records by the Open Watcom Linker. When unresolved references remain after processing all 
object modules specified in linker "FILE" directives, these default libraries are searched after all libraries 
specified in linker "LIBRARY" directives have been searched. 

By default, that is if no library pragma is specified, the Open Watcom F77 compiler generates, in the object 
file defining the main program, default libraries corresponding to the memory model and floating-point 
model used to compile the file. For example, if you have compiled the source file containing the main 
program for the medium memory model and the floating-point calls floating-point model, the library 
"flibm" will be placed in the object file. 

If you wish to add your own default libraries to this list, you can do so with a library pragma. Consider the 
following example. 

*$pragma library mylib 

The name "mylib" will be added to the list of default libraries specified in the object file. 

If you wish to specify more than one library in a library pragma you must separate them with spaces as in 
the following example. 

*$pragma library mylib \watcom\lib286\dos\graph.lib 
*$pragma library mylib \watcom\lib386\dos\graph.lib 

If no libraries are specified as in the following example, 

*$pragma library 

the run-time libraries corresponding to the memory and floating-point models used to compile the file will 
be generated. 

11.3 Auxiliary Pragmas 

The following sections describe the capabilities provided by auxiliary pragmas. 

The backslash character (’V) is used to continue a pragma on the next line. Text following the backslash 
character is ignored. The line continuing the pragma must start with a comment character (V, ’C’ or 

11.3.1 Specifying Symbol Attributes 

Auxiliary pragmas are used to describe attributes that affect code generation. Initially, the compiler defines 
a default set of attributes. Each auxiliary pragma refers to one of the following. 

1. a symbol (such as a variable or function) 

2. the default set of attributes defined by the compiler 

When an auxiliary pragma refers to a particular symbol, a copy of the current set of default attributes is 
made and merged with the attributes specified in the auxiliary pragma. The resulting attributes are assigned 
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to the specified symbol and can only be changed by another auxiliary pragma that refers to the same 
symbol. 

When "default" is specified instead of a symbol name, the attributes specified by the auxiliary pragma 
change the default set of attributes. The resulting attributes are used by all symbols that have not been 
specifically referenced by a previous auxiliary pragma. 

Note that all auxiliary pragmas are processed before code generation begins. Consider the following 
example. 

code in which symbol x is referenced 
*$pragma aux y <attrs_ 1> 
code in which symbol y is referenced 
code in which symbol z is referenced 
*$pragma aux default <attrs_ 2> 

*$pragma aux x <attrs_ 3> 

Auxiliary attributes are assigned to x, y and z in the following way. 

1. Symbol x is assigned the initial default attributes merged with the attributes specified by 
<attrs_ 2> and<attrs_ 3> . 

2. Symbol y is assigned the initial default attributes merged with the attributes specified by 
<attrs_ 1>. 

3. Symbol z is assigned the initial default attributes merged with the attributes specified by 
<attrs_ 2>. 

11.3.2 Alias Names 

When a symbol referred to by an auxiliary pragma includes an alias name, the attributes of the alias name 
are also assumed by the specified symbol. 

There are two methods of specifying alias information. In the first method, the symbol assumes only the 
attributes of the alias name; no additional attributes can be specified. The second method is more general 
since it is possible to specify an alias name as well as additional auxiliary information. In this case, the 
symbol assumes the attributes of the alias name as well as the attributes specified by the additional auxiliary 
information. 

The simple form of the auxiliary pragma used to specify an alias is as follows. 


*$pragma aux ( sym, alias ) 


where description: 

sym is any valid FORTRAN 77 identifier. 

alias is the alias name and is any valid FORTRAN 77 identifier. 

Consider the following example. 
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*$pragma aux value_ args parm (value) 

*$pragma aux ( rtn, value_ args ) 

The routine rtn assumes the attributes of the alias name push_ args which specifies that the arguments 
to rtn are passed by value. 

The general form of an auxiliary pragma that can be used to specify an alias is as follows. 


*$pragma aux ( alias ) sym aux_attrs 


where description: 

alias is the alias name and is any valid FORTRAN 77 identifier. 

sym is any valid FORTRAN 77 identifier. 

aux_attrs are attributes that can be specified with the auxiliary pragma. 
Consider the following example. 


*$pragma 

aux 

WC "* 

_ " parm (value) 

*$pragma 

aux 

(WC) 

rtnl 

*$pragma 

aux 

(WC) 

rtn2 

*$pragma 

aux 

(WC) 

rtn3 


The routines rtnl, rtn2 and rtn3 assume the same attributes as the alias name WC which defines the 
calling convention used by the Open Watcom C compiler. Whenever calls are made to rtnl, rtn2 and 
rtn3, the Open Watcom C calling convention will be used. Note that arguments must be passed by 
value. By default. Open Watcom F77 passes arguments by reference. 

Note that if the attributes of WC change, only one pragma needs to be changed. If we had not used an alias 
name and specified the attributes in each of the three pragmas for rtnl, rtn2 and rtn3, we would 
have to change all three pragmas. This approach also reduces the amount of memory required by the 
compiler to process the source file. 


WARNING! The alias name WC is just another symbol. If WC appeared in your source code, it would 
assume the attributes specified in the pragma for WC . 


11.3.3 Predefined Aliases 

A number of symbols are predefined by the compiler with a set of attributes that describe a particular 
calling convention. These symbols can be used as aliases. The following is a list of these symbols. 

_ cdecl _cdecl defines the calling convention used by Microsoft compilers. 

fgstcall _f astcall defines the calling convention used by Microsoft compilers. 

fortran _fortran defines the calling convention used by Open Watcom FORTRAN compilers. 
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_ pascal _pascal defines the calling convention used by OS/2 1.x and Windows 3.x API 

functions. 

_ stdcall _stdcall defines the calling convention used by Microsoft compilers. 

_ watcall _watcall defines the calling convention used by Open Watcom compilers. 

The following describes the attributes of the above alias names. 


11.3.3.1 Predefined "_cded" Alias 

*$pragma aux_cdecl *" \ 

c parm caller [] \ 

c value struct float struct routine [ax] \ 

c modify [ax bx cx dx es] 

Notes: 

1. All symbols are preceded by an underscore character. 

2. Arguments are pushed on the stack from right to left. That is, the last argument is pushed first. 
The calling routine will remove the arguments from the stack. 

3. Floating-point values are returned in the same way as structures. When a structure is returned, 
the called routine allocates space for the return value and returns a pointer to the return value in 
register AX. 

4. Registers AX, BX, CX and DX, and segment register ES are not saved and restored when a call 
is made. 

11.3.3.2 Predefined "_pascal" Alias 

*$pragma aux_pascal " A " \ 

c parm reverse routine [] \ 

c value struct float struct caller [] \ 

c modify [ax bx cx dx es] 

Notes: 

1. All symbols are mapped to upper case. 

2. Arguments are pushed on the stack in reverse order. That is, the first argument is pushed first, 
the second argument is pushed next, and so on. The routine being called will remove the 
arguments from the stack. 

3. Floating-point values are returned in the same way as structures. When a structure is returned, 
the caller allocates space on the stack. The address of the allocated space will be pushed on the 
stack immediately before the call instruction. Upon returning from the call, register AX will 
contain address of the space allocated for the return value. 

4. Registers AX, BX, CX and DX, and segment register ES are not saved and restored when a call 
is made. 
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11.3.3.3 Predefined ”_watcaH" Alias 

*$pragma aux_watcall " \ 

c parm routine [ax bx cx dx] \ 

c value struct caller 

Notes: 

1. Symbol names are followed by an underscore character. 

2. Arguments are processed from left to right. The leftmost arguments are passed in registers and 
the rightmost arguments are passed on the stack (if the registers used for argument passing have 
been exhausted). Arguments that are passed on the stack are pushed from right to left. The 
calling routine will remove the arguments if any were pushed on the stack. 

3. When a structure is returned, the caller allocates space on the stack. The address of the allocated 
space is put into SI register. The called routine then places the return value there. Upon 
returning from the call, register AX will contain address of the space allocated for the return 
value. 

4. Floating-point values are returned using 80x86 registers ("fpc" option) or using 80x87 
floating-point registers ("fpi" or "fpi87" option). 

5. All registers must be preserved by the called routine. 

11.3.4 Alternate Names for Symbols 

The following form of the auxiliary pragma can be used to describe the mapping of a symbol from its 
source form to its object form. 


*$pragma aux sym obj_name 


where description: 

sym is any valid FORTRAN 77 identifier. 

objjmme is any character string enclosed in double quotes. 

When specifying ob j_ name, some characters have a special meaning: 
where description: 

* is unmodified symbol name 

A is symbol name converted to uppercase 

/ is symbol name converted to lowercase 

# is a placeholder for "@nnn", where nnn is size of all function parameters on the stack; it is 

ignored for functions with variable argument lists, or for symbols that are not functions 
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\ next character is treated as literal 

Several examples of source to object form symbol name translation follow: By default, the upper case 
version "MYRTN" or "MYVAR" is placed in the object file. 

In the following example, the name "MyRtn" will be replaced by "MYRTN_" in the object file. 
*$pragma aux MyRtn " A _ " 

In the following example, the name "MyVar" will be replaced by "_MYVAR" in the object file. 
*$pragma aux MyVar "_ A " 

In the following example, the lower case version "myrtn" will be placed in the object file. 

*$pragma aux MyRtn "!" 

In the following example, the name "MyRtn" will be replaced by "_MyRtn@nnn" in the object file, "nnn" 
represents the size of all function parameters. 

*$pragma aux MyRtn *#" 

In the following example, the name "MyRtn" will be replaced by "_MyRtn#" in the object file. 

*$pragma aux MyRtn *\#" 

The default mapping for all symbols can also be changed as illustrated by the following example. 
*$pragma aux default A _ " 

The above auxiliary pragma specifies that all names will be prefixed and suffixed by an underscore 
character 

11.3.5 Describing Calling Information 

The following form of the auxiliary pragma can be used to describe the way a subprogram is to be called. 


*$pragma aux sym far 
or 

*$pragma aux sym near 
or 

*$pragma aux sym = in_line 

in line ::= { const I "asm" I (float fpinst)} 


where description: 

sym is a subprogram name. 

const is a valid FORTRAN 77 hexadecimal constant. 
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fpinst is a sequence of bytes that forms a valid 80x87 instruction. The keyword float must 

precede fpinst so that special fixups are applied to the 80x87 instruction. 

asm is an assembly language instruction or directive. 

In the following example. Open Watcom F77 will generate a far call to the subprogram myrtn . 
*$pragma aux myrtn far 

Note that this overrides the calling sequence that would normally be generated for a particular memory 
model. In other words, a far call will be generated even if you are compiling for a memory model with a 
small code model. 

In the following example. Open Watcom F77 will generate a near call to the subprogram myrtn. 
*$pragma aux myrtn near 

Note that this overrides the calling sequence that would normally be generated for a particular memory 
model. In other words, a near call will be generated even if you are compiling for a memory model with a 
big code model. 

In the following DOS example. Open Watcom F77 will generate the sequence of bytes following the "=" 
character in the auxiliary pragma whenever a call to mode 4 is encountered, mode4 is called an in-line 
subprogram. 


$pragma aux 

mode4 = 

\ 



zb4 zOO 


\ 

mov 

AH, 0 

zbO z04 


\ 

mov 

AL, 4 

zed zlO 
modify 

[ AH AL ] 

\ 

int 

lOh 


The sequence in the above DOS example represents the following lines of assembly language instructions. 

mov AH,0 ; select function "set mode" 

mov AL,4 ; specify mode (mode 4) 

int 10H ; BIOS video call 

The above example demonstrates how to generate BIOS function calls in-line without writing an assembly 
language function and calling it from your FORTRAN 77 program. 

The following DOS example is equivalent to the above example but mnemonics for the assembly language 
instructions are used instead of the binary encoding of the assembly language instructions. 

*$pragma aux mode4 = \ 

* "mov AH,0" \ 

* "mov AL,4" \ 

* "int 10H" \ 

* modify [ AH AL ] 

If a sequence of in-line assembly language instructions contains 80x87 floating-point instructions, each 
floating-point instruction must be preceded by "float". Note that this is only required if you have specified 
the "fpi" compiler option; otherwise it will be ignored. 

The following example generates the 80x87 "square root" instruction. 
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*$pragma aux mysqrt parm( value ) [8087] = \ 

* float zd9fa 

11.3.5.1 Loading Data Segment Register 

An application may have been compiled so that the segment register DS does not contain the segment 
address of the default data segment (group "DGROUP"). This is usually the case if you are using a large 
data memory model. Suppose you wish to call a subprogram that assumes that the segment register DS 
contains the segment address of the default data segment. It would be very cumbersome if you were forced 
to compile your application so that the segment register DS contained the default data segment (a small data 
memory model). 

The following form of the auxiliary pragma will cause the segment register DS to be loaded with the 
segment address of the default data segment before calling the specified subprogram. 


*$pragma aux sym parm loadds 


where description: 

sym is a subprogram name. 

Alternatively, the following form of the auxiliary pragma will cause the segment register DS to be loaded 
with the segment address of the default data segment as part of the prologue sequence for the specified 
subprogram. 


*$pragma aux sym loadds 


where description: 

sym is a subprogram name. 

11.3.5.2 Defining Exported Symbols in Dynamic Link Libraries 

An exported symbol in a dynamic link library is a symbol that can be referenced by an application that is 
linked with that dynamic link library. Normally, symbols in dynamic link libraries are exported using the 
Open Watcom Linker "EXPORT" directive. An alternative method is to use the following form of the 
auxiliary pragma. 


*$pragma aux sym export 


where description: 

sym is a subprogram name. 
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11.3.5.3 Defining Windows Callback Functions 

When compiling a Microsoft Windows application, you must use the "windows" option so that special 
prologue/epilogue sequences are generated. Furthermore, callback functions require larger 
prologue/epilogue sequences than those generated when the "windows" compiler option is specified. The 
following form of the auxiliary pragma will cause a callback prologue/epilogue sequence to be generated 
for a callback function when compiled using the "windows" option. 


*$pragma aux sym export 


where description: 

sym is a callback function name. 


11.3.6 Describing Argument Information 

Using auxiliary pragmas, you can describe the calling convention that Open Watcom F77 is to use for 
calling subprograms. This is particularly useful when interfacing to subprograms that have been compiled 
by other compilers or subprograms written in other programming languages. 

The general form of an auxiliary pragma that describes argument passing is the following. 


*$pragma aux sym parm { arg_info I pop_info I reverse {reg_set} } 

argjnfo ::= ( arg_attr {, arg_attr} ) 

arg_attr ::= value [v_attr] 

I reference [r_attr] 

I data_ reference [d_attr] 


v_attr ::= far 1 

near 1 *1 1 *2 1 *4 

1 *8 

r_attr ::= [far 

1 near] [descriptor 1 

nodescriptor] 

d_attr ::= [far 

1 near] 


pop_info ::= caller 1 routine 



where description: 

sym is a subprogram name. 

reg_set is called a register set. The register sets specify the registers that are to be used for 

argument passing. A register set is a list of registers separated by spaces and enclosed in 
square brackets. 
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11.3.6.1 Passing Arguments to non-FORTRAN Subprograms 

When calling a subprogram written in a different language, it may be necessary to provide the arguments in 
a form different than the default methods used by Open Watcom F77. For example, C functions require 
scalar arguments to be passed by value instead of by reference. For information on the methods Open 
Watcom F77 uses to pass arguments, see the chapter entitled "Assembly Language Considerations". 

The following form of the auxiliary pragma can be used to alter the default calling mechanism used for 
passing arguments. 


*$pragma aux sym parm ( arg_attr {, arg_attr} ) 

arg_attr ::= value [v_attr] 

I reference [r_attr] 

I data_ reference [d_attr] 


v_attr ::= far 1 

near 1 *1 1 *2 1 *4 

1 *8 

r_attr ::= [far 

1 near] [descriptor 1 

nodescriptor] 

d_attr ::= [far 

1 near] 



where description: 

sym is a subprogram name. 

REFERENCE specifies that arguments are to be passed by reference. For non-character arguments, the 

address is a pointer to the data. For character arguments, the address is a pointer to a string 
descriptor. See the chapter entitled "Assembly Language Considerations" for a description 
of a string descriptor. This is the default calling mechanism. If "NEAR" or "FAR" is 
specified, a near pointer or far pointer is passed regardless of the memory model used at 
compile-time. 

If the "DESCRIPTOR" attribute is specified, a pointer to the string descriptor is passed. 
This is the default. If the "NODESCRIPTOR" attribute is specified, a pointer to the the 
actual character data is passed instead of a pointer to the string descriptor. 

DATA_REFERENCE specifies that arguments are to be passed by data reference. For non-character 

items, this is identical to passing by reference. For character items, a pointer to the actual 
character data (instead of the string descriptor) is passed. If "NEAR" or "FAR" is 
specified, a near pointer or far pointer is passed regardless of the memory model used at 
compile-time. 

VALUE specifies that arguments are to be passed by value. Character arguments are treated 

specially when passed by value. Instead of passing a pointer to a string descriptor, a 
pointer to the actual character data is passed. See the chapter entitled "Assembly Language 
Considerations" for a description of a string descriptor. 
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Notes: 

1. Arrays and subprograms are always passed by reference, regardless of the argument attribute 
specified. 

2. When character arguments are passed by reference, the address of a string descriptor is passed. 
The string descriptor contains the address of the actual character data and the number of 
characters. When character arguments are passed by value or data reference, the address of the 
actual character data is passed instead of the address of a string descriptor. Character arguments 
are passed by value by specifying the "VALUE" or "DATA_REFERENCE" attribute. If 
"NEAR" or "FAR" is specified, a near pointer or far pointer to the character data is passed 
regardless of the memory model used at compile-time. 

3. When complex arguments are passed by value, the real part and the imaginary part are passed as 
two separate arguments. 

4. When an argument is a user-defined structure and is passed by value, a copy of the structure is 
made and passed as an argument. 

5. For scalar arguments, arguments of type INTEGER*1, INTEGER*2, INTEGER*4 ct, REAL 
or DOUBLE PRECISION, a length specification can be specified when the "VALUE" attribute 
is specified to pass the argument by value. This length specification refers to the size of the 
argument; the compiler will convert the actual argument to a type that matches the size. For 
example, if an argument of type REAL is passed to a subprogram that has an argument attribute 
of "VALUE*8", the argument will be converted to DOUBLE PRECISION. If an argument of 
type DOUBLE PRECISION is passed to a subprogram that has an argument attribute of 
"VALUE*4", the argument will be converted to REAL. If an argument of type INTEGER*4 is 
passed to a subprogram that has an argument attribute of "VALUE*2" or VALUE*1, the 
argument will be converted to INTEGER*2 or INTEGER* 1. If an argument of type 
INTEGER*2 is passed to a subprogram that has an argument attribute of "VALUE*4 or 
VALUE*1", the argument will be converted to INTEGER*4 or INTEGER*1. If an argument 
of type INTEGER*1 is passed to a subprogram that has an argument attribute of "VALUE*4 or 
VALUE*2", the argument will be converted to INTEGER*4 or INTEGER*2. 

6. If the number of arguments exceeds the number of entries in the argument-attribute list, the last 
attribute will be assumed for the remaining arguments. 

Consider the following example. 

*$pragma aux printf " parm (value) caller [] 

character cr/zOd/, nullchar/zOO/ 
call printf( 'values: %ld, %ld'//cr//nullchar, 

1 77, 31410 ) 

end 

The C "printf function is called with three arguments. The first argument is of type CHARACTER and is 
passed as a C string (address of actual data terminated by a null character). The second and third arguments 
are passed by value. Also note that "printf" is a function that takes a variable number of arguments, all 
passed on the stack (an empty register set was specified), and that the caller must remove the arguments 
from the stack. 
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11.3.6.2 Passing Arguments in Registers 

The following form of the auxiliary pragma can be used to specify the registers that are to be used to pass 
arguments to a particular subprogram. 


*$pragma aux sym parm {reg_set} 


where description: 

sym is a subprogram name. 

reg_set is called a register set. The register sets specify the registers that are to be used for 

argument passing. A register set is a list of registers separated by spaces and enclosed in 
square brackets. 

Register sets establish a priority for register allocation during argument list processing. Register sets are 
processed from left to right. However, within a register set, registers are chosen in any order. Once all 
register sets have been processed, any remaining arguments are pushed on the stack. 

Note that regardless of the register sets specified, only certain combinations of registers will be selected for 
arguments of a particular type. 

Note that arguments of type REAL and DOUBLE PRECISION are always pushed on the stack when the 
"fpi" or "fpi87" option is used. 

DOUBLE PRECISION 

Arguments of type DOUBLE PRECISION, when passed by value, can only be passed in 
the following register combination: AX:BX:CX:DX. For example, if the following 
register set was specified for a routine having an argument of type DOUBLE 
PRECISION, 

[AX BX SI DI] 

the argument would be pushed on the stack since a valid register combination for 8-byte 
arguments is not contained in the register set. Note that this method for passing arguments 
of type DOUBLE PRECISION is supported only when the "fpc" option is used. Note that 
this argument passing method does not include arguments of type COMPLEX*8 or 
user-defined structures whose size is 8 bytes when these arguments are passed by value. 

far pointer A far pointer can only be passed in one of the following register pairs: DX: AX, CX:BX, 
CX:AX, CX:SI, DX:BX, DI:AX, CX:DI, DX:SI, DI:BX, SI:AX, CX:DX, DX:DI, DI:SI, 
SI:BX, BX:AX, DS:CX, DS:DX, DS:DI, DS:SI, DS:BX, DS:AX, ES:CX, ES:DX, ES:DI, 
ES:SI, ES:BX or ES:AX. For example, if a far pointer is passed to a function with the 
following register set, 

[ES BP] 

the argument would be pushed on the stack since a valid register combination for a far 
pointer is not contained in the register set. Far pointers are used to pass arguments by 
reference in a big data memory model. 
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INTEGER*4, REAL 

The only registers that will be assigned to 4-byte arguments (e.g., arguments of type 
INTEGER*4, when passed by value) are: DX:AX, CX:BX, CX:AX, CX:SI, DX:BX, 
DLAX, CX:DI, DX:SI, DI:BX, STAX, CX:DX, DX:DI, DI:SI, SI:BX and BX:AX. For 
example, if the following register set was specified for a routine with one argument of type 

INTEGER*4, 

[ES DI] 

the argument would be pushed on the stack since a valid register combination for 4-byte 
arguments is not contained in the register set. Note that this argument passing method 
includes arguments of type REAL but only when the "fpc" option is used. 

INTEGER*2 The only registers that will be assigned to 2-byte arguments (e.g., arguments of type 
INTEGER*2 when passed by value or arguments passed by reference in a small data 
memory model) are: AX, BX, CX, DX, SI and DI. For example, if the following register 
set was specified for a routine with one argument of type INTEGER*2, 

[BP] 

the argument would be pushed on the stack since a valid register combination for 2-byte 
arguments is not contained in the register set. 

INTEGER*1 Arguments whose size is 1 byte (e.g., arguments of type INTEGER*1 when passed by 
value) are promoted to 2 bytes and are then assigned registers as if they were 2-byte 
arguments. 

others Arguments that do not fall into one of the above categories cannot be passed in registers 

and are pushed on the stack. Once an argument has been assigned a position on the stack, 
all remaining arguments will be assigned a position on the stack even if all register sets 
have not yet been exhausted. 

Notes: 

1. The default register set is [AX BX CX DX]. 

2. Specifying registers AH and AL is equivalent to specifying register AX. Specifying registers 
DH and DL is equivalent to specifying register DX. Specifying registers CH and CL is 
equivalent to specifying register CX. Specifying registers BH and BL is equivalent to specifying 
register BX. 

3. If you are compiling for a memory model with a small data model, any register combination 
containing register DS becomes illegal. In a small data model, segment register DS must remain 
unchanged as it points to the program’s data segment. 

Consider the following example. 

*$pragma aux myrtn parm (value) \ 

* [ax bx cx dx] [bp si] 

Suppose myrtn is a routine with 3 arguments each of type INTEGER. Note that the arguments are passed 
by value. 

1. The first argument will be passed in the register pair DX: AX. 
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2. The second argument will be passed in the register pair CX:BX. 

3. The third argument will be pushed on the stack since BP:SI is not a valid register pair for 
arguments of type INTEGER. 

It is possible for registers from the second register set to be used before registers from the first register set 
are used. Consider the following example. 

*$pragma aux myrtn parm (value) \ 

* [ax bx cx dx] [si di] 

Suppose myrtn is a routine with 3 arguments, the first of type INTEGER and the second and third of type 
INTEGER. Note that all arguments are passed by value. 

1. The first argument will be passed in the register AX. 

2. The second argument will be passed in the register pair CX:BX. 

3. The third argument will be passed in the register set D1:SI. 

Note that registers are no longer selected from a register set after registers are selected from subsequent 
register sets, even if all registers from the original register set have not been exhausted. 

An empty register set is permitted. All subsequent register sets appearing after an empty register set are 
ignored; all remaining arguments are pushed on the stack. 

Notes: 

1. If a single empty register set is specified, all arguments are passed on the stack. 

2. If no register set is specified, the default register set [AX BX CX DX] is used. 

11.3.6.3 Forcing Arguments into Specific Registers 

It is possible to force arguments into specific registers. Suppose you have a subprogram, say "mycopy", 
that copies data. The first argument is the source, the second argument is the destination, and the third 
argument is the length to copy. If we want the first argument to be passed in the register SI, the second 
argument to be passed in register DI and the third argument to be passed in register CX, the following 
auxiliary pragma can be used. 

*$pragma aux mycopy parm (value) \ 

* [SI] [DI] [CX] 
character*10 dst 

call mycopy( dst, '0123456789', 10 ) 
end 

Note that you must be aware of the size of the arguments to ensure that the arguments get passed in the 
appropriate registers. 

11.3.6.4 Passing Arguments to In-Line Subprograms 

For subprograms whose code is generated by Open Watcom F77 and whose argument list is described by 
an auxiliary pragma. Open Watcom F77 has some freedom in choosing how arguments are assigned to 
registers. Since the code for in-line subprograms is specified by the programmer, the description of the 
argument list must be very explicit. To achieve this. Open Watcom F77 assumes that each register set 
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corresponds to an argument. Consider the following DOS example of an in-line subprogram called 
scrollactivepgup. 


*$pragma aux scrollactivepgup = \ 

* "mov AH,6" \ 

* "int lOh" \ 

* parm (value) \ 


* [ch] [cl] [dh] [dl] [al] [bh] \ 

* modify [ah] 

The BIOS video call to scroll the active page up requires the following arguments. 

1. The row and column of the upper left corner of the scroll window is passed in registers CH and 
CL respectively. 

2. The row and column of the lower right corner of the scroll window is passed in registers DH and 
DL respectively. 

3. The number of lines blanked at the bottom of the window is passed in register AL. 

4. The attribute to be used on the blank lines is passed in register BH. 

When passing arguments. Open Watcom F77 will convert the argument so that it fits in the register(s) 
specified in the register set for that argument. For example, in the above example, if the first argument to 
scrollactivepgup was called with an argument whose type was INTEGER, it would first be 
converted to INTEGER*1 before assigning it to register CH. Similarly, if an in-line subprogram required 
its argument in register pair DX:AX and the argument was of type INTEGER*2, the argument would be 
converted to INTEGER*4 before assigning it to register pair DX:AX. 

In general. Open Watcom F77 assigns the following types to register sets. 

1. A register set consisting of a single 8-bit register (1 byte) is assigned a type of INTEGER*1. 

2. A register set consisting of a single 16-bit register (2 bytes) is assigned a type of INTEGER*2. 

3. A register set consisting of two 16-bit registers (4 bytes) is assigned a type of INTEGER*4. 

4. A register set consisting of four 16-bit registers (8 bytes) is assigned a type of DOUBLE 

PRECISION. 

If the size of an integer argument is larger than the size specified by the register set, the argument will be 
truncated to the required size. If the size of an integer argument is smaller than the size specified by the 
register set, the argument will be padded (to the left) with zeros. 

11.3.6.5 Removing Arguments from the Stack 

The following form of the auxiliary pragma specifies who removes from the stack arguments that were 
pushed on the stack. 
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*$pragma aux sym parm (caller I routine) 


where description: 

sym is a subprogram name. 

"caller" specifies that the caller will pop the arguments from the stack; "routine" specifies that the called 
routine will pop the arguments from the stack. If "caller" or "routine" is omitted, "routine" is assumed 
unless the default has been changed in a previous auxiliary pragma, in which case the new default is 
assumed. 

Consider the following example. It describes the pragma required to call the C "printf' function. 

*$pragma aux printf " parm (value) caller [] 

character cr/zOd/, nullchar/zOO/ 
call printf( 'value is %ld'//cr//nullchar, 

1 7143 ) 

end 

The first argument must be passed as a C string, a pointer to the actual character data terminated by a null 
character. By default, the address of a string descriptor is passed for arguments of type CHARACTER. 

See the chapter entitled "Assembly Language Considerations" for more information on string descriptors. 
The second argument is of type INTEGER and is passed by value. Also note that "printf" is a function that 
takes a variable number of arguments, all pushed on the stack (an empty register set was specified). 

11.3.6.6 Passing Arguments in Reverse Order 

The following form of the auxiliary pragma specifies that arguments are passed in the reverse order. 


*$pragma aux sym parm reverse 


where description: 

sym is a subprogram name. 

Normally, arguments are processed from left to right. The leftmost arguments are passed in registers and 
the rightmost arguments are passed on the stack (if the registers used for argument passing have been 
exhausted). Arguments that are passed on the stack are pushed from right to left. 

When arguments are reversed, the rightmost arguments are passed in registers and the leftmost arguments 
are passed on the stack (if the registers used for argument passing have been exhausted). Arguments that 
are passed on the stack are pushed from left to right. 

Reversing arguments is most useful for subprograms that require arguments to be passed on the stack in an 
order opposite from the default. The following auxiliary pragma demonstrates such a subprogram. 

*$pragma aux rtn parm reverse [] 
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11.3.7 Describing Subprogram Return Information 

Using auxiliary pragmas, you can describe the way functions are to return values. This is particularly 
useful when interfacing to functions that have been compiled by other compilers or functions written in 
other programming languages. 

The general form of an auxiliary pragma that describes the way a function returns its value is the following. 


*$pragma aux sym value {no8087 I reg_set I struct_info} 

struct_info ::= struct {float I struct I (routine I caller) I reg_set} 


where description: 

sym is a function name. 

reg_set is called a register set. The register sets specify the registers that are to be used for 

argument passing. A register set is a list of registers separated by spaces and enclosed in 
square brackets. 

11.3.7.1 Returning Subprogram Values in Registers 

The following form of the auxiliary pragma can be used to specify the registers that are to be used to return 
a function's value. 


*$pragma aux sym value reg_set 


where 

description: 

sym 

is a subprogram name. 

reg_set 

is a register set. 


Note that the method described below for returning values of type REAL or DOUBLE PRECISION is 
supported only when the "fpc" option is used. 

Depending on the type of the return value, only certain registers are allowed in reg_set. 

1- byte For 1-byte return values, only the following registers are allowed: AL, AH, DL, DH, BL, 

BH, CL or CH. If no register set is specified, register AL will be used. 

2- byte For 2-byte return values, only the following registers are allowed: AX, DX, BX, CX, SI or 

DI. If no register set is specified, register AX will be used. 

4-byte For 4-byte return values (except far pointers), only the following register pairs are allowed: 

DX:AX, CX:BX, CX:AX, CX:SI, DX:BX, DI:AX, CX:DI, DX:SI, DI:BX, SI:AX, 

CX:DX, DX:DI, DLSI, SI:BX or BX:AX. If no register set is specified, registers DX:AX 
will be used. This form of the auxiliary pragma is legal for functions of type REAL when 
using the "fpc" option only. 
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far pointer For functions that return far pointers, the following register pairs are allowed: DX: AX, 

CX:BX, CX:AX, CX:SI, DX:BX, DI:AX, CX:D1, DX:SI, DI:BX, SI:AX, CX:DX, DX:D1, 
DI:SI, SI:BX, BX:AX, DS:CX, DS:DX, DS:D1, DS:SI, DS:BX, DS:AX, ES:CX, ES:DX, 
ES:DI, ES:SI, ES:BX or ES:AX. If no register set is specified, the registers DX:AX will be 
used. 

8-byte For 8-byte return values (including functions of type DOUBLE PRECISION), only the 

following register combination is allowed: AX:BX:CX:DX. If no register set is specified, 
the registers AX:BX:CX:DX will be used. This form of the auxiliary pragma is legal for 
functions of type DOUBLE PRECISION when using the "fpc" option only. 

Notes: 

1. An empty register set is not allowed. 

2. If you are compiling for a memory model which has a small data model, any of the above 
register combinations containing register DS becomes illegal. In a small data model, segment 
register DS must remain unchanged as it points to the program’s data segment. 

11.3.7.2 Returning Structures and Complex Numbers 

Typically, structures and complex numbers are not returned in registers. Instead, the caller allocates space 
on the stack for the return value and sets register SI to point to it. The called routine then places the return 
value at the location pointed to by register SI. 

Complex numbers are not scalars but rather an ordered pair of real numbers. One can also view complex 
numbers as a structure containing two real numbers. 

The following form of the auxiliary pragma can be used to specify the register that is to be used to point to 
the return value. 


*$pragma aux sym value struct (callerlroutine) reg_set 


where 

description: 

sym 

is a subprogram name. 

reg_set 

is a register set. 


"caller" specifies that the caller will allocate memory for the return value. The address of the memory 
allocated for the return value is placed in the register specified in the register set by the caller before the 
function is called. If an empty register set is specified, the address of the memory allocated for the return 
value will be pushed on the stack immediately before the call and will be returned in register AX by the 
called routine. It is assumed that the memory for the return value is allocated from the stack segment (the 
stack segment is contained in segment register SS). 

"routine" specifies that the called routine will allocate memory for the return value. Upon returning to the 
caller, the register specified in the register set will contain the address of the return value. An empty 
register set is not allowed. 
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Only the following registers are allowed in the register set: AX, DX, BX, CX, SI or DI. Note that in a big 
data model, the address in the return register is assumed to be in the segment specified by the value in the 
SS segment register. 

If the size of the structure being returned is 1, 2 or 4 bytes, it will be returned in registers. The return 
register will be selected from the register set in the following way. 

1. A 1-byte structure will be returned in one of the following registers: AL, AH, DL, DH, BL, BH, 
CL or CH. If no register set is specified, register AL will be used. 

2. A 2-byte structure will be returned in one of the following registers: AX, DX, BX, CX, SI or DI. 
If no register set is specified, register AX will be used. 

3. A 4-byte structure will be returned in one of the following register pairs: DX:AX, CX:BX, 
CX:AX, CX:SI, DX:BX, DI:AX, CX:DI, DX:SI, DLBX, SI:AX, CX:DX, DX:DI, DLSI, SI:BX 
or BX:AX. If no register set is specified, register pair DX:AX will be used. 

The following form of the auxiliary pragma can be used to specify that structures whose size is 1, 2 or 4 
bytes are not to be returned in registers. Instead, the caller will allocate space on the stack for the sUucture 
return value and point register SI to it. 


*$pragma aux sym value struct struct 


where description: 

sym is a subprogram name. 

11.3.7.3 Returning Floating-Point Data 

There are a few ways available for specifying how the value for a function whose type is REAL or 
DOUBLE PRECISION is to be returned. 

The following form of the auxiliary pragma can be used to specify that function return values whose type is 
REAL or DOUBLE PRECISION are not to be returned in registers. Instead, the caller will allocate space 
on the stack for the return value and point register SI to it. 


*$pragma aux sym value struct float 


where description: 

sym is a function name. 

In other words, floating-point values are to be returned in the same way complex numbers are returned. 

The following form of the auxiliary pragma can be used to specify that function return values whose type is 
REAL or DOUBLE PRECISION are not to be returned in 80x87 registers when compiling with the "fpi" 
or "fpi87" option. Instead, the value will be returned in 80x86 registers. This is the default behaviour for 
the "fpc" option. Function return values whose type is REAL will be returned in registers DX:AX. 
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Function return values whose type is DOUBLE PRECISION will be returned in registers AX:BX:CX:DX. 
This is the default method for the "fpc" option. 


*$pragma aux sym value no8087 


where description: 

sym is a function name. 

The following form of the auxiliary pragma can be used to specify that function return values whose type is 
REAL or DOUBLE PRECISION are to be returned in ST(0) when compiling with the "fpi" or "fpi87" 
option. This form of the auxiliary pragma is not legal for the "fpc" option. 


*$pragma aux sym value [8087] 


where description: 

sym is a function name. 

11.3.8 A Subprogram that Never Returns 

The following form of the auxiliary pragma can be used to describe a subprogram that does not return to 
the caller. 

*$pragma aux sym aborts 


where description: 

sym is a subprogram name. 

Consider the following example. 

*$pragma aux exitrtn aborts 

call exitrtn() 
end 

exitrtn is defined to be a function that does not return. For example, it may call exit to return to the 
system. In this case. Open Watcom F77 generates a "jmp" instruction instead of a "call" instruction to 
invoke exitrtn. 
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11.3.9 Describing How Subprograms Use Variables in Common 

The following form of the auxiliary pragma can be used to describe a subprogram that does not modify any 
variable that appears in a common block defined by the caller. 


*$pragma aux sym modify nomemory 


where description: 

sym is a subprogram name. 

Consider the following example. 

integer i 
common /blk/ i 
while( i -It. 1000 )do 
i = i + 383 
endwhile 
call myrtn() 
i = i + 13143 
end 

block data 
common /blk/ i 
integer i/1033/ 
end 

To compile the above program, "rtn.for", we issue the following command. 

C>wfc rtn -mm -dl 
C>wfc386 rtn -dl 

The "dl" compiler option is specified so that the object file produced by Open Watcom F77 contains source 
line information. 

We can generate a file containing a disassembly of rtn. ob j by issuing the following command. 

C>wdis rtn -1 -s -r 

The "s" option is specified so that the listing file produced by the Open Watcom Disassembler contains 
source lines taken from rtn.for. The listing file rtn. 1st appears as follows. 

Let us add the following auxiliary pragma to the source file. 

*$pragma aux myrtn modify nomemory 

If we compile the source file with the above pragma and disassemble the object file using the Open 
Watcom Disassembler, we get the following listing file. 
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Module: rtn.for 

Group: 'DGROUP' _ DATA,LDATA,CDATA,BLK 
Segment: ' FMAIN_ TEXT' BYTE 00000024 bytes 


*$pragma aux myrtn modify nomemory 


0000 

integer*2 i 
common /blk/ i 

52 

FMAIN 

push 

dx 

0001 

8b 16 00 00 


mov 

dx, L3 

0005 

while ( i .It. 1000 ) do 

81 fa e8 03 LI 

cmp 

dx,03e8H 

0009 

7d 06 


jge 

L2 

000b 

i = i + 383 
endwhile 

81 c2 7 f 01 


add 

dx,017fH 

OOOf 

eb f 4 


jmp 

LI 

0011 

call myrtn () 

89 16 00 00 

L2 

mov 

L3, dx 

0015 

9a 00 00 00 00 


call 

far MYRTN 

001a 

i = i + 13143 

81 c2 57 33 


add 

dx,3357H 

OOle 

89 16 00 00 


mov 

L3, dx 

0022 

end 

block data 
common /blk/ i 
integer*2 i/1033/ 
end 

5a 


pop 

dx 

0023 

cb 


retf 



No disassembly errors 
List of external symbols 


Symbol 


MYRTN 

00000016 



Segment: ' BLK' 

PARA 00000002 

bytes 


0000 09 04 


L3 

- . . 

No disassembly 

errors 



List of public 

symbols 



SYMBOL 

GROUP 

SEGMENT 

ADDRESS 

FMAIN 


FMAIN_ TEXT 

00000000 


Notice that the value of i is in register DX after completion of the "while" loop. After the call to myrtn, 
the value of i is not loaded from memory into a register to perform the final addition. The auxiliary 
pragma informs the compiler that myrtn does not modify any variable that appears in a common block 
defined by Rtn and hence register DX contains the correct value of i . 

The preceding auxiliary pragma deals with routines that modify variables in common. Let us consider the 
case where routines reference variables in common. The following form of the auxiliary pragma can be 
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used to describe a subprogram that does not reference any variable that appears in a common block defined 
by the caller. 


*$pragma aux sym parm nomemory modify nomemory 


where 

description: 

sym 

is a subprogram name. 

Notes: 



1. You must specify both "parm nomemory" and "modify nomemory". 

Let us replace the auxiliary pragma in the above example with the following auxiliary pragma. 

*$pragma aux myrtn parm nomemory modify nomemory 

If you now compile our source file and disassemble the object file using WDIS, the result is the following 
listing file. 


Module: rtn.for 

Group: 'DGROUP' _ DATA,LDATA,CDATA, BLK 
Segment: ' FMAIN_ TEXT' BYTE 00000020 bytes 


*$pragma aux myrtn parm nomemory modify nomemory 


0000 

integer*2 i 
common /blk/ i 

52 FMAIN 

push 

dx 

0001 

8b 16 00 00 

mov 

dx, L3 

0005 

while ( i -It. 1000 )do 

81 fa e8 03 LI 

cmp 

dx,03e8H 

0009 

7d 06 

jge 

L2 

000b 

i = i + 383 
endwhile 

81 c2 If 01 

add 

dx,017fH 

OOOf 

eb f 4 

jmp 

LI 

0011 

call myrtn () 

9a 00 00 00 00 L2 

call 

far MYRTN 

0016 

i = i + 13143 

81 c2 57 33 

add 

dx,3357H 

001a 

89 16 00 00 

mov 

L3, dx 

OOle 

end 

block data 
common /blk/ i 
integer*2 i/1033/ 
end 

5a 

pop 

dx 

OOlf 

cb 

retf 



No disassembly errors 
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List of external symbols 
Symbol 


MYRTN 

00000012 



Segment: ' BLK' 

PARA 00000002 

bytes 


0000 09 04 


L3 

- . . 

No disassembly 

errors 



List of public 

symbols 



SYMBOL 

GROUP 

SEGMENT 

ADDRESS 

FMAIN 


FMAIN_ TEXT 

00000000 


Notice that after completion of the "while" loop we did not have to update i with the value in register DX 
before calling myrtn . The auxiliary pragma informs the compiler that myrtn does not reference any 
variable that appears in a common block defined by myrtn so updating i was not necessary before calling 
myrtn. 

11.3.10 Describing the Registers Modified by a Subprogram 

The following form of the auxiliary pragma can be used to describe the registers that a subprogram will use 
without saving. 


*$pragma aux sym modify [exact] reg_set 


where 

description: 

sym 

is a subprogram name. 

reg_set 

is a register set. 


Specifying a register set informs Open Watcom F77 that the registers belonging to the register set are 
modified by the subprogram. That is, the value in a register before calling the subprogram is different from 
its value after execution of the subprogram. 

Registers that are used to pass arguments are assumed to be modified and hence do not have to be saved 
and restored by the called subprogram. Also, since the AX register is frequently used to return a value, it is 
always assumed to be modified. If necessary, the caller will contain code to save and restore the contents 
of registers used to pass arguments. Note that saving and restoring the contents of these registers may not 
be necessary if the called subprogram does not modify them. The following form of the auxiliary pragma 
can be used to describe exactly those registers that will be modified by the called subprogram. 
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*$pragma aux sym modify exact reg_set 


where 

description: 

sym 

is a subprogram name. 

reg_set 

is a register set. 


The above form of the auxiliary pragma tells Open Watcom F77 not to assume that the registers used to 
pass arguments will be modified by the called subprogram. Instead, only the registers specified in the 
register set will be modified. This will prevent generation of the code which unnecessarily saves and 
restores the contents of the registers used to pass arguments. 

Also, any registers that are specified in the value register set are assumed to be unmodified unless 
explicitly listed in the exact register set. In the following example, the code generator will not generate 
code to save and restore the value of the stack pointer register since we have told it that "GetSP" does not 
modify any register whatsoever. 

Example: 

*$ifdef _ 386_ 

*$pragma aux GetSP = value [esp] modify exact [] 

*$else 

*$pragma aux GetSP = value [sp] modify exact [] 

*$endif 

program main 
integer GetSP 

print *, 'Current SP =', GetSP() 
end 

11.3.11 Auxiliary Pragmas and the 80x87 

This section deals with those aspects of auxiliary pragmas that are specific to the 80x87. The discussion in 
this chapter assumes that one of the "fpi" or "fpi87" options is used to compile subprograms. The following 
areas are affected by the use of these options. 

1. passing floating-point arguments to functions, 

2. returning floating-point values from functions and 

3. which 80x87 floating-point registers are allowed to be modified by the called routine. 

11.3.11.1 Using the 80x87 to Pass Arguments 

By default, floating-point arguments are passed on the 80x86 stack. The 80x86 registers are never used to 
pass floating-point arguments when a subprogram is compiled with the "fpi" or "fpi87" option. However, 
they can be used to pass arguments whose type is not floating-point such as arguments of type "int". 

The following form of the auxiliary pragma can be used to describe the registers that are to be used to pass 
arguments to subprograms. 
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*$pragma aux sym parm {reg_set} 

where description: 

sym is a subprogram name. 

reg_set is a register set. The register set can contain 80x86 registers and/or the string "8087". 

Notes: 

1. If an empty register set is specified, all arguments, including floating-point arguments, will be 
passed on the 80x86 stack. 

When the string "8087" appears in a register set, it simply means that floating-point arguments can be 
passed in 80x87 floating-point registers if the source file is compiled with the "fpi" or "fpi87" option. 

Before discussing argument passing in detail, some general notes on the use of the 80x87 floating-point 
registers are given. 

The 80x87 contains 8 floating-point registers which essentially form a stack. The stack pointer is called ST 
and is a number between 0 and 7 identifying which 80x87 floating-point register is at the top of the stack. 
ST is initially 0. 80x87 instructions reference these registers by specifying a floating-point register number. 
This number is then added to the current value of ST. The sum (taken modulo 8) specifies the 80x87 
floating-point register to be used. The notation ST(n), where "n" is between 0 and 7, is used to refer to the 
position of an 80x87 floating-point register relative to ST. 

When a floating-point value is loaded onto the 80x87 floating-point register stack, ST is decremented 
(modulo 8), and the value is loaded into ST(0). When a floating-point value is stored and popped from the 
80x87 floating-point register stack, ST is incremented (modulo 8) and ST(1) becomes ST(0). The 
following illustrates the use of the 80x87 floating-point registers as a stack, assuming that the value of ST is 
4 (4 values have been loaded onto the 80x87 floating-point register stack). 


+-+ 

0 | 4th from top | ST(4) 

+-+ 

1 | 5th from top | ST(5) 

+-+ 

2 | 6th from top | ST(6) 

+-+ 

3 | 7th from top | ST(7) 

+-+ 

ST -> 4 | top of stack | ST(0) 

+-+ 

5 | 1st from top | ST(1) 

+-+ 

6 | 2nd from top | ST(2) 

+-+ 

7 | 3rd from top | ST(3) 

+-+ 


Starting with version 9.5, the Open Watcom compilers use all eight of the 80x87 registers as a stack. The 
initial state of the 80x87 register stack is empty before a program begins execution. 
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Note: For compatibility with code compiled with version 9.0 and earlier, you can compile with 

the "fpr" option. In this case only four of the eight 80x87 registers are used as a stack. 
These four registers were used to pass arguments. The other four registers form what was 
called the 80x87 cache. The cache was used for local floating-point variables. The state of 
the 80x87 registers before a program began execution was as follows. 

1. The four 80x87 floating-point registers that form the stack are uninitialized. 

2. The four 80x87 floating-point registers that form the 80x87 cache are initialized 
with zero. 

Hence, initially the 80x87 cache was comprised of ST(0), ST(1), ST(2) and ST(3). ST had 
the value 4 as in the above diagram. When a floating-point value was pushed on the stack 
(as is the case when passing floating-point arguments), it became ST(0) and the 80x87 
cache was comprised of ST(1), ST(2), ST(3) and ST(4). When the 80x87 stack was full, 
ST(0), ST(1), ST(2) and ST(3) formed the stack and ST(4), ST(5), ST(6) and ST(7) formed 
the 80x87 cache. Version 9.5 and later no longer use this strategy. 

The rules for passing arguments are as follows. 

1. If the argument is not floating-point, use the procedure described earlier in this chapter. 

2. If the argument is floating-point, and a previous argument has been assigned a position on the 
80x86 stack (instead of the 80x87 stack), the floating-point argument is also assigned a position 
on the 80x86 stack. Otherwise proceed to the next step. 

3. If the string "8087" appears in a register set in the pragma, and if the 80x87 stack is not full, the 
floating-point argument is assigned floating-point register ST(0) (the top element of the 80x87 
stack). The previous top element (if there was one) is now in ST(1). Since arguments are 
pushed on the stack from right to left, the leftmost floating-point argument will be in ST(0). 
Otherwise the floating-point argument is assigned a position on the 80x86 stack. 

Consider the following example. 

*$pragma aux myrtn parm (value) [8087]; 
real x 

double precision y 
integer*2 i 
integer j 
x = 7.7 
i = 7 
y = 77.77 
j = 77 

call myrtn( x, i, y, j ) 
end 

myrtn is an assembly language subprogram that requires four arguments. The first argument of type 
REAL (4 bytes), the second argument is of type INTEGER*2 (2 bytes), the third argument is of type 
DOUBLE PRECISION (8 bytes) and the fourth argument is of type INTEGER*4 (4 bytes). These 
arguments will be passed to myrtn in the following way. 

1. Since "8087" was specified in the register set, the first argument, being of type REAL, will be 
passed in an 80x87 floating-point register. 
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2. The second argument will be passed on the stack since no 80x86 registers were specified in the 
register set. 

3. The third argument will also be passed on the stack. Remember the following rule: once an 
argument is assigned a position on the stack, all remaining arguments will be assigned a position 
on the stack. Note that the above rule holds even though there are some 80x87 floating-point 
registers available for passing floating-point arguments. 

4. The fourth argument will also be passed on the stack. 

Let us change the auxiliary pragma in the above example as follows. 

*$pragma aux myrtn parm [ax 8087] 

The arguments will now be passed to myrtn in the following way. 

1. Since "8087" was specified in the register set, the first argument, being of type REAL will be 
passed in an 80x87 floating-point register. 

2. The second argument will be passed in register AX, exhausting the set of available 80x86 
registers for argument passing. 

3. The third argument, being of type DOUBLE PRECISION, will also be passed in an 80x87 
floating-point register. 

4. The fourth argument will be passed on the stack since no 80x86 registers remain in the register 
set. 

11.3.11.2 Using the 80x87 to Return Subprogram Values 

The following form of the auxiliary pragma can be used to describe a subprogram that returns a 
floating-point value in ST(0). 


*$pragma aux sym value reg_set 


where description: 

sym is a subprogram name. 

reg_set is a register set containing the string "8087", i.e. [8087], 

11.3.11.3 Preserving 80x87 Floating-Point Registers Across Calls 

The code generator assumes that all eight 80x87 floating-point registers are available for use within a 
subprogram unless the "fpr" option is used to generate backward compatible code (older Open Watcom 
compilers used four registers as a cache). The following form of the auxiliary pragma specifies that the 
floating-point registers in the 80x87 cache may be modified by the specified subprogram. 
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*$pragma aux sym modify reg_set 

where description: 

sym is a subprogram name. 

reg_set is a register set containing the string "8087", i.e. [8087]. 

This instructs Open Watcom F77 to save any local variables that are located in the 80x87 cache before 
calling the specified routine. 
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12 32-bit Memory Models 


12.1 Introduction 

This chapter describes the various 32-bit memory models supported by Open Watcom F77. Each memory 
model is distinguished by two properties; the code model used to implement subprogram calls and the data 
model used to reference data. 


12.2 32-bit Code Models 


There are two code models; 

1. the small code model and 

2. the big code model. 

A small code model is one in which all calls to subprograms are made with near calls. In a near call, the 
destination address is 32 bits and is relative to the segment value in segment register CS. Hence, in a small 
code model, all code comprising your program, including library subprograms, must be less than 4GB. 

A big code model is one in which all calls to subprograms are made with far calls. In a far call, the 
destination address is 48 bits (a 16-bit segment value and a 32-bit offset relative to the segment value). 

This model allows the size of the code comprising your program to exceed 4GB. 


Note: If your program contains less than 4GB of code, you should use a memory model that employs 
the small code model. This will result in smaller and faster code since near calls are smaller instructions 
and are processed faster by the CPU. 


12.3 32-bit Data Models 


There are two data models; 

1. the small data model and 

2. the big data model. 

A small data model is one in which all references to data are made with near pointers. Near pointers are 32 
bits; all data references are made relative to the segment value in segment register DS. Hence, in a small 
data model, all data comprising your program must be less than 4GB. 

A big data model is one in which all references to data are made with far pointers. Far pointers are 48 bits 
(a 16-bit segment value and a 32-bit offset relative to the segment value). This removes the 4GB limitation 
on data size imposed by the small data model. However, when a far pointer is incremented, only the offset 
is adjusted. Open Watcom F77 assumes that the offset portion of a far pointer will not be incremented 
beyond 4GB. The compiler will assign an object to a new segment if the grouping of data in a segment will 
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cause the object to cross a segment boundary. Implicit in this is the requirement that no individual object 
exceed 4GB. 


Note: If your program contains less than 4GB of data, you should use the small data model. This will 
result in smaller and faster code since references using near pointers produce fewer instructions. 


12.4 Summary of 32-bit Memory Models 

As previously mentioned, a memory model is a combination of a code model and a data model. The 
following table describes the memory models supported by Open Watcom F77. 


Memory 

Model 

Code 

Model 

Data 

Model 

Default 

Code 

Pointer 

Default 

Data 

Pointer 

flat 

small 

small 

near 

near 

small 

small 

small 

near 

near 

medium 

big 

small 

far 

near 

compact 

small 

big 

near 

far 

large 

big 

big 

far 

far 


12.5 Flat Memory Model 

In the flat memory model, the application’s code and data must total less than 4GB in size. Segment 
registers CS, DS, SS and ES point to the same linear address space (this does not imply that the segment 
registers contain the same value). That is, a given offset in one segment refers to the same memory location 
as that offset in another segment. Essentially, a flat model operates as if there were no segments. 

12.6 Mixed 32-bit Memory Model 

A mixed memory model application combines elements from the various code and data models. A mixed 
memory model application might be characterized as one that includes arrays which are larger than 4GB. 

For example, a medium memory model application that uses some arrays which exceed 4GB in total size 
can be described as a mixed memory model. In an application such as this, most of the data is in a 4GB 
segment (DGROUP) and hence can be referenced with near pointers relative to the segment value in 
segment register DS. This results in more efficient code being generated and better execution times than 
one can expect from a big data model. 
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12.7 Linking Applications for the Various 32-bit Memory 
Models 


Each memory model requires different run-time and floating-point libraries. Each library assumes a 
particular memory model and should be linked only with modules that have been compiled with the same 
memory model. The following table lists the libraries that are to be used to link an application that has 
been compiled for a particular memory model. Currently, only libraries for the flat/small memory model 
are provided. The following table lists the run-time libraries used by FORTRAN 77 and the compiler 
options that cause their use. 

1. The "Library" column specified the library name. 

2. The "Memory model" column indicates the compiler options that specify the memory model of 
the library. 

3. The "Floating-point column" indicates the compiler options that specify the floating-point model 
of the library. 

4. The "Calling convention" column indicates the compiler option that specifies the calling 
convention of the library (register-based or stack-based). 


Library 

Memory 

model 

Floating-point 

model 

Calling 

convention 

flib.lib 

/mf, 

/ms 

/fpc 



flibs.lib 

/mf, 

/ms 

/ fpc 


/sc 

flib7.lib 

/mf, 

/ms 

/ fpi. 

/fpi87 


flib7s.lib 

/mf, 

/ms 

/ fpi. 

/fpi87 

/sc 

clib3r.lib 

/mf, 

/ms 

/fpc. 

/fpi, /fpi87 


clib3r.lib 

/mf, 

/ms 

/fpc. 

/fpi, /fpi87 

/sc 

math387r.lib 

/mf, 

/ms 

/fpi. 

/fpi87 


math387s.lib 

/mf, 

/ms 

/fpi. 

/fpi87 

/sc 

math3r.lib 

/mf, 

/ms 

/fpc 



math3s.lib 

/mf, 

/ms 

/fpc 


/sc 

emu387.lib 

/mf, 

/ms 

/fpi 



noemu387.lib 

/mf, 

/ms 

/fpi87 



12.8 Memory Layout 

The following describes the segment ordering of an application linked by the Open Watcom Linker. Note 
that this assumes that the "DOSSEG" linker option has been specified. 

1. all "USE16" segments. These segments are present in applications that execute in both real 
mode and protected mode. They are first in the segment ordering so that the "REALBREAK" 
option of the "RUNTIME" directive can be used to separate the real-mode part of the application 
from the protected-mode part of the application. Currently, the "RUNTIME" directive is valid 
for Phar Lap executables only. 

2. all segments not belonging to group "DGROUP" with class "CODE" 

3. all other segments not belonging to group "DGROUP" 

4. all segments belonging to group "DGROUP" with class "BEGDATA" 

5. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

6. all segments belonging to group "DGROUP" with class "BSS" 
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7. all segments belonging to group "DGROUP" with class "STACK" 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 

In addition to these special segments, the following conventions are used by Open Watcom F77. 

1. The "CODE" class contains the executable code for your application. In a small code model, this 
consists of the segment "_TEXT". In a big code model, this consists of the segments 
"<subprogram>_TEXT" where <subprogram> is the name of a subprogram. 

2. The "FAR_DATA" class consists of the following: 

(a) arrays whose size exceeds the data threshold in large data memory models (the 
data threshold is 256 bytes unless changed using the "dt" compiler option) 

(b) equivalenced variables in large data memory models 
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13.1 Introduction 

This chapter will deal with the following topics. 

1. The memory layout of a program compiled by Open Watcom F77. 

2. The method for passing arguments and returning values. 

3. The two methods for passing floating-point arguments and returning floating-point values. 

One method is used when one of the Open Watcom F77 "fpi", "fpi87" or "fpi287" options is 
specified for the generation of in-line 80x87 instructions. When the "fpi" option is specified, an 
80x87 emulator is included from a math library if the application includes floating-point 
operations. When the "fpi87" or "fpi287" option is used exclusively, the 80x87 emulator will not 
be included. 

The other method is used when the Open Watcom F77 "fpc" option is specified. In this case, the 
compiler generates calls to floating-point support routines in the alternate math libraries. 

An understanding of the Intel 80x86 architecture is assumed. 

13.2 Calling Conventions 

The following sections describe the method used by Open Watcom F77 to pass arguments. 

The FORTRAN 77 language specifically requires that arguments be passed by reference. This means that 
instead of passing the value of an argument, its address is passed. This allows a called subprogram to 
modify the value of the actual arguments. The following illustrates the method used to pass arguments. 
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Type of Argument 

Method Used to Pass Argument 

non-character constant 

address of constant 

non-character expression 

address of value of expression 

non-character variable 

address of variable 

character constant 

address of string descriptor 

character expression 

address of string descriptor 

character variable 

address of string descriptor 

non-character array 

address of array 

non-character array element 

address of array 

character array 

address of string descriptor 

character array element 

address of string descriptor 

character substring 

address of string descriptor 

subprogram 

address of subprogram 

alternate return specifier 

no argument passed 

user-defined structure 

address of structure 


When passing a character array as an argument, the string descriptor contains the address of the first 
element of the array and the length of an element of the array. 

The address of arguments are either passed in registers or on the stack. The registers used to pass the 
address of arguments to a subprogram are EAX, EBX, ECX and EDX. The address of arguments are 
passed in the following way. 

1. The first argument is passed in register EAX, the second argument is passed in register EDX, the 
third argument is passed in register EBX, and the fourth argument is passed in register ECX. 

2. For any remaining arguments, their address is passed on the stack. Note that addresses of 
arguments are pushed on the stack from right to left. 

13.2.1 Stack-Based Calling Convention 

The previous section described a register-based calling convention in which registers were used to pass 
arguments to subprograms. A stack-based calling convention is another method that can be used to pass 
arguments. The calling convention is selected when the "sc" compiler option is specified. 

The most significant difference between the stack-based calling convention and the register-based calling 
convention is the way the arguments are passed. When using the stack-based calling conventions, no 
registers are used to pass arguments. Instead, all arguments are passed on the stack. 

13.2.2 Processing Function Return Values with no 80x87 

The way in which function values are returned is also dependent on the data type of the function. The 
following describes the method used to return function values. 

1. LOGICAL*l values are returned in register AL. 

2. LOGICAL*4 values are returned in register EAX. 

3. INTEGER*! values are returned in register AL. 
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4. INTEGER*2 values are returned in register AX. 

5. INTEGER*4 values are returned in register EAX. 

6. REAL*4 values are returned in register EAX. 

7. REAL*8 values are returned in registers EDX:EAX. 

8. For COMPLEX*8 functions, space is allocated on the stack by the caller for the return value. 
Register ESI is set to point to the destination of the result. The called function places the result 
at the location pointed to by register ESI. 

9. For COMPLEX*16 functions, space is allocated on the stack by the caller for the return value. 
Register ESI is set to point to the destination of the result. The called function places the result 
at the location pointed to by register ESI. 

10. For CHARACTER functions, an additional argument is passed. This argument is the address of 
the string descriptor for the result. Note that the address of the string descriptor can be passed in 
any of the registers that are used to pass actual arguments. 

11. For functions that return a user-defined structure, space is allocated on the stack by the caller for 
the return value. Register ESI is set to point to the destination of the result. The called function 
places the result at the location pointed to by register ESI. Note that a structure of size 1, 2 or 4 
bytes is returned in register AL, AX or EAX respectively. 


Note: The way in which a function returns its value does not change when the stack-based calling 
convention is used. 


13.2.3 Processing Function Return Values Using an 80x87 

The following describes the method used to return function values when your application is compiled using 
the "fpi87" or "fpi" option. 

1. For REAL*4 functions, the result is returned in floating-point register ST(0). 

2. For REAL*8 functions, the result is returned in floating-point register ST(0). 

3. All other function values are returned in the way described in the previous section. 


Note: When the stack-based calling convention is used, floating-point values are not returned using the 
80x87. REAL*4 values are returned in register EAX. REAL*8 values are returned in registers 
EDX:EAX. 


13.2.4 Processing Alternate Returns 

Alternate returns are processed by the caller and are only allowed in subroutines. The called subroutine 
places the value specified in the RETURN statement in register EAX. Note that the value returned in 
register EAX is ignored if there are no alternate return specifiers in the actual argument list. 
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Note: The way in which a alternate returns are processed does not change when the stack-based calling 
convention is used. 


13.2.5 Alternate Method of Passing Character Arguments 

As previously described, character arguments are passed using string descriptors. Recall that a string 
descriptor contains a pointer to the actual character data and the length of the character data. When passing 
character data, both a pointer and length are required by the subprogram being called. When using a string 
descriptor, this information can be passed using a single argument, namely the pointer to the string 
descriptor. 

An alternate method of passing character arguments is also supported and is selected when the 
"nodescriptor" option is specified. In this method, the pointer to the character data and the length of the 
character data are passed as two separate arguments. The character argument lengths are appended to the 
end of the actual argument list. 

Let us consider the following example. 

INTEGER A, C 

CHARACTER B, D 

CALL SUB( A, B, C, D ) 

In the above example, the first argument is of type INTEGER, the second argument is of type 
CHARACTER, the third argument is of type INTEGER, and the fourth argument is of type CHARACTER. 
If the character arguments were passed by descriptor, the argument list would resemble the following. 

1. The first argument would be the address of A. 

2. The second argument would be the address of the string descriptor for B. 

3. The third argument would be the address of C . 

4. The fourth argument would be the address of the string descriptor for D . 

If we specified the "nodescriptor" option, the argument list would be as follows. 

1. The first argument would be the address of A. 

2. The second argument would be the address of the character data for B. 

3. The third argument would be the address of C . 

4. The fourth argument would be the address of the character data for D . 

5. A hidden argument for the length of B would be the fifth argument. 

6. A hidden argument for the length of D would be the sixth argument. 

Note that the arguments corresponding to the length of the character arguments are passed as INTEGER*4 
arguments. 

13.2.5.1 Character Functions 

By default, when a character function is called, a hidden argument is passed at the end of the actual 
argument list. This hidden argument is a pointer to the string descriptor used for the return value of the 
character function. When the alternate method of passing character arguments is specified by using the 
"nodescriptor" option, the string descriptor for the return value is passed to the function as two hidden 
arguments, similar to the way character arguments were passed. However the two hidden arguments for the 
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return value of the character function are placed at the beginning of the actual argument list. The first 
argument is the the pointer to the storage immediately followed by the size of the storage. 

13.3 Memory Layout 

The following describes the segment ordering of an application linked by the Open Watcom Linker. Note 
that this assumes that the "DOSSEG" linker option has been specified. 

1. all "USE16" segments. These segments are present in applications that execute in both real 
mode and protected mode. They are first in the segment ordering so that the "REALBREAK" 
option of the "RUNTIME" directive can be used to separate the real-mode part of the application 
from the protected-mode part of the application. Currently, the "RUNTIME" directive is valid 
for Phar Lap executables only. 

2. all segments not belonging to group "DGROUP" with class "CODE" 

3. all other segments not belonging to group "DGROUP" 

4. all segments belonging to group "DGROUP" with class "BEGDATA" 

5. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

6. all segments belonging to group "DGROUP" with class "BSS" 

7. all segments belonging to group "DGROUP" with class "STACK" 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 

In addition to these special segments, the following conventions are used by Open Watcom F77. 

1. The "CODE" class contains the executable code for your application. In a small code model, this 
consists of the segment "_TEXT". In a big code model, this consists of the segments 
"<subprogram>_TEXT" where <subprogram> is the name of a subprogram. 

2. The "FAR_DATA" class consists of the following: 

(a) arrays whose size exceeds the data threshold in large data memory models (the 
data threshold is 256 bytes unless changed using the "dt" compiler option) 

(b) equivalenced variables in large data memory models 
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13.4 Writing Assembly Language Subprograms 

When writing assembly language subprograms, use the following guidelines. 

1. All used registers must be saved on entry and restored on exit except those used to pass 
arguments and return values. Note that segment registers only have to be saved and restored if 
you are compiling your application with the "sr" option. 

2. The direction flag must be clear before returning to the caller. 

3. In a small code model, any segment containing executable code must belong to the segment 
"_TEXT" and the class "CODE". The segment "_TEXT" must have a "combine" type of 
"PUBLIC". On entry, register CS contains the segment address of the segment "_TEXT". In a 
big code model there is no restriction on the naming of segments which contain executable code. 

4. In a small data model, segment register DS contains the segment address of the default data 
segment (group "DGROUP"). In a big data model, segment register SS (not DS ) contains the 
segment address of the default data segment (group "DGROUP"). 

5. When writing assembly language subprograms for the small code model, you must declare them 
as "near". If you wish to write assembly language subprograms for the big code model, you 
must declare them as "far". 

6. Use the ".8087" pseudo-op so that floating-point constants are in the correct format. 

7. The called subprogram must remove arguments that were passed on the stack in the "ret" 
instruction. 

8. In general, when naming segments for your code or data, you should follow the conventions 
described in the section entitled "Memory Layout" in this chapter. 

Consider the following example. 


INTEGER HRS, MINS, SECS, HSECS 
CALL GETTIM( HRS, MINS, SECS, HSECS ) 

PRINT 100, HRS, MINS, SECS, HSECS 
100 FORMAT( IX,12.2,12.2,12.2,12.2 } 
END 


GETTIM is an assembly language subroutine that gets the current time. It requires four integer arguments. 
The arguments are passed by reference so that the subroutine can return the hour, minute, seconds and 
hundredths of a second for the current time. These arguments will be passed to GETTIM in the following 
way. 

1. The address of the first argument will be passed in register EAX. 

2. The address of the second argument will be passed in register EDX. 

3. The address of the third argument will be passed in register EBX. 

4. The address of the fourth argument will be passed in register ECX. 

The following is an assembly language subprogram which implements GETTIM. 
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Small or Flat Memory Model (small code, small data) 


_ TEXT 

segment 

byte public 

'CODE' 


assume 

CSTEXT 



public 

GETTIM 


GETTIM 

proc 

near 



push 

EAX ; 

save registers modified by 


push 

ECX ; 

... DOS function call 


push 

EDX ; 



mov 

AH,2ch ; 

set DOS "get time" function 


int 

21h 

issue DOS function call 


movzx 

EAX,DH ; 

get seconds 


mov 

[EBX],EAX ; 

return seconds 


pop 

EBX ; 

get address of minutes 


movzx 

EAX,CL ; 

get minutes 


mov 

[EBX],EAX ; 

return minutes 


pop 

EBX ; 

get address of ticks 


movzx 

EAX,DL ; 

get ticks 


mov 

[EBX],EAX ; 

return ticks 


pop 

EBX ; 

get address of hours 


movzx 

EAX,CH ; 

get hours 


mov 

[EBX],EAX ; 

return hours 


ret 

; 

return 

GETTIM 

endp 



_ TEXT 

ends 




end 




Notes: 

1. No arguments were passed on the stack so a simple "ret" instruction is used to return to the 
caller. If a single argument was passed on the stack, a "ret 4" instruction would be required to 
return to the caller. 

2. Registers EAX, EBX, ECX and EDX were not saved and restored since they were used to pass 
arguments. 


13.4.1 Using the Stack-Based Calling Convention 

When writing assembly language subprograms that use the stack-based calling convention, use the 
following guidelines. 

1. All used registers, except registers EAX, ECX and EDX must be saved on entry and restored on 
exit. Also, if segment registers ES and DS are used, they must be saved on entry and restored on 
exit. Note that segment registers only have to be saved and restored if you are compiling your 
application with the "sr" option. 

2. The direction flag must be clear before returning to the caller. 

3. In a small code model, any segment containing executable code must belong to the segment 
"_TEXT" and the class "CODE". The segment "_TEXT" must have a "combine" type of 
"PUBLIC". On entry, register CS contains the segment address of the segment "_TEXT". In a 
big code model there is no restriction on the naming of segments which contain executable code. 

4. In a small data model, segment register DS contains the segment address of the default data 
segment (group "DGROUP"). In a big data model, segment register SS (not DS ) contains the 
segment address of the default data segment (group "DGROUP"). 

5. When writing assembly language subprograms for the small code model, you must declare them 
as "near". If you wish to write assembly language subprograms for the big code model, you 
must declare them as "far". 

6. Use the ".8087" pseudo-op so that floating-point constants are in the correct format. 

7. The caller will remove arguments that were passed on the stack. 
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8. In general, when naming segments for your code or data, you should follow the conventions 
described in the section entitled "Memory Layout" in this chapter. 

Consider the following example. 


INTEGER HRS, MINS, SECS, HSECS 
CALL GETTIM( HRS, MINS, SECS, HSECS ) 

PRINT 100, HRS, MINS, SECS, HSECS 
100 FORMAT( IX,12.2,12.2,12.2,12.2 } 
END 


GETTIM is an assembly language subroutine that gets the current time. It requires four integer arguments. 
The arguments are passed by reference so that the subroutine can return the hour, minute, seconds and 
hundredths of a second for the current time. These arguments will be passed to GETTIM on the stack. 

The following is an assembly language subprogram which implements GETTIM. 


Small or Flat Memory Model (small code, small data) 


TEXT 


GETTIM 


GETTIM 
_ TEXT 


segment 

byte public 

'CODE' 

assume 

CSTEXT 


public 

GETTIM 


proc 

near 


push 

EBP ; 

save registers 

mov 

EBP,ESP ; 


push 

ESI ; 


mov 

AH,2ch ; 

set DOS "get time" function 

int 

21h 

issue DOS function call 

movzx 

EAX,CH ; 

get hours 

mov 

ESI,8[EBP] ; 

get address of hours 

mov 

[ESI],EAX ; 

return hours 

movzx 

EAX,CL ; 

get minutes 

mov 

ESI,12[BP] ; 

get address of minutes 

mov 

[ESI],EAX ; 

return minutes 

movzx 

EAX,DH ; 

get seconds 

mov 

ESI,16[BP] ; 

get address of seconds 

mov 

[ESI],EAX ; 

return seconds 

movzx 

EAX,DL ; 

get ticks 

mov 

ESI,20[BP] ; 

get address of ticks 

mov 

[ESI],EAX ; 

return ticks 

pop 

ESI ; 

restore registers 

mov 

ESP,EBP ; 


pop 

EBP ; 


ret 

endp 

; 

return 


ends 

end 


Notes: 

1. The four arguments that were passed on the stack will be removed by the caller. 


2. Registers ESI and EBP were saved and restored since they were used in GETTIM. 


Let us look at the stack upon entry to GETTIM. 
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Offset 

0 H-t- <- ESP points here 

| return address | 

4 +-+ 

| argument #1 

8 +-+ 

| argument #2 

12 +-+ 

| argument #3 

16 +-+ 

| argument #4 
20 +-+ 


Notes: 

1. The top element of the stack is a the 32-bit return address. The first argument is at offset 4 from 
the top of the stack, the second argument at offset 8, the third argument at offset 12, and the 
fourth argument at offset 16. 

Register EBP is normally used to address arguments on the stack. Upon entry to the subroutine, registers 
that are modified (except registers EAX, ECX and EDX) are saved and register EBP is set to point to the 
stack. After performing this prologue sequence, the stack looks like this. 


Offset from EBP 

-4 H-1- <- ESP point here 

| saved ESI 

0 H-t- <- EBP point here 

| saved EBP 

4 +-+ 

| return address | 

8 +-+ 

| argument #1 

12 +-+ 

| argument #2 

16 +-+ 

| argument #3 

20 +-+ 

| argument #4 
24 +-+ 


As the above diagram shows, the first argument is at offset 8 from register EBP, the second argument is at 
offset 12, the third argument is at offset 16, and the fourth argument is at offset 20. 

13.4.2 Returning Values from Assembly Language Functions 

The following illustrates the way function values are to be returned from assembly language functions. 

Note: The way in which a function returns its value does not change when the stack-based calling 
convention is used. 


1. A LOGICAL*! function. 
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_ TEXT segment byte public 'CODE' 
assume CS:_TEXT 
public LI 

LI proc near 

mov AL,1 

ret 

LI endp 

_ TEXT ends 
end 

2. A LOGICAL*4 function. 

_ TEXT segment byte public 'CODE' 
assume CS:_TEXT 
public L4 

L4 proc near 

mov EAX,0 

ret 

L4 endp 

_ TEXT ends 
end 

3. An INTEGER* 1 function. 

_ TEXT segment byte public 'CODE' 
assume CS:_TEXT 
public II 

II proc near 

mov AL,7 3 

ret 

11 endp 

_ TEXT ends 

end 

4. An INTEGER*2 function. 

_ TEXT segment byte public 'CODE' 
assume CS:_TEXT 
public 12 

12 proc near 

mov AX,7143 

ret 

12 endp 

_ TEXT ends 
end 

5. An INTEGER*4 function. 

_ TEXT segment byte public 'CODE' 
assume CS:_TEXT 
public 14 

14 proc near 

mov EAX,383 

ret 

14 endp 

_ TEXT ends 
end 

6. A REAL*4 function. 
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.8087 



DGROUP 

group R4 

DATA 

_ TEXT 

segment 

byte public 'CODE' 


assume 

CSTEXT 


assume 

DS:DGROUP 


public 

R4 

R4 

proc 

near 


mov 

EAX,dword ptr R4Val 


ret 


R4 

endp 


_ TEXT 

ends 


R4_ DATA 

segment 

byte public 'DATA' 

R4Val 

dd 1314. 

3 

R4_ DATA 

ends 



end 



7. A REAL*8 function. 


.8087 



DGROUP 

group R8 

_ DATA 

_ TEXT 

segment 

byte public 'CODE' 


assume 

CSTEXT 


assume 

DS:DGROUP 


public 

R8 

R8 

proc 

near 


mov 

EAX,dword ptr R8Val 


mov 

EDX,dword ptr R8Val+4 


ret 


R8 

endp 


_ TEXT 

ends 


R8_ DATA 

segment 

byte public 'DATA' 

R8Val 

dq 103.3 


R8_ DATA 

ends 



end 



8. A COMPLEX*8 function. 


.8087 


DGROUP group C8_ DATA 


_ TEXT 

segment 

byte public 


assume 

CSTEXT 


assume 

DS:DGROUP 


public 

C8 

C8 

proc 

near 


push 

EAX 


mov 

EAX,C8Val 


mov 

[ESI],EAX 


mov 

EAX,C8Val+4 


mov 

4 [ESI],EAX 


pop 

ret 

EAX 

C8 

endp 


_ TEXT 

ends 


C8_ DATA 

segment 

byte public 

C8Val 

dd 2.2 

dd 2.2 


C8_ DATA 

ends 



'CODE' 


'DATA' 


end 
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9. A COMPLEX*16 function. 

.8087 


DGROUP 

group C16_ DATA 

_ TEXT 

segment 

byte public 'CODE' 


assume 

CSTEXT 


assume 

DS:DGROUP 


public 

Cl 6 

Cl 6 

proc 

near 


push 

EAX 


mov 

EAX,dword ptr C16Val 


mov 

[ESI],EAX 


mov 

EAX,dword ptr C16Val+4 


mov 

4[ESI],EAX 


mov 

EAX,dword ptr C16Val+8 


mov 

8[ESI],EAX 


mov 

EAX,dword ptr C16Val+12 


mov 

12[ESI],EAX 


pop 

EAX 


ret 


Cl 6 

endp 


_ TEXT 

ends 



Cl6_ DATA segment byte public 'DATA' 
C16Val dq 3.3 
dq 3.3 
Cl 6_ DATA ends 

end 


10. A CHARACTER function. 


TEXT segment byte public 'CODE' 



assume 

public 

CS 

CHR 

TEXT 

CHR 

proc 

push 

near 

EAX 



mov 

EAX, 

[EAX] 

CHR 

_ TEXT 

mov 

pop 

ret 

endp 

ends 

end 

byte 

EAX 

ptr [EAX] 


Remember, if you are using stack calling conventions (i.e., you specified the "sc" compiler 
option), arguments will be passed on the stack. The above character function must be modified 
as follows. 

_ TEXT segment byte public 'CODE' 



assume 

public 

CS 

CHR 

TEXT 

CHR 

proc 

push 

near 

EAX 



mov 

EAX, 

8[ESP] 


mov 

EAX, 

[EAX] 

CHR 
_ TEXT 

mov 

pop 

ret 

endp 

ends 

end 

byte 

EAX 

ptr [EAX] 


11. A function returning a user-defined structure. 
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DGROUP 

group STRUCT_ DATA 

_ TEXT 

segment 

byte public 'CODE' 


assume 

CSTEXT 


assume 

DS:DGROUP 


public 

STRUCT 

STRUCT 

proc 

near 


push 

EAX 


mov 

EAX,dword ptr StructVal 


mov 

[ESI],EAX 


mov 

EAX,dword ptr StructVal+4 


mov 

4[ESI],EAX 


pop 

ret 

EAX 

STRUCT 

endp 


_ TEXT 

ends 



STRUCT_ DATA segment byte public 'DATA' 
StructVal dd 7 
dd 3 

STRUCT_ DATA ends 
end 


If you are using an 80x87 to return floating-point values, only REAL*4 and REAL*8 assembly language 
functions need to be modified. Remember, this does not apply if you are using the stack-based calling 
convention. 

1. A REAL*4 function using an 80x87. 


.8087 



DGROUP 

group R4 

DATA 

_ TEXT 

segment 

byte public 'CODE' 


assume 

CSTEXT 


assume 

DS:DGROUP 


public 

R4 

R4 

proc 

near 


fid 

dword ptr R4Val 


ret 


R4 

endp 


_ TEXT 

ends 



R4_ DATA segment byte public 'DATA' 
R4Val dd 1314.3 
R4_ DATA ends 

end 

2. A REAL*8 function using an 80x87. 


.8087 



DGROUP 

group R8 

DATA 

_ TEXT 

segment 

byte public 'CODE' 


assume 

CSTEXT 


assume 

DS:DGROUP 


public 

R8 

R8 

proc 

near 


fid 

qword ptr R8Val 


ret 


R8 

endp 


_ TEXT 

ends 
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R8_ DATA segment byte public 'DATA' 

R8Val dq 103.3 
R8_ DATA ends 

end 

The following is an example of a Open Watcom F77 program calling the above assembly language 
subprograms. 

logical 11*1, 14*4 
integer il*l, i2*2, i4*4 
real r4*4, r8*8 
complex c8*8, cl6*16 
character chr 
structure /coord/ 
integer x, y 
end structure 
record /coord/ struct 
print *, 11() 
print *, 14() 
print *, il() 
print *, i2() 
print *, i4() 
print *, r4() 
print *, r8() 
print *, c8() 
print *, cl6() 
print *, chr() 
print *, struct!) 
end 
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14.1 Introduction 

A pragma is a compiler directive that provides the following capabilities. 

• Pragmas can be used to direct the Open Watcom F77 code generator to emit specialized sequences 
of code for calling functions which use argument passing and value return techniques that differ from 
the default used by Open Watcom F77. 

• Pragmas can be used to describe attributes of functions (such as side effects) that are not possible at 
the FORTRAN 77 language level. The code generator can use this information to generate more 
efficient code. 

• Any sequence of in-line machine language instructions, including DOS and BIOS function calls, can 
be generated in the object code. 

Pragmas are specified in the source file using the pragma directive. The following notation is used to 
describe the syntax of pragmas. 

keywords A keyword is shown in a mono-spaced courier font. 

program-item A program-item is shown in a roman bold-italics font. A program-item is a symbol name 
or numeric value supplied by the programmer. 

punctuation A punctuation character shown in a mono-spaced courier font must be entered as 
is. 

A punctuation character shown in a roman bold-italics font is used to describe syntax. 

The following syntactical notation is used. 

[abc] The item abc is optional. 

{abc} The item abc may be repeated zero or more times, 

alblc One of a, b or c may be specified, 

a ::= b The item a is defined in terms of b. 

(a) Item a is evaluated first. 

The following classes of pragmas are supported. 

• pragmas that specify default libraries 

• pragmas that provide auxiliary information used for code generation 
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14.2 Using Pragmas to Specify Default Libraries 

Default libraries are specified in special object module records. Library names are extracted from these 
special records by the Open Watcom Linker. When unresolved references remain after processing all 
object modules specified in linker "FILE" directives, these default libraries are searched after all libraries 
specified in linker "LIBRARY" directives have been searched. 

By default, that is if no library pragma is specified, the Open Watcom F77 compiler generates, in the object 
file defining the main program, default libraries corresponding to the memory model and floating-point 
model used to compile the file. For example, if you have compiled the source file containing the main 
program for the flat memory model and the floating-point calls floating-point model, the library "flib" will 
be placed in the object file. 

If you wish to add your own default libraries to this list, you can do so with a library pragma. Consider the 
following example. 

*$pragma library mylib 

The name "mylib" will be added to the list of default libraries specified in the object file. 

If you wish to specify more than one library in a library pragma you must separate them with spaces as in 
the following example. 

*$pragma library mylib \watcom\lib286\dos\graph.lib 
*$pragma library mylib \watcom\lib386\dos\graph.lib 

If no libraries are specified as in the following example, 

*$pragma library 

the run-time libraries corresponding to the memory and floating-point models used to compile the file will 
be generated. 

14.3 Auxiliary Pragmas 

The following sections describe the capabilities provided by auxiliary pragmas. 

The backslash character (’V) is used to continue a pragma on the next line. Text following the backslash 
character is ignored. The line continuing the pragma must start with a comment character (’c\ ’C’ or 

14.3.1 Specifying Symbol Attributes 

Auxiliary pragmas are used to describe attributes that affect code generation. Initially, the compiler defines 
a default set of attributes. Each auxiliary pragma refers to one of the following. 

1. a symbol (such as a variable or function) 

2. the default set of attributes defined by the compiler 

When an auxiliary pragma refers to a particular symbol, a copy of the current set of default attributes is 
made and merged with the attributes specified in the auxiliary pragma. The resulting attributes are assigned 
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to the specified symbol and can only be changed by another auxiliary pragma that refers to the same 
symbol. 

When "default" is specified instead of a symbol name, the attributes specified by the auxiliary pragma 
change the default set of attributes. The resulting attributes are used by all symbols that have not been 
specifically referenced by a previous auxiliary pragma. 

Note that all auxiliary pragmas are processed before code generation begins. Consider the following 
example. 

code in which symbol x is referenced 
*$pragma aux y <attrs_ 1> 
code in which symbol y is referenced 
code in which symbol z is referenced 
*$pragma aux default <attrs_ 2> 

*$pragma aux x <attrs_ 3> 

Auxiliary attributes are assigned to x, y and z in the following way. 

1. Symbol x is assigned the initial default attributes merged with the attributes specified by 
<attrs_ 2> and<attrs_ 3> . 

2. Symbol y is assigned the initial default attributes merged with the attributes specified by 
<attrs_ 1>. 

3. Symbol z is assigned the initial default attributes merged with the attributes specified by 
<attrs_ 2>. 

14.3.2 Alias Names 

When a symbol referred to by an auxiliary pragma includes an alias name, the attributes of the alias name 
are also assumed by the specified symbol. 

There are two methods of specifying alias information. In the first method, the symbol assumes only the 
attributes of the alias name; no additional attributes can be specified. The second method is more general 
since it is possible to specify an alias name as well as additional auxiliary information. In this case, the 
symbol assumes the attributes of the alias name as well as the attributes specified by the additional auxiliary 
information. 

The simple form of the auxiliary pragma used to specify an alias is as follows. 


*$pragma aux ( sym, alias ) 


where description: 

sym is any valid FORTRAN 77 identifier. 

alias is the alias name and is any valid FORTRAN 77 identifier. 

Consider the following example. 
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*$pragma aux value_ args parm (value) 

*$pragma aux ( rtn, value_ args ) 

The routine rtn assumes the attributes of the alias name push_ args which specifies that the arguments 
to rtn are passed by value. 

The general form of an auxiliary pragma that can be used to specify an alias is as follows. 


*$pragma aux ( alias ) sym aux_attrs 


where description: 

alias is the alias name and is any valid FORTRAN 77 identifier. 

sym is any valid FORTRAN 77 identifier. 

aux_attrs are attributes that can be specified with the auxiliary pragma. 
Consider the following example. 


*$pragma 

aux 

WC "* 

_ " parm (value) 

*$pragma 

aux 

(WC) 

rtnl 

*$pragma 

aux 

(WC) 

rtn2 

*$pragma 

aux 

(WC) 

rtn3 


The routines rtnl, rtn2 and rtn3 assume the same attributes as the alias name WC which defines the 
calling convention used by the Open Watcom C compiler. Whenever calls are made to rtnl, rtn2 and 
rtn3, the Open Watcom C calling convention will be used. Note that arguments must be passed by 
value. By default. Open Watcom F77 passes arguments by reference. 

Note that if the attributes of WC change, only one pragma needs to be changed. If we had not used an alias 
name and specified the attributes in each of the three pragmas for rtnl, rtn2 and rtn3, we would 
have to change all three pragmas. This approach also reduces the amount of memory required by the 
compiler to process the source file. 


WARNING! The alias name WC is just another symbol. If WC appeared in your source code, it would 
assume the attributes specified in the pragma for WC . 


14.3.3 Predefined Aliases 

A number of symbols are predefined by the compiler with a set of attributes that describe a particular 
calling convention. These symbols can be used as aliases. The following is a list of these symbols. 

_ cdecl _cdecl defines the calling convention used by Microsoft compilers. 

fgstcall _f astcall defines the calling convention used by Microsoft compilers. 

fortran _fortran defines the calling convention used by Open Watcom FORTRAN compilers. 
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_ pascal _pascal defines the calling convention used by OS/2 1.x and Windows 3.x API 

functions. 

_ stdcall _stdcall defines a special calling convention used by the Win32 API functions. 

_ syscall _syscall defines the calling convention used by the 32-bit OS/2 API functions. 

_ watcall _watcall defines the calling convention used by Open Watcom compilers. 

The following describes the attributes of the above alias names. 

14.3.3.1 Predefined "_cdecl" Alias 

*$pragma aux_cdecl *" \ 

c parm caller [] \ 

c value struct float struct routine [eax] \ 

c modify [eax ecx edx] 

Notes: 

1. All symbols are preceded by an underscore character. 

2. Arguments are pushed on the stack from right to left. That is, the last argument is pushed first. 
The calling routine will remove the arguments from the stack. 

3. Floating-point values are returned in the same way as structures. When a structure is returned, 
the called routine allocates space for the return value and returns a pointer to the return value in 
register EAX. 

4. Registers EAX, ECX and EDX are not saved and restored when a call is made. 

14.3.3.2 Predefined "__pascal" Alias 

*$pragma aux_pascal " A " \ 

c parm reverse routine [] \ 

c value struct float struct caller [] \ 

c modify [eax ebx ecx edx] 

Notes: 

1. All symbols are mapped to upper case. 

2. Arguments are pushed on the stack in reverse order. That is, the first argument is pushed first, 
the second argument is pushed next, and so on. The routine being called will remove the 
arguments from the stack. 

3. Floating-point values are returned in the same way as structures. When a structure is returned, 
the caller allocates space on the stack. The address of the allocated space will be pushed on the 
stack immediately before the call instruction. Upon returning from the call, register EAX will 
contain address of the space allocated for the return value. 

4. Registers EAX, EBX, ECX and EDX are not saved and restored when a call is made. 
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14.3.3.3 Predefined" stdcall" Alias 


*$pragma 

aux_stdcall 

*@nnn" \ 


c 

parm routine 

[] \ 


c 

value struct 

struct caller [ 

] \ 

c 

modify [eax 

ecx edx] 


Notes: 





1. All symbols are preceded by an underscore character. 

2. All C symbols (extern "C" symbols in C++) are suffixed by "@nnn" where "nnn" is the sum of 
the argument sizes (each size is rounded up to a multiple of 4 bytes so that char and short are size 
4). When the argument list contains the "@nnn" suffix is omitted. 

3. Arguments are pushed on the stack from right to left. That is, the last argument is pushed first. 
The called routine will remove the arguments from the stack. 

4. When a structure is returned, the caller allocates space on the stack. The address of the allocated 
space will be pushed on the stack immediately before the call instruction. Upon returning from 
the call, register EAX will contain address of the space allocated for the return value. 
Floating-point values are returned in 80x87 register ST(0). 

5. Registers EAX, ECX and EDX are not saved and restored when a call is made. 

14.3.3.4 Predefined "_syscall" Alias 

*$pragma aux _syscall \ 

c parm caller [] \ 

c value struct struct caller [] \ 

c modify [eax ecx edx] 

Notes: 

1. Symbols names are not modified, that is, they are not adorned with leading or trailing 
underscores. 

2. Arguments are pushed on the stack from right to left. That is, the last argument is pushed first. 
The calling routine will remove the arguments from the stack. 

3. When a structure is returned, the caller allocates space on the stack. The address of the allocated 
space will be pushed on the stack immediately before the call instruction. Upon returning from 
the call, register EAX will contain address of the space allocated for the return value. 
Floating-point values are returned in 80x87 register ST(0). 

4. Registers EAX, ECX and EDX are not saved and restored when a call is made. 

14.3.3.5 Predefined "_watcall" Alias (register calling convention) 

*$pragma aux_watcall " \ 

c parm routine [eax ebx ecx edx] \ 

c value struct caller 
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Notes: 

1. Symbol names are followed by an underscore character. 

2. Arguments are processed from left to right. The leftmost arguments are passed in registers and 
the rightmost arguments are passed on the stack (if the registers used for argument passing have 
been exhausted). Arguments that are passed on the stack are pushed from right to left. The 
calling routine will remove the arguments if any were pushed on the stack. 

3. When a structure is returned, the caller allocates space on the stack. The address of the allocated 
space is put into ESI register. The called routine then places the return value there. Upon 
returning from the call, register EAX will contain address of the space allocated for the return 
value. 

4. Floating-point values are returned using 80x86 registers ("fpc" option) or using 80x87 
floating-point registers ("fpi" or "fpi87" option). 

5. All registers must be preserved by the called routine. 

14.3.3.6 Predefined "_watcall" Alias (stack calling convention) 

*$pragma aux _watcall "*" \ 

c parm caller [] \ 

c value no8087 struct caller \ 

c modify [eax ecx edx 8087] 

Notes: 

1. All symbols appear in object form as they do in source form. 

2. Arguments are pushed on the stack from right to left. That is, the last argument is pushed first. 
The calling routine will remove the arguments from the stack. 

3. When a structure is returned, the caller allocates space on the stack. The address of the allocated 
space will be pushed on the stack immediately before the call instruction. Upon returning from 
the call, register EAX will contain address of the space allocated for the return value. 

4. Floating-point values are returned only using 80x86 registers. 

5. Registers EAX, ECX and EDX are not preserved by the called routine. 

6. Any local variables that are located in the 80x87 cache are not preserved by the called routine. 

14.3.4 Alternate Names for Symbols 

The following form of the auxiliary pragma can be used to describe the mapping of a symbol from its 
source form to its object form. 
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*$pragma aux sym obj_name 

where description: 

sym is any valid FORTRAN 77 identifier. 

objjiame is any character string enclosed in double quotes. 

When specifying ob j_ name, some characters have a special meaning: 
where description: 

* is unmodified symbol name 

A is symbol name converted to uppercase 

/ is symbol name converted to lowercase 

# is a placeholder for "@nnn", where nnn is size of all function parameters on the stack; it is 
ignored for functions with variable argument lists, or for symbols that are not functions 

\ next character is treated as literal 

Several examples of source to object form symbol name translation follow: By default, the upper case 
version "MYRTN" or "MYVAR" is placed in the object file. 

In the following example, the name "MyRtn" will be replaced by "MYRTN_" in the object file. 
*$pragma aux MyRtn " A _ " 

In the following example, the name "MyVar" will be replaced by "_MYVAR" in the object file. 
*$pragma aux MyVar "_ A " 

In the following example, the lower case version "myrtn" will be placed in the object file. 

*$pragma aux MyRtn "!" 

In the following example, the name "MyRtn" will be replaced by "_MyRtn@nnn" in the object file, "nnn" 
represents the size of all function parameters. 

*$pragma aux MyRtn *#" 

In the following example, the name "MyRtn" will be replaced by "_MyRtn#" in the object file. 

*$pragma aux MyRtn *\#" 

The default mapping for all symbols can also be changed as illustrated by the following example. 
*$pragma aux default A _ " 

The above auxiliary pragma specifies that all names will be prefixed and suffixed by an underscore 
character 
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14.3.5 Describing Calling Information 

The following form of the auxiliary pragma can be used to describe the way a subprogram is to be called. 


*$pragma 

or 

aux 

sym 

far 

*$pragma 

or 

aux 

sym 

f arl 6 

*$pragma 

or 

aux 

sym 

near 

*$pragma 

aux 

sym 

= inline 


in line ::= { const I "asm" } 


where description: 

sym is a subprogram name. 

const is a valid FORTRAN 77 hexadecimal constant. 

asm is an assembly language instruction or directive. 

In the following example. Open Watcom F77 will generate a far call to the subprogram myrtn . 
*$pragma aux myrtn far 

Note that this overrides the calling sequence that would normally be generated for a particular memory 
model. In other words, a far call will be generated even if you are compiling for a memory model with a 
small code model. 

In the following example. Open Watcom F77 will generate a near call to the subprogram myrtn. 
*$pragma aux myrtn near 

Note that this overrides the calling sequence that would normally be generated for a particular memory 
model. In other words, a near call will be generated even if you are compiling for a memory model with a 
big code model. 

In the following DOS example. Open Watcom F77 will generate the sequence of bytes following the "=" 
character in the auxiliary pragma whenever a call to mode 4 is encountered, mode4 is called an in-line 
subprogram. 


$pragma aux 

mode4 = 

\ 



zb4 zOO 


\ 

mov 

AH, 0 

zbO z04 


\ 

mov 

AL, 4 

zed zlO 
modify 

[ AH AL ] 

\ 

int 

lOh 


The sequence in the above DOS example represents the following lines of assembly language instructions. 


mov AH,0 
mov AL,4 
int 10H 


select function "set mode" 
specify mode (mode 4) 

BIOS video call 
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The above example demonstrates how to generate BIOS function calls in-line without writing an assembly 
language function and calling it from your FORTRAN 77 program. 

The following DOS example is equivalent to the above example but mnemonics for the assembly language 
instructions are used instead of the binary encoding of the assembly language instructions. 


*$pragma aux mode4 = \ 

* "mov AH,0" \ 

* "mov AL,4" \ 

* "int 10H" \ 


* modify [ AH AL ] 

The f ar 16 attribute should only be used on systems that permit the calling of 16-bit code from 32-bit 
code. Currently, the only supported operating system that allows this is 32-bit OS/2. If you have any 
libraries of subprograms or APIs that are only available as 16-bit code and you wish to access these 
subprograms and APIs from 32-bit code, you must specify the f ar 16 attribute. If the f ar 16 attribute is 
specified, the compiler will generate special code which allows the 16-bit code to be called from 32-bit 
code. Note that a f ar 16 function must be a function whose attributes are those specified by one of the 
alias names_cdecl or. _ pascal. These alias names will be described in a later section. 

The file bsesub. fap in the \watcom\src\fortran\os2 directory contains examples of pragmas 
that use the f ar 16 attribute to describe the 16-bit VIO, KBD and MOU subsystems available in 32-bit 
OS/2. 

14.3.5.1 Loading Data Segment Register 

An application may have been compiled so that the segment register DS does not contain the segment 
address of the default data segment (group "DGROUP"). This is usually the case if you are using a large 
data memory model. Suppose you wish to call a subprogram that assumes that the segment register DS 
contains the segment address of the default data segment. It would be very cumbersome if you were forced 
to compile your application so that the segment register DS contained the default data segment (a small data 
memory model). 

The following form of the auxiliary pragma will cause the segment register DS to be loaded with the 
segment address of the default data segment before calling the specified subprogram. 


*$pragma aux sym parm loadds 


where description: 

sym is a subprogram name. 

Alternatively, the following form of the auxiliary pragma will cause the segment register DS to be loaded 
with the segment address of the default data segment as part of the prologue sequence for the specified 
subprogram. 


*$pragma aux sym loadds 
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where description: 

sym is a subprogram name. 

14.3.5.2 Defining Exported Symbols in Dynamic Link Libraries 

An exported symbol in a dynamic link library is a symbol that can be referenced by an application that is 
linked with that dynamic link library. Normally, symbols in dynamic link libraries are exported using the 
Open Watcom Linker "EXPORT" directive. An alternative method is to use the following form of the 
auxiliary pragma. 


*$pragma aux sym export 


where description: 

sym is a subprogram name. 


14.3.6 Describing Argument Information 

Using auxiliary pragmas, you can describe the calling convention that Open Watcom F77 is to use for 
calling subprograms. This is particularly useful when interfacing to subprograms that have been compiled 
by other compilers or subprograms written in other programming languages. 

The general form of an auxiliary pragma that describes argument passing is the following. 


*$pragma aux sym parm { arg_info I pop_info I reverse {reg_set} } 

argjnfo ::= ( arg_attr {, arg_attr} ) 

arg_attr ::= value [v_attr] 

I reference [r_attr] 

I data_ reference [d_attr] 


v_attr ::= far 1 

near 1 *1 1 *2 1 *4 

1 *8 

r_attr ::= [far 

1 near] [descriptor 1 

nodescriptor] 

d_attr ::= [far 

1 near] 


pop_info ::= caller 1 routine 



where description: 

sym is a subprogram name. 

reg_set is called a register set. The register sets specify the registers that are to be used for 

argument passing. A register set is a list of registers separated by spaces and enclosed in 
square brackets. 
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14.3.6.1 Passing Arguments to non-FORTRAN Subprograms 

When calling a subprogram written in a different language, it may be necessary to provide the arguments in 
a form different than the default methods used by Open Watcom F77. For example, C functions require 
scalar arguments to be passed by value instead of by reference. For information on the methods Open 
Watcom F77 uses to pass arguments, see the chapter entitled "Assembly Language Considerations". 

The following form of the auxiliary pragma can be used to alter the default calling mechanism used for 
passing arguments. 


*$pragma aux sym parm ( arg_attr {, arg_attr} ) 

arg_attr ::= value [v_attr] 

I reference [r_attr] 

I data_ reference [d_attr] 


v_attr ::= far 1 

near 1 *1 1 *2 1 *4 

1 *8 

r_attr ::= [far 

1 near] [descriptor 1 

nodescriptor] 

d_attr ::= [far 

1 near] 



where description: 

sym is a subprogram name. 

REFERENCE specifies that arguments are to be passed by reference. For non-character arguments, the 

address is a pointer to the data. For character arguments, the address is a pointer to a string 
descriptor. See the chapter entitled "Assembly Language Considerations" for a description 
of a string descriptor. This is the default calling mechanism. If "NEAR" or "FAR" is 
specified, a near pointer or far pointer is passed regardless of the memory model used at 
compile-time. 

If the "DESCRIPTOR" attribute is specified, a pointer to the string descriptor is passed. 
This is the default. If the "NODESCRIPTOR" attribute is specified, a pointer to the the 
actual character data is passed instead of a pointer to the string descriptor. 

DATA_REFERENCE specifies that arguments are to be passed by data reference. For non-character 

items, this is identical to passing by reference. For character items, a pointer to the actual 
character data (instead of the string descriptor) is passed. If "NEAR" or "FAR" is 
specified, a near pointer or far pointer is passed regardless of the memory model used at 
compile-time. 

VALUE specifies that arguments are to be passed by value. Character arguments are treated 

specially when passed by value. Instead of passing a pointer to a string descriptor, a 
pointer to the actual character data is passed. See the chapter entitled "Assembly Language 
Considerations" for a description of a string descriptor. 
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Notes: 

1. Arrays and subprograms are always passed by reference, regardless of the argument attribute 
specified. 

2. When character arguments are passed by reference, the address of a string descriptor is passed. 
The string descriptor contains the address of the actual character data and the number of 
characters. When character arguments are passed by value or data reference, the address of the 
actual character data is passed instead of the address of a string descriptor. Character arguments 
are passed by value by specifying the "VALUE" or "DATA_REFERENCE" attribute. If 
"NEAR" or "FAR" is specified, a near pointer or far pointer to the character data is passed 
regardless of the memory model used at compile-time. 

3. When complex arguments are passed by value, the real part and the imaginary part are passed as 
two separate arguments. 

4. When an argument is a user-defined structure and is passed by value, a copy of the structure is 
made and passed as an argument. 

5. For scalar arguments, arguments of type INTEGER*1, INTEGER*2, INTEGER*4 ct, REAL 
or DOUBLE PRECISION, a length specification can be specified when the "VALUE" attribute 
is specified to pass the argument by value. This length specification refers to the size of the 
argument; the compiler will convert the actual argument to a type that matches the size. For 
example, if an argument of type REAL is passed to a subprogram that has an argument attribute 
of "VALUE*8", the argument will be converted to DOUBLE PRECISION. If an argument of 
type DOUBLE PRECISION is passed to a subprogram that has an argument attribute of 
"VALUE*4", the argument will be converted to REAL. If an argument of type INTEGER*4 is 
passed to a subprogram that has an argument attribute of "VALUE*2" or VALUE*1, the 
argument will be converted to INTEGER*2 or INTEGER* 1. If an argument of type 
INTEGER*2 is passed to a subprogram that has an argument attribute of "VALUE*4 or 
VALUE*1", the argument will be converted to INTEGER*4 or INTEGER*1. If an argument 
of type INTEGER*1 is passed to a subprogram that has an argument attribute of "VALUE*4 or 
VALUE*2", the argument will be converted to INTEGER*4 or INTEGER*2. 

6. If the number of arguments exceeds the number of entries in the argument-attribute list, the last 
attribute will be assumed for the remaining arguments. 

Consider the following example. 

*$pragma aux printf " parm (value) caller [] 

character cr/zOd/, nullchar/zOO/ 
call printf( 'values: %ld, %ld'//cr//nullchar, 

1 77, 31410 ) 

end 

The C "printf function is called with three arguments. The first argument is of type CHARACTER and is 
passed as a C string (address of actual data terminated by a null character). The second and third arguments 
are passed by value. Also note that "printf" is a function that takes a variable number of arguments, all 
passed on the stack (an empty register set was specified), and that the caller must remove the arguments 
from the stack. 
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14.3.6.2 Passing Arguments in Registers 

The following form of the auxiliary pragma can be used to specify the registers that are to be used to pass 
arguments to a particular subprogram. 


*$pragma aux sym parm {reg_set} 


where description: 

sym is a subprogram name. 

reg_set is called a register set. The register sets specify the registers that are to be used for 

argument passing. A register set is a list of registers separated by spaces and enclosed in 
square brackets. 

Register sets establish a priority for register allocation during argument list processing. Register sets are 
processed from left to right. However, within a register set, registers are chosen in any order. Once all 
register sets have been processed, any remaining arguments are pushed on the stack. 

Note that regardless of the register sets specified, only certain combinations of registers will be selected for 
arguments of a particular type. 

Note that arguments of type REAL and DOUBLE PRECISION are always pushed on the stack when the 
"fpi" or "fpi87" option is used. 

DOUBLE PRECISION 

Arguments of type DOUBLE PRECISION, when passed by value, can only be passed in 
one of the following register pairs: EDX:EAX, ECX:EBX, ECX:EAX, ECX:ESI, 
EDX:EBX, EDLEAX, ECX:EDI, EDX:ESI, EDLEBX, ESEEAX, ECX:EDX, EDX:EDI, 
EDEESI, ESEEBX or EBX:EAX. For example, if the following register set was specified 
for a routine having an argument of type DOUBLE PRECISION, 

[EBP EBX] 

the argument would be pushed on the stack since a valid register combination for 8-byte 
arguments is not contained in the register set. Note that this method for passing arguments 
of type DOUBLE PRECISION is supported only when the "fpc" option is used. Note that 
this argument passing method does not include arguments of type COMPLEX*8 or 
user-defined structures whose size is 8 bytes when these arguments are passed by value. 

far pointer A far pointer can only be passed in one of the following register pairs: DX:EAX, CX:EBX, 

CX:EAX, CX:ESI, DX:EBX, DEEAX, CX:EDI, DX:ESI, DEEBX, SEEAX, CX:EDX, 
DX:ED1, DEESI, SEEBX, BX:EAX, FS:ECX, FS:EDX, FS:EDI, FS:ESI, FS:EBX, 
FS:EAX, GS:ECX, GS:EDX, GS:EDI, GS:ESI, GS:EBX, GS:EAX, DS:ECX, DS:EDX, 
DS:ED1, DS:ESI, DS:EBX, DS:EAX, ES:ECX, ES:EDX, ES:EDI, ES:ESI, ES:EBX or 
ES:EAX. For example, if a far pointer is passed to a function with the following register 
set. 


[ES EBP] 
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the argument would be pushed on the stack since a valid register combination for a far 
pointer is not contained in the register set. Far pointers are used to pass arguments by 
reference in a big data memory model. 

INTEGER The only registers that will be assigned to 4-byte arguments (e.g., arguments of type 
INTEGER when passed by value or arguments passed by reference in a small data 
memory model) are: EAX, EBX, ECX, EDX, ESI and EDI. For example, if the following 
register set was specified for a routine with one argument of type INTEGER, 

[EBP] 

the argument would be pushed on the stack since a valid register combination for 4-byte 
arguments is not contained in the register set. Note that this argument passing method also 
includes arguments of type REAL but only when the "fpc" option is used. 

INTEGER* 1, INTEGER*! 

Arguments whose size is 1 byte or 2 bytes (e.g., arguments of type INTEGER*! and 
INTEGER*2 as well as 2-byte structures when passed by value) are promoted to 4 bytes 
and are then assigned registers as if they were 4-byte arguments. 

others Arguments that do not fall into one of the above categories cannot be passed in registers 

and are pushed on the stack. Once an argument has been assigned a position on the stack, 
all remaining arguments will be assigned a position on the stack even if all register sets 
have not yet been exhausted. 

Notes: 

1. The default register set is [EAX EBX ECX EDX]. 

2. Specifying registers AH and AL is equivalent to specifying register AX. Specifying registers 
DH and DL is equivalent to specifying register DX. Specifying registers CH and CL is 
equivalent to specifying register CX. Specifying registers BH and BL is equivalent to specifying 
register BX. Specifying register EAX implies that register AX has been specified. Specifying 
register EBX implies that register BX has been specified. Specifying register ECX implies that 
register CX has been specified. Specifying register EDX implies that register DX has been 
specified. Specifying register EDI implies that register DI has been specified. Specifying 
register ESI implies that register SI has been specified. Specifying register EBP implies that 
register BP has been specified. Specifying register ESP implies that register SP has been 
specified. 

3. If you are compiling for a memory model with a small data model, any register combination 
containing register DS becomes illegal. In a small data model, segment register DS must remain 
unchanged as it points to the program’s data segment. 

4. If you are compiling for the flat memory model, any register combination containing DS or ES 
becomes illegal. In a flat memory model, code and data reside in the same segment. Segment 
registers DS and ES point to this segment and must remain unchanged. 

Consider the following example. 

*$pragma aux myrtn parm (value) \ 

* [eax ebx ecx edx] [ebp esi] 
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Suppose myrtn is a routine with 3 arguments each of type DOUBLE PRECISION. Note that the 
arguments are passed by value. 

1. The first argument will be passed in the register pair EDX:EAX. 

2. The second argument will be passed in the register pair ECX:EBX. 

3. The third argument will be pushed on the stack since EBP:ESI is not a valid register pair for 
arguments of type DOUBLE PRECISION. 

It is possible for registers from the second register set to be used before registers from the first register set 
are used. Consider the following example. 

*$pragma aux myrtn parm (value) \ 

* [eax ebx ecx edx] [esi edi] 

Suppose myrtn is a routine with 3 arguments, the first of type INTEGER and the second and third of type 
DOUBLE PRECISION. Note that all arguments are passed by value. 

1. The first argument will be passed in the register EAX. 

2. The second argument will be passed in the register pair ECX:EBX. 

3. The third argument will be passed in the register set EDLESI. 

Note that registers are no longer selected from a register set after registers are selected from subsequent 
register sets, even if all registers from the original register set have not been exhausted. 

An empty register set is permitted. All subsequent register sets appearing after an empty register set are 
ignored; all remaining arguments are pushed on the stack. 

Notes: 

1. If a single empty register set is specified, all arguments are passed on the stack. 

2. If no register set is specified, the default register set [EAX EBX ECX EDX] is used. 

14.3.6.3 Forcing Arguments into Specific Registers 

It is possible to force arguments into specific registers. Suppose you have a subprogram, say "mycopy", 
that copies data. The first argument is the source, the second argument is the destination, and the third 
argument is the length to copy. If we want the first argument to be passed in the register ESI, the second 
argument to be passed in register EDI and the third argument to be passed in register ECX, the following 
auxiliary pragma can be used. 

*$pragma aux mycopy parm (value) \ 

* [ESI] [EDI] [ECX] 
character*10 dst 

call mycopy( dst, '0123456789', 10 ) 
end 

Note that you must be aware of the size of the arguments to ensure that the arguments get passed in the 
appropriate registers. 
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14.3.6.4 Passing Arguments to In-Line Subprograms 

For subprograms whose code is generated by Open Watcom F77 and whose argument list is described by 
an auxiliary pragma. Open Watcom F77 has some freedom in choosing how arguments are assigned to 
registers. Since the code for in-line subprograms is specified by the programmer, the description of the 
argument list must be very explicit. To achieve this. Open Watcom F77 assumes that each register set 
corresponds to an argument. Consider the following DOS example of an in-line subprogram called 
scrollactivepgup. 


*$pragma aux scrollactivepgup = \ 

* "mov AH, 6" \ 

* "int lOh" \ 

* parm (value) \ 


* [ch] [cl] [dh] [dl] [al] [bh] \ 

* modify [ah] 

The BIOS video call to scroll the active page up requires the following arguments. 

1. The row and column of the upper left corner of the scroll window is passed in registers CFI and 
CL respectively. 

2. The row and column of the lower right corner of the scroll window is passed in registers DH and 
DL respectively. 

3. The number of lines blanked at the bottom of the window is passed in register AL. 

4. The attribute to be used on the blank lines is passed in register BH. 

When passing arguments. Open Watcom F77 will convert the argument so that it fits in the register(s) 
specified in the register set for that argument. For example, in the above example, if the first argument to 
scrollactivepgup was called with an argument whose type was INTEGER, it would first be 
converted to INTEGER*1 before assigning it to register CH. Similarly, if an in-line subprogram required 
its argument in register EAX and the argument was of type INTEGER*2, the argument would be 
converted to INTEGER*4 before assigning it to register EAX. 

In general. Open Watcom F77 assigns the following types to register sets. 

1. A register set consisting of a single 8-bit register (1 byte) is assigned a type of INTEGER*1. 

2. A register set consisting of a single 16-bit register (2 bytes) is assigned a type of INTEGER*2. 

3. A register set consisting of a single 32-bit register (4 bytes) is assigned a type of INTEGER*4. 

4. A register set consisting of two 32-bit registers (8 bytes) is assigned a type of DOUBLE 

PRECISION. 

If the size of an integer argument is larger than the size specified by the register set, the argument will be 
truncated to the required size. If the size of an integer argument is smaller than the size specified by the 
register set, the argument will be padded (to the left) with zeros. 
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14.3.6.5 Removing Arguments from the Stack 

The following form of the auxiliary pragma specifies who removes from the stack arguments that were 
pushed on the stack. 


*$pragma aux sym parm (caller I routine) 


where description: 

sym is a subprogram name. 

"caller" specifies that the caller will pop the arguments from the stack; "routine" specifies that the called 
routine will pop the arguments from the stack. If "caller" or "routine" is omitted, "routine" is assumed 
unless the default has been changed in a previous auxiliary pragma, in which case the new default is 
assumed. 

Consider the following example. It describes the pragma required to call the C "printf' function. 

*$pragma aux printf " parm (value) caller [] 

character cr/zOd/, nullchar/zOO/ 
call printf ( 'value is %ld'//cr//nullchar, 

1 7143 ) 

end 

The first argument must be passed as a C string, a pointer to the actual character data terminated by a null 
character. By default, the address of a string descriptor is passed for arguments of type CHARACTER. 

See the chapter entitled "Assembly Language Considerations" for more information on string descriptors. 
The second argument is of type INTEGER and is passed by value. Also note that "printf" is a function that 
takes a variable number of arguments, all pushed on the stack (an empty register set was specified). 

14.3.6.6 Passing Arguments in Reverse Order 

The following form of the auxiliary pragma specifies that arguments are passed in the reverse order. 


*$pragma aux sym parm reverse 


where description: 

sym is a subprogram name. 

Normally, arguments are processed from left to right. The leftmost arguments are passed in registers and 
the rightmost arguments are passed on the stack (if the registers used for argument passing have been 
exhausted). Arguments that are passed on the stack are pushed from right to left. 

When arguments are reversed, the rightmost arguments are passed in registers and the leftmost arguments 
are passed on the stack (if the registers used for argument passing have been exhausted). Arguments that 
are passed on the stack are pushed from left to right. 
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Reversing arguments is most useful for subprograms that require arguments to be passed on the stack in an 
order opposite from the default. The following auxiliary pragma demonstrates such a subprogram. 

*$pragma aux rtn parm reverse [] 

14.3.7 Describing Subprogram Return Information 

Using auxiliary pragmas, you can describe the way functions are to return values. This is particularly 
useful when interfacing to functions that have been compiled by other compilers or functions written in 
other programming languages. 

The general form of an auxiliary pragma that describes the way a function returns its value is the following. 


*$pragma aux sym value {no8087 I reg_set I struct_info} 

struct_info ::= struct {float I struct I (routine I caller) I reg_set} 


where description: 

sym is a function name. 

reg_set is called a register set. The register sets specify the registers that are to be used for 

argument passing. A register set is a list of registers separated by spaces and enclosed in 
square brackets. 

14.3.7.1 Returning Subprogram Values in Registers 

The following form of the auxiliary pragma can be used to specify the registers that are to be used to return 
a function's value. 


*$pragma aux sym value reg_set 


where 

description: 

sym 

is a subprogram name. 

reg_set 

is a register set. 


Note that the method described below for returning values of type REAL or DOUBLE PRECISION is 
supported only when the "fpc" option is used. 

Depending on the type of the return value, only certain registers are allowed in reg_set. 

1- byte For 1-byte return values, only the following registers are allowed: AL, AH, DL, DH, BL, 

BH, CL or CH. If no register set is specified, register AL will be used. 

2- byte For 2-byte return values, only the following registers are allowed: AX, DX, BX, CX, SI or 

DL If no register set is specified, register AX will be used. 
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4-byte For 4-byte return values (including near pointers), only the following register are allowed: 

EAX, EDX, EBX, ECX, ESI or EDI. If no register set is specified, register EAX will be 
used. This form of the auxiliary pragma is legal for functions of type REAL when using 
the "fpc" option only. 

far pointer For functions that return far pointers, the following register pairs are allowed: DX:EAX, 
CX:EBX, CX:EAX, CX:ESI, DX:EBX, DI:EAX, CX:EDI, DX:ESI, DI:EBX, SI:EAX, 
CX:EDX, DX:EDI, DEES I, SI:EBX, BX:EAX, FS:ECX, FS:EDX, FS:EDI, FS:ESI, 
FS:EBX, FS:EAX, GS:ECX, GS:EDX, GS:EDI, GS:ESI, GS:EBX, GS:EAX, DS:ECX, 
DS:EDX, DS:EDI, DS:ESI, DS:EBX, DS:EAX, ES:ECX, ES:EDX, ES:EDI, ES:ESI, 
ES:EBX or ES:EAX. If no register set is specified, the registers DX:EAX will be used. 

8-byte For 8-byte return values (including functions of type DOUBLE PRECISION), only the 

following register pairs are allowed: EDX:EAX, ECX:EBX, ECX:EAX, ECX:ESI, 
EDX:EBX, EDFEAX, ECX:EDI, EDX:ESI, EDLEBX, ESFEAX, ECX:EDX, EDX:EDI, 
EDFESI, ESFEBX or EBX:EAX. If no register set is specified, the registers EDX:EAX 
will be used. This form of the auxiliary pragma is legal for functions of type DOUBLE 
PRECISION when using the "fpc" option only. 

Notes: 

1. An empty register set is not allowed. 

2. If you are compiling for a memory model which has a small data model, any of the above 
register combinations containing register DS becomes illegal. In a small data model, segment 
register DS must remain unchanged as it points to the program’s data segment. 

3. If you are compiling for the flat memory model, any register combination containing DS or ES 
becomes illegal. In a flat memory model, code and data reside in the same segment. Segment 
registers DS and ES point to this segment and must remain unchanged. 

14.3.7.2 Returning Structures and Complex Numbers 

Typically, structures and complex numbers are not returned in registers. Instead, the caller allocates space 
on the stack for the return value and sets register ESI to point to it. The called routine then places the return 
value at the location pointed to by register ESI. 

Complex numbers are not scalars but rather an ordered pair of real numbers. One can also view complex 
numbers as a structure containing two real numbers. 

The following form of the auxiliary pragma can be used to specify the register that is to be used to point to 
the return value. 


*$pragma aux sym value struct (callerlroutine) reg_set 


where 

description: 

sym 

is a subprogram name. 

reg_set 

is a register set. 
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"caller" specifies that the caller will allocate memory for the return value. The address of the memory 
allocated for the return value is placed in the register specified in the register set by the caller before the 
function is called. If an empty register set is specified, the address of the memory allocated for the return 
value will be pushed on the stack immediately before the call and will be returned in register EAX by the 
called routine. 

"routine" specifies that the called routine will allocate memory for the return value. Upon returning to the 
caller, the register specified in the register set will contain the address of the return value. An empty 
register set is not allowed. 

Only the following registers are allowed in the register set: EAX, EDX, EBX, ECX, ESI or EDI. Note that 
in a big data model, the address in the return register is assumed to be in the segment specified by the value 
in the SS segment register. 

If the size of the structure being returned is 1, 2 or 4 bytes, it will be returned in registers. The return 
register will be selected from the register set in the following way. 

1. A 1-byte structure will be returned in one of the following registers: AL, AH, DL, DH, BL, BH, 
CL or CH. If no register set is specified, register AL will be used. 

2. A 2-byte structure will be returned in one of the following registers: AX, DX, BX, CX, SI or DI. 
If no register set is specified, register AX will be used. 

3. A 4-byte structure will be returned in one of the following registers: EAX, EDX, EBX, ECX, 
ESI or EDI. If no register set is specified, register EAX will be used. 

The following form of the auxiliary pragma can be used to specify that structures whose size is 1, 2 or 4 
bytes are not to be returned in registers. Instead, the caller will allocate space on the stack for the structure 
return value and point register ESI to it. 


*$pragma aux sym value struct struct 


where description: 

sym is a subprogram name. 

14.3.7.3 Returning Floating-Point Data 

There are a few ways available for specifying how the value for a function whose type is REAL or 
DOUBLE PRECISION is to be returned. 

The following form of the auxiliary pragma can be used to specify that function return values whose type is 
REAL or DOUBLE PRECISION are not to be returned in registers. Instead, the caller will allocate space 
on the stack for the return value and point register ESI to it. 


*$pragma aux sym value struct float 
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where description: 

sym is a function name. 

In other words, floating-point values are to be returned in the same way complex numbers are returned. 

The following form of the auxiliary pragma can be used to specify that function return values whose type is 
REAL or DOUBLE PRECISION are not to be returned in 80x87 registers when compiling with the "fpi" 
or "fpi87" option. Instead, the value will be returned in 80x86 registers. This is the default behaviour for 
the "fpc" option. Function return values whose type is REAL will be returned in register EAX. Function 
return values whose type is DOUBLE PRECISION will be returned in registers EDX:EAX. This is the 
default method for the "fpc" option. 


*$pragma aux sym value no8087 


where description: 

sym is a function name. 

The following form of the auxiliary pragma can be used to specify that function return values whose type is 
REAL or DOUBLE PRECISION are to be returned in ST(0) when compiling with the "fpi" or "fpi87" 
option. This form of the auxiliary pragma is not legal for the "fpc" option. 


*$pragma aux sym value [8087] 


where description: 

sym is a function name. 

14.3.8 A Subprogram that Never Returns 

The following form of the auxiliary pragma can be used to describe a subprogram that does not return to 
the caller. 

*$pragma aux sym aborts 


where description: 

sym is a subprogram name. 
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Consider the following example. 

*$pragma aux exitrtn aborts 

call exitrtn() 
end 

exitrtn is defined to be a function that does not return. For example, it may call exit to return to the 
system. In this case. Open Watcom F77 generates a "jmp" instruction instead of a "call" instruction to 
invoke exitrtn. 


14.3.9 Describing How Subprograms Use Variables in Common 

The following form of the auxiliary pragma can be used to describe a subprogram that does not modify any 
variable that appears in a common block defined by the caller. 


*$pragma aux sym modify nomemory 


where description: 

sym is a subprogram name. 

Consider the following example. 

integer i 
common /blk/ i 
while( i .It. 1000 )do 
i = i + 383 
endwhile 
call myrtn() 
i = i + 13143 
end 

block data 
common /blk/ i 
integer i/1033/ 
end 

To compile the above program, "rtn.for", we issue the following command. 

C>wfc rtn -mm -dl 
C>wfc386 rtn -dl 

The "dl" compiler option is specified so that the object file produced by Open Watcom F77 contains source 
line information. 

We can generate a file containing a disassembly of rtn. ob j by issuing the following command. 

C>wdis rtn -1 -s -r 

The "s" option is specified so that the listing file produced by the Open Watcom Disassembler contains 
source lines taken from rtn.for. The listing file rtn. 1st appears as follows. 
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Module: rtn.for 

Group: 'DGROUP' _ DATA,LDATA,CDATA,BLK 

Segment: ' FMAIN_ TEXT' BYTE USE32 00000036 bytes 


0000 

integer i 
common /blk/ i 

52 

FMAIN 

push 

edx 

0001 

8b 15 00 00 00 00 


mov 

edx,L3 

0007 

while( i .It. 1000 )do 

81 fa e8 03 00 00 LI 

cmp 

edx,000003e8H 

OOOd 

7d 08 


jge 

L2 

OOOf 

i = i + 383 
endwhile 

81 c2 7f 01 00 00 


add 

edx,0000017fH 

0015 

eb f 0 


jmp 

LI 

0017 

call myrtn () 

89 15 00 00 00 00 

L2 

mov 

L3,edx 

OOld 

e8 00 00 00 00 


call 

MYRTN 

0022 

8b 15 00 00 00 00 


mov 

edx,L3 

0028 

i = i + 13143 

81 c2 57 33 00 00 


add 

edx,00003357H 

002e 

89 15 00 00 00 00 


mov 

L3,edx 

0034 

end 

block data 
common /blk/ i 
integer i/1033/ 
end 

5a 


pop 

edx 

0035 

c3 


ret 



No disassembly errors 
List of external symbols 
Symbol 


MYRTN OOOOOOle 


Segment: ' BLK' 
0000 09 04 00 

No disassembly 

PARA USE32 
i 00 

errors 

00000004 bytes 

L3 

- — 

List of public 

symbols 



SYMBOL 

GROUP 

SEGMENT 

ADDRESS 

FMAIN 


FMAIN_ TEXT 

00000000 


Let us add the following auxiliary pragma to the source file. 

*$pragma aux myrtn modify nomemory 

If we compile the source file with the above pragma and disassemble the object file using the Open 
Watcorn Disassembler, we get the following listing file. 
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Module: rtn.for 

Group: 'DGROUP' _ DATA,LDATA,CDATA,BLK 


Segment: ' FMAIN_ TEXT' BYTE USE32 00000030 bytes 


$pragma aux myrtn modify nomemory 
integer i 
common /blk/ i 

0000 52 FMAIN 

push 

edx 

0001 

8b 15 00 00 00 00 

mov 

edx,L3 

0007 

while( i -It. 1000 )do 

81 fa e8 03 00 00 LI 

cmp 

edx,000003e8H 

OOOd 

7d 08 

jge 

L2 

OOOf 

i = i + 383 
endwhile 

81 c2 7f 01 00 00 

add 

edx,0000017fH 

0015 

eb f 0 

jmp 

LI 

0017 

call myrtn () 

89 15 00 00 00 00 L2 

mov 

L3,edx 

OOld 

e8 00 00 00 00 

call 

MYRTN 

0022 

i = i + 13143 

81 c2 57 33 00 00 

add 

edx,00003357H 

0028 

89 15 00 00 00 00 

mov 

L3,edx 

002e 

end 

block data 
common /blk/ i 
integer i/1033/ 
end 

5a 

pop 

edx 

002 f 

c3 

ret 



No disassembly errors 
List of external symbols 
Symbol 


MYRTN OOOOOOle 


Segment: ' BLK' 
0000 09 04 00 

No disassembly 

PARA USE32 
i 00 

errors 

00000004 bytes 

L3 

- — 

List of public 

symbols 



SYMBOL 

GROUP 

SEGMENT 

ADDRESS 

FMAIN 


FMAIN_ TEXT 

00000000 


Notice that the value of i is in register EDX after completion of the "while" loop. After the call to 
myrtn, the value of i is not loaded from memory into a register to perform the final addition. The 
auxiliary pragma informs the compiler that myrtn does not modify any variable that appears in a common 
block defined by Rtn and hence register EDX contains the correct value of i . 

The preceding auxiliary pragma deals with routines that modify variables in common. Let us consider the 
case where routines reference variables in common. The following form of the auxiliary pragma can be 
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used to describe a subprogram that does not reference any variable that appears in a common block defined 
by the caller. 


*$pragma aux sym parm nomemory modify nomemory 


where 

description: 

sym 

is a subprogram name. 

Notes: 



1. You must specify both "parm nomemory" and "modify nomemory". 

Let us replace the auxiliary pragma in the above example with the following auxiliary pragma. 

*$pragma aux myrtn parm nomemory modify nomemory 

If you now compile our source file and disassemble the object file using WDIS, the result is the following 
listing file. 

Module: rtn.for 

Group: 'DGROUP' _ DATA,LDATA,CDATA,BLK 

Segment: ' FMAIN_ TEXT' BYTE USE32 0000002a bytes 


*$pragma aux myrtn parm nomemory modify nomemory 


0000 

integer i 
common /blk/ i 

52 

FMAIN 

push 

edx 

0001 

8b 15 00 00 00 00 


mov 

edx,L3 

0007 

while( i .It. 1000 )do 

81 fa e8 03 00 00 LI 

cmp 

edx,000003e8H 

OOOd 

7d 08 


jge 

L2 

OOOf 

i = i + 383 
endwhile 

81 c2 If 01 00 00 


add 

edx,0000017fH 

0015 

eb f 0 


jmp 

LI 

0017 

call myrtn () 
e8 00 00 00 00 

L2 

call 

MYRTN 

001c 

i = i + 13143 

81 c2 57 33 00 00 


add 

edx,00003357H 

0022 

89 15 00 00 00 00 


mov 

L3,edx 

0028 

end 

block data 
common /blk/ i 
integer i/1033/ 
end 

5a 


pop 

edx 

0029 

c3 


ret 



No disassembly errors 
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List of external symbols 
Symbol 


MYRTN 00000018 


Segment: ' BLK' 
0000 09 04 00 

No disassembly 

PARA USE32 
i 00 

errors 

00000004 bytes 

L3 

- — 

List of public 

symbols 



SYMBOL 

GROUP 

SEGMENT 

ADDRESS 

FMAIN 


FMAIN_ TEXT 

00000000 


Notice that after completion of the "while" loop we did not have to update i with the value in register EDX 
before calling myrtn . The auxiliary pragma informs the compiler that myrtn does not reference any 
variable that appears in a common block defined by myrtn so updating i was not necessary before calling 
myrtn. 

14.3.10 Describing the Registers Modified by a Subprogram 

The following form of the auxiliary pragma can be used to describe the registers that a subprogram will use 
without saving. 


*$pragma aux sym modify [exact] reg_set 


where 

description: 

sym 

is a subprogram name. 

reg_set 

is a register set. 


Specifying a register set informs Open Watcom F77 that the registers belonging to the register set are 
modified by the subprogram. That is, the value in a register before calling the subprogram is different from 
its value after execution of the subprogram. 

Registers that are used to pass arguments are assumed to be modified and hence do not have to be saved 
and restored by the called subprogram. Also, since the EAX register is frequently used to return a value, it 
is always assumed to be modified. If necessary, the caller will contain code to save and restore the contents 
of registers used to pass arguments. Note that saving and restoring the contents of these registers may not 
be necessary if the called subprogram does not modify them. The following form of the auxiliary pragma 
can be used to describe exactly those registers that will be modified by the called subprogram. 
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*$pragma aux sym modify exact reg_set 


where 

description: 

sym 

is a subprogram name. 

reg_set 

is a register set. 


The above form of the auxiliary pragma tells Open Watcom F77 not to assume that the registers used to 
pass arguments will be modified by the called subprogram. Instead, only the registers specified in the 
register set will be modified. This will prevent generation of the code which unnecessarily saves and 
restores the contents of the registers used to pass arguments. 

Also, any registers that are specified in the value register set are assumed to be unmodified unless 
explicitly listed in the exact register set. In the following example, the code generator will not generate 
code to save and restore the value of the stack pointer register since we have told it that "GetSP" does not 
modify any register whatsoever. 

Example: 

*$ifdef _ 386_ 

*$pragma aux GetSP = value [esp] modify exact [] 

*$else 

*$pragma aux GetSP = value [sp] modify exact [] 

*$endif 

program main 
integer GetSP 

print *, 'Current SP =', GetSP() 
end 

14.3.11 Auxiliary Pragmas and the 80x87 

This section deals with those aspects of auxiliary pragmas that are specific to the 80x87. The discussion in 
this chapter assumes that one of the "fpi" or "fpi87" options is used to compile subprograms. The following 
areas are affected by the use of these options. 

1. passing floating-point arguments to functions, 

2. returning floating-point values from functions and 

3. which 80x87 floating-point registers are allowed to be modified by the called routine. 

14.3.11.1 Using the 80x87 to Pass Arguments 

By default, floating-point arguments are passed on the 80x86 stack. The 80x86 registers are never used to 
pass floating-point arguments when a subprogram is compiled with the "fpi" or "fpi87" option. However, 
they can be used to pass arguments whose type is not floating-point such as arguments of type "int". 

The following form of the auxiliary pragma can be used to describe the registers that are to be used to pass 
arguments to subprograms. 
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*$pragma aux sym parm {reg_set} 

where description: 

sym is a subprogram name. 

reg_set is a register set. The register set can contain 80x86 registers and/or the string "8087". 

Notes: 

1. If an empty register set is specified, all arguments, including floating-point arguments, will be 
passed on the 80x86 stack. 

When the string "8087" appears in a register set, it simply means that floating-point arguments can be 
passed in 80x87 floating-point registers if the source file is compiled with the "fpi" or "fpi87" option. 

Before discussing argument passing in detail, some general notes on the use of the 80x87 floating-point 
registers are given. 

The 80x87 contains 8 floating-point registers which essentially form a stack. The stack pointer is called ST 
and is a number between 0 and 7 identifying which 80x87 floating-point register is at the top of the stack. 
ST is initially 0. 80x87 instructions reference these registers by specifying a floating-point register number. 
This number is then added to the current value of ST. The sum (taken modulo 8) specifies the 80x87 
floating-point register to be used. The notation ST(n), where "n" is between 0 and 7, is used to refer to the 
position of an 80x87 floating-point register relative to ST. 

When a floating-point value is loaded onto the 80x87 floating-point register stack, ST is decremented 
(modulo 8), and the value is loaded into ST(0). When a floating-point value is stored and popped from the 
80x87 floating-point register stack, ST is incremented (modulo 8) and ST(1) becomes ST(0). The 
following illustrates the use of the 80x87 floating-point registers as a stack, assuming that the value of ST is 
4 (4 values have been loaded onto the 80x87 floating-point register stack). 


+-+ 

0 | 4th from top | ST(4) 

+-+ 

1 | 5th from top | ST(5) 

+-+ 

2 | 6th from top | ST(6) 

+-+ 

3 | 7th from top | ST(7) 

+-+ 

ST -> 4 | top of stack | ST(0) 

+-+ 

5 | 1st from top | ST(1) 

+-+ 

6 | 2nd from top | ST(2) 

+-+ 

7 | 3rd from top | ST(3) 

+-+ 


Starting with version 9.5, the Open Watcom compilers use all eight of the 80x87 registers as a stack. The 
initial state of the 80x87 register stack is empty before a program begins execution. 
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Note: For compatibility with code compiled with version 9.0 and earlier, you can compile with 

the "fpr" option. In this case only four of the eight 80x87 registers are used as a stack. 
These four registers were used to pass arguments. The other four registers form what was 
called the 80x87 cache. The cache was used for local floating-point variables. The state of 
the 80x87 registers before a program began execution was as follows. 

1. The four 80x87 floating-point registers that form the stack are uninitialized. 

2. The four 80x87 floating-point registers that form the 80x87 cache are initialized 
with zero. 

Hence, initially the 80x87 cache was comprised of ST(0), ST(1), ST(2) and ST(3). ST had 
the value 4 as in the above diagram. When a floating-point value was pushed on the stack 
(as is the case when passing floating-point arguments), it became ST(0) and the 80x87 
cache was comprised of ST(1), ST(2), ST(3) and ST(4). When the 80x87 stack was full, 
ST(0), ST(1), ST(2) and ST(3) formed the stack and ST(4), ST(5), ST(6) and ST(7) formed 
the 80x87 cache. Version 9.5 and later no longer use this strategy. 

The rules for passing arguments are as follows. 

1. If the argument is not floating-point, use the procedure described earlier in this chapter. 

2. If the argument is floating-point, and a previous argument has been assigned a position on the 
80x86 stack (instead of the 80x87 stack), the floating-point argument is also assigned a position 
on the 80x86 stack. Otherwise proceed to the next step. 

3. If the string "8087" appears in a register set in the pragma, and if the 80x87 stack is not full, the 
floating-point argument is assigned floating-point register ST(0) (the top element of the 80x87 
stack). The previous top element (if there was one) is now in ST(1). Since arguments are 
pushed on the stack from right to left, the leftmost floating-point argument will be in ST(0). 
Otherwise the floating-point argument is assigned a position on the 80x86 stack. 

Consider the following example. 

*$pragma aux myrtn parm (value) [8087]; 
real x 

double precision y 
integer i 
integer j 
x = 7.7 
i = 7 
y = 77.77 
j = 77 

call myrtn( x, i, y, j ) 
end 

myrtn is an assembly language subprogram that requires four arguments. The first argument of type 
REAL (4 bytes), the second argument is of type INTEGER (4 bytes), the third argument is of type 
DOUBLE PRECISION (8 bytes) and the fourth argument is of type INTEGER*4 (4 bytes). These 
arguments will be passed to myrtn in the following way. 

1. Since "8087" was specified in the register set, the first argument, being of type REAL, will be 
passed in an 80x87 floating-point register. 
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2. The second argument will be passed on the stack since no 80x86 registers were specified in the 
register set. 

3. The third argument will also be passed on the stack. Remember the following rule: once an 
argument is assigned a position on the stack, all remaining arguments will be assigned a position 
on the stack. Note that the above rule holds even though there are some 80x87 floating-point 
registers available for passing floating-point arguments. 

4. The fourth argument will also be passed on the stack. 

Let us change the auxiliary pragma in the above example as follows. 

*$pragma aux myrtn parm [eax 8087] 

The arguments will now be passed to myrtn in the following way. 

1. Since "8087" was specified in the register set, the first argument, being of type REAL will be 
passed in an 80x87 floating-point register. 

2. The second argument will be passed in register EAX, exhausting the set of available 80x86 
registers for argument passing. 

3. The third argument, being of type DOUBLE PRECISION, will also be passed in an 80x87 
floating-point register. 

4. The fourth argument will be passed on the stack since no 80x86 registers remain in the register 
set. 

14.3.11.2 Using the 80x87 to Return Subprogram Values 

The following form of the auxiliary pragma can be used to describe a subprogram that returns a 
floating-point value in ST(0). 


*$pragma aux sym value reg_set 


where description: 

sym is a subprogram name. 

reg_set is a register set containing the string "8087", i.e. [8087], 

14.3.11.3 Preserving 80x87 Floating-Point Registers Across Calls 

The code generator assumes that all eight 80x87 floating-point registers are available for use within a 
subprogram unless the "fpr" option is used to generate backward compatible code (older Open Watcom 
compilers used four registers as a cache). The following form of the auxiliary pragma specifies that the 
floating-point registers in the 80x87 cache may be modified by the specified subprogram. 
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*$pragma aux sym modify reg_set 

where description: 

sym is a subprogram name. 

reg_set is a register set containing the string "8087", i.e. [8087]. 

This instructs Open Watcom F77 to save any local variables that are located in the 80x87 cache before 
calling the specified routine. 
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A. Use of Environment Variables 


In the Open Watcom FORTRAN 77 software development package, a number of environment variables are 
used. This appendix summarizes their use with a particular component of the package. 


A.1 FINCLUDE 


The FINCLUDE environment variable describes the location of the Open Watcom FORTRAN 77 include 
files. This variable is used by Open Watcom FORTRAN 77. 

SET FINCLUDE=[d:][path];[d:][path]... 

The FINCLUDE environment string is like the PATH string in that you can specify one or more 
directories separated by semicolons 


A.2 LFN 


The LFN environment variable is checked by the Open Watcom run-time C libraries and it is used to 
control DOS LFN (DOS Long File Name) support. Normally, these libraries will use DOS LFN support if 
it is available on host OS. If you don’t wish to use DOS LFN support, you can define the LFN 
environment variable and setup it’s value to ’N\ Using the "SET" command, define the environment 
variable as follows: 

SET LFN=N 

Now, when you run your application, the DOS LFN support will be ignored. To undefine the environment 
variable, enter the command: 

SET LFN= 


A.3 LIB 


The use of the WATCOM environment variable and the Open Watcom Linker "SYSTEM" directive is 
recommended over the use of this environment variable. 

The LIB environment variable is used to select the libraries that will be used when the application is linked. 
This variable is used by the Open Watcom Linker (WLINK.EXE). The LIB environment string is like the 
PATH string in that you can specify one or more directories separated by semicolons 


If you have the 286 development system, 16-bit applications can be linked for DOS, Microsoft Windows, 
OS/2, and QNX depending on which libraries are selected. If you have the 386 development system, 32-bit 
applications can be linked for DOS Extender systems, Microsoft Windows and QNX. 
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A.4 LIBDOS 


The use of the WATCOM environment variable and the Open Watcom Linker "SYSTEM" directive is 
recommended over the use of this environment variable. 

If you are developing a DOS application, the LIBDOS environment variable must include the location of 
the 16-bit Open Watcom F77 DOS library files (files with the ".lib" filename extension). This variable is 
used by the Open Watcom Linker (WLINK.EXE). The default installation directory for the 16-bit Open 
Watcom F77 DOS libraries is \WATCOM\LIB2 8 6\DOS . 

Example: 

C>set libdos=c:\watcom\lib286\dos 


A.5 LIBWIN 


The use of the WATCOM environment variable and the Open Watcom Linker "SYSTEM" directive is 
recommended over the use of this environment variable. 

If you are developing a 16-bit Microsoft Windows application, the LIBWIN environment variable must 
include the location of the 16-bit Open Watcom F77 Windows library files (files with the ".lib" filename 
extension). This variable is used by the Open Watcom Linker (WLINK.EXE). If you are developing a 
32-bit Microsoft Windows application, see the description of the LIBPHAR environment variable. The 
default installation directory for the 16-bit Open Watcom F77 Windows libraries is 
\WATCOM\LIB286\WIN. 

Example: 

C>set libwin=c:\watcom\lib286\win 


A.6 LIB0S2 


The use of the WATCOM environment variable and the Open Watcom Linker "SYSTEM" directive is 
recommended over the use of this environment variable. 

If you are developing an OS/2 application, the LIBOS2 environment variable must include the location of 
the 16-bit Open Watcom F77 OS/2 library files (files with the ".lib" filename extension). This variable is 
used by the Open Watcom Linker (WLINK.EXE). The default installation directory for the 16-bit Open 
Watcom F77 OS/2 libraries is \WATCOM\LIB286\OS2 . The LIBOS2 environment variable must also 
include the directory of the OS/2 DOS CALLS .LIB file which is usually \0S2 . 

Example: 

C>set libos2=c:\watcom\lib286\os2;c:\os2 
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A.7LIBPHAR 


The use of the WATCOM environment variable and the Open Watcom Linker "SYSTEM" directive is 
recommended over the use of this environment variable. 

If you are developing a 32-bit Windows or DOS Extender application, the LIBPHAR environment variable 
must include the location of the 32-bit Open Watcom F77 DOS Extender library files or the 32-bit Open 
Watcom F77 Windows library files (files with the ".lib" filename extension). This variable is used by the 
Open Watcom Linker (WLINK.EXE). The default installation directory for the 32-bit Open Watcom F77 
DOS Extender libraries is \WATCOM\LIB386\DOS . The default installation directory for the 32-bit 
Open Watcom F77 Windows libraries is \WATCOM\LIB386\WIN. 

Example: 

C>set libphar=c:\watcom\lib386\dos 
or 

C>set libphar=c:\watcom\lib386\win 


A.8 N087 


The N087 environment variable is checked by the Open Watcom FORTRAN 77 run-time libraries that 
include floating-point emulation support. Normally, these libraries will detect the presence of a numeric 
data processor (80x87) and use it. If you have a numeric data processor in your system but you wish to test 
a version of your application that will use floating-point emulation, you can define the NOS7 environment 
variable. Using the "SET" command, define the environment variable as follows: 

SET N087=l 

Now, when you run your application, the 80x87 will be ignored. To undefine the environment variable, 
enter the command: 

SET N087= 


A.9PATH 

The PATH environment variable is used by DOS "COMMAND.COM" or OS/2 "CMD.EXE" to locate 
programs. 

PATH [d:] [path]; [d:] [path] ... 

The PATH environment variable should include the disk and directory of the Open Watcom FORTRAN 77 
binary program files when using Open Watcom FORTRAN 77 and its related tools. 

If your host system is DOS: 

The default installation directory for 16-bit Open Watcom F77 and 32-bit Open Watcom F77 DOS binaries 
is called \WATCOM\BINW. 
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Example: 

Opath c : \watcom\binw; c : \dos; c : \windows 
If your host system is OS/2: 

The default installation directories for 16-bit Open Watcom F77 and 32-bit Open Watcom F77 OS/2 
binaries are called \WATCOM\BINP and \WATCOM\BINW. 

Example: 

[C:\]path c:\watcom\binp;c:\watcom\binw 
If your host system is Windows NT: 

The default installation directories for 16-bit Open Watcom F77 and 32-bit Open Watcom F77 Windows 
NT binaries are called \WATCOM\BINNT and \WATCOM\BINW. 

Example: 

Opath c:\watcom\binnt;c:\watcom\binw 
The PATH environment variable is also used by the following programs in the described manner. 

1. Open Watcom Compile and Link to locate the 16-bit Open Watcom F77 and 32-bit Open 
Watcom F77 compilers and the Open Watcom Linker. 

2. "WD.EXE" to locate programs and debugger command files. 

A.10TMP 


The TMP environment variable describes the location (disk and path) for temporary files created by the 
16-bit Open Watcom F77 and 32-bit Open Watcom F77 compilers and the Open Watcom Linker. 

SET TMP=[d:][path] 

Normally, Open Watcom FORTRAN 77 will create temporary spill files in the current directory. However, 
by defining the TMP environment variable to be a certain disk and directory, you can tell Open Watcom 
FORTRAN 77 where to place its temporary files. The same is true of the Open Watcom Linker temporary 
file. 

Consider the following definition of the TMP environment variable. 

Example: 

C>set tmp=d:\watcom\tmp 

The Open Watcom FORTRAN 77 compiler and Open Watcom Linker will create its temporary files in 
d:\watcom\tmp. 
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A.11 WATCOM 

In order for the Open Watcom Linker to locate the 16-bit Open Watcom F77 and 32-bit Open Watcom F77 
library files, the WATCOM environment variable should be defined. The WATCOM environment 
variable is used to locate the libraries that will be used when the application is linked. The default directory 
for 16-bit Open Watcom F77 and 32-bit Open Watcom F77 files is "\WATCOM". 

Example: 

C>set watcom=c:\watcom 


A.12WCL 

The WCL environment variable can be used to specify commonly-used WFL options. 

SET WCL=-optionl -option2 .. . 

These options are processed before options specified on the command line. The following example defines 
the default options to be "mm" (compile code for medium memory model), "dl" (include line number 
debug information in the object file), and "ox" (compile for maximum number of code optimizations). 

Example: 

C>set wcl=-mm -dl -ox 

Once the WCL environment variable has been defined, those options listed become the default each time 
the WFL command is used. 


A.13 WCL386 


The WCL386 environment variable can be used to specify commonly-used WFL386 options. 

SET WCL386=-optionl -option2 ... 

These options are processed before options specified on the command line. The following example defines 
the default options to be "3s" (compile code for stack-based argument passing convention), "dl" (include 
line number debug information in the object file), and "ox" (compile for maximum number of code 
optimizations). 

Example: 

C>set wcl386=-3s -dl -ox 

Once the WCL386 environment variable has been defined, those options listed become the default each 
time the WFL386 command is used. 
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A.14 WCGMEMORY 

The WCGMEMORY environment variable may be used to request a report of the amount of memory used 
by the compiler’s code generator for its work area. 

Example: 

C>set WCGMEMORY=? 

When the memory amount is "?" then the code generator will report how much memory was used to 
generate the code. 

It may also be used to instruct the compiler’s code generator to allocate a fixed amount of memory for a 
work area. 

Example: 

C>set WCGMEMORY=128 

When the memory amount is "nnn" then exactly "nnnK" bytes will be used. In the above example, 128K 
bytes is requested. If less than "nnnK" is available then the compiler will quit with a fatal error message. If 
more than "nnnK" is available then only "nnnK" will be used. 

There are two reasons why this second feature may be quite useful. In general, the more memory available 
to the code generator, the more optimal code it will generate. Thus, for two personal computers with 
different amounts of memory, the code generator may produce different (although correct) object code. If 
you have a software quality assurance requirement that the same results (i.e., code) be produced on two 
different machines then you should use this feature. To generate identical code on two personal computers 
with different memory configurations, you must ensure that the WCGMEMORY environment variable is 
set identically on both machines. 

The second reason where this feature is useful is on virtual memory paging systems (e.g., OS/2) where an 
unlimited amount of memory can be used by the code generator. If a very large module is being compiled, 
it may take a very long time to compile it. The code generator will continue to allocate more and more 
memory and cause an excessive amount of paging. By restricting the amount of memory that the code 
generator can use, you can reduce the amount of time required to compile a routine. 

A.15WD 


The WD environment variable can be used to specify commonly-used Open Watcom Debugger options. 
This environment variable is not used by the Windows version of the debugger, WDW. 

SET WD=-optionl -option2 . . . 

These options are processed before options specified on the command line. The following example defines 
the default options to be "noinvoke" (do not execute the profile . dbg file) and "reg=10" (retain up to 10 
register sets while tracing). 
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Example: 

C>set wd=-noinvoke -reg#10 

Once the WD environment variable has been defined, those options listed become the default each time the 
WD command is used. 


A.16WDW 

The WDW environment variable can be used to specify commonly-used Open Watcorn Debugger options. 
This environment variable is used by the Windows version of the debugger, WDW. 

SET WDW=-optionl -option2 .. . 

These options are processed before options specified in the WDW prompt dialogue box. The following 
example defines the default options to be "noinvoke" (do not execute the profile . dbg file) and 
"reg=10" (retain up to 10 register sets while tracing). 

Example: 

C>set wdw=-noinvoke -reg#10 

Once the WDW environment variable has been defined, those options listed become the default each time 
the WDW command is used. 


A.17WFC 

The WFC environment variable can be used to specify commonly-used Open Watcom F77 options. 

SET WFC=-optionl -option2 .. . 

These options are processed before options specified on the command line. The following example defines 
the default options to be "dl" (include line number debug information in the object file) and "om" (compile 
with math optimizations). 

Example: 

C>set wfc=-dl -om 

Once the WFC environment variable has been defined, those options listed become the default each time 
the WFC command is used. 


A.18WFC386 


The WFC386 environment variable can be used to specify commonly-used Open Watcom F77 options. 
SET WFC386=-optionl -option2 ... 

These options are processed before options specified on the command line. The following example defines 
the default options to be "dl" (include line number debug information in the object file) and "om" (compile 
with math optimizations). 
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Example: 

C>set wfc386=-dl -om 

Once the WFC386 environment variable has been defined, those options listed become the default each 
time the WFC386 command is used. 


A.19WFL 

The WFL environment variable can be used to specify commonly-used WFL options. 

SET WFL=-optionl -option2 ... 

These options are processed before options specified on the command line. The following example defines 
the default options to be "mm" (compile code for medium memory model), "dl" (include line number 
debug information in the object file), and "ox" (default optimizations). 

Example: 

C>set wfl=-mm -dl -ox 

Once the WFL environment variable has been defined, those options listed become the default each time 
the WFL command is used. 


A.20 WFL386 

The WFL386 environment variable can be used to specify commonly-used WFL386 options. 

SET WFL386=-optionl -option2 ... 

These options are processed before options specified on the command line. The following example defines 
the default options to be "mf" (flat memory model), "dl" (include line number debug information in the 
object file), and "ox" (default optimizations). 

Example: 

C>set wfl386=-mf -dl -ox 

Once the WFL386 environment variable has been defined, those options listed become the default each 
time the WFL386 command is used. 


A.21 WLANG 


The WLANG environment variable can be used to control which language is used to display diagnostic 
and program usage messages by various Open Watcom software tools. The two currently-supported values 
for this variable are "English" or "Japanese". 

SET WLANG=English 
SET WLANG=Japanese 

Alternatively, a numeric value of 0 (for English) or 1 (for Japanese) can be specified. 
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Example: 

C>set wlang=0 

By default, Japanese messages are displayed when the current codepage is 932 and English messages are 
displayed otherwise. Normally, use of the WLANG environment variable should not be required. 
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B. Open Watcom F77 Diagnostic Messages 


The Open Watcom FORTRAN 77 compiler checks for errors both at compile time and execution time. 

Compile time errors may result from incorrect program syntax, violations of the rules of the language, 
underflow and overflow as a result of evaluation of expressions, etc. Three types of messages are issued: 

EXTENSION *EXT* - This indicates that the programmer has used a feature which is strictly an 

extension of the FORTRAN 77 language definition. Such extensions may not be accepted 
by other FORTRAN 77 compilers. 

WARNING *WRN* - This indicates that a possible problem has been detected by the compiler. For 
example, an unlabelled executable statement which follows an unconditional transfer of 
control can never be executed and so the compiler will issue a message about this 
condition. 

ERROR *ERR* - This indicates that some error was detected which must be corrected by the 

programmer. 

An object file will be created as long as no ERROR type messages are issued. 

Execution or run time errors may result from arithmetic underflow or overflow, input/output errors, etc. An 
execution time error causes the program to cease execution. 

Consider the following program, named "DEMOl.FOR", which contains errors. 

Example: 

* This program demonstrates the following features of 

* Open Watcom's FORTRAN 77 compiler: 

* 

* 1. Extensions to the FORTRAN 77 standard are flagged. 

* 

* 2. Compile time error diagnostics are extensive. As many 

* errors as possible are diagnosed. 

* 3. Warning messages are displayed where potential problems 

* can arise. 

* 

PROGRAM MAIN 
DIMENSION A(10) 

DO 1=1,10 

A (I) = I 
1 = 1 + 1 
ENDLOOP 
GO TO 30 
J = J + 1 

30 END 

If we compile this program with the "extensions" option, the following output appears on the screen. 
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C>wfc demol /exten 

WATCOM FORTRAN 77/16 Optimizing Compiler Version 2.0 1997/07/16 09:22:47 
Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

demol.for(14): *EXT* DO-05 this DO loop form is not FORTRAN 77 standard 
demol.for(16): *ERR* DO-07 column 13, DO variable cannot be redefined 
while DO loop is active 

demol.for(17): *ERR* SP-19 ENDLOOP statement does not match with DO 
statement 

demol.for(19): *WRN* ST-08 this statement will never be executed due 
to the preceding branch 

demol.for: 9 statements, 0 bytes, 1 extensions, 1 warnings, 2 errors 

The diagnostic messages consist of the following information: 

1. the name of the file being compiled, 

2. the line number of the line containing the error (in parentheses), 

3. a message type of either extension (*EXT*), error (*ERR*) or warning (*WRN*), 

4. a message class and number (e.g., ST-08), and 

5. text explaining the nature of the error. 

In the above example, the first error occurred on line 16 of the file "DEMO 1.FOR". Error number DO-07 
was diagnosed. The second error occurred on line 17 of the file "DEMOl.FOR". Error number SP-20 was 
diagnosed. The other errors are informational messages that do not prevent the successful compilation of 
the source file. 

The following is a list of all messages produced by Open Watcom F77 followed by a brief description. 
Run-time messages (messages displayed during execution) are also presented. The messages contain 
references to %s and %d. They represent strings that are substituted by Open Watcom F77 to make the 
error message more exact. %d represents a string of digits; %s any string, usually a symbolic name such as 
AMOUNT, a type such as INTEGER, or a symbol class such as SUBROUTINE. An error message may 
contain more than one reference to %d. In such a case, the description will reference them as %dn where n 
is the occurrence of %d in the error message. The same is true for references to %s. 

Subprogram Arguments 

AR-01 invalid number of arguments to intrinsic function %sl 

The number of actual arguments specified in the argument list for the intrinsic function 
%sl does not agree with the dummy argument list. Consult the Language Reference for 
information on intrinsic functions and their arguments. 

AR-02 dummy argument %sl appears more than once 

The same dummy argument %sl is named more than once in the dummy argument list. 

AR-12 dummy argument %sl must not appear before definition of ENTRY %s2 

The dummy argument %sl has appeared in an executable statement before its appearance 
in the definition of %s2 in an ENTRY statement. This is illegal. 
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Block Data Subprograms 

BD-01 %sl was initialized in a block data subprogram but is not in COMMON 

The variable or array element, %sl, was initialized in a BLOCK DATA subprogram but 
was not specified in a named COMMON block. 

BD-02 %sl statement is not permitted in a BLOCK DATA subprogram 

The statement, %sl, is not allowed in a BLOCK DATA subprogram. The only statements 
which are allowed to appear are: IMPLICIT, PARAMETER, DIMENSION, COMMON, 
SAVE, EQUIVALENCE, DATA, END, and type statements. 

Source Format and Contents 

CC-01 invalid character encountered in source input 

The indicated statement contains an invalid character. Valid characters are: letters, digits, 
$, *, ., +, -, /, :, =, (,), !, %, ’, and .(comma). Any character may be used inside a character 
or hollerith string. 

CC-02 invalid character in statement number columns 

A column in columns 1 to 5 of the indicated statement contains a non-digit character. 
Columns 1 to 5 contain the statement number label. It is made up of digits from 0 to 9 and 
is greater than 0 and less than or equal to 99999. 

CC-03 character in continuation column, but no statement to continue 

The character in column 6 indicates that this line is a continuation of the previous statement 
but there is no previous statement to continue. 

CC-04 character encountered is not FORTRAN 77 standard 

A non-standard character was encountered in the source input stream. This is most likely 
caused by the use of lower case letters. 

CC-05 columns 1-5 in a continuation line must be blank 

When column 6 is marked as a continuation statement to the previous line, columns 1 to 5 
must be left blank. 

CC-06 more than 19 continuation lines is not FORTRAN 77 standard 

More than 19 continuation lines is an extension to the FORTRAN 77 language. 

CC-07 ettd-of-line comment is not FORTRAN 77 standard 

End-of-line comments are an extension to the FORTRAN 77 language. End-of-line 
comments start with the exclamation mark (!) character. 

CC-08 D in column 1 is not FORTRAN 77 standard 
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A "D" in column 1 signifies a debug statement that is compiled when the "_debug_" 

macro symbol is defined. If the "_debug_" macro symbol is not defined, the statement is 

ignored. The "c$define" compiler directive or the "define" compiler option can be used to 
define the "_debug_" macro symbol. 

CC-09 too many continuation lines 

The limit on the number of continuation lines has been reached. This limit depends on the 
size of each continuation line. A minimum of 61 continuation lines is permitted. If the 
"xline" option is used, a minimum of 31 continuation lines is permitted. 

COMMON Blocks 

CM-01 %sl already in COMMON 

The variable or array name, %sl, has already been specified in this or another COMMON 
block. 

CM-02 initializing %sl in COMMON outside of block data subprogram is not FORTRAN 77 standard 

The symbol %sl, in a named COMMON block, has been initialized outside of a block data 
subprogram. This is an extension to the FORTRAN 77 language. 

CM-03 character and non-character data in COMMON is not FORTRAN 77 standard 

The FORTRAN 77 standard specifies that a COMMON block cannot contain both numeric 
and character data. Allowing COMMON blocks to contain both numeric and character 
data is an extension to the FORTRAN 77 standard. 

CM-04 COMMON block %sl has been defined with a different size 

The COMMON block %sl has been defined with a different size in another subprogram. 

A named COMMON block must define the same amount of storage units where ever 
named. 

CM-05 named COMMON block %sl appears in more than one BLOCK DATA subprogram 

The named COMMON block, %sl, may not appear in more than one BLOCK DATA 
subprogram. 

CM-06 blank COMMON block has been defined with a different size 

The blank COMMON block has been defined with a different size in another subprogram. 
This is legal but a warning message is issued. 


Constants 

CN-01 DOUBLE PRECISION COMPLEX constants are not FORTRAN 77 standard 

Double precision complex numbers are an extension to the FORTRAN 77 language. The 
indicated number is a complex number and at least one of the parts, real or imaginary, is a 
double precision constant. Both real and imaginary parts will be double precision. 
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CN-02 invalid floating-point constant %sl 

The floating-point constant %sl is invalid. Refer to the chapter entitled "Names, Data 
Types and Constants" in the Language Reference. 

CN-03 zero length character constants are not allowed 

FORTRAN 77 does not allow character constants of length 0 (i.e., an empty string). 

CN-04 invalid hexadecimal/octal constant 

An invalid hexadecimal or octal constant was specified. Hexadecimal constants can only 
contain digits or the letters ’a' through 'f and 'A' through ’F\ Octal constants can only 
contain the digits ’O' through ’7’. 

CN-05 hexadecimal/octal constant is not FORTRAN 77 standard 

Hexadecimal and octal constants are extensions to the FORTRAN 77 standard. 

Compiler Options 

CO-01 %sl is already being included 

An attempt has been made to include a file that is currently being included in the program. 

CO-02 ’%sl ’ option cannot take a NO prefix 

The compiler option %sl, cannot have the NO prefix specified. The NO prefix is used to 
negate an option. Certain options, including all options that require a value cannot have a 
NO prefix. 

CO-03 expecting an equals sign following the %sl option 

The compiler option %sl, requires an equal sign to be between the option keyword and its 
associated value. 

CO-04 the ’%sl ’ option requires a number 

The compiler option %sl and an equal sign has been detected but the required associated 
value is missing. 

CO-05 option ’%sl ’ not recognized - ignored 

The option %s 1 is not a recognized compiler option and has been ignored. Consult the 
User’s Guide for a complete list of compiler options. 

CO-06 ’%sl ’ option not allowed in source input stream 

The option %sl can only be specified on the command line. Consult the User’s Guide for a 
description of which options are allowed in the source input stream. 

CO-07 nesting level exceeded for compiler directives 
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Use of the C$IFDEF or C$IFNDEF compiler directives has caused the maximum nesting 
level to be exceeded. The maximum nesting level is 16. 

CO-08 mismatching compiler directives 

This error message is issued if, for example, a C$ENDIF directive is used and no matching 
C$IFDEF or C$IFNDEF precedes it. Incorrect nesting of C$IFDEF, C$IFNDEF, C$ELSE 
and C$ENDIF directives will also cause this message to be issued. 

Compiler Errors 

CP-01 program abnormally terminated 

This message is issued during the execution of the program. If you are running 
WATFOR-77, this message indicates that an internal error has occurred in the compiler. 
Please report this error and any other helpful information about the program being 
compiled to Watcom so that the problem can be fixed. 

If you are running an application compiled by the Watcom FORTRAN 77 optimizing 
compiler, this message may indicate a problem with the compiler or a problem with your 
program. Try compiling your application with the "debug" option. This causes the 
generation of run-time checking code to validate, for example, array subscripts and will 
help ensure that your program is not in error. 

CP-02 argument %dl incompatible with register 

The register specified in an auxiliary pragma for argument number %dl is invalid. 

CP-03 subprogram %sl has invalid return register 

The register specified in an auxiliary pragma for the return value of function %sl is invalid. 
This error is issued when, for example, an auxiliary pragma is used to specify EAX as the 
return register for a double precision function. 

CP-04 low on memory - unable to fully optimize %sl 

There is not enough memory for the code generator to fully optimize subprogram %sl. 

CP-05 internal compiler error %dl 

This error is an internal code generation error. Please report the specified internal compiler 
error number and any other helpful information about the program being compiled to 
Watcom so that the problem can be fixed. 

CP-06 illegal register modified by %sl 

An illegal register was said to be modified by %sl in the auxiliary pragma for %sl. In a 
32-bit flat memory model, the base pointer register EBP and segment registers CS, DS, ES, 
and SS cannot be modified. In small data models, the base pointer register (32-bit EBP or 
16-bit BP) and segment registers CS, DS, and SS cannot be modified. In large data models, 
the base pointer register (32-bit EBP or 16-bit BP) and segment registers CS, and SS cannot 
be modified. 


214 Open Watcom F77 Diagnostic Messages 




Open Watcom F77 Diagnostic Messages 


CP-07 %sl 

The message specified by %sl indicates an error during the code generation phase. The 
most probable cause is an invalid instruction in the in-line assembly code specified in an 
auxiliary pragma. 

CP-08 fatal: %sl 

The specified error indicates that the code generator has been abnormally terminated. This 
message will be issued if any internal limit is reached or a keyboard interrupt sequence is 
pressed during the code generation phase. 

CP-09 dynamic memory not freed 

This message indicates an internal compiler error. Please report this error and any other 
helpful information about the program being compiled to Watcom so that the problem can 
be fixed. 

CP-10 freeing unowned dynamic memory 

This message indicates an internal compiler error. Please report this error and any other 
helpful information about the program being compiled to Watcom so that the problem can 
be fixed. 

CP-11 The automatic equivalence containing %sl exceeds 32K limit 

In 16-bit environments, the size of an equivalence on the stack must not exceed 32767 
bytes. 

CP-12 The return value of %sl exceeds 32K limit 

In 16-bit environments, the size of the return value of a function must not exceed 32767 
bytes. 

CP-13 The automatic variable %sl exceeds 32K limit 

In 16-bit environments, the size of any variable on the stack must not exceed 327 Cl bytes. 
Character Variables 

CV-01 CHARACTER variable %sl with length (*) not allowed in this expression 

The length of the result of evaluating the expression is indeterminate. One of the operands 
has an indeterminate length and the result is being assigned to a temporary. 

CV-02 character variable %sl with length (*) must be a subprogram argument 

The character variable %sl with a length specification (*) can only be used to declare 
dummy arguments in the subprogram. The length of a dummy argument assumes the 
length of the corresponding actual argument. 
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Data Initialization 

DA-01 implied DO variable %sl must be an integer variable 

The implied DO variable %sl must be declared as a variable of type INTEGER or must 
have an implicit INTEGER type. 

DA-02 repeat specification must be a positive integer 

The repeat specification in the constant list of the DATA statement must be an unsigned 
positive integer. 

DA-03 %sl appears in an expression but is not an implied DO variable 

The variable %sl is used to express the array elements in the DATA statement but the 
variable is not used as an implied DO variable. 

DA-04 %sl in blank COMMON block cannot be initialized 

A blank or unnamed COMMON block is a COMMON statement with the block name 
omitted. The entries in blank COMMON blocks cannot be initialized using DATA 
statements. 

DA-05 data initialization with hexadecimal constant is not FORTRAN 77 standard 

Data initialization with hexadecimal constants is an extension to the FORTRAN 77 
language. 

DA-06 cannot initialize %sl %s2 

Symbol %s2 was used as a %sl. It is illegal for such a symbol to be initialized in a DATA 
statement. The DATA statement can only be used to initialize variables, arrays, array 
elements, and substrings. 

DA-07 data initialization in %sl statement is not FORTRAN 77 standard 

Data initialization in type specification statements is an extension to the FORTRAN 77 
language. These include: CHARACTER, COMPLEX, DOUBLE PRECISION, 
INTEGER, LOGICAL, and REAL. 

DA-08 not enough constants for list of variables 

There are not enough constants specified to initialize all of the names listed in the DATA 
statement. 

DA-10 too many constants for list of variables 

There are too many constants specified to initialize the names listed in the DATA 
statement. 

DA-12 cannot initialize %sl variable %s2 with %s3 constant 

The constant of type %s3 cannot be used to initialize the variable %s2 of type %sl. 
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Dimensioned Variables 

DM-01 using %sl incorrectly in dimension expression 

The name used as a dimension declarator has been previously declared as type %sl and 
cannot be used as a dimension declarator. A dimension declarator must be an integer 
expression. 


DO-loops 

DO-01 statement number %dl already defined in line %d2 - DO loop is backwards 

The statement number to indicate the end of the DO control structure has been used 
previously in the program unit and cannot be used to terminate the DO loop. The terminal 
statement named in the DO statement must follow the DO statement. 

DO-02 %sl statement not allowed at termination of DO range 

A non-executable statement cannot be used as the terminal statement of a DO loop. These 
statements include: all declarative statements, ADMIT, AT END, BLOCK DATA, CASE, 
DO, ELSE, ELSE IF, END, END AT END, END BLOCK, END GUESS, END IF, END 
LOOP, END SELECT, END WHILE, ENTRY, FORMAT, FUNCTION, assigned GO TO, 
unconditional GO TO, GUESS, arithmetic and block IF, LOOP, OTHERWISE, 
PROGRAM, RETURN, SAVE, SELECT, STOP, SUBROUTINE, UNTIL, and WHILE. 

DO-03 improper nesting of DO loop 

A nested DO loop has not been properly terminated before the termination of the outer DO 
loop. 

DO-04 ENDDO cannot terminate DO loop with statement label 

The ENDDO statement can only terminate a DO loop in which no statement label was 
specified in the defining DO statement. 

DO-05 this DO loop form is not FORTRAN 77 standard 

As an extension to FORTRAN 77, the following forms of the DO loop are also supported. 

1. A DO loop with no statement label specified in the defining DO statement. 

2. The DO WHILE form of the DO statement. 

DO-06 expecting comma or DO variable 

The item following the DO keyword and the terminal statement-label (if present) must be 
either a comma or a DO variable. A DO variable is an integer, real or double precision 
variable name. The DO statement syntax is as follows: 

DO <tsl> <,> DO-var = ex, ex <, ex> 

DO-07 DO variable cannot be redefined while DO loop is active 
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The DO variable named in the DO statement cannot have its value altered by a statement in 
the DO loop structure. 

Equivalence and/or Common 

EC-01 equivalencing %sl has caused extension of COMMON block %s2 to the left 

The name %sl has been equivalenced to a name in the COMMON block %s2. This 
relationship has caused the storage of the COMMON block to be extended to the left. 
FORTRAN 77 does not allow a COMMON block to be extended in this way. 

EC-02 %sl and %s2 in COMMON are equivalenced to each other 

The names %sl and %s2 appear in different COMMON blocks and each occupies its own 
piece of storage and therefore cannot be equivalenced. 

END Statement 

EN-01 missing END statement 

The END statement for a PROGRAM, SUBROUTINE, FUNCTION or BLOCK DATA 
subprogram was not found before the next subprogram or the end of the source input 
stream. 


Equal Sign 

EQ-01 target of assignment is illegal 

The target of an assignment statement, an input/output status specifier in an input/output 
statement, or an inquiry specifier in an INQUIRE statement, is illegal. The target in any of 
the above cases must be a variable name, array element, or a substring name. 

EQ-02 cannot assign value to %sl 

An attempt has been made to assign a value to a symbol with class %sl. For example, an 
array name cannot be the target of an assignment statement. This error may also be issued 
when an illegal target is used for the input/output status specifier in an input/output 
statement or an inquiry specifier in an INQUIRE statement. 

EQ-03 illegal use of equal sign 

An equal sign has been found in the statement but the statement is not an assignment 
statement. 

EQ-04 multiple assignment is not FORTRAN 77 standard 

More than one equal sign has been found in the assignment statement. 

EQ-05 expecting equals sign 

The equal sign is missing or misplaced. The PARAMETER statement uses an equal sign to 
equate a symbolic name to the value of a constant expression. The I/O statements use an 
equal sign to equate the appropriate values to the various specifiers. The DO statement 
uses an equal sign to assign the initial value to the DO variable. 
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Equivalenced Variables 

EV-01 %sl has been equivalenced to 2 different relative positions 

The storage unit referenced by %sl has been equivalenced to two different storage units 
starting in two different places. One name cannot be associated to two different values at 
the same time. 

EV-02 EQUIVALENCE list must contain at least 2 names 

The list of names to make a storage unit equivalent to several names must contain at least 
two names. 

EV-03 %sl incorrectly subscripted in %s2 statement 

The name %sl has been incorrectly subscripted in a %s2 statement. 

EV-04 incorrect substring of %sl in %s2 statement 

An attempt has been made to incorrectly substring %sl in a %s2 statement. For example, if 
a CHARACTER variable was declared to be of length 4 then (2:5) would be an invalid 
substring expression. 

EV-05 equivalencing CHARACTER and non-CHARACTER data is not FORTRAN 77 standard 

Equivalencing numeric and character data is an extension to the FORTRAN 77 language. 

EV-06 attempt to substring %sl in EQUIVALENCE statement but type is %s2 

An attempt has been made to substring the symbolic name %sl in an EQUIVALENCE 
statement but the type of the name is %s2 and should be of type CHARACTER. 


Exponentiation 

EX-01 zero**J where J <= 0 is not allowed 

Zero cannot be raised to a power less than or equal to zero. 

EX-02 X**Y where X <0.0, Y is not of type INTEGER, is not allowed 

When X is less than zero, Y may only be of type INTEGER. 

EX-03 (0,0)**Y where Y is not real is not allowed 

In complex exponentiation, when the base is zero, the exponent may only be a real number 
or a complex number whose imaginary part is zero. 

ENTRY Statement 

EY-01 type of entry %sl does not match type of function %s2 

If the type of a function is CHARACTER or a user-defined STRUCTURE, then the type of 
all entry names must match the type of the function name. 
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EY-02 ENTRY statement not allowed within structured control blocks 

FORTRAN 77 does not allow an ENTRY statement to appear between the start and end of 
a control structure. 

EY-03 size of entry %sl does not match size of function %s2 

The name %sl found in an ENTRY statement must be declared to be the same size as that 
of the function name. If the name of the function or the name of any entry point has a 
length specification of (*), then all such entries must have a length specification of (*) 
otherwise they must all have a length specification of the same integer value. 


Format 

FM-01 missing delimiter in format string, comma assumed 

The omission of a comma between the descriptors listed in a format string is an extension 
to the FORTRAN 77 language. Care should be taken when omitting the comma since the 
assumed separation may not occur in the intended place. 

FM-02 missing or invalid constant 

An unsigned integer constant was expected with the indicated edit descriptor but was not 
correctly placed or was missing. 

FM-03 Ew.dDe format code is not FORTRAN 77 standard 

The edit descriptor Ew.dDe is an extension to the FORTRAN 77 language. 

FM-04 missing decimal point 

The indicated edit descriptor must have a decimal point and an integer to indicate the 
number of decimal positions. These edit descriptors include: F, E, D and G. 

FM-05 missing or invalid edit descriptor in format string 

In the format string, two delimiters were found in succession with no valid descriptor in 
between. 

FM-06 unrecognizable edit descriptor in format string 

An edit descriptor has been found in the format string that is not a valid code. Valid codes 
are: apostrophe (’), I, F, E, D, G, L, A, Z, H, T, TL, TR, X, /, :, S, SP, SS, P, BN, B, $, and 
V 

FM-07 invalid repeat specification 

The indicated repeatable edit descriptor is invalid. The forms of repeatable edit descriptors 
are: Iw, Iw.m, Fw.d, Ew.d, Ew.dEe, Dw.d, Gw.d, Gw.dEe, Lw, A, Aw, Ew.dDe, and Zw 
where w and e are positive unsigned integer constants, and d and m are unsigned integer 
constants. 

FM-08 $ or\ format code is not FORTRAN 77 standard 
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The non-repeatable edit descriptors $ and \ are extensions to the FORTRAN 77 language. 
FM-09 invalid field modifier 

The indicated edit descriptor for a field is incorrect. Consult the Language Reference for 
the correct form of the edit descriptor. 

FM-10 expecting end of FORMAT statement but found more text 

The right parenthesis was encountered in the FORMAT statement to terminate the 
statement and more text was found on the line. 

FM-11 repeat specification not allowed for this format code 

A repeat specification was found in front of a format code that is a nonrepeatable edit 
descriptor. These include: apostrophe, H, T, TL, TR, X, /,S, SP, SS, P, BN, BZ, $,and \. 

FM-12 no statement number on FORMAT statement 

The FORMAT statement must have a statement label. This statement number is used by 
I/O statements to reference the FORMAT statement. 

FM-13 no closing quote on apostrophe edit descriptor 

The closing quote of an apostrophe edit descriptor was not found. 

FM-14 field count greater than 256 is invalid 

The repeat specification of the indicated edit descriptor is greater than the maximum 
allowed of 256. 

FM-15 invalid field width specification 

The width specifier on the indicated edit descriptor is invalid. 

FM-16 Z format code is not FORTRAN 77 standard 

The Z (hexadecimal format) repeatable edit descriptor is an extension to the FORTRAN 77 
language. 

FM-17 FORMAT statement exceeds allotted storage size 

The maximum allowable size of a FORMAT statement has exceeded. The statement must 
be split into two or more FORMAT statements. 

FM-18 format specification not allowed on input 

A format specification, in the FORMAT statement, is not allowed to be used as an input 
specification. Valid specifications include: T, TL.TR, X, /, :, P, BN, BZ, I, F, E, D, G, L, 
A,and Z. 

FM-19 FORMAT missing repeatable edit descriptor 
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An attempt has been made to read or write a piece of data without a valid repeatable edit 
descriptor. All data requires a repeatable edit descriptor in the format. The forms of 
repeatable edit descriptors are: Iw, Iw.m, Fw.d, Ew.d, Ew.dEe, Dw.d, Gw.d, Gw.dEe, Lw, 
A, Aw, Ew.dDe, and Zw where w and e are positive unsigned integer constants, and d and 
m are unsigned integer constants. 

FM-20 missing constant before X edit descriptor, 1 assumed 

The omission of the constant before an X edit descriptor in a format specification is an 
extension to the FORTRAN 77 language. 

FM-21 Ew.dQe format code is not FORTRAN 77 standard 

The edit descriptor Ew.dQe is an extension to the FORTRAN 77 language. 

FM-22 Qw.d format code is not FORTRAN 77 standard 

The edit descriptor Qw.d is an extension to the FORTRAN 77 language. 

GOTO and ASSIGN Statements 

GO-01 %sl statement label may not appear in ASSIGN statement but did in line %d2 

The statement label in the ASSIGN statement in line %d2 references a %sl statement. The 
statement label in the ASSIGN statement must appear in the same program unit and must 
be that of an executable statement or a FORMAT statement. 

GO-02 ASSIGN of statement number %dl in line %d2 not allowed 

The statement label %dl in the ASSIGN statement is used in the line %d2 which references 
a non-executable statement. A statement label must appear in the same program unit as the 
ASSIGN statement and must be that of an executable statement or a FORMAT statement. 

GO-03 expecting TO 

The keyword TO is missing or misplaced in the ASSIGN statement. 

Hollerith Constants 

HO-Ol Hollerith constant is not FORTRAN 77 standard 

Hollerith constants are an extension to the FORTRAN 77 language. 

HO-02 not enough characters for Hollerith constant 

The number of characters following the H or h is not equal to the constant preceding the H 
or h. A hollerith constant consists of a positive unsigned integer constant n followed by the 
letter H or h followed by a string of exactly n characters. 
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IF Statements 

IF-01 ELSE block must be the last block in block IF 


Another ELSE IF block has been found after the ELSE block. The ELSE block must be the 
last block in an IF block. The form of the block IF is as follows: 


IF (logical expression) 
{statement} 

{ ELSE IF 

{statement} } 


[ELSE 


{statement} ] 


END IF 


THEN 


[ :block-label] 


IF-02 expecting THEN 

The keyword THEN is missing or misplaced in the block IF statement. The form of the 
block IF is as follows: 


IF (logical expression) THEN 
{statement} 

{ ELSE IF 

{statement} } 

[ELSE 

{statement} ] 

END IF 


[ :block-label] 


I/O Lists 

IL-01 missing or invalid format/FMT specification 

A valid format specification is required on all READ and WRITE statements. The format 
specification is specified by: 

[FMT=] <format identifier> 

<format identifier is one of the following: statement label, integer variable-name, 
character array-name, character expression, or *. 

IL-02 the UNIT may not be an internal file for this statement 

An internal file may only be referenced in a READ or WRITE statement. An internal file 
may not be referenced in a BACKSPACE, CLOSE, ENDFILE, INQUIRE, OPEN, or 
REWIND statement. 

IL-03 %sl statement cannot have %s2 specification 

The I/O statement %sl may not have the control information %s2 specified. 

IL-04 variable must have a size of 4 

The variable used as a specifier in an I/O statement must be of size 4 but another size was 
specified. These include the EXIST, OPENED, RECL, IOSTAT, NEXTREC, and 
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NUMBER. The name used in the ASSIGN statement must also be of size 4 but a different 
size was specified. 

IL-05 missing or unrecognizable control list item %sl 

A control list item %sl was encountered in an I/O statement and is not a valid control list 
item for that statement, or a control list item was expected and was not found. 

IL-06 attempt to specify control list item %sl more than once 

The control list item %sl in the indicated I/O statement, has been named more than once. 

IL-07 implied DO loop has no input/output list 

The implied DO loop specified in the I/O statement does not correspond with a variable or 
expression in the input/output list. 

IL-08 list-directed input/output with internal files is not FORTRAN 77 standard 

List-directed input/output with internal files is an extension to the FORTRAN 77 language. 

IL-09 FORTRAN 77 standard requires an asterisk for list-directed formatting 

An optional asterisk for list-directed formatting is an extension to the FORTRAN 77 
language. The standard FORTRAN 77 language specifies that an asterisk is required. 

IL-10 missing or improper unit identification 

The control specifier, UNIT, in the I/O statement is either missing or identifies an improper 
unit. The unit specifier specifies an external unit or internal file. The external unit 
identifier is a non-negative integer expression or an asterisk. The internal file identifier is 
character variable, character array, character array element, or character substring. 

IL-11 missing unit identification or file specification 

An identifier to specifically identify the required file is missing. The UNIT specifier is 
used to identify the external unit or internal file. The FILE specifier in the INQUIRE and 
OPEN statements is used to identify the file name. 

IL-12 asterisk unit identifier not allowed in %sl statement 

The BACKSPACE, CLOSE, ENDFILE, INQUIRE, OPEN, and REWIND statements 
require the external unit identifier be an unsigned positive integer from 0 to 999. 

IL-13 cannot have both UNIT and FILE specifier 

There are two valid forms of the INQUIRE statement; INQUIRE by FILE and INQUIRE 
by UNIT. Both of these specifiers cannot be specified in the same statement. 

IL-14 internal files require sequential access 

An attempt has been made to randomly access an internal file. Internal files may only be 
accessed sequentially. 
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IL-15 END specifier with REC specifier is not FORTRAN 77 standard 

The FORTRAN 77 standard specifies that an end-of-file condition can only occur with a 
file connected for sequential access or an internal file. The REC specifier indicates that the 
file is connected for direct access. This extension allows the programmer to detect an 
end-of-file condition when reading the records sequentially from a file connected for direct 
access. 

IL-16 %sl specifier in Ho list is not FORTRAN 77 standard 

The specified i/o list item is provided as an extension to the FORTRAN 77 language. 

IL-17 i/o list is not allowed with NAMELIST-directed format 

An i/o list is not allowed when the format specification is a NAMELIST. 

IL-18 non-character array as format specifier is not FORTRAN 77 standard 

A format specifier must be of type character unless it is an array name. Allowing a 
non-character array name is an extension to the FORTRAN 77 standard. 

IMPLICIT Statements 

IM-01 illegal range of characters 

In the IMPLICIT statement, the first letter in the range of characters must be smaller in the 
collating sequence than the second letter in the range. 

IM-02 letter can only be implicitly declared once 

The indicated letter has been named more than once in this or a previous IMPLICIT 
statement. A letter may only be named once. 

IM-03 unrecognizable type 

The type declared in the IMPLICIT statement is not one of INTEGER, REAL, DOUBLE 
PRECISION, COMPLEX, LOGICAL or CHARACTER. 

IM-04 (*) length specifier in an IMPLICIT statement is not FORTRAN 77 standard 

A character length specified of (*) in an IMPLICIT statement is an extension to the 
FORTRAN 77 language. 

IM-05 IMPLICIT NONE allowed once or not allowed with other IMPLICIT statements 

The IMPLICIT NONE statement must be the only IMPLICIT statement in the program unit 
in which it appears. Only one IMPLICIT NONE statement is allowed in a program unit. 


Input/Output 

10-01 BACKSPACE statement requires sequential access mode 

The file connected to the unit specified in the BACKSPACE statement has not been opened 
for sequential access. 
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10-02 input/output is already active 

An attempt has been made to read or write a record when there is an already active read or 
write in progress. The execution of a READ or WRITE statement has caused transfer to a 
function that contains a READ or WRITE statement. 

10-03 ENDFILE statement requires sequential access mode 

The specified external unit identifier must be connected for sequential access but was 
connected for direct access. 

10-04 formatted connection requires formatted input/output statements 

The FORM specifier in the OPEN statement specifies FORMATTED and the subsequent 
READ and/or WRITE statement does not use formatted I/O. If the FORM specifier has 
been omitted and access is SEQUENTIAL then FORMATTED is assumed. If the access is 
DIRECT then UNFORMATTED is assumed. 

10-05 unformatted connection requires unformatted input/output statements 

The FORM specifier in the OPEN statement specifies UNFORMATTED and the 
subsequent READ and/or WRITE statement uses formatted I/O. If the FORM specifier has 
been omitted and access is SEQUENTIAL then FORMATTED is assumed. If the access is 
DIRECT then UNFORMATTED is assumed. 

10-06 REWIND statement requires sequential access 

The external unit identifier is not connected to a sequential file. The REWIND statement 
positions to the first record in the file. 

10-07 bad character in input field 

The data received from the record in a file does not match the type of the input list item. 

10-08 BLANK specifier requires FORM specifier to be ’FORMATTED’ 

In the OPEN statement, the BLANK specifier may only be used when the FORM specifier 
has the value of FORMATTED. The BLANK specifier indicates whether blanks are 
treated as zeroes or ignored. 

10-09 system file error - %sl 

A system error has occurred while attempting to access a file. The I/O system error 
message is displayed. 

10-10 format specification does not match data type 

A format specification in the FMT specifier or FORMAT statement specifies data of one 
type and the variable list specifies data of a different type. 

10-11 input item does not match the data type of list variable 

In the READ statement, the data type of a variable listed is not of the same data type in the 
data file. For example, non-digit character data being read into an integer item. 
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10-12 internal file is full 

The internal file is full of data. If a file is a variable then the file may only contain one 
record. If the file is a character array then there can be one record for each array element. 

10-13 RECL specifier is invalid 

In the OPEN statement, the record length specifier must be a positive integer expression. 

10-14 invalid STATUS specifier in CLOSE statement 

The STATUS specifier can only have a value of KEEP or DELETE. If the STATUS in the 
OPEN statement is SCRATCH then the KEEP status on the CLOSE statement cannot be 
used. 

10-15 unit specified is not connected 

The unit number specified in the I/O statement has not been previously connected. 

10-16 attempt to perform data transfer past end of file 

An attempt has been made to read or write data after the end of file has been read or 
written. 

10-17 invalid RECL specifier/ACCESS specifier combination 

In the OPEN statement, if the ACCESS specifier is DIRECT then the RECL specifier must 
be given. 

10-18 REC specifier required in direct access input/output statements 

In the OPEN statement, the ACCESS specified was DIRECT. All subsequent input/output 
statements for that file must use the REC specifier to indicate which record to access. 

10-19 REC specifier not allowed in sequential access input/output statements 

In the OPEN statement, the ACCESS specified was SEQUENTIAL. The REC specifier 
may not be used in subsequent I/O statements for that file. The REC specifier is used to 
indicate which record to access when access is DIRECT. 

10-20 %sl specifier may not change in a subsequent OPEN statement 

The %sl specifier may not be changed on a subsequent OPEN statement for the same file, 
in the same program. Only the BLANK specifier may be changed. 

10-21 invalid STATUS specifier for given file 

In the OPEN statement, the STATUS specifier does not match with the actual file status: 
OLD means the file must exist, NEW means the file must not exist. If the STATUS 
specifier is omitted, UNKNOWN is assumed. 

10-22 invalid STATUS specifier/FILE specifier combination 
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In the OPEN statement, if the STATUS is SCRATCH, the FILE specifier cannot be used. 

If the STATUS is NEW or OLD, the FILE specifier must be given. 

10-23 record size exceeded during unformatted input/output 

This error is issued when the size of an i/o list item exceeds the maximum record size of the 
file. The record size can be specified using the RECL= specified in the OPEN statement. 

10-24 unit specified does not exist 

The external unit identifier specified in the input/output statement has not yet been 
connected. Use preconnection or the OPEN statement to connect a file to the external unit 
identifier. 

10-25 REC specifier is invalid 

The REC specifier must be an unsigned positive integer. 

10-26 UNIT specifier is invalid 

The UNIT specifier must be an unsigned integer between 0 and 999 inclusive. 

10-27 formatted record or format edit descriptor is too large for record size 

This error is issued when the amount of formatted data in a READ, WRITE or PRINT 
statement exceeds the maximum record size of the file. The record size can be specified 
using the RECL= specified in the OPEN statement. 

10-28 illegal ’%sl=’ specifier 

In the OPEN or CLOSE statement the value associated with the %sl specifier is not a valid 
value. In the OPEN statement, STATUS may only be one of OLD, NEW, SCRATCH or 
UNKNOWN; ACCESS may only be one of SEQUENTIAL, APPEND or DIRECT; FORM 
may only be one of FORMATTED or UNFORMATTED; CARRIAGECONTROL may 
only be one of YES or NO; RECORDTYPE may only be one of FIXED, TEXT or 
VARIABLE; ACTION may only be one of READ, WRITE or READ/WRITE; and 
BLANK may only be one of NULL, or ZERO. In the CLOSE statement the STATUS may 
only be one of KEEP or DELETE. 

10-29 invalid CARRIAGECONTROL specifier/FORM specifier combination 

The CARRIAGECONTROL specifier is only allowed with formatted i/o statements. 

10-30 i/o operation not consistent with file attributes 

An attempt was made to read from a file that was opened with ACTION=WRITE or write 
to a file that was opened with ACTION=READ. This message is also issued if you attempt 
to write to a read-only file or read from a write-only file. 

10-31 symbol %sl not found in NAMELIST 

During NAMELIST-directed input, a symbol was specified that does not belong to the 
NAMELIST group specified in the i/o statement. 
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10-32 syntax error during NAMELIST-directed input 

Bad input was encountered during NAMELIST-directed input. Data must be in a special 
form during NAMELIST-directed input. 

10-33 subscripting error during NAMELIST-directed Ho 

An array was incorrectly subscripted during NAMELIST-directed input. 

10-34 substring error during NAMELIST-directed Ho 

An character array element or variable was incorrectly substrung during 
NAMELIST-directed input. 

10-35 BLOCKSIZE specifier is invalid 

In the OPEN statement, the block size specifier must be a positive integer expression. 

10-36 invalid operation for files with no record structure 

An attempt has been made to perform an i/o operation on a file that requires a record 
structure. For example, it is illegal to use a BACKSPACE statement for a file that has no 
record structure. 

10-37 integer overflow converting character data to integer 

An overflow has occurred while converting the character data read to its internal 
representation as an integer. 

10-38 range exceeded converting character data to floating-point 

An overflow or underflow has occurred while converting the character data read to its 
internal representation as a floating-point number. 

Program Termination 

KO-Ol floating-point divide by zero 

An attempt has been made to divide a number by zero in a floating-point expression. 
KO-02 floating-point overflow 

The floating-point expression result has exceeded the maximum floating-point number. 
KO-03 floating-point underflow 

The floating-point expression result has exceeded the minimum floating-point number. 
KO-04 integer divide by zero 

An attempt has been made to divide a number by zero in an integer expression. 

KO-05 program interrupted from keyboard 
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The user has interrupted the compilation or execution of a program through use of the 
keyboard. 

KO-06 integer overflow 

The integer expression result has exceeded the maximum integer number. 

Library Routines 

LI-01 argument must be greater than zero 

The argument to the intrinsic function must be greater than zero (i.e., a positive number). 

LI-02 absolute value of argument to arcsine, arccosine must not exceed one 

The absolute value of the argument to the intrinsic function ASIN or ACOS cannot be 
greater than or equal to the value 1.0. 

LI-03 argument must not be negative 

The argument to the intrinsic function must be greater than or equal to zero. 

LI-04 arguments) must not be zero 

The argument(s) to the intrinsic function must not be zero. 

LI-05 argument of CHAR must be in the range zero to 255 

The argument to the intrinsic function CHAR must be in the range 0 to 255 inclusive. 
CHAR returns the character represented by an 8-bit pattern. 

LI-06 %sl intrinsic function cannot be passed 2 complex arguments 

The second argument to the intrinsic function CMPLX and DCMPLX cannot be a complex 
number. 

LI-07 argument types must be the same for the %sl intrinsic function 

The second argument to the intrinsic function CMPLX or DCMPLX must be of the same 
type as the first argument. The second argument may only be used when the first argument 
is of type INTEGER, REAL or DOUBLE PRECISION. 

LI-08 expecting numeric argument, but %sl argument was found 

The argument to the intrinsic function, INT, REAL, DBLE, CMPLX, or DCMPLX was of 
type %sl and a numeric argument was expected. 

LI-09 length of ICHAR argument greater than one 

The length of the argument to the intrinsic function ICHAR must be of type CHARACTER 
and length of 1. ICHAR converts a character to its integer representation. 

LI-10 cannot pass %sl as argument to intrinsic function 
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The item %sl cannot be used as an argument to an intrinsic function. Only constants, 
simple variables, array elements, and substrung array elements may be used as arguments. 

LI-11 intrinsic function requires arguments) 

An attempt has been made to invoke an intrinsic function and no actual arguments were 
listed. 

LI-12 %sl argument type is invalid for this generic function 

The type of the argument used in the generic intrinsic function is not correct. 

LI-13 this intrinsic function cannot be passed as an argument 

Only the specific name of the intrinsic function can be used as an actual argument. The 
generic name may not be used. When the generic and intrinsic names are the same, use the 
INTRINSIC statement. 

LI-14 expecting %sl argument, but %s2 argument was found 

An argument of type %s2 was passed to a function but an argument of type %sl was 
expected. 

LI-15 intrinsic function was assigned wrong type 

The declared type of an intrinsic function does not agree with the actual type. 

LI-16 intrinsic function %sl is not FORTRAN 77 standard 

The specified intrinsic function is provided as an extension to the FORTRAN 77 language. 

LI-17 argument to ALLOCATED intrinsic function must be an allocatable array or character*(*) 
variable 


The argument to the intrinsic function ALLOCATED must be an allocatable array or 
character*(*) variable. 

LI-18 invalid argument to ISIZEOF intrinsic function 

The argument to the intrinsic function ISIZEOF must be a user-defined structure name, a 
symbol name, or a constant. 


Mixed Mode 

MD-01 relational operator has a logical operand 

The operands of a relational expression must either be both arithmetic or both character 
expressions. The operand indicated is a logical expression. 

MD-02 mixing DOUBLE PRECISION and COMPLEX types is not FORTRAN 77 standard 

The mixing of items of type DOUBLE PRECISION and COMPLEX in an expression is an 
extension to the FORTRAN 77 language. 
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MD-03 operator not expecting %sl operands 

Operands of type %sl cannot be used with the indicated operator. The operators **, /, *, +, 
and - may only have numeric type data. The operator // may only have character type data. 

MD-04 operator not expecting %sl and %s2 operands 

Operands of conflicting type have been encountered. For example, in a relational 
expression, it is not possible to compare a character expression to an arithmetic expression. 
Also, the type of the left hand operand of the field selection operator must be a user-defined 
structure. 

MD-05 complex quantities can only be compared using .EQ. or .NE. 

Complex operands cannot be compared using less than (.LT.), less than or equal (.LE.), 
greater than (.GT.), or greater than or equal (.GE.) operators. 

MD-06 unary operator not expecting %sl type 

The unary operators, + and —, may only be used with numeric types. The unary operator 
.NOT. may be used only with a logical or integer operand. The indicated operand was of 
type %sl which is not one of the valid types. 

MD-07 logical operator with integer operands is not FORTRAN 77 standard 

Integer operands are permitted with the logical operators .AND., .OR., ,EQV., .NEQV., 
.NOT. and .XOR. as an extension to the FORTRAN 77 language. 

MD-08 logical operator %sl is not FORTRAN 77 standard 

The specified logical operator is an extension to the FORTRAN 77 standard. 

Memory Overflow 

MO-01 %sl exceeds compiler limit of %d2 bytes 

An internal compiler limit has been reached. %sl describes the limit and %d2 specifies the 
limit. 

MO-02 out of memory 

All available memory has been used up. During the compilation phase, memory is 
primarily used for the symbol table. During execution, memory is used for file descriptors 
and buffers, and dynamically allocatable arrays and character*(*) variables. 

MO-03 dynamic memory exhausted due to length of this statement - statement ignored 

There was not enough memory to encode the specified statement. This message is usually 
issued when the compiler is low on memory or if the statement is a very large statement 
that spans many continuation lines. This error does not terminate the compiler since it may 
have been caused by a very large statement. The compiler attempts to compile the 
remaining statements. 
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MO-04 attempt to deallocate an unallocated array or character*(*) variable 

An attempt has been made to deallocate an array that has not been previously allocated. An 
array or character*(*) variable must be allocated using an ALLOCATE statement. 

MO-05 attempt to allocate an already allocated array or character*(*) variable 

An attempt has been made to allocate an array or character*(*) variable that has been 
previously allocated in an ALLOCATE statement. 


Parentheses 

PC-01 missing or misplaced closing parenthesis 

An opening parenthesis ’(’ was found but no matching closing parenthesis ’)’ was found 
before the end of the statement. 

PC-02 missing or misplaced opening parenthesis 

A closing parenthesis ’)’ was found before the matching opening parenthesis 

PC-03 unexpected parenthesis 

A parenthesis was found in a statement where parentheses are not expected. 

PC-04 unmatched parentheses 

The parentheses in the expression are not balanced. 

PRAGMA Compiler Directive 
PR-01 expecting symbolic name 

Every auxiliary pragma must refer to a symbol. This error is issued when the symbolic 
name is illegal or missing. Valid symbolic names are formed from the following 
characters: a dollar sign, an underscore, digits and any letter of the alphabet. The first 
character of a symbolic name must be alphabetic, a dollar sign, or an underscore. 

PR-02 illegal size specified for VALUE attribute 

The VALUE argument attribute of an auxiliary pragma contains in illegal length 
specification. Valid length specifications are 1, 2, 4 and 8. 

PR-03 illegal argument attribute 

An illegal argument attribute was specified. Valid argument attributes are VALUE, 
REFERENCE, or DATA_REFERENCE. 

PR-04 continuation line must contain a comment character in column 1 

When continuing a line of an auxiliary pragma directive, the continued line must end with a 
back-slash (’V) character and the continuation line must begin with a comment character 
(’c\ ’C’ or ’*’) in column 1. 


Open Watcom F77 Diagnostic Messages 233 




Appendices 


PR-05 expecting ’%sl’ near ’%s2’ 

A syntax error was found while processing a PRAGMA directive. %s 1 identifies the 
expected information and %s2 identifies where in the pragma the error occurred. 

PR-06 in-line byte sequence limit exceeded 

The limit on the number of bytes of code that can be generated in-line using a an auxiliary 
pragma has been exceeded. The limit is 127 bytes. 

PR-07 illegal hexadecimal data in byte sequence 

An illegal hexadecimal constant was encountered while processing a in-line byte sequence 
of an auxiliary pragma. Valid hexadecimal constants in an in-line byte sequence must 
begin with the letter Z or z and followed by a string of hexadecimal digits. 

PR-08 symbol ’%sl ’ in in-line assembly code cannot be resolved 

The symbol %sl, referenced in an assembly language instruction in an auxiliary pragma, 
could not be resolved. 

RETURN Statement 

RE-01 alternate return specifier only allowed in subroutine 

An alternate return specifier, in the RETURN statement, may only be specified when 
returning from a subroutine. 

RE-02 RETURN statement in main program is not FORTRAN 77 standard 

A RETURN statement in the main program is allowed as an extension to the FORTRAN 77 
standard. 

SAVE Statement 

SA-01 COMMON block %sl saved but not properly defined 

The named COMMON block %sl was listed in a SAVE statement but there is no named 
COMMON block defined by that name. 

SA-02 COMMON block %sl must be saved in every subprogram in which it appears 

The named COMMON block %sl appears in a SAVE statement in another subprogram and 
is not in a SAVE statement in this subprogram. If a named COMMON block is specified in 
a SAVE statement in a subprogram, it must be specified in a SAVE statement in every 
subprogram in which that COMMON block appears. 

SA-03 name already appeared in a previous SAVE statement 

The indicated name has already been referenced in another SAVE statement in this 
subprogram. 
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Statement Functions 

SF-01 statement function definition contains duplicate dummy arguments 

A dummy argument is repeated in the argument list of the statement function. 

SF-02 character length of statement function name must not be (*) 

If the type of a character function is character, its length specification must not be (*); it 
must be a constant integer expression. 

SF-03 statement function definition contains illegal dummy argument 

A dummy argument of type CHARACTER must have a length specification of an integer 
constant expression that is not (*). 

SF-04 cannot pass %sl %s2 to statement function 

The actual arguments to a statement function can be any expression except character 
expressions involving the concatenation of an operand whose length specification is (*) 
unless the operand is a symbolic constant. 

SF-05 %sl actual argument was passed to %s2 dummy argument 

The indicated actual argument is of type %sl which is not the same type as that of the 
dummy argument of type %s2. 

SF-06 incorrect number of arguments passed to statement function %sl 

The number of arguments passed to statement function %sl does not agree with the number 
of dummy arguments specified in its definition. 

SF-07 type of statement function name must not be a user-defined structure 

The type of a statement function cannot be a user-defined structure. Valid types for 
statement functions are: LOGICAL* 1, LOGICAL, INTEGER* 1, INTEGER*2, 

INTEGER, REAL, DOUBLE PRECISION, COMPLEX, DOUBLE COMPLEX, and 
CHARACTER. If the statement function is of type CHARACTER, its length specification 
must not be (*); it must be an integer constant expression. 

Source Management 

SM-01 system file error reading %sl - %s2 

An I/O error, described by %s2, has occurred while reading the FORTRAN source file 
%sl. 

SM-02 error opening file %sl - %s2 

The FORTRAN source file %sl could not be opened. The error is described by %s2. 
SM-03 system file error writing %sl - %s2 

An I/O error, described by %s2, has occurred while writing to the file %sl. 
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SM-06 error opening %sl - too many temporary files exist 

The compiler was not able to open a temporary file for intermediate storage during code 
generation. Temporary files are created in the directory specified by the TMP environment 
variable. If the TMP environment variable is not set, the temporary file is created in the 
current directory. This error is issued if an non-existent directory is specified in the TMP 
environment variable, or more than 26 concurrent compiles are taking place in a 
multi-tasking environment and the directory in which the temporary files are created is the 
same for all compilation processes. 

SM-07 generation of browsing information failed 

An error occurred during the generation of browsing information. For example, a disk full 
condition encountered during the creation of the browser module file will cause this 
message to be issued. Browsing information is generated when the /db switch is specified. 

Structured Programming Features 

SP-01 cannot have both ATEND and the END= specifier 

It is not valid to use the AT END control statement and the END= option on the READ 
statement. Only one method can be used to control the end-of-file condition. 

SP-02 ATEND must immediately follow a READ statement 

The indicated AT END control statement or block does not immediately follow a READ 
statement. The AT END control statement or block is executed when an end-of-file 
condition is encountered during the read. 

SP-03 block label must be a symbolic name 

The indicated block label must be a symbolic name. A symbolic name must start with a 
letter and contain no more than 32 letters and digits. A letter is an upper or lower case 
letter of the alphabet, a dollar sign ($), or an underscore (_). A digit is a character in the 
range ’0’ to ’9’. 

SP-04 could not find a structure to %sl from 

This message is issued in the following cases. 

1. There is no control structure to QUIT from. The QUIT statement will transfer 
control to the statement following the currently active control structure or return 
from a REMOTE BLOCK if no other control structures are active within the 
REMOTE BLOCK. 

2. There is no control structure to EXIT from. The EXIT statement is used to exit a 
loop-processing structure such as DO, DO WHILE, WHILE and LOOP, to 
return from a REMOTE BLOCK regardless of the number of active control 
structures within the REMOTE BLOCK, or to transfer control from a GUESS or 
ADMIT block to the statement following the ENDGUESS statement. 

3. There is no active looping control structure from which a CYCLE statement can 
be used. A CYCLE statement can only be used within a DO, DO WHILE, 
WHILE and LOOP control structure. 
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SP-05 REMOTE BLOCK is not allowed in the range of any control structure 

An attempt has been made to define a REMOTE BLOCK inside a control structure. 

Control structures include IF, LOOP, WHILE, DO, SELECT and GUESS. When a 
REMOTE BLOCK definition is encountered during execution, control is transferred to the 
statement following the corresponding END BLOCK statement. 

SP-06 the SELECT statement must be followed immediately by a CASE statement 

The statement immediately after the SELECT statement must be a CASE statement. The 
SELECT statement allows one of a number of blocks of code (case blocks) to be selected 
for execution by means of an integer expression in the SELECT statement. 

SP-07 cases are overlapping 

The case lists specified in the CASE statements in the SELECT control structure are in 
conflict. Each case list must specify a unique integer constant expression or range. 

SP-08 select structure requires at least one CASE statement 

In the SELECT control structure, there must be at least one CASE statement. 

SP-09 cannot branch to %dl from outside control structure in line %d2 

The statement in line %d2 passes control to the statement %dl in a control structure. 
Control may only be passed out of a control structure or to another place in that control 
structure. Control structures include DO, GUESS, IF, LOOP, SELECT, and WHILE. 

SP-10 cannot branch to %dl inside structure on line %d2 

The statement attempts to pass control to statement %dl in line %d2 which is in a control 
structure. Control may only be passed out of a control structure or to another place in that 
control structure. Control structures include DO, GUESS, IF, LOOP, SELECT, and 
WHILE. 

SP-11 low end of range exceeds the high end 

The first number, the low end of the range, is greater than the second number, the high end 
of the range. 

SP-12 default case block must follow all case blocks 

The default case block in the SELECT control structure must be the last case block. A case 
block may not follow the default case block. 

SP-13 attempt to branch out of a REMOTE BLOCK 

An attempt has been made to transfer execution control out of a REMOTE BLOCK. A 
REMOTE BLOCK may only be terminated with the END BLOCK statement. Execution 
of a REMOTE BLOCK is similar in concept to execution of a subroutine. 

SP-14 attempt to EXECUTE undefined REMOTE BLOCK %sl 
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The REMOTE BLOCK %sl referenced in the EXECUTE statement does not exist in the 
current program unit. A REMOTE BLOCK is local to the program unit in which it is 
defined and may not be referenced from another program unit. 

SP-15 attempted to use REMOTE BLOCK recursively 

An attempt was made to execute a REMOTE BLOCK which was already active. 

SP-16 cannot RETURN from subprogram within a REMOTE BLOCK 

An illegal attempt has been made to execute a RETURN statement within a REMOTE 
BLOCK in a subprogram. 

SP-17 %sl statement is not FORTRAN 77 standard 

The statement %sl is an extension to the FORTRAN 77 language. 

SP-18 %sl block is unfinished 

The block starting with the statement %sl does not have the ending block statement. For 
example: ATENDDO-ENDATEND, DO-ENDDO, GUESS-ENDGUESS. IF-ENDIF, 
LOOP-ENDLOOP, SELECT-ENDSELECT, STRUCTURE-ENDSTRUCTURE and 
WHILE-ENDWHILE. 

SP-19 %sl statement does not match with %s2 statement 

The statement %sl, which ends a control structure, cannot be used with statement %s2 to 
form a control structure. Valid control structures are: LOOP - ENDLOOP, LOOP - 
UNTIL, WHILE - ENDWHILE, and WHILE - UNTIL. 

SP-20 incomplete control structure found at %sl statement 

The ending control structure statement %sl was found and there was no preceding 
matching beginning statement. Valid control structures include: ATENDDO - 
ENDATEND, GUESS - ENDGUESS, IF - ENDIF, LOOP - ENDLOOP, REMOTE 
BLOCK - ENDBLOCK, and SELECT - ENDSELECT. 

SP-21 %sl statement is not allowed in %s2 definition 

Statement %sl is not allowed between a %s2 statement and the corresponding END %s2 
statement. For example, an EXTERNAL statement is not allowed between a 
STRUCTURE and END STRUCTURE statement, a UNION and END UNION statement, 
or a MAP and END MAP statement. 

SP-22 no such field name found in structure %sl 

A structure reference contained a field name that does not belong to the specified structure. 

SP-23 multiple definition of field name %sl 

The field name %sl has already been defined in a structure. 

SP-24 structure %sl has not been defined 
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An attempt has been made to declare a symbol of user-defined type %sl. No structure 
definition for %sl has occurred. 

SP-25 structure %sl has already been defined 

The specified structure has already been defined as a structure. 

SP-26 structure %sl must contain at least one field 

Structures must contain at least one field definition. 

SP-27 recursion detected in definition of structure %sl 

Structure %sl has been defined recursively. For example, it is illegal for structure X to 
contain a field that is itself a structure named X. 

SP-28 illegal use of structure %sl containing union 

Structures containing unions cannot be used in formatted I/O statements or data initialized. 

SP-29 allocatable arrays cannot be fields within structures 

An allocatable array cannot appear as a field name within a structure definition. 

SP-30 an integer conditional expression is not FORTRAN 77 standard 

A conditional expression is the expression that is evaluated and checked to determine a 
path of execution. A conditional expression can be found in an IF or WHILE statement. 
FORTRAN 77 requires that the conditional expression be a logical expression. As an 
extension, an integer expression is also allowed. When an integer expression is used, it is 
converted to a logical expression by comparing the value of the integer expression to zero. 

SP-31 %sl statement must be used within %s2 definition 

The statement identified by %sl must appear within a definition identified by %s2. 


Subprograms 

SR-01 name can only appear in an EXTERNAL statement once 

A function/subroutine name appears more than once in an EXTERNAL statement. 

SR-02 character function %sl may not be called since size was declared as (*) 

In the declaration of the character function name, the length was defined to be (*). The (*) 
length specification is only allowed for external functions, dummy arguments or symbolic 
character constants. 

SR-03 %sl can only be used an an argument to a subroutine 

The specified class of an argument must only be passed to a subroutine. For example, an 
alternate return specifier is illegal as a subscript or an argument to a function. 
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SR-04 name cannot appear in both an INTRINSIC and EXTERNAL statement 

The same name appears in an INTRINSIC statement and in an EXTERNAL statement. 
SR-05 expecting a subroutine name 

The subroutine named in the CALL statement does not define a subroutine. A subroutine is 
declared in a SUBROUTINE statement. 

SR-06 %sl statement not allowed in main program 

The main program can contain any statements except a LUNCTION, SUBROUTINE, 
BLOCK DATA, or ENTRY statement. A SAVE statement is allowed but has no effect in 
the main program. A RETURN statement in the main program is an extension to the 
FORTRAN 77 language. 

SR-07 not an intrinsic FUNCTION name 

A name in the INTRINSIC statement is not an intrinsic function name. Refer to the 
Language Reference for a complete list of the intrinsic functions. 

SR-08 name can only appear in an INTRINSIC statement once 

An intrinsic function name appears more than once in the intrinsic function list. 

SR-09 subprogram recursion detected 

An attempt has been made to recursively invoke a subprogram, that is, to invoke an already 
active subprogram. 

SR-10 two main program units in the same file 

There are two places in the program that signify the start of a main program. The 
PROGRAM statement or the first statement that is not enclosed by a PROGRAM, 
FUNCTION, SUBROUTINE or BLOCK DATA statement specifies the main program 
start. 

SR-11 only one unnamed %sl is allowed in an executable program 

There may only be one unnamed BLOCK DATA subprogram or main program in an 
executable program. 

SR-12 function referenced as a subroutine 

An attempt has been made to invoke a function using the CALL statement. 

Subscripts and Substrings 

SS-01 substringing offunction or statement function return value is not FORTRAN 77 standard 

The character value returned from a CHARACTER function or statement function cannot 
be substrung. Only character variable names and array element names may be substrung. 
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SS-02 substringing valid only for character variables and array elements 

An attempt has been made to substring a name that is not defined to be of type 
CHARACTER and is neither a variable nor an array element. 

SS-03 subscript expression out of range %s 1 does not exist 

An attempt has been made to reference an element in an array that is out of bounds of the 
declared array size. The array element %sl does not exist. 

SS-04 substring expression (%dl:%d2) is out of range 

An expression in the substring is larger than the string length or less than the value 1. The 
substring expression must be one in which 

1 <= %dl <= %d2 <= len 

Statements and Statement Numbers 

ST-01 statement number %dl has already been defined in line %d2 

The two statements, in line %d2 and the current line, in the current program unit have the 
same statement label number, namely %dl. 

ST-02 statement function definition appears after first executable statement 

There is a statement function definition after the first executable statement in the program 
unit. Statement function definitions must follow specification statements and precede 
executable statements. Check that the statement function name is not an undeclared array 
name. 

ST-03 %sl statement must not be branched to but was in line %d2 

Line %d2 passed execution control down to the statement %sl. The specification 
statements, ADMIT, AT END, BLOCK DATA, CASE, ELSE, ELSE IF, END AT END, 
END BLOCK, END DO, END LOOP, END SELECT, END WHILE, ENTRY, FORMAT, 
FUNCTION, OTHERWISE, PROGRAM, QUIT, REMOTE BLOCK, SAVE, 
SUBROUTINE, and UNTIL statements may not have control of execution transferred to it. 

ST-04 branch to statement %dl in line %d2 not allowed 

An attempt has been made to pass execution control up to the statement labelled %d 1 in 
line %d2. The specification statements, ADMIT, AT END, BLOCK DATA, CASE, ELSE, 
ELSE IF, END AT END, END BLOCK, END DO, END LOOP, END SELECT, END 
WHILE, ENTRY, FORMAT, FUNCTION, OTHERWISE, PROGRAM, QUIT, REMOTE 
BLOCK, SAVE, SUBROUTINE, and UNTIL statements may not have control of 
execution transferred to it. 

ST-05 specification statement must appear before %sl is initialized 

The variable %sl has been initialized in a specification statement. A COMMON or 
EQUIVALENCE statement then references the variable. The COMMON or 
EQUIVALENCE statement must appear before the item can be initialized. Use the DATA 
statement to initialize data in this case. 
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ST-06 statement %dl was referenced as a FORMAT statement in line %d2 

The statement in line %d2 references statement label %dl as a FORMAT statement. The 
statement at that label is not a FORMAT statement. 

ST-07 IMPLICIT statement appears too late 

The current IMPLICIT statement is out of order. The IMPLICIT statement may be 
interspersed with the PARAMETER statement but must appear before other specification 
statements. 

ST-08 this statement will never be executed due to the preceding branch 

Because execution control will always be passed around the indicated statement, the 
statement will never be executed. 

ST-09 expecting statement number 

The keyword GOTO or ASSIGN has been detected and the next part of the statement was 
not a statement number as was expected. 

ST-10 statement number %dl was not used as a FORMAT statement in line %d2 

The statement at line %d2 with statement number %dl is not a FORMAT statement but the 
current statement uses statement number %dl as if it labelled a FORMAT statement. 

ST-11 specification statement appears too late 

The indicated specification statement appears after a statement function definition or an 
executable statement. All specification statements must appear before these types of 
statements. 

ST-12 %sl statement not allowed after %s2 statement 

The statement %sl cannot be the object of a %s2 statement. %s2 represents a logical IF or 
WHILE statement. These statements include: specification statements, ADMIT, AT END, 
CASE, DO, ELSE, ELSE IF END, END AT END, END BLOCK, END DO, END GUESS, 
ENDIF, END LOOP, END SELECT, END WHILE, ENTRY, FORMAT, FUNCTION, 
GUESS, logical IF, block IF, LOOP, OTHERWISE, PROGRAM, REMOTE BLOCK, 
SAVE, SELECT, SUBROUTINE, UNTIL, and WHILE. 

ST-13 statement number must be 99999 or less 

The statement label number specified in the indicated statement has more than 5 digits. 

ST-14 statement number cannot be zero 

The statement label number specified in the indicated statement is zero. Statement label 
numbers must be greater than 0 and less than or equal to 99999. 

ST-15 this statement could branch to itself 

The indicated statement refers to a statement label number which appears on the statement 
itself and therefore could branch to itself, creating an endless loop. 
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ST-16 missing statement number %dl - used in line %d2 

A statement with the statement label number %dl does not exist in the current program 
unit. The statement label number is referenced in line %d2 of the program unit. 

ST-17 uttdecodeable statement or misspelled word %sl 

The statement cannot be identified as an assignment statement or any other type of 
FORTRAN statement. The first word of a FORTRAN statement must be a statement 
keyword or the statement must be an assignment statement. 

ST-18 statement %dl will never be executed due to the preceding branch 

The statement with the statement label number of %dl will never be executed because the 
preceding statement will always pass execution control around the statement and no other 
reference is made to the statement label. 

ST-19 expecting keyword or symbolic name 

The first character of a statement is not an alphabetic. The first word of a statement must 
be a statement keyword or a symbolic name. Symbolic names must start with a letter 
(upper case or lower case), a dollar sign ($) or an underscore (_). 

ST-20 number in %sl statement is longer than 5 digits 

The number in the PAUSE or STOP statement is longer than 5 digits. 

ST-21 position of DATA statement is not FORTRAN 77 standard 

The FORTRAN 77 standard requires DATA statements to appear after all specification 
statements. As an extension to the standard, Watcom FORTRAN 77 allows DATA 
statements to appear before specification statements. Note that in the latter case, the type of 
the symbol must be established before data initialization occurs. 

Subscripted Variables 

SV-01 variable %sl in array declarator must be in COMMON or a dummy argument 

The variable %sl was used as an array declarator in a subroutine or function but the 
variable was not in a COMMON block nor was it a dummy argument in the FUNCTION, 
SUBROUTINE or ENTRY statement. 

SV-02 adjustable/assumed size array %sl must be a dummy argument 

The array %sl used in the current subroutine or function must be a dummy argument. 

When the array declarator is adjustable or assumed-size, the array name must be a dummy 
argument. 

SV-03 invalid subscript expression 

The indicated subscript expression is not a valid integer expression or the high bound of the 
array is less than the low bound of the array when declaring the size of the array. 
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SV-04 invalid number of subscripts 

The number of subscripts used to describe an array element does not match the number of 
subscripts in the array declaration. The maximum number of subscripts allowed is 7. 

SV-05 using %sl name incorrectly without list 

An attempt has been made to assign a value to the declared array %sl. Values may only be 
assigned to elements in the array. An array element is the array name followed by integer 
expressions enclosed in parentheses and separated by commas. 

SV-06 cannot substring array name %sl 

An attempt has been made to substring the array %sl. Only an array element may be 
substrung. 

SV-07 %sl treated as an assumed size array 

A dummy array argument has been declared with 1 in the last dimension. The array is 
treated as if an had been specified in place of the 1. This is done to support a feature 
called "pseudo-variable dimensioning" which was supported by some FORTRAN IV 
compilers and is identical in concept to FORTRAN 77 assumed-size arrays. 

SV-08 assumed size array %sl cannot be used as an Ho list item or a format/unit identifier 

Assumed size arrays (arrays whose last dimension is ’*’) must not appear as an i/o list item 
(i.e. in a PRINT statement), a format identifier or an internal file specifier. 

SV-09 limit of 65535 elements per dimension has been exceeded 

On the IBM PC, for 16-bit real mode applications, the number of elements in a dimension 
must not exceed 65535. 


Syntax Errors 

SX-01 unexpected number or name %sl 

The number or name %sl is in an unexpected place in the statement. 

SX-02 bad sequence of operators 

The indicated arithmetic operator is out of order. An arithmetic operator is one of the 
following: **, *, /, +, and -. All arithmetic operators must be followed by at least a 
primary. A primary is an array element, constant, (expression), function name, or variable 
name. 

SX-03 invalid operator 

The indicated operator between the two arithmetic primaries is not a valid operator. Valid 
arithmetic operators include: **,*,/,+, and —. A primary is an array element, constant, 
(expression), function name, or variable name. 

SX-04 expecting end of statement after right parenthesis 
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The end of the statement is indicated by the closing right parenthesis but more characters 
were found on the line. Multiple statements per line are not allowed in FORTRAN 77. 

SX-05 expecting an asterisk 

The next character of the statement should be an asterisk but another character was found 
instead. 

SX-06 expecting colon 

A colon (:) was expecting but not found. For example, the colon separating the low and 
high bounds of a character substring was not found. 

SX-07 expecting colon or end of statement 

On a control statement, a word was found at the end of the statement that cannot be related 
to the statement. The last word on several of the control statements may be a block label. 
All block labels must be preceded by a colon (:). 

SX-08 missing comma 

A comma was expected and is missing. There must be a comma after the statement 
keyword AT END when a statement follows. A comma must occur between the two 
statement labels in the GO TO statement. A comma must occur between the expressions in 
the DO statement. A comma must occur between the names listed in the DATA statement 
and specification statements. A comma must occur between the specifiers in I/O 
statements. 

SX-09 expecting end of statement 

The end of the statement was expected but more words were found on the line and cannot 
be associated to the statement. FORTRAN 77 only allows for one statement per line. 

SX-10 expecting integer variable 

The name indicated in the statement must be of type INTEGER but is not. 

SX-11 expecting %sl name 

A name with the characteristic %sl was expected at the indicated place in the statement but 
is missing. 

SX-12 expecting an integer 

The length specifier, as in the IMPLICIT statement, must be an integer constant or an 
integer constant expression. The repeat specifier of the value to be assigned to the 
variables, as in the DATA statement, must be an integer constant or an integer constant 
expression. 

SX-13 expecting INTEGER, REAL, or DOUBLE PRECISION variable 

The indicated DO variable is not one of the types INTEGER, REAL, or DOUBLE 
PRECISION. 
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SX-14 missing operator 

Two primaries were found in an expression and an operator was not found in between. A 
primary is an array element, constant, (expression), function name, or variable name. 

SX-15 expecting a slash 

A slash is expected in the indicated place in the statement. Slashes must be balanced as 
parentheses. Slashes are used to enclose the initial data values in specification statements 
or to enclose names of COMMON blocks. 

SX-16 expecting %sl expression 

An expression of type %sl is required. 

SX-17 expecting a constant expression 

A constant expression is required. 

SX-18 expecting INTEGER, REAL, or DOUBLE PRECISION expression 

The indicated expression is not one of type INTEGER, REAL, or DOUBLE PRECISION. 
Each expression following the DO variable must be an expression of one of these types. 

SX-19 expecting INTEGER or CHARACTER constant 

In the PAUSE and STOP statement, the name following the keyword must be a constant of 
type INTEGER or of type CHARACTER. This constant will be printed on the console 
when the statement is executed. 

SX-20 unexpected operator 

An operand was expected but none was found. For example, in an I/O statement, the 
comma is used to separate I/O list items. Two consecutive commas without an I/O list item 
between them would result in this error. 

SX-21 no closing quote on literal string 

The closing quote of a literal string was not found before the end of the statement. 

SX-22 missing or invalid constant 

In a DATA statement, the constant required to initialize a variable was not found or 
incorrectly specified. 

SX-23 expecting character constant 

A character constant is required. 
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Type Statements 

TY-01 length specification before array declarator is not FORTRAN 77 standard 

An array declarator specified immediately after the length specification of the array is an 
extension to the FORTRAN 77 language. 

TY-02 %dl is an illegal length for %s2 type 

The length specifier %dl is not valid for the type %s2. For type LOGICAL, valid lengths 
are 1 and 4. For the type INTEGER, valid lengths are 1, 2, and 4. For the type REAL, 
valid lengths are 4 and 8. For the type COMPLEX, valid lengths are 8 and 16. On the IBM 
PC, the length specifier for items of type CHARACTER must be greater than 0 and not 
exceed 65535. 

TY-03 length specifier in %sl statement is not FORTRAN 77 standard 

A length specifier in certain type specification statements is an extension to the FORTRAN 
77 language. These include: LOGICAL* 1, LOGICAL*4, INTEGER* 1, INTEGER*2, 
INTEGER*4, REAL*4, REAL*8, COMPLEX*8, and COMPLEX* 16. 

TY-04 length specification not allowed with type %sl 

A length specification is not allowed in a DOUBLE PRECISION or DOUBLE COMPLEX 
statement. 

TY-05 type of %sl has already been established as %s2 

The indicated name %sl has already been declared to have a different type, namely %s2. 
The name %sl cannot be used in this specification statement. 

TY-06 type of %sl has not been declared 

The indicated name %sl has not been declared. This message is only issued when the 
IMPLICIT NONE specification statement is used. 

TY-07 %sl of type %s2 is illegal in %s3 statement 

The symbol %sl with type %s2 cannot be used in statement %s3. For example, a symbol 
of type STRUCTURE cannot be used in a PARAMETER statement. 

Variable Names 

VA-01 illegal me of %sl name %s2 in %s3 statement 

The name %s2 has been defined as %sl and cannot be used as a name in the statement %s3. 

VA-02 symbolic name %sl is longer than 6 characters 

Symbolic names greater than 6 characters is an extension to the FORTRAN 77 language. 
The maximum length is 32 characters. 

VA-03 %sl has already been defined as a %s2 
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The name %sl has been previously defined as a %s2 in another statement and cannot be 
redefined as specified in the indicated statement. 

VA-04 %sl %s2 has not been defined 

The name %s2 has been referenced to be a %sl but has not been defined as such in the 
program unit. 

VA-05 %sl is an unreferenced symbol 

The name %sl has been defined but not referenced. 

VA-06 %sl already belongs to this NAMELIST group 

The name %sl can only appear in a NAMELIST group once. However, a name can belong 
to multiple NAMELIST groups. 

VA-07 %sl has been used but not defined 

%sl has not been defined before using it in a way that requires its definition. Note that 
symbols that are equivalenced, belong to a common block, are dummy arguments, or 
passed as an argument to a subprogram, will not be checked to ensure that they have been 
defined before requiring a value. 

VA-08 dynamically allocating %sl is not FORTRAN 77 standard 

Allocatable storage are extensions to the FORTRAN 77 standard. 

VA-09 %sl in NAMELIST %s2 is illegal 

Symbol %sl appearing in NAMELIST %s2 is illegal. Symbols appearing in a NAMELIST 
cannot be dummy arguments, allocatable, or of a user-defined type. 
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11ntroduction to Open Watcom FORTRAN 77 


Welcome to the Open Watcom FORTRAN 77 2.0 development system. Open Watcom FORTRAN 77 is 
an Open Source successor to commercial compilers previously marketed by Sybase, Powersoft and 
originally WATCOM International Corp. 

Version 2.0 of Open Watcom FORTRAN 77 is a professional, optimizing, multi-platform FORTRAN 77 
compiler with a comprehensive suite of development tools for developing and debugging both 16-bit and 
32-bit applications for DOS, extended DOS, Novell NLMs, 16-bit OS/2, 32-bit OS/2, Windows 3.x, 
Windows 95/98/Me, Win32s, and Windows NT/2000/XP (Win32). 

You should read the entire contents of this booklet, as it contains information on new programs and 
modifications that have been made since the previous release. 

Special NOTE to users of previous versions! See the section entitled "Release Notes for Open Watcom 
FORTRAN 77 2.0" on page 35 to determine if you need to recompile your application. 


1.1 What is in version 2.0 of Open Watcom FORTRAN 77? 

Version 2.0 incorporates the features professional developers have been demanding: 

Open, Multi-target Integrated Development Environment 

The IDE allows you to easily edit, compile, link, debug and build applications for 16-bit systems 
like DOS, OS/2 1.x, and Windows 3.x and 32-bit systems like extended DOS, Novell NLMs, 
OS/2, Windows 3.x (Win32s), Windows 95/98/Me, and Windows NT/2000/XP. Projects can be 
made up of multiple targets which permit a project to include EXEs and DLLs. The IDE produces 
makefiles for the project which can be viewed and edited with a text editor. The IDE is hosted 
under Windows 3.x, Windows 95/98/Me, Windows NT/2000/XP, and 32-bit OS/2. 

The Widest Range of Intel x86 Platforms 


Host Platforms 


• DOS (command line) 

• 32-bit OS/2 (IDE and command line) 

• Windows 3.x (IDE) 

• Windows 95/98/Me (IDE and command line) 

• Windows NT/2000/XP (IDE and command line) 

16-bit Target Platforms 

•DOS 

• Windows 3.x 
•OS/2 1.x 
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32-bit Target Platforms 

• Extended DOS 

• Win32s 

• Windows 95/98/Me 

• Windows NT/2000/XP 

• 32-bit OS/2 

• Novell NLMs 

Cross-Platform Development Tools 

The core tools in the package permit cross-platform development that allows developers to exploit 
the advanced features of today’s popular 32-bit operating systems, including Windows 95/98/Me, 
Windows NT/2000/XP, and OS/2. Cross-platform support allows you to develop on a host 
development environment for execution on a different target system. 

Multi-Platform Debugger 

The new debugger advances developer productivity. New features include redesigned interface, 
ability to set breakpoints on nested function calls, improved C++ and DLL debugging, reverse 
execution, and configurable interface. Graphical versions of the debugger are available under 
Windows 3.x, Windows 95/98/Me, Windows NT/2000/XP, and 32-bit OS/2. Character versions 
of the debugger are available under DOS, Windows 3.x, Windows NT/2000/XP, and 32-bit OS/2. 
Lor VIDEO fans, we have kept the command line compatibility from the original debugger. 

Performance Analysis 

The Open Watcom Execution Sampler and Open Watcom Execution Profiler are performance 
analysis tools that locate heavily used sections of code so that you may focus your efforts on these 
areas and improve your application's performance. 

Editor The Open Watcom Editor is a context sensitive source editor, integrated into the Windows 3.x, 
Windows 95/98/Me and Windows NT/2000/XP version of the IDE. 

Graphical Development Tools 

Open Watcom FORTRAN 77 includes a suite of graphical development tools to aid development 
of Windows 3.x, Windows 95/98/Me and Windows NT/2000/XP applications. The development 
tools include: 

Resource Editors Enable you to create resources for your 16-bit and 32-bit Windows 

applications. For 32-bit OS/2 PM development. Open Watcom FORTRAN 
77 interoperates with IBM’s OS/2 Developer's Toolkit (available from IBM). 
These tools have been seamlessly integrated into the IDE. The resource 
compiler allows you to incorporate these resources into your application. 

Resource Compiler Produces a compiled resource file from a source file. 

Zoom Magnifies selected sections of your screen. 

Heap Walker Displays memory usage for testing and debugging purposes. 

Spy Monitors messages passed between your application and Windows. 

DDESpy Monitors all DDE activity occurring in the system. 
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Dr. Watcom Enables you to debug your program by examining both the program and the 

system after an exception occurs; monitors native applications running under 
Windows 3.x, Windows 95/98/Me or Windows NT/2000/XP. 


Assembler 

An assembler is included in the package. It is compatible with a subset of the Microsoft macro 
assembler (MASM). 

Royalty-free 32-bit DOS Extender 

Open Watcom FORTRAN 77 includes the DOS/4GW 32-bit DOS extender by Tenberry Software 
with royalty-free run-time and virtual memory support up to 32MB. 

Support for wide range of DOS Extenders 

Open Watcom FORTRAN 77 allows you to develop and debug applications based on the 
following DOS extender technology: CauseWay DOS Extender, Tenberry Software’s DOS/4G 
and Phar Lap’s TNT DOS Extender. You can also develop applications using DOS/32A and 
FlashTek’s DOS Extender but, currently, there is no support for debugging these applications. 

Sample programs and applications 

Open Watcom FORTRAN 77 includes a large set of sample applications to demonstrate the 
integrated development environment. 

1.2 Technical Support and Services 

We are committed to ensuring that our products perform as they were designed. Although a significant 
amount of testing has gone into this product, you may encounter errors in the software or documentation. 
Technical support is provided on an informal basis through the Open Watcom FORTRAN 77 newsgroups. 
Please visit http://www.openwatcom.org/ for more information. 

1.2.1 Resources at Your Fingertips 

Open Watcom FORTRAN 77 contains many resources to help you find answers to your questions. The 
documentation is the first place to start. With each release of the product, we update the manuals to answer 
the most frequently asked questions. Most of this information is also accessible through on-line help. 

The "README" file in the main product directory contains up-to-date information that recently became 
available. 

Answers to frequently asked questions are available on the Open Watcom World Wide Web server 
(http://www.openwatcom.org/). 

1.2.2 Contacting Technical Support 

Our technical support is available to help resolve technical defects in the software. Note that all support is 
currently informal and free. The following are ways to contact technical support. 
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Newsgroups The easiest way to get support is through the Open Watcom newsgroups at 
news://news.openwatcom.org/. 

World Wide Web You can also submit bug reports or enhancement requests through the Open Watcom bug 
tracking system at http://bugzilla.openwatcom.org/. 

1.2.3 Information Technical Support Will Need to Help You 

The more information you can provide to technical support, the faster they can help you solve your 
problem. A detailed description of the problem, short sample program, and a summary of steps to duplicate 
the problem (including compiler and linker options) are essential. Concise problem reports allow technical 
support to quickly pinpoint the problem and offer a resolution. Here is a list of information that will help 
technical support solve the problem: 

Contact information 

We would like your name, as well as telephone and fax numbers where you can be reached 
during the day. 

Product information 

Please tell us the product name and exact version number. 

Hardware configuration 

Please tell us what type of processor you are using (e.g., 2.2GHz Intel Pentium 4), how 
much memory is present, what kind of graphics adapter you are using, and how much 
memory it has. 

Software configuration 

Please tell us what operating system and version you are using. 

Concise problem report with short sample program 

Please provide a complete description of the problem and the steps to reproduce it. A 
small, self-contained program example with compile and link options is ideal. 

1.2.4 Suggested Reading 

There are a number of good books and references that can help you answer your questions. Following is a 
list of some of the books and documents we feel might be helpful. This is by no means an exhaustive list. 
Contact your local bookstore for additional information. 

1.2.4.1 DOS Developers 

PC Interrupts, Second Edition 

Ralf Brown and Jim Kyle; Addison-Wesley Publishing Company, 1994. 

Relocatable Object Module Format Specification, VI.1 

The Tool Interface Standards (TIS) OMF specification can be obtained from the Open 
Watcom website. Here is the URL. 

http://www.openwatcom.org/ftp/devel/docs/omf.pdf 


This file contains a PDF version of the TIS OMF V 1.1 specification. 
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1.2.4.2 Extended DOS Developers 

Extending DOS—A Programmer’s Guide to Protected-Mode DOS, 2nd Edition 
Ray Duncan, et al; Addison-Wesley Publishing Company, 1992. 

DOS Protected-Mode Interface (DPMI) Specification 

The DPMI 1.0 specification can be obtained from the Open Watcom website. Here is the 
URL. 


http://www.openwatcom.org/ftp/devel/docs/dpmilO.pdf 


This file contains a PDF version of the DPMI 1.0 specification. 

1.2.4.3 Windows 3.x Developers 

Microsoft Windows Programmer’s Reference 

Microsoft Corporation; Microsoft Press, 1990. 

Programming Windows 3.1, Third Edition 

Charles Petzold; Microsoft Press, 1992. 

Windows Programming Primer Plus 

Jim Conger; Waite Group Press, 1992. 

1.2.4.4 Windows NT Developers 

Advanced Windows NT 

Jeffrey Richter; Microsoft Press. 1994. 

Inside Windows NT 

Helen Custer; Microsoft Press. 1993. 

Microsoft Win32 Programmer’s Reference, Volume One 

Microsoft Corporation; Microsoft Press, 1993. 

1.2.4.5 OS/2 Developers 

The Design of OS/2 

H.M. Deitel and M.S. Kogan; Addison-Wesley Publishing Company, 1992. 

OS/2 Warp Unleashed, Deluxe Edition 

David Moskowitz and David Kerr, et al; Sams Publishing, 1995. 
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2 Installation 


The package contains the following components: 

• Open Watcom FORTRAN 77 CD-ROM 

• This manual 


2.1 Hardware and Software Requirements 

Open Watcom FORTRAN 77 requires the following minimum configuration: 

• IBM PC compatible 

• An 80386 or higher processor 

• 8 MB of memory 

• Hard disk with enough space available to install the components you require. 

• A CD-ROM disk drive 

In addition to the above requirements, you need one of the following operating systems: 

• DOS version 5.0 or higher 

• Microsoft Windows version 3.1 running in enhanced mode 

• Microsoft Windows 95 or higher 

• Microsoft Windows NT version 3.1 or higher 
•IBM OS/2 2.1 or higher 


2.2 The README File 


Before you install Open Watcom FORTRAN 77, you should read the contents of the "README" file 
which is stored in the root directory of the CD-ROM. It contains valuable, up-to-date information 
concerning this product. 

2.3 Installing Open Watcom FORTRAN 77 

The installation program in this version has been completely redesigned with several new "smart" features. 
If you have installed a previous version of Open Watcom FORTRAN 77 then you should install Open 
Watcom FORTRAN 77 2.0 into the same path (except for the reason described in the following paragraph). 
It will examine a previous installation to determine what features were previously installed. It will use this 
information to establish default settings for the installation that you are about to attempt. Of course, you 
can add or remove features as you progress through the installation steps. 
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If you are installing only one of the Open Watcom C/C++ or Open Watcom FORTRAN 77 products and 
you have an older version of the other product, we do NOT recommend that you install the new product 
into the same directory as the old product. The Open Watcom C/C++ and Open Watcom FORTRAN 77 
products are compatible at the same version number. However, the Open Watcom C/C++ and Open 
Watcom FORTRAN 77 products are usually NOT compatible across different version numbers. If this is 
the case, care must be exercised when switching between use of the two products. Environment variables 
such as PATH and WATCOM must be modified and/or corrected. System files such as CONFIG.SYS 
and SYSTEM. INI must be modified and/or corrected. 

If you are installing both Open Watcom C/C++ 2.0 and Open Watcom FORTRAN 77 2.0, we recommend 
that you install both products under the same directory. This will eliminate duplication of files and, as a 
result, reduce the total required disk space. The two products share the use of certain environment variables 
which point to the installation directory. If separate installation directories are used, problems will arise. 

When you install Open Watcom C/C++ and Open Watcom FORTRAN 77 in the same directory, you 
should not deselect any options when running the second installation; otherwise the second product’s install 
may remove files that were installed (and are required) by the first product’s install. This isn't an issue if 
you only have one of Open Watcom C/C++ or Open Watcom FORTRAN 77. The problem is that Open 
Watcom C/C++ and Open Watcom FORTRAN 77 don’t know about the installation options you have 
selected for each other’s product. 

If you wish to create a backup of your previous version, please do so before installing Open Watcom 
FORTRAN 77 2.0. 

If you decide to install Open Watcom FORTRAN 77 2.0 into a different directory than the previously 
installed version, you will have to manually edit system files (e.g., CONFIG.SYS, AUTOEXEC.BAT, 
SYSTEM.INI) after the installation process is complete to remove the old version from various 
environment variables (e.g., PATH, DEVICE=). This is necessary since the path to the new version will 
appear after the path to the old version. To avoid this extra work, we recommend installing the new version 
into the same path as the old version. 

As an example, here are a few of the environment variables and "RUN" directives that are modified/added 
to the OS/2 CONFIG. SYS file. You should make sure that all references to the older version of the 
software are removed. 


Example: 

LIBPATH=...;D:\WATCOM\BINP\DLL;... 

SET PATH=. . .;D:\WATCOM\BINP;D:\WATCOM\BINW; . . . 
SET HELP=...;D:\WATCOM\BINP\HELP;... 

SET BOOKSHELF=...;D:\WATCOM\BINP\HELP;... 

SET INCLUDE=...;D:\WATCOM\H\OS2;D:\WATCOM\H; 

SET WATCOM=D:\WATCOM 

SET EDPATH=D:\WATCOM\EDDAT 

RUN=D:\WATCOM\BINP\NMPBIND.EXE 


You may wish to run Open Watcom FORTRAN 77 under more than one operating system on the same 
personal computer. For every operating system that you use, simply start up the operating system and run 
the corresponding install procedure. 

If you run the Windows 3.x installation procedure, you do not need to run the DOS installation procedure 
also. 

If you plan to use Win-OS/2 as a development platform under OS/2, you must run the Windows 3.1 install 
program (selecting Windows 3.1 host support). 
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Installation 


Place the CD-ROM disk in your CD-ROM drive. Select one of the following procedures depending on the 
host operating system that you are currently running. Below, substitute the CD-ROM drive specification 
for "x:". 

DOS Enter the following command: 

x:\setup 

Windows 3.x Start Windows 3.x and choose Run from the File menu of the Program Manager. 

Enter the following command: 

x:\setup 

Windows 95/98/Me Choose Run from the Start menu and enter the following command: 

x:\setup 

Windows NT/2000/XP Log on to an account that is a member of the "Administrator" group so that you 

have sufficient rights to modify the system environment. Choose Run from the File 
menu of the Program Manager. Enter the following command: 

x:\setup 

OS/2 Start an OS/2 session and enter the following command: 

x:\install 


2.4 Incremental Installation 


You may wish to install Open Watcom FORTRAN 77, and subsequently install features that you omitted in 
the first install. You can also remove features that you no longer wish to have installed. You can achieve 
this as follows: 

1. Start the installation program. 

2. Select any new features that you wish to install. 

3. Deselect any features that you wish to remove. 

4. Re-run the installation program for each host operating system that you use. 

2.5 System Configuration File Modifications 

The install program makes changes to your operating system startup files to allow Open Watcom 
FORTRAN 77 to run. We strongly recommend that you allow the install program to modify your system 
configuration files for you, but you may do it by hand. The changes required may be found in any of the 
following files which have been placed in the root of the installation directory: 

CONFIG.NEW Changes required for CONFIG. SYS (DOS, Windows, Windows 95/98/Me, 

OS/2) 

AUTOEXEC.NEW Changes required for AUTOEXEC. BAT (DOS, Windows, Windows 95/98/Me, 

OS/2) 
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CHANGES.ENV Changes required for the Windows NT/2000/XP environment 


2.6 Installation Notes for Windows 3.x 

1. When you use the Integrated Development Environment under Windows 3.x, it is important that 
the IDE’s batch server program be able to run in the background. Therefore, make sure that the 
"Exclusive in Foreground" checkbox is NOT checked in the "Scheduling" options of "386 
Enhanced" in the "Control Panel". 

2. When you use the Integrated Development Environment under Windows 3.x, the line 

OverlappedIO=ON 

in your "SYSTEM.INI" file can cause problems. This controls (disables) the queuing of DisklO 
and makes some changes between DOS box timings to allow some processes to finish. 

3. When you use the Integrated Development Environment under Windows 3.x, it is important that 
the line 

NoEMMDriver=ON 

not appear in your "SYSTEM.INI" file. It will prevent a link from succeeding in the IDE.. 

4. When you use the Integrated Development Environment under Windows 3.x on the NEC 
PC-9800 series, it is important that the line 

InDOSPolling=TRUE 

not appear in your "SYSTEM.INI" file. It will prevent a make from succeeding in the IDE. 

5. Central Point Software’s anti-virus programs (VDEFEND, VSAFE, VWATCH) conflict with the 
Integrated Development Environment under Windows 3.x. 

6. The Program Information File "BATCHBOX.PIF" is used by the Integrated Development 
Environment (IDE) to start up a background batch server for compiling, linking, etc. The PIF 
references "COMMAND.COM". If you are using a substitute for "COMMAND.COM" such as 
"4DOS.COM" then you must modify the PIF accordingly using a PIF editor. 


2.7Installation Notes for OS/2 

1. The Integrated Development Environment (IDE) uses the IBM OS/2 Enhanced System Editor 
(EPM) for editing text files. You must ensure that EPM is installed in your OS/2 system if you 
are planning to use the IDE. You can selectively install the Enhanced Editor by running the 
OS/2 Setup and Installation program (Selective Install) and choosing "Enhanced Editor" from 
the "Tools and Games" detail page. 

2. On some systems with limited memory that use the UNDELETE feature of OS/2, compile times 
may be slow because OS/2 is saving copies of compiler temporary files. You may start the 
BATSERV process using the OS/2 STARTUP . CMD file with DELDIR turned off as illustrated 
below. 
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Installation 


SET OLD_ DEL_ DIR=%DELDIR% 

SET DELDIR= 

DETACH C:\WATCOM\BINP\BATSERV.EXE 
SET DELDIR=%OLD_ DEL_ DIR% 

SET OLD_ DEL_ DIR= 


3. If you plan to use the Named Pipe Remote Debugging support of the Open Watcom Debugger 
then the NMPSERV. EXE . program must be running. It may be started during OS/2 
initialization via a "RUN=" statement in your CONFIG. SYS file or manually as needed through 
the DETACH command. 


Installation Notes for OS/2 
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3 Hands-on Introduction to Open Watcom 
FORTRAN 77 


Let’s get started and introduce some of the tools that are in Open Watcom FORTRAN 77. The purpose of 
this chapter is to briefly test out the new graphical tools in Open Watcom FORTRAN 77 using an existing 
application. 

In this tutorial, we will take an existing set of FORTRAN 77 source files, create a project in our integrated 
development environment, and perform the following tasks: 

• Add multiple targets 

• Make a target 

• Make all targets 

• Execute the program 

• Debug the program 

• Correct errors 

• Sample and profile the executable 

• Save the project 

• Terminate the session 


3.1 Outline 


Open Watcom’s Integrated Development Environment (IDE) manages the files and tools that a programmer 
uses when developing a project. This includes all the source files, include files, libraries, compiler!s), 
linkers, preprocessors, etc. that one uses. 

The IDE has a graphical interface that makes it easy to visualize the make-up of a project. A single IDE 
session shows a project. If the project consists of a number of components, such as two executables and 
one library, these are each shown as target windows in the project window. Each target window shows the 
files that are needed to construct the target and is associated via its filename extension with a rule that 
describes the construction mechanism. For example, a filename with the extension ".EXE" may be 
associated with the rule for constructing 32-bit Windows executables, or a filename with the extension 
".LIB" may be associated with the rule for constructing static libraries. Different projects can refer to the 
same target. If they do, the target is shared and can be manipulated via either project, with changes made 
through one affecting the other. 

The IDE itself is a collection of programs that manages the various files and tools used to create the target 
libraries and executables. It creates makefile(s) from the information in the target descriptions and invokes 
Open Watcom Make to construct the targets themselves. A configuration file contains built-in knowledge 
of the Open Watcom compilers, editors. Profiler, and Browser, as well as all their switches. 


Outline 
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3.2 The Open Watcom FORTRAN 77 Tutorial 

This tutorial walks you through the creation and execution of a FORTRAN 77 program under Windows. 
This will give you an understanding of the basic concepts of the IDE and its components, and it will detail 
the steps involved in project development. The result of this tutorial is a three dimensional drawing of a 
kitchen which you can manipulate using either the menus or the icons on the toolbar. You can rotate and 
resize the drawing, as well as adjust the lighting and contrast. 

To begin, start the IDE. This is done by double-clicking on the "IDE" icon in the Open Watcom 
FORTRAN 77 window. 

A status field at the bottom of the IDE window indicates the function of the icon on the toolbar over which 
your mouse cursor is currently positioned. If the status area does not show you the function of the icons as 
you move the mouse cursor over them, check that no item in the menu bar is highlighted (if one is 
highlighted, press the Alt key). 



Figure 1. The initial IDE screen 


3.2.1 Defining a Project 

In this tutorial, you will be creating a new project called KITCHEN. Here are the steps required to 
accomplish this task. 

1. Define a new project by pulling down the File menu and selecting the New Project... item. You 
can also define a new project by clicking on the "Create a new project" icon on the toolbar. 

2. A choice of different sample project directories is available. Assuming that you installed the 
Open Watcom FORTRAN 77 software in the \WATCOM directory, you will find the sample 
project directories in the following directory: 

\WATCOM\SAMPLES\IDE\FORTRAN 

For purposes of this tutorial, we recommend that you select one of the following project 
directories: 
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WIN for an example of 16-bit Windows 3.x application development when using 

Windows 3.x under DOS as a host development system, 

WIN386 for an example of 32-bit Windows 3.x application development when using 
Windows 3.x under DOS as a host development system, 

WIN32 for an example of 32-bit Win32 application development when using Windows 

NT/2000/XP or Windows 95/98/Me as a host development system, and 

OS2 for an example of 32-bit OS/2 application development when using 32-bit OS/2 

as a host development system. 

Thus the target that we refer to below should be one of WIN, WIN386, WIN32, or OS2 
depending on your selection. The tutorial uses the WIN32 example for illustrative purposes. 
You will find some minor variations from your selected target environment. 

When asked for a project name, you can do one of two things: 

1. enter the following pathname: 

d:[path]\SAMPLES\IDE\FORTRAN\target\KITCHEN 

where d: [path] is the drive and path where you installed the Open Watcom 
software, or 

2. use the file browser to select the following directory: 

d:[path]\SAMPLES\IDE\FORTRAN\target 
and specify the filename kitchen . 



Figure 2. Creating a new project 

Press the Enter key or click on OK (OPEN). 

The project description will be stored in this file and the IDE will set the current working 
directory to the specified path during your session. 

3. You will be prompted for a target name. Since we will be attaching pre-defined targets, just 

click the Browse button when prompted for the target name. Select the "draw" target file (it will 
be one of drawl 6 .tgt, draw.tgt, draw32.tgt, drawos2 . tgt depending on your 
selection of target). 
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Figure 3. Attaching existing targets 

Press the Enter key or click on OK (OPEN). 

4. You can ignore the settings displayed for Target Environment and Image Type since the target 
definition already exists (we created it for you). The settings are important when you are 
defining a new target (i.e., one that was not predefined). 



Figure 4. Selecting a target type 

Press the Enter key or click on OK. 

A target window is created in the project window for the "draw" target. This window contains all of the 
files associated with the target. You can click on any of the "Folder" icons to hide or un-hide all files with 
a particular extension. For example, you may wish to un-hide all the files with a . bmp extension by 
clicking on the folder icon associated with bitmap files. 
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3.2.2 Adding Multiple Targets 

Open Watcom’s IDE allows you to have multiple targets in any particular project. Note that targets can be 
used by multiple projects. To add a new target to the project, do the following. 

1. Pull down the Targets menu and select the New Target... item. 

2. Enter button. tgt as the target name for the new target to be added to the project. Do not 
forget to include the . tgt extension. It is required when selecting a pre-existing target. 

3. You can ignore the settings displayed for Target Environment and Image Type since the target 
definition already exists (we created it for you). The settings are important when you are 
defining a new target (i.e., one that was not predefined). 

4. Press the Enter key or click on OK. 

A target window is created in the project window for the button target. 

3.2.3 Making a Target 

Open Watcom’s IDE will automatically generate the sequence of steps required to build or "make" each of 
the targets in a project. Note that the targets in a project can be made individually or collectively. To make 
the button . lib target, do the following. 

1. Click on the window of the target you wish to make. In this case, click on the button . lib 
target window. 

2. Pull down the Targets menu and select the Make item (you can also do this by clicking on the 
"Make the current target" icon on the toolbar, or by right-clicking on the target and selecting the 
Make item from the pop-up menu). 

The IDE will now construct a makefile based on its knowledge of the target and construction rules, and 
then invoke the make utility to create the target, in this case button . lib . The output of this procedure 
is displayed in the Log window. 

3.2.4 Making Ail Targets 

Click the "Make all targets in the project" icon on the toolbar to make all of the targets in the current 
project. If one target depends on another target, the latter target will be made first. In this tutorial 
button . lib will be made first (there will be nothing to do since it was made previously) and then 
draw??? .exe, since button. lib is in the list of files associated with draw???.exe. In each case, 
the IDE constructs makefiles based on its knowledge of the target and construction rules. The output of this 
procedure is displayed in the Log window. 
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Figure 5. Making one or more targets 


3.2.5 Executing the Program 

The project should have built without errors, so now you are ready to execute the program you have 
developed. 

Click on the draw? ? ? . exe target window and simply click on the "Run the current target" icon on the 
toolbar. You can also do this by selecting Run from the Targets menu, or right-clicking anywhere on the 
target window outside of the inner frame and selecting Run from the pop-up menu (right-clicking is context 
sensitive and the pop-up menu that results will vary depending on the area of the window in which you 
right-click). 
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Figure 6. The kitchen demo 

The demo you have created is a simple three dimensional drawing of a kitchen. By using either the icons 
on the toolbar or the menus you can rotate the picture left, right, up, and down, make the picture brighter or 
dimmer, move the picture closer or farther away, and increase or decrease the amount of contrast (this latter 
feature is found in the "Lighting" menu). Choose Exit from the File menu to exit the demo program when 
you are finished. 

3.2.6 Smart Editing 

The IDE recognizes the type of file you wish to edit, and invokes the appropriate editor for the task. To 
edit a file, you either double-click on it or select it and click the "Edit" icon on the toolbar. Files with a 
.c, . epp, .h, . hpp, .for, . asm or . rc extension are edited with a text editor; files with a .bmp, 
. ico, or . cur extension are edited with the Image Editor; files with a . dig or . res extension are 
edited with the Resource Editor. 
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Figure 7. The Open Watcom Editor for Windows 

Now we will edit one of the source files and introduce an error into the application. 

1. Double-click on the "draw" source file (i.e., draw? ? ? . for) to load the source file into the 
editor. 

2. Search for the line containing the text: 

c$ifdef undefined 

For Windows users, "Find" is in the "Edit" menu. If you are building a WIN386 application, 
search for the second line containing this text (located in subroutine memclear). 

3. Now, to introduce an error into the application, add the line 

c$define undefined 
just before the line containing c$ifdef. 

4. Save your changes by clicking on the "Write the current file to disk" icon or select Save from the 
File menu. 

5. Return to the IDE (by clicking on it if it is visible on your screen, or by using Alt-Tab), re-make 
your project, and run it. A fault occurs in your application, so the next step is to track down the 
problem using the Open Watcom Debugger. 

3.2.7 Debugging the Program 

To debug a program it must first be compiled to include debugging information. The IDE maintains two 
sets of switches for each target in a project. These are known as the Development Switches and the Release 
Switches. 

1. Right click on draw? ? ? . f or and select Source options from the pop-up menu. Select Fortran 

Compiler Switches from the sub-menu. 
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By default, your target is placed in development mode with the debugging switches for the 
compiler and linker set to include debugging information. You can either set the switches in 
each category manually or you can copy the default Release switches using the CopyRel button. 
This method of setting switches is especially convenient since you can specify everything from 
diagnostic, optimization, and code generation switches to special linker switches all without 
having to memorize a cryptic switch name — you simply click next to the switches you wish to 
use for a particular item. 

2. Scroll through the categories using the » button until you get to: 

4. Debugging Switches 

We can see that full debugging information was used in the compile, so just click on Cancel to 
exit this screen. 



Figure 8. Setting compiler switches 

3. To invoke the debugger, pull down the Targets menu and choose the Debug item or select the 
"Debug the current target" icon from the toolbar. 

The Open Watcom Debugger is designed to be as convenient and intuitive as possible, while at the same 
time providing a comprehensive and flexible environment for serious debugging. You can configure your 
environment to display exactly the information you require to be most productive. Among the windows 
available are source and assembly, modules, functions, calls, threads, images, watches, locals, globals, file 
variables, registers, 80x87 FPU, stack, I/O ports, memory display, and a log window. You can step through 
your source using the keys or icons on the toolbar. Execute one line at a time by stepping over calls or 
stepping into calls, or execute until the current function returns. Right-mouse button functionality gives 
context-sensitive pop-up menus. 
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Figure 9. The Open Watcom Debugger 

We know that a fault has occurred in draw? ? ? . exe, so we will run the application and examine the state 
of the program when the fault occurs. 

1. Click on the "go!" icon on the toolbar to begin execution of the program. The exception occurs 
and the source window shows the line 

arr( cnt ) = ch 

in the subroutine memclear as the last line executed before the exception. Examining the 
Locals window you will see that the array location or address, locale, is 0. This means that 
the array arr was mapped to location 0. For the 32-bit Windows example, we also needed to 
use the "array" pragma to force a far pointer reference to cause the exception. 

2. We can now move up the call stack by clicking on the "Move up the call stack" icon on the 
toolbar (red up arrow) to follow the program’s execution. On the previous executable line of 
code, we see memclear is called from the main program with three arguments. 

call memclear( 0, loc (Draw_ area) , isizeof(RECTL) ) 

We see that memclear is called with 0 as the first argument and loc (Draw_ area) as the 
second argument which is backwards to the way it should be. An artificial error was introduced 
for the purposes of this tutorial. 

3. By removing the line 
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c$define undefined 
we can undo this error. Exit the debugger. 

4. Double-click on draw? ? ? . f or to load the source file into the editor. 

5. Go to the line in question using "find" or "search" and delete the line. Save your changes by 
clicking on the "Write the current file to disk" icon or selecting Save from the File menu. 

6. Return to the IDE (by clicking on it if it is visible on your screen, or by using Alt-Tab) and 
re-make your project. 

7. Run your project to see the kitchen demo. 

3.2.8 Correcting an Error 

We are now going to introduce an error into the source code to illustrate another feature of the IDE. 

1. Double-click on draw? ? ? . f or to load the source file into the editor. 

2. Search for the line containing the text: 

c$ifdef undefined 
For Windows users, "Find" is in the "Edit" menu. 

3. Now, to introduce a syntax error into the application, add the line 

hThree_ d + 0 

just before the line containing c$ifdef. 

4. Save your changes by clicking on the "Write the current file to disk" icon or select Save from the 
File menu. 

5. Return to the IDE (by clicking on it if it is visible on your screen, or by using Alt-Tab). 

6. Click the "Make all targets in the project" icon to re-make the project. 

An error is encountered during the make and error message(s) appear in the log window. Additional 
information on the error is available by selecting the error, pulling down the Log menu and selecting the 
Help on Message item. 

1. Double-click on the error message 

drawwin.for(83): *ERR* ST-17 column 9, undecodeable statement or 
misspelled word HTHREE_ D 

The offending source file ( draw? ? ? . for) is loaded into the Editor and the cursor is 
positioned at the line which caused the error. 

2. Delete the line to correct the error. 
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3. Save your changes. 

4. Return to the IDE and re-make the project. 

3.2.9 Editing a Bitmap 

You can edit bitmaps, icons, or cursors associated with your project using Open Watcom’s Image Editor. 
Double-click on a file with a . bmp, . ico, or . cur extension and the file is loaded into the Image 
Editor. The editor has many features to design your images, including resizing, rotation, shifting, and a 
utility to take a "snapshot" of another image and import it. 



Figure 10. The Open Watcom Image Editor 

Suppose you wanted to change the color of the right-arrow icon in your application. 

1. If the "Folder" icon next to . bmp is closed, click on it to restore all the files with a . bmp 
extension to the file list. 

2. Scroll the window until the file right. bmp is visible. 

3. Double-click on right. bmp in the draw? ? ? . exe target window. 

4. Select the "Paint Can" icon from the Tool Palette. 

5. Select a color from the Color Palette. 

6. Click on the arrow. 

7. Save your changes using the "Save" icon on the toolbar and exit the Image Editor. 
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8. Click the "Make all targets in the project" icon to rebuild the project with the change 
incorporated. 

3.2.10 Editing Menus 

Next, you will add source files to the list of items that make up draw? ? ? . exe . 

1. Pull down the Sources menu and select the New Source... item. 

Note: You can do this either by choosing from the menu bar or by positioning the 

mouse over the file list area and clicking the right mouse button. The IDE 
displays a pop-up menu from which you can choose the desired action. 

2. Enter the filename draw. res (or drawos2 . res for OS/2). For OS/2, click OK when you 
have entered the source file name. For all other systems, click on Add when you have entered 
the source file name and then click on Close. Now we will remove the . rc file from the project 
so that our changes to the . res file will not be overwritten. When an . rc file is present, the 

. res file is generated from the . rc file. 

3. Right click on draw. rc (or drawos2 . rc for OS/2), then select Remove Source from the 
pop-up menu. 

4. Double-click on draw. res (or drawos2 . res). The Resource Editor is invoked, displaying 
all the available resources (in this case, icons, bitmaps, and menus). 



Figure 11. The Open Watcom Resource Editor 

5. Click on "Menu Resources". 

6. Double-click on "DrawMenu" in the right-hand box. This will bring up the Menu Editor. The 
Menu Editor displays the menus defined for the resource DrawMenu . You can specify pop-up 
menus, menu items and sub-items, text, separators, attributes, break styles, and memory flags. 
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Figure 12. The Open Watcom Menu Editor 

7. Click on MENU ITEM " SDimmer" in the item list window. 

8. In the "Item Text" window change the item to SDarker and then click on the "Change" button. 

9. Select Update from the File menu or click on the "Update the file with this menu" icon. 

10. Exit the Menu Editor. 


11. Now, select Save from the File menu or click on the "Save this file" icon and exit the Resource 
Editor. 

12. Click the "Make all targets in the project" icon to re-make the project. 


3.2.11 Sampling and Profiling an Executable 

Together, the Open Watcom Execution Sampler and the Open Watcom Execution Profiler allow you to 
pinpoint the areas of your code that are the most heavily used, indicating possible candidates for 
performance improvements. 

1. Click on the draw? ? ? . exe target. 
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2. Select the Sample item from the Targets menu item, or click on the "Run and sample the current 
target" icon from the toolbar. The Open Watcom Execution Sampler is invoked and your 
application begins to execute. 

3. Try rotating and resizing the image a few times. The sampler takes a "snapshot" of the code that 
is being executed at regular intervals. Exit the application. A samples file with extension . smp 
is created in the current directory. This file is input for the profiler. 

4. You are now ready to profile the executable. Do this by selecting Profile from the Targets 
menu, or by clicking on the "Profile the current target" icon on the toolbar. The profiler scans 
the . smp file and reports the activity in the various modules of the application. The percentage 
of time spent in the modules is indicated as an absolute percentage (percent of total samples) and 
as a relative percentage (percent of samples in the . exe image). 

5. Double-click on the module or routine names to step down to the exact source being executed 
when a sample was taken. For more details, you can adjust the sampling rate of the Sampler to 
get a better picture of your code. To do this, exit the Profiler, pull down the Targets menu, and 
select Target options, then Sample Switches... from the pop-up menus. Specify a sampling rate 
such as 2 (for 2 milliseconds), click on OK, then run the Sampler and Profiler again. 



Figure 13. The Open Watcom Execution Profiler 

3.2.12 Saving the Project and Terminating the Session 

You can now exit the IDE session by selecting Exit from the File menu. If you have not already saved your 
project, you will be prompted to do so. Choose "Yes" and the session ends. 


3.3 Tutorial Review 


In this tutorial, you created a project called kitchen. wp j, which was composed of two targets: 
draw? ? ? . exe and button . lib. You compiled and linked it into an executable program using the 
WMAKE utility, the Open Watcom FORTRAN 77 compiler, and the Open Watcom Linker. You executed 
it both directly and under the control of the Open Watcom Debugger.. You browsed the source, and made 
changes using the text and resource editors. Finally, you sampled and profiled the application. 
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When you saved the project, you created the following permanent files: 

• kitchen . wp j — describes the screen layout and refers to the target files called draw??? . tgt 
and button.tgt. 

• draw? ? ? . tgt — describes the target executable draw? ? ? . exe and all switches required to link 
it. It also describes the .for files and switches required to compile them. 

• button . tgt — describes the target library and all switches required to create it. It also describes 
the .for file and the switches used to build the library. 
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4 Documentation 


The following manuals comprise the Open Watcom FORTRAN 77 documentation set. When you install 
the software, the Open Watcom FORTRAN 77 documentation set is provided as on-line help files. 
Subsequent sections describe how to access this on-line help. 

The following describes the titles in the Open Watcom FORTRAN 77 documentation set. 

Open Watcom FORTRAN 77 User’s Guide 

This manual describes how to use Open Watcom FORTRAN 77. It contains an 
introduction to the compiler and a tutorial section. It also describes compiler options, 
include file processing, libraries, memory models, calling conventions, pragmas, in-line 
assembly, and environment variables. 

Open Watcom FORTRAN 77 Tools User’s Guide 

This manual describes the command line oriented tools including the compile and link 
utility, library manager, object file disassembler, far call optimization tool, assembler, patch 
utility, strip utility, make utility, and touch utility. 

Open Watcom Graphical Tools User’s Guide 

This manual describes Open Watcom’s Windows and OS/2 graphical tools including the 
Integrated Development Environment, Browser, Dr. Watcom, Spy, DDE Spy, Image 
Editor, Resource Editor, Sampler/Profiler, Resource Compiler, Heap Walker, Zoom, and 
Editor. 

Open Watcom FORTRAN 77 Programmer’s Guide 

This manual includes 5 major sections each of which describes operating system specific 
development issues. The operating systems covered include extended DOS, OS/2, 
Windows 3.x, Windows NT/2000/XP, Windows 95/98/Me, 32-bit Windows 3.x (using 
Open Watcom’s Supervisor technology) and Novell NLMs. Topics include creating a 
sample program, operating system specific error messages, and debugging techniques. 

Open Watcom FORTRAN 77 Language Reference 

This manual describes the ANSI FORTRAN 77 programming language and extensions 
which are supported by Open Watcom FORTRAN 77. 

Open Watcom FORTRAN 77 Graphics Library Reference 

This manual describes the graphics libraries supported by Open Watcom FORTRAN 77. 
The graphics functions are used to display graphical images such as lines and circles upon 
the screen. Functions are also provided for displaying text. 

Open Watcom Debugger User’s Guide 

This manual describes the Open Watcom Debugger and discusses advanced debugging 
techniques. 

Open Watcom Linker User’s Guide 

This manual describes how to use the Open Watcom Linker to generate executables for 
target systems such as extended DOS, Windows 3.x, Windows 95/98/Me, Windows 
NT/2000/XP, OS/2, and Novell NLMs. 
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4.1 Accessing On-line Documentation 

The following sections describe how to access the on-line help that is available for DOS, Windows and 
OS/2. 

4.1.1 On-line Documentation under DOS 

The Open Watcom Help program, WHELP , may be used under DOS to access on-line documentation. The 
Open Watcom Help command line syntax is: 

WHELP help_ file [topic_name] 

Notes: 

1. If helpjile is specified without an extension then "THP" is assumed. 

2. The topic_name parameter is optional. 

3. If topic_name is not specified, the default topic is "Table of Contents". 

4. If topic_name contains spaces then it must be enclosed in quotes. 

The following help files are available: 

CLIB Open Watcom C Library Reference 

FMIX Open Watcom FORTRAN 77 Master Index 

FPGUIDE Open Watcom FORTRAN 77 Programmer’s Guide 
FTOOLS Open Watcom FORTRAN 77 Tools User’s Guide 

FUGUIDE Open Watcom FORTRAN 77 User’s Guide (excludes Diagnostic Messages appendix 
which is available as a separate help file) 

F77LR Open Watcom FORTRAN 77 Language Reference 

F77GRAPH Open Watcom FORTRAN 77 Graphics Library Reference 

LGUIDE Open Watcom Linker User’s Guide 

F_README Open Watcom FORTRAN 77 Getting Started manual 

RESCOMP Documentation for the Open Watcom Resource Compiler (excerpt from the Open Watcom 
Graphical Tools User’s Guide) 

WD Open Watcom Debugger User’s Guide 

WPROF Documentation for the Open Watcom Execution Sampler and Open Watcom Execution 

Profiler (excerpt from the Open Watcom Graphical Tools User’s Guide) 
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WFCERRS Documentation for the Open Watcom F77 Diagnostic Messages (excerpt from the Open 
Watcom FORTRAN 77 User’s Guide). 

4.1.2 On-line Documentation under Windows 

On-line documentation is presented in the form of Windows Help files (".HLP" files). When the software 
is installed under Windows 3.x, Windows 95/98/Me or Windows NT/2000/XP, a number of program 
groups are created. You can access the on-line document by opening a program group and double-clicking 
on a help icon. 

Open Watcom FORTRAN 77 Group 

Getting Started Open Watcom FORTRAN 77 Getting Started 

Open Watcom FORTRAN 77 Tools Help Group 

Accelerator Editor Help Documentation for the Accelerator Editor (excerpt from the Open Watcom 

Graphical Tools User’s Guide) 

C Library Reference Open Watcom C Library Reference 

DDE Spy Help Documentation for the DDE Spy utility (excerpt from the Open Watcom 

Graphical Tools User’s Guide) 

Debugger Help Open Watcom Debugger User’s Guide 

Dialog Editor Help Documentation for the Dialogue Editor (excerpt from the Open Watcom 

Graphical Tools User’s Guide) 

Dr. Watcom Help Documentation for Dr. Watcom (excerpt from the Open Watcom Graphical 

Tools User’s Guide) 

Editor Help Documentation for the Open Watcom Editor (excerpt from the Open Watcom 

Graphical Tools User’s Guide) 

FORTRAN 77 Error Messages Documentation for the Open Watcom F77 Diagnostic Messages (excerpt 

from the Open Watcom FORTRAN 77 User’s Guide) 

FORTRAN 77 Master Index The master index for all of the Open Watcom FORTRAN 77 on-line help 

Heap Walker Help Documentation for the Heap Walker utility (excerpt from the Open Watcom 

Graphical Tools User’s Guide) 

IDE Help Documentation for the Interactive Development Environment (excerpt from the 

Open Watcom Graphical Tools User’s Guide) 

Image Editor Help Documentation for the Image Editor (exceipt from the Open Watcom Graphical 

Tools User’s Guide) 

Linker Guide Open Watcom Linker User’s Guide 

Menu Editor Help Documentation for the Menu Editor (excerpt from the Open Watcom Graphical 

Tools User’s Guide) 
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Profiler Help 

Documentation for the Open Watcom Execution Sampler and Open Watcom 
Execution Profiler (excerpt from the Open Watcom Graphical Tools User’s 
Guide) 

Programmer’s Guide 

Open Watcom FORTRAN 77 Programmer’s Guide 

Resource Compiler Help 

Documentation for the Resource Compiler (excerpt from the Open Watcom 
Graphical Tools User’s Guide) 

Resource Editor Help 

Documentation for the Resource Editor (excerpt from the Open Watcom 
Graphical Tools User’s Guide) 

Spy Help 

Documentation for the Spy utility (excerpt from the Open Watcom Graphical 
Tools User’s Guide) 

String Editor Help 

Documentation for the String Editor (excerpt from the Open Watcom Graphical 
Tools User’s Guide) 

Tools Guide 

Open Watcom FORTRAN 77 Tools User’s Guide 

User’s Guide 

Open Watcom FORTRAN 77 User’s Guide 

Zoom Help 

Documentation for the Zoom utility (excerpt from the Open Watcom Graphical 
Tools User’s Guide) 


4.1.3 On-line Documentation under OS/2 

On-line documentation is presented in the form of OS/2 Information files (".INF" files). When the software 
is installed under OS/2, the Open Watcom FORTRAN 77 folder is created. You can access the on-line 
document by opening the Open Watcom FORTRAN 77 folder and double-clicking on a help icon. 

C Library Reference Open Watcom C Library Reference 

Debugger Help Open Watcom Debugger User’s Guide 

FORTRAN 77 Error Messages Documentation for the Open Watcom F77 Diagnostic Messages (excerpt 

from the Open Watcom FORTRAN 77 User’s Guide) 

FORTRAN 77 Master Index The master index for all of the Open Watcom FORTRAN 77 on-line help 

Getting Started Open Watcom FORTRAN 77 Getting Started 

IDE Help Documentation for the Interactive Development Environment (excerpt from the 

Open Watcom Graphical Tools User’s Guide) 

Profiler Help Documentation for the Open Watcom Execution Sampler and Open Watcom 

Execution Profiler (excerpt from the Open Watcom Graphical Tools User’s 
Guide) 

Programmer’s Guide Open Watcom FORTRAN 77 Programmer’s Guide 
Tools Guide Open Watcom FORTRAN 77 Tools User’s Guide 
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5 Release Notes for Open Watcom FORTRAN 77 
2.0 


There are a number of enhancements and changes in this new version of Open Watcom FORTRAN 77. 

The following sections outline most of the major changes. You should consult the User’s Guide for full 
details on these and other changes made to the compiler and related tools. You should check the next 
section to determine if you need to recompile your application. 

5.1 Changes in 11.0 that may Require Recompilation 

Do not attempt to mix object code generated by earlier versions of the compilers with object code generated 
by this release or with the libraries provided in this release. 

clock() The clock function accuracy has changed from 100 ticks per second to 1000 ticks per 

second (i.e., CLOCKS_PER_SEC has changed). Source code that uses the clock function 
and CLOCKS_PER_SEC in its calculations must be recompiled before linking the 
application with new libraries. 

5.2 Major Differences from Version 10.6 

The following sections summarize the major differences from the previous release of Watcom FORTRAN 
77. 


• Some of the Win32 and 32-bit OS/2 versions of our tools are now available in DLL form. 
EXE DLL Description 


wlink wlink Open Watcom Linker 

wlib wlibd Open Watcom Library Manager 

This provides better performance when using the Integrated Development Environment or Open 
Watcom Make. See the description of the ! loaddll preprocessing directive in Open Watcom 
Make for more information. 

5.2.1 Changes to the Code Generator for 11.0 

• A new optimization, "branch prediction", has been added. This optimization is enabled by the 
"OBP" or "OX" compiler options. The code generator tries to increase the density of cache use by 
predicting branches based upon heuristics (this optimization is especially important for Intel’s 
Pentium Pro). 

• We have added Multi-media Extensions (MMX) support to the in-line assembler. 


Major Differences from Version 10.6 35 







Chapter 5 


5.2.2 Changes to the Compiler Tools for 11.0 

• The Open Watcom Linker supports incremental linking. 

• The Open Watcom Linker can now process COFF and ELF format object files, as well as OMF et al. 
The Open Watcom Linker can now read both AR-format (Microsoft compatible) libraries and 
old-style OMF libraries. 

• Support for creating 16-bit DOS overlaid executables has been removed from the linker. 

• The Open Watcom Library Manager (WLIB) can now process COFF and ELF format object files, as 
well as OMF et al. The Open Watcom Library Manager can now read/write both AR-format 
(Microsoft compatible) libraries and old-style OMF libraries. The default output format is 
AR-format and this can be changed by switches. The Open Watcom Library Manager can output 
various format import libraries. 

• We have added Multi-media Extensions (MMX) support to the Open Watcom Assembler (WASM). 

• A new version of the Open Watcom Disassembler (WDIS) is included. It can process ELF, COFF 
or OMF object files and ELF, COFF or PE format (Win32) executables. 

The old disassembler (WDISASM) has been retired and is not included in the package. 

• We have added new tool front-ends that emulate Microsoft tools. These are: 

• rc 

These programs take the usual Microsoft arguments and translate them, where possible, into 
equivalent Open Watcom arguments and spawn the equivalent Open Watcom tools. 

• Open Watcom Make now processes Microsoft format makefiles when the "ms" option is used. 

5.2.3 Changes to the C/C++ Libraries for 11.0 

• We have added multi-byte and wide character (including UNICODE) support to the libraries. 

• We have added Multi-media Extensions (MMX) support to the libraries. 

• The clock function accuracy has changed from 100 ticks per second to 1000 ticks per second (i.e., 
CLOCKS _PER_SEC has changed). 

5.2.4 Changes to the DOS Graphics Library for 11.0 

• The graphics library now performs the VESA test before testing for vendor specific graphics cards. 
This fix is intended to broaden the number of graphics cards that are supported. 
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5.2.5 Changes in Microsoft Win32 SDK Support for 11.0 

• The Win32 SDK is included for Windows 95 and Windows NT platforms. 

5.3 Changes in 10.6 that may Require Recompilation 

_diskfree_t The struct members of the _diskfree_t structure has been changed from UNSIGNED 

SHORTs to UNSIGNED INTs. This is to deal with possible HPFS partitions whose size 
will overflow a short, as well as Microsoft compatibility. 

clock() The clock function accuracy has changed from 100 ticks per second to 1000 ticks per 

second (i.e., CLOCKS_PER_SEC has changed). Source code that uses the clock function 
and CLOCKS_PER_SEC in its calculations must be recompiled before linking the 
application with new libraries. 

5.4 Major Differences from Version 10.5 

The following sections summarize the major differences from the previous release of Watcom FORTRAN 
77. 

5.4.1 Windows 95 Help File Format 

We have included Windows 95 format help files. 

5.4.2 Changes to the C Library 

The following new functions were added to the library. 

_getw read int from stream file 

_putw write int to stream file 

The clock function accuracy has changed from 100 ticks per second to 1000 ticks per second (i.e., 
CLOCKS_PER_SEC has changed). 

5.4.3 Changes to the Image Editor 

• Support has been added for >16 colors for bitmaps. 

• Support has been added for 16 X 16 icons. 

• Support has been added for 48 X 48 icons. 
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5.4.4 Changes to the Dialog Editor 

• Support has been added for Windows 95 controls. 

• Support has been added for adding new control styles to existing controls. 

• Support has been added for new dialog styles. 

• Support has been added for allowing help IDs to be specified in dialog and control statements. 

• Support has been added for generating new resource statements in .RC files. 

5.4.5 Changes to the Resource Editor 

• Support has been added for new Windows 95 resource types. 

• Support has been added for generating new resource statements in .RC files. 

5.4.6 Changes to the Resource Compiler 

• Support has been added for extended styles for dialogs. 

• Support has been added for the RCINCLUDE keyword. 

5.5 Major Differences from Version 9.5 

• The functionality of Open Watcom FORTRAN 77/16 and Open Watcom FORTRAN 77/32 is 
included in a single package. 

• OS/2 3.0 Warp is supported. 

• Windows NT 3.5 is supported. 

• Windows 95 (Chicago) is supported. 

• An Integrated Development Environment for Windows 3.x, Windows 95, Windows NT and OS/2 
PM is included. 

• New, redesigned debugger with GUI interfaces for Windows 3.x, Windows 95, Windows NT and 
OS/2 PM is included. 

• TCP/IP remote debug servers for OS/2 and Windows NT are included. 

• The optimizer has been enhanced. 

• New, redesigned user interface for the Profiler. 

• Windows resource editing tools are included: 
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Dialog Editor 
Bitmap Editor 
Resource Editor 
Menu Editor 
String Editor 
Accelerator Editor 

• Windows development tools are included: 

Dr. Watcom (a post mortem debug utility) 

Spy (Windows message spy program) 

DDESpy 
Heap Walker 
Zoom 

• On-line documentation is included. 

• Creation of FlashTek DOS extender applications is supported. 

• Compiler executables have been created that run under all supported operating systems. They are 
located in the BINW directory. 

5.5.11tems No Longer Supported 

• Debugging of Ergo OS/386 DOS extender applications 

• DESQView remote debugging 

5.5.2 Changes that may Require Recompilation 

FORTRAN applications should not require recompilation, but you should recompile your application if you 
want to take full advantage new features in the debugger. 

5.6 Major Differences from Version 9.0 

The following lists some of the new features/differences between version 9.5 and 9.0. 

1. The "/resource" option has been added and allows run-time messages to be placed in the 
executable file as resource information instead of being linked with the application. The 
resource file containing these messages is called "wf77.res" and is locating in the root of the 
directory in which you installed the software. The strip utility (WSTRIP) can be used to place 
the resource information in the executable file. Special libraries for processing resource 
information will be required when you link your application. These libraries are called 
"wresf.lib" (for 32-bit register calling convention), "wresfs.lib" (for 32-bit stack calling 
convention), "wresm.lib" (for 16-bit medium memory model), and "wresl.lib" (for 16-bit large 
and huge memory models) and are located in the "lib386" and "lib286" directories of the 
directory in which you installed the software. 

2. The 75" option has been added and causes the compiler to generate code that is optimized for 
the Pentium. This is the default. The "/fp5" option has been added and causes the compiler to 
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generate floating-point code that is optimized for the Pentium. This is not the default. The 
default floating-point option is "/fp3". 

3. The 73" option has been added and causes the compiler to generate code optimized for a 80386 
processor. The 74" option has been added and causes the compiler to generate code optimized 
for a 80486 processor. The 75" option has been added and causes the compiler to generate code 
that is optimized for the Pentium. In addition, the "/fp5" option has been added and causes the 
compiler to generate floating-point code that is optimized for the Pentium. 

4. The "/descriptor" option has been added which specifies that string descriptors are to be passed 
for character arguments. You can specify the "/nodescriptor" option if you do not want string 
descriptors to be passed for character arguments. Instead, the pointer to the actual character data 
and the length will be passed as two arguments. The arguments for the length will be passed as 
additional arguments following the normal argument list. For character functions, the pointer to 
the data and the length of the character function will be passed as the first two arguments. 

5. The "oi" option has been added. This option causes code for statement functions to be generated 
in-line. 

6. The floating-point model used when generating in-line 80x87 instructions has changed. If you 
wish to call subprograms compiled with version 9.0 you must specify the "/fpr" option. 

7. Support for records in text files separated by only a line feed character has been added. 
Previously, records in text files had to be separated by a carriage return/line feed sequence. 

8. The "/debug" option has been divided into two separate options. The "/bounds" option generates 
array and character subscript checking code. The "/trace" option generates code that allows a 
run-time traceback to be generated when a error is issued. 

9. The "/quiet" option has been added to suppress banner/summary information. The "terminal" 
option only affects the display of diagnostic messages (extensions, warnings and errors). For 
example, compiling with the "/quiet" option will only display diagnostic messages (if any). 

10. The "/cc" option has been added. It specifies that unit 6 is a carriage control device and that 
output to this unit will be assumed to contain carriage control characters. Note that a blank 
carriage control character will automatically be generated for list-directed output. 

11. The "/automatic" option causes all local variables (including arrays) to be allocated on the stack. 
Care should be taken when using this option since the stack requirements of your application 
may increase dramatically. 

12. The "/wild" option has been added. It suppresses the compile-time checking that normally 
causes an error to be issued when an attempt is made to transfer control into a block structure 
from outside the block structure and vice versa. This option is only to be used when compiling 
existing code that contains GOTO statements of this type; it does not encourage this style of 
programming. 

13. National language support has been added. The "/japanese" option causes the compiler to 
process Japanese double-byte characters in variable names and character data. Similarly, the 
"/Chinese" option will process Traditional Chinese characters and the "/korean" will process 
Korean characters. 

14. The "/ob" option has been added. This allows the code generator to use register ESP as a base 
register to reference local variables and subprogram arguments. Note that when this option is 
specified, the compiler will abort when there is not enough memory to optimize the subprogram. 
By default, the code generator uses more memory-efficient algorithms when a low-on-memory 
condition is detected. 

15. The GROWHANDLES() function has be added. This function increases the number of files that 
can be opened by a program to the specified amount. The value returned is the new maximum. 
This may be less than the requested amount because of operating system limitations. 

16. The IARGC() and IGETARGO functions have been added. IARGC is an integer function that 
returns the argument count. IGETARG is an integer function that takes two arguments. The 
first argument is of type INTEGER and is the index of the argument to be returned. The second 
argument is of type CHARACTER and is used to return the argument. The value returned by the 
function is the length of the argument. 
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17. The SHARE= specifier has been added to the OPEN statement. It allows the program to specify 
how other processes can access a file that is opened by the original process. Possible values for 
the SHARE= specifier are as follows. 


DENYRW 

DENYWR 

DENYRD 

DENYNO 

COMPAT 


- deny read and write access 

- deny write access 

- deny read access 

- allow read and write access 

- compatibility mode 
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6 Sybase Open Watcom Public License 


USE OF THE SYBASE OPEN WATCOM SOFTWARE DESCRIBED BELOW ("SOFTWARE") IS 
SUBJECT TO THE TERMS AND CONDITIONS SET FORTH IN THE SYBASE OPEN 
WATCOM PUBLIC LICENSE SET FORTH BELOW ("LICENSE"). YOU MAY NOT USE THE 
SOFTWARE IN ANY MANNER UNLESS YOU ACCEPT THE TERMS AND CONDITIONS OF 
THE LICENSE. YOU INDICATE YOUR ACCEPTANCE BY IN ANY MANNER USING 
(INCLUDING WITHOUT LIMITATION BY REPRODUCING, MODIFYING OR 
DISTRIBUTING) THE SOFTWARE. IF YOU DO NOT ACCEPT ALL OF THE TERMS AND 
CONDITIONS OF THE LICENSE, DO NOT USE THE SOFTWARE IN ANY MANNER. 

Sybase Open Watcom Public License version 1.0 

1. General; Definitions. This License applies only to the following software programs: the open source 
versions of Sybase’s Watcom C/C++ and Fortran compiler products ("Software"), which are modified 
versions of, with significant changes from, the last versions made commercially available by Sybase. As 
used in this License; 

1.1 "Applicable Patent Rights" mean: (a) in the case where Sybase is the grantor of rights, (i) claims of 
patents that are now or hereafter acquired, owned by or assigned to Sybase and (ii) that cover subject matter 
contained in the Original Code, but only to the extent necessary to use, reproduce and/or distribute the 
Original Code without infringement; and (b) in the case where You are the grantor of rights, (i) claims of 
patents that are now or hereafter acquired, owned by or assigned to You and (ii) that cover subject matter in 
Your Modifications, taken alone or in combination with Original Code. 

1.2 "Contributor" means any person or entity that creates or contributes to the creation of Modifications. 

1.3 "Covered Code" means the Original Code, Modifications, the combination of Original Code and any 
Modifications, and/or any respective portions thereof. 

1.4 "Deploy" means to use, sublicense or distribute Covered Code other than for Your internal research and 
development (R&D) and/or Personal Use, and includes without limitation, any and all internal use or 
distribution of Covered Code within Your business or organization except for R&D use and/or Personal 
Use, as well as direct or indirect sublicensing or distribution of Covered Code by You to any third party in 
any form or manner. 

1.5 "Larger Work" means a work which combines Covered Code or portions thereof with code not 
governed by the terms of this License. 

1.6 "Modifications" mean any addition to, deletion from, and/or change to, the substance and/or structure of 
the Original Code, any previous Modifications, the combination of Original Code and any previous 
Modifications, and/or any respective portions thereof. When code is released as a series of files, a 
Modification is: (a) any addition to or deletion from the contents of a file containing Covered Code; and/or 
(b) any new file or other representation of computer program statements that contains any part of Covered 
Code. 

1.7 "Original Code" means (a) the Source Code of a program or other work as originally made available by 
Sybase under this License, including the Source Code of any updates or upgrades to such programs or 
works made available by Sybase under this License, and that has been expressly identified by Sybase as 
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such in the header file(s) of such work; and (b) the object code compiled from such Source Code and 
originally made available by Sybase under this License. 

1.8 "Personal Use" means use of Covered Code by an individual solely for his or her personal, private and 
non-commercial purposes. An individual’s use of Covered Code in his or her capacity as an officer, 
employee, member, independent contractor or agent of a corporation, business or organization (commercial 
or non-commercial) does not qualify as Personal Use. 

1.9 "Source Code" means the human readable form of a program or other work that is suitable for making 
modifications to it, including all modules it contains, plus any associated interface definition files, scripts 
used to control compilation and installation of an executable (object code). 

1.10 "You" or "Your" means an individual or a legal entity exercising rights under this License. For legal 
entities, "You" or "Your" includes any entity which controls, is controlled by, or is under common control 
with. You, where "control" means (a) the power, direct or indirect, to cause the direction or management of 
such entity, whether by contract or otherwise, or (b) ownership of fifty percent (50%) or more of the 
outstanding shares or beneficial ownership of such entity. 

2. Permitted Uses; Conditions & Restrictions.Subject to the terms and conditions of this License, Sybase 
hereby grants You, effective on the date You accept this License and download the Original Code, a 
world-wide, royalty-free, non-exclusive license, to the extent of Sybase’s Applicable Patent Rights and 
copyrights covering the Original Code, to do the following: 

2.1 You may use, reproduce, display, perform, modify and distribute Original Code, with or without 
Modifications, solely for Your internal research and development and/or Personal Use, provided that in 
each instance: 

(a) You must retain and reproduce in all copies of Original Code the copyright and other proprietary notices 
and disclaimers of Sybase as they appear in the Original Code, and keep intact all notices in the Original 
Code that refer to this License; and 

(b) You must retain and reproduce a copy of this License with every copy of Source Code of Covered Code 
and documentation You distribute, and You may not offer or impose any terms on such Source Code that 
alter or restrict this License or the recipients’ rights hereunder, except as permitted under Section 6. 

(c) Whenever reasonably feasible you should include the copy of this License in a click-wrap format, which 
requires affirmative acceptance by clicking on an "I accept" button or similar mechanism. If a click-wrap 
format is not included, you must include a statement that any use (including without limitation 
reproduction, modification or distribution) of the Software, and any other affirmative act that you define, 
constitutes acceptance of the License, and instructing the user not to use the Covered Code in any manner if 
the user does not accept all of the terms and conditions of the License. 

2.2 You may use, reproduce, display, perform, modify and Deploy Covered Code, provided that in each 
instance: 

(a) You must satisfy all the conditions of Section 2.1 with respect to the Source Code of the Covered Code; 

(b) You must duplicate, to the extent it does not already exist, the notice in Exhibit A in each file of the 
Source Code of all Your Modifications, and cause the modified files to carry prominent notices stating that 
You changed the files and the date of any change; 

(c) You must make Source Code of all Your Deployed Modifications publicly available under the terms of 
this License, including the license grants set forth in Section 3 below, for as long as you Deploy the 
Covered Code or twelve (12) months from the date of initial Deployment, whichever is longer. You should 
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preferably distribute the Source Code of Your Deployed Modifications electronically (e.g. download from 
a web site); 

(d) if You Deploy Covered Code in object code, executable form only. You must include a prominent 
notice, in the code itself as well as in related documentation, stating that Source Code of the Covered Code 
is available under the terms of this License with information on how and where to obtain such Source 
Code; and 

(e) the object code form of the Covered Code may be distributed under Your own license agreement, 
provided that such license agreement contains terms no less protective of Sybase and each Contributor than 
the terms of this License, and stating that any provisions which differ from this License are offered by You 
alone and not by any other party. 

2.3 You expressly acknowledge and agree that although Sybase and each Contributor grants the licenses to 
their respective portions of the Covered Code set forth herein, no assurances are provided by Sybase or any 
Contributor that the Covered Code does not infringe the patent or other intellectual property rights of any 
other entity. Sybase and each Contributor disclaim any liability to You for claims brought by any other 
entity based on infringement of intellectual property rights or otherwise. As a condition to exercising the 
rights and licenses granted hereunder. You hereby assume sole responsibility to secure any other 
intellectual property rights needed, if any. For example, if a third party patent license is required to allow 
You to distribute the Covered Code, it is Your responsibility to acquire that license before distributing the 
Covered Code. 

3. Your Grants. In consideration of, and as a condition to, the licenses granted to You under this License, 
You hereby grant to Sybase and all third parties a non-exclusive, royalty-free license, under Your 
Applicable Patent Rights and other intellectual property rights (other than patent) owned or controlled by 
You, to use, reproduce, display, perform, modify, distribute and Deploy Your Modifications of the same 
scope and extent as Sybase’s licenses under Sections 2.1 and 2.2. 

4. Larger Works. You may create a Larger Work by combining Covered Code with other code not 
governed by the terms of this License and distribute the Larger Work as a single product. In each such 
instance. You must make sure the requirements of this License are fulfilled for the Covered Code or any 
portion thereof. 

5. Limitations on Patent License. Except as expressly stated in Section 2, no other patent rights, express or 
implied, are granted by Sybase herein. Modifications and/or Larger Works may require additional patent 
licenses from Sybase which Sybase may grant in its sole discretion. 

6. Additional Terms. You may choose to offer, and to charge a fee for, warranty, support, indemnity or 
liability obligations and/or other rights consistent with this License ("Additional Terms") to one or more 
recipients of Covered Code. However, You may do so only on Your own behalf and as Your sole 
responsibility, and not on behalf of Sybase or any Contributor. You must obtain the recipient’s agreement 
that any such Additional Terms are offered by You alone, and You hereby agree to indemnify, defend and 
hold Sybase and every Contributor harmless for any liability incurred by or claims asserted against Sybase 
or such Contributor by reason of any such Additional Terms. 

7. Versions of the License. Sybase may publish revised and/or new versions of this License from time to 
time. Each version will be given a distinguishing version number. Once Original Code has been published 
under a particular version of this License, You may continue to use it under the terms of that version. You 
may also choose to use such Original Code under the terms of any subsequent version of this License 
published by Sybase. No one other than Sybase has the right to modify the terms applicable to Covered 
Code created under this License. 
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8. NO WARRANTY OR SUPPORT. The Covered Code may contain in whole or in part pre-release, 
untested, or not fully tested works. The Covered Code may contain errors that could cause failures or loss 
of data, and may be incomplete or contain inaccuracies. You expressly acknowledge and agree that use of 
the Covered Code, or any portion thereof, is at Your sole and entire risk. THE COVERED CODE IS 
PROVIDED "AS IS" AND WITHOUT WARRANTY, UPGRADES OR SUPPORT OF ANY KIND AND 
SYBASE AND SYBASE’S LICENSOR!S) (COLLECTIVELY REFERRED TO AS "SYBASE" FOR 
THE PURPOSES OF SECTIONS 8 AND 9) AND ALL CONTRIBUTORS EXPRESSLY DISCLAIM 
ALL WARRANTIES AND/OR CONDITIONS, EXPRESS OR IMPLIED, INCLUDING, BUT NOT 
LIMITED TO, THE IMPLIED WARRANTIES AND/OR CONDITIONS OF MERCHANTABILITY, OF 
SATISFACTORY QUALITY, OF FITNESS FOR A PARTICULAR PURPOSE, OF ACCURACY, OF 
QUIET ENJOYMENT, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. SYBASE AND 
EACH CONTRIBUTOR DOES NOT WARRANT AGAINST INTERFERENCE WITH YOUR 
ENJOYMENT OF THE COVERED CODE, THAT THE FUNCTIONS CONTAINED IN THE 
COVERED CODE WILL MEET YOUR REQUIREMENTS, THAT THE OPERATION OF THE 
COVERED CODE WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT DEFECTS IN THE 
COVERED CODE WILL BE CORRECTED. NO ORAL OR WRITTEN INFORMATION OR ADVICE 
GIVEN BY SYBASE, A SYBASE AUTHORIZED REPRESENTATIVE OR ANY CONTRIBUTOR 
SHALL CREATE A WARRANTY. You acknowledge that the Covered Code is not intended for use in the 
operation of nuclear facilities, aircraft navigation, communication systems, or air traffic control machines in 
which case the failure of the Covered Code could lead to death, personal injury, or severe physical or 
environmental damage. 

9. LIMITATION OF LIABILITY. TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT 
SHALL SYBASE OR ANY CONTRIBUTOR BE LIABLE FOR ANY DIRECT, INCIDENTAL, 
SPECIAL, INDIRECT, CONSEQUENTIAL OR OTHER DAMAGES OF ANY KIND ARISING OUT 
OF OR RELATING TO THIS LICENSE OR YOUR USE OR INABILITY TO USE THE COVERED 
CODE, OR ANY PORTION THEREOF, WHETHER UNDER A THEORY OF CONTRACT, 
WARRANTY, TORT (INCLUDING NEGLIGENCE), PRODUCTS LIABILITY OR OTHERWISE, 
EVEN IF SYBASE OR SUCH CONTRIBUTOR HAS BEEN ADVISED OF THE POSSIBILITY OF 
SUCH DAMAGES, AND NOTWITHSTANDING THE FAILURE OF ESSENTIAL PURPOSE OF ANY 
REMEDY. SOME JURISDICTIONS DO NOT ALLOW THE LIMITATION OF LIABILITY OF 
INCIDENTAL OR CONSEQUENTIAL OR OTHER DAMAGES OF ANY KIND, SO THIS 
LIMITATION MAY NOT APPLY TO YOU. In no event shall Sybase’s or any Contributor’s total liability 
to You for all damages (other than as may be required by applicable law) under this License exceed the 
amount of five hundred dollars ($500.00). 


10. Trademarks. This License does not grant any rights to use the trademarks or trade names "Sybase" or 
any other trademarks or trade names belonging to Sybase (collectively "Sybase Marks") or to any 
trademark or trade name belonging to any ContributorC'Contributor Marks"). No Sybase Marks or 
Contributor Marks may be used to endorse or promote products derived from the Original Code or Covered 
Code other than with the prior written consent of Sybase or the Contributor, as applicable. 

11. Ownership. Subject to the licenses granted under this License, each Contributor retains all rights, title 
and interest in and to any Modifications made by such Contributor. Sybase retains all rights, title and 
interest in and to the Original Code and any Modifications made by or on behalf of Sybase ("Sybase 
Modifications"), and such Sybase Modifications will not be automatically subject to this License. Sybase 
may, at its sole discretion, choose to license such Sybase Modifications under this License, or on different 
terms from those contained in this License or may choose not to license them at all. 


12. Termination. 


12.1 Termination. This License and the rights granted hereunder will terminate: 
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(a) automatically without notice if You fail to comply with any term(s) of this License and fail to cure such 
breach within 30 days of becoming aware of such breach; 

(b) immediately in the event of the circumstances described in Section 13.5(b); or 

(c) automatically without notice if You, at any time during the term of this License, commence an action 
for patent infringement (including as a cross claim or counterclaim) against Sybase or any Contributor. 

12.2 Effect of Termination. Upon termination. You agree to immediately stop any further use, 
reproduction, modification, sublicensing and distribution of the Covered Code and to destroy all copies of 
the Covered Code that are in your possession or control. All sublicenses to the Covered Code that have 
been properly granted prior to termination shall survive any termination of this License. Provisions which, 
by their nature, should remain in effect beyond the termination of this License shall survive, including but 
not limited to Sections 3, 5, 8, 9, 10, 11, 12.2 and 13. No party will be liable to any other for compensation, 
indemnity or damages of any sort solely as a result of terminating this License in accordance with its terms, 
and termination of this License will be without prejudice to any other right or remedy of any party. 

13. Miscellaneous. 

13.1 Government End Users. The Covered Code is a "commercial item" as defined in FAR 2.101. 
Government software and technical data rights in the Covered Code include only those rights customarily 
provided to the public as defined in this License. This customary commercial license in technical data and 
software is provided in accordance with FAR 12.211 (Technical Data) and 12.212 (Computer Software) 
and, for Department of Defense purchases, DFAR 252.227-7015 (Technical Data — Commercial Items) and 
227.7202-3 (Rights in Commercial Computer Software or Computer Software Documentation). 
Accordingly, all U.S. Government End Users acquire Covered Code with only those rights set forth herein. 

13.2 Relationship of Parties. This License will not be construed as creating an agency, partnership, joint 
venture or any other form of legal association between or among you, Sybase or any Contributor, and You 
will not represent to the contrary, whether expressly, by implication, appearance or otherwise. 

13.3 Independent Development. Nothing in this License will impair Sybase’s or any Contributor’s right to 
acquire, license, develop, have others develop for it, market and/or distribute technology or products that 
perform the same or similar functions as, or otherwise compete with. Modifications, Larger Works, 
technology or products that You may develop, produce, market or distribute. 

13.4 Waiver; Construction. Failure by Sybase or any Contributor to enforce any provision of this License 
will not be deemed a waiver of future enforcement of that or any other provision. Any law or regulation 
which provides that the language of a contract shall be construed against the drafter will not apply to this 
License. 

13.5 Severability, (a) If for any reason a court of competent jurisdiction finds any provision of this 
License, or portion thereof, to be unenforceable, that provision of the License will be enforced to the 
maximum extent permissible so as to effect the economic benefits and intent of the parties, and the 
remainder of this License will continue in full force and effect, (b) Notwithstanding the foregoing, if 
applicable law prohibits or restricts You from fully and/or specifically complying with Sections 2 and/or 3 
or prevents the enforceability of either of those Sections, this License will immediately terminate and You 
must immediately discontinue any use of the Covered Code and destroy all copies of it that are in your 
possession or control. 

13.6 Dispute Resolution. Any litigation or other dispute resolution between You and Sybase relating to this 
License shall take place in the Northern District of California, and You and Sybase hereby consent to the 
personal jurisdiction of, and venue in, the state and federal courts within that District with respect to this 
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License. The application of the United Nations Convention on Contracts for the International Sale of 
Goods is expressly excluded. 

13.7 Entire Agreement; Governing Law. This License constitutes the entire agreement between the parties 
with respect to the subject matter hereof. This License shall be governed by the laws of the United States 
and the State of California, except that body of California law concerning conflicts of law. 

Where You are located in the province of Quebec, Canada, the following clause applies; The parties 
hereby confirm that they have requested that this License and all related documents be drafted in English. 
Les parties ont exige que le present contrat et tous les documents connexes soient rediges en anglais. 

EXHIBIT A. 


Portions Copyright (c) 1983-2002 Sybase, Inc. All Rights Reserved. 

This file contains Original Code and/or Modifications of 
Original Code as defined in and that are subject to the 
Sybase Open Watcom Public License version 1.0 (the 
'License'). You may not use this file except in compliance 
with the License. BY USING THIS FILE YOU AGREE TO ALL 
TERMS AND CONDITIONS OF THE LICENSE. A copy of the License 
is provided with the Original Code and Modifications, and 
is also available at www.sybase.com/developer/opensource. 

The Original Code and all software distributed under the 
License are distributed on an 'AS IS' basis, WITHOUT 
WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, AND SYBASE 
AND ALL CONTRIBUTORS HEREBY DISCLAIM ALL SUCH WARRANTIES, 

INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF 
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, QUIET 
ENJOYMENT OR NON-INFRINGEMENT. Please see the License for 
the specific language governing rights and limitations 
under the License. 
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7 Trouble-Shooting 


This section is intended to provide you with help on some of the common (and not so common) problems 
that users have encountered when trying to run the software. 

Symptom: The message "Cannot connect to batch spawn server" is displayed. 

Resolution: This message occurs when the Open Watcom IDE is trying to connect to the batch server. 

The batch server is a program that is employed by the Open Watcom IDE to run "makes" in 
the background. There are several reasons why you may receive this message. 

• Installing Under the Host System and Selecting "Modify System Files" During 
Install 

For the IDE to run properly under a particular host operating system, the install 
program must be run on that system. 

It is very important to check the "Modify System Files" when running the install on 
the host platform. Otherwise, changes required in the host system’s environment will 
not be made. If this is the problem, you should re-install under the host environment 
and select this option. 

• System stability 

If for some reason the operating system has become unstable, the IDE may have 
trouble connecting to the batch server. This can happen if you have run a badly 
behaved application that caused an exception, for example a page fault. If this is the 
problem, you should shutdown the operating system and reboot. 

• Running Windows 3.1 in Enhanced Mode 

The IDE requires at least version 3.1 of Windows to be running, in enhanced mode. 
Windows 3.0 is not supported. 

Running Third-Party Shell Programs 

If you run 4DOS.COM or some other shell besides COMMAND.COM, you must change the 
"BATCHBOX.PIF" file accordingly. You can do this using the standard Windows PIF editor. 

Running Virus Checkers 

If you are running Central Point’s PCTOOLS, VWATCH, or some other virus checker, it may be 
conflicting with our batch server. To isolate the problem, uninstall the virus checker and see if the IDE 
works again. 

386 Enhanced "Exclusive in Foreground" Option 

If you go to the Windows Control Panel, "Scheduling Options" of "386 Enhanced", and the "Exclusive in 
Foreground" checkbox is checked, uncheck it. This causes our batch server to starve under Windows. 


Trouble-Shooting 49 




Chapter 7 


Changes to the SYSTEM.INI File 

The WDEBUG.386 driver is required to be installed in the [386Enh] section of SYSTEM.INI. This should 
have been done automatically by the WATCOM install program when the software was installed under the 
host environment and the "modify system files" option was selected. 

It has been reported that the line 

OverlappedIO=on 

not appear in the SYSTEM.INI file. 

It appears the user’s problem was related to conflicts with other devices installed in the SYSTEM.INI file. 
On its own, the above line does not appear to affect the execution of the IDE. 

It has been reported that the line 

NoEMMDriver=ON 

not appear in the SYSTEM.INI file. It will prevent a link from succeeding in the IDE. 

7 .1 Win-OS/2 and OS/2 Specific 

Installing for a Win-OS/2 Host 

For Win-OS/2, the install must be run under OS/2 and "Modify System Files" must be selected. This 
installs the batch server under OS/2, which we require under Win-OS/2. Then the Windows install 
program should be run under Win-OS/2 so that the program groups will be created. "Modify System Files" 
should also be checked for the Win-OS/2 install. 

Named Pipe Conflicts 

Under OS/2, the batch server is a named pipe. Win-OS/2 uses the OS/2 named pipe for the batch server, 
hence the OS/2 IDE will conflict with the Win-OS/2 IDE if they are both running. If this is the problem, 
you should run only one of the OS/2 and Win-OS/2 IDE, not both at the same time. 
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Preface 

This book was produced with the Open Watcom GML electronic publishing system, a software tool 
developed by WATCOM. In this system, writers use an ASCII text editor to create source files containing 
text annotated with tags. These tags label the structural elements of the document, such as chapters, 
sections, paragraphs, and lists. The Open Watcom GML software, which runs on a variety of operating 
systems, interprets the tags to format the text into a form such as you see here. Writers can produce output 
for a variety of printers, including laser printers, using separately specified layout directives for such things 
as font selection, column width and height, number of columns, etc. The result is type-set quality copy 
containing integrated text and graphics. 

July, 1997. 
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IBM OS/2 is a trademark of International Business Machines Corp. IBM is a registered trademark of 
International Business Machines Corp. 

Microsoft, Windows and Windows 95 are registered trademarks of Microsoft Corp. Windows NT is a 
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1 Open Watcom Integrated Development 
Environment 

1.1 Introduction 


Software development normally involves managing a number of different files for each project. A project 
often includes multiple source files, include files, and libraries. In addition, there are usually several 
programming tools involved: compilers, linkers, preprocessors, debuggers, editors, and so on. But this is 
likely not new to you. What will be new is the Open Watcom Integrated Development Environment (IDE). 

The Open Watcom Integrated Development Environment is a software development tool that manages 
project files and language tools. Although it is really a tool itself, the common term to describe it (and 
possibly the best analogy) is Development Environment. By using the Open Watcom Integrated 
Development Environment, you have direct access to each of the files relating to a project and all of the 
language tools you require to build your application. 

1.2 How the Environment Operates 

The Open Watcom Integrated Development Environment has a graphical interface that combines file 
management and tool management. An IDE session deals with a Project. A project can be generally 
defined as the collection of files and necessary information that relates to the development of project 
components. However, a project is more than just a graphical representation of a file list—it contains all of 
the underlying smarts to understand the interrelation of all files associated with the project and to ensure 
that these files are up-to-date. 

Each project component is referred to as a Target. An Integrated Development Environment target is made 
up of the source files, include files, libraries, and MAKE instructions to create the target file (for example, 
".exe", ".dll", ".lib", or ".hip"). A project often has more than one target. Each target can be set to create 
the associated target file for a specific destination platform. 

Within a target, there are Sources. A source is an individual file (such as a ".c" or ".cpp" file, but it can also 
be a ".bmp", ".rc", or ".lib" file) used to create the target file. A target usually has more than one source. 

1.3 How the Integrated Development Environment Looks 

In the following illustration, the main window is the project window for a project entitled first. wp j . 
The sub-window represents the target for this project, target 1. exe . The source file for the target is 
listed within the target window. In this project, there is only a single target with a single source file. 
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Figure 1 . The Open Watcom IDE window displays project and target windows. 

The language tools are available on the toolbar and the drop-down menus. For example, on the Sources 
menu, you can work with the source that is selected in the target window. Here you can add a new source, 
remove or rename an existing source, edit a source, and so on. A similar set of target actions are available 
in the Targets menu and project actions are located in the File menu. 

A single IDE session displays a project. If the project consists of a number of components, such as two 
executables and one library, these appear as target sub-windows on the project window. Each target 
window displays the files necessary to construct the target and associates files with a rule describing the 
construction mechanism based on filename extension. For example, a filename with the extension ".exe" 
may associate with the rule for constructing executables, or a filename with the extension ".lib" may 
associate with the rule for constructing static libraries. 

Different projects can refer to the same target. If they do, either project can manipulate the shared target 
and any changes to either project affect the shared target. 

1.4 The Files the Integrated Development Environment Uses 

The Open Watcom Integrated Development Environment creates and manages a project, referencing a 
number of targets. The IDE uses filename extensions to represent projects and targets. The extension 
".wpj" represents projects and the extension ".tgt" represents targets. The IDE compiles and links the target 
in the target directory. 

The project file (.wpj) contains the names of all of the target files related to the project, including 
housekeeping information about the project and the current IDE session. 

Each target file (.tgt) describes one target and includes the name and type of the target executable, a 
reference to a rule describing how to build the target, and a list of relevant switches the rule uses. In 
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addition, target files also contain the names of all of the source files used to construct the target program, 
references to similar rules for compiling them, and relevant switches. 

In constructing targets, the Integrated Development Environment references a list of rules defined in a 
configuration file, called ide . cf g. Each rule defines a command line used to do the construction and a 
list of actions you can perform on the target program (such as make, run, or debug) or on the files in the 
item list (such as make or edit). Additionally, rules refer to tools. 

Tools define which command line switches you can use in the Open Watcom Integrated Development 
Environment. 


1.5 Using the Open Watcom Integrated Development 
Environment 

This section discusses the following topics: 

• Starting the Open Watcom Integrated Development Environment 

• Quitting the Open Watcom Integrated Development Environment 

• The IDE Menu Bar 

• The IDE Status Bar 

• The IDE Toolbar 

1.5.1 Starting the Open Watcom Integrated Development Environment 

To start the Integrated Development Environment, double-click on the IDE icon. This opens the Open 
Watcom IDE Project window. 

1.5.2 Quitting the Open Watcom Integrated Development Environment 

To exit the Integrated Development Environment, choose Exit from the File menu of the Open Watcom 
IDE Project window or double-click on the system menu box on the same window. 

1.5.3 The IDE Menu Bar 

The IDE’s menu bar consists of the following eight menus: 

File Open new or existing projects, close and save projects, exit the IDE, and show or hide the 

toolbar and status bar 

Actions Make all targets, run applications, and invoke other GUI Tools 

Targets Work with targets, including setting switches and creating, removing, and renaming targets 

Sources Work with sources, including setting switches and creating, removing, and renaming 

sources 

Options Set switches for creating targets and sources 
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Log Perform functions relating to the IDE Log window 

Window Refresh the contents of the IDE windows and view the targets currently available on the 
IDE window 

Help Access on-line help information 

1.5.4 The IDE Status Bar 

The Status Bar appears along the bottom of the Open Watcom IDE Project window. This bar displays hint 
text for the toolbar button and menu option over which your cursor is positioned. Status messages, such as 
Saving, Adding, and Executing Log, appear in this bar so you are aware of what action the IDE is 
performing. A check mark beside the Show Status Bar menu option in the File menu indicates that this 
feature is enabled. To disable this feature, choose the option again from the File menu and the status bar 
disappears from the window. 



Figure 2. The IDE Status Bar can be toggled from the File menu. 


1.5.5 The IDE Toolbar 

In the Open Watcom IDE Project window, the toolbar appears below the menu bar when the Show Tool 
Bar option in the File menu is activated (default). A check mark beside the menu option indicates that it is 
enabled. To disable this feature, choose the option again from the File menu and the toolbar disappears. 
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Figure 3. You can access thirteen IDE functions from the toolbar. 

The following explains the function each icon performs, as well as the equivalent function on the menu bar. 
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Create 

Open 

Save 

Edit 

Make Source 
Make Target 
Run 
Debug 

Remote Debug 


Create a new project. This is equivalent to the option New Project in the File menu. 

Open an existing project. This is equivalent to the option Open Project in the File menu. 

Save the current project. This is equivalent to the option Save Project in the File menu. 

Edit the selected source file. This is equivalent to the option Edit Text in the Sources 
menu. 

Make the selected source file. This is equivalent to the option Make in the Sources menu. 
Make the current target. This is equivalent to the option Make in the Targets menu. 

Run the current target. This is equivalent to the option Run in the Targets menu. 

Debug the current target. This is equivalent to the option Debug in the Targets menu. 


Debug the current target on a remote machine. This is equivalent to the option Remote 
Debug in the Targets menu. 

Browse Browse the current target. This is equivalent to the option Browse in the Targets menu. 

Currently, browsing is supported by the Open Watcom C/C++ compilers only (Open 
Watcom FORTRAN 77 does not support browsing). 

Sample Run and sample the current target. This is equivalent to the option Sample in the Targets 

menu. 


Profile Profile the current target. This is equivalent to the option Profile in the Targets menu. 

Make All Make all targets in the project. This is equivalent to the option Make All in the Actions 

menu. 


1.6 Getting Started with a Short Tutorial 

Perhaps the easiest way to understand how the Open Watcom Integrated Development Environment 
manages an entire project’s files and tools, is to work through a brief example. In this walk-through, you 
create and execute a simple C program using the IDE. FORTRAN developers can follow along substituting 
FORTRAN code and file names where appropriate. The session will help you understand the basic 
concepts of the IDE and the steps involved in project development. 

The illustrations shown in this section are taken from the Windows environment. The OS/2 environment is 
very similar with some minor differences. For example, in the OS/2 environment the IDE uses the OS/2 
Editor rather than Open Watcom’s Windows Editor. Although this tutorial builds a Win32 executable, you 
can choose to build a Winl6 or OS/2 PM executable. The procedures to follow are not that much different. 
When the time comes to select the type of target, simply choose an environment that you can run on your 
machine so that you can run your application to make sure it works. 
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1.6.1 A Simple Executable 

(1) Double-click on the IDE icon in the Open Watcom Tools window. 

The Open Watcom IDE Project window appears. 

(2) Choose New Project from the File menu. 

The Enter Project Filename dialog appears. The default project name is noname . wp j . 

(3) Enter the filename \pro ject\f irst in the File Name field and click on OK. 



Figure 4. Enter the filename in the Enter Project Filename dialog. 

This is the name of the project you are creating. If you enter a directory that doesn’t exist (in this 
case, \pro ject), the IDE reveals a message box asking if you want to create the specified directory. 
Click on OK to create the specified directory and project file. 

Note: The IDE looks for existing projects with the new name. If a project with the specified 

name already exists, the IDE will prompt you rather than simply overwriting the 
existing project. 

The project name appears in the title bar of the Open Watcom IDE Project window. Note that the IDE 
added the extension ".wpj" to the project name. The New Target dialog appears on the screen where 
you define a target for the new project. 

(4) Enter the desired target name in the Target Name field (we suggest target 1). Next, select the 
appropriate Target Environment (we suggest "Win32") and Image Type (we suggest "Character-mode 
Executable"). Click on OK when completed. 
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Figure 5. Select target name, target environment and image type 

The New Target dialog closes and the IDE creates a target window entitled target 1. exe for the 
new target. Note that the IDE appends the appropriate extension to the target name for you once you 
click on OK. You can now add sources to the target. 

(5) Choose New Source from the Sources menu. 

The Add File(s) dialog appears where you specify the sources you want to add to the target. Source 
names must be filenames with extensions; pathnames are not required. 

For the OS/2 IDE, you can add multiple source files to the target at one time by inserting a space 
between each filename you enter. You can also use the file browser to add files by clicking on the 
Browse... button. 

For all other systems, you can enter the names of the source files (with extensions) in the File Name 
field or you can use the file browser to select files. The type of files displayed in file list window can 
be controlled by modifying the List Files of Type field. Once you have typed a name in the File 
Name field or selected a name from the file list, you can add it to the list of source files to be included 
by clicking the Add button. All files in the file list can be added by clicking the Add All button. 
Individual names can be removed from the "add" list by selecting them and clicking the Remove 
button. 
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Figure 6. Select source file names in the Add File(s) dialog 

(6) Enter the following source file names. 

sourcel.c (or sourcel.for) 
source2.c (or source2.for) 
source3.rc 


For the OS/2 IDE, enter all the names into the field separating each name by a space. Click on OK 
when done. 

For all other systems, enter one name at a time into the File Name field, pressing Enter or clicking on 
Add after each one has been entered. Click on Close when done. 
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Figure 7. Enter one or several source files in the Add File(s) dialog. 

The IDE adds the new source files to the target window, followed by the characters [n/a]. This 
indicates that the source files are not available, meaning that the files do not yet exist. The indicators 
are: 

[n/a] This code appears if the file does not exist. 

[r/o] This code appears if the file is Read Only. 

[sw] This code appears if the user has set switches for the specified source file. 

The Integrated Development Environment organizes the source files in the target window under 
headers according to the filename extension. You can expand and collapse the file groups by clicking 
on the folder icon. 

For this tutorial, we only need one source file, so now we will delete the extra files from the target. 

(7) Click on the file source2 . c (or source2 . for) to select it then choose Remove Source from the 
Sources menu. 

A message box appears asking if you want to remove the selected source. Click on the Yes button to 
continue. The IDE removes the selected source file from the target window. Now we can remove 
source3 . rc . To do this we will perform the function of removing all source files with a common 
extension. 
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(8) Click on the (.re) header on the target window then choose Remove Source from the Sources menu. 

A message box appears on the screen asking if you want to remove all of the ".re" files. Click on the 
Yes button to continue. The message box closes and the IDE removes the source3 . rc file from 
the target window. Now you can edit the remaining source file. 

(9) Highlight the line sourcel. c (or sourcel. for) and choose Edit Text from the Sources menu to 
edit the selected source file. 

The Open Watcom Editor appears. The name of the selected source file, sourcel. c (or 
sourcel. for), appears in the window. Here you can enter the source code. 


Hint: You can also invoke the Open Watcom Editor by double-clicking on the source file that you 
want to edit. 


In this case, the Open Watcom Editor appears because the selected source file has a ".c" or ".for" 
extension. Performing an edit can open different editors, depending on the extension of the selected 
source file. 

(10) Enter the following lines of source code. 

Important: For the purpose of this session, we ask you to enter ii instead of i in the "print" line. 

This will allow you to see how the Integrated Development Environment reacts to 
errors. You will then be able to correct the error. 

♦include <stdio.h> 

void main() 

{ 

int i; 

for (i=0; i<10; i++) 

{ 

printf ( "Value is %d\n", ii ); 

} 

printf("Press Enter ...\n"); 
getchar(); 

} 

FORTRAN programmers can enter the following lines of code. 

program main 
implicit none 
integer i 

do i = 0, 9 

print *, 'Value is ', ii 
enddo 

print *, 'Press Enter...' 
read * 

end 
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You can now save your work and close the Editor in one of the following two ways: close down the 
entire editor or close down only the source file window. For this exercise, close only the source file 
window as follows. 

(11) Choose Close from the File menu to close down the current source file window. 

In both cases, if changes have been made to the file and not saved, a message prompts you to save the 
changes before exiting. The advantage of closing only the Editor window is that the Editor continues 
to run. If you need to access it again, you will not need to wait for it to go through the start-up 
procedures again. 

Important: You must save the file. The Open Watcom compilers do not access the source lines in 

the Editor’s buffers. 

(12) Minimize the Editor window. 

or 

Click on the Open Watcom IDE Project window to bring it to the foreground. 

(13) Choose Refresh from the Window menu. 

This action forces the IDE to update the display with the state of all files. It is not necessary to use 
this function if you have selected Auto Refresh in the File menu. If Auto Refresh is disabled then it 
may be necessary to alert the IDE of the presence of the file on disk. 

(14) Choose Save Project from the File menu to save your project up to this point. 

You are now ready to make and run the target. Making a target is the act of constructing a target file. 
In this case, it involves compiling the source file sourcel. c (or sourcel. for) using the 
appropriate Open Watcom compiler and linking the target executable using the Open Watcom Linker. 

(15) Highlight the line sourcel. c and choose C Compiler Switches... from the Source Options item 
located under the Sources menu to set compile options. 

FORTRAN programmers: Highlight the line sourcel. for and choose Fortran Compiler 
Switches... from the Source Options item located under the Sources menu to set compile options. 

The C Compiler Switches dialog appears. If you are using FORTRAN, the Fortran Compiler 
Switches dialog appears. 

(16) Click on the "»" button until the 7. CodeGen Strategy Switches dialog appears. Click 
on the "Multithreaded application [-bm]" checkbox button to select this option. 

FORTRAN programmers: Click on the "»" button until the 9. Application Type 
Switches dialog appears. Click on the "Multithreaded application [-bm]" checkbox to select this 
option. 

A check-mark appears in the checkbox. 

Note: Selecting this option is for demonstration purposes only, it is not required for this simple 
application. 

Click OK to close the dialog. 
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(17) Choose Make from the Targets menu. 


The IDE constructs a makefile based on its knowledge of the target and construction rules and then 
invokes the Open Watcom Make utility to create target 1. exe . The IDE Log window appears at 
the bottom of the Open Watcom IDE Project window. Use this window to monitor the procedure. 
Since you entered ii instead of i, the MAKE fails. 



Figure 8. Use the IDE Log window to monitor the make procedure. 


(18) Highlight the error message in the IDE Log window and choose Help on Message from the Log 
menu. 


Help information regarding the error message appears on the screen. 


Open Watcom C Diagnostic Messages Help 


File Edit Bookmark Options Help 
Help Topics[ 


Options 

<< 

>> 

Index 




Bact 


Print 


Up 


El011 Symbol '%$' has not been declared 


The compiler has found a symbol which has not been previously declared. The symbol may be 
spelled differently than the declaration, oryou may need to #include a headerfile that 
contains the declaration. 

Figure 9. Help for error messages is available 

Close the Help window and edit the source file as follows. 

(19) Highlight the error message in the IDE Log window and choose Edit File from the Log menu, 
or 

Double-click on the error message in the IDE Log window. 


14 


Getting Started with a Short Tutorial 




















































Open Watcom Integrated Development Environment 


The Open Watcom Editor opens and the cursor appears at the position of the error. Edit and correct 
the error and then save the file again. Minimize the Editor window and bring the IDE window to the 
foreground. 


(20) Choose Make from the Targets menu again. 

This time, the procedure creates the executable file targetl. exe . 

(21) Choose Run from the Targets menu. 


The IDE executes the program targetl. exe . 



Figure 10. Run from the Targets menu runs the target. 


The program you wrote is a character mode application and its output appears in a separate console 
window. You are now ready to debug your target program. You probably do not need to debug this 
simple program with the Open Watcom Debugger but go through the steps so that you know what to 
do for more complex programs. 


The IDE has several debugging information options which it uses as defaults when it is started. The 
first thing to do is check to make sure that your application compiled with the default debugging 
information activated. 


(22) Choose Target Options from the Targets menu to activate the Target Options menu. 

The option Use Development Switches should appear in grey text with a check mark next to it. 
Development Switches automatically include debugging information in the target. If you were to 
select Use Release Switches, the IDE would select options useful for a production version of your 
program. Selecting this option turns the text grey and places a check mark beside it. The IDE uses 
the development switches by default. 
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Note: For the purpose of this session, you should make the target with the development 

switches on. If this is not the option selected, select it and remake the target before 
debugging. 

(23) Choose Debug from the Targets menu. 

The IDE starts the Open Watcom Debugger. 

(24) Choose Step Over from the Run menu of the Open Watcom Debugger to step through the code. 
Choose Go from the Run menu of the Open Watcom Debugger to continue execution to the end of the 
code. For more information on using the Open Watcom Debugger, refer to the Open Watcom 
Debugger User’s Guide. The task has completed running appears when the program has completed 
execution. 

(25) Choose Exit from the File menu to terminate the debugging session. 

The Open Watcom Debugger closes and you return to the Open Watcom IDE Project window. You 
can now exit the IDE. 

(26) Choose Exit from the File menu to exit the IDE. 

The IDE prompts you to save the current project if you have not saved it since the last change. 

1.6.2 Review of What Happened 

In this session, you created a project called f irst. wp j . This project had one target called 
targetl. exe, a 32-bit Windows executable (unless you specified another target type). Using the Open 
Watcom Editor, you entered and edited the source text in a file called sourcel. c or sourcel. for (if 
you tried the FORTRAN example). You compiled and linked it into an executable program using the Open 
Watcom Make utility, a Open Watcom compiler, and the Open Watcom Linker. You ran it directly and 
under the control of the Open Watcom Debugger. 

When you saved the project, the Open Watcom Integrated Development Environment created the following 
permanent files: 

first.wpj Describes the screen layout and refers to a file called targetl. tgt 

targetl.tgt Describes the target executable targetl. exe and all switches required to link it. It also 

describes sourcel. c (or sourcel. for) and the switches required to compile it. 

1.7 The Open Watcom IDE Project Window 

When you first start the Open Watcom Integrated Development Environment, an empty Open Watcom IDE 
Project window opens. This window represents the project that is currently open in the IDE. The name of 
the current project appears in the title bar of this window. 

The first thing you need to do is open a project for the Open Watcom IDE Project window. This can be a 
new project you create or an existing project you open. 
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Important: You can have only one project open at a time in the IDE. If you attempt to open or create a 

project while one already exists in the IDE window, a message box appears informing you 
that the IDE is closing the current project and asks if you want to save any changes made to 
that project. Choose Yes, No, or Cancel in this box to continue. 

1.7.1 Opening a Project 

To create a new project: 

(1) Choose New Project from the File menu. 

The Enter Project Filename dialog appears on the screen where you enter the name of the project you 
are creating. 

(2) Enter the desired name in the File Name field and choose the desired directory. 

All projects must have the extension ".wpj". 



Figure 11. Use the Enter Project Filename dialog to create a new project. 

(3) Click on OK when completed. 

The Enter Project Filename dialog closes and the new project name appears in the title bar of the Open 
Watcom IDE Project window. A New Target dialog opens on the screen where you add a target to the 
new project. Refer to the section Adding a Target for more information. 

To open an existing project: 

(1) Choose Open Project from the File menu. 

The Open dialog appears on the screen where you select the project you want to open. 
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Figure 12. Use the Open dialog to open an existing project. 

(2) Choose the desired project. 

All projects have the extension ".wpj". 

(3) Click on OK when the desired project appears in the File Name field. 

The Open dialog closes and the name of the selected project appears in the title bar of the Open 
Watcom IDE Project window. If targets exist for the selected project, windows representing the 
targets appear in the main window. 

1.7.2 Closing a Project 

To close the current project: 

(1) Choose Close Project from the File menu. 

The IDE removes all target windows for the current project from the Open Watcom IDE Project 
window. The project name disappears from the title bar and the window is empty. 

1.7.3 Saving a Project 

There are two ways of saving your current project. You can perform a simple save where the project is 
updated with any changes made since the last save or you can save the project under a different project 
name using the Save Project As function. 

1.7.3.1 Updating the Project 
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To perform a simple save on your project: 

(1) Choose Save Project from the File menu. 

The IDE updates the project specified in the title bar. The status bar along the bottom of the window 
indicates that the save function is being executed. 

1.7.3.2 Saving the Project Under a New Name 

To save the current project using a different name: 

(1) Choose Save Project As from the File menu. 

The Save As dialog appears on the screen where you specify the file name by which you want to save 
the current project. 

(2) Enter the desired project name in the File Name field. 

This is the new name by which you want to save the current project. This can be the name of a new 
project or an existing project. 

Important: Entering the name of an existing project overwrites the contents of that project with 

the contents of the current project. 

(3) Choose the desired directory for the project using the Directories list on the Save As dialog. 

(4) Click on OK when completed. 

The Save As dialog closes and the new project name appears in the title bar of the Open Watcom IDE 
Project window. 

1.8 Working with Targets 

Once you have created a project, it is a simple matter to add additional targets. You can also change the 
name of a target, remove targets, change the target environment, and change the image type. This section 
discusses the following topics: 

• Adding a Target 

• Minimizing a Target 

• Removing a Target 

• Renaming a Target 

• Marking a Target for Remake 

• Making Targets 

• Running a Target 

1.8.1 Adding a Target 

You add targets to the current project using the New Target dialog. When you create a new project, this 
dialog appears automatically. You have two options when adding targets to a project: you can either enter 
the name of a new target or you can choose an existing target, previously created in another project. This 
section describes both methods for adding a target. 
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To add a new target to the current project: 

(1) Choose New Target from the Targets menu. 

The New Target dialog appears on the screen where you enter the details of the target you are adding. 



Figure 13. Enter the new target details in the New Target dialog. 

(2) Enter the target name in the Target Name field. 

Enter the entire pathname to ensure the directory is created where you want. Depending on the nature 
of the target, it may or may not be able to share the same directory as other pre-existing targets. 
Generally, if the target shares one or more of the same source files as other targets in the project, then 
it must be placed in its own subdirectory. The object files that are produced for the target may have 
different attributes than a pre-existing target’s object files (e.g., 16-bit vs 32-bit). This is why the 
target should be placed in a separate subdirectory. 

(3) Select the desired Target Environment and Image Type as desired. 

(4) Click on OK when the Target Name, Target Environment and Image Type fields are correct. 

If you specify a new directory in the target pathname, a message box appears asking if you want to 
create the specified directory. Choose Yes or No to continue. A window representing the new target 
appears on the Open Watcom IDE Project window. The target name appears in the title bar. 

The first line in this window describes the target. It specifies the current mode, the target type. The 
current mode is represented by either the letter D or R which appears in parentheses in front of the 
target type. The letter D indicates that the target is placed in Development mode. The letter R 
indicates that the target is placed in Release mode. The rest of the window displays the source files 
for the target. 
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Figure 14. A project may have multiple targets. 


To add an existing target to a current project: 

(1) Choose New Target from the Targets menu. 


The New Target dialog appears on the screen. 

(2) Click on the Browse button. 


The Enter Target Filename dialog appears on the screen. This dialog allows you to browse the 
directories and files and select the ".tgt" file for the target you want to add. 


Working with Targets 21 














































Open Watcom Integrated Development Environment 



Figure 15. Choose an existing target from the Pick Target Filename dialog for the current project. 

(3) Click on the desired target to select it. 

The selected target appears in the File Name field. 

(4) Click on OK to process the target selection. 

The Enter Target Filename dialog closes. 

(5) Click on OK to close the New Target dialog. 

A window representing the new target appears on the Open Watcom IDE Project window. The target 
name appears in the title bar. 

The first line in this window describes the target. It specifies the current mode and the target type. 
The current mode is represented by either the letter D or R which appears in parentheses in front of 
the target type. The letter D indicates that the target is placed in development mode. The letter R 
indicates that the target is placed in Release mode. The rest of the window displays the source files 
for the target. 

1.8.2 Minimizing a Target 

If you are working with a project that has multiple targets, the Open Watcom IDE Project window can 
become cluttered. You can tidy your window by minimizing the target windows that you are not currently 
using. 

To minimize a target window: 

(1) Click on the system box in the upper left-hand corner of the target window you want to close. 

A menu appears listing the functions you can perform on the selected window. 

(2) Choose Minimize from the menu. 
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The selected target window closes and an icon appears along the bottom of the screen representing 
that window. The name of the target appears on or under the icon. 

(3) Double-click on the icon to open the target window again. 



Figure 16. Minimize targets to reduce clutter in the project window. 


1.8.3 Removing a Target 

The procedure for removing a target from a project is simple. If your project has multiple targets, it is 
important to ensure that the target you want to remove is the one selected. Removing a target does not 
permanently delete the target, it simply removes it from the current project. If the target is attached to 
multiple projects, those projects will not be affected by the removal of the selected target from the current 
project. 

To remove a target from the current project: 

(1) Click once on the target window you want to remove from the project. 

The title bar of the selected target window is highlighted. 

(2) Choose Remove Target from the Targets menu. 

A message box appears on the screen asking if you really want to remove the selected target. 

(3) Choose OK to continue. 

The message box closes and the selected target window disappears from the Open Watcom IDE 
Project window. 
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1.8.4 Renaming a Target 

When renaming a target, you can either give it a new name or you can give it the name of an existing target. 
Choosing an existing target name overwrites the contents of the existing target with the contents of the 
current target. 

To rename a target: 

(1) Click once on the target window you want to rename. 

The title bar of the selected target window is highlighted. 

(2) Choose Rename Target from the Targets menu. 

The Rename Target dialog appears. The Target Name, Target Environment, and Image Type of the 
selected target appear in the appropriate fields. 



Figure 17. Change a target’s name using the Rename Target dialog. 

(3) Enter the new target name in the Target Name field, 
or 

Click on the Browse button and select an existing target name; click on OK when completed. 

The selected or entered target name appears in the Target Name field. 

(4) Verify that the Target Environment and Image Type are correct. 

(5) Click on OK on the Rename Target window. 

The Rename Target dialog closes. The title bar of the selected target window now displays the new 
target name. 
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1.8.5 Marking a Target for Remake 

Marking a target for remake ensures that the IDE will perform the link the next time you make that target or 
make all targets. This function is necessary if you are not using the Autodepend function in the Setup 
Target submenu under the Targets menu. By marking a target for remake, you control when and which 
targets need to be remade. 

To mark a target for remake: 

(1) Click once on the target window you want to mark. 

The title bar of the selected target window is highlighted. 

(2) Choose Mark Target for Remake from the Targets menu. 

A message box appears asking if you want to also mark all of the source files of the selected target. 

(3) Choose Yes or No to continue. 

Choosing Yes marks all of the source files for the selected target as well as the target itself. This 
means that the next time you do a make, the source files for the selected target will be compiled. 
Choosing No marks only the selected target for remake. In both cases, the message box closes and 
you return to the Open Watcom IDE Project window. 

1.8.6 Making Targets 

The Make function in the Targets menu creates an executable for the selected target. When you perform 
this function, the IDE compiles the source files for the selected target into object files. The object files are 
then linked together to create the target file. 

There are two make functions available to you for targets: Make and Make All. The Make All function in 
the Actions menu tells the IDE to compile and link all of the targets for the current project. This can be a 
lengthy process, depending upon the number of targets in your project, so you may choose to only make 
targets to which changes have been made. This enables you to see if they can be made successfully. 

Performing the Make function opens the IDE Log window which allows you to monitor the progress of the 
make. 

To make a single target: 

(1) Click once on the target window you want to make to select it. 

The title bar of the selected target window is highlighted. 

(2) Choose Make from the Targets menu. 

The IDE Log window opens along the bottom of the Open Watcom IDE Project window. In the log 
window you can monitor the make procedure. Execution Complete appears in the IDE Log window 
when the make is completed on the selected target. If the make is successful an executable file for the 
selected target can be found in the directory associated with the target window. 
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Figure 18. Use the IDE Log window to monitor the make procedure. 

To make all targets for the current project: 

(1) Choose Make All from the Actions Menu. 

The IDE Log window opens along the bottom of the Open Watcom IDE Project window. In the log 
window you can monitor the make procedure. Execution Complete appears in the IDE Log window 
when the make is completed on the targets. If the make is successful an executable file for each target 
in the project can be found in the directory associated with the target window. 

1.8.6.1 Viewing the Make Command for a Target 

With the IDE you can use the Show Make Command function to display the makefile commands for the 
selected target. These are the commands that will be used to compile the selected target when you choose 
the function Make from the Targets menu or Make All from the Actions menu. 

To view the make commands for targets: 

(1) Click once on the target window whose makefile commands you want to view. 

The title bar of the selected target window is highlighted. 

(2) Choose Target Options from the Targets menu. 

A submenu appears on the screen from the Target Options menu. 

(3) Choose Show Make Command from the Target Options submenu. 

The Target Command dialog appears on the screen. This dialog displays the makefile commands for 
the selected target. 
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Target Command 



@%write targetl.lkl 
@%append targetl .Ikl 
lifneq BLANK "" 

*wlib -q -n -b targetl.imp 

@%append targetl.lkl LIBR targetl.imp 

lendif 

lifneq BLANK "" 

@%append targetl.lkl op resource= 
lendif 

x wlink name targetl d all SYS nt op m op maxe=25 op q op symf ©targetl Ikl 


I OK j 

Figure 19. The Target Command dialog displays the makefile commands for the selected target. 

(4) Click on OK to close the dialog. 

1.8.7 Running a Target 

Once you have compiled and linked your target using the Make function, you can run the target to execute 
the program. 

To run a target: 


(1) Click once on the target window you want to run. 

The title bar of the selected target window is highlighted. 

(2) Choose Run from the Targets menu. 


The IDE executes the target program. 



Figure 20. Run from the Targets menu runs the target. 
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1.8.7.1 Other Run Functions 

In the Open Watcom Integrated Development Environment you can run programs other than the targets in 
your current project window. Use the run functions in the Actions menu to specify the program you want 
to run. The Run item runs the specified program under your host environment. The Run Batch item runs 
the specified program in the IDE Log window. 

To run other programs in the IDE: 

(1) Choose Run from the Actions menu. 

or 

Choose Run Batch from the Actions menu. 

A Run or Run Batch dialog appears on the screen. These dialogs are identical. 



Figure 21. Use the Run (or Run Batch) dialog to run other programs in the IDE. 

(2) Enter the name of the program you want to run in the Command field. 

(3) Click on OK to run the specified program. 

The dialog closes and the specified program runs, either under the host environment or in the IDE Log 
window. 

1.8.8 Setting Application Parameters 

The Targets and Sources menus and their submenus are divided into sections. Horizontal lines separate 
each section. The menu items in the bottom sections of the Targets and Sources menus are actions that you 
can perform on the selected target or source file in the current project. If there are switches that can be set 
for these actions, there are corresponding menu item entries in the bottom sections of the submenus. 

Choose Target Options and Source Options from their respective menus to display the submenus. 

1.9 Working with Source Files 

Once your project has a target you need to add source files to the target. The procedure for adding a source 
file to a target is simple. Once you have source files that make up your target, you can also change the 
name of a source file and remove source files. This section discusses the following topics: 
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• Adding Source Files 

• Removing Source Files 

• Renaming a Source File 

• Marking a Source File for Remake 

• Making Source Files 

• Viewing Included Files 


1.9.1 Adding Source Files 

You add source files to the selected target (the target whose title bar is currently highlighted ) using the Add 
File(s) dialog. The current project must have a target in order to use the New Source function. You have 
two options when adding source files to a target: you can either enter the name of a new source file or you 
can choose an existing source file. When adding existing source files you can use the file browser, type 
sources one at a time into the Add File(s) dialog, or use wild cards in the Add File(s) dialog. This section 
describes all methods for adding source files. 

The extension you use with the source file name determines the compiler that the IDE uses to create the 
target. For example, the ".c" extension, invokes the Open Watcom C compiler to make the target. You can 
specify several different compilers: 


xxx.asm 
xxx.c 
xxx.cpp 
xxx.for 
xxx.hip 
xxx.rc 
xxx.res 
xxx.sqc 

xxx.sqp 


The ".asm" extension invokes the Open Watcom Assembler. 

The ".c" extension invokes the Open Watcom C compiler. 

The ".cpp" extension invokes the Open Watcom C++ compiler. 

The ".for" extension invokes the Open Watcom FORTRAN 77 compiler. 

The ".hip" extension invokes either the Winl6, OS/2, or Win32 compiler. 

The ".rc" extension invokes the Open Watcom resource compiler. 

The ".res" extension invokes the Open Watcom Resource Editor. 

The ".sqc" extension invokes the embedded SQL preprocessor and the Open Watcom C 
compiler. 

The ".sqp" extension invokes the embedded SQL preprocessor and the Open Watcom C++ 
compiler. 


To add new source files to the selected target: 

(1) Choose New Source from the Sources menu. 

The Add File(s) dialog appears where you specify the name(s) of the source file(s) you are adding. 
Source names must be filenames with extensions; pathnames are not required. 

For the OS/2 IDE, you can add multiple source files to the target at one time by inserting a space 
between each filename you enter into the filenames field. 

For all other systems, you can enter the names of the source files (with extensions) in the File Name 
field, one at a time. Once you have typed a name in the File Name field, you can add it to the list of 
source files to be included by clicking the Add button. Individual names can be removed from the 
"add" list by selecting them and clicking the Remove button. 
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Figure 22. Add one or several source files to a target using the Add File(s) dialog. 

(2) Enter the source file name(s). 

For the OS/2 IDE, enter all the names into the field separating each name by a space. Click on OK 
when done. 

For all other systems, enter one name at a time into the File Name field, pressing Enter or clicking on 
Add after each one has been entered. Click on Close when done. 

The Add File(s) dialog closes and the selected source file(s) appear in the selected target window on 
the Open Watcom IDE Project window. 

The source files are grouped by their file extensions and appear in alphabetical order. You can 
expand and collapse the list of source files by clicking on the folder icon to the left of the header. 

To add existing source files to the selected target using the file browser: 

(1) Choose New Source from the Sources menu. 

The Add File(s) dialog appears on the screen. 

For the OS/2 IDE, click on the Browse button and the Pick Filename dialog appears on the screen. 
This dialog allows you to browse the directories and files and select the source file(s) you want to add 
to the current target. Click on the desired source file to select it. The selected source file(s) appear 
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highlighted in the Pick Filename dialog. When done browsing files, click on OPEN to add the 
selected files. The Pick Filename dialog closes. When done selecting files, click on OK. 

For all other systems, you can use the file browser to select files. The type of files displayed in file 
list window can be controlled by modifying the Fist Files of Type field. Once you have selected a 
name from the file list, you can add it to the list of source files to be included by clicking the Add 
button. All files in the file list can be added by clicking the Add All button. Individual names can be 
removed from the "add" list by selecting them and clicking the Remove button. When done, click on 
Close to add the selected files. 

The Add File(s) dialog closes and the selected source file(s) appear in the selected target window on 
the Open Watcom IDE Project window. 

The source files are grouped by their file extensions and appear in alphabetical order. You can 
expand and collapse the list of source files by clicking on the folder icon to the left of the header. 

To add existing source files to the selected target using wild cards: 

(1) Choose New Source from the Sources menu. 

The Add File(s) dialog appears on the screen. 

For the OS/2 IDE, enter the source file name pattern in the filename(s) field using wild cards. For 
example, enter sou* . c to add all source files whose name begins "sou" and have a ".c" extension to 
the current target. When done, click on OK to add the selected files. 


Hint: Even when entering wild cards, you can add multiple source file groups by separating each 
entry with one space (e.g., sou*.c sou*.cpp). 


For all other systems, enter the source file name pattern in the File Name field using wild cards. For 
example, enter sou* . c to select all source files whose name begins "sou" and have a ".c" extension. 
Click on the Add All button to add all the names that match the wild card pattern. Individual names 
can be removed from the "add" list by selecting them and clicking the Remove button. When done, 
click on Close to add the selected files. 

The Add File(s) dialog closes and the selected source file(s) appear in the selected target window on 
the Open Watcom IDE Project window. 

The source files are grouped by their file extensions and appear in alphabetical order. You can 
expand and collapse the list of source files by clicking on the folder icon to the left of the header. 

1.9.2 Removing a Source File 

The procedure for removing a source file from a project is simple. You can remove one source at a time or 
you can remove all source files with a common file extension from the target. Removing a source file does 
not permanently delete the it. The IDE simply removes it from the current target. If the removed source 
file is common to multiple targets, the other targets will not be affected by the removal of the selected 
source file. 
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To remove one source file from a target: 

(1) Click once on the source file you want to remove from the target. 

The selected source file appears highlighted in the target window. 

(2) Choose Remove Source from the Sources menu. 

A message box appears asking if you are sure you want to remove the selected source file. 

(3) Click on the Yes button. 

The message box closes and the IDE removes the selected source file from the target window. 

To remove a group of source files from a target: 

(1) Click once on the header to the right of the folder icon of the source files group you want to remove 
from the target. 

The selected header appears highlighted in the target window. 



Figure 23. Click on the header to remove all source files with a common file extension. 

(2) Choose Remove Source from the Sources menu. 

A message window appears asking if you want to remove all source files with the selected file 
extension. 

(3) Choose OK to continue. 

The message box closes and the IDE removes the selected group of source files from the target. 
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1.9.3 Renaming a Source File 

When renaming a source file, you can either give it a new name or you can give it the name of an existing 
source file. Choosing an existing source file name overwrites the contents of that source file with the 
contents of the current source file. 

To rename a source file: 

(1) Click once on the source file you want to rename. 

The selected source file appears highlighted in the target window. 

(2) Choose Rename Source from the Sources menu. 

The Rename File dialog appears where you enter the new name of the selected source file. 



Figure 24. Use the Rename File dialog to rename the selected source file. 


(3) Enter the new source file name in the field, 
or 

Click on the Browse button and select an existing source file name; click on OK when completed. 
The selected or entered source file name appears in the Rename File dialog. 

(4) Click on OK on the Rename File dialog. 

The Rename File dialog closes. The target window displays the updated source file. 
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1.9.4 Marking a Source File for Remake 

The Mark Source for Remake function in the Sources menu enables you to mark a source file to ensure that 
the IDE will recompile it the next time you make the target. This function is useful because although 
changes may not have been made to the selected source file, changes may have been made to a source file 
on which the selected source file depends. This function is necessary if you are not using the Autodepend 
function in the Target Options submenu under the Targets menu. Marking source files for remake gives 
you control over when and which source files need to be remade. 

With the Mark function you can mark an individual source file or a group of source files with a common 
file extension. 

To mark a source file or a group of source files for remake: 

(1) Click once on the source file you want to mark, 
or 

Click once on the header of the group of source files you want to mark. 

The selection is highlighted in the target window. 

(2) Choose Mark Source for Remake from the Sources menu. 

If you selected a group of source files to mark, a message box appears asking if you want to also mark 
all of the source files of the specified extension. 

(3) Choose Yes to continue. 

The message box disappears and the IDE marks all of the source files in the selected group to be 
recompiled. 

1.9.5 Making Source Files 

The Make function in the Sources menu enables you to compile a selected source file into an object file. 
You can also perform the Make function on a group of source files with a common file extension. 

Performing the Make function opens the IDE Log window which allows you to monitor the progress of the 
make. 

To make source files: 

(1) Click once on the source file you want to make, 
or 

Click once on the header of the group of source files you want to make. 

The selected source files are highlighted in the target window. 

(2) Choose Make from the Sources menu. 
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The IDE Log window opens along the bottom of the Open Watcom IDE Project window. In the log 
window you can monitor the make procedure. Execution Complete appears in the IDE Log window 
when the make is completed on the selected source files. 

To make all targets for the current project: 

(1) Choose Make All from the Actions Menu. 

The IDE Log window opens along the bottom of the Open Watcom IDE Project window. In the log 
window you can monitor the make procedure. Execution Complete appears in the IDE Log window 
when the make is completed on the targets. If the make is successful an executable file for each target 
in the project can be found in the directory associated with the target window. 

1.9.5.1 Viewing the Make Command for a Source File 

With the IDE you can use the Show Make Command function to display the makefile commands for the 
selected source file. These are the commands that will be used to compile the selected source file when you 
choose the function Make from the Sources menu. 

To view the make commands for source files: 

(1) Click once on the source file whose makefile commands you want to view, 
or 

Click once on the header of the group of source files whose makefile commands you want to view. 
The selected source file or group header is highlighted. 

(2) Choose Source Options from the Sources menu. 

A submenu appears on the screen from the Source Options menu. 

(3) Choose Show Make Command from the Source Options submenu. 

The Source Command dialog appears on the screen. This dialog displays the makefile commands for 
the selected source file or source file header. 



Figure 25. The IDE Source Command dialog displays the makefile commands for the selected source 
file(s). 

(4) Click on OK to close the dialog. 


Working with Source Files 35 











Open Watcom Integrated Development Environment 


1.9.6 Viewing Included Files 

The Included Files function in the Sources menu enables you to select a source file and view a list of all of 
the files included by that source file. This is a list of all files on which the selected source file depends. 
From this list you can select included files and edit them. 

Because the selected source file depends on the files in this list, it is necessary to remake it if changes are 
made to any of the included files. If you are using the Autodepend function, the IDE automatically 
remakes the source file if any of the included files are modified. 

To view the list of included files: 

(1) Click on the source file whose list of included files you want to view. 

The selected source file is highlighted in the target window. 

(2) Choose Included Files from the Sources menu. 

The Files Included dialog appears on the screen. This dialog lists all source files on which the 
selected source files depends. 

To edit a source file from the File Included dialog: 

(1) Click once on the source file in the included files list that you want to edit. 

The selected source file is highlighted in the File Included dialog. 

(2) Click on OK. 

or 

Double-click on the selected source file. 

The Files Included dialog closes and the IDE invokes the appropriate editor for the selected included 
file. The editor appears and you can edit the file. Close the editor when you are finished making the 
desired changes to return to the Open Watcom IDE Project window. 

1.10 Using the IDE Log Window 

When you compile a target or source file, the IDE Log window appears along the bottom of the screen. 
Once this window is open it remains on your screen until you close the project. However, to maximize 
your project window space you can minimize the IDE Log window when it is not being used. 

The Log menu contains three functions that you use in relation to the IDE Log window. This section 
discusses the following functions: 

• Stopping the Make Function 

• Getting Help 

• Editing the Source File 

• Saving the Log 
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1.10.1 Stopping the Make Function 

Choosing to make a source file, target, or all targets can be a lengthy process. The Stop function in the Log 
menu gives you the opportunity to cancel the make function once it has started. This is a useful function in 
case you decide that you do not want to continue with the make. 

To stop the make function: 

(1) Choose Stop from the Log menu. 

A message box appears asking if it is okay to interrupt the executing process. 

(2) Click on OK to continue. 

The message box closes and the IDE stops the make function. The IDE Log window displays the 
message Stop Invoked followed by the message Execution Complete. 

1.10.2 Getting Help 

The Help on Message function in the Log menu gives you access to on-line help information for the 
selected error message in the IDE Log window. 

To reveal help for an error message: 

(1) Click once on the error message in the IDE Log window on which you want information. 

The selected error message is highlighted in the IDE Log window. 

(2) Choose Help on Message from the Log menu. 

This opens the Help window. Information on the selected error message appears in this window. 

(3) Choose Close from the system menu on the Help window to cancel the Help facility. 

The Help window closes and you return to the IDE Log window. 

1.10.3 Editing the Source File 

The Edit File function in the Log menu allows you to select an error message in the IDE Log window and 
edit the corresponding source file. This function invokes the appropriate editor for the source file and 
positions your cursor in the source code where the error occurred (if the error message contained line and 
column information). 

To edit a source file: 

(1) Click once on the error message in the IDE Log window that you want to edit. 

The selected error message is highlighted in the IDE Log window. 

(2) Choose Edit File from the Log menu. 
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or 

Double-click on the selected error message. 

Both of these actions open the appropriate editor. If the Open Watcom Editor appears and the error 
message contained column and line details, your cursor will be positioned at the error in the source 
code. 

(3) Make the required changes to the source file and exit the Editor. 

1.10.4 Saving the Log 

The Save Log As function in the Log menu allows you to save the contents of the Log window into a file. 
To save the log: 

(1) Choose Save Log As from the Log menu. 

The Save Log As dialog appears where you specify the filename by which you want to save the 
contents of the Log window. 

(2) Enter the desired log name in the Lile Name field. 

(3) Specify the directory to which you want to save the log. 

(4) Click on the OK button. 

The IDE closes the Save Log As dialog and saves the current log as specified 


1.11 The IDE Switches 


There are a number of different switches you can set in the Open Watcom Integrated Development 
Environment. Switches enables you to change the way the various tools, such as compilers and linkers, 
perform their jobs. The switches discussed in this section are: 

• Release and Development Switches 

• Target and Source Lile Switches 

• The Autodepend Switch 

This section discusses the different switches available in the IDE and how you can use them. 

1.11.1 Using Release and Development Switches 

There are two sets of switches the IDE can use during the make process: Development and Release 
switches. You are able to specify different switches in each set for each target in your project. The letters 
D and R in the target window to the left of the target type indicate which set of switches is being used. You 
choose the switches you want the IDE to use from the Target Options submenu under the Targets menu. 

The selected set of switches has a check mark beside it and appears in grey text. 
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To change the selected set of switches for a target: 

(1) Click once on the target whose switches you want to change. 

The title bar of the selected target is highlighted. 

(2) Choose Target Options from the Targets menu. 

A submenu appears from the Target Options menu. 

(3) Choose Use Development Switches or Use Release Switches (whichever is not currently selected) 
from the submenu, as desired. 

A message box appears asking if you want to mark the selected target and its source files for remake. 

(4) Choose Yes or No, as desired, to continue. 

The message box closes and you return to the Open Watcom IDE window. The next time you 
perform a make, the IDE will use the selected set of switches. 

1.11.2 Setting Target and Source File Switches 

You can set a variety of command-line compiler and linker options in the Open Watcom Integrated 
Development Environment. This section shows you how to use the Switches dialogs to choose your 
options. 

You can set the Integrated Development Environment to work in one of two switch modes: Use 
Development Switches or Use Release Switches. Either of these two options uses a default set of switch 
settings, unless you specify otherwise. You can set switches for an individual target, specific source file 
type, or individual source file. 

1.11.2.1 Setting Target Switches 

To set switches for a target: 

(1) Click once on the target window for which you want to set switches. 

The title bar of the selected window is highlighted. 

(2) Choose Windows Linking Switches from the Options menu, 
or 

Choose Target Options from the Targets menu and then choose Windows Linking Switches from the 
Target Options submenu. 

The Windows Linking Switches dialog appears on the screen. The switches you access from this 
dialog affect only the currently selected target. There are four Switches dialogs, each one allowing 
you to set the following types of switches: 


The IDE Switches 39 




Open Watcom Integrated Development Environment 


• Basic 

• Import, Export and Library 

• Advanced 

• Special 

• Resource 

You can use the forward (») and backward («) buttons or the drop-down list to choose the set of 
switches you want to set. 



Figure 26. Use the Windows Linking Switches dialog to set command-line compiler and linker options. 

The first dialog allows you to choose the debugging information you want to see. Remember, if the 
option Use Development Switches is enabled in the Target Options submenu of the Targets menu, the 
Integrated Development Environment automatically sets switches to include all debugging 
information. You can change this setting by selecting Use Release Switches from the Target Options 
submenu under the Targets menu or choosing specific switches in the Switches dialogs. 

Select the CopyRel button in the Switches dialog to copy the set of Release switches to the current 
dialog. You can then make further changes, as required. This button is available only if the 
Development switches are selected in the Setup Target submenu under the Targets menu. 

Select the CopyDev button in the Switches dialog to copy the set of Development switches to the 
current dialog. You can then make further changes, as required. This button is available only if the 
Release switches are selected in the Target Options submenu under the Targets menu. 

Select the Reset button to reset the switches to the default Release or Development switches, as 
selected in the Target Options submenu under the Targets menu. 

(3) Click on OK when you are finished setting switches for the selected target. 

The Switches dialog closes and you return to the Open Watcom IDE Project window. 
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1.11.2.2 Setting Source File Switches 

The Switches function in the Source Options submenu of the Sources menu enables you to set switches for 
the compiler that is associated with the selected source file or source file group. 

To set switches for a source file group: 

(1) Click once on the target window that contains the relevant source files. 

(2) Choose the appropriate item from the Options menu. 

For example, to set switches for all ".c" files in the selected target, choose C Compiler Switches from 
the Options menu. 

The Compiler Switches dialog appears on the screen. The switches you access from this dialog affect 
only the currently selected source file or source file group. There are eleven Switches dialogs for 
Open Watcom C/C++, each one allowing you to set the following types of switches: 

• File Option Switches 

• Diagnostics Switches 

• Source Switches 

• Miscellaneous Switches 

• Optimization Switches 

• Debugging Switches 

• CodeGen Strategy Switches 

• Register Usage Switches 

• CodeGen Option Switches 

• Memory Model and Processor Switches 

• C or C++ Compiler Switches 

There are ten Switches dialogs for Open Watcom FORTRAN 77. 

• File Option Switches 

• Compile-time Diagnostic Switches 

• Run-time Diagnostic Switches 

• Debugging Switches 

• Code Generation Strategy Switches 

• Code Generation Option Switches 

• Register Usage Switches 

• Optimization Switches 

• Application Type Switches 

• Miscellaneous Switches 

You can use the forward (») and backward («) buttons or the drop-down list to choose the set of 
switches you want to set. 
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Figure 27. Use the C Compiler Switches dialog to set switches for the compiler associated with the selected 
source file(s). 

The first of several compiler switch dialogs appears. Of note is the sixth screen, Debugging Switches, 
which allows you to choose the debugging information you want to see. Remember, if the option Use 
Development Switches is enabled in the Target Options submenu of the Targets menu, the Integrated 
Development Environment automatically sets switches to include all debugging information. You can 
change this setting by selecting Use Release Switches from the Target Options submenu under the 
Targets menu or choosing specific switches in the Switches dialogs. 

Select the CopyRel button in the Switches dialog to copy the set of Release switches to the current 
dialog. You can then make further changes, as required. This button is available only if the 
Development switches are selected in the Target Options submenu under the Targets menu. 

Select the CopyDev button in the Switches dialog to copy the set of Development switches to the 
current dialog. You can then make further changes, as required. This button is available only if the 
Release switches are selected in the Target Options submenu under the Targets menu. 

Select the Reset button to reset the switches to the default Release or Development switches, as 
selected in the Target Options submenu under the Targets menu. 

(3) Click on OK when you are finished setting switches for the selected source file or group of source 
files. 

The Switches dialog closes and you return to the Open Watcom IDE Project window. 

To set switches for a specific source file: 

(1) Click once on the source file for which you want to set switches. 

The selected source file is highlighted. 

(2) Choose Source Options from the Sources menu. 

A submenu for the Source Options menu appears on the screen. 
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(3) Choose the appropriate item from the Source Options submenu. 

For example, if the selected source file has a ".c" extension, choose C Compiler Switches from the 
Options menu. 

The Compiler Switches dialog appears on the screen. The switches you access from this dialog affect 
only the currently selected source file. There are eleven Switches dialogs for Open Watcom C/C++, 
each one allowing you to set the following types of switches: 

• File Option Switches 

• Diagnostics Switches 

• Source Switches 

• Miscellaneous Switches 

• Optimization Switches 

• Debugging Switches 

• CodeGen Strategy Switches 

• Register Usage Switches 

• CodeGen Option Switches 

• Memory Model and Processor Switches 

• C or C++ Compiler Switches 

There are ten Switches dialogs for Open Watcom FORTRAN 77. 

• File Option Switches 

• Compile-time Diagnostic Switches 

• Run-time Diagnostic Switches 

• Debugging Switches 

• Code Generation Strategy Switches 

• Code Generation Option Switches 

• Register Usage Switches 

• Optimization Switches 

• Application Type Switches 

• Miscellaneous Switches 

You can use the forward (») and backward («) buttons or the drop-down list to choose the set of 
switches you want to set. 
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Figure 28. Use the C Compiler Switches dialog to set switches for the compiler associated with the selected 
source file(s). 

The first of several compiler switch dialogs appears. Of note is the sixth screen. Debugging Switches, 
which allows you to choose the debugging information you want to see. Remember, if the option Use 
Development Switches is enabled in the Target Options submenu of the Targets menu, the Integrated 
Development Environment automatically sets switches to include all debugging information. You can 
change this setting by selecting Use Release Switches from the Target Options submenu under the 
Targets menu or choosing specific switches in the Switches dialogs. 

Select the CopyRel button in the Switches dialog to copy the set of Release switches to the current 
dialog. You can then make further changes, as required. This button is available only if the 
Development switches are selected in the Target Options submenu under the Targets menu. 

Select the CopyDev button in the Switches dialog to copy the set of Development switches to the 
current dialog. You can then make further changes, as required. This button is available only if the 
Release switches are selected in the Target Options submenu under the Targets menu. 

Select the Reset button to reset the switches to the default Release or Development switches, as 
selected in the Target Options submenu under the Targets menu. 

(4) Click on OK when you are finished setting switches for the selected source file or group of source 
files. 

The Switches dialog closes and you return to the Open Watcom IDE Project window. 

1.11.3 Using the Autodepend Switch 

The Use Autodepend switch in the Target Options submenu of the Targets menu keeps track of updated 
source files. Once a source is modified, the IDE remembers that it needs to be recompiled the next time 
you do a make. By using the Use Autodepend switch, the IDE also keeps track of changes made to source 
files on which other source files depend. 

For example, let’s say that your current project has a source file, source . cpp, that depends on a header 
file, source . hpp. If the Use Autodepend feature is not enabled and changes are made to source . hpp 
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after source . cpp in your current project has been compiled, the IDE does not recognize that your 
current source file is now out of date. This means that the next time you do a make, the IDE will not 
compile source . cpp . The Use Autodepend feature tells the IDE to compare the date and time stamps 
on all of the dependent source files in addition to the source files in the current project and their 
corresponding object files, so the IDE recognizes when your current source file needs to be recompiled. 

To set the Use Autodepend switch: 

(1) Choose Target Options from the Targets menu. 

A submenu appears from the Target Options menu. A check mark beside the menu option indicates 
that it is enabled. 

(2) Select the Use Autodepend option from the Target Options submenu. 

If the option was enabled when you selected it, you have disabled the Use Autodepend feature. If the 
option had no check mark when you selected it, you have enabled the Use Autodepend feature. 

1.12 Configuring the Integrated Development Environment 

The Integrated Development Environment can be reconfigured to some extent. You can customize the 
following features. 

• Show or hide the Toolbar 

• Show or hide the Status Bar 

• Enable or disable automatic updates of file status in the target windows 

• Select your own text editor 

• Select a source revision control system 
The next few sections describe these features. 

1.12.1 Show Toolbar 

The Integrated Development Environment Toolbar that appears under the Menu Bar can be removed from 
or added to the IDE window. 

To add or remove the toolbar: 

(1) Choose File from the menu bar. 

A checkmark beside Show Tool Bar indicates that the toolbar is present on the screen. 

(2) Select Show Tool Bar. 

The Show Tool Bar state will be toggled. If the toolbar was on the screen, it will disappear. If the 
toolbar was not on the screen, it will reappear. 
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1.12.2 Show Status Bar 

The Integrated Development Environment Status Bar that appears at the bottom of the IDE window can be 
removed from or added to the screen. 

To add or remove the status bar: 

(1) Choose File from the menu bar. 

A checkmark beside Show Status Bar indicates that the status bar is present on the screen. 

(2) Select Show Status Bar. 

The Show Status Bar state will be toggled. If the status bar was on the screen, it will disappear. If the 
status bar was not on the screen, it will reappear. 

1.12.3 Auto Refresh 

The IDE will automatically update the target windows with the state of all files when this option is enabled. 
To enable or disable auto refresh: 

(1) Choose File from the menu bar. 

A checkmark beside Auto Refresh indicates that auto refresh is enabled. 

(2) Select Auto Refresh. 

The Auto Refresh state will be toggled. When Auto Refresh is disabled, it may be necessary to select 
Refresh from the Window menu whenever the target window status becomes out of date. 

1.12.4 Selecting Your Own Text Editor 

You can use your own favourite text editor from within the Integrated Development Environment. 

To select your own text editor: 

(1) Choose Set Text Editor from the File menu. 

The Set Text Editor dialog appears. You can enter the name of the text editor in the first field. You 
must also indicate whether the text editor is an executable file or a Dynamic Link Library (DLL). If 
the editor is an executable file (rather than a DLL), then you can enter an argument line in the second 
field. The argument line will be supplied to the editor whenever it is started by the IDE. The 
argument line can include any of three different macros which will be filled in by the IDE. The 
macros are: 
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%f The name of the file to be edited. 

%r The row in the file at which to position the cursor. If the editor is invoked from a 

diagnostic message which contains a line number then the row value is extracted from 
the message; otherwise the row value is 1. 

%c The column in the file at which to position the cursor. If the editor is invoked from a 

diagnostic message which contains a column number then the column value is 
extracted from the message; otherwise the column value is 1. 

For example, if the editor argument line that you specified was: 
file='%f' row='%r' col='%c' 

and you double click on an error message in the Log window that names the file f oobar . c with an 
error at line 215 and column 31, then the argument line that is passed to your editor is: 

file='foobar.c' row='215' col='31' 

This flexibility allows you to specify the name of the file to edit and the row and/or column at which 
to position the text cursor. If no row or column is available, then the IDE will supply the value of 1 as 
a default. 

(2) Select OK when you wish to confirm the selection of a new editor, 
or 

Select Cancel when you wish to cancel the selection of a new editor, 
or 

Select Default when you wish to restore the default editor selection and then select OK or Cancel. 

1.12.5 Selecting a Source Revision Control System 

You can use a source code Revision Control System (RCS) in conjunction with the Integrated Development 
Environment. 

To select a revision control system 

(1) Choose Set Source Control from the File menu. 

A number of options are presented: 

MKS RCS Mortice Kern Systems Revision Control System 

MKS SI Mortice Kern Systems Source Integrity 

PVCS Intersolv Project Version Control System 

Other Any other flavour of revision control system (default) 
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None No revision control system 

Object Cycle Powersoft’s Object Cycle 
Perforce Perforce 

When you select a source revision control system, the Checkout Source and Checkin Source items in the 
Sources menu are enabled. The Checkout Source and Checkin Source items spawn batch/command files or 
dialogs corresponding to your selection of revision control system. The batch/command files are located in 
the \WATCOM\BINW and YWATCOMYBINP directories. These files can be modified to suit your 
environment. 

MRS RCS 


MKS_CO for checking out/locking files with MKS RCS 
MKS_CI for checking in/unlocking files with MKS RCS 


MKS SI 


Checkout Dialog a check out dialog will appear on the screen when using MKS SI 
Checkin Dialog a check in dialog will appear on the screen when using MKS SI 


PVCS 


Other 


None 


PVCS_CO for checking out/locking files with Intersolv PVCS 
PVCS_CI for checking in/unlocking files with Intersolv PVCS 


GEN_CO a file which you can edit to provide check out (and lock) functionality to 
any generic revision control system 

GEN_CI a file which you can edit to provide check in (and unlock) functionality to 
any generic revision control system 

When selected. Checkout Source and Checkin Source are disabled. 


When one of the batch files is spawned, a number of arguments are passed to the batch file. 

For checking out files, the following arguments are passed: 

1. "pause" or "nopause" to enable optional screen pause after completion of action 

2. full source file path specification 

3. full project file path specification (,wpj file) 

4. full target file path specification (.tgt file) 

For checking in files, the following arguments are passed: 

1. full source file path specification 

2. full message file path specification (this file contains the textual message that you enter when 
checking in a file) 
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3. full project file path specification (.wpj file) 

4. full target file path specification (.tgt file) 

1.13 Executing Special Commands 

Sometimes you may find it necessary to execute commands before and/or after performing a make. The 
Open Watcom Integrated Development Environment provides Before and After commands in the File and 
Targets menus. These commands enable you to perform actions immediately before or after making either 
the selected target or all targets for the current project. 

To set Before or After directives: 

(1) Click once on the target for which you want to set a before or after directive. 

The title bar of the selected target is highlighted. 

(2) Choose Target Options from the Targets menu. 

A submenu appears from the Target Options menu. 

(3) Choose Execute Before or Execute After from the Target Options submenu. 

A Target Before or Target After dialog appears on your screen. 

Note: If you want to set before or after directives to be executed when you make all targets, 

select the before and after commands from the File menu. 

(4) Enter the command you want to execute before or after the selected target is made. 



Figure 29. Enter execute commands in the Target Before or Target After dialogs. 

(5) Click on OK to continue. 

The IDE stores the information you entered and closes the dialog. When you next perform a make on 
the selected target, the IDE will execute the before or after directive you entered. 
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1.14 Adding Resources to a Target 

You may want to include resources in your target executable. There are two ways of doing this in the IDE: 
indirectly and directly. The act of adding resources to a target can only be done for targets that support 
resources, such as Windows or OS/2 PM. 

To add a resource to a target using the indirect method: 

(1) Create a new source file with the extension ".rc". 

(2) Click once on the new source file to select it. 

(3) Choose Edit Text from the Sources menu to invoke the Open Watcom Editor. 

The editor opens on your screen with an empty window. You can now add the resource file text. 

(4) Enter the resource statements in the editor. 

(5) Save your work and close the editor when you are finished. 

You return to the Open Watcom IDE Project window. You can now compile the new source file. 

(6) Click once on the new source file to select it. 

The selected source file is highlighted in the target window. 

(7) Choose Make from the Sources menu to compile the new source file. 

The IDE compiles the selected source file. To do this, the IDE invokes the Resource Compiler which 
creates a ".res" file. The ".res" file will be automatically included in the target when it is linked. 

When you create the resource file directly, the source file contains the same information but it is stored in a 
different format. 

To add a resource to a target using the direct method: 

(1) Create a new source file with the extension ".res". 

(2) Click once on the new source file to select it. 

(3) Choose Edit Resources from the Sources menu to invoke the Open Watcom Resource Editor. 

The editor opens on your screen with an empty window. You can now create the resources. 

(4) Create the resources. 

(5) Save your work and close the editor when you are finished. 

You return to the Open Watcom IDE Project window. You can now compile the new source file. 

(6) Click once on the new source file to select it. 

The selected source file is highlighted in the target window. 
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(7) Choose Make from the Sources menu to compile the new source file. 

The IDE compiles the selected source file. The IDE does not need to invoke the Resource Compiler 
to create a ".res" file because you created the ".res" file directly using the Resource Editor. The ".res" 
file will be automatically included in the target when it is linked. 

1.15 Including Libraries in a Target 

You use the same procedure to include static and DLL libraries in your target as you use to add any source 
file to a target. The IDE includes the libraries when the target is linked. 

To create static and DLL libraries: 

(1) Create a new target entering the library name in the Target Name field and choosing the appropriate 
image type. 

Clicking on OK on the New Target dialog closes the dialog and creates a new target with the specified 
name in the title bar. 

(2) Add the desired source files, new or existing, to the library you have created. 

Note: If you want one of your other targets to use that library, you must enter the library as a 

source file for that target. When you enter the library as a source file you must give it 
the extension ".lib", regardless of whether the library is a static or DLL library. For 
example, if your library is entitled Target A and you want your existing Target B to 
use that library, add Target A as a source file on Target B with the extension ".lib". 

1.16 Targets and Image Types Supported by the IDE 

The IDE supports the creation of a wide variety of targets. The following sections summarize the choices 
available. 

1.16.1 Win32 Targets 

Character-mode Executable [.exej 

The target is a non-GUI Win32 application. 

Windowed Executable [.exej 

The target is a GUI Win32 application. 

Dynamic Link Library [.dll] 

The target is a Win32 DLL. 

Library [.lib] 

The target is a Win32 library. 

Help File [.hip] 

The target is a help file. 
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1.16.2 Win 16 Targets 

Executable [.exe] 

The target is a 16-bit Windows application. 

Dynamic Link Library [.dll] 

The target is a 16-bit Windows DLL. 

Library [.lib] 

The target is a 16-bit Windows library. 

Help File [.hip] 

The target is a help file. 

1.16.3 Win386 (Watcom Extender) Targets 

Executable [.exe] 

The target is a 32-bit Open Watcom Windows extender application. 
Dynamic Link Library [.dll] 

The target is a 32-bit Open Watcom Windows extender DLL. 

Library [.lib] 

The target is a 32-bit Open Watcom Windows extender library. 

Help File [.hip] 

The target is a help file. 

1.16.4 DOS - 16-bit Targets 

Executable [.exe] 

The target is a 16-bit DOS .exe file. 

.COMExecutable [.com] 

The target is a 16-bit DOS .com file. 

Library [.lib] 

The target is a 16-bit DOS .lib file. 

1.16.5 DOS - 32-bit Targets 

CauseWay Executable [.exe] 

The target is a 32-bit CauseWay .exe file. 

CauseWay DLL (register based) [.dll] 

The target is a 32-bit CauseWay dll using register-based calling conventions. 

CauseWay DLL (stack based) [.dll] 

The target is a 32-bit CauseWay dll using stack-based calling conventions. 
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DOS4GW Executable [.exe] 

The target is a 32-bit DOS/4GW .exe file. 

PMODW/WExecutable [.exe] 

The target is a 32-bit PMODE/W .exe file. 

DOS32/A Executable [.exe] 

The target is a 32-bit DOS32/A .exe file. 

Pharlap Executable [.exp] 

The target is a 32-bit PharLap "RUN386" .exe file. 

Pharlap TNT Executable [.exe] 

The target is a 32-bit PharLap TNT .exe file. 

Flashtek Executable [.exe] 

The target is a 32-bit FlashTek .exe file using register-based calling conventions. 
Flashtek — Stack based [.exe] 

The target is a 32-bit FlashTek .exe file using stack-based calling conventions. 


Library [.lib] 

The target is a 32-bit DOS .lib file. 

1.16.6 OS/2 -16-bit Targets 

Executable [.exe] 

The target is a 16-bit OS/2 console application. 

PM Executable [.exe] 

The target is a 16-bit OS/2 Presentation Manager application. 

Fullscreen Executable [.exe] 

The target is a 16-bit OS/2 Fullscreen application. 

Dynamic Link Library [.dll] 

The target is a 16-bit OS/2 DFF. 

Library [.lib] 

The target is a 16-bit OS/2 library file. 

Help File [.hip] 

The target is an OS/2 help file (HLP format). 

INF File [.inf] 

The target is an OS/2 help file (INF format). 
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1.16.7 OS/2 - 32-bit Targets 

Executable [.exe] 

The target is a 32-bit OS/2 console application. 

PM Executable [.exe] 

The target is a 32-bit OS/2 Presentation Manager application. 

Fullscreen Executable [.exe] 

The target is a 32-bit OS/2 Fullscreen application. 

Virtual Device [.exe] 

The target is a 32-bit OS/2 Virtual Device Driver application. 

Dynamic Link Library [.dll] 

The target is a 32-bit OS/2 DLL. 

Library [.lib] 

The target is a 32-bit OS/2 library file. 

Help File [.hip] 

The target is an OS/2 help file (HLP format). 

INF File [.inf] 

The target is an OS/2 help file (INF format). 

1.16.8 Linux Targets 

Executable [.exe] 

The target is a Linux application. 

Shared Library [.dll] 

Shared libraries are not yet supported. 


Library [.lib] 

The target is a Linux static library file. 

1.17 Invoking Other Applications from the IDE 

When using the Open Watcom Integrated Development Environment, there are several other applications 
you may want to use. To save you the frustration of having to constantly exit the IDE and start up a new 
application, we have made it possible to invoke other applications from within the Integrated Development 
Environment. Following are the applications you can invoke from the IDE: 

• Browser 

• Open Watcom Debugger 

• Open Watcom Execution Sampler 

• Open Watcom Execution Profiler 

• Open Watcom Disassembler 

• Open Watcom Editor (text editor) 

• Open Watcom Resource Editor 


54 


Invoking Other Applications from the IDE 




Open Watcom Integrated Development Environment 


• Open Watcom Zoom 

• Open Watcom Heap Walker 
•Spy 

• DDE Spy 

You invoke these applications by making a selection from the toolbar or various menus in the IDE. The 
Actions menu contains some of the applications. You can find others in the Targets and Sources menus. 
The menu options that appear vary, depending on the contents of the current project. The applications are 
available in the menu items only when appropriate. For example, if the currently selected target has no 
source files, no applications appear in the Sources menu. 


Hint: An alternate way to view the contents of the Targets and Sources menu is to click the right 
mouse button while your cursor is positioned in the project window. If your cursor is positioned over a 
target, the Targets menu appears. If your cursor is positioned over a source file, the Sources menu 
appears. 


Refer to the appropriate sections in this manual for detailed information on using the various applications. 


1.18 Invoking DOS Applications from the IDE under OS/2 

There are occasions where you may wish to change the default DOS or WIN-OS/2 settings when running a 
DOS/Windows application from the IDE. The mechanism which we provide is through the use of a special 
IDE_DOS_SETTINGS environment variable. For example, to set the DPMI memory limit to 16 and to 
enable DOS BREAK, you can set the environment variable as follows: 

Example: 

set ide_ dos_ settings=dpmi_ memory_ limit#l6; dos_ break#l 

Due to the command processor limitations, the "#" character is used in place of the The above 
command is equivalent to configuring a DOS session with DOS settings as follows: 

Variable Value 

DPMI_ MEMORY_ LIMIT 16 
DOS_ BREAK ON 


1.19 Using the Information of the IDE from outside 

The batch utility IDE2MAKE generates .mk and .mkl makefiles for use with Open Watcom Make from the 
IDE .wpj and .tgt files. See IDE2MAKE in Open Watcom Tools User’s Guide. 
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2 The Open Watcom Browser 


2.1 Introduction 


Imagine being assigned to a project with thousands of lines of C++ source code. Learning the relationship 
between the objects of such an application can be very difficult. The Browser was developed to solve this 
very problem — to help developers better understand the source code they are working with. Information 
such as the class inheritance hierarchy and the call tree for an application can be studied while using the 
Browser. Once you have located a symbol, you can quickly view the source file that contains its definition 
or list all the files that reference it. Viewing these relationships helps you understand how the program 
works. 

This chapter describes the many tasks you can perform with the Browser, including creating and opening a 
Browser database file, configuring the Browser session, and viewing the list of all symbols in your 
program, the class inheritance hierarchy, and call structure. 

2.2 Using the Browser 

This section discusses the following topics: 

• Starting the Browser 

• Starting the Browser through the Open Watcom Integrated Development Environment 

• Quitting the Browser 

• The Browser Menu Bar 

2.2.1 Starting the Browser 

To start the Browser, double click on the Browser icon. This opens the Browser window. The caption bar 
of this window displays the current option file and Browser database file. The message no browser 
file appears on this line if a database file is not currently selected. 

The Browser is an integrated tool that you can open from the IDE so that you can browse the source code of 
the project you are working on. Refer to the IDE guide for further information on the Integrated 
Development Environment. 

2.2.2 Quitting the Browser 

To exit the Browser, choose Exit from the File menu of the Browser window. If you made changes to the 
options during the Browser session, a message box appears prompting you to save the changes. 

Choose No in the message box to close the Browser session without saving. Any options changed within 
the session are lost. 
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Choose Yes in the message box to save the current options to the current option file, if one exists, and exit 
the Browser session. If no option file exists, a Save As dialog appears that allows you to specify the option 
file to which you want to save the new options. 

Select Cancel to return to the main Browser window without saving the options. 


Select OK to close the dialog and exit the Browser session. 

2.2.3 The Browser Menu Bar 

The Browser’s menu bar consists of the following eight menus: 

File Create, open, and configure Browser files; save and load options 

View Choose a global view for the current database file 

Detail View detailed information for a symbol 

Tree Choose the nodes to display for a tree view 

Locate Find symbols within the current global view 

Options Configure the Browser session 

Windows Select from the list of Browser windows currently open 
Help Access on-line help information 

2.3 Browser Files 

To browse your source code, you must first create a Browser module file for each source file that you wish 
to browse. Currently, browsing is supported by the Open Watcom C/C++ compilers only (Open Watcom 
FORTRAN 77 does not support browsing). To create a Browser module file, specify the "db" option when 
you compile the source file. If you are using the Open Watcom Integrated Development Environment, 
select Emit Browser Information from the Debugging Switches panel of the Compiler Switches dialog. The 
Browser module file will have the same name as the source file and an extension of ".MBR". 

Once the Browser module files have been created, these files are merged and a Browser database file is 
created. This process eliminates redundant information such as duplicate definitions that occur when a 
header file is included by many source files. Browser database files have the extension ".DBR". 

The Browser allows you to configure your session and saves this configuration to an options file. Options 
files have the extension ".OBR". The file name setup. obr is the default name of the options file. The 
default options file is automatically loaded by the Browser when the Browser is started. 
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2.3.1 Creating a Browser Database File within the Browser 

(1) Choose New from the File menu. 

This opens the New Browser File dialog where you enter the name of the Browser database file you 
are creating. 



Figure 30. Use the New Browser File dialog to create a new Browser database file. 

(2) Type the name and path of the new Browser database file, 
or 

Click on the Files button to open a second dialog that allows you to browse the directory structure for 
an existing Browser database file. Select an existing file and change its name. If you do not change 
its name, a message box appears when you press OK asking if you want to overwrite the existing file. 

(3) Click on OK. 

This opens a Module window that will eventually contain a list of the module files that will make up 
the database file. 

(4) Click on the Add button in the Module window. 

This opens the Select Module File(s) dialog where you choose the module files to add to the database 
file. 

(5) Select the module files to add to the database file and click on OK. 
or 

Double click on the desired module file. 

This closes the Select Module File(s) dialog and adds the selected module file to the Browser file 
component list. Each module file on the components list has a check box. When added, this check 
box is marked with an X, indicating that the module file is enabled. 

(6) Continue with steps 4 and 5 until you have added all desired module files to the component list. 
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Figure 31. The Modules dialog displays the selected module files. 

(7) Click on OK on the Module window. 

This closes the Module window and creates the database file. 

2.3.2 Creating a Browser Database File from the Command Line 

It is also possible to create the Browser database file from the command line. This allows you to make 
Browser database file creation part of your standard build procedure. When you do this, the batch build 
procedure will automatically update your database file. Updating the Browser database file occurs only if 
changes have been made to a module file within the database file. 

A separate utility, called the merger, is used to create the database file. The name of the merger program is 
wbrg. exe . Its command line consists of the name of the database file and a list of the module files 
(.MBR files) to be merged. The name of the database file must be preceded by a database command. 
The default extension given to the database file is ".DBR". The list of module files must be preceded by a 
file command. The module file names must be separated by commas or enclosed by curly braces and 
separated by spaces. The list of module file names can contain wild cards. The following are examples of 
valid merger commands. In each case, the module files ml .mbr and m2 .mbr will be processed and the 
database file db. dbr will be created. 

wbrg database db file ml, m2 
wbrg database db file { ml m2 } 
wbrg file ml, m2 database db 
wbrg file { ml m2 } database db 

It is also possible to specify a command file that contains merger commands. Command files have the 
extension ".CBR". Consider a command file, called merge . cbr, containing the following merger 
commands. 

database db 
file ml 
file m2 

The following example will achieve the same results as the previous example, 
wbrg @merge 
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If you want to suppress the listing of file names that the merger produces as it is working, you can include 
the "quiet" option on the command line or in the command file. 

2.3.3 Opening an Existing Browser Database File 

(1) Choose Open from the File menu. 

This opens the Open Browser Database File dialog where you select the database file you want to 
open. 

(2) Select a database file to open and click on OK. 

or 

Double click on the desired database file. 

This closes the Open Browser Database File dialog. 

Note: You can have only one database file open at a time. If you open a second database 

file, the Browser discards the first and displays information for the second. 

2.3.4 Working with Browser Module Files 

Once a Browser database file is loaded, you might want to edit the list of modules originally used to create 
the database file. Editing the list of modules allows you to temporarily remove modules from the database 
or add modules to the database. For example, you may decide that you only want to browse a particular 
module or set of modules or you may have forgotten a module when the database was originally created. 

The Modules menu item in the File menu allows you to view the list of module files that make up the 
current database file. From this list you can perform the following functions on the module files: 

•Add 

• Remove 

• Disable 

• Enable 
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Figure 32. On the Modules dialog, you can add, remove, disable, and enable module files. 
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2.3.4.1 Adding a Module File 

(1) Choose Modules from the File menu. 

This opens the Modules dialog for the current database file. This dialog lists all module files that 
make up the database file. Each module file has a check box. An X in this box indicates that the 
module file is enabled. The Browser browses only the enabled module files. 

(2) Click on the Add button in the Modules dialog. 

This opens the Select Module File(s) dialog where you choose the module files to add to the current 
Browser file. 

(3) Select the module files to add to the Browser file and click on OK. Select multiple module files by 
holding the Shift key while you click on the desired files. 

Clicking on OK closes the Select Module File(s) dialog and adds the selected module file to the 
database file. Each module file in the module list has a check box. When added, this check box is 
marked with an X, indicating that the module file is enabled. 

(4) Continue with steps 2 and 3 until you have added all desired module files to the component list. 

(5) Click on OK in the Module dialog. 

This closes the Modules dialog and updates the database file. 

2.3.4.2 Removing a Module File 

(1) Choose Modules from the File menu. 

This opens the Modules dialog for the current database file. This dialog lists all module files that 
make up the database file. Each module file has a check box. An X in this box indicates that the 
module file is enabled. The Browser browses only the enabled module files. 

(2) Click once on the module file you want to remove from the database file. 

This highlights the selected module file. 

(3) Click on the Remove button in the Modules dialog. 

This removes the selected module file from the list. 

(4) Click on OK in the Modules dialog. 

This closes the Modules dialog and updates the database file. 

2.3.4.3 Disabling a Module File 
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(1) Choose Modules from the File menu. 

This opens the Modules dialog for the current database file. This dialog lists all module files that 
make up the database file. Each module file has a check box. An X in this box indicates that the 
module file is enabled. The Browser browses only the enabled module files. 

(2) Click in the check box of the module file you want to disable. Alternatively, use the up and down 
arrow keys to select the module file you wish to disable. Press the space bar to disable the currently 
selected module file. 

This removes the X. The blank box indicates that the module file is disabled and will not be browsed. 

(3) Repeat step 2 until you have disabled all desired module files. 

(4) Click on OK on the Modules dialog. 

This closes the Modules dialog and updates the database file. 

To disable all of the module files in the Modules dialog, click on the Disable All button. Click on OK to 
update the database file and close the Modules dialog. 

2.3 A A Enabling a Module File 

(1) Choose Modules from the File menu. 

This opens the Modules dialog for the current database file. This dialog lists all module files that 
make up the database file. Each module file has a check box. An X in this box indicates that the 
module file is enabled. The Browser browses only the enabled module files. 

(2) Click in the check box of the module file you want to enable. Alternatively, use the up and down 
arrow keys to select the module file you wish to enable. Press the space bar to enable the currently 
selected module file. 

This places an X in the box indicating that the module file is enabled and will be browsed. 

(3) Repeat step 2 until you have enabled all desired module files. 

(4) Click on OK on the Module dialog. 

This closes the Modules dialog and updates the database file. 

To enable all of the module files on the Modules window, click on the Enable All button. Click on OK to 
update the database file and close the Modules window. 


2.4 Global Views 


The menu items under the View menu let you display a global view of your program. A global view is one 
that displays relationships between all symbols in your program. The following are global views. 
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List Displays a list of all symbols in your program 

Inheritance Displays the class inheritance graph for your program 
Call Displays the call graph for your program 

Once a global view has been displayed, you can view detailed information for the symbols in the global 
view. Refer to the section entitled "Viewing Detail Information" on page 71 for a discussion on displaying 
detail information. 

It is possible to specify a query that restricts the symbols displayed in global views. See the section entitled 
"Global Symbol Queries" on page 80 for more information. 

2.4.1 The List View 

Using the Browser to view the symbols in your program is much faster than searching through your source 
code for symbol information. From the symbols list you can quickly access detailed information on a 
symbol that tells you where the symbol is used and where it is defined. 

To view a list of all symbols in the current Browser database file, choose List from the View menu. This 
displays a window which can list all symbols in your program. The window has a vertical scroll bar that 
allows you to scroll through the list of symbols in your program. Since your program may contain a very 
large number of symbols, the Browser does not load all the symbols in your program from the database. 
Instead, only the number of symbols that can be displayed in the window are loaded. As far as the Browser 
is concerned, this list is infinite. For this reason, the scroll thumb on the vertical scroll bar is positioned in 
the middle of the vertical scroll bar and cannot be moved. Click below the vertical scroll thumb to view the 
next page of symbols and above the vertical scroll thumb to view the previous page of symbols. 
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Figure 33. The List window displays all symbols in the current browser database file. 

Each symbol has a icon to its left. A letter marking each icon indicates the symbol type in the source code 
as follows: 
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F Function 

C Class 

T Typedef 

V Variable 

E Enum 

There are several ways to display the detail view of symbols. When you reveal the detail view, the file 
folder icon changes to an open file folder. To close the detail view dialog, click on the file folder. This 
changes the icon back to a closed folder and closes the dialog. To reveal the detail view of a symbol you 
can perform any of the following actions: 

• The file folder icons are hot spots that display the detail view of the selected symbol. To activate the 
hot spot, click once on the symbol name to select it and press ENTER to reveal the detail view. 

• Click once on the file folder to reveal the detail view for that symbol. 

• Click once on the symbol name to select it and choose Detail from the Detail menu. 

• Double click on the symbol name. 

2A.2 The Class Inheritance View 

Selecting Inheritance from the View menu displays the inheritance hierarchy of all of the C++ classes in 
your program using a tree. This allows you to see the relationships between base classes and derived 
classes. In the inheritance hierarchy, each node represents a class. 
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Figure 34. The Inheritance view displays the hierarchy of all C++ classes in your program (graph view 
shown). 

There are two different tree views you can choose from to display the class hierarchy: 
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Graph view The graph view displays each class in a box. A box, or node, is connected to another node 
if one is a derived class of the other. The root node of the tree is the base class for all nodes 
in the tree. The tree is initially fully expanded. See the section entitled "Manipulating the 
Tree Views" on page 69 for more information on removing and expanding nodes from the 
tree. 

Outline view The outline view displays the same information as the graph view but in a different way. 

The outline view is initially fully collapsed. That is, only the base classes are displayed. In 
order to view the derived classes of a node, you must single click on the node. This 
expands the node, displaying all its immediate derived classes. See the section entitled 
"Manipulating the Tree Views" on page 69 for more information on removing and 
expanding nodes from the tree. 

2.4.3 The Function Call Tree View 

Selecting Call from the View menu displays the function call tree for all functions in your program. This 
allows you to see all the functions that a given function calls and conversely all functions that call a certain 
function. In the call tree, each node represents a function. 
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Figure 35. The Call view displays a call tree for all functions in your program (outline view shown). 

There are two different tree views you can choose from to display the function call tree: 

Graph view The graph view displays each function in a box. A box, or node, is connected to another 
node if one function calls the other. The tree is initially fully expanded. See the section 
entitled "Manipulating the Tree Views" on page 69 for more information on removing and 
expanding nodes from the tree. 

Outline view The outline view displays the same information as the graph view but in a different way. 

The outline view is initially fully collapsed. In order to view the functions called by the 
function specified in the node, you must single click on the node. This expands the node, 
displaying all functions it calls. See the section entitled "Manipulating the Tree Views" on 
page 69 for more information on removing and expanding nodes from the tree. 
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2.4.4 Manipulating the Tree Views 

With both the graph view and the outline view you can change the information displayed in the following 
ways: 


• select the root nodes you want to view 

• expand any node in the view 

• collapse any node in the view 

You expand and collapse nodes in the graph and outline views to hide and reveal descendant and ancestor 
nodes of the selected node. There are two ways to expand and collapse nodes: 

• choose the desired function from the Tree menu 

• click on the node (applies only to the outline view) 

In addition to these functions, you can force the graph to be redrawn when a node in the tree view is 
collapsed. By default, collapsed nodes will leave a gap in the graph. Redrawing the graph removes these 
gaps. This feature is controlled by an option. See the section entitled "Configuring the Browser" on page 
79 for more information. 

Clicking on the right mouse button when the mouse cursor is in a tree view will automatically display the 
Tree menu. This allows you to perform the actions in the Tree menu without actually going to the menu 
bar. 

2.4.4.1 Selecting Root Nodes 

Select Select Root Nodes from the Tree menu to change the root nodes that are displayed. The root nodes 
you select appear in the graph or outline view; all other root nodes are hidden. 

Choosing Select Root Nodes from the Tree menu opens the Select Root Nodes dialog. This dialog lists all 
of the symbols that appear as a root node. Each symbol in the Select Root Nodes dialog has a check box. 
When enabled, this check box is marked with an X, indicating that the symbol will appear as a root node in 
the display. 



Figure 36. On the Select Root Nodes dialog, choose the symbols you want to appear as root nodes. 


Disabling Root Nodes 
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(1) Click in the check box of the root node you want to disable. Alternatively, use the up and down 
arrow keys to select the root node you wish to disable. Press the space bar to disable the currently 
selected root node. 

The X disappears meaning that the root node is disabled and will not appear in the display. 

(2) Repeat step one until you have disabled all desired root nodes. 

(3) Click on OK in the Select Root Nodes dialog. 

The Select Root Nodes dialog closes and the display is updated. 

To disable all of the root nodes in the Select Root Nodes dialog, click on the Disable All button. This 
removes Xs from each box in the Select Root Nodes dialog. Click on OK to close the dialog and update the 
display. 

Note: This disables the selected root nodes only for the active view window. 

Enabling Root Nodes 

(1) Click in the check box of the root node you want to enable. Alternatively, use the up and down 
arrow keys to select the root node you wish to enable. Press the space bar to enable the currently 
selected root node. 

An X appears in the box indicating that the root node is enabled and will appear in the display. 

(2) Repeat step one until you have enabled all desired root nodes. 

(3) Click on OK in the Select Root Nodes dialog. 

The Select Root Nodes dialog closes and the display is updated. 

To enable all of the root nodes in the Select Root Nodes dialog, click on the Enable All button. An X 
appears in each box on the Select Root Nodes dialog. Click on OK to close the dialog and update the 
display. 

Note: This enables the selected root nodes only for the active view window. 

2.4A2 Expanding Nodes 

You can expand the display all at once, one level at a time, or one branch at a time. To expand by levels 
and branches, you must first select the node you want to expand. Do this by clicking once on the desired 
node. 

Expand One Level 

Choose Expand One Level from the Tree menu to display all of the immediate children for 
the selected node. 

Expand Branch 

Choose Expand Branch from the Tree menu to display all descendants of the selected node. 

Expand All Choose Expand All from the Tree menu to fully expand all of the enabled root nodes. 

Disabled root nodes do not appear in the display. 
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2.4A.3 Collapsing Nodes 

You can collapse the display all at once or one branch at a time. To collapse by branches, you must first 
select the node you want to collapse. Do this by clicking once on the desired node. 

Collapse Branch 

Choose Collapse Branch from the Tree menu to hide all descendants of the selected node. 

Collapse All Choose Collapse All from the Tree menu to collapse all of the nodes and display only the 
root nodes. 

Using the Keyboard 

You can expand and collapse the symbols using key sequences. Click once on the symbol name to 
highlight it and press one of the following keys: 

+ Expand the symbol one level 

Collapse the symbol one level 

* Expand all descendants of the selected node. This is the same as choosing Expand Branch 

from the Tree menu. 

CTRL * Expands all of the enabled root nodes. This is the same as choosing Expand All from the 

Tree menu. 

CTRL - Collapses all of the symbols and displays only the root nodes. This is the same as choosing 

Collapse All from the Tree menu. 

2.5 Viewing Detail Information 

Once a global view is displayed, you can view detailed information for a symbol in the global view in 
several ways: 

• Double click on the desired symbol. 

• Click once on the desired symbol to select it; then choose Detail from the Detail menu. 

• Click once on the desired symbol to select it then press ENTER. 

From the list view, you can reveal the detail view if you: 

• Click once on the icon to the left of the symbol. 

Performing any of these actions reveals a detail view window for the selected symbol. The same 
information appears in this window regardless of the method used to access it. 
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Figure 37. The detail view displays detailed information for the selected symbol. 


The detail view window displays the source file where the symbol is defined or declared and it shows you 
what the symbol looks like in your source code. 


A list box appears in the detail view window when you select a symbol whose type is a function, class, or 
enum. The list box contains information specific to the symbol type, as follows. 

Functions The list box displays, where applicable, local variables for the function. 

Classes The list box displays member variables and member functions for the selected class and any 

inherited classes. The Browser divides this information into three categories: 

• Public 

• Private 

• Protected 

Enums The list box displays enumerator values for the selected enumerator. 


You can view detailed information for symbols in the list box by double-clicking on the symbol. Other 
symbols in the header information for the detail view are highlighted. Double-clicking on these symbols 
also displays a detail view. 
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2.5.1 Goto Definition 

From a detail view. Goto Definition in the Detail menu allows you to edit the file that contains the symbol’s 
definition. The editor is positioned on the line and column containing the symbols definition. This allows 
you to make edits to your source code while you are browsing. When you are done, save any changes 
made and exit the editor to return to the Browser session. 

Note that any changes to your source code will make the Browser database out-of-date. 

2.5.2 Source References 

Selecting Source References from the Detail menu displays all locations in the source code where a symbol 
is referenced. This allows you to analyze all uses of a particular symbol. 

When modifying a symbol, you can use this feature to locate all occurrences of the symbol in the source 
code so you can update them. 

To view the source references for a symbol: 

(1) Position yourself at the detail view of the symbol whose source references you want to view. 

(2) Choose Source References from the Detail menu. 

This opens the Source References window for the selected symbol. This window displays the 
filename, line number, and column number of each occurrence of the selected symbol in the source 
code. 
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Figure 38. Use the Source References window to view all the occurrences of the selected symbol in the 
source code. 


2.5.3 Symbol References 

Symbol References allows you to view a list of all symbols that use a particular symbol. When modifying a 
symbol you can use this feature to locate all symbols using the modified symbol. This allows you to 
determine if all referencing symbols need to be updated. 

To view the symbol references for a symbol: 

(1) Position yourself at the detail view of the symbol whose symbol references you want to view. 

(2) Choose Symbol References from the Detail menu. 

This opens the Symbol Referencing window for the selected symbol. This window displays a list of 
all symbols that use the selected symbol. The display is the same as the list view of symbols. Each 
symbol has a icon indicating its symbol type. 
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Figure 39. Use the Symbols window to view a list of all symbols that use the selected symbol. 

You can perform the same actions in this window as from the List window. Refer to the section 
entitled "The List View" on page 66 for more information. 


From this window you can invoke the editor to make changes to the source code that contains the symbols 
that reference a particular symbol. Select the reference you want to edit in one of two ways: 


• Double click on the desired reference. 


• Click once on the desired reference to select it and press ENTER. 

This invokes the editor and positions the cursor at the line that contains the selected reference. 

2.6 Locating Symbols 

When a global view is displayed and your program contains many symbols, it can be difficult to scroll 
through the global view to locate a particular symbol. There are two functions that can help you locate a 
symbol in a global view: 

• Find 

• Find Selected 
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2.6.1 Find 

Choose Find from the Locate menu to open the Find dialog. Use this dialog to specify the criteria to be 
used to locate a symbol. For example, you can search for a particular symbol or a set of symbols with 
common characteristics. 



Figure 40. Use the Find dialog to locate one symbol or a set of symbols. 


2.6.1.1 Find Pattern 

In the Pattern field of the Find dialog, enter a pattern for the symbol(s) you wish to locate. The matching 
behaviour depends on the switches set in this dialog. 

Match Case When enabled, the Browser performs a case sensitive compare when attempting to find a 
match. 

Match Whole Symbols Only 

When enabled, the Browser locates symbols that exactly match the specified pattern. This 
switch only applies when the Use Regular Expressions switch is disabled. 

Use Regular Expressions 

When enabled, the Browser interprets the pattern specified as a regular expression. The 
Edit button, when pressed, displays the Regular Expression Options dialog. This dialog 
allows you to specify the regular expression. 

Dropping the combo box of the Pattern field displays a list of previous patterns entered. You can select a 
pattern from this list instead of entering a new one. 


2.6.1.2 Find Filters 

Clicking on the Filters button on the Find dialog opens the Find Filters dialog. This dialog allows you to 
specify the characteristics of the symbol(s) to be located. 
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Figure 41. Use the Find Filters dialog to specify characteristics of the symbol(s) you want to locate. 

In the Symbol Type section of the dialog click on the symbol types you want to view. To search for all 
symbol types, select the All button. 

In the Symbol Scope section, you can specify the scope for locating symbols. 

Member of Class: 

Specify the class that the symbol must be a member of in order to be located. 

Local Symbols of Function: 

Specify the function that the symbol must be local to in order to be located. 


Find File Filters 

The Source Files button, when pressed, displays the Source Files dialog that allows you to specify the files 
to be searched when attempting to locate a symbol. This dialog lists all source files that make up the 
database file. Each source file in the list has a check box. An X in this box indicates that the source file is 
searched when trying to locate a symbol. Click in the check box of the source file you want to disable. 

This removes the X. The blank box indicates that the source file will not be searched when trying to locate 
a symbol. To re-enable the source file, click in the check box again. This places an X in the box indicating 
that the source file will be searched. 
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Figure 42. Choose the source files to be searched using the Source Files dialog. 

The Pattern section of the dialog, allows you to specify wild card directory specifications for files that are 
to be included or excluded in the search. For example, specifying "d:\watcom\h\*.h" and pressing the 
Exclude button, will prevent any file in the "d:\watcom\h" directory with extension ".h" from being 
searched. To include these files in the search again, specify the same pattern and press the Include button. 

Pressing the Set All button includes all files in the search. 

Pressing the Clear All button excludes all files in the search. This is useful, for example, if you wish to 
only search files in the current directory. Simply press the Clear All button, specify in the Pattern 
section, and press the Include button. 

2.6.1.3 Performing the Find 

Once the filter criteria are set, perform the find operation by clicking on the OK button on the Find dialog. 
This closes the dialog and performs the search. The Browser examines the symbols in the current global 
view and selects the first symbol that matches the search criteria. 

To find the next symbol that matches the search criteria, choose Find Next from the Locate menu. 

2.6.2 Find Selected 

Because the symbols displayed in a global view are often many, only a portion of the display is visible in 
the window at any time. When you temporarily scroll away from the selected symbol or node, a quick 
method of locating that symbol is to select Find Selected from the Locate menu. This will immediately 
locate and display the currently selected symbol in the global view. 
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2.7 Configuring the Browser 

There are several options in the Browser that you can configure: 

• Regular expression processing for find and query 

• Global Symbol Queries 

• Enumerator styles for detail views of enumeration constants 

• Member filters for detail views of classes 

• Auto-arranging of graph views 

• Line drawing method for graph views 

• Orientation of graph views 

• Line styles and colors for inheritance graphs 

• Line styles and colors for call graphs 

• Selection of text editor 

• Automatic saving of options on exit 

This section describes each configuration option. 

2.7.1 Regular Expressions for Find and Query 

Regular Expressions in the Options menu allows you to configure the regular expression used to find a 
symbol and specify a query. 



Figure 43. Use the Regular Expressions Options dialog to configure a regular expression for Find and 
Query. 

Choose Regular Expressions from the Options menu to open the Regular Expressions Options dialog. In 
the Search String Meaning section of the dialog you select the anchoring method used to find a match. 

Starts With Matches only if the pattern is found at the beginning of the symbol 

Contains Matches if it occurs anywhere in the symbol 

In the Regular Expression Characters section of the dialog you select the characters you want the Browser 
to interpret as meta-characters. 
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Select the desired characters by clicking once in the corresponding check box. An X in the check box 
indicates that the character will be interpreted as a meta-character. Unchecked characters are matched as 
standard keyboard characters. To de-select a character, click again on its check box. 

The other buttons on this dialog are: 

Set All Click on Set All to enable all of the characters. 

Clear All Click on Clear All to disable all of the characters. 

Defaults Click on Defaults to discard the current settings in this dialog and replace them with the 

settings configured at the start of the Browser session. 

OK Click on OK to close this dialog. This changes the configuration for the current Browser 

session. 

2.7.2 Global Symbol Queries 

Choose Query from the Options menu to open the Query dialog. Use this dialog to specify the criteria to be 
used to display symbols in a global view. 



Figure 44. Use the Query dialog to configure global view symbol queries. 

2.7.2.1 Query Pattern 

In the Pattern field of the Query dialog, enter a pattern for the symbol(s) you wish to display in the global 
views. The matching behaviour depends on the switches set in this dialog. 

Match Case When enabled, the Browser performs a case sensitive compare when attempting to find a 
match. 

Match Whole Symbols Only 

When enabled, the Browser includes symbols that exactly match the specified pattern. This 
switch only applies when the Use Regular Expressions switch is disabled. 

Use Regular Expressions 

When enabled, the Browser interprets the pattern specified as a regular expression. The 
Edit button is enables and, when pressed, displays the Regular Expression Options dialog. 
This dialog allows you to specify the regular expression. 

Dropping the combo box of the Pattern field displays a list of previous patterns entered. You can select a 
pattern from this list instead of entering a new one. 
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2.7.2.2 Query Filters 

Clicking on the Filters button on the Query dialog opens the Query Filters dialog. This dialog allows you 
to specify the characteristics of the symbol(s) to be displayed in the global views. 

In the Symbol Type section of the dialog click on the symbol types you want to view. To display symbols 
of all types, click on the All button. 

In the Symbol Scope section, you can specify the scope of the symbols to be displayed. 

Member of Class: 

Specify the class that the symbol must be a member of in order to be displayed. 

Local Symbols of Function: 

Specify the function that the symbol must be local to in order to be displayed. 

In the Symbol Attributes section, you can specify the attributes of the symbols to be displayed. Selecting 
Artificial will cause compiler-generated symbols to be displayed. Selecting Anonymous will cause 
unnamed types to be displayed. Unnamed types will be displayed as square brackets enclosing the symbols 
whose type they define. Selecting Declared Only will cause only symbols that have been defined to be 
displayed. For example, a function prototype for an unreferenced function will not be displayed when 
Declared Only is selected. 

Query File Filters 

The Source Files button, when pressed, displays the Source Files dialog that allows you to specify the files 
that a symbol must be defined in in order to be displayed. This dialog lists all source files that make up the 
database file. Each source file in the list has a check box. An X in this box indicates that all symbols 
defined in the source file will be displayed. Click in the check box of the source file you want to disable. 
This removes the X. The blank box indicates that any symbols defined in the source file will not be 
displayed. Alternatively, use the up and down arrow keys to select the source file you wish to disable. 

Press the space bar to disable the currently selected source file. To re-enable the source file, click in the 
check box again or press the space bar. This places an X in the box again. 

The Pattern section of the dialog, allows you to specify wild card directory specifications for files. Any 
symbols defined in these files will be displayed in the global views. For example, specifying 
d: \watcom\h\ * . h and pressing the Exclude button, will prevent any symbol defined in any file in the 
d: \watcom\h directory with extension ".h" from being displayed. To display symbols from these files 
again, specify the same pattern and press the Include button. 

Pressing the Set All button displays all symbols in all files. 

Pressing the Clear All button causes no symbols to be displayed. This is useful, for example, if you wish to 
only display symbols defined in files in the current directory. Simply press the Clear All button, specify 
* . * in the Pattern section, and press the Include button. 

2.7.3 Enumerator Styles 

Selecting Enumeration Styles from the Options menu displays the Enumeration Styles dialog. This dialog 
allows you to specify the format for displaying enumeration constants in the detail views for enumeration 
constants. 
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Figure 45. Specify enumerator styles for detail views of enumerator constants using the Enumeration Styles 
dialog. 


2.7.4 Member Filters for Classes 

Member Filters in the Options menu allows you to specify the members you want to appear in the detail 
view of a class. For example, you may not want the detail class to contain private members. Alternatively, 
you may only wish to see function members and not data members. 

(1) Choose Member Filters from the Options menu. 

This opens the Member Filters dialog where you specify the information you want to appear in detail 
views for classes. 



Figure 46. Use the Member Filters dialog to select the information to appear in detail views for classes. 

(2) Choose the inheritance level from the Inherited Members section of the dialog. 

The options are: 

None Do not show inherited members. 

Visible Show the local members of a class and visible members of inherited classes. 

All Show all local and inherited members of a class. 

(3) Click on the check boxes in the Access Level section of the dialog to select the desired access levels. 

The options are Public, Protected, and Private. Only members with the selected attributes will appear 
in the detail view for a class. 
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(4) Select the desired members in the Members section of the dialog. 

Show data members in a class by enabling the variables check box. When the variables check box is 
enabled, you may also enable or disable static data members by clicking on the static check box. 

Show function members in a class by enabling the, functions check box. When the functions check 
box is enabled, you may also enable or disable static and virtual function members by clicking on the 
static and virtual check boxes. 

(5) Click on OK to accept the member filter query. 

This closes the dialog and returns you to the active window. 

Note: The Default button on the Member Filter dialog resets the query to the default settings. 

2.7.5 Auto-arranging of Graph Views 

When collapsing a graph view, nodes that become hidden are replaced by gaps in the graph. Arrange 
Graph in the Tree menu compacts the graph view to remove the spaces left vacant by hidden nodes. 

When enabled. Graph Auto-arrange of the Options menu causes the Browser to automatically compact the 
graph view each time you perform a collapse operation. To enable the automatic compaction of the graph 
view after a collapse operation, select Graph Auto-arrange from the Options menu. A check mark appears 
beside the menu item when it is enabled. Select the menu item again to disable it. 

2.7.6 Line Drawing Method for Graph Views 

Graph Square Lines in the Options menu allows you to select the type of line that connects the nodes in a 
graph view. The default is to connect nodes of the graph using diagonal lines. Choosing Graph Square 
Lines from the Options menu causes nodes to be connected using square lines (combinations of vertical and 
horizontal lines). A check mark beside the menu item indicates this method of drawing lines is enabled. 

To disable this option, select it again. 
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Figure 47. The Graph Square Lines option changes the connecting lines from diagonal to square. 
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2.7.7 Changing the Graph Orientation 

In the Options menu you can select whether the trees on the graph view grow horizontally or vertically. A 
graph view that grows horizontally is one where the root node is at the left and the leaf nodes at the right. 

A graph view that grows vertically is one where the root node is at the top and the leaf nodes at the bottom. 
By default, graphs grow vertically. 

Select Graph Horizontal from the Options menu to change the graph orientation to horizontal. Selecting 
this option changes the menu item name to Graph Horizontal in the Options menu. Select this menu item 
to change the graph orientation back to vertical. 
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Figure 48 . The Graph Horizontal option displays the graph with the root node at the left. 

2.7.8 Defining Graph View Legends 

The Inheritance Legend and Call Legend menu items in the Options menu allow you to change the colors, 
line styles, and node styles used in the graph views. Changing the styles updates all open graph views in 
the current session, as well as any new ones you open. Saving the session configuration to an option file 
saves changes made to the colors and the lines and node styles. 

The Inheritance Legend and Call Legend dialogs are designed differently, but the procedures for changing 
the graph styles are identical. 

To change the line and node styles for inheritance graphs, choose Inheritance Legend from the Options 
menu. The Inheritance Legend dialog appears. 

To change the line and node styles for call graphs, choose Call Legend from the Options menu. The Call 
Legend dialog appears. 

(1) Click once on the line or node style or use the up, down, right and left arrow keys to select the line 
or node style you want to change. 

A box appears around the selected line. 

(2) Click on the Modify button. 
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This opens the Draw Style dialog for the selected line or node style. 

(3) Click once on the desired line or node style 


use the up and down arrow keys to select the desired line or node style. 

The sample appearing in the Example field at the top of the dialog now reflects the currently selected 
line or node style. 

(4) Click once on the desired color or use the up and down arrow keys to select the desired color. 

The sample appearing in the Example field at the top of the dialog now reflects the currently selected 
color. 

(5) Click on OK to accept the new style and color setting. 

The Draw Style dialog closes, returning you to the Inheritance Legend or Call Legend dialog. Select 
another line or node style to change and repeat this procedure. 

(6) Click on OK in the Inheritance Legend or Call Legend dialog when you have changed all desired 
colors and styles for lines and nodes. 

Clicking OK closes the dialog and updates all open inheritance or call graph views with the selected 
colors and line and node styles. 

2.7.9 Selecting a Text Editor 

You can use your own favourite text editor from within the Browser. 

To select your own text editor: 

(1) Choose Set Text Editor from the Options menu. 

The Set Text Editor dialog appears. You can enter the name of the text editor in the first field. You 
must also indicate whether the text editor is an executable file or a Dynamic Link Library (DLL). If 
the editor is an executable file (rather than a DLL), then you can enter an argument line in the second 
field. The argument line will be supplied to the editor whenever it is started by the Browser. The 
argument line can include any of three different macros which will be filled in by the Browser. The 
macros are: 

%f The name of the file to be edited. 

%r The row in the file at which to position the cursor. If the editor is invoked from a 

diagnostic message which contains a line number then the row value is extracted from 
the message; otherwise the row value is 1. 

%c The column in the file at which to position the cursor. If the editor is invoked from a 

diagnostic message which contains a column number then the column value is 
extracted from the message; otherwise the column value is 1. 

Lor example, if the editor argument line that you specified was: 
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file='%f' row='%r' col='%c' 

and you double click on an error message in the Log window that names the file f oobar . c with an 
error at line 215 and column 31, then the argument line that is passed to your editor is: 

file='foobar.c' row='215' col='31' 

This flexibility allows you to specify the name of the file to edit and the row and/or column at which 
to position the text cursor. If no row or column is available, then the Browser will supply the value of 
1 as a default. 

(2) Select OK when you wish to confirm the selection of a new editor, 
or 

Select Cancel when you wish to cancel the selection of a new editor, 
or 

Select Default when you wish to restore the default editor selection and then select OK or Cancel. 

2.7.10 Automatically Saving Options on Exit 

Save Options on Exit in the Options menu instructs the Browser to automatically save the current options to 
an options file. To enable the automatic saving of options, select Save Options on Exit from the Options 
menu. A check mark beside the menu item indicates that it is enabled. To disable this option, select it 
again. 

See the section entitled "Saving Options" for more information on saving options to a file. 

2.8 Loading Options 

Use the Load Options menu to load an option file into your Browser session. 

Choose Load Options from the File menu. The Load Options File dialog appears where you select the 
option file you want to load for the current Browser session. 

2.9 Saving Options 

There are three ways to save the current options to an option file: 

• Save Options 

• Save Options As 

• Save Options on Exit 

An asterisk beside the option file name in the caption bar indicates that changes were made to the options 
during the Browser session and should be saved. This section describes each method for saving options to 
a file. 
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Note: If you have made option changes during the Browser session and you choose Exit from the 

File menu without first saving the options, the Browser prompts you to save the options to 
a file. Refer to the section entitled "Quitting the Browser" on page 59 for more 
information. 

Save Options Selecting Save Options from the File menu saves the updated options information to the 
current options file. To save options in this way, an options file must be specified in the 
caption bar. 

Save Options As 

Save Options A.? in the File menu opens the Save Options As dialog. Specify the filename 
of the option file to which you want to save the current options. Click on OK to close the 
dialog and save the options. 

Save Options on Exit 

Save Options on Exit in the Options menu allows you to specify that the Browser is to 
automatically save the current options to an options file, if one exists. When enabled, a 
check mark appears beside this menu item. 

When enabled and an option file exists, the Browser saves the changes without prompting 
when you close the session. 

When enabled and no option file exists, the Browser displays a message box prompting you 
to save the new options. Choose No in this box to close the Browser session without 
saving. Choose Yes in this box to display a Save As dialog where you specify the option 
file to which you want to save the new options. 

2.10 Setting Source Search Paths 

You can specify a command line option to the Browser that allows you to specify alternate source file 
search paths. This option is useful when a database file is created on a system different from the one that is 
used to browse the application source code. The syntax of the command line option is: 

path path_ specl;path_ spec2; . . . 

Since the database files record explicit paths to source files, it is likely that the path will no longer be valid 
once the software is moved to another system. 

When the Browser cannot locate the specified file using its explicit path, it will search the paths listed in the 
path option. 
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3 Profile Analysis Tools 


This section describes how to use the profile analysis tools to enhance the performance of your program. 
There are two profile analysis tools: 

• The Open Watcom Execution Sampler (the sampler) 

• The Open Watcom Execution Profiler (the profiler) 

You must use both of these tools to discover where your code is spending time as it executes. 

First, you must run the Sampler. The sampler starts your application and, at a predetermined interval, 
records the location where your program is executing. This information is saved in a "sample file". It is a 
statistical sampling of your program’s execution. It is not exact information, but it is accurate enough to be 
a very useful tool to enhance your program’s performance. See "The Open Watcom Execution Sampler" 
on page 93. 

Second, you run the Profiler. It reads the sample file and displays the sample information graphically. You 
can use the profiler to examine the sample data and narrow in on the places where your program spends 
large amounts of time. See "The Open Watcom Execution Profiler" on page 99. 

Once you have discovered heavily executed portions of your program, you might want to rewrite then using 
a faster algorithm or fine tune your implementation of the current algorithms. 

Note You must compile and link the program with debugging information. Use at least the dl 

option when compiling and the debug all option when linking. 
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4 The Open Watcom Execution Sampler 


4.1 Running The Open Watcom Execution Sampler 

To run the sampler from the Integrated Development Environment, click on the toolbar item that looks like 
a stopwatch. 

The sampler’s command line syntax is shown below. 


WSAMPLE [options] program [arguments] 


WSAMPLE is one of several versions of the sampler. See the section entitled "Sampler Operating 
System Considerations" on page 95 for a description of how to run the sampler under 
various environments. 


options is a list of valid sampler options, each preceded by a slash ("/") or a dash Options 

may be specified in any order. 

program is the name of the program to be sampled. 

arguments is the set of arguments passed to the program. The program behaves just as if it were 

executed directly from the command line. If you normally run your program using: 

C>program [arguments] 

then it may be sampled using the following command: 

C>wsample program [arguments] 

By default, the output of WSAMPLE is a sample file with the same name as the executable 
but with an extension of .SMP. In the above example, it would be called PROGRAM. SMP . 


4.2 Sampler Options Summary 

The sampler has several command line options. A summary of the available options is displayed on the 
screen by executing the "WSAMPLE" program appropriate for your system. 
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Owsample 


Usage: wsample [options] program [program arguments] 

Options: 

/b=<size> specify the buffer size for samples (default: 63) 
/f=<file> specify the output filename for the sample file 
/r=<rate> specify the sampling rate 


<size> is a number in the range 1 to 63 (default: 63 kb) 

<rate> is a number (range 27 to 1000) specifying the approximate 

time interval (in milliseconds) between samples 
(default: 55) 


'#' may be used instead of '=' in options (e.g., /b#10) 


4.3 Sampler Command Line Options 

Command line options allow you to control how much the program’s execution will be affected by the 
presence of the sampler. System specific options are described in detail in subsequent sections. The 
options that apply to all versions of the sampler are: 

/r=<sample_rate> Specifies the approximate time between execution samples (in milliseconds). The 

sampler will set up the system so that the program will be interrupted in intervals of the 
number of milliseconds specified on the command line. A smaller number will result in a 
more accurate sample file. A larger number result in a less accurate sample. If your 
program runs for a very short time, you should use the smallest interval possible. The 
default value is system dependent and it will be displayed if you enter "WSAMPLE" with 
no arguments. The following example will sample the program’s execution 200 times per 
second. 

Example: 

Owsample /r=5 program 

/b=<Jbuffer_size> Specifies the size of the sampler’s internal buffer (in kilobytes). The execution of the 
program will produce many samples which must be recorded in the sample file. The 
sampler stores the samples in an internal buffer until the buffer is filled and must be written 
to the disk. You may reduce the buffer size if you want to leave more memory for your 
application program. You should not make the buffer size so small that the sampler would 
have to write samples to disk more than once a second. The default size for the sample 
buffer is 63K. In the following example, a buffer size of 10K will be used: 

Example: 

Owsample /b=10 program 

/f=<fname> Specify the name of the sample file. Samples will be written to the specified file. By 

default, a file with the same name as the executable and an extension of .SMP is created. 
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4.4 Sampler Operating System Considerations 

There is a different version of the sampler to match each operating system. Some systems do not allow the 
sample rate to be adjusted. Each sampler will provide information about any unique aspects of its operation 
when you type its program name on the command line. 

Example: 

Owsample 

Here are the Open Watcom Execution Sampler executable names provided. 

Operating System: Command: 

DOS WSAMPLE.EXE 

OS/2 WSAMPLE.EXE 

DOS/4GW or DOS/4G WSAMPRSI.EXE 

386IDOS-Extender WSAMPPLS.EXP 

Windows 3.x WSAMPLEW.EXE 

Win32 WSAMPLE.EXE 

NetWare 386 WSAMPLE.NLM 

The sampler for an operating system such as DOS will not operate correctly in an environment that is not 
strictly DOS such as a Windows or OS/2 DOS box. The sampler obtains its information about what was 
executing when a timer interrupt occurs from the stack. Unlike "real" DOS, the segment/offset on the stack 
in a protected-mode environment supporting Virtual DOS Machines does not correspond to the program 
that was executing at the time of the timer interrupt. As a result, you must run the sampler in the real 
operating system environment for which it was designed. The same is true for Windows applications in a 
Win-OS/2 session. 

4.4.1 Using the Sampler with DOS 

The following options are available under DOS. For a further description of options, see "Sampler 
Command Line Options" on page 94. 

Example: 

Owsample [wsample_ options] program [arguments] 

/r=<rate> Rates from 1ms to 55ms are allowed. 

/b=<size> Sizes from IK to 64K are allowed. Since DOS places a limit on the amount of memory 
available to all programs, you may need to use the "b" option to reduce the memory 
requirements of the sampler, leaving more memory for your program. 

/f=<file> Specify the name of the sample file. 
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/i=<interrupt> specify an interrupt to monitor 

This option allows you to assign any samples that occur while a service interrupt is 
executing to the instruction following the requesting INT instruction. This will reveal the 
amount of time code spends "waiting" for interrupt services. The interrupt number 
specified is in base 16 (hex) and can be in the range 20 to ff except for the range 34 to 3d 
which is reserved for 80x87 emulation. 

Example: 

C>wsample /i=25 /i=26 program 

Id disable monitoring of the DOS interrupt 

By default, the DOS version of the sampler assigns any samples that occur while a DOS 
interrupt is executing to the instruction following the requesting INT 21H instruction. This 
will reveal the amount of time code spends "waiting" for DOS to complete a service. This 
option can be used to disable this assignment of samples so that the total time spent 
executing in DOS code may be determined. 

4.4.2 Using the Sampler with OS/2 

The following options are available under OS/2. For a further description of options, see "Sampler 
Command Line Options" on page 94. 

Example: 

Owsample [wsample_ options] program [arguments] 
lr=<rate> Rates from 1ms to 1000ms are allowed. 

Ib=<size> Sizes from IK to 64K are allowed. 

/f=<file> Specify the name of the sample file. 

Is start the application in a new session. By default the sampler starts your application in its 

own session. Use /s if you application is a PM application, or requires its own session to 
run. 

4.4.3 Using the Sampler with DOS/4GWor D0S/4G 

This version of the sampler uses one of DOS/4GW or DOS/4G to run the sampler in 32-bit protected mode. 
One of DOS4GW.EXE or DOS4G.EXE must be located in the path specified in DOS4GPATH or PATH. 
The sampler will, in turn, invoke the program with any arguments specified on the command line. The 
following options are available. For a further description of options, see "Sampler Command Line 
Options" on page 94. 
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Example: 

Owsamprsi [wsample_ options] program [arguments] 

/b=<size> Sizes from IK to 64K are allowed. 

/f=<file> Specify the name of the sample file. 

4.4.4 Using the Sampler with the Phar Lap 386IDOS-Extender 

The sampler must be run using RUN386. RUN386 will run the sampler in 32-bit protected mode which 
will invoke the program with any arguments specified on the command line. The following options are 
available. For a further description of options, see "Sampler Command Line Options" on page 94. 

Example: 

C>run386 wsamppls [wsample_ options] program [arguments] 

/r=<rate> Rates from 1ms to 55ms are allowed. 

/b=<size> Sizes from IK to 64K are allowed. 

/f=<file> Specify the name of the sample file. 

4.4.5 Using the Sampler with Windows 3.x 

The Windows 3.x sampler (WSAMPLEW.EXE) will sample both 16-bit and 32-bit Windows applications. 
The sampler will only run under Windows 3.x 386 enhanced mode. You must also include the "device" 
specification listed below in the [386Enh] section of your SYSTEM.INI file. 

DEVICE=C:\WATCOM\BINW\WDEBUG.386 

When starting the sampler, you will be presented with a window to select the executable and to specify the 
sampling rate. 

Once you start the sampler, a log window will appear. This will report the state of the sampled program (it 
does not in any way interfere with the program as it is running). Once the program terminates, this window 
will remain. The sample file will be placed in the same directory as the program you are sampling, and will 
have the extension .SMP. 

A well-behaved Windows application should have very few samples inside the application. Final 
development of a Windows application should involve a phase where the application is analyzed so that it 
does not consume large amounts of CPU time without yielding to Windows 3.x. 

To start the sampler, double-click on the Open Watcom Execution Sampler icon. Enter a command in the 
prompt dialogue box. 

[wsample_ options] program [arguments] 

The following options are available under Windows. For a further description of options, see "Sampler 
Command Line Options" on page 94. 
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/r=<rate> Rates from 1ms to 1000ms are allowed. 

/b=<size> Sizes from IK to 64K are allowed. 

/f=<file> Specify the name of the sample file. 

4.4.6 Using the Sampler with Win32 

The Win32 sampler (WSAMPLE.EXE) will only sample Win32 applications such as those that run under 
Windows 9x or Windows NT and later operating systems. It cannot be used to sample 16-bit applications. 
When starting the sampler, you will be presented with a window to select the executable and to specify the 
sampling rate. 

Once you start the sampler, a log window will appear. This will report the state of the sampled program (it 
does not in any way interfere with the program as it is running). Once the program terminates, this window 
will remain. The sample file will be placed in the same directory as the program you are sampling, and will 
have the extension .SMP. 

To start the sampler, double-click on the Open Watcom Execution Sampler icon. Enter a command in the 
prompt dialogue box. 

[wsample_ options] program [arguments] 

The following options are available under Win32. For a further description of options, see "Sampler 
Command Line Options" on page 94. 

/r=<rate> Rates from 1ms to 1000ms are allowed. 

/b=<size> Sizes from IK to 64K are allowed. 

/f=<file> Specify the name of the sample file. 

4.4.7 Using the Sampler with NetWare 386 

The sampler is also available for sampling the execution of NetWare Loadable Modules. The sampler (an 
NLM itself) will load and execute the program with arguments. 

Example: 

load wsample [wsample_ options] program [arguments] 

The following options are available under NetWare: 

/r=<rate> Rates from 1ms to 55ms are allowed. 

/b=<size> Sizes from IK to 64K are allowed. 

/f=<file> Specify the name of the sample file. 
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5 The Open Watcom Execution Profiler 

5.1 Profiler Overview 


The profiler reads the information from sample files and displays the results as a graph. Regions of 
concentrated activity are visible and may be explored by zooming in to successive levels of detail. See 
"The Open Watcom Execution Sampler" on page 93. 


5.1.1 Zoom-In and Backout 


The profiler allows you to zoom-in to successively more detailed views of your program. You may also 
back-out of any detail view. The levels of detail available are: 


Sample This is a sample file. The profiler can show you information from several sample files at 

once. 

Image A sample file may consist of several images. These are your main executable file and any 

Dynamic Link Libraries (DLL) or NetWare Loadable Modules (NLM) that your 
application called while executing. 

Modules An image may consist of several modules. Each module is a compilation unit. It consists 

of all the source code generated by one invocation of the compiler. 

Files A module may be made up of several files. Your application may contain code that is 

generated by included files. 

Functions A file may contain several functions. These are all of the global functions that are defined 
within that file. 


Source Lines A function is made up of one or more source lines. 

Assembler instructions Each source line generates zero or more lines of assembler instructions. It is 

possible to get clues about expensive operations from the number of samples found at each 
instruction. Lor example, the C statement "i = j + k * 1" will generate a multiply 
instruction. If you inspected the assembler instructions, you might find that the multiply 
instruction took the majority of the time in question. 

The process of moving from higher levels to lower levels, say, from "modules" to "functions", is called 
zooming in. Moving from lower levels to higher levels ("assembler instructions" to "source lines") is called 
backing out. As you zoom into your program the size of the region will get smaller but the amount of detail 
will increase. Likewise, backing out will restore previous levels to the larger regions and reduced detail. 
You may zoom-in and back-out of detail views in order to explore your applications execution 
characteristics. 
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5.1.2 Samples 

After you have run the sampler, you are left with a sample file. It contains a record of all locations where 
your program was interrupted by the sampler. A sample is a record of the instmction pointer within the 
program at the point in time that the interrupt occurred. Regions of the program that consume large 
amounts of execution time have a larger number of samples associated with them. 


5.1.3 Absolute and Relative Percentages 

The most important piece of data that the profiler provides is the percentage of time that a region of code 
contributes to total execution time. At the highest level (images), these percentages reflect each image’s 
contribution to the total execution time. As you successively zoom into modules and functions, you may 
become interested in the relative percentages. 

The percentage of time that a region contributes to the total program execution time of the program is 
called an absolute percentage. The percentage of time that a piece of a region contributes to the total 
execution time of your current detail level is called a relative percentage. 


As you zoom in to the source and assembly views, the absolute percentages of execution time may get quite 
small. The relative percentages help you to get a feel for the proportion of time involved within the detail 
view, but don’t get fooled into thinking that a routine contributes more than it actually does. Your 
decisions about which code to optimize should always be based on absolute percentages. 

5.2 The Open Watcom Execution Profiler User Interface 



Figure 49. The Main Profiler Screen 


The profile screen is divided into six areas. In the middle of the screen is the information area. It contains 
relative and absolute percentage numbers. The top half of the screen is the title area. The bottom half of 
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the screen is the detail view. The menu is displayed at the top of the screen. The bottom line displays 
status information. 


5.2.1 The Title Area 



Figure 50. The Profiler Title Area 


As you zoom in and back out, the title area adds and removes lines to show you that path that you took to 
your current detail view. You can back out to any level displayed in the title area by double clicking on 
that line. 


5.2.2 The Information Area 



Figure 51. The Profiler Information Area 

The information area is updated as you move around in the detail view. The red and green percentage 
numbers give you numerical values that correspond to the histogram bar on the current line in the detail 
area. The red number represents the line’s percentage of total execution time. The green number 
represents the line’s percentage of the time spent within the current detail level. 
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5.2.3 The Detail View 



Figure 52. The Profiler Detail View 

The detail view shows you a list of one of the following: 

• Image Names 

• Module Names 

• File Names 

• Routine Names 

• Source Lines 

• Assembler Instructions 

On the left half of the screen is a histogram which shows the number of samples at each location. On the 
right is a list of names. If there are more lines than will fit on the screen, you can use the cursor keys and 
scroll bars to move through the list. As you cursor through the list of names, or click on a name with the 
mouse, the information area is updated to show statistics about the current line in the detail area. 

If you find a line that is heavily executed, and you wish to examine the it in more detail, double click on it, 
or cursor to it and press F3 or ENTER. You may back out of a detail view by pressing F4 or 
BACKSPACE. As you zoom in and back out, the title area is updated to show that path you took to your 
current detail area. 
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Figure 53. The Profiler Assembly Detail 


The histogram will be drawn in two colors, red and green. The red portion represents the absolute 
percentages of execution time for each line. The green and red portions, taken together, show the 
percentage of a line relative to the current detail view. For example, if a detail line represented 10% of the 
total execution time, then the red absolute bar would take 10% of the histogram area. If the entire digital 
view represented 20% of the execution time, then the single detail line would have a green and red bar 
which would take 50% of the histogram area (10% is half the total time of the entire detail view). 


5.2.4 The Profiler Menu Bar 

The Profiler’s menu bar lets you perform operations. You can activate the menu bar by using the mouse, or 

by holding the ALT key and pressing the key that corresponds to the highlighted character in the menu bar. 

There are five menu bars. 

5.2.4.1 The File Menu 

The File menu contains the following items: 

Open... Open a new sample file. A new window will be opened, and the data from the sample file 

will be displayed in it. 

Close Close the current sample file. The current window will be closed. 

Options This allows you to set profiler options. See the section entitled "The Options Dialog" on 

page 105 for details. 

System Start a new operating system shell. This option is only available in the DOS version of the 

profiler. 

Exit Close your profiler session and exit. 
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5.2A.2 The Convert Menu 

The Convert menu allows you to select an output format to save some of the raw information to a file. The 
DIF format is supported by most of the major data manipulation or spreadsheet programs. The comma 
delimited format is a simpler format that is supported by older software, and is easily manipulated by 
custom made software. The Convert menu contains the following items: 

Current Module Use this menu item to save out the information related to the current module. 

Current Image Use this menu item to save out the information related to the current image. 

All Images Use this menu item to save out the information related to the all of the sample images. 


5.2A.3 The Windows Menu 

The Windows menu contains one menu item for each sample file you have open. Use this menu to switch 
between sample files. 


5.2AA The Actions Menu 

When you select an item from the Actions menu, it acts on the current detail view. To configure one of the 

actions across all windows, see "The Options Dialog" on page 105. The Actions menu is identical to the 

floating popup associated with the current window. See "The Popup Menu" on page 105. The Actions 

menu contains the following items: 

Zoom In (F3) Zoom in to the currently selected line. If the line is a source file, you will see a list of 

functions. If the line is a function, you will see source lines, and so on. You can also zoom 
into a line by double clicking on it. 

Back Out (F4) Back out of the current detail view to the previous view. Double clicking in the title area 
will also achieve this. 

Gather Small Values Large portions of your program may be executed very little, if at all. This menu item 
will cause lines with a smaller absolute percentage than the cutoff value to be grouped 
together. They will be displayed on a single line starting with the text ’***Gathered'. To 
change the cutoff value, see "The Options Dialog" on page 105. 

Bar Graph/Stretch When looking at areas that are not executed very much, the histogram bars can get very 
small. This menu item will stretch the histogram so that the largest bar goes all the way to 
the left of the screen. 

Bar Graph/Absolute Bars Use this menu item to turn the absolute (red) histogram bars on and off. 

Bar Graph/Relative Bars Use this menu item to turn the relative (green) histogram bars on and off. 

Sort/Sample Count Use this menu item to sort the detail view with the most heavily executed region at the 
top. 

Sort/Name Use this menu item to sort the detail view alphabetically by name. 
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5.2A.5 The Help Menu 

The Help menu item is used to select an action from the help sub-system. All of the profiler documentation 
is available in the on-line help. 

5.2.5 The Popup Menu 

You can access the pop-up menu for a window by pressing the right mouse button or by typing the period 
(.) key. The popup menu item is identical to the Action menu. The Zoom-in menu item will zoom in to the 
line on which the mouse was clicked. See "The Actions Menu" on page 104. 

5.2.6 The Options Dialog 



Figure 54. The Profiler Options Dialog 

The options dialog changes profiler settings across all views and windows. The following items can be 

changed: 

Stretch the Graphs When looking at areas that are not executed very much, the histogram bars can get very 
small. This menu item will stretch the histogram so that the largest bar goes all the way to 
the left of the screen. 

Show Absolute Bar Graphs Check this box to turn the absolute (red) histogram bars on or off. 

Show Relative Bar Graphs Check this box to turn the relative (green) histogram bars on or off. 

Sort By Sample Count Check this radio button to sort the detail views with the most heavily executed 
regions at the top. 

Sort By Name Check this radio button to sort the detail view alphabetically by name. 

Gather Small Values Large portions of your program may be executed very little, if at all. This menu item 
will cause lines with a smaller absolute percentage than the cutoff value to be grouped 
together. They will be displayed on a single line starting with the text ’***Gathered’. 
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Cutoff Percentage Specify a new cutoff percentage here. You can specify any value between 0 and 100. 



Figure 55. The Bar Graph After the Stretch Option is Selected 


5.2.7 The Convert Dialog 


Convert Data to a File 


Output File Name 



Browse ... 


Format Type 
9 DIF Format 
C Comma Format 


OK | | defaults | | Cancel 


Figure 56. The Convert Dialog 


After selecting from the Convert menu the portion of the sample information that you wish to convert, a 
conversion dialog is presented. The following items may be changed: 


Output File Name The name of the sample file with the file extension most commonly used for the 

conversion type is displayed. You may change this to any name, or use the Browse button 
to help select the name. 

Format Type Check this radio button to specify the data type that the sample information will be 
converted to. 
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5.2.8 The Status Line 

The status line is located at the bottom of the profiler screen. As you cursor through a menu, or drag the 
mouse over a menu, the status line will display hints about what each menu item does. 

5.3 How to Use the Profiler Effectively 

The fundamental principle behind the profiler is: devote your attention to the heavily executed regions 
of the program in order to extract the most performance out of a program. This principle can be 
applied to the different levels of detail within a program. You should focus on the modules that contribute 
the most time to the execution of a program. Within a module, you should focus on the functions that 
contribute the most time to the module’s total execution time. Regions of the program that exhibit heavy 
use during the execution of a program will benefit most from improvement. 

A simple example will illustrate how this is accomplished. Suppose we have a program that has three 
distinct regions. 

Region Percentage 

1 10 % 

2 70% 

3 20% 

The percentages represent the percentage of the total execution time that the region contributed. If the 
program took 100 seconds to execute, we could know that regions 1, 2, and 3 took 10, 70, and 20 seconds 
respectively. Now suppose we could rewrite region 1 so that it was twice as fast. What would be the 
impact on the total execution time of the program? It is difficult to predict precisely but, as a rule of thumb, 
we would expect that if we made region 1 twice as fast, it would only take 5% of the original execution 
time as opposed to the original 10% before optimization. So, if the original program took 100 seconds to 
execute, we would expect region l’s contribution of time to drop from 10 seconds to 5 seconds making the 
execution time of the new program now 95 seconds. Notice that the region of code was twice as fast as 
before but the total effect on the execution of the program was small. The impact of rewriting the code was 
reduced because the region did not contribute greatly to the execution time of the original program. 

To illustrate the point of using a profiler tool to increase performance, let us now look at the effect on the 
program execution speed if we were to recode region 2 so that it was twice as fast as before. Using the 
previous rule of thumb, we would expect region 2’s contribution to the original execution time to drop from 
70% to 35%. Now, if the original program took 100 seconds to execute, we would have reduced the total 
execution time to 65 seconds by focusing on region 2. Comparing these results, we can see that the most 
benefit was derived from doubling the speed of region 2 as opposed to doubling the speed of region 1. The 
change in region 2 reduced the execution time by 35% while the change to region 1 reduced the execution 
time by 5% for roughly the same amount of work. The large amount of work involved in speeding up code 
means that the most productive avenue is to focus on the heavily executed regions of the program. 
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5.4 Open Watcom Execution Profiler Command Line Format 

The formal profiler command line syntax is shown below. 


WPROF [options] [sample_file] 


The options are: 

-DIP dipjiame Specify a DIP for use by the profiler. All default DIPs are disabled by the first use of this 
option. Successive uses of the option will add to the list of DIPs. The DIPS will used in 
the order in which they are specified. 

-NOCHarremap The profiler uses character re-mapping to display many of the graphics characters. When 
you are running the profiler in some DOS environments, you may see a number of strange 
characters on the screen. This is a DOS only option to turn off character re-mapping. 

-NOGraliicsmouse This is a DOS only option to turn off the graphics mouse, and to use the block mouse 
cursor instead. 

-? or -Help Display command line help. 

5.5 Profiling a NetWare NLM 

The profiler does not run under NetWare. After you have run the sampler under NetWare, you will have to 
run the profiler under DOS, OS/2 or Windows. By default, the sample file will be created in the root 
directory of the file server. Log into the file server from a workstation and specify the name of the sample 
file on the server when you start the profiler. All NLMs should be found automatically. If they are not, 
copy the sample file and all relevant NLMs to the current directory on your workstation then try running 
the profiler again. 
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6 The Open Watcom Editor 


The Open Watcom Editor is a text editor designed for the Windows environment. It contains a toolbar and 
menu items which you can use to make your choices. It can use proportional fonts. It also contains drag 
and drop toolbars or palettes that allow you to make choices and then simply drag them to the elements to 
which you want to apply them. 



Figure 57. The Open Watcom Editor 

6.1 Startup Options 

When the Editor is started under Windows, a set of default options are used. To find out what options are 
available, modify the "Command Line:" of Program Item Properties dialog by adding after the 
program name and then start the Editor. Alternatively, you can use the Program Manager Run dialogue to 
start the Editor, specifying after the program name. 

6.2 Using Menus 

The Editor follows standard Windows conventions for its menus. A brief description of each menu item 
appears in the status bar on the bottom right of the screen when you select it. 

The File and Edit menus contain items standard to most Windows applications. 
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6.3 Using Drag and Drop Palettes 

The Editor contains two drag and drop palettes. You can affect elements of the Editor by dragging and 
dropping colors or fonts onto them. 

6.4 Using the Right Mouse Button 

The Editor has two context-sensitive menus— one for the current cursor location if less than one line is 
selected, and one if several lines are selected. You can access both of them by clicking on the right mouse 
button. 

6.4.1 When Less Than One Line is Selected 

When the cursor is in a word or a word is selected you can press the right mouse button to select the 
following options: 

Windows Help Choose Windows Help to find information about the currently selected text. 

CLib Help Choose CLib Help to find information from the C Library Reference manual about the 
currently selected text. 

Open Choose Open to open a new file. The name of the new file is the selected text. 

Cut Choose Cut to delete the selected text and place it on the Windows clipboard. 

Copy Choose Copy to copy the selected text to the Windows clipboard and leave the original. 

Find Choose Find to look for the first occurrence of the selected text. The Find dialog appears. 

Fgrep Choose Fgrep to find all files in the current directory which match the grep default mask 

and contain the selected text. 

Tag Choose Tag to look for a tag whose name is the selected text. 

6.4.2 When More Than One Line is Selected 

When several lines are selected, press the right mouse button to select the following options: 

Cut Choose Cut to delete the selected lines and place them on the Windows clipboard. 

Copy Choose Copy to copy the selected lines to the Windows clipboard and leave the original 

lines. 

»Shift Right Choose Shift Right to move the selected lines right by a number of spaces equal to the shift 
width setting. 

«Shift Left Choose Shift Left to move the selected lines left by a number of spaces equal to the shift 
width setting. 
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6.5 Starting and Quitting the Editor 

You can start the Editor from within the Open Watcom IDE or through Windows. 

To open the Editor from within the Open Watcom IDE, double click on a source module. To start the 
Editor from Windows, double click on the Open Watcom Editor icon. 

To leave the Editor, choose Exit from the File menu. 

6.6 Opening and Closing Files 

There are three items that you can select from the File menu to open and close files: 


New 

Open a new file. 

Open 

Open an existing file 

Close 

Close an open file. 


6.6.1 Opening a New File 

(1) Start the Editor. 

(2) Choose New from the File menu. 

An empty text window appears. 

6.6.2 Opening an Existing File 

(1) Start the Editor. 

(2) Choose Open from the File menu. 

The standard Windows Open dialog appears. 

(3) Choose the file and click on OK. 

You may have to change the current drive and directory to find the file. The file then opens. 

6.6.3 Closing a File 

To close a file, choose Close from the File menu. 

You can also close any open file by choosing File List from the File menu. You can then select the file 
from the list of open files and click on the Close button. 
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6.7Saving Files 

There are three items that you can select from the File menu to save files: 

Save Save the changes made to the current file. 

Save As... Save the current file under a different name. This is the standard Windows Save As... 

dialog. When you save the current file with a new name, only the new file remains open. 

Save All S ave the changes made to all open files. 

6.8 The Editor Toolbar 


In the Open Watcom Editor window, the toolbar appears below the menu bar when the Toggle Toolbar in 
the Options menu is selected (default). A check mark beside the menu option indicates that it is enabled. 
To disable this feature, choose the option again from the Options menu and the toolbar disappears. 



Figure 58. You can access up to 15 Editor functions from the toolbar. 

The following explains the function each icon performs, as well as the equivalent function on the menu bar. 

New Open a new file. This is equivalent to New in the File menu. 

Open Open a new or existing file. This is equivalent to Open in the File menu. 

Save Save the current file. This is equivalent to Save in the File menu. 

Cut Delete the selected text to the clipboard. This is equivalent to Cut in the Edit menu. 

Copy Copy the selected text to the clipboard. This is equivalent to Copy in the Edit menu. 

Paste Insert the clipboard contents at the current cursor position. This is equivalent to Paste in 

the Edit menu. 

Undo Undo the last change to the current file. This is equivalent to Undo in the Edit menu. 
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Redo 

Find 

Find Next 
Match 
File List 
Previous File 
Next File 
IDE 


Undo the last undo. This is equivalent to Redo in the Edit menu. 

Search for the specified text. This is equivalent to Find in the Edit menu. 

Repeat the last search. This is equivalent to Find Next in the Edit menu. 

Find matching brackets from the current cursor position. 

Display a list of all files being edited. This is equivalent to File List in the File menu. 
Switch to the previous file. 

Switch to the next file. 

Reactivate the IDE. This icon is present on the toolbar if the Editor was invoked from the 
IDE. 


6.9 Searching Text 

The Editor has a powerful search function that you can use to locate strings of text, including regular 
expressions. For more information on regular expressions, refer to the chapter entitled "Regular 
Expressions" on page 129. 



Figure 59. The Find Dialog 
To search for a string of text: 

(1) Choose Find from the Edit menu. 

The cursor flashes in the Find box. 

(2) Enter the search string in the Find box. 

(3) Set the find options. 

(4) Click on the Find button. 
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When the search is successful, you are repositioned to the line containing the string. 

You can use Find Next and Find Previous in the Edit menu to repeat a search for the same string. 

6.9.1 Setting Search Options 

The Find dialog contains a number of default options that you can set in the General... dialog of the 
Options menu. You can change the default settings for the current session in the Find dialog. 

You can set the following options: 

Ignore Case You can have the search match the case exactly or match the characters only and ignore the 
case. 

Regular Expressions 

You can use regular expressions in your "Find" text if you check this box. 

Search Backwards 

By default, a search is conducted through the lines that follow the current cursor position. 
Select this option if you wish to search backwards from the current cursor position. 

Wrap Search By default, the search ends when it reaches the end of the file. Flowever, if your search 
begins in the middle of the file and you want to search through the whole file, you can set 
the search to go to the beginning of the file and continue until it reaches the search starting 
point. 

6.10 Replacing Text 

The Editor has a powerful search and replace function that you can use to replace strings of text, including 
regular expressions. For more information on regular expressions, refer to the chapter entitled "Regular 
Expressions" on page 129. 
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Figure 60. The Replace Dialog 
To search and replace a string of text: 

(1) Choose Replace from the Edit menu. 

The cursor flashes in the Find box. 

(2) Enter the search string in the Find box. 

(3) Press Tab. 

The cursor moves to the Replace box. 

(4) Enter the replace string. 

(5) Set the replace options. 

(6) Click on the Replace button. 

When the replace is complete, you return to the file. 

If the Prompt on Replace option is turned on, you must confirm each replacement. If it is off, all 
occurrences of the string are replaced automatically. 

6.10.1 Setting Search and Replace Options 

The Replace dialog contains a number of default options that you can set in the General... dialog of the 
Options menu. You can change the default settings for the current session in the Replace dialog. 

You can set the following options: 
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Ignore Case You can have the search match the case exactly or match the characters only and ignore the 
case. 

Regular Expressions 

You can use regular expressions in your "Find" and "Replace" text if you check this box. 

Prompt on Replace 

By default, all found strings are replaced with the replace string. Turn this option on to be 
prompted for each replacement. 

Wrap Search By default, the search ends when it reaches the end of the file. However, if your search 
begins in the middle of the file and you want to search through the whole file, you can set 
the search to go to the beginning of the file and continue until it reaches the search starting 
point. 

6.11 Changing the Font 

You can define the font for the message window, status window, and all syntax elements in the edit buffers. 

Within the edit buffer, all fonts must be the same typeface and point size. Other areas, such as message or 
status windows, can have any typeface or point size. 



Figure 61. The Font Settings Dialog 

You can use the drag and drop feature with the Font dialog. To use drag and drop: 

(1) Choose Fonts from the Options menu. 

(2) Choose the typeface, style, and point size that you want. A sample of the text appears in the Drag 
and Drop box. 

(3) Click in the drag and drop box and drag the cursor to the element to which you want to apply the 
font characteristics. 

All elements change to the new font style. All buffers are affected when you change one. 
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6.12 Changing Colors 

Use the Colors drag and drop palette to set the color of your windows and code. You can define the color 
of the toolbar, message window, status window, and all syntax elements in the edit buffers. 



Figure 62. The Colors Palette 


To change the color of an element in your file: 

(1) Choose Colors from the Options menu. 

(2) Click on the color you want and drag it to the screen or syntax element to which you want to apply 
the color The element is changed to the new color 

Use the left mouse button to color foreground elements and the right mouse button to color 
background elements. 

Press Control and the right mouse button to affect the color of all backgrounds. Press Control and the 
left mouse button to affect all foregrounds. 

6.13 Accessing Help 

A description of the currently selected option appears in the Status bar on the bottom right of the screen. 
You can also choose items from the Help menu to see more information about an item. 

6.14 Using Fgrep Capabilities 

Fgrep stands for File Global Regular Expression and Print. It is a powerful tool that allows you to search 
through a number of files to find all occurrences of a regular expression. 
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Figure 63. The Fgrep Dialog permits you to search files containing a certain string. 

To perform an fgrep: 

(1) Choose Fgrep from the Edit menu. 

A dialog appears. 

(2) Enter the text you want to search for. 

(3) Select any options you want to use during the search. 

(4) Click on OK. 

You can set the default "fgrep" file extensions in the File Specific... dialog of the Options menu. For a 
description of the options, refer to the section entitled "File Specific Options" on page 125. 

The Files Containing dialog shows the name of all files that contain the string as well as the beginning of 
the line that contains the string. 



Figure 64. The Files Containing Dialog shows you all files with occurrences of a string. 
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From the Fgrep dialog you can: 

Edit Select an individual occurrence and open that file. The file opens in the background, but 

the Fgrep dialog remains. 

Goto Open the selected file for editing at the first occurrence of the search pattern in the Fgrep 

dialog. 

Get All Open all found files. The files open, with the last one in the list the currently open file. 

Cancel Leave the Fgrep dialog. 

6.15 Configuring the Editor 

The Options menu items contain all of the control and formatting options available with the Editor. You 
can configure the Editor as you like. Most options apply to the Editor, but some apply only to the current 
file. A description of each of the dialogs follows. 

6.15.1 Status Bar Contents 

Use the Status Bar Contents dialog to set the contents of the status bar. 



Figure 65. The Status Bar Contents dialog 

The options in the Status Bar Contents dialog are divided into three areas: 

• Items 

• Alignment 

• Commands 
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6.15.1.1 Status Bar Contents: Items 

The items in this area are: 

• Time of day 

• Current date 

• Current insertion mode 

• Line number 

• Column number 

• Menu help text 

Any of these items may be dragged to one of the windows in the status bar. When an item is dragged to 
one of these windows, it replaces the contents of that window. For example, you can drag the "Date" item 
into the status bar window displaying the current line number and the current date will be displayed in its 
place. 



Figure 66. The Status Bar consists of several small windows 

6.15.1.2 Status Bar Contents: Alignment 

The items in this area are: 

• Left aligned 

• Center aligned 

• Right aligned 

When any of these items are dragged to a window in the status bar, it affects the alignment of the item 
currently displayed in the window. For example, you can drag the "Center aligned" item (the middle one) 
into the status bar window displaying the current time and the current time will be centered in the window. 


6.15.1.3 Status Bar Contents: Commands 

The items in this area are: 
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• Split 

• Clump 

• Defaults 

When the "split" item is dragged to a window in the status bar, the window is split into two evenly-sized 
smaller windows. You can adjust the size of a window by dragging the bar between two windows to the 
left or right. 

When the "clump" item is dragged to a window in the status bar, the window is removed from the status 
bar. 

When the "defaults" item is dragged to any place on the status bar, the default settings for the status bar are 
re-established. 

6.15.2 General Options 

Use the General Options dialog to set the general features of the Editor including save, search, and word 
definitions. 



Figure 67. The General Options Dialog 

The options in the General Options dialog are divided into six categories: 

• Features 

• VI Emulation 

• Searching 

• Word Definitions 

• Filenames/Paths 

• Miscellaneous 

6.15.2.1 General Options: Features 

The Features section allow you to set options such as undo, autosave, automatic save of configuration, and 
save of files upon IDE build. 
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Undo Turn this option on to allow an unlimited number of undo’s. 

AutoSave Enable or disable the autosave option. This option allows you to determine how often a 
copy of your file is saved to the Temp Directory. Enter the time in seconds in the Interval 
box. 

Save configuration on exit 

Turn this option on if you want the Editor to save the current configuration when you leave 
the Editor. 

Save files on IDE build 

Turn this option on if you want the Editor to be notified whenever you start an IDE make. 

It will cause the Editor to prompt you for each file that was modified and has not been 
saved to disk since the last make (build). 

6.15.2.2 General Options: VI Emulation 

Beneath the Editor’s mild-mannered exterior lurks the full power of the Open Watcom VI editor, complete 
with scripting, commands and bookmarks. Turning on VI emulation causes the Editor to emulate the 
behaviour of the Open Watcom VI editor. 

6.15.2.3 General Options: Searching 

Use the Searching options dialog to set the default search and replace options. 

Ignore case Turn this option on if you do not want the Search function to match case when searching 
for a string. 

Wrap at EOF Turn this option on if you want the search to continue at the beginning of the file when it 
reaches the end of the file. It will then continue to the starting point of the search. 

6.15.2.4 General Options: Word Definitions 

Use the Word Definition options to define pairs or ranges that are considered valid parts of a word. The 

default for Ctrl-Left/Right is_09AZaz which defines the underscore character, all numbers, and all upper 

and lower case letters. The default for mouse clicks is _09AZaz which defines the colon, period, 

backslash, and underscore characters as well as all numbers, and upper and lower case letters. 

6.15.2.5 General Options: Filenames/Paths 

Use the Filenames/Paths option to define the default directory to which the Editor writes temporary files 
and the Editor’s history file. 

The Temp Directory is set, by default, from the TMPDIR environment variable if it is defined. 

Autosave files are written to the Temp Directory. 
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6.15.2.6 General Options: Miscellaneous 

Use the miscellaneous options to set: 

Beep on error Turn this option on if you want an audible beep to sound when the Editor encounters an 
error. 

Same-file check on open 

Use this option to have the Editor check that a file you are opening is not already open. 
You can open multiple copies of the same file, however, the Editor keeps only the last 
version of the file saved. To open multiple copies of the same file, you must specify 
different paths. 

Close rotates forward 

Turn this option on if you want the Editor to rotate forward through the open files when 
you close the current file. 

6.15.3 File Specific Options 

The File Specific Options dialog contains settings that control your file including tabs, tags, line numbers, 
and default file extensions. 



Figure 68. The File Specific Options Dialog 
The settings are divided into five categories: 


• Source 

• Language 

• Tabs 

• Tags 

• Miscellaneous 
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6.15.3.1 File Specific Options: Source 

The source section contains a number of options that allow you to control your source code. 

Read entire file 

Turn this on if you want the Editor to read the entire file when it opens a new file. Turn 
this option off if you want the Editor to load small pieces of the file as needed. 

Check read-only flag 

Turn this option on if you want files that you open to be read only. You cannot change or 
write the files under the same name. 

Ignore Ctrl-Z Turn this option on if you want the Editor to ignore Ctrl-Z as the end of file marker. 

CRLF Autodetect 

Turn this option on if you want the Editor to detect if the file it is opening has CR and LF at 
the end of each line. If it does, it will write the file in the same format. 

Write CRLFs Turn this option on if you want both a CR and an LF at the end of each line. This is the 
standard format for DOS files. 

Use eight-bit characters 

Turn this option on if you want to edit the IBM extended characters, such as line drawing. 

If this option is off, you can edit normal text only. 

6.15.3.2 File Specific Options: Language 

The Editor allows you to highlight different parts of the syntax for the language you are using. This allows 
you to easily find the parts of code you are looking for because they are different colors and/or fonts. The 
Editor highlights lexical elements for C, C++, Fortran, Java and JavaScript, and HTML code (among 
others). 

The Language section also allows you to turn on C Indent Assist. The Editor then uses common C 
formatting conventions such as smart indenting and outdenting with braces. 

6.15.3.3 File Specific Options: Tabs 

Use the tab options to define what the tab key does and the tab amounts. 

Tab amount Set the tab width if real tabs has not been set. Tab amount specifies the number of spaces 
indented by tab key. 

Shiftwidth Set the shiftwidth value. The default is four characters. 

Real Tabs Turn Real Tabs on to use the ASCII tab character instead of spaces when you press TAB. 
Turn this option off to have tabs replaced with the appropriate number of spaces. 

Hard Tabs Set the width of hard tabs. The default is eight characters. 

Autoindent Turn on the Autoindent feature. Each new line then indents to the same level as the 

previous line. 
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6.15.3.4 File Specific Options: Tags 

Use the Tags options to control the file that contains the list of code items in your source files. 

Tag File Enter the name of the tag file that contains your ctags. 

Ignore Case Turn this option on, if you want the tag file to ignore the case of tags. 

Prompt on multiple tags 

Turn this option on, if you want to be prompted when you tag a function that has multiple 
entries in the tags file. 

Tag files are created by the CTAGS utility, which is described in the Open Watcom VI editor 
documentation. 

6.15.3.5 File Specific Options: Miscellaneous 

Use the Miscellaneous options to define the default file extensions for Editor files and to show matching 
brackets. 

Grep extensions 

Define the default file extension to grep when you choose fgrep from the right mouse 
button pop-up menu. 

Show matching brackets 

Turn this option on for the cursor to flash to the opening brace when you type the closing 
brace. 

6.15.4 Screen/Window Options 

Use the Screen and Window Options dialog to define how you move around your screen and what appears 
on it. 



Figure 69. The ScreenAVindow Options Dialog 
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6.15.4.1 Screen/Window Options: Editing 

The Editing section allows you to to define how the text moves around the screen. 

Jumpy Scrolling 

Turn this option on to scroll two lines at a time instead of one. 

Line-based Selection 

Turn this option on to select a whole line no matter where you are in the line when you 
select more than one line. You can still however, select part of one line. If this option is 
off, you can select any part of the first and last line in the block of lines you select. 

Paging Enter the number of lines that you want to overlap when you use the Page Up and Page 

Down keys. 

6.15.4.2 Screen/Window Options: Miscellaneous 

The Miscellaneous options allow you to set the following: 

• Enter your own string to appear at the end of the file. For example, you may want the word END to 
appear at the end of the file. 

• Save the Editor’s screen position when you exit the file. 

• Clear messages after the next key is pressed instead of having them remain until the next error 
message occurs. 

6.15.5 Saving the Configuration 

The Save Configuration menu item will save your current configuration regardless of the status of the 
"Save configuration on exit" setting. The configuration information is saved to a weditor . ini file 
either in the user’s home directory (on multi-user systems) or in the Windows system directory. 
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7.1 Introduction 

Regular expressions are a powerful method of matching strings in your text. Commands that use regular 
expressions are: 

• forward slash (/) command mode key (search forwards) 

• question mark (?) command mode key (search backwards) 

• forward slash (/) command line address (search forwards) 

• question mark (?) command line address (search backwards) 

• substitute command line command 

• global command line command 

• egrep command line command 

• match command line command 

Different characters in a regular expression match different things. A list of all special (or "magical") 
characters is: 

• A backslash (\) followed by a single character other than new line matches that character 

• The caret ( A ) matches the beginning of a line 

• The dollar sign ($) matches the end of a line 

• The dot (.) matches any character 

• A single character that does not have any other special meaning matches that character 

• A string enclosed in brackets [] matches any single character from the string. Ranges of ASCII 
character codes may be abbreviated as in a "a-zO-9". A ] may occur only as the first character of the 
string. You must place a literal - where it cannot be mistaken as a range indicator. If a caret ( A ) 
occurs as the first character inside the brackets, then any characters NOT in the string are matched 

• A regular expression followed by an asterisk (*) matches a sequence of 0 or more matches of the 
regular expression 

• A regular expression followed by a plus sign (+) matches one or more matches of the regular 
expression 
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• A regular expression followed by a question mark (?) matches zero or one matches of the regular 
expression 

• Two regular expressions concatenated match a match of the first followed by a match of the second 

• Two regular expressions separated by an or bar (I) match either a match for the first or a match for 
the second 

• A regular expression enclosed in parentheses matches a match for the regular expression 

• The order of precedence of operators at the same parenthesis level is the following: {}, then *+?, 
then concatenation, then /. 

• All regular expressions following an at sign (@) are treated as case sensitive 

• All regular expressions following a tilde (~) are to be treated as case insensitive 

• If an exclamation point (!) occurs as the first character in a regular expression, it causes the ignoring 
of the magic setting; that is, all magic characters are treated as magical. An exclamation point (!) is 
treated as a regular character if it occurs anywhere but at the very start of the regular expression. 

If a regular expression could match two different parts of the line, it will match the earliest one. If both 
begin in the same place, but match different lengths, or match the same length in different ways, then the 
rules are more complicated. 

In general, the possibilities in a list of branches are considered from left to right, the possibilities for *, +, 
and ? are considered longest first, nested constructs are considered from the outermost in, and concatenated 
constructs are considered leftmost first. The match that is chosen is the one that uses the earliest possibility 
in the first choice that has to be made. If there is more than one choice, the next will be made in the same 
manner (earliest possibility) subject to the decision on the first choice. An so forth. 

For example, (abla)b*c could batch the string abc in one of two ways. The first choice is between ab and a. 
Since ab is earlier in the expression and does lead to a successful overall match, it is chosen. Since the b is 
already spoken for, the b* must match its last possibility since it must respect the earlier choice. 

If there are no I’s present and only one *m, +, or ?, the net effect is that the longest possible match will be 
chosen. So ab presented with xabbbby, will match abbbbb. Note that is ab* is tried against xabyabbbz, it 
will match adjust after x, due to the begins earliest rule. 

7.2 Regular Expression BNF 

A pseudo-BNF for regular expressions is: 
reg-exp {branch}[{branch}l... 

branch {piece} {piece}... 

piece {atom{* or + or ?}} {atom {* or + or ?}}... *—match 0 or more of the atom; H—match 1 

or more of the atom; ?—match a match of the atom, or the null string. 

atom (reg-exp) or range or @ or A or $ or \char or char. 
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range [{ A } char and/or charlo-charhi]. A causes negation of range. 

. Match any character. 

A Match start of line. 

$ Match end of line. 

@ Search with case sensitivity. 

~ Search without case sensitivity. 

/ If it occurs as the first character in a regular expression, the magic setting is ignored; that is, 

all magic characters are treated as magical. ! is treated as a regular character if it occurs 
anywhere but at the very start of the regular expression. 

char Any character. 

\char Forces \char to be accepted as char (no special meaning) except \t matches a tab character if 

realtabs is set. 


7.3 File Matching Regular Expressions 

When specifying a file name in the Editor, it is possible to use a file matching regular expression. This 
expression is similar to a regular expression, but has a couple of differences: 

1. A dot (.) specifies an actual dot in the file name. 

2. An asterisk (*) is the same as .* (matches 0 or more characters). 

3. A question mark (?) is the same as a regular expression dot (.); that is, a question mark matches 
exactly one character. 

4. A caret ( A ) has no meaning. 

5. A dollar sign ($) has no meaning. 

6. The backslash (\) has no meaning. It is used to separate directories. 

Suppose we have the following list of files: 

a. c 
abc. c 
abc 
bed. c 
bad 
xyz. c 

The following examples show how the files from the above list are matched by various file name regular 
expressions. 

a*.c All files that start with a and end in . c . Therefore, it matches a. c and abc. c 

(a\b)*.c All files that start with an a or a b and end in .c. Therefore, it matches a.c, abc.c, and 

bed. c 

*d.c All files that end in d. c . Therefore, it matches bed. c 
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* All files. 

*. * All files that have a dot in them. Therefore, it matches a . c, abc . c, bed. c, xy z . c 

7.4 Replacement Strings 

There are special characters to use in the replacement string if you use regular expressions in the search and 
replace function. 

& Replace each instance of & in the replacement string with the entire string of matched 

characters 

\\ Enter a \ in the replacement string 

\n Replace with a new line 

\f Replace with a tab (if realtabs is set) 

\<n> Replace each instance of < n >, where <n> is a digit from 0 to 9, with the n’th 

sub-expression in the regular expression 

\u Change the next item in the replacement string to upper case 

V Change the next item in the replacement string to lower case 

\U Change all items following \U in the replacement string with upper case, until \e, or \E is 

encountered 

\L Change all items following \L in the replacement string with lower case, until \e, or \E is 

encountered 

\e, \E End the change to upper (\U) or lower case (\L) 

\I<h> Substitute spaces up to column <n>, so that the item that follows occurs at column <n> 

W Substitute the current line number on which the match occurred. 


7.5 Controlling Magic Characters 

By default, all special characters in a regular expression are magical; that is, if a special character is used, it 
has a special meaning. To use a special character, like (, you must escape it (\(). 

However, it is possible to change this using the magic setting in the General Options dialog. If magic is 
turned on, then all special characters are magical. If magic is turned off, then any special characters listed 
in Magic String Edit Control in the General Options dialog lose their special meaning and are treated as 
regular characters. If magic is turned off and you want to use the characters in their magical way, you must 
escape them with a V 
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8 The Open Watcom Resource Editor 

8.1 Introduction 


The Open Watcom Resource Editor is a full-featured editor that enables you to easily create and edit 
resources and the files that contain them. A file containing one or more resources will generally be referred 
to as a resource file. A resource file may be an executable (.EXE), resource file (.RES ), dynamic link 
library (.DLL), bitmap file (.BMP), cursor file (.CUR), or icon file (.ICO). The editor also supports a 
variety of resource scripts. They include dialog (.DLG), accelerator (.ACC), menu (.MNU), and string 
(.STR) scripts. This support is accomplished by maintaining a synchronized resource file (.RES) in the 
same directory as the resource script. Opening a resource file reveals a Resource window in the Resource 
Editor window. This window is a visual representation of the resource file. 

A resource is a piece of data with a specific format that Windows uses to create the visual and interactive 
elements of your application. Most of the visual aspects of Windows applications are the result of the 
application having resources, all of which can be created using the Open Watcom Resource Editor. Use the 
Resource Editor to create and edit the following resource types: 

• Accelerators 

• Bitmaps 

• Cursors 

• Dialogs 

• Icons 

• Menus 

• Strings 

When designing your application’s user interface, the resources are separate from the application’s source 
code. This makes changing the user interface a simple task. Instead of accessing the application’s source 
code, you can make the changes directly to the resources. You can manipulate some aspects of the 
resources, such as the memory flags and resource names, without invoking the resource’s associated editor. 
Invoking the desired editor from the Resource Editor enables you to change all aspects of the selected 
resource. 

Different applications often use the same or similar resources, such as bitmaps, icons, dialogs, and menus. 
The Resource Editor enables you to create resource files for a new application by reusing existing 
resources. Copying a resource from existing applications into the new resource file makes the task of 
creating your user interface quick and simple. 

8.2 Using the Open Watcom Resource Editor 

This section discusses the following topics: 

• Starting the Resource Editor 

• Quitting the Resource Editor 

• The Resource Editor Menu Bar 

• The Resource Editor Toolbar 
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8.2.1 Starting the Resource Editor 

To start the Resource Editor, double click on the Resource Editor icon in your Windows Program Manager. 
The Open Watcom Resource Editor window opens. 



Figure 70. The Open Watcom Resource Editor window acts as a workspace where you work with 
resources. 


8.2.2 Quitting the Resource Editor 

To exit the Resource Editor, choose Exit from the File menu of the Open Watcom Resource Editor window. 
If you made changes to the current file, a message box appears prompting you to save the changes. Select 
Yes to save the file and exit the Resource Editor, No to exit the Resource editor without saving the file, or 
Cancel to return to the Resource editor. 


D:\WATCOM\BINNT\ide.exe 


□ 


A This resource has been modified, 
-i-j Save resource? 


Yes 

No 

Cancel 

l. 




Figure 71. As a safety feature, a message box appears when you select Exit from the File menu without 
saving a modified resource file. 


8.2.3 The Resource Editor Menu Bar 

The menu bar consists of the following five menus: 
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File 

Edit 

Resource 

Window 

Help 


Open a new or existing resource file, save the current resource file, and exit the Resource 
Editor 

Access the clipboard functions, delete the selected resource, and set the Resource Editor 
options 

Open a new resource and work with existing resources 
Customize the Resource Editor workspace 
Access on-line help information 


To see the function of a menu item, hold the mouse button and drag the cursor over the desired menu item. 
A description of the item appears in the status line at the bottom of the screen. If you do not want to select 
the menu item, drag the cursor off of the menu item before releasing the mouse button. 


8.2.4 The Resource Editor Toolbar 


In the Open Watcom Resource Editor window, the toolbar appears below the menu bar. When the toolbar 
is shown, choose Hide Toolbar from the Window menu to hide it. When the toolbar is hidden, you can 
display it by choosing Show Toolbar from the Window menu. 



Figure 72. You can access six Resource Editor functions from the toolbar. 

The following explains the function each toolbar button performs, as well as the equivalent menu item. 

CREATE Create a new resource file. This is equivalent to the New item in the File menu. 

OPEN Open an existing resource file. This is equivalent to the Open item in the File menu. 

SAVE Save the resource file. This is equivalent to the Save item in the File menu. 

CUT Cut the selected resource to the clipboard. This is equivalent to the Cut item in the Edit 

menu. 

COPY Copy the selected resource to the clipboard. This is equivalent to the Copy item in the Edit 

menu. 

PASTE Paste the resource on the clipboard to the specified resource file. This is equivalent to the 

Paste item in the Edit menu. 

To see the function of an item in the toolbar, position your cursor over the desired button. A description of 
the button’s function appears in the status line at the bottom of the window. 
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8.3 Working with Resource Files 

In the Open Watcom Resource Editor, the items in the File menu apply to resource file. These items enable 
you to perform the following functions: 

• Creating a New Resource File 

• Opening an Existing Resource File 

• Saving a Resource File 

8.3.1 Creating a New Resource File with the Resource Editor 

Create a new resource file each time you need a file to hold a collection of resources. You can create the 
resources and add them to the new file or you can copy existing resources from another file and place them 
in the new file. 



Figure 73. Choosing New opens an untitled and empty Resource window into which you can store 
resources. 

To create a new resource file, choose New from the File menu in the Open Watcom Resource Editor 
window. An untitled and empty Resource dialog appears on the screen. From here, you can begin adding 
resources to the resource file. You can also open an existing resource file and copy selected resources to 
the new file. The file remains untitled until you save it and assign it a file name. 

8.3.2 Opening an Existing Resource File with the Resource Editor 

Open an existing resource file to view the resources for that file or perform functions on the file’s 
resources. 
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Figure 74. Choosing Open permits you to access resources in an existing file. 

To open an existing resource file: 

(1) Choose Open from the File menu in the Open Watcom Resource Editor window. 

An Open File dialog appears where you select the file you want to open. 

(2) Double click on the desired file 

or 

Click on the desired file to select it, then click on OK. 

The Open File dialog closes and a Resource dialog for the selected resource file appears in the 
Resource Editor window. This dialog displays a button representing each type of resource that exists 
in the resource file. Clicking on the resource buttons displays a list of the resources of that type in the 
resource file. 

From here, you can perform any of the functions in the section entitled "Working with Resources" on 
page 141. 

8.3.3 Saving a Resource File with the Resource Editor 

There are two menu items that you can use to save resource files with the Resource Editor: 

• Save 

• Save As 
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Important: You can have several resource files open in the Resource Editor window at one time. The 

caption bar of the currently selected resource file appears highlighted. Only this window is 
affected when you choose Save or Save As from the File menu. 


8.3.3.1 Resource Editor: Save 

Choose Save from the File menu in the Open Watcom Resource Editor window to save any changes made 
to the resource file. 

If the file is new and previously unsaved, refer to the section entitled "Resource Editor: Save As". 

After modifying individual resources, you perform an update at the resource level. The resource file and its 
resources are not saved until you select Save from File menu of the Resource Editor. The Resource Editor 
prompts you if you attempt to exit the editor without saving changes. Choose Yes to save the file and exit 
the Resource Editor, No to exit the Resource Editor without saving the file, or Cancel to return to the 
Resource Editor. 

8.3.3.2 Resource Editor: Save As 

To save a resource file to another file: 

(1) Choose Save As from the File menu in the Open Watcom Resource Editor window to save any 
changes made to the resource file. 

A Save File dialog appears where you specify the file to which you want to save the current resource 
file. 

(2) Specify the file to which you are saving by selecting an existing file or entering the name of a new 
file. 

(3) Click on OK when completed. 



Figure 75. A Save File message box appears when you attempt to save the current resource file to an 
existing file. 

The dialog closes and the Resource Editor saves the resource file, returning you to the Resource 
Editor window. 
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Note: If you attempt to save the current resource file to an existing file, a Save File window 

appears informing you that the selected file already exists. Choosing Yes on this 
dialog overwrites the selected existing file with the contents of the current resource 
file. 

The dialog closes and the Resource Editor saves the resource file, returning you to the Resource 
Editor window. 

The dialog closes and the Resource Editor saves the resource file, returning you to the Resource 
Editor window. 


8.4 Working with Resources 

The items in the Edit and Resource menus in the Open Watcom Resource Editor window enables you to 
perform functions on resources within a resource file. To use these functions, a resource file must be open 
in the workspace. This resource file can be empty or can contain existing resources. The functions you can 
perform are: 

• Creating a New Resource 

• Editing an Existing Resource 

• Saving a Resource 

• Using Shortcuts to Create a Resource 

• Deleting a Resource 

• Renaming a Resource 

• Changing Memory and Load Options 

8.4.1 Creating a New Resource 

From the Open Watcom Resource Editor window, you can create any of the following resources: 

• Accelerator 

• Bitmap 

• Cursor 

• Dialog 

• Icon 

• Menu 

• String 

To create a new resource, choose the type of resource from the cascading menu that appears when you 
choose New from the Resource Menu. The editor for the selected resource type appears on the screen on 
top of the Resource Editor window. From here, create the desired resource, referring to the appropriate 
editor section in this guide for more information. 

8.4.2 Editing an Existing Resource 

Front the Resource Editor window, you can select any resource within a resource file and edit it by opening 
the editor with which the resource was created. This makes editing resources efficient as you have access 
to every resource in a resource file and you can invoke the appropriate editor quickly. 
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To edit an existing resource: 

(1) Select the desired resource file on the Resource Editor window by selecting the appropriate 
Resource window. 

This is the resource file whose resource you want to edit. 

(2) Select the resource type by selecting on the appropriate line in the type listbox. 

A list of all resources of the selected type for this resource file appears in the Resource listbox. 



Figure 76. Each resource type contained in the resource file appears in the Types listbox. 

(3) Double click on the resource you want to edit 

or 

Select the desired resource, then choose Edit from the Resource menu 

or 

Select the desired resource, then press ENTER. 

The appropriate editor for the selected resource opens on top of the Resource Editor window. Use this 
editor to make changes to the selected resource. 

(4) Refer to the appropriate editor section in this guide for information on using the editor to edit the 
selected resource. 
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8.4.3 Saving a Resource 

The Save As menu item in the Resource menu enables you to save a resource to a new or existing resource 
file. Saving a resource to an existing resource file replaces the existing resources for that resource file with 
the resource you are saving. You can save only one resource at a time with this function. 

(1) Select the desired resource. 

You can select only one resource at a time and the selected resource appears highlighted. This is the 
resource you want to save to another resource file. 

(2) Choose Save As from the Resource menu. 

A Save Resource dialog appears where you specify the resource file to which you are saving the 
selected resource. 

(3) Specify the file to which you are saving by selecting an existing file or entering the name of a new 
file. 

(4) Click on OK when completed. 

How you proceed from here depends on whether you are saving the resource to a new or existing 
resource file. 

8.4.3.1 Saving to a New Resource File 

Once you enter the name of the new resource file to which you are saving the selected resource and click on 
OK in the Save Resource dialog, the dialog closes. 

8.4.3.2 Saving to an Existing Resource File 

When you choose an existing file from the Save Resource dialog, a Save Resource message box appears on 
the screen. This message box informs you that the selected file already exists and asks if you want to 
replace the existing file. 



Figure 77. A Save File As message box appears when you attempt to save the current resource file to an 
existing file. 
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To cancel the save: 

(1) Choose No 

The Save Resource dialog reappears. 

(2) Select another file to which you can save the selected resource 
or 

Cancel the save function 

The dialog closes and the Resource Editor returns you to the Resource Editor window. 

To replace the existing file: 

(1) Choose Yes to replace the contents of the existing resource file with the selected resource. 

The dialog closes and the Resource Editor saves the resource file, returning you to the Resource 
Editor window. 

84.3.3 Copying Into an Existing Resource File 

The Copy To function enables you to copy the selected resource into an existing resource file. This does 
not remove the resource from its current resource file and it does not delete the resources in the existing 
resource file, as in the Save As function. 

To copy a resource to another resource file: 

(1) Select the desired resource. 

The selected resource appears highlighted in the Resource window. This is the resource you want to 
copy to another resource file. Copying a resource does not remove it from its current resource file. 

(2) Choose Copy To from the Resource menu. 

A Copy Resource Into File dialog appears where you select an existing resource file to which you 
want to copy the selected resource. 
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Figure 78. In the Copy Resource Into File dialog, select the resource file to which you want to copy the 
selected resource. 

(3) Double click on the desired resource file 

or 

Click on the desired resource file to select it, then click on OK. 

The Resource Editor copies the resource to the selected resource file. The dialog closes and you 
return to the Open Watcom Resource Editor window. 

Note: If the resource file to which you copied the selected resource is open on the Resource 

Editor window, the copied resource will not appear. To view the updated resource 
file, simply open that resource file again. The copied resource now appears in the 
Resource window for the resource file. 

8.4.4 Using Shortcuts to Create a Resource 

The Edit menu on the Open Watcom Resource Editor window contains some standard Windows items that 
you can use to quickly create resources. The items are: 

• Cut 

• Copy 

• Paste 

These items allow you to cut or copy selected resources from one resource file, then open a second resource 
file and paste them into it. You can also paste them directly into the appropriate editor. 

Cut 

(1) Select the resource you want to cut to the clipboard. 

The selected resource appears highlighted in the Resource window. 

(2) Choose Cut from the Edit menu of the Resource Editor window. 
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The Resource Editor removes the selected resource from the Resource window and places it on the 
clipboard. 

Refer to Paste in this section for details on pasting information from the clipboard. 

Copy 

(1) Select the resource you want to copy to the clipboard. 

The selected resource appears highlighted in the Resource window. 

(2) Choose Copy from the Edit menu of the Resource Editor window. 

The Resource Editor copies the selected resource to the clipboard. 

Refer to Paste in this section for details on pasting information from the clipboard. 

Paste 

(1) Select the resource file in which you want to paste the resource that is currently on the clipboard. 

(2) Choose Paste from the Edit menu of the Resource Editor window. 

The Resource Editor places the resource from the clipboard into the current resource file in the 
Resource Editor window. 

8.4.5 Deleting a Resource 

The Delete item in the Edit menu enables you to quickly delete resources from a resource file. 

To delete an object from a resource file: 

(1) Select the resource you want to delete from a resource file on the Resource Editor window. 

The selected resource appears highlighted in the Resource window. 

(2) Choose Delete from the Edit menu, 
or 

Press the Delete key on the keyboard. 

A Delete Resource dialog box appears displaying the name of the resource chosen to delete. 
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Delete Resource 


Resource Name: 



\ OK j 


Cancel 


Help 


Figure 79. The Delete Resource dialog prompts you to verify that you want to delete the resource 
indicated. 

(3) Click on OK to delete the selected resource. 

The Delete Resource dialog closes and the Resource Editor removes the selected dialog from the 
Resource window. 

Note: Choosing Cancel on the Delete Resource dialog cancels the deletion and returns you to the 

Resource Editor window. 

8.4.6 Renaming a Resource 

You can change the name of a resource from either the Resource Editor or from the editor in which the 
resource was created. 

To rename a resource: 

(1) Select the resource you want to rename. 

(2) Choose Rename from the Resource menu in the Open Watcom Resource Editor window. 

A Rename Resource dialog appears containing two fields: 

• Old Name 

• New Name 



Figure 80. In the Rename Resource dialog, you enter the new name of the selected resource. 

(3) Enter the new name for the resource in the New Name field. 

(4) Click on OK to close the Rename Resource dialog. 

The dialog closes and the new resource name appears in the Resource window. The Resource Editor 
automatically reorders the resources into alphabetical order. 
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8.4.7 Resource Editor: Changing Memory Options 

The Memory Flags item in the Resource menu of the Resource Editor window enables you to change the 
memory options for the selected resource without opening the editor for that resource. These options 
indicate the memory type and loading instructions for the resource. 

To set the memory options for a resource: 

(1) Select the resource whose memory options you want to change. 

(2) Choose Memory Flags from the Resource menu in the Open Watcom Resource Editor window. 
The Memory Options dialog opens displaying the current memory options for the selected resource. 



Figure 81. In the Memory Options dialog, you change the memory options for the selected resource. 

(3) Select the required flags in the Memory Options and Load Options sections of the dialog by clicking 
on the check box or radio button beside the appropriate field. 

Following is a description of each option. 


Moveable Selecting this option marks this resource to be stored in moveable memory when it is 
loaded by an application. 

Discardable Selecting this option marks this resource to be stored in discardable memory when it 
is loaded by an application. 


Pure When marked as Pure, Windows does not allow the memory into which the resource 

is loaded to be modified. 


Preload All resources marked as Preload are loaded when the application for which the 

resource is created is loaded. 

LoadOnCall Resources marked as LoadOnCall are loaded only when an application issues a call to 
load them. 
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9 The Open Watcom Accelerator Editor 

9.1 Introduction 


The Accelerator Editor enables you to create and edit accelerator items so you can invoke menu items 
without using a mouse. Accelerators define hot keys for menu items in your application. These enhance 
the user interface for more advanced users of the application. 

Accelerators are keyboard equivalents for menu items, such as Ctrl+S or F2. For example, many 
applications associate the accelerator Ctrl+C with the Copy item in the Edit menu. The Windows 
Interface: An Application Design Guide suggests some standard accelerators. 

An accelerator item is made up of a key value, menu item identifier, and flags. These components define 
the key combination the user presses to access the specified menu item. The Accelerator Editor stores the 
accelerator items in an accelerator table. You can have multiple accelerator tables for a resource file. 

The accelerator editor allows you to create new accelerators and edit existing accelerators without having to 
create a resource script or use a resource compiler. Without the accelerator editor, you would have to use 
the resource compiler to add accelerators to your applications. 

9.2 Using the Accelerator Editor 

This section discusses the following topics: 

• Starting the Accelerator Editor 

• Quitting the Accelerator Editor 

• The Accelerator Editor Menu Bar 

• The Accelerator Toolbar 

9.2.1 Starting the Accelerator Editor 

The Accelerator Editor may be invoked in one of two ways. The first involves first starting the Resource 
Editor then starting the Accelerator Editor. The second way the editor may be started is from the Open 
Watcom IDE. 

To start the Accelerator Editor from the Resource Editor, you must first open the Resource Editor. How 
you proceed depends on whether you are opening a new (empty) accelerator table or an existing accelerator 
table. 
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Figure 82. The Accelerator Editor window 


9.2.1.1 Creating a New Accelerator Table 

To create a new accelerator table: 

(1) Double click on the Resource Editor icon in your Windows Program Manager. 

The Open Watcom Resource Editor window opens. 

(2) Open a new or existing resource file. Refer to the chapter entitled "The Open Watcom Resource 
Editor" on page 135 for more information. 

(3) Choose Accelerator from the cascading menu that appears when you choose New from the Resouce 
menu. 

The Open Watcom Accelerator Editor window opens and displays an empty accelerator item list. 


9.2.1.2 Opening an Existing Accelerator Table 

To open an existing accelerator table: 

(1) Double click on the Resource Editor icon in your Windows Program Manager. 

The Open Watcom Resource Editor window opens. 

(2) Open an existing resource file. Refer to the chapter entitled "The Open Watcom Resource Editor" 
on page 135 for more information on the steps involved in opening a resource file. 

The Resource window for the existing resource file displays buttons representing each existing 
resource type. 

(3) Select the accelerator table button to view the existing accelerator tables. 
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or 

Choose Accelerator from the cascading menu that appears when you choose View from the Resource 
menu. 

The Accelerator Resources list appears revealing all accelerator tables in this resource file. 

(4) Double click on the existing accelerator table you want to open, 
or 

Click on the desired accelerator table to select it, then press ENTER 

or 

Click on the desired accelerator table to select it and choose Edit from the Resource menu on the 

Open Watcom Resource Editor window. 

The Open Watcom Accelerator Editor window opens and displays the existing accelerator items for 
the selected accelerator table. 

9.2.2 Quitting the Accelerator Editor 

To exit the Accelerator Editor, choose Exit from the File menu of the Open Watcom Accelerator Editor 
window. 

If you made changes to accelerator items but did not save the information, a message box prompts you to 
save before exiting. Choose Yes to save the changes and exit. No to exit without saving the changes, or 
Cancel to return to the Open Watcom Resource Editor window. 

When you exit the Accelerator Editor, the application remembers the directory in which you last opened or 
saved an accelerator table (not the resource file). The next time you open an accelerator table, the last 
directory accessed appears in the File Selection dialog so you do not have to reenter its path. This feature 
makes the Accelerator Editor more convenient and efficient to use. 
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9.2.3 The Accelerator Editor Menu Bar 



Figure 83. The Accelerator Editor menu bar 


The menu bar consists of the following five menus: 


File 

Edit 


Resource 

Accelerator 

Help 


Clear and save the accelerator table, and exit the Accelerator Editor 

Access the clipboard functions, hide or show the toolbar, and delete an accelerator item 

Rename the accelerator table and change its memory flags 

Insert and edit accelerator items 

Access on-line help information 


To see the function of an item on the menu bar or submenus, hold the mouse button and drag the cursor 
over the desired menu item. A description of the item appears in the status line at the bottom of the screen. 
If you do not want to select the menu item, drag the cursor off of the menu item before releasing the mouse 
button. 


9.2.4 The Accelerator Editor Toolbar 

In the Open Watcom Accelerator Editor window, the toolbar appears below the menu bar. When the 
toolbar is shown choose Hide Toolbar from the Edit menu to hide it. When the toolbar is hidden you can 
display it by choosing Show Toolbar from the Edit menu. 



Figure 84. The Accelerator Editor toolbar 

The following explains the function each toolbar button performs, as well as the equivalent menu item. 
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CLEAR Clear the accelerator table. This is equivalent to the Clear item in the File menu. 

UPDATE Update the resource file with this accelerator table. This is equivalent to the Update item in 
the File menu. 

CUT Cut the current accelerator table to the clipboard. This is equivalent to the Cut item in the 

Edit menu. 

COPY Copy the current accelerator table to the clipboard. This is equivalent to the Copy item in 

the Edit menu. 

PASTE Paste the accelerator table from the clipboard to the current accelerator table. This is 

equivalent to the Paste item in the Edit menu. 

INSERT Insert the new accelerator item into the accelerator table. This is equivalent to the Insert 
New Item item in the Accelerator menu. 

DELETE Delete the selected accelerator item from the accelerator table. This is equivalent to the 
Delete item in the Edit menu. 

KEY VALUE Set the accelerator item’s key value using the keyboard. This is equivalent to the Key 
Value item in the Accelerator menu. 

To see the function of a button on the toolbar, position your cursor over the desired icon. A description of 

the button’s function appears in the status line at the bottom of the window. 

9.3 Using the Accelerator Editor Window 

The Open Watcom Accelerator Editor window contains a menu bar, toolbar, and status line to help you 

create and edit accelerators. The rest of the window, the workspace, is divided into four sections: 

• Resource Name Field 

• Attributes Area 

• Accelerator Item List 

• Action Buttons 
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Figure 85. The Accelerator Editor window contains a menu bar, toolbar, status line, and workspace. 


9.3.1 Accelerator Editor: Resource Name Field 

The Resource Name field in the Open Watcom Accelerator Editor window contains the name of the 
accelerator table currently being edited. A resource file can contain more than one accelerator table, so it is 
important that the resource names for the accelerator tables be unique. The Resource Name field is not case 
sensitive and can hold up to 255 characters. You can enter a textual name, a number or a symbol in this 
field. 

When you create a new accelerator table, the Resource Editor assigns the default name ACCELERATOR_# 
to it, where # is a decimal number starting at one and increasing for each new resource of that type opened. 
You can rename the accelerator table using the Rename item in the Resource menu. 

9.3.2 Accelerator Editor: Attributes Area 

The attributes area provides information about the currently selected accelerator item. You can edit 
accelerator items using only the fields in this area. 



Figure 86. The Accelerator Editor attributes area 
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Accelerator item attributes are displayed in four sections. Following is an explanation of each section. 

Key The Key field contains the key value used to activate the menu item. 

Menu Item ID The two Menu Item ID fields contain: 

• the number of the menu item that is activated by the entry in the Key field. 

• the symbol information for the selected menu item. 

This section indicates if the key value is in ASCII or virtual key. 

An X appears in the check box for the modifiers that are part of the accelerator key value. 
The available modifier keys are: 

•Alt 

• Control 

• Shift 

The option Flash Top-level Menu Item indicates that when the specified key value is used, the Accelerator 
Editor briefly highlights the corresponding menu bar item. 


Key Type 
Modifiers 


9.3.3 Accelerator Editor: Accelerator Item List 

The accelerator item list displays all of the accelerator items in the current accelerator table. Use this list to 
view the attributes of the accelerator items. Select an accelerator item from the list by clicking on it. 

Details of the selected accelerator item appear in the attributes area of the window. 
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Figure 87. The Accelerator Editor item list 


9.3.4 Accelerator Editor: Action Buttons 

The action buttons control how the information in the attributes area is handled by the editor. The Insert 
button will use the contents of the attributes area to create a new entry in the table. The Change button will 
use the contents of the attributes area to modify the current entry in the table. The Reset button will discard 
the contents of the attributes area and reset them to those of the current entry in the table. The Insert button 
is the default button when the ENTER key is pressed and no other button has the focus. 

Insert ~| Change I Reset I 


Figure 88. The Accelerator Editor action buttons 
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9.4 Accelerator Functions 

You can perform several functions with the Accelerator Editor. This section describes the following tasks: 

• Adding a New Accelerator Item 

• Changing an Existing Accelerator Item 

• Deleting Accelerator Items 

• Renaming an Accelerator Table 

• Saving Accelerator Items 

• Using Shortcuts to Create Accelerator Tables 

• Changing Memory Options 

9.4.1 Adding a New Accelerator Item 

The steps for adding a new accelerator item to the accelerator table are the same, regardless of whether the 

accelerator table is empty or already contains accelerator items. 

To add a new accelerator item: 

(1) Position the cursor in the Key field. 

(2) Enter the desired key value that will activate the menu item. 

You can enter a single key, such as a letter or number, or a key sequence. A key sequence may be 
made up of a modifier and a key, such as A k for Ctrl+k. 

(3) Enter a symbol or numeric identifier for the menu item that is activated by the entry in the Key 
field. 

The symbol or numeric identifier you enter here is the identifier associated with the menu item. This 
relationship is defined in the Menu Editor. If you do not know the desired menu item identifier, open 
the appropriate menu and look up the identifier. It is not possible for the Accelerator Editor to get this 
information for you. 

(4) Specify ASCII or Virtual Key in the Key Type section of the window. 

ASCII Keys When the Key Type specified is ASCII, keys you press appear as characters, such as 
a, B, 2, or $. In the Key field, the ASCII characters are surrounded by quotation 
marks. For example, c appears as "c" and Ctrl+C appears as " A C". When using 
ASCII characters as accelerators, you may combine them with the Ctrl key to form 
key sequences, such as Ctrl+X or Ctrl+P. There is no symbol to represent the Shift 
key in ASCII. Applying the Shift key with an ASCII character results in an upper 
case character in the Key field. For example, Shift+d appears as "D". 

Virtual Keys When the Key Type specified is Virtual Key, you enter the standard Windows 

identifier for the desired key. For example, the Windows identifier for the Home key 
is VK_HOME. The header file WINDOWS.H defines these identifiers. To avoid 
looking up these identifiers yourself, use the Key Value function explained in the 
section Editing the Key Value. To specify whether the Alt, Ctrl, or Shift keys must be 
pressed with another key to form a key sequence, mark the appropriate check box in 
the Modifiers section of the attributes area. 
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(5) Select the desired modifiers in the Modifiers section. 

Modifiers are flags indicating keys that you must press in addition to the specified key value to 
activate the menu item. When the ASCII option is selected, the Control and Shift modifiers are not 
available. 

(6) Press the Insert action button 

or 

Choose Insert New Item from the Accelerator menu. 

or 

Select the Insert New Item button on the toolbar. 

The Accelerator Editor adds the new accelerator item to the accelerator table. When accelerator items 
exist in the accelerator table, one item is always selected. Choosing the Insert New Item menu item or 
button positions the new accelerator item directly after the selected accelerator item in the list. 

9.4.2 Changing an Existing Accelerator Item 

You may want to change the key value or the menu item identifier associated with an accelerator item. 

To modify an existing accelerator item: 

(1) Click the accelerator item you want to modify. 

The selected accelerator item appears highlighted in the accelerator item list and the accelerator item 
details appear in the attributes area of the window. 

(2) Enter the new accelerator item details in the attributes area. 

(3) Press the Change action button 

These actions update the selected accelerator item with the modified accelerator item attributes. 

9.4.2.1 Editing the Key Value 

When editing only the key value of an accelerator item, use the Key Value function. With this function, the 
Accelerator Editor looks up the correct virtual key value for the selected key and inserts it into the 
accelerator item list for you. This is a quick way to make accelerator item changes, but it only applies to 
accelerator items whose key type is Virtual Key. 

To use the Key Value function: 

(1) Choose the accelerator table you want to work with from the Resource window on the Open 
Watcom Resource Editor window. 

The Accelerator Editor window appears displaying all of the accelerator items for the selected 
accelerator table. 
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(2) Click on the accelerator item you want to modify. 

The selected accelerator item appears highlighted in the accelerator table and the accelerator item 
details appear in the attributes area of the window. 

(3) Choose Select Key Value from the Accelerator menu 
or 

Select the Key Value button on the toolbar. 

The accelerator table disappears and instructions for using the Key Value function appear in its place. 

(4) Press the desired key on the keyboard. 

This is the key that you want to activate the menu item specified in the Menu Item field. The 
instructions disappear from the window revealing the modified accelerator table. The updated 
accelerator item is still selected. 

(5) Change modifiers, if required. 

9.4.3 Deleting Accelerator Items 

There are two functions you can use to delete accelerator items from the accelerator table: 

• Delete 

• Clear 

The Delete item in the Edit menu deletes the selected accelerator item from the accelerator item list. You 
can delete only one accelerator item at a time with this function. 

The Clear item in the File menu deletes all accelerator items in the current accelerator table. This is a 
powerful function and must be used carefully to avoid accidentally deleting all accelerator items. 

9.4.3.1 Deleting an Accelerator Item 

To delete accelerator items from the current accelerator table one at a time: 

(1) Select the accelerator item you want to delete from the accelerator item list by clicking on it. 

The selected accelerator item is highlighted. 

(2) Choose Delete from the Edit menu 
or 

Select the Delete button from the toolbar. 

The Accelerator Editor removes the selected item from the accelerator item list. 

(3) Choose Update from the File menu to save the accelerator table changes. 
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9A.3.2 Deleting All Accelerator Items 

To delete all accelerator items in the current accelerator table: 

(1) Choose Clear from the File menu 
or 

Select the Clear button from the toolbar. 

A message box appears prompting you to verify that you want to clear all accelerator items from the 
current accelerator table. 

(2) Choose Yes or No to continue. 

Choosing Yes removes all accelerator items from the current accelerator table. The accelerator item 
list is empty. Choosing No cancels the operation. 



Figure 89. Av a safety feature, a message box appears when you choose the Clear function. 

9.4.4 Renaming an Accelerator Table 

When you create an Accelerator Table, the Resource Editor assigns a default name to it. Assign a new 
name to the accelerator table using the Rename function. 

To rename an accelerator table: 

(1) Choose Rename from the Resource menu on the Open Watcom Accelerator Editor window, 
or 

Double click or right click on the Resource Name field. 

A Rename Resource dialog box appears containing two fields: 

• Old Name 

• New Name 
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Figure 90. In the Rename Resource dialog, you enter the new name of the accelerator table. 

(2) Enter the desired accelerator table name in the New Name field. 

(3) Click on OK to close the Rename Resource dialog. 

The dialog closes and the new accelerator table name appears in the Resource Name field. 


9.4.5 Saving Accelerator Items 

There are two functions you can use to save accelerator tables with the Accelerator Editor: 

• Update 

• Save As 

• Copy To 

Each of these options performs a different type of save function. This section describes how to use each 
function. 

9.4.5.1 Accelerator Editor: Update 

After modifying an accelerator item in an accelerator table, choose Update from the File menu on the 
Accelerator Editor window to save the updated accelerator table to the current resource file. This prevents 
the changes from being lost when you exit the Accelerator Editor. 

The Update function updates the resource file only at the resource level. The resource file is not saved until 
you perform a save at the Resource Editor level as well. Exiting the Resource Editor without saving causes 
you to lose the accelerator table changes made. 


9.4.5.2 Accelerator Editor: Save As 

Choose Save As from the File menu on the Accelerator Editor window to save the current accelerator table 
to another resource file. 

If you added any new symbol names (Item ID’s), a Save Symbol Header File dialog appears which allows 
you to create a new header file which includes the newly added symbol names. 
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Figure 91. On the Save Symbol Header File dialog, specify the header file to which you want to save 
symbol ID’s. 

Afterwards, a Save Accelerator Table dialog appears where you specify the resource file to which you want 
to save the current accelerator table. 



Figure 92. On the Save Accelerator Table dialog, specify the resource file to which you want to save the 
accelerator table. 

Important: If the resource file to which you are saving the accelerator table already contains resources, 

the existing resources will be discarded and replaced with the accelerator table you are 
saving. 

9.4.5.3 Accelerator Editor: Copy To 

Choose Copy To from the Resource menu of the Accelerator Editor window to copy the current accelerator 
table into an existing resource file. 

If you added any new symbol names (Item ID’s), a Save Symbol Header File dialog appears which allows 
you to create a new header file which includes the newly added symbol names. 
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Figure 93. On the Save Symbol Header File dialog, specify the header file to which you want to save 
symbol ID’s. 

Afterwards, a Copy To dialog appears where you specify the resource file to which you want to copy the 
current accelerator table. Unlike the Save As function, copying an accelerator table to a resource file adds 
an entry to the list of resources rather than replacing the existing resources with the new entry. 



Figure 94. On the Copy To dialog, specify the resource file to which you want to copy the accelerator 
table. 

9.4.6 Using Shortcuts to Create Accelerator Tables 

The Edit menu on the Open Watcom Accelerator Editor window contains some standard Windows options 
that you can use to quickly create accelerator resources. The options are: 

• Cut 

• Copy 

• Paste 

These options allow you to perform functions on accelerator tables but not on individual accelerators items. 
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Cut Choose Cut from the Edit menu of the Accelerator Editor window to cut the accelerator 

item list from the current accelerator table and place it on the clipboard. 

Copy Choose Copy from the Edit menu of the Accelerator Editor window to copy the accelerator 

item list in the current accelerator table to the clipboard. 

Paste Choose Paste from the Edit menu of the Accelerator Editor window to copy the accelerator 

item list on the clipboard into the current accelerator table. 


9.4.7 Accelerator Editor: Changing Memory Options 

The Memory Flags option allows you to change the selected memory options for the current accelerator 
table. These options indicate the memory type and loading instructions. 

To set the flags for an accelerator table resource: 

(1) Choose Memory Flags from the Resource menu of the Open Watcom Accelerator Editor window. 
The Memory Options dialog opens displaying either the current or default memory options. 



Figure 95. On the Memory Options dialog, you change the memory options for the accelerator table. 

(2) Select the required flags in the Memory Options and Load Options sections of the dialog by clicking 
on the check box beside the field. Following is a description of each option. 


Moveable Selecting this option marks this accelerator table to be stored in moveable memory 
when it is loaded by an application. 

Discardable Selecting this option marks this accelerator table to be stored in discardable memory 
when it is loaded by an application. 


Pure When marked as Pure, Windows will not allow the memory that the accelerator table 

is loaded into to be modified. 


Preload All accelerator tables marked as Preload will be loaded when the application for 

which you are creating the accelerator table is loaded. 

LoadOnCall Accelerator tables marked as LoadOnCall will only be loaded when an application 
issues a call to load them. 


(3) Click on OK when all memory option selections are made. 


A ccelerator Functions 163 




















Resource Editors 


The Memory Options dialog closes returning you to the Accelerator Editor window. 
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10 The Open Watcom Dialog Editor 

10.1 Introduction 


Dialogs are windows that contain controls such as push buttons, check boxes, list boxes, and combo boxes. 
Dialogs are the principle medium for the exchanging of information between the user and the application. 
You include dialogs in your application to prompt the user for information, enable the user to change 
settings, and allow the user to make choices. Dialogs provide the medium through which users and your 
application can communicate with each other. 

The Open Watcom Dialog Editor enables you to create dialogs. With this editor you can design and test 
your dialogs so you can see exactly how they will look and work in your application. 

The Dialog Editor allows you to create a new dialog or modify an existing dialog. When you complete the 
dialog you can save it as a resource script or binary resource file. You can also save your dialog directly to 
an .EXE or .DLL file if you originally loaded that dialog from one of these files. 

10.2 Using the Dialog Editor 

This section discusses the following topics: 

• Starting the Dialog Editor 

• Quitting the Dialog Editor 

• Saving a Resource File with the Dialog Editor 

• The Dialog Editor Menu Bar 

• The Dialog Editor Toolbar 

10.2.1 Starting the Dialog Editor 

The Dialog Editor is a stand-alone application, so you can invoke it without first starting the Resource 
Editor. To start the Dialog Editor, double click on the Dialog Editor icon in your Windows Program 
Manager. An empty Open Watcom Dialog Editor window opens. To create a dialog resource you must 
first open a resource file. You can either open a new or existing resource file. 

How you proceed depends on whether you are opening a new resource file or working with an existing 
resource file. 
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Figure 96. The Dialog Editor window 

10.2.1.1 Opening a New Resource File with the Dialog Editor 

Choose New from the File menu of the Open Watcom Dialog Editor window. 

Default dialog information appears in the editor window of the Dialog Editor window. The Dialog Editor 
window is ready for you to create a new dialog resource. 

10.2.1.2 Opening an Existing Resource File with the Dialog Editor 

(1) Double click on the Dialog Editor icon. 

The Open Watcom Dialog Editor window opens. 

(2) Choose Open from the File menu. 

An Open Dialog Resource dialog appears listing all resource files. 

(3) Double click on the resource file you want to open 

or 

Click on the resource file you want to open to select it, then click on OK. 

A Select Dialog(s) dialog appears listing all of the dialog resources in the selected resource file. You 
can select one, several, or all of the dialog resources in the resource file. All of the dialog resources 
you select will open on the editor window of the Dialog Editor window. 

(4) Double click on the dialog you want to open. 

or 
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Click on the dialogs you want to open to select them, then click on OK. 

The selected dialog(s) appears in the Open Watcom Dialog Editor window in the editor window. 


Select Dialog(s) 



Figure 97. You can select one or more resources to edit 

10.2.2 Quitting the Dialog Editor 

To exit the Dialog Editor, choose Exit from the File menu of the Open Watcom Dialog Editor window. 

When you exit the Dialog Editor, it remembers the size and position of its main window and the position of 
the toolbox. It also remembers whether the toolbar and toolbox were hidden or not. The next time you 
open the Dialog Editor, it will be set up the same way you left it. The Dialog Editor also remembers the 
directory in which you last opened or saved a dialog. This feature makes the Dialog Editor more 
convenient and efficient to use. 

10.2.3 Saving a Resource File with the Dialog Editor 

There are two functions you can use to save resource files with the Dialog Editor: 

• Save 

• Save As 

Important: You can have several resource files open in the Dialog Editor window at one time. The 

caption bar of the currently selected resource file appears highlighted. Only this window is 
affected when you choose Save or Save As from the File menu. 

Note: Save operations will always create a file containing the dialog script(s) (.DLG) and a 

resource file (.RES). 

10.2.3.1 Dialog Editor: Save 

Choose Save from the File menu in the Open Watcom Dialog Editor window to save any changes made to 
the resource file. 

After modifying individual dialog resources, you perform an update at the resource level (the Save item in 
the Dialog menu). The resource file is not saved until you perform a save at the editor level as well, using 
the Save function. The Dialog Editor prompts you if you attempt to exit the editor without saving changes. 
Choose Yes, No, or Cancel to continue. 
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10.2.3.2 Dialog Editor: Save As 

(1) Choose Save As from the File menu in the Open Watcom Dialog Editor window to save any changes 
made to the resource file. 

A Save Resource dialog appears where you specify the file to which you want to save the current 
resource file. 

(2) Specify the file to which you are saving by selecting an existing file or entering the name of a new 
file. 

Note: If you attempt to save the current resource file to an existing resource file, a Save 

Resource message box appears informing you that the selected file already exists. 
Choosing Yes on this dialog overwrites the selected existing resource file with the 
contents of the current resource file. Choosing No returns you to the Save Resource 
dialog. 

(3) Click on OK when completed. 

The dialog closes and the editor saves the resource file, returning you to the Dialog Editor window. 

10.2.4 The Dialog Editor Menu Bar 



Figure 98. The Dialog Editor menu bar 

The menu bar consists of the following five menus: 

File Open and save resource file, load libraries, select custom controls, work with symbols, and 

exit the editor 

Edit Access the clipboard functions, align and size the dialog controls, configure the dialog, and 

delete dialogs 
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Dialog Test, revert, and save the dialog, create a new dialog, copy the dialog to another resource 

file, and set the order, tabs, and groups for dialog controls 

Tools Select the desired tools to use to create the dialog 

Window Manipulate child windows, arrange icons, and hide/show the toolbox and toolbar 
Help Access the on-line help information 

To see the function of an item in the menu bar or submenus, hold the mouse button and drag the cursor over 
the desired menu item. A description of the item appears in the status line at the bottom of the screen. If 
you do not want to select the menu item, drag the cursor off of the menu item before releasing the mouse 
button. 

10.2.5 The Dialog Editor Toolbar 


In the Open Watcom Dialog Editor window, the toolbar appears below the menu bar when the Show 
Toolbar item in the Window menu is enabled. Once enabled, the menu item changes to Hide Toolbar. To 
disable this feature, choose Hide Toolbar from the File menu and the Toolbar disappears. 



Figure 99. The Dialog Editor Toolbar 


The following explains the function each icon performs, as well as the equivalent function in the menu bar. 

Create Create a new resource file. This is equivalent to the item New in the File menu. 

Open Open an existing resource file. This is equivalent to the item Open in the File menu. 

Save Save the current resource file. This is equivalent to the item Save in the File menu. 

Cut Cut the selected object(s) to the clipboard. This is equivalent to the item Cut in the Edit 

menu. 

Copy Copy the selected object(s) to the clipboard. This is equivalent to the item Copy in the Edit 

menu. 

Paste Paste the object(s) on the clipboard to the current resource file. This is equivalent to the 

item Paste in the Edit menu. 

Size Size the selected control to the text within it. This is equivalent to the item Size to Text in 

the Edit menu. 

Test Test the current dialog. This is equivalent to the item Test Mode in the Dialog menu. 

Order Order the controls in the current dialog. This is equivalent to the item Set Order in the 

Dialog menu. 

Set Tab Set tab stops in the current dialog. This is equivalent to the item Set Tabs in the Dialog 

menu. 
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Set Groups Set groups in the current dialog. This is equivalent to the item Set Groups in the Dialog 
menu. 

To see the function of an item in the toolbar, position your cursor over the desired icon. A description of 
the button’s function appears in the status line at the bottom of the window. 

10.2.6 The Dialog Editor Toolbox 

The toolbox allows you to conveniently select the tool you want, without having to access it through the 
Tools menu. Each toolbox button represents an option in the Tools menu. Moving the cursor over the 
toolbox buttons displays the function of the button in the status bar. 



Figure 100. The Dialog Editor toolbox 

10.3 Using the Dialog Editor Window 

The Open Watcom Dialog Editor window contains a menu bar, toolbar, toolbox, and status line. The rest 
of the window is divided into three sections: 

• The Information Bar 

• The Edit Window 

• The Workspace 
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Figure 101. The Dialog Editor window contains a menu bar, toolbar, workspace, and status line. 


10.3.1 The Dialog Editor Information Bar 

The Information Bar is located under the toolbar. It provides information about the currently selected 
object you are adding to the dialog or modifying. This object can be a control or the dialog window itself. 
There are three fields in the Information Bar. The contents of two fields depends on whether the selected 
object is a dialog or a control. You may press F9 to set the keyboard focus to the Information Bar. While 
the Information Bar has the keyboard focus you may press ESCAPE to have the focus return to the Editor. 



Figure 102. The Dialog Editor information bar 


Changes made to these fields are only processed once you press ENTER or click on the Set button. 

Reverse uncommitted changes by clicking on the Discard button. 

Size The Size field in this area contains three sets of numbers. These numbers provide 

information on the size and position of the selected dialog or object in the Edit Window. 
The default number sequence when you create a new dialog is: 

(20, 20) (115, 95) 95x75 

(20, 20) indicates that the top left hand corner of the dialog is at the position 20, 20 on the 
Edit Window grid. 

(115, 95) indicates that the bottom right hand corner of the dialog is at the position 115, 95 
on the Edit Window grid. 

95x75 indicates the width and height of the dialog. 
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10.3.1.1 Dialogs 

Caption When the selected object is a dialog, this field contains the name of the dialog that you 

want to appear on the dialog in the application. Any changes you make to this field are not 
stored until you: 

• Press ENTER, or 

• Select the Set button to the right of the field. 

Dig Name When the selected object is a dialog, this field contains the name of the dialog resource. 

This is the name by which the dialog is stored in the resource file. When you create a new 
dialog, the Dialog Editor assigns the default name DIALOG_# to the new dialog. You 
change the name of the dialog using the Dig Name field. 

To change the dialogs name: 

(1) Type the new dialog name using double quotes if the dialogs name is to be an 
character string. 

or 

Type the symbol name (without double quotes). New symbols will automatically be 
created. 

10.3.1.2 Controls 

Text When the selected object is a control, the Text field contains the text appearing in the 

dialog with the selected object. 
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Figure 103. The information bar text field 


This field is not applicable for all objects. Any changes you make to this field are not 
stored until you: 

• Press ENTER, or 

• Select the Set button to the right of the field 

ID There are two parts to the ID field. The field on the right contains the numeric value of the 

currently selected control. Each control always has a numeric identifier. You may enter a 
symbol here ( new symbols will automatically be created ) or a numeric identifier. 

The symbol is a string used to specify the selected control. This is an alternate way to 
identify the control in your source code. 
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10.3.2 The Edit Window 

The edit window is the window on which you create dialogs and controls. It represents the resource file 
that your dialog is a part of. 



Figure 104. The Dialog Editor edit window 

The edit window gives you space so you can temporarily move controls off your dialog when it gets too 
crowded. For example, to rearrange controls in your dialog, you can drag them onto the edit window and 
then drag them back onto the dialog in the desired order. 

Although you can’t see it on your screen, the edit window is an infinite grid with the origin (0,0) initially at 
its top left. Dialogs are always positioned relative to the edit window. The origin is in the middle of the 
world co-ordinate system, which is the reason the scroll thumbs are initially in the middle of the scroll bars. 

10.3.3 The Workspace 

The workspace is the area under the Information Bar on which you can manipulate several resource files. 
This area can be compared to your desktop. For instance, if you minimize an edit window, an icon 
representing that edit window appears in the workspace. The workspace provides you with an area in 
which to open and close edit windows. 
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Figure 105. The Dialog Editor workspace 

10.4 Dialog Functions 

This section describes the several functions you can perform with the Dialog Editor. The following tasks 
are included in this section: 

• Creating New Dialogs 

• Opening Existing Dialogs 

• Changing the Dialog Size 

• Changing the Location of a Dialog 

• Saving Dialogs 

• Changing the Name of a Dialog 

• Changing the Caption in a Dialog 

• Adding Controls to a Dialog 

• Modifying Controls in a Dialog 

• Ordering Controls in a Dialog 

10.4.1 Creating New Dialogs 

When you open the Dialog Editor, it displays an empty dialog box in the editor window of the Dialog 
Editor window. You can change the size and location of this dialog and add controls to it to meet the needs 
of your application. However, if you are not happy with the changes you have made and want to delete 
your dialog to start over again, or if you want to modify more than one dialog at a time, you can create 
another empty dialog in one of the following ways: 
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(1) Select New from the File menu. 

(2) Select New from the toolbar. 

(3) Draw another dialog in the editor window with the "dialog" item from the toolbox. 

An empty dialog named "Untitled" appears in the editor window. Now you can add controls to the empty 
dialog, and change its size and location within the edit window. 

10.4.2 Opening Existing Dialogs 

You can open a dialog from any .RES, .EXE, or .DLL file to your edit window where you can modify it. 
To do this: 

(1) Open the file you want, in one of the following ways: 

• Select Open from the file menu, or 

• Select the Open button from the toolbar. 

(2) Select the .RES, .EXE, or .DLL file that contains the dialog you want to copy. 

The Open Watcom Dialog Editor Open Resource dialog appears. 

(3) Select the resource file you want. 

(4) Select the name of the file you want, in one of the following ways: 

• Select the name and press OK, or 

• Double click on the name of the file. 

If there are any dialog resources in the file, the Select Dialog appears listing the names of all the 
dialog resources that exist in that resource file. 

Note: If the file does not contain any dialog resources, the main screen appears with an 

empty edit window and dialog for you to add controls and modify. 

(5) Select one or more dialogs to place in the edit window in one of the following ways: 

• Double click on the dialogs you wish to modify, or 

• Select the dialogs you wish to modify and select OK. 

The dialog you copied appears in the edit window of your main screen. From here you can add 
controls to the dialog and modify its size and location. 

10.4.3 Changing the Dialog Size 

To modify the size of a dialog. 
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(1) Select the dialog. 

(2) Position the mouse above the appropriate sizing handle. 

(3) Drag the dialog’s sizing handle until the dialog is the size you want. 

You will notice that the dialog size information in the Information Bar will track the size of the dialog. 

10.4.4 Changing the Location of a Dialog 

Since you will want all parts of your dialog to be visible to your users and grab their attention, you can 
modify the location of your dialog relative to the parent window. To do this: 

(1) Position the mouse either above the dialog caption or within several pixels of the dialog’s border 
(while remaining in the dialog). 

(2) Drag the dialog to the position you want in the edit window. 

You will notice that the dialog size information in the Information Bar will track the location of the dialog. 

10.4.5 Saving Dialogs 

It is a good idea to save changes to your dialog as you modify it rather than wait for the Dialog Editor to 
prompt you when you close your dialog or exit the Dialog Editor. There are five ways to save dialogs. The 
two primary ways to save a dialog are to select one of the following from the file menu: 

• Save 

• Save As 

Selecting Save or Save As from the File menu saves the entire resource file in which your dialog resides, 
updating any changes you made to your dialog in the process. 

In addition, there are three other ways to save your dialog. You can choose Save, Save As, or Copy To 
from the Dialog menu. Saving a dialog from the Dialog menu only saves one resource — the currently 
selected dialog — not the entire resource file which typically contains numerous resources. 

Warning: If you choose to select Save or Save As from the dialog menu you will only be saving the 

current dialog and not any of the other resources in the resource file. If you save the dialog 
under the same name as the resource file, you will overwrite all the resources in that file 
and be left with a resource file that contains nothing more than your dialog. 

10.4.6 Changing the Name of a Dialog 

The name of a dialog is the name associated with the dialog resource when you save it to a dialog resource 
file. 

To avoid name conflicts, (you can’t have two dialog resources with the same name, in the same file) you 
will want to change the name of your dialog (the editor gives you one as a default). Type in the edit field a 
name you want to give your dialog or, if symbols have been loaded, you can select a symbol from the 
combo box. You can drop down the combo list box and select a symbol from there. 
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Figure 106. The combo box is labelled "ID". 


10.4.7 Changing the Caption in a Dialog 

A dialog’s caption is the text that appears in the title bar of the dialog. 

You can type in the edit field of the Information Bar to change the caption’s name. 

10.4.8 Adding Controls to a Dialog 

Select a tool that will allow you to create controls by selecting an item from the Tools menu or from the 
toolbox. 

There are two ways in which controls may be drawn in the dialog. 

Click the left mouse button at the position where you would like the top left corner of the control to 
be. The control will be created in its default size. 

or 

Press the left mouse button and drag out a rectangle. Release the left mouse button. 

The tool box goes back to select mode when you draw a control (the current tool becomes the select tool). 

To draw more than one of the same types of controls without having to choose the control from the toolbar 
or menu every time, choose the sticky tool which causes the tool to stay down. 

10.4.9 Modifying Controls in a Dialog 

Once you have created controls for your dialog you can modify the controls as follows: 

(1) Double-click the control. 

or 

Select the control and Press ENTER. 

A Style dialog box appears. 

Once in the Dialog editor, you can define your dialog box. You can also add, change, group, reorder, 
move, resize, ore delete dialog controls so that your dialog box functions the way you want it to. 
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10.4.10 Ordering Controls in a Dialog 

There is an ordering associated with the controls of a dialog. This ordering is commonly referred to as the 
"tab order" and controls which dialog control is highlighted next when you press the TAB or cursor keys. 
As you add controls to a dialog, they are added to the end of the list. 

The Dialog editor allows you to change this ordering using a simple "point-and-click" technique. To do 
this: 

(1) Select the dialog 

(2) Select Set Order from the Dialog Menu dialog 
or 

Press the Set Order button on the toolbar 

All of the controls in the dialog now have a button at their top-left corner indicating their current 
position. 

(3) Click the dialog controls in order until the ordering is what you would like. 

(4) Select Set Order from the Dialog Menu dialog 
or 

Press the Set Order button on the toolbar 

Reselecting Set Order will terminate the ordering session and record any changes made. 

As you click the dialog controls you will notice two things. First, the buttons at the dialog controls top-left 
take on a "depressed" look. This indicates a button you have already clicked. Second, the unselected or 
unclicked buttons will reorder themselves to reflect any changes you have made so far. This will allow you 
terminate the ordering session without having to click all of the dialogs controls. 

Clicking on a dialog control that is in the "depressed" or selected state will undo the new ordering you have 
given it and it will go back to its original position. If a "depressed" dialog control already has its original 
position then it finds the first available position. This feature is handy if you make a mistake and would 
like to perform a quick fix. 

There may be a point in the ordering process where you decide to start over from the beginning. Instead of 
clicking over all the dialog controls you have previously clicked or leaving and then re-entering the Set 
Order mode you may simply double click the dialog control you wish to be first. This will undo all that 
you have done and make the selected dialog control the first one. 

You may run into a situation where the first n dialog controls are correctly ordered but subsequent one are 
not. Before you begin to click through the first n dialog controls note that there is a better way. Simply 
shift-click the n’th control to accept the current ordering up to that point and proceed. 
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11.1 Introduction to the Image Editor 

If you want to design visual resources such as bitmaps, icons, or cursors and add sizzle to your 
application’s interface, the image editor can help. 

The Image Editor is a visually oriented drawing tool with the power to draw all the visual resources you 
want — exactly the way you picture them. This way, you can design effective bitmaps, meaningful icons, 
and communicative cursors. 

Of course, the Image Editor can help bring to life your new artistic achievements. But it can also copy 
visual images from anything else you can see on your computer screen. For example, if you would like to 
incorporate a favorite bitmap or icon from your desktop or even from another application, you can use the 
Image Editor’s Screen Select option to copy that image to your design grid where you can tailor the image 
to your exact specifications. Then, when you are happy with your visual image, you can save it to an 
executable. 

Most of the sections in this chapter apply to all your visuals, but for more information on the specific type 
of visual you are creating, see the sections specific to creating and editing your specific resource type. 

This chapter contains the following: 

• Opening the Image Editor 

• Closing the Image Editor 

• The Main Screen 

• The Image Editor Menu Bar 

• The Image Editor Toolbar 

• The Image Editor Toolbox 

• The Image Editor Color Palette 

• The Image Editor Status Line 

• Creating and Editing Bitmaps 

• Creating and Editing Cursors 

• Creating and Editing Icons 

11.2 Opening the Image Editor 

To open the Image Editor: 

Double click on the Image Editor icon in your windows program manager, 
or 

Select the Image Editor icon and choose Open from the File menu. 

The Open Watcom Image Editor window appears. 
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11.3 Closing the Image Editor 

To close the Image Editor and return to your desktop: 

Double click on the system menu in the top, left comer of the screen, 
or 

Choose Exit from the File menu. 

When you close the Image Editor, it remembers the size and position of its main window, as well as the 
position of the toolbar and color palette. It also remembers whether the toolbar and color palette were 
hidden or not. This way, when you open the Image Editor again, it is set up the same way you left it. 


11.4 The Main Screen 


Every time you open the Image Editor, the Open Watcom Image Editor window appears. The toolbar, 
toolbox, and color palette you use to edit your images appear on top of this window. 



Figure 107. The Open Watcom Image Editor window 

You cannot draw or copy images onto the screen itself. Instead, you must first create a design grid, a work 
area on which you can design your visuals. You can create an empty design grid and draw your own visual 
or you can create a design grid with an image from your desktop or another application already on it. Once 
you have an image on your design grid you can edit it so it looks exactly the way you want. 
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11.4.1 Creating a Design Grid 

To create a design grid: 

(1) Choose New from the File menu. 

The Image Type dialog box appears. 

(2) Select the type of image you want to create by clicking on either Bitmap, Icon, or Cursor. 

(3) Click on OK. 

A dialog box appears where you specify the image size you want to work with. The Image Editor 
automatically defaults to the standard sizes (in pixels) for bitmaps, icons, and cursors. To create 
different sized images, simply enter the desired pixel width and height. 

(4) Click on OK. 

For more information on creating and editing a bitmaps, cursors or icons, see the sections entitled "Creating 
and Editing Bitmaps" on page 186, "Creating and Editing Icons" on page 188, and "Creating and Editing 
Cursors" on page 187. 

11.5 The Image Editor Menu Bar 

The menu bar along the top of the Image Editor window allows you to access most of the items in the 
toolbar, the toolbox, and the color palette. It also provides you with other items that you cannot access 
anywhere else except on the menu bar. 



Figure 108. The Open Watcom Image Editor menu bar 


To see what an item does, position your cursor over the item and hold the mouse button. A description of 
the item appears in the status line. For more information about the status line, see the section entitled "The 
Image Editor Status Line" on page 186. This manual assumes that you know how to use the menus and are 
familiar with common menu items such as Save As and Undo. 
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Some of the menu items have accelerator keys, also called accelerators, so you can invoke an item without 
having to pull down the menu. This means, for example, that you can start a new image in three ways. 
You can either: 

• Select the new image button from the toolbar, or 

• Choose New from the File menu, or 

• Press F2 (the accelerator for starting a new image). 


11.6 The Image Editor Toolbar 

The toolbar allows you quick and easy access to the most used items in the menus. 
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Figure 109. The Open Watcom Image Editor tool bar 

To find out what a button does, position your cursor over the button and hold the mouse button. A 
description of the button’s function appears in the bottom right comer of your screen. If you only wish to 
read what the button will do and not activate it, drag your cursor onto another part of the window and then 
release the mouse button. 

Here is a list of the buttons from left to right in the toolbar and what they do. 

New Creates a new bitmap, icon, or cursor 

Open Opens an existing file 

Save Saves the current image 

Toggle Grid Allows you to view the exact pixels on your design grid 
Maximize Enlarges the appearance of your image and design grid 
Clear Deletes everything on your design grid 

Snap Bitmap Allows you to select a bitmap image from your desktop or another application and place 
that image on your design grid 

Shift Right Moves the current image to the right 

Shift Left Moves the current image to the left 

Shift Up Moves the current image up 

Shift Down Moves the current image down 

Flip Vertically 

Mirrors the current image along the X-axis 

Flip Horizontally 

Mirrors the current image along the Y-axis 
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Rotate 90 Clockwise 

Rotates the current image 90 degrees clockwise 

Rotate 90 Counter Clockwise 

Rotates the current image 90 degrees counter clockwise 

11.7 The Image Editor Toolbox 

The toolbox allows you to conveniently select and change the tool you are using to edit your image, 
without having to hunt through the menus for the tool you want. 



Figure 110. The Open Watcom Image Editor toolbox 
Here is a list of the tools and what they do. 

Pencil Draws on the grid, pixel by pixel 

Lines Draws straight lines on the grid 

Ellipse Outline 

Draws outlines of circles and ellipses 
Ellipse Fill Draws filled circles and ellipses 

Rectangle Outline 

Draws outlines of rectangles 

Rectangle Fill Draws filled rectangles 

Brush Draws on the grid in various brush sizes 

Select Region Allows you to select a rectangular region on the grid 

Select Hot Spot 

Allows you to select the cursor hot spot (for cursors only) 


The Image Editor Toolbox 183 














Resource Editors 


11.8 The Image Editor Color Palette 

If you want to draw or fill a new visual in different colors, or change the colors of an existing bitmap, icon, 
or cursor, the color palette allows you to select the colors you want. 



Figure 111. The Open Watcom Image Editor color palette 

To select a color: 

(1) Click either the left or right mouse button on the color in the color palette that you wish to assign 
to that button. 

(2) Select a drawing tool. 

(3) Draw or fill holding down the mouse button assigned to the color you want. 

For example, if you want to draw a red line: 

1. Create a design grid for the resource you want 

2. Select a shade of red from the color palette. 

3. Select the line tool from the toolbox. 

4. Drag your cursor across the design grid. 

When you choose one of the 12 colors on the right of the color palette, the draw color will not be the same 
as the fill color. Don’t be alarmed. This is because they are not true VGA colors. The Image Editor 
creates them by dithering two or more colors together so that, while the color appears solid in the view 
window, it is actually made up of different colored pixels intermingled with each other. Since it is 
impossible to represent a single pixel-unit of a dithered color, the draw color always differs from the fill 
color when you select a dithered color. 

11.8.1 Selecting Screen and Inverse Colors 

Unlike simple bitmaps, visuals such as icons and cursors usually require transparent or inverse colors. This 
is so that they don’t entirely obscure everything underneath them and so they can be seen no matter what 
color they happen to be sitting on. 

When you create or edit an icon or cursor, you can choose the screen and inverse colors from the color 
palette. Then, you can draw portions of your icon or cursor with those colors, so that these pixels blend 
into the background of your application. 

Remember, if you want to use a specific color in your icon or cursor, make sure the color you want to use is 
not the screen or inverse color. Reserve these two colors for drawing only the transparent portions of your 
icon or cursor. And use the other 26 colors available in the color palette for regular drawing. 
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To choose a screen color: 

(1) Create a design grid for a cursor or icon. 

(2) Move your cursor over the two squares beside the words Screen and Inverse, so that your cursor 
changes from a pointer to a hand. 

(3) Double click on either square. 

The Select Screen Color dialog appears. 

(4) Select the color you want to use as your screen color. 

(5) Click on OK. 

The dialog closes and the screen color and its inverse are assigned to the screen and inverse boxes in 
the color palette. These will be the Screen and Inverse colors you can use to draw the portions of your 
icon or cursor that you want to be transparent. 

Note: When you select a color, its inverse is automatically selected for you. Try to find a 

screen color and inverse color that you won’t want to use in the foreground of your 
icon or cursor. For example, if you don’t intend to use yellow in your icon, select 
yellow as your screen color. The inverse color, blue, is automatically selected for 
you, so if you intend to use blue in your icon, find another screen color that doesn't 
have blue as its inverse. 

11.8.2 Assigning Colors to Mouse Buttons 

When you are drawing and filling in multiple colors, you may find it useful to assign colors to the left and 
right mouse buttons. This way, you can draw in one color, and quickly switch to another color simply by 
pressing the opposite mouse button. For example, if you find you draw mostly in black and red, assign 
black to the left mouse button and red to the right mouse button. To do this, 

(1) Select the black square by clicking on it with the left mouse button. 

(2) Select the red square by clicking on it with the right mouse button. 

The colors assigned to the mouse buttons appear in the squares of the color palette marked L (for left) 
and R (for right). 

11.8.3 Hiding and Showing the Color Palette 

If you generally only draw in one or two colors or temporarily need more room on your screen, you can 
hide the color palette: 

• Double click on the system menu icon in the corner of the Color Palette, or 

• Choose Show Color Palette from the Options menu. 

To reveal the color palette again, choose Show Color Palette again from the Options menu. 
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11.9 The Image Editor Status Line 

There are five sections in the status line. The first four sections provide information on the current image. 
The fifth section displays hint text for the items in the menus, toolbar, and toolbox when you position your 
cursor over an item and hold down the mouse button. 



Figure 112. The Open Watcom Image Editor status line 

11.10 Creating and Editing Bitmaps 

If you want your applications to have visual impact, you can create and edit bitmaps. Bitmaps are graphical 
images that can be as large as 512 x 512 square pixels representing such things as buttons, brush patterns, 
company logos, toolbar items, wallpaper, and graphical elements in menus. 

Using the Image Editor you can create a new bitmap or you can create a bitmap from any other image on 
your desktop. You can even copy a bitmap from another application on your desktop. 

To create a new bitmap: 

(1) Choose New from the File menu. 

The Image Type dialog appears. 

(2) Select Bitmap. 

(3) Click on OK. 
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The Bitmap Information dialog appears. This dialog prompts you for information about the 
dimensions of the bitmap you want to create and the color scheme you want to work with. The Image 
Editor defaults to the dimensions most commonly used for creating bitmaps, 32 pixels by 32 pixels. 
However, if you want to create a different sized bitmap, enter the pixel width and height you want. 

The Image Editor also defaults to a 256-Color color scheme. Other color schemes available are 
16-Color VGA and 2-Color Monochrome. 

To copy a bitmap from your desktop or from another application on your desktop: 

(1) Choose New from the File menu. 

The Image Type dialog appears. 

(2) Select Bitmap. 

(3) Click on OK. 

The Bitmap Information dialog appears. 

(4) Select the Screen Select button. 

This option allows you to choose the size and contents of the newly created bitmap with images from 
your desktop or from another application sitting on your desktop. The Image Editor ignores the 
limitations specified in the Bitmap Information dialog and uses the dimensions you sweep out (up to 
512x512 pixels). 

(5) Position the cursor at the image you want to select. 

(6) Hold the left mouse button and drag the cursor across the image you want to copy to your design 
grid. 

(7) Release the mouse button. 

The image you selected appears on your design grid. 

11.11 Creating and Editing Cursors 

You can create and edit cursors that communicate to your users the mode or state of the application. 

You can create a new cursor or you can create an empty cursor and copy an image from your desktop or 
another application onto your design grid. From there you can edit your cursor’s appearance and set its hot 
spot. 

When you edit cursors, the Image Editor provides you with an extra tool called Set Hotspot This tool allows 
you to select the exact pixel to which you want to assign the hotspot. The default hotspot is 0,0 (at the top 
left corner of the design grid ). 
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Figure 113. The Set Hotspot tool allows you to select the hotspot 

To create a new cursor: 

(1) Choose New from the File menu. 

The Image Type dialog appears. 

(2) Select Cursor. 

(3) Click on OK. 

The Cursor Format dialog box appears. Since cursors should be standardized, you can only choose 
monochrome cursors 32x32 pixels. You cannot create a colored cursor. 

(4) Click on OK. 

Cursors (and icons, too) differ from bitmaps in that they almost always include pixels that blend into the 
background of your application. Unless you want a rectangular shaped cursor, you must assign special 
screen and inverse colors to the "blending pixels," so that they don’t obscure the areas over which you 
move the cursor. 

Since you can only create black and white cursors, do not use black or white as your screen or inverse 
colors. Instead, use one of the dithered colors as your screen color. The Image Editor automatically 
chooses the inverse of the chosen dithered color. 

For more information on selecting screen and inverse colors, refer to the section entitled "Selecting Screen 
and Inverse Colors" on page 184. 

11.12 Creating and Editing Icons 

With the Image Editor, you can create icons that look exactly the way you want. Icons are usually the 
user’s first exposure to your application, so you want them to be as professional and meaningful as 
possible. 

You can create a new icon or you can create an empty icon design grid and use the Image Editor’s Snap 
Bitmap option to copy an image from your desktop to your design grid where you can edit it as desired. 
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To create a new icon: 

(1) Choose New from the File menu. 

The Image Type dialog appears. 

(2) Select Icon. 

(3) Click on OK. 

The Icon Target dialog box appears. You can create the following types of icons: 

• 16-color 32x32 

• 2-color 32x32 

• 2-color 32x16 

• 16-color 16x16 

• 2-color 16x16 

• 256-color 48x48 

• 16-color 48x48 

• 16-color 24x24 

(4) Select the desired icon type. 

(5) Click on OK. 

The Image Editor window displays an empty icon design grid awaiting your new creation. 

If you want to copy an image from your desktop or from another application sitting on your desktop, select 
the Snap Bitmap option from the toolbar and drag across the image on your desktop that you want to copy. 
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12 The Open Watcom Menu Editor 

12.1 Introduction 


Windows applications typically contain menus that enable users to initiate actions. When users see familiar 
menus in the menu bar, such as the File or Edit menu, they may feel less intimidated by a new application 
and be more apt to explore its capabilities. 

In an application you can have three types of menu items: 

• Standard 

• Popup 

• Separator 

A standard menu item performs a function when selected. A popup menu item is a menu item with a 
sub-menu. Selecting a popup menu reveals another menu list, rather than performing a function. A 
separator is a horizontal line that separates groups of menu items within a popup menu. A resource file can 
have multiple menus. 

The Open Watcom Menu Editor enables you to create new menus and edit existing menus found in 
resource files. A resource file may contain multiple menus. 

With the Menu Editor you can create all of the menus needed for your application visually, without having 
to create a resource script or use a resource compiler. 

12.2 Using the Menu Editor 

This section discusses the following topics: 

• Starting the Menu Editor 

• Quitting the Menu Editor 

• The Menu Editor Menu Bar 

• The Menu Editor Toolbar 

12.2.1 Starting the Menu Editor 

The Menu Editor may be invoked in one of two ways. The first involves first starting the Resource Editor 
then starting the Menu Editor. The second way the editor may be started is from the Open Watcom IDE. 

To start the Menu Editor from the Resource Editor, you must first open the Resource Editor. How you 
proceed depends on whether you are opening a new (empty) menu table or an existing menu table. 
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Figure 114. The Menu Editor window 


12.2.1.1 Creating a New Menu 

(1) Double click on the Resource Editor icon in your Windows Program Manager. 

The Open Watcom Resource Editor window opens. 

(2) Open a new or existing resource file. 

Refer to the chapter entitled "The Open Watcom Resource Editor" on page 135 for more information. 

(3) Choose New from the Resource menu. 

A cascading menu appears from the New menu item. 

(4) Select Menu from the New cascading menu. 

The Open Watcom Menu Editor window opens and displays an empty menu. 


12.2.1.2 Opening an Existing Menu 

(1) Double click on the Resource Editor icon in your Windows Program Manager. 

The Open Watcom Resource Editor window opens. 

(2) Open an existing Resource File. 

Refer to the chapter entitled "The Open Watcom Resource Editor" on page 135 for more information. 
The Resource window for the existing resource file displays buttons representing each existing 
resource type. 

(3) Select the menu button to view the existing menus. 
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or 

Choose Menu from the cascading menu that appears when you choose View from the Resource 
menu. 

The Menu list appears revealing all menus in this resource file. 

(4) Double click on the existing menu you want to open 

or 

Click on the desired menu to select it, then press ENTER or choose Edit from the Resource menu 

on the Open Watcom Resource Editor window. 

The Open Watcom Menu Editor window opens and displays the selected menu. 

12.2.2 Quitting the Menu Editor 

To exit the Menu Editor, choose Exit from the File menu of the Open Watcom Menu Editor window. 

If you made changes to menu items but did not save the information, a message box prompts you to save 
before exiting. Choose Yes to save the changes and exit the Menu Editor, No to exit the Menu Editor 
without saving the changes, or Cancel to return to the Menu Editor. 

When you exit the Menu Editor, the application remembers the directory in which you last opened or saved 
a menu (not the resource file). The next time you open a menu, the last directory accessed appears in the 
File Selection dialog so you do not have to reenter its path. This feature makes the Menu Editor more 
convenient and efficient to use. 

12.2.3 The Menu Editor Menu Bar 
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Figure 115. The Menu Editor menu bar. 


The menu bar consists of the following five menus: 

File Clear and save the menu, and exit the Menu Editor 

Edit Access the clipboard functions, hide or show the toolbar, and delete a menu 

Resource Rename the menu and change its memory flags 
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Menu Insert menu entries 

Help Access on-line help information 

To see the function of an item in the menu bar or submenus, hold the mouse button and drag the cursor over 
the desired menu item. A description of the item appears in the status line at the bottom of the screen. If 
you do not want to select the menu item, drag the cursor off of the menu item before releasing the mouse 
button. 

12.2.4 The Menu Editor Toolbar 

In the Open Watcom Menu Editor window, the toolbar appears below the menu bar. When the toolbar is 
shown choose Hide Toolbar from the Edit menu to hide it. When the toolbar is hidden you can display it 
by choosing Show Toolbar from the Edit menu. 



Figure 116. The Menu Editor toolbar. 

The following explains the function each icon performs, as well as the equivalent function in the menu bar. 

Clear Clear the menu workspace. This is equivalent to Clear in the File menu. 

Save Save the current menu. This is equivalent to Update in the File menu. 

Cut Cut the current menu item to the clipboard. This is equivalent to Cut in the Edit menu. 

Copy Copy the current menu item to the clipboard. This is equivalent to Copy in the Edit menu. 

Paste Paste the menu item that is on the clipboard to the current menu workspace. This is 

equivalent to Paste in the Edit menu. 

Delete Delete the selected menu item from the menu workspace. This is equivalent to Delete in 

the Edit menu. 

Only one of the following two buttons appears at a time. The displayed button indicates where new menu 

items will be inserted. When one is selected the other one replaces it on the toolbar. 

Insert Before When this button is displayed, new menu items will be inserted before the currently 

selected menu item. Selecting this button is equivalent to selecting Insert After from the 
Menu menu. 

Insert After When this button is displayed, new menu items will be inserted after the currently selected 
menu item. Selecting this button is equivalent to selecting Insert Before from the Menu 
menu. 
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Insert This button will insert a new menu item into the menu. This is equivalent to Insert New 

Item in the Menu menu. 

To see the function of an item in the toolbar, position your cursor over the desired button. A description of 
the button’s function appears in the status line at the bottom of the window. 

12.3 Using the Menu Editor Window 

The Open Watcom Menu Editor window contains a menu bar, toolbar, and status line to help you create 
and edit menus. The rest of the window is divided into five sections: 


• Resource Name Field 

• Preview Window 

• Attributes Area 

• Menu Item List 

• Action Buttons 



Figure 117. On the Open Watcom Menu Editor window, you create menus for your application. 


12.3.1 Menu Editor: Resource Name Field 

The Resource Name field in the Open Watcom Menu Editor window contains the name of the menu 
currently being edited. A resource file can contain more than one menu, so it is important that the resource 
names for the menu resources be unique. The Resource Name field is not case sensitive and can hold up to 
255 characters. You can enter a textual name, a number or a symbol in this field. 

When you create a new menu, the Resource Editor assigns the default name MENU_# to it. You can 
rename the menu using the Rename item in the Resource menu. 
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12.3.2 Menu Editor: The Preview Window 

The Preview window appears on the Menu Editor window above the menu item list. This window allows 
you to see how the menu you are creating will look in the application. The popup menu items in the 
preview window are functional so you can test your menu as you create it. 



Figure 118. The preview window allows you to see how the menu will look and work in the application. 

You can use the sample menu that appears in the preview window to test the behaviour of your menu items. 
For example, by selecting top-level menu items in the preview window you can check the positions and 
breaks of your menu items and separators. The preview window allows you to verify that your menus 
cascade properly and that other attributes function properly, including inactive, grayed, and check marked 
menu items. 

12.3.3 Menu Editor: Attributes Area 

The attributes area provides information about the currently selected menu item. You can edit menu items 
using only the fields in this area. 

The attributes area displays menu item details in five sections. Following is an explanation of each section. 

Item Text The Item Text field contains the name of the menu item. Whatever appears in this field 
will appear in the menu. 

An ampersand (&) in front of a letter in this field tells the editor to underscore that letter in 
the menu. This automatically creates a hot key for that menu item. When using the menu, 
pressing AFT plus the underscored letter activates that menu item. 

To specify a tab character, enter \t in this field. All text after \t in the Item Text field will 
be right justified in the menu. 

Item ID The Item ID is the unique numeric identifier for the menu item. In the source code, you 

match the identifier to the function the menu item is to perform. The Item ID applies only 
to normal menu items. Popups and separators do not perform functions, so do not need an 
identifier. 

You can enter any number in the range 0 to 65535 in the Item ID field. Hexadecimal 
values can be entered by prefixing them with Ox. Octal values can be entered by prefixing 
them with zero. 

The two Item ID fields contain: 

• the numeric identifier of the selected menu item 

• the symbol information for the selected menu item. 
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Note: Both Menu Item fields currently contain the same numerical information 

because the Menu Editor does not yet support symbols. 

Item Type The Item Type section of the window indicates whether the selected menu item is a popup, 
normal, or separator menu item. Following is a description of each menu item type. 

Popup A popup menu is a menu item that has a sub-menu. When you select a 

popup menu, another menu appears. 

Normal A normal menu item is an item that performs a function when selected. 

Separator A separator menu item is a horizontal line that separates menu items to 

logically group menu items with similar functions. When a separator is 
selected from the menu item list, the Item Text and Item ID fields are 
always empty because they do not apply to separators. 

Attributes The options in the Attributes section allow you to specify how the selected menu item will 
appear in the menu. Use the check boxes to select the desired menu item characteristic. 
Following is a description of each option. 

Checked When the Checked option is selected, the menu item appears in the menu 
with a check mark beside it. This is a graphic only and does not affect the 
functionality of the menu item. 

Note: Top level menu items cannot be checked. 

Grayed When the Grayed option is selected, the menu item text appears in gray 

instead of black. This option also makes the menu item inactive. 

Inactive When the Inactive option is selected, the menu item appears unchanged in 

the menu. However, this option prevents the menu item from being 
selected. 

Break Styles The options in the Break Styles section control the positioning of the menu items. The 

break styles you choose affects the selected menu item and all menu items that follow that 
item. Following is a description of the available options. 

Help The Help break option positions the selected menu to the far right of the 

menu bar. This option is available only for top-level menus. 

Menu For top-level menu items, the Menu break option begins a new line in the 

menu bar, positioning the selected menu item on the far left. In a popup 
menu, this break option creates a new column, positioning the selected 
menu item at the beginning of the new column. 

Note The Menu option overrides the Menu Bar option. 

Menu Bar For top-level menu items, the Menu Bar break option performs the same 
function as the Menu break option. In a popup menu, the Menu Bar break 
option creates a new column, beginning with the selected menu item and 
places a vertical line between the columns. 
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12.3.4 Menu Editor: Menu Item List 

The menu item list displays the menu items in the current menu. Use this list to view the attributes of the 
menu items listed. Select a menu item from the table by clicking on it. Details of the selected menu item 
appear in the attributes area of the window. 

12.3.5 Menu Editor: Action Buttons 

The action buttons control how the information in the attributes area is handled by the editor. The Insert 
button will use the contents of the attributes area to create a new entry in the menu. The Change button will 
use the contents of the attributes area to modify the current entry in the menu. The « (shift left) button 
will cause the current menu item to become a subitem of its parent. This button is enabled only when the 
current item is the last item in its parent menu. The current item will visually appear to shift left. The » 
(shift right) button will cause the current menu item to become the last subitem of the popup menu 
preceding it. This button is enabled only when the item preceding the current item is a popup menu. The 
current item will visually appear to shift right. The Reset button will discard the contents of the attributes 
area and reset them to those of the current entry in the menu. The Insert button is the default button when 
the ENTER key is pressed and no other button has the focus. 


12.4 Menu Functions 

You can perform several functions with the Menu Editor. This section describes the following tasks: 

• Adding a New Menu Item 

• Changing an Existing Menu Item 

• Deleting Menu Items 

• Renaming a Menu 

• Saving Menu Items 

• Using Shortcuts to Create Menus 

• Changing Memory Options 

12.4.1 Adding a New Menu Item 

The steps for adding a new menu item to a menu are the same, regardless of whether the menu item list is 
empty or already contains menu items. Follow these steps to add a new menu item. 

(1) Enter the text for the menu item in the Item Text field. 

To set one of the letters as a hot key, insert an ampersand (&) directly in front of that letter. The letter 
marked as the hot key key appears underlined in the menu item text. For example, to add the menu 
item Cut with the letter t as its hot key, enter Cu&t in the Item Text field. 

To have text in the menu item appear right justified, enter the code \t in the Item Text field. For 
example, to add the entry Open with the accelerator Ctrl+O right justified, enter 0pen\tCtrl+0 
in the Item Text field. 

(2) Enter a symbol or numeric identifier for the menu item. 
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The identifier in this field is the unique identifier associated with the menu item. You define the 
relationship between the menu item function and this identifier in the source code for your 
application. 

You must enter a value between 0 and 65535 in this field. Hexadecimal values can be entered by 
prefixing them with Ox. Octal values can be entered by prefixing the with zero. 

(3) Select the type of menu item you wish to create 

Use separators in your menus to logically group menu items with similar functions. When adding a 
separator to your menu you do not need to complete the fields in the Attributes Area of the Menu 
Editor window. 

(4) Select the desired attributes for the menu item in the Attributes section of the workspace. 

Refer to the section entitled "Using the Menu Editor Window" on page 195 for a description of each 
attribute. 

(5) Select the desired break styles for the menu item in the Break Styles section of the workspace 

Refer to the section entitled "Using the Menu Editor Window" on page 195 for a description of each 
break style. 

(6) Select Insert Before or Insert After from the Menu menu or the toolbar. 

The toggle button on the toolbar indicates if the new menu item is to be inserted into the menu item 
list before or after the currently selected menu item. In the Menu menu, the Insert After item is 
checked if new menu items will be added after the current item. The Insert Before item is checked if 
new items will be added before the current item. 

(7) Press the Insert action button 

or 

Choose Insert New Item from the Accelerator menu. 

or 

Select the Insert New Item button on the toolbar. 

The new menu item appears in the menu item list and the Preview Menu window. 

12.4.2 Changing an Existing Menu Item 

You may want to change the attributes of a menu item in a menu. 

To change an existing menu item: 

(1) Choose the menu you want to work with from the Resource window on the Open Watcom Resource 
Editor window. 

The Menu Editor window appears displaying all of the menu items for the selected menu. 
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(2) Click the menu item you want to modify. 

The selected menu appears highlighted in the menu item list and the menu item details appear in the 
attributes area of the window. 

(3) Select the field you want to change using the Tab key or the mouse. 

(4) Make the desired menu item changes. 

(5) Press the Change action button 

This updates the selected menu item with the modified menu item details. 

12.4.3 Deleting Menu Items 

There are two functions you can use to delete menu items from the menu item list: 

• Delete 

• Clear 

The Delete function in the Edit menu deletes the selected menu item. You can delete only one menu item 
at a time with this function. Deleting a popup menu item also deletes all of the submenus for that item. 

The Clear function in the File menu deletes all menu items in the current menu. This is a powerful function 
and must be used carefully to avoid accidentally deleting an entire menu item list. 

12.4.3.1 Deleting a Menu Item 

To delete menu items from the current menu one at a time: 

(1) Select the menu item you want to delete from the menu item list by clicking on it. 

The selected menu item is highlighted. 

(2) Choose Delete from the Edit menu 
or 

Select the Delete button from the toolbar. 

The Menu Editor removes the selected menu item from the menu item list. 

(3) Choose Update from the File menu to save the menu changes. 

12.4.3.2 Deleting All Menu Items 

To delete all menu items in the current menu: 
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(1) Choose Clear from the File menu 
or 

Select the Clear button from the toolbar. 

A message box appears prompting you to verify that you want to clear all of the menu items from the 
current menu. 

(2) Choose Yes or No to continue. 

Choosing Yes removes all menu items from the current menu. The menu item left list is empty. 



Figure 119. As a safety feature, a message box appears when you choose the Clear function. 

12.4.4 Renaming a Menu 

When you create a menu, the Resource Editor assigns a default name to it. Assign a new name to the menu 
using the Rename menu item. 

(1) Choose Rename from the Resource menu on the Open Watcom Menu Editor window, 
or 

Double click or right click on the Resource Name field. 

A Rename Resource dialog box appears containing two fields: 

• Old Name 

• New Name 



Figure 120. In the Rename Resource dialog, you enter the new name of the menu. 

(2) Enter the desired menu name in the New Name field. 

(3) Click on OK to close the Rename Resource dialog. 
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The dialog closes and the new menu name appears in the Resource Name field. 

12.4.5 Saving Menu Items 

There are three functions you can use to save menus with the Menu Editor: 

• Update 

• Save As 

• Copy To 

Each of these options performs a different type of save function. This section describes how to use each 
function. 

12.4.5.1 Menu Editor: Update 

After modifying a menu item in a menu, choose Update from the File menu on the Menu Editor window to 
save the updated menu to the current resource file. This prevents the changes from being lost when you 
exit the Menu Editor. 

The Update function updates the resource file only at the resource level. The resource file is not saved until 
you perform a save at the Resource Editor level as well. Exiting the Resource Editor without saving causes 
you to lose any the menu changes made. 


12.4.5.2 Menu Editor: Save As 

Choose Save As from the File menu on the Menu Editor window to save the current menu to another 
resource file. A Save Menu dialog appears where you specify the resource file to which you want to save 
the current menu. 



Figure 121. 


On the Save Menu dialog, specify the resource file to which you want to save the menu. 


Important: If the resource file to which you are saving the menu already contains resources, the 

existing resources will be discarded and replaced with the menu you are saving. 
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12.4.5.3 Menu Editor: Copy To 

Choose Copy To from the Resource menu on the Menu Editor window to copy the current menu item list 
into an existing resource file. A Copy To dialog appears where you specify the resource file to which you 
want to copy the current menu item list. Unlike the Save As function, copying a menu item list to a 
resource file adds an entry to the list of resources rather than replacing the existing resources with the new 
entry. 



Figure 122. On the Copy To dialog, specify the resource file to which you want to copy the menu item list. 

12.4.6 Using Shortcuts to Create menus 

The Edit menu on the Open Watcom Menu Editor window contains some standard Windows options that 
you can use to quickly create menu resources. The options are: 

• Cut 

• Copy 

• Paste 

These options allow you to perform functions on menus but not on individual menu items. 

Cut Choose Cut from the Edit menu of the Menu Editor window to cut the menu item list from 

the current menu and paste it to the clipboard. 

Copy Choose Copy from the Edit menu of the Menu Editor window to copy the menu item list 

from the current menu to the clipboard. 

Paste Choose Paste from the Edit menu of the Menu Editor window to copy the menu on the 

clipboard into the current menu item list. 

12.4.7 Menu Editor: Changing Memory Options 

The Memory Flags option allows you to change the selected memory options for the current menu. These 
options indicate the memory type and loading instructions. 
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To set the flags for a menu resource: 

(1) Choose Memory Flags from the Resource menu of the Open Watcom Menu Editor window. 

The Memory Options dialog opens displaying either the current or default memory options. 

(2) Select the required flags in the Memory Options and Load Options sections of the dialog by clicking 

on the check box beside the field. Following is a description of each option. 

Moveable Selecting this option marks this menu to be stored in moveable memory when it is 
loaded by an application. 

Discardable Selecting this option marks this menu to be stored in discardable memory when it is 
loaded by an application. 

Pure When marked as Pure, Windows will not allow the memory that the menu is loaded 

into to be modified. 

Preload All menus marked as Preload will be loaded when the application for which you are 

creating the menu is loaded. 

LoadOnCall Menus marked as LoadOnCall will be loaded when an application issues a call to load 
them. 

(3) Click on OK when all memory option selections are made. 

The Memory Options dialog closes returning you to the Menu Editor window. 
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13 The Open Watcom String Editor 


13.1 Introduction 

To group together text strings in your application, you can use string tables. A string table is a list of 
strings such as error messages, prompts, and other text you want your application to display. Each string in 
the string table has a unique number, called an identifier, associated with it. When the application presents 
the user with a message, it searches for the appropriate identifier and displays the associated string, 
regardless of the textual content of the string. 

The Open Watcom String Editor enables you to create string tables for your application. The String Editor 
stores these tables in the resource file. You can have multiple string tables in a resource file, which allows 
you to logically group the text strings for your application. Since a string table is simply another Windows 
resource that is separate from the source code, you can use the String Editor to do such things as translate 
your strings into another language or make your strings more concise without having to change the source 
code. 


13.2 Using the String Editor 

This section discusses the following topics: 

• Starting the String Editor 

• Quitting the String Editor 

• The String Editor Menu Bar 

• The String Editor Toolbar 

13.2.1 Starting the String Editor 

The String Editor may be invoked in one of two ways. The first involves first starting the Resource Editor 
then starting the String Editor. The second way the editor may be started is from the Open Watcom IDE. 

To start the String Editor from the Resource Editor, you must first open the Resource Editor. How you 
proceed depends on whether you are opening a new (empty) string table or an existing string table. The 
String Editor works on resources found in resource files. 
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Figure 123. The String Editor window 

13.2.1.1 Creating a New String Table 

To create a new string table: 

(1) Double click on the Resource Editor icon in your Windows Program Manager. 

The Open Watcom Resource Editor window opens. 

(2) Open a new or existing resource file. 

Refer to the chapter entitled "The Open Watcom Resource Editor" on page 135 for more information. 

(3) Choose New from the Resource menu. 

A cascading menu appears from the New menu item. 

(4) Choose String from the New cascading menu. 

The Open Watcom String Editor window opens which contains an empty Strings list. 

13.2.1.2 Opening an Existing String Table 

To edit the contents of an existing string table: 

(1) Double click on the Resource Editor icon in your Windows Program Manager. 

The Open Watcom Resource Editor window opens. 

(2) Open an existing resource file. 
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Refer to the chapter entitled "The Open Watcom Resource Editor" on page 135 for more information. 
The Resource window for the existing resource file displays buttons representing each existing 
resource type. 

(3) Select the string table button to view all existing string tables, 
or 

Choose Menu from the cascading menu that appears when you choose View from the Resource 
menu. 

The String Tables list appears revealing all string tables in this resource file. 

(4) Double click on the existing string table you want to open. 

or 

Click on the desired string table to select it, then choose Edit from the Resource menu on the 

Open Watcom Resource Editor window. 

The Open Watcom String Editor window opens and displays the existing string items for the selected 
string table. 

13.2.2 Quitting the String Editor 

To exit the String Editor, choose Exit from the File menu of the Open Watcom String Editor window. 

If you made changes to strings but did not save the information, a message box prompts you to save before 
exiting. Choose Yes to save the changes and exit the String Editor, No to exit the String Editor without 
saving the changes, or Cancel to return to the String Editor. 

When you exit the String Editor, the application remembers the directory in which you last opened or saved 
a string table (not the resource file). The next time you open a string table, the last directory accessed 
appears in the File Selection dialog so you do not have to reenter its path. This feature makes the String 
Editor more convenient and efficient to use. 

13.2.3 The String Editor Menu Bar 



Figure 124. The String Editor menu bar 


The menu bar consists of the following five menus: 


Using the String Editor 207 




















Resource Editors 


File Clear and save the string table, and exit the String Editor 

Edit Access the clipboard functions, hide or show the toolbar, and delete a string item 

Resource Change the string table memory flags and copy it into another resource file 
String Insert a new string item 

Help Access on-line help information 

To see the function of an item in the menu bar, position your cursor over the item and hold down the mouse 
button. A description of the item appears in the status line at the bottom of the screen. If you do not want 
to select the menu item, drag the cursor off of the menu item before releasing the mouse button. 


13.2.4 The String Editor Toolbar 

In the Open Watcom String Editor window, the toolbar appears below the menu bar. When the toolbar is 
shown choose Hide Toolbar from the Edit menu to hide it. When the toolbar is hidden you can display it 
by choosing Show Toolbar from the Edit menu. 



Figure 125. You can access seven String Editor functions from the toolbar. 

The following explains the function each toolbar button performs, as well as the equivalent menu item. 

Clear Clear the string table. This is equivalent to the item Clear in the File menu. 

Update Update the resource file with this string table. This is equivalent to the item Update in the 

File menu. 

Cut Cut the current string table to the clipboard. This is equivalent to the item Cut in the Edit 

menu. 

Copy Copy the current string table to the clipboard. This is equivalent to the item Copy in the 

Edit menu. 

Paste Paste the string table from the clipboard to the current string table. This is equivalent to the 

item Paste in the Edit menu. 

Insert Insert the new string item into the string table. This is equivalent to the item Insert New 

Item in the Strings menu. 

Delete Delete the selected string item from the string table. This is equivalent to the item Delete in 

the Edit menu. 

To see the function of an item in the toolbar, position your cursor over the desired button. A description of 

the button’s function appears in the status line at the bottom of the window. 
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13.3 Using the String Editor Window 

The Open Watcom String Editor window contains a menu bar, toolbar, and status line to help you create 
and edit string items. The rest of the window, the workspace, is divided into four sections: 

• String Text Field 

• String ID Field 

• Action Buttons 

• Strings Fist 



Figure 126. The String Editor window contains a menu bar, toolbar, workspace, and status line. 

13.3.1 String Text Field 

The String Text field in the Open Watcom String Editor window contains the text for the string item you 
are defining. Whatever appears in this field will appear in your application. 

13.3.2 String ID Field 

The two String ID fields contains: 

• the identifier associated with the string item 

• the symbol information for the specified string 

Creating a string item automatically creates a relationship between the string item and its identifier, the 
String ID. In your source code you reference the string item by its String ID. 
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Note: Both String ID fields currently contain the same numerical information because the String 

Editor does not yet support symbols. 

13.3.3 String Editor: Action Buttons 

The action buttons control how the information in the attributes area is handled by the editor. The Insert 
button will use the contents of the attributes area to create a new entry in the string table. The Change 
button will use the contents of the attributes area to modify the current entry in the string table. The Reset 
button will discard the contents of the attributes area and reset them to those of the current entry in the 
string table. The Insert button is the default button when the ENTER key is pressed and no other button has 
the focus. 

13.3.4 Strings List 

The Strings list displays all of the string items in the current string table. The string items appear in 
ascending numerical order by String ID. 

13.4 String Functions 

You can perform several functions with the String Editor. This section describes the following tasks: 

• Adding a New String Item 

• Changing an Existing String Item 

• Deleting String Items 

• Saving String Items 

• Using Shortcuts to Create String Tables 

• Changing Memory Options 

13.4.1 Adding a New String Item 

The steps for adding a new string item to the Strings list are the same, regardless of whether the Strings list 
is empty or already contains string items. 

To add a new string item: 

(1) Enter the text that you want to appear in the application in the String Text Field of the Open Watcom 
String Editor window. 

The text that will be displayed in your application appears exactly as you enter it in this field. 

(2) Enter symbol or numeric identifier fo the string. 

The identifier you enter here is associated with the string item. This is the identifier by which your 
source code references the string. 

(3) Press the Insert action button 

or 
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Choose Insert New Item from the Strings menu, 
or 

Select the Insert New Item button on the toolbar. 

The String Editor adds the new string item to the Strings list. The editor automatically arranges the 
strings in order by String ID. 

13.4.2 Changing an Existing String Item 

You may want to change the text or identifier for a string item in the Strings list. 

To modify an existing sting table item: 

(1) Choose the string table you want to work with from the Resource window on the Open Watcom 
Resource Editor window. 

The String Editor window appears displaying all of the string items for the selected string table. 

(2) Click on the string item from the Strings list that you want to modify. 

The selected string item appears highlighted in the Strings list. 

(3) Change the String Item or String ID field. 

(4) Press the Change action button 

These actions update the selected string item with the modified string item details. 

13.4.3 Deleting String Items 

These are two functions you can use to delete string items from the Strings list: 

• Delete 

• Clear 

The Delete item in the Edit menu deletes the selected string item. You can delete only one string item at a 
time with this function. 

The Clear item in the File menu deletes all string items in the current string table. This is a powerful 
function and must be used carefully to avoid accidentally deleting an entire String list. 

13.4.3.1 Deleting a String Item 

To delete string items from the current string table one at a time: 
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(1) Select the string item you want to delete from the Strings table by clicking on it. 

The selected string item is highlighted. 

(2) Choose Delete from the Edit menu 
or 

Select the Delete button from the toolbar. 

The String Editor removes the selected string item from the Strings list. 

(3) Choose Update from the File menu to save the string table changes. 

13.4.3.2 Deleting All String Items 

To delete all string items in the current string table: 

(1) Choose Clear from the File menu 
or 

Select the Clear button on the toolbar. 

A message box appears prompting you to verify that you want to clear all of the string items from the 
current string table. 

(2) Choose Yes, No, or Cancel to continue. 

Choosing Yes removes all string items from the current string table. The Strings list is left empty. 



Figure 127. As a safety feature, a message box appears when you choose the Clear function. 

13.4.4 Saving String Items 

There are three functions you can use to save string tables with the String Editor: 

• Update 

• Save As 

• Copy To 

Each of these options performs a different type of save function. This section describes how to use each 
function. 
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13.4.4.1 String Editor: Update 

After modifying a string item in a string table, choose Update from the File menu on the String Editor 
window to save the updated string table to the current resource file. This prevents the changes from being 
lost when you exit the String Editor. 

The Update function updates the resource file only at the resource level. The resource file is not saved until 
you perform a save at the Resource Editor level as well. Exiting the Resource Editor without saving causes 
you to lose the string table changes made. 

13.4.4.2 String Editor: Save As 

Choose Save As from the File menu on the String Editor window to save the current string table to another 
resource file. A Save Menu dialog appears where you specify the resource file to which you want to save 
the current string table. 



Figure 128. On the Save Menu dialog, specify the resource file to which you want to save the string table. 

Important: If the resource file to which you are saving the string table already contains resources, the 

existing resources will be discarded and replaced with the string table you are saving. 

13.4.4.3 String Editor: Copy To 

Choose Copy To from the Resource menu on the String Editor window to copy the current string table into 
an existing resource file. A Copy To dialog appears where you specify the resource file to which you want 
to copy the current string table. Unlike the Save As function, copying a string table to a resource file adds 
an entry to the list of resources rather than replacing the existing resources with the new entry. 
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Figure 129. On the Copy To dialog, specify the resource file to which you want to copy the String list. 

13.4.5 Using Shortcuts to Create String Tables 

The Edit menu on the Open Watcom String Editor window contains some standard Windows options that 
you can use to quickly create string tables. The options are: 

• Cut 

• Copy 

• Paste 

These options allow you to perform functions on a string table but not on individual string items. 

Cut Choose Cut from the Edit menu of the String Editor window to cut the Strings list from the 

current string table and paste it to the clipboard. 

Copy Choose Copy from the Edit menu of the String Editor window to copy the String list in the 

current string table to the clipboard. 

Paste Choose Paste from the Edit menu of the String Editor window to copy the string table on 

the clipboard into the current String list. 

13.4.6 String Editor: Changing Memory Options 

The Memory Flags option allows you to change the selected memory options for the current string table. 
These options indicate the memory type and loading instructions. 
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Figure 130. Changing memory options 


To set the memory flags for a string table: 

(1) Choose Memory Flags from the Resource menu of the Open Watcom String Editor window. 

The Memory Options dialog opens displaying either the current or default memory options. 

(2) Select the required flags in the Memory Options and Load Options sections of the dialog by clicking 
on the check box beside the field. 

Following is a description of each option. 

Moveable Selecting this option marks this string table to be stored in moveable memory when it 
is loaded by an application. 

Discardable Selecting this option marks this string table to be stored in discardable memory when 
it is loaded by an application. 


Pure 


Preload 


When marked as Pure, Windows will not allow the memory that the string table is 
loaded into to be modified. 

All string tables marked as Preload will be loaded when the application for which you 
are creating the string table is loaded. 


LoadOnCall String tables marked as LoadOnCall will be loaded only when an application issues a 
call to load them. 

(3) Click on OK when all memory option selects are made. 

The Memory Options dialog closes returning you to the String Editor window. 


String Functions 215 















Resource Editors 


216 String Functions 




Resource Compiler 



Resource Compiler 


218 




14 The Open Watcom Resource Compiler 

14.1 Introduction 


The Open Watcom Resource Compiler (WRC) performs two functions. It converts human readable 
resource script files (usually with the extension ".RC") into machine readable resource files (usually with 
the extension ".RES"). We call this process pass one. The Open Watcom Resource Compiler then 
combines this ".RES" file with an existing executable file or dynamic link library. We call this process pass 
two. Pass two may also be run without a ".RES" file to set flags or to produce a fastload section. 

The Open Watcom Resource Compiler can process Winl6, Win32 and OS/2 resources. 

The Open Watcom Resource Compiler command line syntax is the following. 


WRC {options} input-filename {options} {output-filename] {options} 


The square brackets [ ] denote items which are optional. 

WRC is the name of the Open Watcom Resource Compiler. 

input-filename 

The filename specification of the resource file to compile. 

If no extension is specified for input-filename, then the extension "rc" is assumed. If the 
period (.) is specified but not the extension, the file is assumed to have no file extension. 

output-filename 

The filename specification for the output of the compilation. 

The meaning of this filename and its default extension is dependent on the actions being 
performed. See the section entitled "Using the Open Watcom Resource Compiler" on page 
225 for information on this. 

options A list of valid options, each preceded by a slash (/) or a dash (-). 

Options may be specified in any order. 

Options: Description: 

-? print this help summary 

-q operate quietly 

-30 mark file as requiring Windows 3.0 

-31 mark file as requiring Windows 3.1 (default) 

-dNAME=value behave as if # define NAME value was at top of file 
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-ad 


-bt=<target> 


-c=name 

-e 

-fe=name 

-fo=name 

-fr=name 

-i=path 

-k 

-1 

-m 

-P 


-s{0,l,2} 


-t 


-vl 

-v2 

-x 

-zk{0,l,2,3} 


-zku8 

-zm 

-zn 


generate auto dependency information for use by the Open Watcom 
Make utility 

build target is one of the following: 

windows build a Winl6 resource file (default for the DOS-hosted 
resource compiler) 

nt build a Win32 resource file (default for the 

Win32-hosted resource compiler) 

os2 build an OS/2 resource file (default for the OS/2-hosted 

resource compiler) 
set the code page conversion file 
for a DLL, global memory above EMS line 
set the output EXE file to name 
set the output RES file to name 
specify an additional input RES file, 
look in path for include files 
don't sort segments (same as /sO) 
program uses LIM 3.2 EMS directly 
each instance of program has its own EMS bank 
private DLL 
only build the RES file 
segment and resource sorting method: 

0: no sorting, leave segments in the linker order 

1: move preload segments to front and mark for fast load 

if possible 

2: (default) move preload, data, and non-discardable 

segments to front and mark for fast load if possible 
protected mode only 

verbose: print tokens as they are scanned 
verbose: print grammar rules as they are reduced 
verbose: print both tokens and grammar rules 
ignore the INCLUDE environment variable 
double-byte character support: 

0: (default) Kanji 

1: Chinese/Taiwanese (for Windows only) 

2: Korean (for Windows only) 

3: Simplified Chinese (for Windows only) 

Unicode UTF-8 character support 
output Microsoft/IBM format . RES files 
don't preprocess the file 


14.2 Resource Definition Files 


A resource definition file (".RC" file) lists all resources that your application will use. You should refer to 
your Windows 3.x, Win32 or OS/2 programmer’s documentation for information on the script language 
used in resource definition files. 
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14.2.1 Sample .RC file 

The following example is the resource script file from an application called Life: 


Example: 

#include "windows.h" 

#include "life.h" 

ABOUTBOX DIALOG LOADONCALL MOVEABLE DISCARDABLE 7, 15, 

147, 87 

CAPTION "About Life" 

STYLE WS_ BORDER | WS_ CAPTION | WS_ DLGFRAME | WS_ SYSMENU | 

DS_ MODALFRAME | WS_ POPUP 

BEGIN 

CONTROL "Open Watcom Life Program for Windows", -1, "static", 
SS_ CENTER I WS_ GROUP | WS_ CHILD, 0, 5, 144, 8 
CONTROL "Version 1.0", -1, "static", SS_ CENTER | WS_ GROUP 
| WS_ CHILD, 0, 14, 144, 8 

CONTROL "OK", 1, "button", BS_ DEFPUSHBUTTON | WS_ GROUP 

| WS_ TABSTOP I WS_ CHILD, 55, 64, 32, 14 
CONTROL "Lifelcon", -1, "static", SS_ ICON | WS_ CHILD, 

58, 28, 27, 22 

END 

CellBitMap BITMAP cell.bmp 
MenuBitMap BITMAP menu.bmp 

Lifelcon ICON life.ico 


LifeMenu MENU 
BEGIN 

POPUP "&File" 

BEGIN 

MENUITEM "&Save Selected Region MENU_ SAVE 

MENUITEM "&Load New Pattern MENU_ LOAD 

MENUITEM SEPARATOR 

MENUITEM "&About Life MENU_ ABOUT 

END 

POPUP "SBoundary" 

BEGIN 

MENU ITEM "&Wrap Around", MENU_ WRAP_ AROUND 
MENU ITEM "&Bounded Edges", MENU_ BOUNDED_ EDGES 

END 

END 


The two #include statements for . h files are used to include definitions necessary to compile the resource 
file. The windows . h header file contains general definitions for Windows, and the life.h header file 
contains definitions specific to the LIFE application. 

The DIALOG statement defines the "ABOUT" dialog box used by the LIFE application. 

The two BITMAP statements define a pair of bitmap resources found in the files cell, bmp and 
menu. bmp. The bitmaps are identified by the names CellBitMap and MenuBitMap respectively. 

The ICON statement defines an icon resource found in the file life . ico . The icon is identified by the 
name Lifelcon. 

The MENU statement defines the various menu items that are in the menu, and what identifiers are sent to 
the application when the menu item is selected. 
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14.2.2 Differences from IBM Resource Compiler 

Open Watcom Resource Compiler is largely compatible with IBM’s OS/2 Resource Compiler, but there are 
some differences. 

Octal constants Open Watcom Resource Compiler recogizes octal constants such as 007, 056 etc. Hence 
values such as 008 are considered to be an error. This is consistent with IBM’s RC version 
5 and also consistent with the C/C++ language. In resource files that need to be portable 
between RC versions, do not use octal constants and strip all leading zeros. 

Expression parsing There are differences in parsing statements such as 

Example: 

♦ define IDR_ ACCEL 1 

ICON IDR_ ACCEL -1, 8, 40, 0, 0 

Older versions of IBM RC consider ’IDR_ACCEL’ and ’-1’ to be separate tokens while 
Open Watcom Resource Compiler considers them to be a single arithmetic expression. 

This is consistent with IBM’s RC version 5. The correct and unambiguous syntax is as 
follows: 

Example: 

ICON IDR_ ACCEL, -1, 8, 40, 0, 0 

Binary resource files Using the -zm switch. Open Watcom Resource Compiler produces resource files 

compatible with those that IBM RC produces, however, the files are not always identical. 

In particular the ordering of dialog data within binary resource files is not always the same 
between Open Watcom Resource Compiler and IBM RC. This has no effect on the 
semantics of such resource files. 


14.3 Resource Compiler Options 

Options: Description: 

-? Displays a summary of Open Watcom Resource Compiler command line options. 

-q Causes the Open Watcom Resource Compiler to operate quietly. No text is displayed as 

the Open Watcom Resource Compiler runs except for warning and error messages. 

-30 Marks the executable file as being able to run on Windows 3.0 or Windows 3.1. By 

default, WRC marks the executable file as able to run on Windows 3.1 only. This option 
affects pass two only. 

-31 Marks the executable file as being able to run on Windows 3.1 only. This is the default 

setting. This option affects pass two only. 

-ad Allows the use of the WMAKE .AUTODEPEND directive with your . RES files. If you do 

the first and second passes separately and use this option, you should specify it for both 
passes. This option may not be used with the -zm switch. 

-DNAME=value 

Defines a macro NAME. This is the same as adding the line 
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-bt=<target> 


-e 

-fe=name 

-fo=name 

-fr=name 

-i=path 

-k 

-1 

-m 

-P 

-r 

-s{0,l,2} 


♦define NAME value 

to the top of your resouce script file. If value is not specified then a compiler generated 
value is provided. This option affects pass one only. 

This is the build target directive. It is used to specify whether you are building a resource 
file for Winl6, Win32 or OS/2. The target may be one of the following: 

windows build a Winl6 resource file (default for the DOS-hosted resource compiler) 

nt build a Win32 resource file (default for the Win32-hosted resource 

compiler) 

os2 build an OS/2 resource file (default for the OS/2-hosted resource compiler) 

This option affects pass one only. During pass two the target is inferred from the format of 
the input files. 

Specifies that global memory is above the EMS line in a Windows 3.0 DLL. This option 
has no effect with Windows 3.1, Win32 or OS/2. This option affects pass two only. 

Specifies a new name for the resulting executable file after the resources are added to the 
executable. 

Specifies the name of the output resource file (default is the name of the . RC file with a 
. RES extension). The option affects pass one only. 

Specifies the name of an additional input resource file. The option affects pass one only. 
This option may be specified multiple times. 

Specifies an include path. This include path is searched before the directories specified in 
the INCLUDE environment variable. This option affects pass one only. 

Disables the segment sorting feature (load optimization). If this option is not specified, the 
Open Watcom Resource Compiler arranges all pre-load segments and resources so that they 
are at the start of the executable. This option has no effect on Win32 or OS/2. This option 
affects pass two only. 

Mark the application as using LIM 3.2 EMS directly. This option has no effect with 
Windows 3.1, Win32 or OS/2. This option affects pass two only. 

Each instance of the application has its own EMS bank, when Windows is running with 
EMS 4.0 (by default, all instances share the same EMS bank). This option has no effect 
with Windows 3.1, Win32 or OS/2. This option affects pass two only. 

Mark a dynamic link library as a private DLL that is called by only one application. This 
option has no effect with Windows 3.1, Win32 or OS/2. This option affects pass two only. 

Only build the . RES file. This option is used when you do not want to add the compiled 
resources to the executable file. It prevents pass two from being performed. 

Specifies the segment and resource sorting method. Possible settings are: 
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0: No sorting, leave segments in the linker order. 

1: Move preload segments to front and mark for fast load if possible. 

2: Move preload, data, and non-discardable segments to front and mark for 

fast load if possible (the default). 

This option has no effect with Win32 or OS/2. This option affects pass two only. 

-t Marks the application as able to run in a protected-mode Windows environment (standard 

mode or enhanced mode) only. This option has no effect with Windows 3.1, Win32 or 
OS/2. This option affects pass two only. 

-v This is a debugging option. It causes WRC to print tokens as they are scanned during pass 

one. 

-vl This is a debugging option. It causes WRC to print grammar rules as they are reduced 

during pass one. 

-v2 This is a debugging option. It causes WRC to print both tokens and grammar rules while 

pass one is performed. 

-x This option causes WRC to ignore the INCLUDE environment variable. Normally, the 

Open Watcom Resource Compiler searches the directories specified in the INCLUDE 
environment variable for files specified in a #include directive in the . RC file. This option 
affects pass one only. 

-zk{0,l,2,3} Strings contained in resources in the . RC file are assumed to contain double byte characters 
from the appropriate character sets. Although these options allow strings to contain 
multi-byte characters the names of resources in the resource script file must contain only 
standard ASCII characters in the range 0-127 (inclusive). This option affects pass one 
only. Possible settings are: 

0: (default) Kanji 

1: Chinese/Taiwanese (for Windows only) 

2: Korean (for Windows only) 

3: Simplified Chinese (for Windows only) 

-zku8 Unicode UTF-8 character support 

-zm This option causes WRC to output a Microsoft/IBM format . RES file. This is useful when 

using a dialog editor or other resource tool that understands Microsoft or IBM . RES files. 
This option affects pass one only. This option may not be specified when creating a .RES 
file for Win32 (i.e., when the -bt=nt switch has been specified). 

-zn WRC will not pre-process the . RC file if this option is specified. This option affects pass 

one only. 
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14.4 Using the Open Watcom Resource Compiler 

The command WRC is used to start the Open Watcom Resource Compiler. The Open Watcom Resource 
Compiler may be used in a number of different ways: 

• To compile a resource definition file and add the resulting resources to the executable. 

WRC is used as follows to accomplish this: 

wrc [options] resource-definition-file [executable-file] 

The resource-definition-file must not have the extension ".RES", ".EXE", ".SCR", ".DLL" or 
".DRV". If no extension is specified for the executable-file then ".EXE" is assumed. If 
executable-file is specified without an extension but is terminated with a period (".") then the default 
extension is not added. If the executable-file is not specified then its value defaults to the filename 
specified for the resource-definition-file with its extension changed to ".EXE". 

Example: 

wrc life.rc 

• To compile resources separately. 

This causes the Open Watcom Resource Compiler to create a .RES file only. WRC is used as 
follows to accomplish this: 

wrc -r [options] resource-definition-file [output-file] 

The resource-definition-file must not have the extension ".RES", ".EXE", ".SCR", ".DLL" or 
".DRV". If no extension is specified for the output-file then ".RES" is assumed. If output-file is 
specified without an extension but is terminated with a period (".") then the default extension is not 
added. If the output-file is not specified then its value defaults to the filename specified for the 
resource-definition-file with its extension changed to ".RES". 

Example: 

wrc -r -bt=nt life.rc 

• To add a compiled resource file to an executable file. 

WRC is used as follows to accomplish this: 

wrc [options] resource-file [executable-file] 

The resource-file must have the extension ".RES". The defaults for the executable-file parameter are 
the same as in the case of compiling a resource definition file and adding the results to an executable. 

Example: 

wrc life.res 

• To add multiple compiled resource files to an executable file. 

WRC is used as follows to accomplish this: 

wrc [options] res-file [executable-file] -fr=res-file-2 ... 
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The resource files must have the extension ".RES". The defaults for the executable-file parameter are 
the same as in the case of compiling a resource definition file and adding the results to an executable. 

Example: 

wrc life.res life.exe -fr wave.res 
• To compile an application that does not have a resource file. 

This is useful if you wish to set the Windows 3.x or Win32 version number, or sort load the segments 
(Windows 3.x), or use any of the other executable modifying features of Open Watcom Resource 
Compiler. WRC is used as follows to accomplish this: 

wrc [options] executable-file 

The file specified for executable-file specified must have a ".EXE", ".SCR", ".DLL" or ".DRV" 
extension. 

Example: 

wrc -30 life.exe 


14.5 Warning and Error Messages 

This section describes the various warning and error messages that may be issued by the Open Watcom 
Resource Compiler. 

Read Errors Messages concerning "read errors" indicate than an error occurred while the Open Watcom 
Resource Compiler was reading the specified file. The reason, if present, indicates the type 
of error. The message may indicate the type of file that was being read, such as a bitmap or 
icon. If the message says ’temporary file’ then the file is one created by the Open Watcom 
Resource Compiler for use while it is running. This is not a file specified by the user. 

Write Errors Messages concerning "write errors" indicate than an error occurred while the Open Watcom 
Resource Compiler was writing to the specified file. The reason, if present, indicates the 
type of error. The message may indicate the type of file that was being written, such as a 
bitmap or icon. If the message says "temporary file" then the file is one created by the 
Open Watcom Resource Compiler for use while it is running. This is not a file specified by 
the user. 

6 Unable to open file "<file>": <reason>. 

The Open Watcom Resource Compiler was unable to open the specified file for the 
specified reason. 

7 Error renaming temporary file "<file>" to "<file>": <reason> 

When creating an executable or resource file the Open Watcom Resource Compiler first 
writes the information to a temporary file then renames that file. This messages indicates 
that an error occurred while renaming the specified temporary file. 
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8 "<file> " is not a valid icon file. 

The file specified in an ICON statement is either not a valid icon file or is corrupted. You 
can do two things: 

• Try recreating the file 

• Make sure the correct file is specified 

9 "<file> " is not a valid cursor file. 

The file specified in a CURSOR statement is either not a valid cursor file or is corrupted. 
You can do two things: 

• Try recreating the file 

• Make sure the correct file is specified 

10 "<file> " is not a valid bitmap file. 

The file specified in a BITMAP statement is either not a valid bitmap file or is a corrupted. 
You can do two things: 

• Try recreating the file 

• Make sure the correct file is specified 

11 Trying to add a Winl6 or OS/2 RES file "<file>" to a Win32 executable "<file>". 

This error occurs when you attempt to run pass two of the Open Watcom Resource 
Compiler with a Winl6 or OS/2 . RES file and a Win32 executable file. You can do two 
things: 

• Recreate the . RES file using the -bt=nt switch 

• Make sure the correct file is specified. 

12 Trying to add a Win32 or OS/2 RES file "<file>" to a Winl6 executable "<file>". 

This error occurs when you attempt to run pass two of the Open Watcom Resource 
Compiler with a Win32 or OS/2 . RES file and a Winl6 executable file. You can do two 
things: 

• Recreate the . RES file using the -bt=windows switch 

• Make sure the correct file is specified. 

13 Object alignment increase required. Relink with larger object alignment. 

Each Win32 executable file contains an object alignment value that determines the 
maximum size of the file. This error indicates that in adding resources to a Win32 
executable, the size of the executable increased enough that its object alignment must be 
increased. The solution is to re-link the executable file with a larger object alignment. 
(Refer to the Open Watcom Linker OBJALIGN option) then run the Open Watcom 
Resource Compiler again. 
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14 EXE contained old resources that could not be removed. 

The Win32 executable that the Open Watcom Resource Compiler is operating on already 
contains resources that the compiler cannot remove. As a result, the produced executable 
will be larger than it needs to be but it will still work. The recommended solution is to 
relink the EXE and run the Open Watcom Resource Compiler again. This is a warning 
only. 

15 Error reading EXEfile "<file>": <reason>. 

Refer to the notes on Read Errors at the start of this section. 

16 Error reading file "<file>": Unexpected end of file. 

Refer to the notes on Read Errors at the start of this section. 

This message probably indicates that the given file is corrupt. Try regenerating the file. 

17 Error writing to "<file>": <reason>. 

Refer to the notes on Write Errors at the start of this section. 

18 Error reading icon file "<file>": <reason>. 

Refer to the notes on Read Errors at the start of this section. 

19 Error reading cursor file "<file>": <reason>. 

Refer to the notes on Read Errors at the start of this section. 

20 Error reading bitmap file "<file>": <reason>. 

Refer to the notes on Read Errors at the start of this section. 

21 Error reading font file "<file>": <reason>. 

Refer to the notes on Read Errors at the start of this section. 

22 Error reading data file "<file>": <reason>. 

Refer to the notes on Read Errors at the start of this section. 

23 Error reading RES file "<file>": <reason>. 

Refer to the notes on Read Errors at the start of this section. 
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24 Error reading temporary file "<file>": <reason>. 

Refer to the notes on Read Errors at the start of this section. 

25 Error writing to temporary file "<file>": <reason>. 

Refer to the notes on Write Errors at the start of this section. 

26 Unable to open temporary file "<file>": <reason>. 

The Open Watcom Resource Compiler is unable to create a temporary file that is needed to 
perform the specified task. The reason gives an explanation of why the operation failed. 

27 Error reading from file "<file>": <reason>. 

Refer to the notes on Read Errors at the start of this section. 

28 Unable to read RES file "<file>": wrong version. 

The Open Watcom Resource Compiler is unable to read the specified . RES file because its 
version is incompatible with this version of the compiler. The solution is to recreate the 
. RES file using this version of the Open Watcom Resource Compiler 

29 "<file> " is not a valid RES file. 

This error occurs if the specified file is not a valid RES file. You can do two things: 

• Regenerate the . RES file. 

• Make sure the correct file is specified. 

30 Internal compiler error <internal_error_num>. 

This message indicates that an unexpected error occurred within the Open Watcom 
Resource Compiler . Report any occurrence of this message to Open Watcom Technical 
Support. 

31 Error writing resources to temporary file "<file> <resource>. 

Refer to the notes on Write Errors at the start of this section. 

32 Error while closing file "<file>" or flushing buffers to it: <reason>. 

This indicates an error occurred while closing or writing to the given file. 

33 Error while closing temporary file "<file>" or flushing buffers to it: <reason>. 

This indicates an error occurred while closing or writing to the given file. The given file 
was a temporary file created by the Open Watcom Resource Compiler for its use while it is 
running. 
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35 RCINCLUDE keyword not currently supported. Use #include. 

This message indicates the rcinclude keyword was used and it is not supported. The 
solution is to convert rcinclude statements to #include statements in the following manner: 
convert RCINCLUDE f oo . h to #include "foo.h" 

36 <src_char> ’ is not valid at this point. 

This message indicates that a syntactic error occurred while parsing a resource script file. 

37 String may not cross newline boundary. 

While compiling a . RC file a string literal was encountered that did not have a closing 
quotation before the end of the line it was on. For example, 

"this string 

would cause the error, while 

"this one would not" 

38 Expecting ’ <expected_str> ’ but found ’<src_char> ’ 

This message indicates that a syntactic error occurred while parsing a resource script file. 

39 Too many arguments: <extra_name> 

This error occurs when more than two filenames are specified on the command line. 

40 Filename required on command line. 

This message indicates that no filename was specified on the command line. 

41 Unknown option ’<option>’ 

This error occurs when the stated option is specified on the command line but is not a valid 
Open Watcom Resource Compiler option. 

42 No options specified after options character. 

This error occurs when the character / or - is specified on the command line with no option 
specified after it. 

43 Out of memory 

The Open Watcom Resource Compiler does not have enough memory to complete the 
requested operation. 
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44 No type given for accelerator <source_num> 

This error is reported when the Open Watcom Resource Compiler encounters a definition 
for a character or virtual-key accelerator that lacks a type. 

45 Keyword <accel_type> ignored for type ASCII accelerator <source_num> 

This error occurs when the keyword specified by <accel_type> is specified for an ASCII 
accelerator. This keyword is not valid for ASCII accelerators and will be ignored. 

46 Duplicate resource: <resource_name> 

This error occurs when more than one resource with the same name, type, and language is 
encountered in a . RC file. Only the first resource encountered is properly included in the 
. RES file. This is a warning only. 

47 Internal parser error. 

This indicates that a syntactic error occurred while parsing a resource script file. 

49 Syntax error near "<src_str>" 

This indicates that a syntactic error occurred while parsing a resource script file. 

50 <source_num> is a duplicate string identifier. 

This message indicates that more than one string table string is defined with the given 
numeric identifier. Numeric identifiers for strings in string tables must be unique. 

51 Raw data item <source_num> is too big. Max <max_num> 

This message indicates that the given value is specified as an element of an RCDATA 
resource and is greater than the largest allowable value for an RCDATA resource element. 

52 Raw data item <source_num> is too small. Min <max_num> 

This message indicates that the given value is specified as an element of an RCDATA 
resource and is less than the least allowable value for an RCDATA resource element. 

53 Font name must be a number. 

This error occurs when an ASCII string is used as a name for a FONT resource. Font 
resource names must be numeric. 

54 Can’t Jtinclude more than <max_num> levels. 

There is a limit on the number of levels deep you can nest #include statements. 
<max_num> specifies the maximum number of levels of nesting allowed. This message 
occurs when a file contains more levels of nesting than are allowed. 
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55 Unknown preprocessor directive 

This error occurs when a command that is not a valid preprocessor directive is prefixed by 
a #. 

56 Invalid Mine directive 

This error is reported when a #line directive is encountered in a resource script file but the 
parameters after it are not valid. 

57 Unknown option ’<option>’ 

This error is reported when a command line option is specified that the Open Watcom 
Resource Compiler does not understand. 

58 "<file> " is not a valid EXE file. 

This error occurs when the Open Watcom Resource Compiler expects the given file to be 
an EXE file but it is either not an EXE file or it is a corrupted EXE file. You can do two 
things: 

• Make sure the correct file is specified. 

• Regenerate the EXE file by relinking. 

59 Unable to produce fastload section. 

This error occurs when the Open Watcom Resource Compiler is unable to create a fastload 
section in the given EXE because one of the segments in the EXE is larger than 64K. This 
message is only a warning; a working executable including resources is still produced. 

This message does not appear if the -k option is used. 

60 Can’t find file "<file>". 

This message indicates that the Open Watcom Resource Compiler is unable to locate an 
input file needed to complete the operation. This file may be one of the files specified on 
the command line or one included in the . RC file by a statement such as ICON, BITMAP, 
RCDATA, or CURSOR. You can do two things: 

• For files specified on the command line, make sure the file was specified correctly 
and that it exists in the current directory or in the specified directory if a path for it is 
given on the command line. 

• For files included by a . RC file statement, make sure the file is specified correctly 
and exists in the current directory or a directory specified by the INCLUDE 
environment variable. 

61 Unknown target OS: ’<os> ’ 

This message indicates that on the Open Watcom Resource Compiler command line the 
-bt=<os> option is specified and the compiler does not recognize the specified <os>. The 
valid values for <os> are windows, nt and os2. 
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62 <preproc_msg> 

This indicates an error occurred while preprocessing a . RC file. The text of the message 
contains information about the error. 

63 Keyword "<keyword> " is only valid for Win32. 

While creating a non-Win32 . RES file, the Open Watcom Resource Compiler encountered 
a keyword that is only valid for Win32. 

64 Keyword "<keyword> " not currently being supported. 

A keyword was used in a . RC file that is not supported by the Open Watcom Resource 
Compiler 

65 Resource strings not found. 

This message indicates that your copy of the Open Watcom Resource Compiler has been 
corrupted. Try reinstalling the compiler from your original installation disks. If this fails, 
report the problem to Open Watcom Technical Support. 

66 Error can’t find character translation file "<file>". 

Character translation files are data files that the Open Watcom Resource Compiler uses 
when creating a Win32 . RES file to convert text into UNICODE. This message indicates 
that the Open Watcom Resource Compiler cannot locate the given translation file that it 
requires. The solution is to find the file and make sure it is in your path. 

67 Error opening character translation file "<file>": <reason>. 

Character translation files are data files that the Open Watcom Resource Compiler uses 
when creating a Win32 . RES file to convert text into UNICODE. This message indicates 
that the Open Watcom Resource Compiler found the character translation file but was 
unable to access it for the given reason. 

68 Error reading character translation file "<file>": <reason>. 

Refer to the notes on Read Errors at the start of this section. 

69 "<file> " is not a valid character translation file. 

Character translation files are data files that the Open Watcom Resource Compiler uses 
when creating a Win32 . RES file to convert text into UNICODE. This error occurs when 
the Open Watcom Resource Compiler finds a file with the same name as the expected 
character translation file but this file is either not a character translation file or is a 
corrupted character translation file. You can do two things: 

• Find the correct character translation file (the one that came with this version of the 
Open Watcom Resource Compiler) and put it in a directory that appears in your path 
before any other directory that contains a file of that name. 

• Try reinstalling the file from your original distribution disks. 
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70 Unable to read character translation file "<file>": wrong version. 

Character translation files are data files that the Open Watcom Resource Compiler uses 
when creating a Win32 . RES file to convert text into UNICODE. This error occurs when 
the Open Watcom Resource Compiler finds a file with the same name as the expected 
character translation file but is unable to read it because its version is incompatible with this 
version of the compiler. You can do two things: 

• Find the correct character translation file (the one that came with this version of the 
Open Watcom Resource Compiler) and put it in a directory that appears in your path 
before any other directory that contains a file of that name. 

• Try reinstalling the file from your original distribution disks. 

71 Option ’<option> ’ not valid for a Win32 .RES file. 

This indicates that while producing a Win32 . RES file, a command line parameter was 
specified that is not valid for Win32 . RES files. 

72 L"..." construct is not valid for Winl6. 

This error occurs when the user enters a string prefixed by the letter (i.e. L"Bob") in an 
. RC file being turned into a Winl6 . RES file. The L specifier is meaningless for Winl6 
and will be ignored. This is a warning only. 

73 Options ’<option> ’ and ’<option> ’ may not be specified together. 

This error occurs when two options specified on the command line are not compatible with 
one another. You should remove one of the specified options. 

74 Environment variable ’<var> ’ is not set. 

An environment variable specified on the command line using the @ option had no value 
set for it. 

76 MENUITEM must have ID value. 

A MENUITEM in a MENU resource must contain a menu id. This message is issued when 
a MENUITEM in a menu resource does not have a menu id specified for it. 

Example: 

mymenu MENU 
BEGIN 

MENUITEM "my item" 

END 

Menu items in menuex resources do not need a menu id. 
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77 Id/Type/State/Helpld not allowed for MENU POPUP controls. 

A POPUP statement in a MENU resource may not be followed by any modifiers (such as 
an ID). This message is issued when a POPUP statement in a MENU resource is followed 
by one or more modifiers. 

Example: 

mymenu MENU 
BEGIN 

POPUP "my popup", MY_ ID 

END 

POPUP statements in menuex resources may be followed by modifiers. 

78 MENUITEM options are not allowed for MENUEX POPUP controls. 

A POPUP statement in a MENUEX resource may not use optional modifiers such as 
CHECKED or GREYED. This message is issued when a POPUP statement in a MENUEX 
resource contains one of these optional modifiers. In a MENUEX resource these modifiers 
are replaced by MFT_* and MFS_* flags. 

79 Type/State not valid for MENU MENUITEM controls. 

A MENUITEM statement in MENU resource must not specify state and type information 
using the MFT_* or MFS_* flags. This message is issued when type or state information is 
specified for a MENUITEM in a MENU resource. 

Example: 

mymenu MENU 
BEGIN 

MENUITEM "item", MY_ ID, MFT_ STRING, MFS_ GREYED 

END 

In a MENU resource this information is specified using option modifiers such as GREYED 
or CHECKED. 

80 MENUITEM options not valid for MENUEX MENUITEM controls. 

A MENUITEM statement in a MENUEX resource may not use optional modifiers such as 
CHECKED or GREYED. This message is issued when a MENUITEM statement in a 
MENUEX resource contains one of these optional modifiers. In a MENUEX resource 
these modifiers are replaced by MFT_* and MFS_* flags. 

81 HELP ID not valid for DIALOG. 

You may not specify a help id for a DIALOG resource. This message is issued when a help 
id is found with a DIALOG resource. 
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Example: 

my_ dig DIALOG 0, 0, 100, 100, MY_ HELPID 
A help id may be specified for a DIALOGEX resource. 

82 Font Italic setting not allowed for DIALOG. 

You may not specify an italic font for a DIALOG resource. This message is issued when 
the italic flag has been specified in a FONT statement in a DIALOG resource. 

Example: 

my_ dig DIALOG 0, 0, 100, 100 
FONT "helvetica", 8, FW_ BOLD, 1 

The italic flag may be specified for DIALOGEX resources. 

83 Font Weight setting not allowed for DIALOG. 

You may not specify a font weight for a DIALOG resource. This message is issued when a 
font weight has been specified in a FONT statement in a DIALOG resource. 

Example: 

my_ dig DIALOG 0, 0, 100, 100 
FONT "helvetica", 8, FW_ BOLD 

A font weight may be specified for DIALOGEX resources. 

84 HELPID not valid for DIALOG controls. 

You may not specify a help id for a control in a DIALOG resource. This message is issued 
when a help id is specified for a control in a DIALOG resource. 

Example: 

my_ dig DIALOG 0, 0, 100, 100 
BEGIN 

CONTROL "None", MY_ ID, "BUTTON", 

BS_ AUTORADIOBUTTON | WS_ CHILD | WS_ VISIBLE 
12, 40, 30, 10, 0, MY_ HELPID 

END 

A help id may be specified for a control in DIALOGEX resource. 

85 Data Elements not valid for DIALOG controls. 

This indicates that a list of data values has been found following a control in a DIALOG 
resource. Data can only follow control statements in a DIALOGEX resource. 
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86 <value> is not a valid resource id. 

This message is issued when a numeric identifier has been specified for a resource but the 
value is outside the allowable range. 

87 User interrupt detected. 

Processing was stopped to allow another user action to occur. 

88 Resource type for resource "<resource> " is greater than 32767. 

When a number is used to identify the type of a resource the number must be between 0 
and 32767. This message is issued when a number has been specified as a resource type 
that is outside the allowable range. 

Example: 

MYRES OxFOOO { 0 } 

89 Resource ID "<id> " is greater than 32767. 

When a number is used to identify a resource the number must be between 0 and 32767. 
This message is issued when a number has been specified as a resource identifier that is 
outside the allowable range. 

Example: 

OxFOOO ICON "t.ico" 

90 Unmatched quotation mark on command line. 

Quotations marks may be used on the WRC command line to delimit file or path names. 
This message indicates that a quotation mark was found on the command line but no 
matching quotation mark could be found. 

100 Trying to add a Winl6 or Win32 RES file "<file>" to an OS/2 executable "<file>". 

This error occurs when you attempt to run pass two of the Open Watcom Resource 
Compiler with a Winl6 or Win32 . RES file and an OS/2 executable file. You can do two 
things: 

• Recreate the . RES file using the -bt=os2 switch 

• Make sure the correct file is specified. 

101 <value> is not a valid resource type. 

This message is issued when a numeric type has been specified for a resource but the value 
is outside the allowable range. 
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Symbol <value> is not defined. 

This message is issued when a numeric resource id is expected but the symbol representing 
the resource id has not been defined. 

This error occurs only for OS/2 resource files. Other platforms support symbolic and string 
constant resource ids. 
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15 Zoom 


15.1 Introduction 


Zoom is a tool designed to magnify selected sections of your screen. This allows you to view icons more 
closely and examine windows to detect errors in the graphics. With Zoom you can also watch a program, 
while magnified, paint its windows to detect subtle errors. 

15.2 Using Zoom 

This section discusses the following topics: 

• Starting Zoom 

• Quitting Zoom 

• The Zoom Menu Bar 

• The Zoom Window 

15.2.1 Starting Zoom 

To start Zoom double-click on the Zoom icon. This opens the Open Watcom Zoom window. When you 
start Zoom, the Zoom window contains a magnification of the upper left hand corner of the current screen. 
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Figure 131. The Zoom window displays, in magnification, the selected screen area. 

15.2.2 Quitting Zoom 

To close the Zoom session, choose Exit from the File menu of the Open Watcom Zoom window. 

15.2.3 The Zoom Menu Bar 

The menu bar consists of the following: 

File Configure the session and paste the window contents to the clipboard 

« Decrease the magnification of the object in the Zoom window 

» Increase the magnification of the object in the Zoom window 

15.2.4 The Zoom Window 

The Open Watcom Zoom Window has both a vertical and horizontal scroll bar which enable you to view, 
in magnification, the area around the selected screen space. Once you have selected an area to view in 
magnification, you can decrease and increase the magnification using the symbols on the menu bar. 
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• Click on the decrease symbol («) to lessen the magnification of the selected area. 

• Click on the increase symbol (») to get a closer view of the selected area. 

15.3 Zoom Operations 

There are a number of functions you can perform with Zoom, including zooming, resizing the window, and 
pasting magnified screen sections to the clipboard. This section describes each Zoom function. 

15.3.1 Zooming 

The following procedures describe the standard steps you perform to zoom. 

(1) Position the mouse pointer in the Zoom window. 

(2) Press the left mouse button and drag the mouse outside of the Zoom window. 

Attached to the cursor is a box which acts as a magnifier. As you move the mouse, the screen sections 
over which you drag this magnifier appear magnified in the Zoom window. 

(3) Position the magnifier on top of the screen area you want to capture in magnification. 

(4) Release the mouse button. 

Zoom captures the selected screen section in the Zoom window in magnification. 

(5) Make fine adjustments, such as centering the captured image, using the scroll bars of the Zoom 
window. 

Scrolling is a standard Windows feature. However, with Zoom, you can see the magnifier move on 
the screen as you scroll the captured image in the Zoom window. 

15.3.2 Resizing the Zoom Window 

Resizing the Zoom window can be done at two different times: before you zoom an area or while you are 
zooming an area. 

Resizing the window before you zoom is a standard Windows operation. 

(1) Position the cursor on the border of the window until it turns into a double-pointed arrow. 

(2) Press the left mouse button and drag the mouse until the window is the desired size. 

(3) Release the mouse button. 

While positioning the magnifier over an area of the screen to select it for magnification, you may find you 
want to increase or decrease the size of the area you capture. 
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To resize the window while zooming: 

(1) Position the cursor in the Zoom window. 

(2) Press the left mouse button and drag the mouse outside of the Zoom window. 

(3) Position the magnifier over the desired screen area to select. 

(4) Press the right mouse button while continuing to hold down the left mouse button. 

If the Sticky Magnifier option is activated, you do not need to hold down the left mouse button. For 
details on the Sticky Magnifier option, refer to the section entitled "Configuring Zoom" on page 245. 

(5) Move the mouse to increase or decrease the size of the magnifier. 

There is a maximum and minimum size for the magnifier. The resizing interaction is similar to 
resizing a regular window. The Zoom window does not change in size until you release the right 
mouse button. 

(6) Release the right mouse button when the magnifier is the desired size. 

Note: When resizing the window while zooming, the Zoom window may overlap the selected 

screen area when you release the right mouse button. When this occurs, the magnifier 
captures the image of the resize window, not the original screen area. This only happens if 
the screen area you are selecting is close to the Zoom window. 

15.3.3 The Begin Zoom Item 

The Begin Zoom item in the File menu allows you to scan the screen area without holding down the left 
mouse button. This is similar to the Sticky Magnifier feature that is offered in the Configure dialog. 

Note: The Begin Zoom item is not available in Zoom for Win32. 

To Zoom using the Begin Zoom item: 

(1) Select Begin Zoom from the File menu. 

This reveals the magnifier attached to your cursor. 

(2) Position the magnifier over the screen area you want to magnify. 

(3) Resize the magnifier as desired using the right mouse button. 

(4) Click the left mouse button to capture the selected screen area in the Zoom window. 

15.3.4 Pasting with Zoom 

The paste function in Zoom allows you to paste whatever is in the Zoom window onto the clipboard. From 
here you can paste the clipping to other applications, such as the Image Editor. 

To paste the contents of the Zoom window to the clipboard, choose Paste to Clipboard from the File menu 
of the Open Watcom Zoom window. 
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15.4 Configuring Zoom 

The Configure item under the File menu opens the Configure dialog. On this dialog you set certain options 
that dictate how the Zoom application behaves. Once you have selected the desired configure options, click 
on OK to store this information and close the Configure dialog. The following sections explain the options 
presented in the configure dialog. 



Figure 132. On the Configure dialog, you customize the behaviour of the Zoom application. 

15.4.1 Configuring Zoom: Always On Top 

Selecting the Always On Top option Configuring Zoom: ensures that the Zoom window will always 
appear on top of other windows. If this option Configuring Zoom: is not selected, then when working with 
several windows at a time the Zoom window can get pushed behind other windows. 

15.4.2 Configuring Zoom: Sticky Magnifier 

Selecting Sticky Magnifier is the same as using the Begin Zoom menu item. When this box is checked, the 
zooming interaction Configuring Zoom: changes. 

The Sticky Magnifier option Configuring Zoom: dictates that you zoom by pressing the left mouse button 
once in the Zoom window to activate the zoom function Configuring Zoom: and then press it once more to 
capture the selected screen area. With this option Configuring Zoom: you are able to drag the magnifier 
into position Configuring Zoom: without holding down the mouse button. 

Note: The Sticky Magnifier option Configuring Zoom: is not available in the Win32 version of 

Zoom. 
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15.4.3 Configuring Zoom: Auto Refresh 

Normally, Zoom only refreshes the selected area in the Zoom window when the magnifier moves. When 
the Auto Refresh option Configuring Zoom: is selected. Zoom refreshes the image displayed in the Zoom 
window at regular intervals, as well as when the magnifier moves. This feature is useful when magnifying 
screen images that change frequently, such as the seconds on the clock application Configuring Zoom:. 

When the enable auto refresh box in the configuration Configuring Zoom: dialog is checked you can enter 
a value in the Interval field. This value specifies the interval in tenths of seconds that Zoom will wait 
between image refreshes. 
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16 Heap Walker 


16.1 Introduction 


The Open Watcom Heap Walker is a testing and debugging tool for Windows. It allows you to do two 
things: 

• observe how memory is being used 

• view the contents of memory 

Note: Under Windows NT, the Heap Walker monitors only the memory used by 16-bit Windows 

applications. 

Heap Walker enables you to locate corrupted data and allows you to manipulate stored memory for testing 
purposes. In addition to these functions, this tool allows you to optimize your memory usage. 

Heap Walker displays the stored memory, or objects, in the Heap Walker window. Objects are blocks of 
memory that go together to make up the global heap. The objects may contain information such as program 
instructions, data, or program resources. You control Heap Walker using the items from the menu bar. 

16.2 Using Heap Walker 

This section discusses the following topics: 

• Starting Heap Walker 

• Quitting Heap Walker 

• The Heap Walker Menu Bar 

16.2.1 Starting Heap Walker 

To start Heap Walker, double click on the Heap Walker icon. This opens the Heap Walker window. The 
information list displayed is the last list that was viewed during the previous Heap Walker session. 
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Figure 133. The Heap Walker window displays lists of memory objects 

16.2.2 Quitting Heap Walker 

To close the Heap Walker session, choose Exit from the File menu of the Heap Walker window. 


16.2.3 The Heap Walker Menu Bar 

The menu bar consists of the following eight menus: 

File S ave to a file and configure the session 

Display Select the type of information you want to appear on the Heap Walker window 

Sort Select how you want to sort the information in the Heap Walker window 

Object Work with the items in the Heap Walker window by viewing, removing, and reordering 

them 

Local Work with Local Heaps 

Global Work with the Global Heap 

Alloc Allocate blocks of memory for testing purposes 

Help Access on-line help information 

16.3 Configuring the Heap Walker Session 

There are many aspects of Heap Walker that you can configure, including setting the fonts, window 
positions, and save paths. Choose the Configure item from the File menu. This opens the Heap Walker 
Configuration dialog box where you customize the Heap Walker’s behavior. 
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Figure 134. On the Heap Walker Configuration dialog, you customize the Heap Walker’s behavior 

The Configuration dialog is set up with defaults for all options. To reset all options to their defaults, click 
the Defaults button. 

16.3.1 Heap Walker: Configuring the File Name Paths 

The Heap Walker window, the local heap window and the memory display windows all have file menus 
with save items. When you choose the save item one in these windows the currently displayed information 
is saved to a filename generated by heapwalker. 

These file names are generated based on the entries in the File name for... fields of the Configuration 
Dialog. The File name for Global Saves affects filename generation for saves from the Heap Walker 
window. The File name for Local Saves affects filename generation for saves from the local walk window. 
The File name for Memory Dumps affects filename generation for saves from the memory display window. 

The file names for saves are generated from the entered file name as follows. If a path is specified for the 
filename then the generated file will appear in the specified directory. The filename for the generated file is 
formed by adding three digits to the end of the specified file name to form a new filename that is unique in 
the given directory. 

For example, if the File name for Memory Dumps field contains "c:\mem\foo.txt" then all files saved from 
the memory display window appear in the directory c:\mem and have filenames such as "foo000.txt", 
"foo001.txt" and "foo003.txt". 

Beside each file name field in the configuration dialog is a Browse button. Pressing this button opens a file 
selection dialog where you can view your directory structure while picking the filename for that field. 

16.3.2 Heap Walker: Configuring Window Behaviour 

As well as file name options, the Configuration dialog contains six configuration options that you activate 
and de-activate using check boxes. A description of each option follows. 
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16.3.2.1 Save Main Window Size/Position 

Activating this option causes the size and position of the Heap Walker window to be saved when you close 
the application. The next time you open the Heap Walker application, the window appears with the same 
size and same position as when you last closed it. 

16.3.2.2 Save Memory Window Size/Position 

Activating this option causes the size and position of the Memory Display window to be saved when you 
close the application. The next time you open the Memory Display window, it appears with the same size 
and same position as when you last closed it. 

16.3.2.3 Allow Multiple Memory Display Windows 

When this option is activated, you can open multiple Memory Display windows. The new window may 
open on top of an existing window, but can be moved and resized as necessary. 

When this option is not activated, selecting a second object to view from the Heap Walker window closes 
the first Memory Display window and opens the new Memory Display window in its place. 

16.3.2.4 Display Memory Info Window 

When this option is selected a Handle Information or Selector Information dialog box appears whenever a 
Memory Display window is opened. If this option is not activated the information box does not appear, but 
it can be opened by choosing Show Info from the File menu in the Memory Display window. 

16.3.2.5 Auto Position Memory Info Window 

The setting of the Auto Position Memory Info option in the Configuration dialog determines the default 
setting of the Auto Position Info feature in the Memory Display window. 

In the Memory Display window, activating the Auto Position Info feature ensures that the information box 
is always attached to the window. When deactivated, the Handle Information or Selector Information 
dialog box moves separately from the Memory Display window. You can turn on the auto position feature 
by selecting Auto Position Info from the File menu on the Memory Display window. 

16.3.2.6 Display Resources 

When the Display Resources option is activated. Heap Walker displays a graphical image when you open 
the memory display window for an object that represents a graphical resource. 

16.3.3 Heap Walker: Saving the Current Configuration 

Normally, Heap Walker saves the configuration information, such as the window size and position, only 
when the application closes. Choosing the Save Current Configuration item from the File menu of the 
Heap Walker window causes Heap Walker to save the current configuration information. This saves the 
main window and Memory Display window sizes and positions, even if the Save Main window 
size/position and the Save Memory window size/position options in the Configuration dialog box are not 
selected. 
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16.3.4 Heap Walker: Setting the Font 

The Font item in the File menu allows you to set the font, style, and size for the text in all Heap Walker 
windows. This item opens the Font dialog box. Select the desired font details and click on OK to close the 
dialog and apply the fonts. 

16.4 Walking the Global Heap 

There are four lists of information you can display in the Heap Walker window. The Display menu allows 
you to choose a list to be displayed. The lists Heap Walker can display are: 

Entire Heap All of the memory objects on the global heap 

Free Items All of the objects that are not currently allocated 

LRU Items The least recently used list items 

Selector List All valid selectors 

16.4.1 The Entire Heap 

Choosing Entire Heap from the Display menu displays a list of all the global heap in the Heap Walker 
window. The global heap is a pool of memory set aside by the system from which all program memory is 
allocated. 
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Figure 135. Choosing the Entire Heap item displays the global heap. 


The following are the column headings that appear when the selected display is Entire Heap, Free Items, or 
LRU Items. 


Handle An identifier assigned by the operating system to each object on the global heap 

Address The physical address in memory of the first byte in the object 

Size The total number of bytes occupied by the object 
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Owner The module that owns the memory 

Flags An indicator specifying the type of the object. The codes are F (fixed memory) and D 

(discardable memory). A blank indicates that Heap Walker is unable to determine if the 
object is fixed or discardable. 

Lock An identifier indicating if there is a lock on the object. LI indicates there is a lock on the 

memory; PI indicates there is a page lock on the object; a blank indicates there is no lock 
on the object. 

Heap An indicator specifying if the object has a local heap. The code Y indicates that the object 

has a local heap; a blank field indicates there is no local heap. 

Type An indicator specifying the type of information in the object 

16.4.2 Free Items List 

The Free Items list contains all objects on the global heap that are currently unallocated. Viewing the Free 
Items list allows you to see how fragmented your free memory is. The Free Items list appears under the 
same column headings as The Entire Heap list. 

16.4.3 LRU Items List 

The LRU Items list contains all items in the system that are currently available to be discarded. The system 
discards memory when there is not enough free memory to satisfy an allocation request from a program. 
Memory is discarded based on a least recently used algorithm. 

Only the LRU list can be sorted by age. When sorted this way the objects appear in order from newest to 
oldest. This means the first object on the list will be the last item to be discarded. This allows you to see 
the order in which the system will discard objects. 

To sort the LRU list, refer to the section "Sorting the Lists" on page 255. 

The LRU Items list appears under the same column headings as The Entire Heap list. 

16.4.4 The Selector List 

The selector list displays all valid ring three selectors in the system. This list also shows descriptor table 
information about each selector. 
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Figure 136. The Selector List displays all valid ring three selectors. 


You can view the data accessible by a selector by double clicking on its entry in the list. When you do this 
a Memory Display window appears. Attached to this window is a Selector Information dialog box that 
contains the information about the chosen selector that was displayed in the selector list. 


The following are the column headings that appear when the Selector List is displayed. 


Sel 

The selector that information on this line refers to 

Base 

The lowest linear address accessible using this selector 

Limit 

The number of bytes of memory that this selector allows you to access. The greatest linear 
address accessible using this selector is Base plus the Limit, (i.e. <sel>:<limit>) 

Gran 

The granularity of the selector 

Type 

A value indicating if this selector provides execute access. This value contains the value 
code if execute access is provided. Otherwise the field contains data. 

DPL 

The privilege level for this selector. This determines the privilege level that a task requires 
to access this memory. 

Access 

The operations that are allowed on memory using this selector. The codes in this field are 
R (read), W (write), and Ex (execute). 

Big 

A code indicating if the selector’s B flag (bit 54) is set. A Y in this column indicates the 
flag is set. A blank indicates the flag is not set. 

16.5 Sorting the Lists 


The items that appear in the Sort menu depend on the list selected from the Display menu. The Sort items 
allows you to organize the displayed information, making objects easier to find. There are two ways to sort 
information in Heap Walker. 


• Choose the desired sort method from the Sort menu 
or 

• Click once on the column heading by which you want to sort. 
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Only those headings appearing in the Sort menu change the organization of the displayed information when 
selected. 

The following is a list of the headings by which you can sort the displayed information. Some headings 
have a secondary sort feature. For example, when you sort by Type, Heap Walker first sorts the Type field 
alphabetically, then organizes objects of the same Type by Owner. Where applicable, the secondary sort 
appears in parentheses. 

For the Entire Heap, Free Items, and LRU Items lists: 

• Address 

• Handle 

• Owner (secondary sort=Type) 

• Size 

• Type (secondary sort=Owner) 

• Flag 

• Age (available for LRU Items list only) 

Lor the Selector List 

• Base Address 

• Selector 

• Limit 

• Granularity 

• Type 

• DPL 


16.6 Viewing the Contents of Memory 

You can view the data stored in an object that appears in one of the lists displayed in the Heap Walker 
window by double clicking on the desired object. This opens a Memory Display window for the object. 

16.6.1 The Memory Display Window 


Memory Display for handle 1CEE 


File Display Set Offset... 

00000000 00000000 01360000 26207942 72646441 . 6.By.Addr [7 

00000010 00737365 01370000 26207942 646E6148 ess...7.By.Hand “ 

00000020 0000656C 42013800 4F262079 72656E77 le...8.By.Owner = 

100000030 39000000 20794201 7A695326 00000065 ...9.By.Size... 1* 

Figure 137. The Memory Display window displays the data stored in the selected object. 

The Memory Display window displays all of the data stored in the selected object. The data in this window 
appears in hexadecimal form. The Memory Window is useful because it allows you to see if the data in 
memory is what you believe it should be. Heap Walker cannot display the Memory Display window for 
free items or objects whose size equals zero. 

When you size the Memory Display window Heap Walker automatically reformats the information so that 
it is the same width as the window. 

Some memory objects contain information representing graphical objects used by Windows, such as 
menus, dialogs, cursors, and icons. When you display the data for one of these objects in the Memory 
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Display window. Heap Walker also displays the object in graphical form. Occasionally, this operation may 
fail for different reasons, including lack of memory and the inability to read certain resource formats. 

If the object displayed is a menu then Heap Walker can tell you the constant associated with any item in the 
menu. When the menu is displayed in graphical form simply select an item from it. Heap Walker will 
display a dialog that shows the name of the item selected and the numeric constant associated with it. This 
numeric constant is the number passed as the wparam parameter of a window’s callback function when the 
menu item is selected. 

The Memory Display window is accompanied by an Information dialog box. This section describes the 
Information dialog, as well as the various functions you can perform within the Memory Display window. 
Functions include saving, setting the display, and setting the offset. 

16.6.1.1 Saving Heap Walker Information to a File 

The Save items in Heap Walker allow you to save the information displayed in a window to a text file. 
Saving information to a file allows you to do many things, including: 

• print the output later 

• compare objects outside of Heap Walker 

• annotate the text file on-line 

Choosing Save from the File menu on the Memory Display window saves the data in the window to a file 
name generated by Heap Walker based on the information in the Configuration dialog. A message box 
appears indicating the path to which Heap Walker saved the file. 

Choosing Save As from the File menu allows you to specify the file to which you want to save the data 
currently in the window. This opens a Save As dialog box where you select the desired file. Click on OK 
when completed. A message box appears indicating the path to which Heap Walker saved the file. 

16.6.1.2 Changing the Heap Walker Display 

There are five ways to display the information in the Memory Display window. You can display the 
information as: 

• Bytes 

• Words 

• DWords 

• 16-bit Code 

• 32-bit Code 

To change the form of the displayed data, select an item from the Display menu. 

When displaying data in bytes, the data appears in the window as it physically appears in memory. When 
the data is displayed as words, the bytes in memory are interpreted for you so that the values displayed are 
those that would be obtained by treating the memory as an array of words. For example, if memory 
containing the values: 

12 34 56 78 9A BC DE FF 

was shown as words, the memory window would display: 

3412 7856 BC9A FFDE 
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A similar interpretation is performed when the data is displayed as DWords. If the above memory was 
shown as DWords, the memory window would display: 

78563412 FFDEBC9A 

This rearrangement of bytes does not affect the textual interpretation of the data shown on the right hand 
side of the window. 

Selecting 16 or 32 Bit Code from the Display menu presents the data in a disassembled form. Sometimes 
presenting the data in disassembled form is not accurate. This is because when Heap Walker disassembles 
the data it begins at the first byte of the memory block and disassembles it linearly. If a byte in this block, 
such as a padding byte, throws off the sequence, the disassembly will be meaningless. 

16.6.1.3 Setting the Offset in the Memory Display Window 

In the Memory Display window, selecting the Set Offset item from the menu bar allows you to reposition 
the data so that the specified line appears at the top of the window. The offset you enter appears on the first 
line. It will not necessarily be the first piece of information because rounding often occurs to avoid 
breaking a line. 

(1) Choose Set Offset from the menu. 

This opens a Goto Offset dialog box. 



Figure 138. In the Goto Offset dialog, enter the offset you want to appear at the top of the Memory Display 
window. 

(2) Enter the desired offset that you want to position at the top of the Memory Display window. You 
can enter the offset in decimal or hexadecimal form. However, you must prefix hexadecimal values 
with Ox (e.g. 0x00000005). 

(3) Click on OK. 

This closes the dialog and positions the data as requested. 

16.6.1.4 Information Dialog Boxes 

A Handle Information dialog box attached to the Memory Display window provides the information that 
appears on the Heap Walker window for the displayed object. The information in this dialog is: 
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• Block Address 

• Block Handle 

• Block Size 

• Lock Count 

• Page Lock Count 


— Handle Information 

Block Address: 

00000400 

Block Handle: 

1CEE 

Block Size: 

OOGO 

Lock Count: 

0000 

Page Lock Count: 

0000 


Figure 139. The Handle Information dialog box displays information for the selected object. 

When the selected display is the Selector List, the Selector Information dialog box is attached to the 
Memory Display window. The information in this dialog is: 

• Selector 

• Base 

• Limit 

• Type 

• DPL 

• Granularity 

• Access 


—J Selector Information 

Selector: 

1017 

Base: 

00000400 

Limit: 

0000FFFF 

Type 

data 

DPL: 

3 

Granularity: 

byte 

Access: 

R/W 


Figure 140. The Selector Information dialog displays the Selector List information for the selected object. 

The information boxes stay with the Memory Display window when the Auto Position Info item under the 
File menu is checked. Uncheck this item by selecting it again from the File menu. 

If the information dialog is not visible, reveal it by choosing Show Info from the File menu on the Memory 
Display window. Close this dialog by double clicking on the system menu box in the upper left hand 
corner of the dialog. 
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16.7 Working with Individual Objects 

The items in the Object menu enable you to operate on the individual objects on the global heap. 

The Object Menu 

Show View the data stored in an object. 

Get Selector Show the Selector corresponding to a Handle. 

Discard Request that a discardable object be purged from memory. 

Oldest Reposition an object to become the oldest object on the LRU list. 

Newest Reposition an object to become the newest object on the LRU list. 

Add Calculate and display the amount of memory used by selected objects. 

These items allow you to quickly set up test situations while developing a program. For example, if you 
suspect your program has a bug caused by the system discarding a particular object, you can use the Newest 
item to force the system to keep that object. Similarly, you can discard an object that you suspect is 
causing a bug to see if your program runs without it. 

Some items apply only to specific objects. To reposition and discard objects, the selected object must be a 
discardable item. When the Selector List is displayed only the Show item is available. 

16.7.1 Viewing an Object’s Memory 

Viewing an object’s memory is useful because it allows you to see if what is actually in memory is what 
you think should be in memory. There are two ways to view an object’s memory: 

• Double click on the desired object 
or 

• Click once on the desired object to select it and choose Show from the Object menu. 

This opens a Memory Display window for the selected object. 

You can save the information on this window to a file and change the way in which the window displays 
the memory information. Refer to the section "Viewing the Contents of Memory" on page 256 for details 
on these functions. 

16.7.2 Finding a Selector 

The Get Selector function locates the selector for any object with a handle. You need to know the selector 
to get the logical address in memory of an object. This function is not available for free items or objects 
without handles. 

To find the selector for an object: 
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(1) Click once on the object whose selector you want to find. 

(2) Choose Get Selector from the Object menu. 

This opens a message box which indicates the Selector that corresponds to the selected memory 
object. 

(3) Click on OK to close the message box. 

16.7.3 Discarding an Object 

The Discard item allows you to request that the system purge a discardable object from memory. Only 
objects marked by the operating system as discardable can be discarded. 

Choosing this item is equivalent to making the API call GlobalDiscard for the selected object. 

To discard an object: 

(1) Click once on the object you want to discard. 

(2) Choose Discard from the Object menu. 

This opens a message box which indicates the Handle of the object discarded, as well as the number 
of bytes discarded. 

(3) Click on OK to close the message box. 

16.7.4 Repositioning an Object 

Repositioning objects allows you to force discardable objects to be the oldest or newest object on the LRU 
list. The system discards objects from memory when there is not enough free memory available to satisfy 
an allocation request from a program. Giving an object the status Oldest ensures that if the system discards 
objects from memory, this will be the first object discarded. Giving an object the status Newest ensures 
that when the system removes memory, this will be the last object removed. 

To reposition an object: 

(1) Click once on the object you want to reposition. 

(2) Choose Oldest or Newest from the Object menu, depending on how you want to reposition the object 
in the list. 

This opens a message box which indicates the handle of the object that has been repositioned in the 
selected manner. 

(3) Click on OK to close the message box. 
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16.7.5 Calculating Memory Size 

The Add function is a summary function you use to calculate the memory size of selected objects. This 
function may be helpful in identifying memory leaks. 

A memory leak occurs when a program allocates memory but does not free it when the memory is no 
longer needed. If a program has a memory leak it requires increasingly more memory as it inns. With the 
Add function you can quickly determine the amount of memory being used by your program at any point in 
time. This allows you to determine if its memory requirements are increasing over time. 

Choosing Add from the Objects menu opens an Add dialog box. 



Figure 141. As you select objects, the Add function calculates and displays the number of selected objects 
and their total size. 

During an Add operation the global heap list acts as an extended selection list box. There are several ways 
to select objects in an extended selection list box. The following describes three common selection 
techniques you can use. 

• Select one object by clicking on it. The Add dialog displays the size of the selected item. 

• Select multiple objects by holding the CTRL key and clicking on each object one at a time. The Add 
dialog displays the number of objects selected and the total size of those objects. 

• Select many objects in a sequence by clicking on the first object and dragging the mouse while 
depressing the mouse button. Release the mouse button when the last item in the sequence is 
highlighted. The Add dialog displays the number of objects selected and the total size of those 
objects. 

16.8 Walking the Local Heap 

A local heap is a pool of memory set aside by an individual program from which only that program can 
make allocations. Looking at the local heap allows you to see how your program is using the memory it is 
taking from the local heap. 

All items in the Local menu relate to objects with local heaps, so are only functional with such objects. 
Objects marked with a Y in the Heap column have a local heap. 
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16.8.1 Monitoring Data Segment Usage 

Every Windows program has a default data segment. This block of memory contains the program’s stack, 
local heap and the memory for any static or extern variables that it declares (static data). If a program 
requires enough static data that its default data segment grows beyond 64K then it must be recompiled for 
the large memory model and may encounter problems when more than one instance of the program run 
simultaneously. 

The Monitor Local Heap item allows you to see how memory in a program’s default data segment is being 
used so you can optimize this by reducing the amount of stack space allocated to the minimum required or 
eliminate memory leaks that could drive up the amount of memory required by the local heap. 

When you choose the Monitor Local Heap item a Local Heap Monitor window is opened. This window 
contains a scale ranging from zero to the number of bytes in the selected data segment. The scale is divided 
into colored blocks which illustrate how the memory for the object is used. Uses include: 

Fixed heap memory occupied by fixed objects on the program’s local heap 

Free heap memory occupied by free objects on the program’s local heap 

Moveable heap 

memory occupied by movable objects on the program’s local heap 

Stack allocated 

memory allocated for use by the program’s stack 
Stack used memory actually used by the program’s stack since the program began execution 
Static data memory used by the program’s static data 
Unknown memory for which Heap Walker cannot determine a use 
Heap Walker updates this display continuously as memory usage changes. 

To view the usage of a program’s default data segment: 

(1) Click once on the object containing the default data segment you want to monitor. 

This object will contain a local heap. A program’s "hlnstance" is the handle of its default data 
segment. 

(2) Choose Monitor Local Heap from the Local menu. 

The Local Heap monitor window opens which displays the usage scale for the selected object. 
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WHEAPWLK Local Heap Monitor 


27040 


Unknown [44] 
Free Heap [2480] 


Fixed Heap [8276] 
Stack Allocated [7018], used [2734] 
Static Data [9222] 


Figure 142. The Local Heap Monitor window displays a scale indicating how the selected object is used. 


(3) Double click on the system menu to close the window. 

16.8.2 Local Walk 

Selecting the Local Walk item from the Local menu opens the Local Heap window for the selected object. 


WHEAPWLK Local Heap 


File Sort 


Of fset 

Handle 

Size Flags 

Locks 

Type 

3F84 

3F84 

8 FIXED 

0 

UNKNOWN 

3F90 

3F90 

76 FIXED 

0 

UNKNOWN 

3FE0 

3FE0 

8192 FIXED 

0 

UNKNOWN 

5FE4 

0000 

2480 FREE 

0 

FREE 


Figure 143. The Local Heap window displays the local heap for the selected object. 


This window displays all objects on the selected object’s local heap. Unlike the global heap, you cannot 
double click on the local heap objects to view the data they contain. 


The local heap window displays the following information: 

Offset The number of bytes from the beginning of the object containing the local heap to the 

beginning of the object on the local heap 

Handle An identifier assigned by the operating system to each object on the local heap 

Size The total number of bytes occupied by the object 

Flags An indicator specifying the type of the object. The types are Free (unallocated object). 

Fixed (allocated object that has a fixed position on the local heap), and Moveable (allocated 
object that the operating system is able to reposition on the local heap). 

Locks The lock count for the object 

Type An indicator specifying the type of information in the object 
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There are two menus in this window: File and Sort. The File menu allows you to perform standard 
functions, including: 

• saving to a file (Save, Save As) 

• closing the window (Exit) 

Following are other functions you can perform in the Local Heap window. 

16.8.2.1 Refresh the Heap 

The state of the local heap constantly changes as applications run. Selecting the Refresh Local List item in 
the Lile menu updates the information in the Local Heap window. 

16.8.2.2 Display Heap Information 

Selecting the Heap Info item in the Lile menu of the Local Heap window opens the Local Heap Information 
dialog box. 



Figure 144. The Local Heap Information dialog displays summary information for the current local heap. 

This dialog displays the count and size, in bytes, of the free, moveable, and fixed objects in the local heap 
for the selected object. 

Because the state of the local heap constantly changes, you can select the Refresh button on the dialog to 
update the local heap information. Click on OK to close the dialog. 

16.8.2.3 Sorting the Local Heap 

The Sort menu allows you to select the way Heap Walker displays the local heap information, making 
objects easier to find. There are two ways to sort information in the local heap window: 
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• Choose the desired sort method from the Sort menu 
or 

• Click once on the column heading by which you want to sort. 

Only those headings appearing in the Sort menu change the organization of the displayed information when 
selected. 

16.8.3 Compact and Local Walk 

Selecting the Compact and Local Walk item compacts the local heap for the selected object. Once 
compacted, this function opens the Local Heap window. The functions available on this window are the 
same as for the Local Walk function. This function is equivalent to making the API call LocalCompact(-l) 
and then selecting Local Walk from the Local menu. 

16.8.4 GDI Local Walk 

GDI is the part of the Windows operating system responsible for drawing on the screen. Much of what a 
Windows program does involves drawing on the screen using objects such as device contexts, pens, and 
bitmaps. GDI is responsible for managing these objects. Memory for them is contained on the GDI Local 
Heap. Walking the GDI local Heap allows you to view the GDI objects that currently exist in the system. 

GDI objects are a limited resource in the system, so it is important that Windows applications use them 
wisely. Walking the GDI Local Heap allows you to monitor GDI object usage. 

To walk the GDI Local Heap choose GDI Local Walk from the Local menu. 

16.8.5 USER Local Walk 


USER is the part of the Windows operating system responsible for managing user interface objects such as 
windows, menus, and dialogs. Some memory associated with these objects is contained on the USER 
Local Heap. 

Space on the USER Local Heap is a limited resource in the system, so it is important that Windows 
applications use it wisely. Walking the USER Local Heap allows you to monitor usage of this space. 

To walk the USER Local Heap choose USER Local Walk from the Local menu. 

16.9 Working with the Global Heap 

The global heap is a pool of memory set aside by the system from which all program memory is allocated. 
There are five functions you can use to monitor and manipulate the Global Heap. This section describes 
these functions. 
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16.9.1 Refreshing the Global Heap 

As programs run, the state of the global heap changes. When you select the global heap window after a 
window belonging to another application has been active. Heap Walker automatically refreshes the 
displayed global heap information. 

Selecting the Refresh Global Heap item in the Global menu forces Heap Walker to update the displayed 
global heap information. 

16.9.2 Compacting the Global Heap 

Compacting the global heap creates larger blocks of free memory. The system automatically compacts the 
global heap when it needs memory. 

The Global Compact item in the Global menu allows you to manually force the system to compact the 
global heap. Selecting this item is equivalent to making the API call GlobalCompact(O). 

16.9.3 Removing Discardable Objects 

Selecting the Global Compact and Discard item from the Global menu removes all discardable objects and 
compacts the free memory on the global heap. This allows you to create larger blocks of free memory. 
Selecting this item is equivalent to making the API call GlobalCompact(-l). 

16.9.4 Viewing the Global Heap Summary 

Selecting the Global Heap Info item from the Global Menu opens a Global Heap Information dialog box. 
This dialog summarizes global heap usage. 



Figure 145. The Global Heap Information dialog provides a summary of global heap usage. 
Information included on this dialog is: 

• Total Items on the Heap 

• Number of Free Items 

• Number of LRU Items 
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The state of the global heap changes as applications run. Select the Refresh button to update the global 
heap summary. Click on OK to close the dialog. 

16.9.5 Viewing Memory Management Information 

Selecting the Memory Management Info item from the Global menu opens a Memory Management 
Information dialog box. This dialog displays information regarding the state of the virtual memory 
manager. 



Figure 146. The Memory Management Information dialog displays information regarding the state of the 
virtual memory manager. 

Following is the information that appears on this dialog. 

Size of Linear Address Space (in pages) 

The size of the total linear address space in pages 

Free Pages in Linear Address Space 

The amount of free memory, in pages, in the linear address space 

System Page Size (in bytes) 

The size, in bytes, of a page of memory 

Pages in Swap File 

The number of pages in the system swap file 

Total Pages in System 

The total number of pages managed by the virtual memory manager, including free, locked, 
and unlocked pages 

Number of Unlocked Pages 

The number of unlocked pages in the system, including free pages 

Number of Free Pages 

The number of pages in the system that are not currently in use 
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Largest Free Memory Block 

The size, in bytes, of the largest free block of contiguous linear memory in the system 

Maximum Allocatable Pages 

The maximum number of pages that are available in the system for allocation 

Maximum Lockable Pages 

The maximum number of pages that are available in the system to be allocated and locked 

The information displayed by this dialog changes as applications run. Click on the Refresh button to 
update the displayed information. Click on OK to close the Memory Management Information dialog. 

16.10 Testing with Heap Walker 

Heap Walker provides various allocation functions that allow you to test your programs. By allocating and 
freeing memory you can see how your program reacts in low memory situations. 

Each time you select the Alloc menu an Allocation Information dialog box appears on the screen. 


Allocation Information 1 

K allocated (approx): 

352 

K Free: 

1G022 

B^tes Free: 

1G40G528 


Figure 147. The Allocation Information dialog provides approximate size information regarding allocated 
and free memory. 

The information in this dialog includes Kilobytes allocated (approximately). Kilobytes free, and Bytes free. 
It is important to realize that the information appearing in this dialog is approximate. This information 
appear so you can monitor the approximate amounts of memory you have allocated using an Allocation 
function. You should use this information only when using an Allocation function. 

Important: Do not use the Allocation functions under the Windows Debug Kernel as they can make 

your system unstable. 

16.10.1 Allocate All Memory 

To see how your program runs when all free memory is allocated, choose Allocate All Memory from the 
Alloc menu. Choosing this item may change the appearance and performance of your application. This is 
normal because when there is little memory available, the system may discard fonts that Heap Walker is 
using and swap information to disk more frequently. 
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16.10.2 Free All Memory 

Selecting the Free All Memory item frees all of the allocated memory. This returns to the system the 
memory taken away using other Allocation functions. 

16.10.3 Other Allocation Functions 

The final three allocation functions—Allocate all but. Allocate, and Free—allow you to choose an amount 
of memory to allocate or free. Perform these functions as follows: 

(1) Choose the desired function from the Alloc menu. 

(2) Choose the desired amount of memory that you want to allocate, free, or leave unallocated. 

For all functions, an n amount is available. Selecting this item closes the Allocation Information 
dialog box and opens a separate dialog box displaying the following information: 

• K Allocated (approx.) 

• K free (approx.) 

• Bytes Free 



Figure 148. On the allocation dialog box, enter the desired amount of memory to allocate, free, or leave 
unallocated. 

(3) In this dialog, enter the specific number of bytes to Allocate all but. Allocate, or Free. 

The system interprets the entered value as bytes, unless you follow the value with a K, in which case 
the value is read as kilobytes. You can enter Hexadecimal values by prefixing them with Ox. 

(4) Click on OK to process the request and close the dialog. 
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17 Spy 

17.1 Introduction 


Most Windows programs are message based. Messages are sent to windows that programs create and the 
programs are expected to react to the messages appropriately. 

When a program does not react as expected, you must spend time debugging the program to find and 
correct the errors. Spy is a tool designed to help you debug Windows programs by letting you view the 
messages sent to windows in Winl6 and Win32 applications. By watching how a program reacts to the 
messages it receives, you can isolate the parts of your code that are causing problems and then make the 
required corrections. 

With Spy: 

• you can determine if your window is receiving the messages you expect it to receive. 

• you can verify that your window is receiving messages in the order you expect. 

• novice Windows programmers can become familiar with Windows messages, by viewing the 
messages and their parameters. 

As you run your Windows programs. Spy displays messages in the Spy window. You control the window 
using the menu items or the Spy toolbar. 

17.2 Using Spy 

This section discusses the following topics: 

• Starting Spy 

• Quitting Spy 

• The Spy Menu Bar 

• The Spy Toolbar 

17.2.1 Starting Spy 

To start Spy, double click on the Spy icon. This opens the Spy window. When you start the application, 
the Spy window is always empty. This window displays the menu bar, message list and a toolbar. 
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Figure 149. The Spy window contains the menu bar, message list and toolbar. 

17.2.2 Quitting Spy 

To exit Spy, choose Exit from the File menu of the Spy window. 


17.2.3 The Spy Menu Bar 

The menu bar consists of the following five menus: 

File S ave to a file, start and pause logging, and configure the session 

List Manipulate the message list by clearing, marking, and autoscrolling it 

Spy Start, stop, and pause the Spy session, select the windows you want to monitor, and gain 

access to information in windows. 

Messages Select the messages you want to monitor or stop on. 

Help Gain access to on-line help information 



Figure 150. The Spy menu bar. 
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17.2.4 The Spy Toolbar 

The Spy toolbar provides quick access to commonly used menu items. The following explains the function 

each tool bar button performs as well as the equivalent menu item. 

SELECT WINDOW Select a single window and start spying on it or add a window to the list of windows 
being spied on. This is equivalent to the Select Window and Add Window items in the Spy 
menu. 

STOP Stop monitoring the selected window(s) and cancel the window selections. This is 

equivalent to the Stop Spying item in the Spy menu. 

PEEK AT WINDOW Obtain information about a selected window. This is equivalent to the Peek at 
Window item in the Spy menu. 

MARK Record your own comments in the Spy window. This is equivalent to the Mark item in the 

List menu. 

CLEAR MESSAGE LIST Erase all messages from the Spy window. This is equivalent to the Clear 
Message List item in the List menu. 

SHOW SELECTED WINDOWS Obtain information about the windows open on your desktop. This is 
equivalent to the Show Selected Windows item in the Spy menu. 

MESSAGES TO WATCH Select the messages you want to monitor and log. This is equivalent to the 
Messages to Watch item in the Messages menu. 

MESSAGES TO STOP ON Specify the messages you want Spy to stop on when it encounters them. This 
is equivalent to the Messages to Stop on item in the Messages menu. 



Figure 151. The Spy toolbar. 

Only one of the following three toolbar buttons appears at a time. 

NOT SPYING This button appears when Spy is not monitoring any windows. Pressing this button has no 
effect. It is simply an indicator to you that spying is not in progress. 

STOP SPYING TEMPORARILY This button appears when Spy is in the process of monitoring one or 

more windows. Choosing this button temporarily suspends monitoring operations. This is 
equivalent to the Stop Spying Temporarily item in the Spy menu. 

CONTINUE SPYING This button appears when you instruct Spy to temporarily suspend monitoring 

operations. Choosing this button resumes monitoring operations. This is equivalent to the 
Continue Spying item in the Spy menu. 
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17.3 The Spy Window 

The Spy window contains the menu bar and the toolbar discussed above. However, most of the Spy 
window is occupied by the message list. This is where Spy logs the messages it monitors. 



Figure 152. Once you start spying, the message list displays the messages selected for monitoring. 


For the messages it monitors Spy displays the following information in the message list: 


Message Name 

Name of the message sent. 

hWnd The handle of the window that received the message. 

MsgID The numeric identifier of the message. 

wParam Data specific to the message. This is the value that will be passed as the wparam parameter 
of the window’s callback function. To find the meaning of this parameter see the section 
Viewing Message Information for information on how to get help on a message or refer to 
your Windows 3.x or Win32 programmer’s documentation. 

IParam Data specific to the message. This is the value that will be passed as the lparam parameter 

of the window’s callback function. To find the meaning of this parameter see the section 
Viewing Message Information for information on how to get help on a message or refer to 
your Windows 3.x or Win32 programmer’s documentation. 

Several spy functions affect the appearance or behavior of the Spy window. 


• Setting the Fonts 

• Saving 

• Clearing the Message List 

• Marking the Message List 

• Automatic Scrolling 
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• Always On Top 

17.3.1 Spy: Setting the Fonts 

The Set Font item in the File menu allows you to set the font, style, and size for the text in the Spy window. 
Choosing this item opens the Font dialog box. Select the desired font details and click on OK to close the 
dialog and apply the fonts. 

17.3.2 Spy: Saving the Contents of the Message List 

The Save and Save as items under the File menu in Spy allow you to save the contents of the message list 
to a text file. Saving information to a file enables you to print the output later or annotate the text file 
on-line. 

Choose Save from the File menu in the Spy window to save the message list information into the current 
working directory. A message box appears indicating the path to which Spy saved the file. 

Choose Save As from the File menu to specify the file to which you want to save the currently displayed 
information. This opens a Save As dialog box where you select the desired file. Click on OK when 
completed. A message box appears indicating the path to which Spy saved the file. 

17.3.3 Spy: Clearing the Message List 

Choose Clear from the File menu to delete all information from the message list. 

17.3.4 Spy: Marking the Message List 

Use the Mark function to annotate the information in the message list by entering text into it. 

To mark the message list: 

(1) Choose Mark from the List menu. 

This opens the Set Mark dialog box. 


The Spy Window 277 




Spy 


Set Mark 


Enter mark text: 
event list messagej 


“Mark Style 

O plain boxed 


OK 


CANCEL 


Figure 153. With the Set Mark dialog, you can annotate the message list by entering text and choosing a 
mark style. 


(2) Type the desired text in the Enter Mark Text field. 

The text you enter will appear at the end of the message list 

(3) Select the desired Mark Style option. 

These options determine how the entered text is formatted when it is added to the message list When 
the boxed option is selected, the text is displayed bordered by asterisks. With this option the text is 
easier to find. When the plain option is selected, the text is displayed as it is entered. 

(4) Click on OK when completed. 

The Set Mark dialog closes and the text in the dialog appears at the end of the message list. 


Dr. WATCOM 


File Log lask Help 


TASK START: 

DLL LOAD: 

TASK EXIT: 

MODULE DEL: 

TASK START: 

TASK EXIT: 

MODULE DEL: 
********************** 
* event list message * 


********************** 


task id=ldl7, Initial CS:IP=lbf£:757a 
Module=WHEAPULK, Path=C:\WATCOM\BINW\UHEAPWLK.EXE 
module id=lbe7, initial CS:IP=lbbf:0000 
module 1 STRESS, path=C:\WATCOM\BINW\STRESS. DLL 
Task id=ldl7, rc=lc27 

id=lbS7, module=STRESS. path=C:\UATCOM\BINW\STRESS.DLL 
task id=lb0f. Initial CS:IP=lb5f:16e8 
Modu1e=UZOOM, Pa t h=C:\WATCOM\BINUMJZOOM.EXE 
Task id=lb0f, rc=0001 

id = lb07, modu1e=WZOOM, path=C:\WATCOM\BINW\WZOOM.EXE 


Figure 154. Text you enter in the Set Mark dialog appears in the message list in the selected style. 


17.3.5 Spy: Automatic Scrolling 

As Spy writes new information to the message list, the information is added to the bottom of the list. 
Choosing Auto Scroll Message List from the List menu tells Spy to automatically scroll the information in 
the message list so that the most recent information written to the message list always appears on the 
screen. The Auto Scroll Message List menu item is checked when this feature is active. 
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When this feature is deactivated, new messages written to the message list are added to the bottom of the 
list and you must use the scroll bar to scroll down and view the information. 

17.3.6 Spy: Always On Top 

The Spy window behaves like all other windows—it moves into the background when other windows are 
selected. To ensure the Spy window is visible at all times, select the Always On Top item from the File 
menu. The Always On Top menu item is checked when this feature is enabled. To turn this feature off, 
select the item again from the File menu. 

17.4 Selecting Messages to Monitor 

Each window receives an overwhelming volume of messages. Generally, you will only be interested in a 
small subset of these. Spy lets you limit the messages on which it will report so that you do not have to sort 
through all the extraneous data yourself. 

Spy maintains two lists of messages: the messages to watch list and the messages to stop on list. When spy 
monitors a message in the messages to watch list it adds information about that message to the Message 
List in the Spy window. When spy monitors a message in the messages to stop on list it displays a message 
box reporting that the message has been encountered and pauses spying operations until you restart them by 
selecting Continue Spying from the spy menu. Any message that does not appear on either list is ignored 
by Spy 

To modify the messages to watch list choose Messages To Watch from the Messages menu. To modify the 
messages to stop on list choose Messages To Stop On from the Messages menu. In either case, the process 
of modifying the list is the same. The rest of this section explains the dialogs you use to do this. 

17.4.1 Selecting Individual Messages 

The most precise way to modify the messages to watch or messages to stop on lists is simply to select a set 
of individual messages to appear on the list. To select a set of individual messages to monitor follow these 
procedures. 

(1) Choose Messages To Watch or Messages To Stop On from the Messages Menu. 

This opens a Message Class dialog box. The caption of the dialog box reflects the menu item 
selected. 
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Messages To Watch 


B 


P Clipboard 

P NC Misc 

W DDE 

P NC Mouse 

W IME 

P Other 

1^ Init 

P System 

W Input 

P Unknown 

W MDI 

P User 

P Mouse 

P Window 


OK 


Cancel 



Clear All 


Set All 


Individual Message Control... 


Figure 155. In the Message Class dialog, select the Individual Message Control button. 


(2) Click on the Individual Message Control button. 


This opens a dialog that contains a check box for each message. 


17 WM_ALT tABACT IVE 
[7 WM.APPCOMMAND 
(7 WM_ASKCBFORMATNAME 
17 WM_BEGINDRAG 
17 WM_CANCE(JOURNAL 
R WM_CANCELMODE 
17 WM_CAPTURECHANGED 
|7 WM_CHANGECBCHAIN 
17 WM.CHANGEUISTATE 
[7 WM_CHAR 
[7 WM_CHARTOITEM 
17 WM_CHI LD ACT IVAT E 
17 WM.CLEAR 
[7 WM_CLIPBOARDUPOATE 
[7 WM_CL0SE 
[7 WM_COALESCE_FIRST 


17 WM_COMPACTING 
17 WM_COMPAREITEM 
17 WM_CONTEXTMENU 
17 WM_CONVERTREQUEST 
17 WM.CONVERTRESULT 
17 WM_C0PY 
17 WM_COPYDATA 
17 WM_CREATE 
17 WM_CTLC0L0R 
17 WM_CTLC0L0RBTN 
17 WM_CTLC0L0RDLG 
17 WM.CTLCOLOREDIT 
17 WM_CTLC0L0RLISTB0X 
17 WM_CTLC0L0RMSGB0X 
17 WM_CTLCOLORSCROLLBAR 
17 WM.CTLCOLORSTATIC 


[7 WM_DDE_DATA 
[7 WM_DDE_EXECUTE 
17 WMJ5DEJNITIATE 
(7 WM_DDE_POKE 
17 WM_DDE_REQUEST 
[7 WM_DDE_TERMINATE 
17 WM_DDE_UNADVISE 
|7 WM_DEADCHAR 
17 WMJ3ELETEITEM 
[7 WM.DESTROY 
|7 WM_D E S T R 0YCU PB OAR D 
|7 WM_DEVICECHANGE 
17 WM_DEVMODECHANGE 
17 WM_DISPLAYCHANGE 
[7 WM_DRAGL00P 
|7 WM.DRAGMOVE 


Cleat All | Set All | 



OK 

Cancel | 

Next > 



Figure 156. In the Message Range dialog, you select the individual messages you want Spy to watch or 
stop on. 


(3) Add or remove messages from the list of messages. 


A message appears on the selected list if it is checked. The following buttons are provided for your 
convenience: 
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Clear All Uncheck all messages on this dialog. 

Set All Check all messages on this dialog. 

(4) Choose an action button. 

The following buttons allow you to proceed from this dialog: 

Next Close the current dialog and open the one for the alphabetic range of messages 

immediately following this one. Changes made on the current dialog will not be 
saved until you press the OK button on some future message range dialog. 

Prev Close the current dialog and open the one for the alphabetic range of messages 

immediately preceding this one. Changes made on the current dialog will not be 
saved until you press the OK button on some future message range dialog. 

OK Close the current dialog and save all changes made in it and in previous dialog that 

were exited using the Next or Prev button. 

Cancel Close the current dialog and ignore all changes made in it and in previous dialog that 

were exited using the Next or Prev button. 

(5) Select OK on the Message Class dialog. 

The message class dialog closes and your message selections take effect. If you choose Cancel on the 
Message Class dialog your message selections will be discarded. 

17.4.2 Selecting Message Classes 

Although modifying the list of messages to watch or stop on by selecting individual messages is more 
precise, you may find this process tedious. To speed up the process several message classes have been 
defined for you. These classes group messages by their function. The messages contained in each message 
class are listed in the section entitled "Predefined Spy Message Classes" on page 282 

Selecting a message class adds all the individual messages in that class to the selected list. Similarly, 
de-selecting a message class removes all the individual messages in that class from the selected list. 

To select messages to monitor by class follow these procedures: 

(1) Choose Messages To Watch or Messages To Stop On from the Messages Menu. 

This opens a Message Class dialog box. The caption of the dialog box reflects the menu item 
selected. 
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Figure 157. In the Message class dialog, choose the message classes you want Spy to monitor. 

(2) Click on the check box beside the message classes you want to monitor. 

A message class is selected when an X appears in the check box. The following buttons are available 
for your convenience: 

Clear All De-select all of the message classes. 

Set All Select all of the message classes. 

(3) Click on OK to save your choices and close the dialog. 

Selecting Cancel on this dialog exits without saving your selections. 


17.4.3 Predefined Spy Message Classes 

The sections that follow list the messages contained in each message class that Spy defines for you. 

Messages followed by (*) are undocumented messages. 

Messages followed by (**) are available under Win32 only. 


17.4.3.1 Clipboard Messages 


WM_ ASKCBFORMATNAME WM_ 

WM_ CLEAR WM_ 

WM_ COPY WM_ 

WM_ DESTROYCLIPBOARD WM_ 

WM_ HSCROLLCLIPBOARD WM_ 

WM_ PASTE WM_ 

WM_ RENDERFORMAT WM_ 

WM_ UNDO WM_ 


CHANGECBCHAIN 

CLIPBOARDUPDATE 

CUT 

DRAWCLIPBOARD 

PAINTCLIPBOARD 

RENDERALLFORMATS 

SIZECLIPBOARD 

VSCROLLCLIPBOARD 


* *) 
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17.4.3.2 DDE Messages 

WM_ DDE_ ACK 
WM_ DDE_ DATA 
WM_ DDE_ INITIATE 
WM_ DDE_ REQUEST 
WM_ DDE_ UNADVISE 

17.4.3.3 Init Messages 

WM_ INITDIALOG 
WM_ INITMENUPOPUP 


17.4.3.4 Input Messages 

WM_ AP P COMMAND (* *) 

WM_ CHAR 

WM_ COMMAND 

WM_ COPYDATA (**) 

WM_ DRAGLOOP (*) 

WM_ DRAGSELECT (*) 

WM_ EXITSIZEMEOVE (*) 
WM_ INPUT (**) 

WM_ INPUTLANGCHANGE (**) 

WM_ KEYDOWN 

WM_ LBTRACKPOINT (*) 

WM_ MENUCOMMAND (* *) 

WM_ MENUGETOBJECT (* *) 
WM_ MENUSELECT 
WM_ NOTIFY (**) 

WM_ QUERYDROPOBJECT (*) 
WM_ UNICHAR (**) 

17.4.3.5 MDI Messages 

WM_ ISACTIVEICON (*) 

WM_ MDICASCADE 
WM_ MDIDESTROY 
WM_ MDIICONARRANGE 
WM_ MDINEXT 
WM_ MDISETMENU 


17.4.3.6 Mouse Messages 

WM_ CAPTURECHANGED (**) 
WM_ LBUTTONDOWN 
WM_ MBUTTONDBLCLK 
WM_ MBUTTONUP 
WM_ MOUSEHOVER (* *) 

WM_ MOUSELEAVE (* *) 

WM_ MOUSEWHEEL (* *) 

WM_ RBUTTONDOWN 

WM_ SETCURSOR 

WM_ XBUTTONDOWN (**) 


WM_ DDE_ ADVISE 
WM_ DDE_ EXECUTE 
WM_ DDE_ POKE 
WM_ DDE_ TERMINATE 


WM_ INITMENU 

WM_ UNINITMENUPOPUP (**) 


WM_ BEGINDRAG (*) 

WM_ CHARTOITEM 
WM_ CONTEXTMENU (**) 

WM_ DEADCHAR 
WM_ DRAGMOVE ( *) 

WM_ DROPOBJECT (*) 

WM_ HSCROLL 

WM_ INPUT_ DEVICE_ CHANGE ( * * ) 
WM_ INPUTLANGCHANGEREQUEST (**) 
WM_ KEYUP 
WM_ MENUCHAR 
WM_ MENUDRAG (**) 

WM_ MENURBUTTONUP (* *) 

WM_ NEXTMENU ( *) 

WM_ NOTIFYFORMAT (**) 

WM_ TCARD (**) 

WM_ VSCROLL 


WM_ MDI ACTIVATE 
WM_ MDI CREATE 
WM_ MDIGETACTIVE 
WM_ MDIMAXIMIZE 
WM_ MDI RE STORE 
WM_ MDITILE 


WM_ LBUTTONDBLCLK 
WM_ LBUTTONUP 
WM_ MBUTTONDOWN 
WM_ MOUSEACTIVATE 
WM_ MOUSEHWHEEL ( * *) 
WM_ MOUSEMOVE 
WM_ RBUTTONDBLCLK 
WM_ RBUTTONUP 
WM_ XBUTTONDBLCLK (* *) 
WM_ XBUTTONUP (* *) 
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17.4.3.7 NC Misc Messages 

WM_ NCACTIVATE WM_ 

WM_ NCCREATE WM_ 

WM_ NCPAINT 


17.4.3.8 NC Mouse Messages 


WM_ NCHITTEST WM_ 
WM_ NCLBUTTONDOWN WM_ 
WM_ NCMBUTTONDBLCLK WM_ 
WM_ NCMBUTTONUP WM_ 
WM_ NCMOUSELEAVE (**) WM_ 
WM_ NCRBUTTONDBLCLK WM_ 
WM_ NCRBUTTONUP WM_ 
WM_ NCXBUTTONDOWN (**) WM_ 


17.4.3.9 Other Messages 


WM_ CHANGEUISTATE (**) WM_ 

WM_ COALESCE_ LAST WM_ 

WM_ CONVERTREQUEST (*) WM_ 

WM_ DROPFILES WM_ 

WM_ PENWINFIRST WM_ 

WM_ PRINT (**) WM_ 

WM_ QUERYSAVESTATE (*) WM_ 

WM_ QUERYUISTATE (**) WM_ 

WM_ SYNCTASK ( *) WM_ 

WM_ UPDATEUISTATE (**) WM_ 


17.4.3.10 System Messages 


WM_ 

CANCELJOURNAL (**) 

WM_ 

WM_ 

DEVMODECHANGE 

WM_ 

WM_ 

DISPLAYCHANGE (**) 

WM_ 

WM_ 

ENTERIDLE 

WM_ 

WM_ 

EXITMENULOOP 

WM_ 

WM_ 

NULL 

WM_ 

WM_ 

POWERBROADCAST (**) 

WM_ 

WM_ 

SYSCHAR 

WM_ 

WM_ 

SYSCOMMAND 

WM_ 

WM_ 

SYSKEYDOWN 

WM_ 

WM_ 

SYSTEMERROR (*) 

WM_ 

WM_ 

THEMECHANGED (**) 

WM_ 

WM_ 

TIMER 

WM_ 

WM_ 

WININICHANGE 

WM_ 


17.4.3.11 User Messages 

WM_ USER 


NCCALCSIZE 

NCDESTROY 


NCLBUTTONDBLCLK 
NCLBUTTONUP 
NCMBUTTONDOWN 
NCMOUSEHOVER (**) 
NCMOUSEMOVE 
NCRBUTTONDOWN 
NCXBUTTONDBLCLK (**) 
NCXBUTTONUP (**) 


COALESCE_ FIRST 
COMMNOTIFY 
CONVERTRESULT (*) 
INTERIM (*) 
PENWINLAST 
PRINTCLIENT (**) 
QUEUESYNC 
SIZEWAIT (*) 
TESTING (*) 
YOMICHAR (*) 


COMPACTING 
DEVICECHANGE (**) 
ENDSESSION 
ENTERMENULOOP 
FILESYSCHANGE (*) 

POWER 

SPOOLERSTATUS 
SYSCOLORCHANGE 
SYSDEADCHAR 
SYSKEYUP 
SYSTIMER (*) 

TIMECHANGE 
USERCHANGED (**) 
WTSSESSION_ CHANGE (**) 
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17.4.3.12 Unknown Messages 

None 


17.4.3.13 Window Messages 


WM_ 

ACTIVATE 

WM_ 

ACTIVATEAPP 

WM_ 

ACTIVATESHELLWINDOW (* 

)WM_ 

ALTTABACTIVE (*) 

WM_ 

CANCELMODE 

WM_ 

CREATE 

WM_ 

CHILDACTIVATE 

WM_ 

CLOSE 

WM_ 

COMPAREITEM 

WM_ 

CTLCOLOR 

WM_ 

CTLCOLORBTN (**) 

WM_ 

CTLCOLORDLG (**) 

WM_ 

CTLCOLOREDIT (**) 

WM_ 

CTLCOLORLISTBOX (**) 

WM_ 

CTLCOLORMSGBOX (**) 

WM_ 

CTLCOLORSCROLLBAR (**) 

WM_ 

CTLCOLORSTATIC (**) 

WM_ 

DELETEITEM 

WM_ 

DESTROY 

WM_ 

DRAWITEM 

WM_ 
* * ) 

DWMCOLORIZATIONCHANGED 

WM_ 

DWMCOMP 0 SITIONCHANGED (** 

WM_ 
* * ) 

DWMNCRENDERINGCHANGED 

WM_ 

DWMWINDOWMAXIMIZEDCHANGE 

WM_ 

ENABLE 

WM_ 

ENTERSIZEMOVE (*) 

WM_ 

ERASEBKGND 

WM_ 

FONTCHANGE 

WM_ 

GETDLGCODE 

WM_ 

GETFONT 

WM_ 

GETHOTKEY 

WM_ 

GETICON (**) 

WM_ 

GETMINMAXINFO 

WM_ 

GETTEXT 

WM_ 

GETTEXTLENGTH 

WM_ 

GETTITLEBARINFOEX (**) 

WM_ 

HELP (**) 

WM_ 

ICONERASEBKGND 

WM_ 

KILLFOCUS 

WM_ 

MEASUREITEM 

WM_ 

MOVE 

WM_ 

MOVING (**) 

WM_ 

NEXTDLGCTL 

WM_ 

OTHERWINDOWCREATED 

WM_ 

OTHERWINDOWDESTROYED 

WM_ 

PAINT 

WM_ 

PAINTICON 

WM_ 

PALETTECHANGED 

WM_ 

PALETTEISCHANGING 

WM_ 

PARENTNOTIFY 

WM_ 

QUERYDRAGICON 

WM_ 

QUERYENDSESSION 

WM_ 

QUERYNEWPALETTE 

WM_ 

QUERYOPEN 

WM_ 

QUERYPARKICON (*) 

WM_ 

QUIT 

WM_ 

SETFOCUS 

WM_ 

SETFONT 

WM_ 

SETHOTKEY 

WM_ 

SETICON (**) 

WM_ 

SETREDRAW 

WM_ 

SETTEXT 

WM_ 

SETVISIBLE (*) 

WM_ 

SHOWWINDOW 

WM_ 

SIZE 

WM_ 

SIZING (**) 

WM_ 

STYLECHANGED (**) 

WM_ 

STYLECHANGING (**) 

WM_ 

SYNCPAINT (*) 

WM_ 

VKEYTOITEM 

WM_ 

WINDOWPOSCHANGED 

WM_ 

WINDOWPOSCHANGING 


17.4.4 Saving and Loading Message Configurations 

Selecting messages to monitor can be an involved procedure because of the number of options available. 
Once selected, the group of message selections is called a message configuration. 


Spy allows you to save message configurations and recall them again. This section describes the functions 
relating to message configurations: 
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• Using the Auto Save Feature 

• Saving a Message Configuration 

• Loading a Message Configuration 

17.4.4.1 Using the Auto Save Feature 

When the Auto Save Message Configuration feature is active Spy saves your message configuration each 
time you exit. The next time you start Spy, the message configuration is automatically reloaded. 

To activate or deactivate this feature choose the Auto Save Message Configuration item from the Messages 
menu. When this feature is active its menu item is checked. 

17.4.4.2 Saving a Message Configuration 

With Spy you can save your message configurations so you can easily load a previous message 
configuration instead of reselecting the desired messages. 

To save a message configuration follow these procedures: 

(1) Select the messages you want to monitor as described in the sections entitled "Selecting Message 
Classes" on page 281 and "Selecting Individual Messages" on page 279. 

(2) Choose Save Message Configuration from the Messages menu. 

This opens a Save As dialog box. 

(3) Specify the desired file name and path for this message configuration. 

(4) Click on OK in the Save As dialog box when completed. 

This saves the message configuration as specified and closes the dialog. 

17.4.4.3 Loading a Message Configuration 

To load a previously saved message configuration, follow these procedures: 

(1) Choose Load Message Configuration from the Messages menu. 

The Open dialog box appears. 

(2) Select the message configuration you previously saved. 

(3) Click on OK. 

The Open dialog box closes and Spy loads the selected message configuration. 
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17.5 Spying 

Once you have selected the messages you want Spy to monitor, you select windows for Spy to watch. This 
starts spying operations. 

17.5.1 Start Spying 

Message logging begins when you select a window to monitor. Spy monitors the selected window for the 
messages specified. You can start spying by selecting one window to spy on, or choosing to spy on all 
windows. 

To spy on all windows: 

(1) Choose All Windows from the Spy menu. 

Spy begins immediately monitoring all windows for the specified messages. The caption bar specifies 
that you are monitoring all windows. 

Note: You can use the All Windows menu item at any time, not just to start spying. If you begin 

spying by choosing one window, then want to monitor all windows, choose All Windows 
from the Spy menu. 

To spy on one window: 

(1) Choose Select Window from the Spy menu. 

This minimizes the Spy window and opens the Select Window dialog which prompts you to choose a 
window to monitor. 


window to be selected. 


Current Window 
hWnd: 04210648 
Name: Dr. Watcom 


Cancel 


OK 


Figure 158. The Select Window dialog displays information for the window on which the cursor rests. 

(2) Position the cursor inside the icon in the dialog box. Press the mouse button and hold it down. 

As you move the cursor across the screen, the window on which the cursor is positioned has a 
highlighted border and information about the selected window appears in the dialog box. 

(3) Position the cursor on the window you want to monitor. Release the mouse button. 
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Note: You can select only one window at a time using the Select Window dialog box. 

(4) Click on OK to save this window selection. 

This closes the Select Window dialog and returns you to the Spy window. The caption bar indicates 
the window you are monitoring. 

17.5.2 Spying on More Windows 

Once you have started spying you can select additional windows to monitor, unless you chose All Windows 
to start the spy process. You select additional windows in the same way you select one window. 

(1) Choose Add Window from the Spy menu. 

This minimizes the Spy window and opens the Select Window dialog. 

(2) Position the cursor inside the icon in the dialog box. Press the mouse button and hold it down. 
Information about the currently selected window appears in the dialog. 

(3) Position the cursor on the window you want to monitor. Release the mouse button. 

Note: You can select only one window at a time using the Select Window dialog box. 

(4) Click on OK to save this window selection. 

This closes the Select Window dialog and opens the Spy window. The window heading specifies that 
you are monitoring multiple windows. 

17.5.3 Stop Spying 

Choose Done Spying from the Spy menu to stop spying on the selected windows. When you choose this 
item. Spy does not retain the list of windows selected for spying. 

17.5.4 Pause Spying 

Choose Stop Spying Temporarily from the Spy menu to pause message logging. When you choose this 
item. Spy retains the list of windows selected for spying. 

The Stop Spying Temporarily menu item changes to Continue Spying when the pause is active. Choose 
Continue Spying from the Spy menu to start spying again. This starts spying and changes the menu item 
back to Stop Spying Temporarily. 
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17.6 Viewing Message Information 

Double clicking on a message in the message list reveals a Message Information dialog box which contains 
additional information about the selected message. This dialog displays the message, the number of times it 
has been issued, and the window that received the selected instance of the message. 



Figure 159. The Message Information dialog box displays additional information about the selected 
message. 

From the Message Information dialog you can perform the following actions: 

• Reset the usage count 

• Display Windows help for the message. 

• Change the monitoring state for the message. 

• Highlight the window that received the message. 

• Display information about the window that received the message. 

17.6.1 Resetting the Usage Count 

You can reset the usage count for the message to zero by pressing the Reset Count button on the Message 
Information dialog. The usage count will also be automatically reset to zero when you start spying or clear 
the message list. 

17.6.2 Displaying Help for the Message 

You can get more information about most messages, such as the meaning of their parameters, by the Help 
for Message button on the Message Information dialog. This starts the Windows help facility to display the 
information. Help is not available for all messages. 
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17.6.3 Changing the Monitoring State of the Message 

The watch and stop on check boxes in the Message Information dialog indicate if the message appears in 
the messages to watch or messages to stop on lists. You can add the message to either of these lists by 
checking the appropriate check box or remove it by removing the check. 

17.6.4 Highlighting the Receiving Window 

If the window that received this message has not been destroyed you can highlight it by selecting the 
Highlight Window button. This changes the border color of the window so it is easy to locate. 

17.6.5 Displaying Information about the Receiving Window 

If the window that received this message has not been destroyed you can get additional information about it 
by selecting the Show Information button. This opens a Window Information dialog that displays 
information such as the window’s class, style, size and position. For more information on the Window 
Information dialog see the section entitled "Viewing Window Information" on page 293. 

17.7Spy: Working with Log Files 

By writing the information in the message list to a log file, you have a file you can look at in case a 
program you are running terminates your applications. In such a situation, your message list is lost so you 
have no information to refer to when debugging. Writing to a log file also allows you to print the output 
later or annotate the text file on-line. 

17.7.1 Spy: Configuring the Log File 

Choosing Configure Log from the File menu opens the Log Configuration dialog where you customize 
Spy’s behaviour when it logs to a file. This dialog contains four sections where you specify information. 
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Figure 160. In the Log Configuration dialog you set the desired behaviour for Spy when logging to a file. 

17. 7 . 1.1 Spy: Default Log Name 

In the Default Log Name field, specify the file to which Spy writes when you begin logging. Clicking the 
Browse button next to this field opens a Choose Log Name dialog that lets you browse your file structure 
while choosing the log name. 

17.7.1.2 Spy: Log Name 

The settings in the Log Name section of the dialog indicate to Spy how the name of the log file should be 
determined when the Log to File menu item is chosen. 

When the Query for Log Name option is selected. Spy presents a prompt each time you select Log to File 
from the File menu or the toolbar. This reveals a Choose Log Name dialog where you specify the file to 
which Spy writes the log information. 

When the Use Default Log Name option is selected. Spy writes the log information to the file indicated in 
the Default Log Name field in the Log Configuration dialog. No prompt appears. 

17.7.1.3 Spy: Action When Log File Exists 

The options in the Action When Log File Exists section of the Log Configuration dialog dictate how Spy 
behaves when you choose Log to File and a log file already exists. 

Replace Spy writes over the existing log file. All information in the existing file is lost. 

Append Spy adds the new information to the end of the existing log file. 

Query Spy prompts you with a message box that allows you to choose a course of 

action—Replace, Append, or Cancel. 
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Figure 161. The Log Information message box appears when logging if the Query option is selected on the 
Log Configuration dialog. 

17.7.2 Spy: Start Logging 

Choosing Log to File from the File menu tells Spy to write all new information added to the message list to 
the log file. Depending on the options selected in the Log Configuration dialog, the following dialogs may 
appear when you choose Log to File: 

• Choose Log Name dialog—On this dialog you specify the file to which Spy writes the log 
information. 

• Log Information dialog—On this dialog you choose a course of action for logging when the 
specified log file already exists. 

Note: Choosing Cancel on either of these dialogs closes the dialog and prevents logging from 

starting. 

17.7.3 Spy: Logging Type 

There are two ways to write information to the log file: 

• Continuous Logging 

• Periodic Logging 

If the Continuous Logging option is activated, then as Spy writes information to the message list, it 
simultaneously writes to a log file. 

When the Periodic Logging option is activated. Spy writes information to the log file only after a 
reasonable amount of information, as determined by the application, has been recorded in the message list 

Periodic logging is more convenient because it is faster than continuous logging. However, if your system 
goes down, some information will be lost. By simultaneously writing to the log file and the message list, 
continuous logging allows you to store all information in a log file without the chance of losing 
information. 
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17.7.4 Spy: Stop Logging 

Once the log is started. Spy continues writing to the log file until you stop logging. A check mark beside 
the Log to File item in the File menu indicates that a log is being created. Choose this item again to stop 
logging. 

17.7.5 Spy: Pause Logging 

To temporarily stop writing information to the log file you can choose the Pause Log item from the File 
menu. A check mark appears beside the item indicating that the log is currently paused. To restart logging, 
choose this item again from the File menu. 

17.8 Viewing Window Information 

In Spy you can view different window information using items in the Spy menu. You can view: 

• information about a specific window 

• a list of all windows open on your desktop 

17.8.1 Viewing Information About a Window 

To view information about a window: 

(1) Choose Peek At Window from the Spy menu. 

This minimizes the Spy window and opens the Peek At Window dialog box. 

(2) Position the cursor inside the icon in the dialog box. Press the mouse button and hold it down. 

As you move the cursor across the screen, the window on which the cursor is positioned has a 
highlighted border and information about the selected window appears in the dialog box. The 
following information is displayed: 

Window the handle of the window and its title, if it has one 

Class the name of the window class to which this window belongs 

Parent the handle of the window’s parent if it has one 

Size the screen coordinates of the top right and bottom left corners of the window, 

followed by the window’s size 

Window Style the window’s style bits 

Class Style the style bits for the window’s class 

Child ID a numeric identifier associated with the window when it is created (This only appears 
if the selected window is a child window.) 

(3) Position the cursor on the window you want to monitor. Release the mouse button. 
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(4) Click on OK to close the dialog box. 

This closes the Peek at Window dialog box and returns you to the Spy window. 

17.8.2 Listing All Windows 

To view a list of all windows open on your desktop: 

(1) Choose Show Selected Windows from the Spy menu. 

This opens the Window Selection dialog box which displays the following: 

• window handles 

• window captions 



Figure 162. The Window Selection dialog displays a list of all windows currently open on the desktop. 

The information appears in a hierarchical manner. Windows with a parent are listed, indented, 
directly below their parent. Windows currently being monitored by Spy are marked with an asterisk. 

(2) From this dialog you can perform the following functions: 

• Add a window for Spy to monitor 

• Delete a window that Spy is monitoring 

• Select all windows for monitoring 

• View information about a window in the list 

17.8.2.1 Adding a Window 

You can add a window for Spy to monitor in two ways: 
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(1) Double click on the line for the window you want to add, or 

(2) Click once on the line for the desired window to select it and then select the Add button. 

The window you added is now marked with an asterisk indicating that Spy is monitoring that window. 
Click on OK to close the dialog and save the updated window list. 

17.8.2.2 Deleting a Window 

To delete a window that Spy is monitoring, do one of the following: 

(1) Double click on the line for the window you want to delete, or 

(2) Click once on the line for the window that you no longer want Spy to monitor and then select the 
Delete button. 

This removes the asterisk from beside the window handle, indicating that Spy is no longer monitoring that 
window. 

Click on OK to close the dialog and save the updated window list. 

17.8.2.3 Monitoring All Windows 

To instruct spy to start spying on all windows open on the desktop, check the "Spy on all windows" check 
box. Then chose the OK button to close the dialog and accept this selection. 

17.8.2.4 Viewing Information 

To view information about a window in the list, do the following: 

(1) Click once on the line for the window whose information you want to view. 

The selected line appears highlighted in the list. 

(2) Select the Show Info button on the dialog. 

The Window Information dialog box opens. The information in this dialog is identical to the 
information in the Peek at Window dialog box. Refer to the section entitled "Viewing Information 
About a Window" on page 293 for a description of the fields in this dialog. 

(3) Click OK. 

The Window Information dialog closes and you return to the Window Selection dialog. 

(4) Click OK on the Window Selection dialog to close it. 
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18 DDE Spy 


18.1 Introduction 

DDE Spy is a debugging tool that allows you to watch all DDE (Dynamic Data Exchange) activity 
occurring in the system. DDE Spy also allows you to monitor DDEML errors and registration of various 
DDE objects, such as strings, conversations, links, and servers. DDE is one way for different applications 
running under Windows to communicate with each other. 

By watching the communications between applications, you can determine if the information being sent is 
correct. If it does not seem correct you can locate the cause of the error. 

18.2 Using DDE Spy 

This section discusses the following topics: 

• Starting DDE Spy 

• Quitting DDE Spy 

• The DDE Spy Menu Bar 

• The DDE Spy Toolbar 

18.2.1 Starting DDE Spy 

To start DDE Spy, double click on the DDE Spy icon. This opens the DDE Spy window. When you start 
the application, the Open Watcom DDE Spy window is always empty. This window displays the menu bar 
and a toolbar. 



Figure 163. The Open Watcom DDE Spy window contains the event list, menu bar, and toolbar. 
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18.2.2 Quitting DDE Spy 

To exit DDE Spy, choose Exit from the File menu of the Open Watcom DDE Spy window. 

18.2.3 The DDE Spy Menu Bar 

The menu bar consists of the following six menus: 

File Save to a file, start and pause logging, and configure the session 

Output Work with the event list and control its output behaviour 

Monitor Select the information you want DDE Spy to write to the event list 

Track Display windows summarizing information for DDE objects tracked by DDE Spy 

Aliases Replace numeric values with meaningful text 


Help Access on-line help information 



Figure 164. The Open Watcom DDE Spy menu bar. 


18.2.4 The DDE Spy Toolbar 

In the Open Watcom DDE Spy window, the toolbar appears below the menu bar when the Show Toolbar 

item in the File menu is checked. To disable this feature, choose the item again from the File menu and the 

Toolbar disappears. The following explains the function each toolbar button performs, as well as the 

equivalent menu item. 

TRACK STRINGS Display or hide the strings tracking window. This window displays a list of all strings 
currently registered with the operating system. This button is equivalent to the Strings item 
in the Track menu. 

TRACK CONVERSATIONS Display or hide the conversations tracking window. This window displays a 
list of all conversations currently active in the system. This button is equivalent to the 
Conversations item in the Track menu. 

TRACK LINKS Display or hide the links tracking window. This window displays a list of all links 

currently active in the system. This button is equivalent to the Links item in the Track 
menu. 

TRACK SERVERS Display or hide the servers tracking window. This window displays a list of all servers 
currently registered with the operating system. This button is equivalent to the Servers item 
in the Track menu. 

LOG Start Logging. This button is equivalent to the Log to File item in the File menu. 


300 Using DDE Spy 
































DDE Spy 


MARK Record your own comments in the event list. This button is equivalent to the Mark item in 

the Output menu. 

CLEAR Clear the event list. This button is equivalent to the Clear item in the Output menu. 

ADD HWND ALIAS Replace window handle values with text. This is equivalent to the Add Hwnd Alias 
item in the Alias menu. 

ADD TASK ALIAS Replace task id values with text. This is equivalent to the Add Task Alias item in the 
Alias menu. 

ADD CONVERSATION ALIAS Replace conversation id values with text. This is equivalent to the Add 
Conversation Alias item in the Alias menu. 



Figure 165. The Open Watcom DDE Spy toolbar. 


18.3 The DDE Spy Event List 

Opening DDE Spy reveals an empty window. This is the event list where DDE Spy logs the information 
you define in the Monitor menu. Some examples of events are strings being created or deleted and 
conversations and links being established or terminated. 


WATCOM DDE Spy 


File Output Monitor Jrack Aliases Help 


^ 0-'>J 0>l» 0-*>J 

“ 0G* fWND TftiK [b.<U | 

time: 287752 task 
time: 288081 task 
time: 288246 task 
service: 
client cc 
time: 288521 task: 

service: 
client cc 
time: 288575 task 
time: 288630 task 
time: 288795 task 

0x277F STRING CREATED 0xC22C (Server) 

0x277F STRING CREATED 0xC239 (Test) 

0x26FF CONVERSATION ESTABLISHED 

0x0000C22C (Server) topic: 0x0000C239 (Test) 
jnv: 0x000546B8| server conv: 0x000749FC I 

0x277F CONVERSATION ESTABLISHED 

0x0000C22C (Server) topic: 0x0000C239 (Test) 
>nv: 0x000546B8| server conv: 0x000749FC| 

0x277F STRING KEPT 0xC239 (Test) 

0x277F STRING KEPT 0xC22C (Server) 

0x277F STRING DELETED 0xC22C (Server) 

♦ 

+ 

ran ±i 


| Replace HWND values with meaninqful text. || 


Figure 166. Once you start spying, the event list displays the information selected for monitoring. 


This section describes the tasks you can perform in relation to the event list. 

18.3.1 DDE Spy: Setting the Font 

The Font item in the File menu allows you to set the font, style, and size for the text in the DDE Spy 
window. Choosing this item opens the Font dialog box. Select the desired font details and click on OK to 
close the dialog and apply the fonts. 
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18.3.2 DDE Spy: Saving the Event List to a File 

The Save items in the File menu allow you to save the contents of the event list to a text file. Saving 
information to a file enables you to print the output later or annotate the text file on-line. 

Choose Save from the File menu in the Open Watcom DDE Spy window to save the event list information 
into the current working directory. A message box appears indicating the path to which DDE Spy saved 
the file. 

Choose Save As from the File menu to specify the file to which you want to save the event list information. 
This opens a Save As dialog box where you select the desired file. Click on OK when completed. A 
message box appears indicating the path to which DDE Spy saved the file. 

18.3.3 DDE Spy: Clearing the Event List 

Choose Clear from the File menu to delete all information from the current event list. 

18.3.4 DDE Spy: Marking the Event List 

Use the Mark function to annotate the information in the event list by entering text into it. 

To mark the event list: 

(1) Choose Mark from the output menu. 

This opens the Set Mark dialog box. 



Figure 167. With the Set Mark dialog, you can annotate the event list by entering text and choosing a mark 
style. 

(2) Type the desired text in the Enter Mark Text field. 

The text you enter will appear at the end of the event list 

(3) Select the desired Mark Style option. 
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These options determine how the entered text is formatted when it is added to the event list When the 
boxed option is selected, the text is displayed bordered by asterisks. With this option the text is easier 
to find. When the plain option is selected, the text is displayed as it is entered. 

(4) Click on OK when completed. 

The Set Mark dialog closes and the text in the dialog appears at the end of the event list. 
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Figure 168. Text you enter in the Set Mark dialog appears in the event list in the selected style. 


18.3.5 DDE Spy: Pausing the Event List Output 

The Output to Screen item in the Output menu allows you to temporarily stop writing information to the 
event list. When this menu item is unchecked output will not be written to the event list. Although DDE 
Spy stops writing information to the event list, it still writes it to the log file if you are currently creating a 
log file. When DDE Spy is not writing information to the event list applications will run sightly faster so 
when you are not interested in viewing the event list you may want to stop writing to it. 

Note: If you mark the event list while the Output to Screen feature is deactivated, the text you 

enter does not appear in the event list. 


18.3.6 DDE Spy: Automatic Scrolling 

As DDE Spy writes new information to the event list, the information is added to the bottom of the list. 
Checking the Auto Scroll item in the Output menu tells DDE Spy to automatically scroll the information in 
the event list so that the most recent information written to the event list always appears on the screen. 

When the Auto Scroll menu item not checked you must use the scroll bar to scroll down and view any new 
information that is added to the event list. 
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18.4 Selecting Information to Monitor 

The monitor menu contains items that let you specify the types of DDE events that DDE Spy will report on 
by recording them in the event list. Limiting the amount of information logged makes reading the event list 
more efficient. 

When an item appears in the menu with a checkmark, DDE Spy reports on that type of activity. The 
following describes various types of activity DDE Spy can monitor. 

Posted Messages 

When the Posted Messages item is checked, DDE Spy makes an entry in the event list 
whenever a DDE message that has been selected using the Message Filter dialog is posted 
to an application's message queue. 

Sent Messages When the Sent Messages item is checked, DDE Spy makes an entry in the event list 

whenever a DDE message that has been selected using the Message Filter dialog is sent to 
an application. 

String Handle Data 

DDE applications use strings to communicate with other applications. These strings are 
registered with the operating system by the applications using them. When done with the 
strings, the applications tell the operating system they are done and the system destroys the 
strings. DDE Spy reports on all string operations that occur within the system when the 
String Handle Data menu item is checked. 

Callbacks Callbacks are special functions called by the operating system to process DDE messages. 

When the Callback item is checked DDE Spy makes an entry in the event list each time the 
operating system calls a DDE Callback for a transaction type that has been selected using 
the Callback Filter dialog. 

Errors A DDE error usually indicates that a DDE operation has failed. When the Errors item is 

checked, DDE Spy reports all DDE errors that occur within the system. 

Conversations A conversation is the connection established between two applications that is necessary to 
perform DDE operations. When the Conversations item is checked, DDE Spy makes an 
entry in the event list each time a conversation is established or terminated. 

Links A link is a relationship between two DDE applications: a server and a client. A link is 

established for a single value maintained by the server. When this value changes the server 
notifies the client. When the Links item is checked, DDE Spy logs notifications in the 
event list each time a link is established or terminated. 

18.4.1 Setting the Message Filter 

The Set Message Filter item opens the Message Filter dialog which lists the various DDE messages that can 
be posted or sent. This dialog allows you to select the specific messages you want DDE Spy to write to the 
event list. 
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lx WM DDE UNADVISE 


OK 


CANCEL 



SET ALL 



CLEAR ALL 


Figure 169. In the Set Message Filter dialog, select the messages on which you want DDE Spy to report. 


Select the messages that you want DDE Spy to report on when posted or sent. A message is activated when 
its check box contains a check. 


• Use the Set All button in this dialog to activate all of the messages. 

• Use the Clear All button in this dialog to deactivate all of the messages. 

Click on OK when the desired messages are activated. 


18.4.2 Setting the Callback Filter 

The Set Callback Filter menu item opens the Callback Filter dialog which lists the various types of 
transactions for which a DDE callback function may be called. This dialog allows you to specify the 
transaction types you want DDE Spy to report in the event list. 



Figure 170. In the Set Callback Filter dialog, select the transaction types on which you want DDE Spy to 
report. 

Select the transaction types on which you want DDE Spy to report. A transaction type will be reported on 
when its check box contains a check. 
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• Use the Set All button in this dialog to activate all of the transaction types. 

• Use the Clear All button in this dialog to deactivate all of the transaction types. 

Click on OK when the desired transaction types are activated. 

18.5 DDE Spy: Working with Log Files 

By writing the information in the event list to a log file, you have a file you can look at in case a program 
you are running terminates your applications. In such a situation, your event list is lost so you have no 
information to refer to when debugging. Writing to a log file also allows you to print the output later or 
annotate the text file on-line. 

18.5.1 DDE Spy: Configuring the Log File 

Choosing Configure Log from the File menu opens the Log Configuration dialog where you customize 
DDE Spy’s behaviour when it logs to a file. This dialog contains four sections where you specify 
information. 



Figure 171. In the Log Configuration dialog you set the desired behaviour for DDE Spy when logging to a 

file. 

18.5.1.1 DDE Spy: Default Log Name 

In the Default Log Name field, specify the file to which DDE Spy writes when you begin logging. 

Clicking the Browse button next to this field opens a Choose Log Name dialog that lets you browse your 
file structure while choosing the log name. 

18.5.1.2 DDE Spy: Log Name 

The settings in the Log Name section of the dialog indicate to DDE Spy how the name of the log file should 
be determined when the Log to File menu item is chosen. 
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When the Query for Log Name option is selected, DDE Spy presents a prompt each time you select Log to 
File from the File menu or the toolbar. This reveals a Choose Log Name dialog where you specify the file 
to which DDE Spy writes the log information. 

When the Use Default Log Name option is selected, DDE Spy writes the log information to the file 
indicated in the Default Log Name field in the Log Configuration dialog. No prompt appears. 

18.5.1.3 DDE Spy: Action When Log File Exists 

The options in the Action When Log File Exists section of the Log Configuration dialog dictate how DDE 
Spy behaves when you choose Log to File and a log file already exists. 

Replace DDE Spy writes over the existing log file. All information in the existing file is lost. 

Append DDE Spy adds the new information to the end of the existing log file. 

Query DDE Spy prompts you with a message box that allows you to choose a course of 

action—Replace, Append, or Cancel. 



Figure 172. The Log Information message box appears when logging if the Query option is selected on the 
Log Configuration dialog. 

18.5.2 DDE Spy: Start Logging 

Choosing Log to File from the File menu tells DDE Spy to write all new information added to the event list 
to the log file. Depending on the options selected in the Log Configuration dialog, the following dialogs 
may appear when you choose Log to File: 

• Choose Log Name dialog—On this dialog you specify the file to which DDE Spy writes the log 
information. 

• Log Information dialog—On this dialog you choose a course of action for logging when the 
specified log file already exists. 

Note: Choosing Cancel on either of these dialogs closes the dialog and prevents logging from 

starting. 
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18.5.3 DDE Spy: Logging Type 

There are two ways to write information to the log file: 

• Continuous Logging 

• Periodic Logging 

If the Continuous Logging option is activated, then as DDE Spy writes information to the event list, it 
simultaneously writes to a log file. 

When the Periodic Logging option is activated, DDE Spy writes information to the log file only after a 
reasonable amount of information, as determined by the application, has been recorded in the event list 

Periodic logging is more convenient because it is faster than continuous logging. However, if your system 
goes down, some information will be lost. By simultaneously writing to the log file and the message list, 
continuous logging allows you to store all information in a log file without the chance of losing 
information. 

18.5.4 DDE Spy: Stop Logging 

Once the log is started, DDE Spy continues writing to the log file until you stop logging. A check mark 
beside the Log to File item in the File menu indicates that a log is being created. Choose this item again to 
stop logging. 

18.5.5 DDE Spy: Pause Logging 

To temporarily stop writing information to the log file you can choose the Pause Log item from the File 
menu. A check mark appears beside the item indicating that the log is currently paused. To restart logging, 
choose this item again from the File menu. 

18.6 Tracking with DDE Spy 

In the process of DDE interactions programs register and unregister several types of DDE objects such as: 

• Strings 

• Conversations 

• Links 

• Servers 

The tracking windows offer you an easy way to determine at any time which objects are currently 
registered with the system. 

To open a tracking window choose Strings, Conversations, Links or Servers from the Track menu. This 
opens a tracking window that displays all the objects of the selected type that have been registered but not 
unregistered since DDE Spy started. The tracking windows are automatically updated whenever an event 
occurs that changes the displayed information. 

Each tracking window lists its information in tabular form under several headings. You can sort the 
displayed information based on any column by clicking on the column heading for that column. 
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18.6.1 Tracking Strings 

Choose Strings from the Track menu to open a Strings window which tracks all strings currently registered 
with the operating system. As strings are destroyed, DDE Spy removes them from the list. 
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Figure 173. The Strings window tracks all strings currently registered with the operating system. 


The information in this window is: 

Handle The unique numeric identifier for the string 

Count The current usage count of the string. A string is deleted when its usage count is zero. 

String The text of the registered string 

18.6.2 Tracking Conversations 


Choose Conversations from the Track menu to open a Conversations window which tracks all 
conversations currently active in the system. 
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Figure 174. The Conversations window tracks all conversations currently active in the system. 


The information in this window is: 

Client The unique numeric identifier for the client 

Server The unique numeric identifier for the server 

Service The service name specified when the conversation was established 
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Topic The topic specified by the client when the conversation was established 

18.6.3 Tracking Links 

Choose Links from the Track menu to open a Links window which tracks all links currently active in the 
system. 
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Figure 175. The Links window tracks all links currently active in the system. 


The information in this window is: 

Client The unique numeric identifier for the client 

Server The unique numeric identifier for the server 

Type A value indicating if the link is Hot or Warm. When a link is established between a client 

and server, the server notifies the client whenever the value of the item changes. When the 
link type is Warm, the only information sent to the client is notification that the value of the 
item has changed. When the link type is Hot, then the notification that the value has 
changed is sent to the client as well as the new value of the item. 

Service The service name specified when the conversation on which this link exists was established 

Topic The topic specified by the client when the conversation was established. 

Item The name of the item for which the link is established. 

Format The format of the information that is being communicated between applications. 

18.6.4 Tracking Servers 

Choose Servers from the Track menu to open a Servers window which tracks all servers currently 

registered with the operating system. 



Figure 176. The Sen’ers window tracks all servers currently registered with the operating system. 
The information in this dialog is: 
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Server Name The name of each server that is registered with the operating system. This name is 
generally descriptive of the type of server. 


Instance Name 

The server name with a numeric identifier added by the operating system. This name 
uniquely identifies the server in the system. 

18.7 Working with Aliases 

The event list displays an overwhelming array of numeric identifiers. The alias functions allow you to 
replace these numeric identifiers with meaningful text. This makes the event list easier for you to 
understand. For example, if you are monitoring a server application and you know it’s task id is 0x1234 
then you can replace every occurrence of that task id with the text "server". 

18.7.1 Defining Aliases 

Using the alias functions you can define aliases for window handles, task id’s and conversation id’s. 

(1) Choose Add hwnd alias. Add task alias or Add conversation alias from the Alias menu 
or 

Click on the appropriate icon on the toolbar. 

This opens the appropriate Add Alias dialog. The dialog contains a list box that lists all identifiers of 
the chosen type that DDE Spy has encountered. 
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Figure 177. In the Add Alias dialog box, you replace the selected window handle, task, or conversation id 
with descriptive text. 

(2) Click once on the window handle, task, or conversation for which you want to add an alias 
or 

Enter a numeric value in the Value field. 

(3) Position the cursor in the Current Text field. 

(4) Enter the text with which you want to replace this numeric identifier. 

(5) Click on OK to register the alias and close the dialog 
or 

Select the Do More button to register the alias and leave the dialog open. 

This allows you to create aliases for more numeric identifiers. 

18.7.2 Disabling Aliases 

Choosing Disable Aliases from the Aliases menu changes all aliased values back to their original numeric 
identifiers. The Disable Aliases menu item is checked when this option is active. Choosing the menu item 
again disables it. Numeric identifiers are then replaced by their text aliases again. 
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18.7.3 Purging Aliases 

Choosing Purge Aliases from the Aliases menu deletes all aliases set up in DDE Spy. Any values replaced 
by aliases will revert to their original numeric values. 
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19 Dr. Watcom for Windows 3.1 

19.1 Introduction 


The 16-bit version of Dr. Watcom is a post-mortem debugger for Windows 3.1. When an exception occurs 
in a program, a post-mortem debugger allows you, after the fact, to examine the state of both the program 
and the system in order to determine the cause of the exception. In addition to being a debugging tool. Dr. 
Watcom is a system utility that enables you to examine task information. 

Dr. Watcom can be a useful tool when performing in-house testing on your applications. By running Dr. 
Watcom while testing applications, all faults are logged. This gives you important information to recreate 
the errors so you can fix the problems. 

Note: Use the 16-bit version of Dr. Watcom to monitor 16-bit Windows (Win 16) applications 

running under Windows 3.1 or Win32 based operating systems. Use the 32-bit version of 
Dr. Watcom to monitor Win32 applications running under Win32 based operating systems. 

19.2 Using Dr. Watcom 

This section discusses the following topics: 

• Starting Dr. Watcom 

• Quitting Dr. Watcom 

• The Dr. Watcom Menu Bar 

Dr. Watcom is designed to be used effectively while minimized. You only need to view the application 
window when an error or warning occurs. When this happens the Dr. Watcom icon changes from 
stethoscope to an explosion indicating that information is waiting for your attention in the main window. 

Some of Dr. Watcom’s main functionality can also be accessed using the system menu while the 
application is minimized. This includes the log options, task control, and log current state functions. 

Dr. Watcom is more useful with the Windows debug kernel. Under the debug kernel, Windows checks for 
many common programming errors and generates debugging messages when it finds them. Dr. Watcom 
catches the debugging messages and displays them on the event list. Viewing these messages helps you 
identify errors in your program that you might not otherwise see. 

19.2.1 Starting Dr. Watcom 

To start Dr. Watcom, double click on the Dr. Watcom icon. This opens the Dr. Watcom window. 
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19.2.2 Quitting Dr. Watcom 

To exit Dr. Watcom, select Exit from the File menu. This is the only way to quit the application. Unlike 
other applications, double clicking on the system menu box or selecting close from the system menu only 
minimizes the application. 

19.2.3 The Dr. Watcom Menu Bar 

The menu bar consists of the following four menus: 

File Save to a file, work with the event list, and configure the session 

Log Work with the log file 

Task Work with tasks currently running under Windows 

Help Access on-line help information 

19.3 Using the Dr. Watcom Window 

When you open Dr. Watcom, a window appears which contains the event list. The event list records the 
various events occurring under Windows. Some examples of events are errors, debugging messages (under 
the debug kernel of Windows only), the starting and ending of programs, and the loading and unloading of 
DLLs. 


Dr. WATCOM 


File Log Jask Help 


Dr. WATCOM started 
Will Use WDEBUG.386 

DLL LOAD: module id=118f, initial CS:IP=1187:024a 

module=WINT32, path=C:\WATCOM\BINW\WINT32.DLL 
TASK EXIT: Task id=112f, rc=105f 

MODULE DEL: id=2067, module=STRESS, path=C: \WATCOM\BINW\STRESS. DLL 
TASK START: task id=206f, Initial CS:IP=1077:16e8 

Module=WZOOM. Path=C:\WATCOM\BINW\WZOOM.EXE 
DLL LOAD: module id=1087. initial CS:IP=1097:3340 

module=CTL3D, path=C:\WATCOM\BINW\CTL3D.DLL 
TASK EXIT: Task id=206f, rc=203f 

MODULE DEL: id=2067, module=CTL3D, path=C:\WATCOM\BINW\CTL3D.DLL 
MODULE DEL: id=2067, module=WZOOM, path=C:\WATCOM\BIHW\WZOOM.EXE 


Figure 178. The Dr. Watcom window contains the event list which records and displays events occurring 
under Windows. 


When a debug message is issued, the Dr. Watcom icon alerts you that an entry has been made on the event 
list. The Dr. Watcom icon changes from stethoscope to an explosion. To reset the icon you must 
acknowledge the alert in one of two ways: 
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(1) View the event list by double clicking on the icon, or 

(2) Choose Clear Alert from the system menu. 

Dr. Watcom intercepts all exceptions that occur in the system. An exception is an error that causes your 
program to terminate. Dr. Watcom prevents your program from terminating by halting the program’s 
execution. The state of the program remains intact. 

As with non-fatal errors. Dr. Watcom makes an entry on the event list when an exception occurs. 
However, instead of alerting you to the entry by changing the icon. Dr. Watcom reveals an exception 
dialog. This dialog gives you several options. Refer to the section entitled "Dr. Watcom: Exception 
Handling" on page 322 for more information. 

The following sections describe functions that allow you to manipulate the event list: 

• Saving the Event List 

• Clearing the Event List 

• Marking the Event List 

• Setting the Fonts 

19.3.1 Dr. Watcom: Saving Event List Information to a File 

The Save items in the File menu allow you to save the contents of the event list to a text file. Saving 
information to a file enables you to print the output later or annotate the text file on-line. 

Choose Save from the File menu to save the event list information into the current working directory. A 
message box appears indicating the path to which Dr. Watcom saved the file. 

Choose Save As from the File menu to specify the file to which you want to save the information currently 
in the window. This opens a Save As dialog box where you select the desired file. Click on OK when 
completed. A message box appears indicating the path to which Dr. Watcom saved the event list. 

19.3.2 Dr. Watcom: Clearing the Event List 

Choose Clear from the File menu to delete all information from the event list. 

19.3.3 Dr. Watcom: Marking the Event List 

Use the Mark function to annotate the information in the event list by entering text into it. 

To mark the event list : 

(1) Choose Mark from the File menu. 

This opens the Set Mark dialog box. 
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Set Mark 


Enter mark text: 
event list messagej 


“Mark Style 

O plain boxed 


OK 


CANCEL 


Figure 179. With the Set Mark dialog, you can annotate the event list by entering text and choosing a mark 
style. 


(2) Type the desired text in the Enter Mark Text field. 

The text you enter will appear at the end of the event list 

(3) Select the desired Mark Style option. 

These options determine how the entered text is formatted when it is added to the event list When the 
boxed option is selected, the text is displayed bordered by asterisks. With this option the text is easier 
to find. When the plain option is selected, the text is displayed as it is entered. 

(4) Click on OK when completed. 

The Set Mark dialog closes and the text in the dialog appears at the end of the event list. 


Dr. WATCOM 


File Log lask Help 


TASK START: 

DLL LOAD: 

TASK EXIT: 

MODULE DEL: 

TASK START: 

TASK EXIT: 

MODULE DEL: 
********************** 
* event list message * 


********************** 


task id=ldl7, Initial CS:IP=lbf£:757a 
Module=WHEAPULK, Path=C:\WATCOM\BINW\UHEAPWLK.EXE 
module id=lbe7, initial CS:IP=lbbf:0000 
module 1 STRESS, path=C:\WATCOM\BINW\STRESS.DLL 
Task id=ldl7, rc=lc27 

id=lbS7, module=STRESS. path=C:\UATCOM\BINW\STRESS.DLL 
task id=lb0f. Initial CS:IP=lb5f:16e8 
Modu1e=UZOOM, Pa t h=C:\WATCOM\BINUMJZOOM.EXE 
Task id=lb0f, rc=0001 

id = lb07, modu1e=WZOOM, path=C:\WATCOM\BINW\WZOOM.EXE 


Figure 180. Text you enter in the Set Mark dialog appears in the event list in the selected style. 


19.3.4 Dr. Watcom: Setting the Fonts 

The Set Font item in the File menu allows you to set the font, style, and size for the text in the Dr. Watcom 
window. Choosing this item opens the Font dialog box. Select the desired font details and click on OK to 
close the dialog and apply the fonts. 
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19.3.5 Setting the Alert Feature 

Each time Dr. Watcom logs a debug message, its icon changes from a stethoscope to an explosion . This 
indicates that there is important information waiting for you in the event list. Some debug messages report 
only minor programming anomalies that may not be errors at all. The text for these messages is prefixed by 
wn, for warning. Because these messages are not urgent, you may not want the icon to signal the message. 
The Alert on Warnings menu item allows you to configure Dr. Watcom so that its icon does not change for 
these minor warning messages. 

When the Alert on Warnings item in the File menu is not checked, the icon does not change for minor 
warning messages. When this item is checked, the Dr. Watcom icon alerts you when a warning or serious 
error occurs. 

19.3.6 Showing the DIP status 

DIP’s (Debugging Information Processors) are Dynamic Link Libraries that Dr. Watcom loads to read 
debugging information. Each DIP allows Dr. Watcom to read a different type of debugging information. 
Choosing the Show DIP Status item from the File menu displays the Debugging Information Processor 
Status dialog. 


Debugging Information Processor Status 


Processor Status 


codeview 

loaded 

dwarf 

loaded 

export 

loaded 

watcom 

loaded 


OK 


Figure 181. The Debugging Information Processor Status dialog shows the DIP's Dr. Watcom has loaded. 

This dialog contains a list of all the DIP’s that Dr. Watcom attempted to load at startup and the results of 
those loads. If Dr. Watcom was unable to load a particular DIP then the dialog will show the reason for 
the failure. Dr. Watcom can only read a given type of debugging information if it has successfully loaded 
the appropriate DIP. 

19.3.7 Using the Clear Alert Function 

If you are running Dr. Watcom minimized then each time an error or warning is logged, the icon changes 
from a stethoscope to an explosion. Unless you reset the icon, you will not know when more events are 
added to the event list. 

There are two ways to reset the Dr. Watcom icon: 
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(1) Double click on the icon to view the event list, or 

(2) Choose Clear Alert from the system menu. 

To clear the alert message, click on the Dr. Watcom icon to reveal the system menu. Choose Clear Alert 
from the menu to change the icon back to the stethoscope. Dr. Watcom still logs the event, but you do not 
have to look at it immediately. 


19.4 Dr. Watcom: Exception Handling 

The Dr. Watcom exception dialog box appears on your screen when an exception occurs in any program in 
the system. This indicates that a fatal error has occurred. 



Figure 182. The exception dialog appears when a fatal error occurs in a program. 

Instead of terminating the program. Dr. Watcom suspends it and leaves its state intact. Because the state is 
undisturbed you can view the program’s state information from the exception dialog, including memory 
and register values. The exception dialog displays information about error and gives you several options. 
The information displayed about the error includes: 


Task Name 
Task Path 
Fault Type 
Fault CS:EIP 
Source Info 


The name of the module in which the error occurred. 

The full path of the file from which the offending module was loaded. 

The type of fault that occurred. 

The address of the instruction being executed when the fault occurred. 

The source line on which the error occurred. This only appears if the program running 
contains debugging information. 


There are four buttons on the exception dialog that you can use to proceed. 


Act When the act button is pressed. Dr. Watcom’s action is determined by the option currently 

selected in the action to take section of the dialog. The following describes the action taken 
for each option. 
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Terminate Task 

When the Terminate Task radio button is selected choosing Act causes the 
faulting task to be terminated immediately. 

Restart Instruction 

When the Restart Instruction radio button is selected choosing Act causes 
the faulting task to restart execution starting with the instruction pointed to 
by its CS:EIP. This option is primarily used to restart a task after you have 
changed its register values using the Task Status dialog. 

Chain to Next Handler 

A handler is a piece of code, a program, or a routine that gets called when 
an exception occurs. The system can have several exception handlers. 
When the Chain to Next Handler radio button is selected choosing Act 
passes the exception on to the next handler in the sequence, or chain. 

Act and Log Choosing the Act and Log button first creates a log file entry recording information about 
this fault then takes the same action that would result from choosing the Act button. 

Registers Select the Registers button to open the Task Status dialog. This dialog gives you additional 
information on the state of the program when it crashed. From this window you can change 
the registers and flags, view segment mappings, and do a stack trace. Refer to the section 
entitled "Examining the Task Status" for further information. 

Options Select the Options button to choose the information you want to write to the log file. This 

opens the Log File Options dialog explained in the section entitled "Customize the Log 
File" on page 329. 

19.4.1 Examining the Task Status 

The Task Status dialog appears when you choose the Registers button on the exception dialog. 
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Task Status 


Source Information 

Line 8 of D:\DEV\SDK\DRWAT\FAULTS\src\stack.c 


Registers 


DS: lba7 

EAX: 0000206e 

ES: oooo 

EBX: 00000000 

FS: oooo 

ECX: 00000015 

GS: oooo 

EDX: 00001ba7 

CS: icOf 

EIP: 00000027 

SS: lba7 

ESP: 00002074 

EBP: 00002082 

ESI: 00000000 

EDI: 0000003e 




E! Show Symbols 


'Instructions Around Fault 


crash_+17 MOV 

crash_+lc LES 

»crash_+1f MOV 

crash_+23 LEA 

crash_+26 POP 

crash_+27 POP 

crash_+28 POP 

crash_+29 POP 


WORD PTR [BP+00F4],0000 
BX,DWORD PTR [BP+00F2] 
BYTE PTR ES:[BX].0061 
SP.[BP+00F6] 

DI 

SI 

DX 


Figure 183. The Task Status dialog provides additional information on the program state when the 
exception occurred. 


This dialog displays information in four sections: 


• Source Information 

• Registers 

• Flags 

• Instructions Around Fault 


The Source Information section indicates the source file where the error occurred and the 
file. In order to get source information, your program must have debugging information, 
the Source Information section if the program does not contain debugging information or 
occurred on an assembly instruction that does not correspond to a source file. 

The Registers and Flags sections display information in the CPU at the time of the exception. 

The Instructions Around Fault section displays the assembly instructions surrounding the instruction that 
was being executed when the fault occurred. An asterisk marks the instruction to which the CS:EIP is 
currently pointing. 

When the Show Symbols box is checked. Dr. Watcom tries to replace addresses in the assembly code with 
symbolic names. Dr. Watcom can only replace addresses if the faulting module contained debugging 
information. If this box is not checked, addresses are left as numeric values. 


line of that source 
N/A appears in 
the exception 


19.4.1.1 Dr. Watcom: Changing the Registers 

In the Task Status dialog you can set up testing and debugging situations by changing the register and flag 
values. To change a register value simply enter a new value in the edit field that contains the current 
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register value. To change the state of a flag register just check or uncheck the check box associated with 
that flag. A flag has a value of 1 when its check box is checked. 

The register and flag values will not take effect until you choose OK on the Task Status dialog. 

19.4.1.2 Dr. Watcom: Applying Registers 

Choosing Apply Registers updates the information in the Task Status dialog based on values of registers 
and flags to which you have made changes. 

19.4.1.3 Dr. Watcom: Segment Mapping 

Choosing Segment Map from the Task Status dialog opens a Segment Map dialog box which indicates the 
selectors to which your map segments were mapped. There is one entry for every segment in the program. 


Segment Map 


Double click segment to view 



OK 


Figure 184. The Segment Map dialog lists the selectors to which the segments were mapped. 


This dialog allows you to view the data contained in each of your program’s segments. To view this 
memory, double click on the desired segment. This opens a Memory Display window for the selected 
segment. 


5 


Memory Display for handle 1 COE 



~^1 

File Display 

Set Offset... 
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Figure 185. The Memory Display window displays the memory stored in the selected segment. 


The Memory Display window displays all of the data stored in the selected segment. This information 
appears in hexadecimal form. This allows you to see if the data in memory is what you believe it should 
be. 


There are a number of functions you can perform in the Memory Display window. Following is a 
description of these functions. 
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Dr. Watcom: Saving Window Information 

The Save items in the File menu of the Memory Display window allow you to save the current window 
information to a text file. Choosing Save from the File menu in the Memory Display window saves the 
data in the window into the current working directory. A message box appears indicating the path to which 
Dr. Watcom saved the file. 

Choosing Save As from the File menu allows you to specify the file to which you want to save the 
information currently in the window. This opens a Save As dialog box where you select the desired file. 
Click on OK when completed. A message box appears indicating the path to which Dr. Watcom saved the 
file. 

Dr. Watcom: Changing the Display 

There are five ways to display the information on the Memory Display window. You can display the 
information as: 

• Bytes 

• Words 

• DWords 

• 16 Bit Code 

• 32 Bit Code 

To change the form of the displayed data, select an item from the Display menu. When displaying data in 
bytes, the data appears in the window as it physically appears in memory. When the data is displayed as 
words, the bytes in memory are interpreted for you so that the values displayed are those that would be 
obtained by treating the memory as an array of words. For example, if memory containing the values: 

12 34 56 78 9A BC DEFF 

was shown as words, the memory window would display: 

3412 7856 BC9A FFDE 

A similar interpretation is performed when the data is displayed as DWords. If the above memory was 
shown as DWords, the memory window would display: 

78563412 FFDEBC9A 

This rearrangement of bytes does not affect the textual interpretation of the data shown on the right hand 
side of the window. 

Selecting 16 or 32 Bit Code from the Display menu presents the data in a disassembled form. Sometimes 
presenting the data in disassembled form is not accurate. This is because when Dr. Watcom disassembles 
the data it begins at the first byte of the memory block and disassembles it linearly. If a byte in this block, 
such as a padding byte, throws off the sequence, the disassembly will be meaningless. 

Dr. Watcom: Setting the Offset 

On the Memory Display window you can set the offset. This means that you can reposition the data so that 
the specified line appears at the top of the window. The offset you enter appears on the first line. It will 
not necessarily be the first piece of information because rounding often occurs to avoid breaking a line. 
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(1) Choose Set Offset from the menu bar on the Memory Display window. 
This opens a Goto Offset dialog box. 



Figure 186. In the Goto Offset dialog, enter the offset you want to appears at the top of the Memory 
Display window. 

(2) Enter the desired offset that you want to position at the top of the Memory Display window. You 
can enter the offset in decimal or hexadecimal form. However, you must prefix hexadecimal values 
with Ox. 

(3) Click on OK. 

This closes the dialog and positions the data as requested. 

Dr. Watcom: The Handle Information Dialog Box 

A Handle Information dialog box attached to the Memory Display window provides the following 
information: 

• Block Address 

• Block Handle 

• Block Size 

• Lock Count 

• Page Lock Count 


Handle Information 

Block Address: 

00008EC0 

Block Handle: 

1 COE 

Block Size: 

0380 

Lock Count: 

0000 

Page Lock Count: 

0000 


Figure 187. The Handle Information dialog box displays information about the memory object displayed in 
the Memory Display Window. 

This box stays with the window when the Auto Position Info item under the File menu is checked. 
Deactivate this function by selecting the item again from the File menu. 
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If the Handle Information dialog is not visible, reveal it by choosing Show Info from the File menu in the 
Memory Display window. Close this dialog by double clicking on the system menu box in its upper left 
hand corner. 

19.4.1.4 Performing a Stack Trace 

A program is made up of a series of functions. A function executes when it is called by the operating 
system or another function. When completed it returns to the point in the code from which it was called. 

Whenever a function is called, a stack frame is pushed onto the stack. When the function returns, the stack 
frame is popped from the stack. The stack frame contains information about the point from which the 
function was called and to which it will return. The collection of stack frames currently on the stack is 
called a call chain. 

The stack trace function lets you walk the call chain. This allows you to determine where each function in 
the call chain was called from and where it will return to. To perform a stack trace, click on the Stack 
Trace button in the Task Status dialog to reveal the Stack Trace dialog. 


Stack Trace: STACK 


Instructions Around Call 


♦ 

test6_+d 

PUSH 

DI 


test6_+e 

SUB 

SP.0000 


test6_+12 

CALI 

crash_ 


*test6_+15 

LEA 

SP.[BP+00F6] 


testS_+18 

POP 

DI 


testS_+19 

POP 

SI 


test6_+la 

POP 

DX 


test6_+lb 

POP 

CX 

♦ 

CS:IP = lcOf 

004a 

SS:BP = lba7:2090 



Cancel 


Next ... 


Previous 


Source Information: 

Line 13 of D:\DEV\SDK\DRWAT\FAULTS\src\stack.c 


Figure 188. The Stack Trace dialog allows you to walk the call chain. 


When the Stack Trace dialog opens, it contains information from the stack frame for the function that was 
executing at the time of the fault. The Instructions Around Fault section displays the assembly instructions 
around the call to the faulting function. The instruction directly after the call to the faulting function is 
marked with an asterisk. Other information includes the address of this instruction (CS:IP) and the base 
stack pointer (SS:BP) at the time of the call. If the faulting module contained debugging information and 
the marked assembly instruction corresponds to a source line, then source file information appears. 


Selecting the Next button displays information from the next oldest stack frame. This is information about 
the point from which the currently displayed function was called. If the currently displayed function was 
called by the operating system, then the message "No more stack frames!" appears because there are no 
stack frames for calls made from the operating system. 


Selecting the Prev button displays information from the next most recent stack frame. This moves you in 
the opposite direction along the call chain as pressing the Next button. 


The Cancel button closes the window. 
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19.4.2 Resetting the Fault Handled Flag 

The Reset Fault Handled Flag menu item is only accessible when an exception occurs from which Dr. 
Watcom is unable to recover. When such an error occurs. Dr. Watcom cannot log exceptions or be 
terminated until you choose Reset Fault Handled Flag from the File menu. This will not happen frequently. 

19.5 Dr. Watcom: Working with Log Files 

A log file is a text file created by Dr. Watcom. The log file consists of entries that describe the state of the 
system at the time the entry was made. Dr. Watcom gives you the opportunity to create a log file entry 
each time an exception occurs. Such entries include information about the state of the program that caused 
the exception, as well as information about the state of the system. You can create a log file entry at any 
time using the Log Current State menu item in the Log menu. 

A log file is a permanent record of the state of the system and, possibly, your program. With a log file you 
can make note of an error and return to it at a later time to examine and debug the problem. 

19.5.1 Log the Current State 

Choose Log Current State from the Log menu to write to the current log file. This tells Dr. Watcom to 
create a log file entry with all of the log details except the Offending Task Information. The settings in the 
Log Options dialog determine the information written to the log file. 

The Log Current State item is also available on the system menu. 

19.5.2 Erase the Log File 

To erase the current log file, choose Erase Log File from the Log menu. This erases the log file specified in 
the Log File Options dialog. 

Choosing this item reveals a message box which asks you to verify that you want to erase the specified log 
file. Select yes to erase the log file or No to cancel the request. 

19.5.3 Customize the Log File 

The Log Options item in the Log menu opens the Log Options dialog where you indicate to Dr. Watcom 
the information you want to appear in log file entries. The Log Options item is also available from the 
system menu. 
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Log File Options 


Log File Name 


c:\watcom\dfltJ.log 


Browse 


Log File Data 
G GDI Heap Info 
G Current Tasks 
G All Modules 
G Stack Trace 


User Heap Info 
Module Segments 
Mem Manager Info 
Query for Notes 


Disassembly Options" 
Di sasm Backu p: 

4 


Disasm Lines: 


10 


"Log Options 
G Auto Log 


Max Log File Size: 


70000 


OK 


Cancel 


Figure 189. In the Log Options dialog, you customize the log file to which you write information. 
The following sections describe the options that make up the Log Options dialog. 


19.5.3.1 Dr. Watcom: Naming the Log File 

In the Log File Name field you can specify the file to which Dr. Watcom writes the log file entries. The 
Browse button to the right of this field opens the Pick Log Filename dialog. This dialog lets you browse 
your file structure and select the path to which Dr. Watcom writes the log file entries. 


19.5.3.2 Dr. Watcom: Specifying the Log File Data 

In the Log File Data and Disassembly Options sections of the Log File Options dialog you select the 
information you want to appear in the log file. The Log File Data section lists the various types of 
information that can be included in a log file. If the check box for a piece of information is marked then 
that type of information will be written to the log file. The options in this section are: 

Stack Trace When this option is selected stack trace information for the application that caused the 
exception is written when a log file entry is made. This option only affects log entries 
made due to exceptions. 

Current Tasks 

When this option is selected a list of all tasks currently running in the system, including 
information about each task is included in each log entry. 

All Modules When this option is selected a list of all modules currently loaded in the system, including 
information about each module is included in each log entry. 
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GDI Heap Info 

When this option is selected summary information about the state of the GDI local heap is 
included in each log entry. 

User Heap Info 

When this option is selected summary information about the state of the User local heap is 
included in each log entry. 

Mem Manager Info 

When this option is selected summary information about the state of the virtual memory 
manager is included in each log entry. 

Module Segments 

When this option is selected log file entries list the selectors for each module currently 
loaded in the system. The All Modules option must also be selected to write this 
information. 

Query for Notes 

When the Query for Notes option is selected Dr. Watcom displays an Annotate Log dialog 
whenever a log file entry is made. This dialog lets you enter some explanatory text that 
will be included in the log file entry. 



Figure 190. In the Annotate Log dialog box, enter text you want to include in the log file entry. 

Enter any text you want to include in the space provided. Press the OK button to include 
this text in the log file. If you press the Cancel button Dr. Watcom continues to create the 
log file entry but does not include any information from the dialog. 

The values in the Disassembly Options box only affect log entries made due to exceptions. These values 
relate to the disassembly section appearing in the log file. The value in the Disasm Backup field tells Dr. 
Watcom the number of instructions before the fault you want written to the log file. The value in the 
Disasm Lines field tells Dr. Watcom the total number instructions you want it to show in the log file. This 
value includes the instructions displayed before the fault. 
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19.5.3.3 Dr. Watcom: Other Options 

If the Auto Log option is selected. Dr. Watcom creates a log file when an exception occurs and then 
terminates the application that caused the fault instead of revealing the exception dialog. The Auto Log 
option is useful when running test streams. 

The Max Log File Size field allows you to set the maximum size in bytes for a log file. When the log file 
exceeds this size, Dr. Watcom prompts you with a message box when you start the application. 



Figure 191. A message box prompts you to erase the log file when it becomes larger than the maximum log 
file size specified on the Log File Options dialog. 

This message box offers you the opportunity to delete your log file before it becomes uncontrollably large. 

19.6 Performing Task Control 

Choosing Task Control from the Task menu or the System menu opens the Task Control dialog. This 
dialog displays a Task List which consists of all programs currently running under Windows. The Task 
Control dialog lets you terminate and debug tasks. 

The task list in the Task Control dialog is different from the system Task List which appears when you 
double click on the wallpaper. The system Task List list displays only applications that currently have a 
window open on the desktop. The task list in the Task Control dialog lists all tasks regardless of whether 
they have a window open. 

19.6.1 Terminating a Task 

The Kill Task button on the Task Control dialog terminates a task listed in the Task List. This function is 
extremely powerful. It allows you to terminate programs immediately without giving them the opportunity 
to clean up by saving data, unloading DLLs, and freeing allocated memory. 

For this reason, you should exercise care when using this function. It is wise to only use the Kill Task 
function for tasks that cannot be terminated in the usual way. 
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To terminate a task: 

(1) Choose Task Control from the Task menu. 

This opens the Task Control dialog containing a list of all tasks currently running in the system. 


Task Control 


T ask List 


CODEVIEW cs 
DWARF cs 
EXPORT cs 
PROGMAN cs 
WATCOM cs 
WBRUN20 cs 


ip=13cf:00e8 
ip=121f:00e8 
ip=llbf:00e8 
ip=02bf:OOdc 
ip=1277:00e8 
ip=ld2f. 03c0 


id=2047 
id=19d7 
id=27df 
id=0657 
id=205f 
id=lfc7 


WHEAPWLK cs:io=118f:0240 id=14c7 


WZOOM 


cs:ip=la9f:0136 id=labf 


Close 


Kill Task 


Debug Task 


Selected Task: 

WHEAPWLK cs:ip=1181:0240 
id=14c7 


Figure 192. In the Task Control dialog, you can terminate a task selected from the Task List. 


(2) Select the task you want to terminate by clicking on its entry in the task list. 

(3) Select the Kill Task button. 

This terminates the selected task, removing it from the task list. Dr. Watcom enters this event in the 
event list. 


19.6.2 Debugging a Task 

Use the Debug Task button on the Task Control dialog to attach the debugger to the selected task from the 
Task List. 

To debug a task: 

(1) Choose Task Control from the Task menu. 

This opens the Task Control dialog containing a list of all tasks currently running in the system. 

(2) Select the task you want to debug by clicking on its entry in the task list. 

(3) Select the Debug Task button. 

This opens the Debugger Options dialog box. 
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Figure 193. In the Debugger Option dialog, you enter the command line options to pass to the debugger. 

(4) Enter the command line options you want Dr. Watcom to pass to the debugger. 

(5) Click on OK. 

This starts the debugger. 
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20 Dr. Watcom for Win32 


20.1 Introduction 


The 32-bit version of Dr. Watcom is a post-mortem debugger for Win32 applications. When an exception 
occurs in a program, a post-mortem debugger allows you, after the fact, to examine the state of both the 
program and the system in order to determine the cause of the exception. In addition to being a debugging 
tool. Dr. Watcom is a system utility that enables you to examine and modify process information. 

Note: Use the 32-bit version of Dr. Watcom to monitor native (Win32) applications running 

under Windows 9x and NT based operating systems. Use the 16-bit version of Dr. 
Watcom to monitor 16-bit Windows (Winl6) applications. 

20.2 Using Dr. Watcom 

This section discusses the following topics: 

• Starting Dr. Watcom 

• Quitting Dr. Watcom 

• The Dr. Watcom Menu Bar 

Dr. Watcom is designed to be used effectively while minimized. You can access some of Dr. Watcom’s 
main functionality using the system menu while the application is minimized. This includes the Log 
Current State, Log Options, and Process Control menu items. 

20.2.1 Starting Dr. Watcom 

To start Dr. Watcom double click on the Dr. Watcom icon. This opens the Dr. Watcom window. 

Note: You can run only one instance of Dr. Watcom at a time. 

20.2.2 Quitting Dr. Watcom 

To exit Dr. Watcom, choose Exit from the File menu of the Dr. Watcom window. 

20.2.3 The Dr. Watcom Menu Bar 

The Menu bar consists of the following four menus: 
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File 

Log 

Process 

Help 


Save to a file and work with the event list a file 
Work with the log file 

Work with processes currently running under Windows 
Access on-line help information 


20.3 Using the Dr. Watcom Window 


When you open Dr. Watcom, a window appears which contains the event list. The event list records 
events generated by processes to which Dr. Watcom is attached. To record these events you must first 
attach Dr. Watcom to the desired processes. To perform this function, refer to the section entitled 
"Attaching Processes to Dr. Watcom" on page 349. Some examples of events are errors, the starting and 
ending of threads, and the loading and unloading of DLLs. 


Dr. WATCOM 


File Log Task Help 


Dr. WATCOM started 
Will Use WDEBUG.386 


DLL LOAD: 

TASK EXIT: 
MODULE DEL: 
TASK START: 

DLL LOAD: 

TASK EXIT: 
MODULE DEL: 
MODULE DEL: 


module id=118f 
module=WINT32, 
Task. id=112f , 
id=2067, modul 
task id=206f, 
Modu1e=WZOOM, 
module id=1087 
module=CTL3D, 
Task id=206f, 
id=2067. modul 
id=2067, modul 


initial CS:IP=1187:024a 
path=C:\WATCOM\BINW\WINT32 .DLL 
rc=105f 

e=STRESS, path=C:\WATCOM\BINW\STRESS.DLL 
Initial CS:IP=1077:16e8 
Path=C:\WATCOM\BINW\WZOOM.EXE 
initial CS:IP=1097:3340 
path=C: \WATCOM\BINW\CTL3D. DLL 
rc=203£ 

e=CTL3D, path=C:\WATCOM\BINW\CTL3D.DLL 
e-WZOOM, pa t h=C:\WATCOM\BINWNWZOOM.EXE 


Figure 194. The Dr. Watcom window contains the event list where occurring events are recorded. 


The following sections describe functions that allow you to manipulate the event list: 

• Saving the Event List 

• Clearing the Event List 

• Marking the Event List 

• Setting the Fonts 


20.3.1 Dr. Watcom: Saving Event List Information to a File 

The Save items in the File menu allow you to save the contents of the event list to a text file. Saving 
information to a file enables you to print the output later or annotate the text file on-line. 

Choose Save from the File menu to save the event list information into the current working directory. A 
message box appears indicating the path to which Dr. Watcom saved the file. 

Choose Save As from the File menu to specify the file to which you want to save the information currently 
in the window. This opens a Save As dialog box where you select the desired file. Click on OK when 
completed. A message box appears indicating the path to which Dr. Watcom saved the event list. 
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20.3.2 Dr. Watcom: Clearing the Event List 

Choose Clear List from the File menu to delete all information from the event list. 

20.3.3 Dr. Watcom: Marking the Event List 

Use the Mark function to annotate the information in the event list by entering text into it. 
To mark the event list: 

(1) Choose Mark from the File menu. 

This opens the Set Mark dialog box. 


Set Mark 


Enter mark text: 


event list messagej 


Mark Style 
O plain 


boxed 


OK 


CANCEL 


Figure 195. With the Set Mark dialog, you can annotate the event list by entering text and choosing a mark 
style. 

(2) Type the desired text in the Enter Mark Text field. 

The text you enter will appear at the end of the event list 

(3) Select the desired Mark Style option. 

These options determine how the entered text is formatted when it is added to the event list When the 
boxed option is selected, the text is displayed bordered by asterisks. With this option the text is easier 
to find. When the plain option is selected, the text is displayed as it is entered. 

(4) Click on OK when completed. 

The Set Mark dialog closes and the text in the dialog appears at the end of the event list. 
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Dr. WATCOM 


File Log lask Help 


TASK START: 

DLL LOAD: 

TASK EXIT: 
MODULE DEL: 
TASK START: 

TASK EXIT: 
MODULE DEL: 


task id=ldl7, Initial CS:IP=lbff:757a 
Module=¥HEAP¥LK, Path=C:\¥ATCOM\BIN¥\¥HEAP¥LK.EXE 
module id=lbe7, initial CS:IP=lbbf:0000 


module=STRESS, path=C:\¥ATCOM\BIN¥\STRESS.DLL 
Task id=ld!7, rc=lc27 


id=lb57, module=STRESS, path=C:\¥ATCOM\BIN¥\STRESS.DLL 
task id=lb0f. Initial CS:IP=Tb5f:16e8 
Modu1e=¥ZOOM. Pa t h=C:\¥ATCOM\BIN¥\¥ZOOM.EXE 
Task id=lb0f, rc=0001 


id=Tb07, modu1e=¥ZOOM, path=C:\¥ATCOM\BIN¥\¥ZOOM.EXE 


********************** 

* event list message * 


********************** 


Figure 196. Text you enter in the Set Mark dialog appears in the event list in the selected style. 


20.3A Dr. Watcom: Setting the Fonts 

The Set Font item in the File menu allows you to set the font, style, and size for the text in the Dr. Watcom 
window. Choosing this item opens the Font dialog box. Select the desired font details and click on OK to 
close the dialog and apply the fonts. 


20.4 Debugging Information Processors 

Debugging Information Processors (DIP’s) are Dynamic Link Libraries that Dr. Watcom loads to read 
debugging information. Each DIP allows Dr. Watcom to read a different type of debugging information. 

20.4.1 Using the Debugging Information Processor Status dialog 

Choosing the Show DIP Status item from the File menu displays the Debugging Information Processor 
Status dialog. 


Debugging Information Processor Status 


Processor Status 


codeview 

loaded 

dwarf 

loaded 

export 

loaded 

watcom 

loaded 


OK 


Figure 197. The Debugging Information Processor Status dialog shows the DIP’s Dr. Watcom has loaded. 
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This dialog contains a list of all the DIP’S that Dr. Watcom attempted to load at startup and the results of 
those loads. If Dr. Watcom was unable to load a particular DIP then the dialog will show the reason for 
the failure. Dr. Watcom can only read a given type of debugging information if it has successfully loaded 
the appropriate DIP. 


20.5 Dr. Watcom: Exception Handling 

When a fatal error, or exception, occurs in a process to which Dr. Watcom is attached. Dr. Watcom 
intercepts the exception. By intercepting the exception, Dr. Watcom halts the program’s execution to 
prevent it from terminating. When an exception occurs, a Dr. Watcom exception dialog box appears on the 
screen indicating that a fatal error has occurred. This dialog displays information about the error and gives 
you several options. 



Figure 198. The exception dialog appears when a fatal error occurs in a program. 
The information displayed about the error includes: 


Process Name The name of the process in which the error occurred. 

Process ID The unique identifier associated with the process. 

Fault Type The type of fault that occurred. 

Fault CS:EIP The address of the instruction being executed when the fault occurred. 

Source Info The source line on which the error occurred. This only appears if the program running 

contains debugging information and the exception occurred on an assembly instruction that 
corresponds to a source line. 

There are four buttons on the exception dialog that you can use to proceed. 


Act When the Act button is pressed Dr. Watcom’s action is determined by the option currently 

selected in the "action to take" section of the dialog. The following describes the action 
taken for each option. 
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Terminate Task 

When the Terminate Task radio button is selected choosing Act causes the 
faulting process to be terminated immediately. 

Restart Instruction 

When the Restart Instruction radio button is selected choosing Act causes 
the faulting process to restart execution starting with the instruction pointed 
to by its CS:EIP. This option is primarily used to restart a process after you 
have changed its register values using the Process Status dialog. 

Chain to Next Handler 

A handler is a piece of code, a program, or a routine that gets called when 
an exception occurs. A process can have several exception handlers. 

When the Chain to Next Handler radio button is selected choosing Act tells 
the operating system to continue searching for a handler to deal with this 
exception. If no handler is found for the exception then Dr. Watcom will 
redisplay the exception dialog to give you a second chance to deal with the 
exception. During this second chance notification the chain to next handler 
option is not available. This option is useful for testing your own exception 
handling code. 

Act and Log Choosing the Act and Log button first creates a log file entry recording information about 
this exception then takes the same action that would result from choosing the Act button. 

Select the Registers button to open the Process Status dialog. This dialog gives you 
additional information on the state of the process when the exception occurred. From this 
window you can change the registers and flags and view the process’s address space. Refer 
to the section entitled "Examining the Process Status" for further information. 

Select the Options button to choose the information you want to write to the log file. This 
opens the Log Options dialog explained in the section entitled "Customizing the Log File" 
on page 347. 

20.5.1 Using External Exception Handlers 

You can use the Continue Exceptions item in the file menu to tell Dr. Watcom to only report on exceptions 
that are not handled by another exception handler. When this item is checked Dr. Watcom only displays 
an exception dialog if the system is unable to find a handler for an exception. This behavior is the same as 
when Continue Exceptions is not checked and chain to next handler is selected on the exception dialog. 

20.5.2 Examining the Process Status 

The Process Status dialog appears when you choose the Registers button in the exception dialog. 

This dialog displays information in four sections: 

• Source Information 

• Registers 

• Flags 

• Instructions Around Fault 


Registers 


Options 
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The Source Information section indicates the source file where the error occurred and the line of that source 
file. In order to get source information, your program must contain debugging information. N/A appears in 
the Source Information section if the program does not contain debugging information or the exception 
occurred on an assembly instruction that does not correspond to a source file. 

The Registers and Flags sections display information in the CPU at the time of the exception. 

The Instructions Around Fault section displays the assembly instructions surrounding the instruction that 
was being executed when the fault occurred. An asterisk marks the instruction to which the CS:EIP is 
currently pointing. 

When the Show Symbols box is checked. Dr. Watcom tries to replace addresses in the assembly code with 
symbolic names. Dr. Watcom can only replace addresses if the faulting module contained debugging 
information. If this box is not checked, addresses appear as numeric values. 

20.5.2.1 Dr. Watcom: Changing the Registers 

In the Process Status dialog you can set up testing and debugging situations by changing the values of the 
registers and flags. To change a register value simply enter a new value in the edit field that contains the 
current register value. To change the state of a flag register just check or uncheck the check box associated 
with that flag. A flag has a value of 1 when its check box is checked. 

The register and flag values will not take effect until you choose OK on the Process Status dialog. 

20.5.2.2 Dr. Watcom: Applying Registers 

Selecting the Apply Registers button on the Process Status dialog after making changes to the registers and 
flags updates the displayed information based on your changes. 

20.5.2.3 Dr. Watcom: Viewing Memory 

Selecting the View Memory button in the Process Status dialog opens a Memory Walk window which 
allows you to view the address space of the process that caused the exception. 

The information in this window appears under the following headings: 

Base This is the address where this memory object begins. 

AlIocBase The is the address where the allocation object begins. This tells you which allocation 

object a memory object belongs to. 

Size This is the size of the memory object. 

Prof Codes indicating what you can do with the memory. The codes are: 

• RO—Read Only 

• NA—Not applicable 

• ExRO—Executable and Read Only 

• RW—Read, Write 

• WC—Write, Copy 

• Ex—Executable 

• ExRW—Executable, Read, Write 
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• ExWC—Executable, Write, Copy 

State The state of the memory. Values are: 

• Free—range of addresses not being used 

• Committed—range of addresses refers to memory that exists 

• Reserved—this range of addresses has been set aside for future use but no memory 
exists for the addresses 

Object Information indicating what the memory is being used for. This field is only completed if 

Dr. Watcom can provide useful information. 

Image The name of the module that owns the memory object. This field is only completed if Dr. 

Watcom can provide useful information. 

From this window you can select a memory object and view its contents. To view this information, double 
click on the desired object. This opens a Memory Range window for the selected object. This window 
displays all of the data stored in the selected object. The data appears in hexadecimal form. This window 
allows you to see if the data in memory is what you believe it should be. 

Note: You can only view memory for an object whose state is Committed since there is no 

memory associated with other objects. 

There are a number of functions you can perform in the Memory Range window. Following is a 
description of these functions. 

Dr. Watcom: Saving Window Information 

The Save items in the File menu on the Memory Range window allows you to save the currently displayed 
information to a text file. Choosing Save from the File menu on the Memory Range window saves the data 
in the window into the current working directory. A message box appears indicating the path to which Dr. 
Watcom saved the file. 

Choosing Save As from the File menu allows you to specify the file to which you want to save the data 
currently in the window. This opens a Save As dialog box where you select the desired file. Click on OK 
when completed. A message box appears indicating the path to which Dr. Watcom saved the file. 

Dr. Watcom: Changing the Display 

There are three ways to display the information in the Memory Range window. You can display the 
information as: 

• Bytes 

• Words 

• DWords 

To change the form of the displayed data, select an item from the Display menu. When displaying data in 
bytes, the data appears in the window as it physically appears in memory. When the data is displayed as 
words, the bytes in memory are interpreted for you so that the values displayed are those that would be 
obtained by treating the memory as an array of words. For example, if memory containing the values: 

12 34 56 78 9A BC DE FF 
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was shown as words, the memory window would display: 

3412 7856 BC9A FFDE 

A similar interpretation is performed when the data is displayed as DWords. If the above memory was 
shown as DWords, the memory window would display: 

78563412 FFDEBC9A 

This rearrangement of bytes does not affect the textual interpretation of the data shown on the right hand 
side of the window. 

Dr. Watcom: Setting the Offset 

In the Memory Range window you can set the offset. This means that you can reposition the data so that 
specific information appears at the top of the window. The offset you enter appears on the first line. It will 
not necessarily be the first piece of information because rounding often occurs to avoid breaking a line. 

(1) Choose Set Offset from the menu bar on the Memory Display window. 

This opens a Goto Offset dialog box. 

(2) Enter the desired offset that you want to position at the top of the Memory Range window. You can 
enter the offset in decimal or hexadecimal form. However, you must prefix hexadecimal values with 
Ox. 

(3) Click on OK. This closes the dialog and positions the data as requested. 



Figure 199. In the Goto Offset dialog, enter the offset you want to appear at the top of the Memory Display 
window. 


20.6 Dr. Watcom: Working with Log Files 

A log file is a text file created by Dr. Watcom. The log file consists of entries that describe the state of the 
system at the time the entry was made. Dr. Watcom gives you the opportunity to create a log file entry 
each time an exception occurs. Such entries include information about the state of the program that caused 
the exception, as well as information about the state of the system. You can create a log file entry at any 
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time using the Log Current State menu item. Log entries made in this way only contain information about 
the state of the system. 

A log file is a permanent record of the state of the system and, possibly, your program. With a log file you 
can make note of an error and return to it at a later time to examine and debug it. 

20.6.1 Creating A Log File Entry 

You can create a log file entry at any time by selecting Log Current state from the Log menu or the system 
menu. You can also create a log file entry when an exception occurs by choosing the Act and Log button 
on the Exception dialog. 

When a log entry is created the following dialogs may be displayed: 

• Annotate Log 

• Memory Dump 

20.6.1.1 Using the Annotate Log Dialog 

When the Query for notes option in the Log Options dialog is selected, an Annotate Log dialog box appears 
whenever a log entry is created. 

In the space provided, enter any explanatory text that you want to include in the log file. Press OK when 
completed. This information appears under the heading "User Notes" at the beginning of the log file. 

20.6.1.2 Using the Memory Dump Dialog 

When the Memory Dump option in the Log Options dialog is selected. Dr. Watcom displays the Log 
Memory Dump dialog whenever a log entry is created because of an exception. This dialog displays a list 
of all committed pages of memory owned by the process that caused the exception. 

This dialog allows you to select the memory objects you want to include in the log file entry. The data 
contained in any memory object highlighted in the list box will be written to the log file. Clicking on an 
object in the list box toggles it between selected and unselected. 

The following buttons are available on the dialog: 

Select All Selects all memory for dumping to the log file 

Clear All De-selects all memory currently selected in the dialog 

Cancel Closes the dialog and continues writing to the log file but does not include information on 

any of the memory objects in the dialog 

OK Closes the dialog and writes selected objects to the log file 
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20.6.2 Viewing the Current Log File 

Choosing View Log from the Log menu invokes an editor which allows you to view the current log file. 
You can select this editor in the Log Viewer section of the Log Options dialog. 

20.6.3 Erasing the Log File 

To erase the current log file, choose Erase Log File from the Log menu. This erases the log file specified in 
the Log Options dialog. 

Choosing this item reveals a message box which asks you to verify that you want to erase the specified log 
file. Select Yes to erase the log file or No to cancel the request. 

20.6.4 Customizing the Log File 

The Log Options item in the Log menu opens the Log Options dialog where you indicate to Dr. Watcom 
the information you want to appear in log file entries. The Log Options item also appears in the system 
menu. 


Log File Options 


Log File Name 


c:\watcom\dfltJ.log 


Browse 


Log File Data 
ES GDI Heap Info 
Current Tasks 
SI All Modules 
S Stack Trace 


User Heap Info 
Module Segments 
Mem Manager Info 
Query for Notes 


Disassembly Options" 
Di sasm Backu p: 

4 


Disasm Lines: 


10 


'Log Options 
D Auto Log 


Max Log File Size: 


70000 


OK 


Cancel 


Figure 200. In the Log Options dialog, you customize the log file to which you write information. 
The following sections describe the options that make up the Log Options dialog. 


20.6.4.1 Dr. Watcom: Naming the Log File 

In the Log File field, you specify the file to which Dr. Watcom writes the log file entries. The Browse 
button to the right of this field opens the Pick log file name dialog. This dialog lets you browse your file 
structure and select the path to which Dr. Watcom writes the log file entries. 
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20.6.4.2 Dr. Watcom: Choosing the Log Viewer 

In the Log Viewer field, you specify the editor you want to invoke when you select View Log from the Log 
menu. The Browse button to the right of this field opens the Pick log viewer dialog. This dialog lets you 
browse your file structure and select the desired editor. 

When View Log is selected from the Log menu, this editor will be invoked with the name of the log file 
passed as a command line parameter. 

20.6.4.3 Dr. Watcom: Specifying the Log File Data 

In the Log File Data and Disassembly Options sections of the Log Options dialog, you select the 
information you want to appear in the log file. The Log File Data section lists the various types of 
information that can be included in a log file. If the check box for a piece of information is marked then 
that type of information will be written to the log file. The options in this section are: 

Memory Dump 

When this box is checked, a Memory Dump dialog is displayed whenever a log file entry is 
made. This dialog allows you to select the regions of memory you want to dump into the 
log file and is discussed in the section entitled "Creating A Log File Entry" on page 346. 

This option only affects log file entries created because of an exception. 

Query for notes 

When this box is checked, an Annotate Log dialog is displayed whenever a log file entry is 
made. This dialog lets you enter text to be included in the log file entry. The Annotate Log 
dialog is discussed in the section entitled "Creating A Log File Entry" on page 346. 

Loaded modules 

When this box is checked, each log file entry includes a list of all modules loaded for each 
process running in the system. 

Current Processes 

When this box is checked, each log file entry includes a list of all processes currently 
running in the system, including information about each process. 

Mem Manager Info 

When this box is checked, log file entries will include summary information on the memory 
usage of the process that caused the exception. This option affects only log file entries 
created because of an exception. 

The fields in the Disassembly Options section relate to the disassembly section appearing in the log file. 
These fields affect only log file entries made because of exceptions. 

• The value in the Disasm Backup field tells Dr. Watcom the number of instructions before the fault 
you want written to the log file. 

• The value in the Disasm Lines field tells Dr. Watcom the total number of instructions you want it to 
show in the log file. This value includes the instructions displayed before the fault. 
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20.6.4.4 Dr. Watcom: Other Options 

When the Auto Log option is selected, Dr. Watcom creates a log file when an exception occurs and then 
terminates the application instead of revealing the exception dialog. 

The Max Log File Size option allows you to set the maximum size in bytes for a log file. When the log file 
exceeds this size. Dr. Watcom prompts you with a message box when you start the application. 



Figure 201. A message box prompts you to erase the log file when it becomes larger than the maximum log 
file size specified on the Log File Options dialog. 

This message box offers you the opportunity to delete your log file before it becomes uncontrollably large. 

20.7 Attaching Processes to Dr. Watcom 

Attaching processes to Dr. Watcom enables it to monitor events that occur within the processes. When 
processes are attached. Dr. Watcom reports on events that occur within your process, such as DLL loads, 
thread creations, and thread terminations. Attaching also allows Dr. Watcom to detect exceptions in your 
process. 

There are four ways to attach processes to Dr. Watcom: 

• Command line 

• Add New process menu item 

• Auto Add Process feature 

• Process Control dialog 

Dr. Watcom cannot detach from processes to which it is attached. The attachment exists until the process 
terminates. If you try to close Dr. Watcom while it is attached to processes, a warning box appears listing 
the processes to which Dr. Watcom is still attached. 

Select Yes or No to continue. 

20.7.1 Command Line 

You can run a program and attach Dr. Watcom to it at start-up by passing the path of the executable to Dr. 
Watcom as a command line parameter. For example, to run the program f oo . exe and attach Dr. 

Watcom to it, type: 
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drwatcom foo.exe 

If you often want to run a certain program with Dr. Watcom attached to it then you can create a Program 
Manager icon that runs Dr. Watcom with the name of the program as a command line parameter. 

Double clicking on the icon when Dr. Watcom is not running causes Dr. Watcom to start-up. Dr. 

Watcom then starts the specified process and attaches to it immediately. 

Double clicking on the icon when there is already an instance of Dr. Watcom running causes the existing 
instance of Dr. Watcom to run the specified process and attach to it. The second Dr. Watcom terminates 
immediately so that only one instance of Dr. Watcom is left running. 

20.7.2 Add New Process 

The Add New Process item in the Process menu is another way to start a new process and attach to it 
immediately. 

To start a new process using this item: 

(1) Choose Add New Process from the Process menu. 

This opens the Load Process dialog where you browse the file structure. 

(2) Select the program you want to start with Dr. Watcom attached. 

(3) Click on OK. 

This runs the selected program and attaches to it immediately. 

20.7.3 Auto Add Processes 

Checking the Auto Add Process item in the Process menu tells Dr. Watcom to attach to all new processes 
that start in the system. When you activate this feature. Dr. Watcom checks the system every few seconds 
for new processes. When it finds them, it attaches to them. Dr. Watcom will not automatically attach to 
processes that began before the Auto Add Process item was checked. 

The disadvantage of this feature is that in the few seconds between Dr. Watcom’s process checks, your 
process can start-up, run, and possibly cause an exception. When this occurs, a system dialog box appears 
reporting the error. Selecting OK on this dialog immediately may not allow Dr. Watcom sufficient time to 
attach to the faulting process. Wait for a few seconds and select the OK button on this dialog. The dialog 
closes and Dr. Watcom attaches to the faulting process. The Dr. Watcom exception dialog then appears 
and you can proceed as usual. 

Note: Occasionally, when this feature is active a message box may appear saying, "An 

unexpected failure occurred while processing a DebugActiveProcess API request. You 
may choose OK to terminate the process or Cancel to ignore the error". This message 
results from a known limitation in Win32. If it appears simply choose Cancel. 
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20.7.4 Process Control 

Using the Add Process button on the Process Control dialog, you can attach Dr. Watcom to any process 
that is currently running in the system. 

To do this follow these instructions: 

(1) Choose Process Control from the Process menu or the system menu. 

This opens the Process Control dialog which lists all processes currently running under Windows. 

(2) Click on the process to which you want Dr. Watcom to attach. You can only select one process at a 
time. 

(3) Select the Add Process button. 

This attaches Dr. Watcom to the selected process. An asterisk appears to the left of this process 
indicating that Dr. Watcom is currently attached to it. 

20.8 Performing Process Control 

Selecting Process Control from the process menu or the system menu opens the Process Control dialog. 
This dialog lists all processes currently running under Windows. Any process to which Dr. Watcom is 
attached is marked with an asterisk. When you select a process by clicking on it, the Selected Process 
section of the dialog displays its Process ID, Name, and Priority. 

The Refresh button on this dialog updates the displayed process information. 

From this dialog you can perform several functions. This section describes each function. 

Important: The Process Control functions are extremely powerful and give you the ability to perform 

functions that can make the operating system unstable. Because of this, it is wise to save 
information before you attempt to use the Process Control functions. 

20.8.1 Setting the Process Priority 

Each process in the system has an assigned priority class. This priority class establishes the schedule for 
running processes. The Set Priority button on the process Control dialog allows you to assign a priority to 
the selected process. 

To set a process’s priority: 

(1) Select the process from the Process List to which you want to assign a priority. 

(2) Select the Set Priority button. 

This opens the Set Process Priority dialog which displays the priority classes: idle, normal, high, and 
real time. 

(3) Select the desired priority for the selected process. 
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(4) Click on OK to assign the priority and close the Set Process Priority dialog. 

20.8.2 Terminating a Process 

The Kill Process button on the Process Control dialog terminates a process selected from the Process List in 
the Process Control dialog. 

To terminate a process: 

(1) Choose Process Control from the Process menu. 

This opens the Process Control dialog containing a list of all processes currently running in the 
system. 

(2) Click once on the process you want to terminate to select it. 

(3) Select the Kill Process button. 

This terminates the selected process. The process’s entry in the list may not be removed until you 
select the Refresh button. 

20.8.3 Viewing the Threads for a Process 

A process is made up of one or more threads. The View Threads button in the Process Control dialog 
opens a Thread Control dialog that lets you view and manipulate the threads for the selected process. With 
this dialog, you can terminate, suspend, and resume threads. 

To view the threads for a process: 

(1) Select the process from the Process List whose threads you want to view. 

(2) Select the View Threads button from the Process Control dialog. 

This opens the Thread Control dialog which displays the threads that make up the selected process. 

Selecting a thread from the Threads list displays information for that thread in the Selected Thread section 
of the dialog. This information is: 

tid (Thread Id) 

A unique identifier assigned by the operating system to each thread in the system. 

State Indicates the current state of the thread. This tells you if the thread is currently ready for 

execution or if it is waiting for some event. 

Priority The thread's current priority class 

Use the Refresh button to update the information displayed in the Thread Control dialog. 
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20.8.3.1 Terminating a Thread 

Use the Kill Thread button to terminate a thread. 

To terminate a thread, select the desired thread from the Threads list and select the Kill Thread button. 

20.8.3.2 Suspending a Thread 

Each thread has a suspend count. A thread can only be scheduled for execution when its suspend count is 
zero. To increment a thread's suspend count, select the thread on the list in the Thread Control dialog and 
press the Suspend button. 

20.8.3.3 Resuming a Thread 

Each thread has a suspend count. A thread can only be scheduled for execution when its suspend count is 
zero. To decrement a thread's suspend count, select the thread on the list in the Thread Control dialog and 
press the Resume button. 

20.8.4 Viewing the Memory for a Process 

Selecting the View Memory button on the Process Control dialog opens a Memory Walk window for the 
currently selected process. For information on this window, see the section entitled "Dr. Watcom: 
Viewing Memory" on page 343. 

20.8.5 Summarizing Process Memory Usage 

Selecting the Memory Info button on the Process Control dialog opens a Memory Information dialog box. 
This dialog provides a breakdown of the memory usage for the process selected from the Process List. 

To view this memory information, select the desired process from the Process List and select the Memory 
Info button. 

The Memory Information dialog displays information in the following sections: 

• Mapped and Committed memory 

• Reserved Memory 

• Memory Usage by Module (Address Space) 

The Mapped and Committed section displays the amount of committed memory the application is using 
broken down by its protection. 

The Reserved section displays the amount a memory reserved but not yet committed. This information is 
broken down by its protection. 

In the Address Space section of this dialog, you can view the memory usage of each module that the 
selected process currently has loaded. The combo box in this section lists all modules the process has 
loaded. Selecting a module from the combo box displays a summary of its memory usage. Selecting the 
All Images item in the combo box displays the total memory usage by all loaded modules listed in the 
combo box. 
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Use the Refresh button to update the information displayed in the Memory Information dialog box. 
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1 The Open Watcom Linker 


The Open Watcom Linker is a linkage editor (linker) that takes object and library files as input and 
produces executable files as output. The following object module and library formats are supported by the 
Open Watcom Linker. 

• The standard Intel Object Module Format (OMF). 

• Microsoft’s extensions to the standard Intel OMF. 

• Phar Lap’s Easy OMF-386 object module format for linking 386 applications. 

• The COFF object module format. 

• The ELF object module format. 

• The OMF library format. 

• The AR object library format (Microsoft, GNU or BSD compatible). 

The Open Watcom Linker is capable of producing a number of executable file formats. The following lists 
these executable file formats. 

• DOS executable files 

• RDOS executable files including Dynamic Link Libraries 

• ZDOS executable files 

• ELF executable files 

• executable files that run under CauseWay DOS extender including Dynamic Link Libraries 

• executable files that run under Tenberry Software’s DOS/4G and DOS/4GW DOS extenders, and 
compatible products 

• executable files that run under FlashTek's DOS extender 

• executable files that run under Phar Lap’s 386IDOS-Extender 

• NetWare Loadable Modules (NLMs) that run under Novell's NetWare operating system 

• OS/2 executable files including Dynamic Link Libraries 

• QNX executable files 

• 16-bit Windows (Winl6) executable files including Dynamic Link Libraries 

• 32-bit Windows (Win32) executable files including Dynamic Link Libraries 
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• raw binary images 

• Intel Hex files (Hex80, Hex86 and extended linear) 

In addition to being able to generate the above executable file formats, the Open Watcom Linker also runs 
under a variety of operating systems. Currently, the Open Watcom Linker runs under the following 
operating systems. 

•DOS 

•ZDOS 

• Linux 
•OS/2 

• QNX 

• Windows NT/2000/XP 

• Windows 95/98/Me 

We refer to the operating system upon which you run the Open Watcom Linker as the "host". 

The chapter entitled "Linking Executable Files for Various Systems" on page 5 summarizes each of the 
executable file formats that can be generated by the linker. The chapter entitled "Linker Directives and 
Options" on page 17 describes all of the linker directives and options. The remaining chapters describe 
aspects of each of the executable file formats. 
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2 Linking Executable Files for Various Systems 


The Open Watcom Linker command line format is as follows. 

wlink {directive} 

where directive is a series of Open Watcom Linker directives specified on the command line or in one or 
more files. If the directives are contained within a file, the "@" character is used to reference that file. If 
no file extension is specified, a file extension of "Ink" is assumed. 

Example: 

wlink name testprog @first Ssecond option map 

In the above example, directives are specified on the command line (e.g., "name testprog" and "option 
map") and in files (e.g., first. ink and second, ink). 

2.1 Using the SYSTEM Directive 

For each executable file format that can be created using the Open Watcom Linker, a specific SYSTEM 
directive may be used. The SYSTEM directive selects a subset of the available directives necessary to 
create each specific executable file format. 

System Description 

causeway 32-bit x86 CauseWay executable 

cwdllr 32-bit x86 CauseWay Dynamic Link Library (register calling convention) 

cwdlls 32-bit x86 CauseWay Dynamic Link Library (stack calling convention) 

com 16-bit x86 DOS ".COM" executable 

dos 16-bit x86 DOS executable 

dos4g 32-bit x86 DOS/4GW executable 

dos4gnz non-zero based 32-bit x86 DOS/4GW executable 

netware 32-bit x86 NetWare Loadable Module. Uses original Novell developer kit (NOVH + 

NOVI). This is a legacy system type. It is recommended to use one of the netware_clib or 
netware_libc system types instead. 

novell synonym for "netware". This is a legacy system type. It is recommended to use one of the 

netware_clib or netware_libc system types instead. 
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netwarelibc 

netware J.ibc 

netware _clib 

netware _clib 

os2 

os2_dll 

os2 _pm 

os2v2 

os2v2_dll 

os2v2 _pm 

pharlap 

tnt 

rdos 

rdos_dll 

qnx 

qnx386 

x32r 

x32rv 

x32s 

x32sv 

windows 

windows _dll 

win_vxd 


32-bit x86 NetWare Loadable Module. Targetted for Novells LibC based environment on 
NetWare 5 and later. Uses the full Open Watcom run-time library for NetWare. 

lite 32-bit x86 NetWare Loadable Module. Targetted for Novells LibC based environment 
on NetWare 5 and later. Uses the thin Open Watcom run-time library support for NetWare 
and consumes C library functionality from the server libraries. 

32-bit x86 NetWare Loadable Module. Targetted for Novells traditional CLIB based 
environment on NetWare 3 and later. Uses the full Open Watcom run-time library for 
NetWare. 

lite 32-bit x86 NetWare Loadable Module. Targetted for Novells traditional CLIB based 
environment on NetWare 3 and later. Uses the thin Open Watcom run-time library support 
for NetWare and consumes C library functionality from the server libraries. 

16-bit x86 OS/2 executable 

16-bit x86 OS/2 Dynamic Link Library 

16-bit x86 OS/2 Presentation Manager executable 

32-bit x86 OS/2 executable 

32-bit x86 OS/2 Dynamic Link Library 

32-bit x86 OS/2 Presentation Manager executable 

32-bit x86 Phar Lap executable 

32-bit x86 Phar Lap TNT executable 

32-bit x86 RDOS executable 

32-bit x86 RDOS Dynamic Link Library 

16-bit x86 QNX executable 

32-bit x86 QNX executable 

32-bit x86 FlashTek executable using register-based calling conventions 

32-bit x86 virtual-memory FlashTek executable using register-based calling conventions 

32-bit x86 FlashTek executable using stack-based calling conventions 

32-bit x86 virtual-memory FlashTek executable using stack-based calling conventions 

16-bit x86 Windows 3.x executable 

16-bit x86 Windows 3.x Dynamic Link Library 

32-bit x86 Windows 3.x or 9x Virtual Device Driver 
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win95 32-bit x86 Windows 9x executable 

win95 dll 32-bit x86 Windows 9x Dynamic Link Library 

nt 32-bit x86 Windows NT character-mode executable 

nt_win 32-bit x86 Windows NT windowed executable 

Win32 synonym for "nt_win" 

nt_dll 32-bit x86 Windows NT Dynamic Link Library 

win386 32-bit x86 Open Watcom extended Windows 3.x executable or Dynamic Link Library 

The various systems that we have listed above are defined in special linker directive files which are plain 
ASCII text files that you can edit. These files are called wlink. Ink and wlsystem. Ink. 

The file wlink. Ink is a special linker directive file that is automatically processed by the Open Watcom 
Linker before processing any other directives. On a DOS, ZDOS, OS/2, or Windows-hosted system, this 
file must be located in one of the paths specified in the PATH environment variable. On a QNX-hosted 
system, this file should be located in the /etc directory. A default version of this file is located in the 
\watcom\binw directory on DOS-hosted systems, the \watcom\binp directory on OS/2-hosted 
systems, the /etc directory on QNX-hosted systems, and the \watcom\binnt directory on Windows 
95 or Windows NT-hosted systems. Note that the file wlink. Ink includes the file wl system. Ink 
which is located in the \watcom\binw directory on DOS, OS/2, or Windows-hosted systems and the 
/etc directory on QNX-hosted systems. 

The files wlink. Ink and wlsystem. Ink reference the WATCOM environment variable which must 
be set to the directory in which you installed your software. 

The default name of the linker directive file (wlink. Ink) can be overridden by the WLINK_LNK 
environment variable. If the specified file can’t be opened, the default file name will be used. For 
example, if the WLINK_LNK environment variable is defined as follows 

set WLINK_ LNK=my . Ink 

then the Open Watcom Linker will attempt to use a my. Ink directive file, and if that file cannot be 
opened, the linker will revert to using the default wlink . Ink file. 

In the following sections, we show some of the typical directives that you might use to create a particular 
executable file format. The common directives are described in the chapter entitled "Linker Directives and 
Options" on page 17. They are "common" in the sense that they may be used with any executable format. 
There are other, less general, directives that may be specified for a particular executable format. In each of 
the following sections, we refer you to chapters in which you will find more information on the directives 
available with the executable format used. 

At this point, it should be noted that various systems have adopted particular executable file formats. For 
example, the CauseWay DOS extender, Tenberry Software DOS/4G(W) and FlashTek DOS extenders all 
support one of the OS/2 executable file formats. It is for this reason that you may find that we direct you to 
a chapter which would, at first glance, seem unrelated to the executable file format in which you are 
interested. 

To summarize, the steps that you should follow to learn about creating a particular executable are: 
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1. Look for a section in this chapter that describes the executable format in which you are 
interested. 

2. See the chapter entitled "Linker Directives and Options" on page 17 for a description of the 
common directives. 

3. If you require additional information, see also the chapter to which we have referred you. 

4. Also check the Open Watcom C/C++ Programmer’s Guide or Open Watcom FORTRAN 77 
Programmer’s Guide for more information on creating specific types of applications. 

2.2 Linking 16-bit x86 Executable Files 

The following sections describe how to link a variety of 16-bit executable files. 

2.2.1 Linking 16-bit x86 DOS Executable Files 

To create this type of file, use the following structure. 

system dos 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The DOS Executable File Format" on page 183. 

2.2.2 Linking 16-bit x86 DOS .COM Executable Files 

To create this type of file, use the following structure. 

system com 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The DOS Executable File Format" on page 183. 

2.2.3 Linking 16-bit x86 OS/2 Executable Files 

To create this type of file, use the following structure. 

system os2 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The OS/2 Executable and DLL File Formats" on page 215. 
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2.2.4 Linking 16-bit x86 OS/2 Dynamic Link Libraries 

To create this type of file, use the following structure. 

system os2 dll 
option map 
name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The OS/2 Executable and DLL File Formats" on page 215. 

2.2.5 Linking 16-bit x86 QNX Executable Files 

To create this type of file, use the following structure. 

system qnx 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The QNX Executable File Format" on page 225. 

2.2.6 Linking 16-bit x86 Windows 3.x Executable Files 

To create this type of file, use the following structure. 

system windows 
option map 
name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The Winl6 Executable and DLL File Formats" on page 229. 

2.2.7 Linking 16-bit x86 Windows 3.x Dynamic Link Libraries 

To create this type of file, use the following structure. 

system windows_ dll 
option map 
name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The Winl6 Executable and DLL File Formats" on page 229. 
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2.3 Linking 32-bit x86 Executable Files 

The following sections describe how to create a variety of 32-bit executable files. 

2.3.1 Linking 32-bit x86 CauseWay Executable Files 

To create this type of file, use the following structure. 

system causeway 
option map 
name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The OS/2 Executable and DLL File Formats" on page 215. 

2.3.2 Linking 32-bit x86 CauseWay Dynamic Link Libraries 

To create this type of file, use the following structure. 

system cwdllr or cwdlls 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The OS/2 Executable and DLL File Formats" on page 215. 

2.3.3 Linking 32-bit x86 D0S/4GW Executable Files 

To create this type of file, use the following structure. 

system dos4g 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The OS/2 Executable and DLL File Formats" on page 215. 

2.3.4 Linking 32-bit x86 FlashTek Executable Files 

To create these files, use one of the following structures. 

system x32r 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 
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If the system is x32r, a FlashTek executable file is created for an application using the register calling 
convention. 

system x32rv 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

If the system is x32rv, a virtual-memory FlashTek executable file is created for an application using the 
register calling convention. 

system x32s 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

If the system is x32s, a FlashTek executable file is created for an application using the stack calling 
convention. 

system x32sv 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

If the system is x32sv, a virtual-memory FlashTek executable file is created for an application using the 
stack calling convention. 

For more information, see the chapter entitled "The OS/2 Executable and DLL File Formats" on page 215. 

2.3.5 Linking 32-bit x86 Novell NetWare Loadable Modules 

To create this type of file, use the following structure. 

system netware. (clib|libc) [_lite] 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

module mod_ name 

For more information, see the chapter entitled "The NetWare O/S Executable File Format" on page 209. 

2.3.6 Linking 32-bit x86 OS/2 Executable Files 

To create this type of file, use the following structure. 

system os2v2 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 


Linking 32-bit x86 Executable Files 11 




The Open Watcom Linker 


For more information, see the chapter entitled "The OS/2 Executable and DLL File Formats" on page 215. 

2.3.7 Linking 32-bit x86 OS/2 Dynamic Link Libraries 

To create this type of file, use the following structure. 

system os2v2 dll 
option map 
name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The OS/2 Executable and DLL File Formats" on page 215. 

2.3.8 Linking 32-bit x86 OS/2 Presentation Manager Executable Files 

To create this type of file, use the following structure. 

system os2v2_ pm 
option map 
name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The OS/2 Executable and DLL File Formats" on page 215. 

2.3.9 Linking 32-bit x86 Phar Lap Executable Files 

To create this type of file, use the following structure. 

system pharlap 
option map 
name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The Phar Lap Executable File Format" on page 221. 

2.3.10 Linking 32-bit x86 Phar Lap TNT Executable Files 

To create this type of file, use the following structure. 

system tnt 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The Win32 Executable and DLL File Formats" on page 239. 
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2.3.11 Linking 32-bit x86 RDOS Executable Files 

To create this type of file, use the following structure. 

system rdos 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The Win32 Executable and DLL File Formats" on page 239. 

2.3.12 Linking 32-bit x86 RDOS Dynamic Link Libraries 

To create this type of file, use the following structure. 

system rdos_ dll 
option map 
name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The Win32 Executable and DLL File Formats" on page 239. 

2.3.13 Linking 32-bit x86 QNX Executable Files 

To create this type of file, use the following structure. 

system qnx386 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The QNX Executable File Format" on page 225. 

2.3.14 Linking 32-bit x86 Extended Windows 3.x Executable 

To create this type of file, use the following structure. 

system win386 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

After linking this executable, you must bind the Open Watcom 32-bit Windows-extender to the executable 
(a .REX file) to produce a Windows executable (a .EXE file). 

wbind -n app_ name 

For more information, see the chapter entitled "The Winl6 Executable and DLL File Formats" on page 229. 
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2.3.15 Linking 32-bit x86 Extended Windows 3.x Dynamic Link Libraries 

To create this type of file, use the following structure. 

system win386 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

After linking this executable, you must bind the Open Watcom 32-bit Windows-extender for DLLs to the 
executable (a . REX file) to produce a Windows Dynamic Link Library (a . DLL file). 

wbind -n -d app_ name 

For more information, see the chapter entitled "The Winl6 Executable and DLL File Formats" on page 229. 

2.3.16 Linking 32-bit x86 Windows 3.x or 9x Virtual Device Driver 

There are two type of the Virtual Device Driver. 

Staticaly loaded Virtual Device Driver used by Windows 3.x or 9x. To create this type of file, use the 
following structure. 

system win_ vxd 
option map 
name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

Dynamicaly loaded Virtual Device Driver used by Windows 3.11 or 9x. To create this type of file, use the 
following structure. 

system win_ vxd dynamic 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The Windows Virtual Device Driver File Format" on page 
235. 

2.3.17 Linking 32-bit x86 Windows 95 Executable Files 

To create this type of file, use the following structure. 

system win95 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The Win32 Executable and DLL File Formats" on page 239. 
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2.3.18 Linking 32-bit x86 Windows 95 Dynamic Link Libraries 

To create this type of file, use the following structure. 

system win95 dll 
option map 
name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The Win32 Executable and DLL File Formats" on page 239. 

2.3.19 Linking 32-bit x86 Windows NT Character-Mode Executable Files 

To create this type of file, use the following structure. 

system nt 

option map 

name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The Win32 Executable and DLL File Formats" on page 239. 

2.3.20 Linking 32-bit x86 Windows NT Windowed Executable Files 

To create this type of file, use the following structure. 

system nt_ win 
option map 
name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The Win32 Executable and DLL File Formats" on page 239. 

2.3.21 Linking 32-bit x86 Windows NT Dynamic Link Libraries 

To create this type of file, use the following structure. 

system nt_ dll 
option map 
name app_ name 

file objl, obj2, ... 

library libl, lib2, ... 

For more information, see the chapter entitled "The Win32 Executable and DLL File Formats" on page 239. 
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The Open Watcom Linker supports a large set of directives and options. The following sections present 
these directives and options in alphabetical order. Not all directives and options are supported for all 
executable formats. When a directive or option applies only to a subset of the executable formats that the 
linker can generate, the supporting formats are noted. In the following example, the notation indicates that 
the directive or option is supported for all executable formats. 

Example: 

Formats: All 

In the following example, the notation indicates that the directive or option is supported for OS/2, 16-bit 
Windows and 32-bit Windows executable formats only. 

Example: 

Formats: OS/2, Winl6, Win32 

Directives tell the Open Watcom Linker how to create your program. For example, using directives you 
can tell the Open Watcom Linker which object files are to be included in the program, which library files to 
search to resolve undefined references, and the name of the executable file. 

The file wlink. Ink is a special linker directive file that is automatically processed by the Open Watcom 
Linker before processing any other directives. On a DOS, ZDOS, OS/2, or Windows-hosted system, this 
file must be located in one of the paths specified in the PATH environment variable. On a QNX-hosted 
system, this file should be located in the /etc directory. A default version of this file is located in the 
\watcom\binw directory on DOS-hosted systems, the \watcom\binp directory on OS/2-hosted 
systems, the /etc directory on QNX-hosted systems, and the \watcom\binnt directory on Windows 
95 or Windows NT-hosted systems. Note that the file wlink. Ink includes the file wlsystem. Ink 
which is located in the \watcom\binw directory on DOS, OS/2, or Windows-hosted systems and the 
/etc directory on QNX-hosted systems. 

The files wlink. Ink and wlsystem. Ink reference the WATCOM environment variable which must 
be set to the directory in which you installed your software. 

The default name of the linker directive file (wlink. Ink) can be overridden by the WLINK_LNK 
environment variable. If the specified file can’t be opened, the default file name will be used. For 
example, if the WLINK_LNK environment variable is defined as follows 

set WLINK_ LNK=my . Ink 

then the Open Watcom Linker will attempt to use a my. Ink directive file, and if that file cannot be 
opened, the linker will revert to using the default wlink . Ink file. 

It is also possible to use environment variables when specifying a directive. For example, if the LIBDIR 
environment variable is defined as follows, 

set libdir=\test 

then the linker directive 
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library %libdir%\mylib 
is equivalent to the following linker directive, 
library \test\mylib 

Note that a space must precede a reference to an environment variable. 

Many directives can take a list of one or more arguments separated by commas. Instead of a 
comma-delimited list, you can specify a space-separated list provided the list is enclosed in braces (e.g., { 
space delimited list }). For example, the "FILE" directive can take a list of object file names as an 
argument. 

file first, second,third,fourth 
The alternate way of specifying this is as follows, 
file {first second third fourth} 

Where this comes in handy is in make files, where a list of dependents is usually a space-delimited list. 
OBJS = first second third fourth 


wlink file {$(objs)} 

The following notation is used to describe the syntax of linker directives and options. 

ABC All items in upper case are required. 

[abc] The item abc is optional. 

{abc} The item abc may be repeated zero or more times. 

{abc}+ The item abc may be repeated one or more times, 

alblc One of a, b or c may be specified, 

a ::= b The item a is defined in terms of b. 

Certain characters have special meaning to the linker. When a special character must appear in a name, you 
can imbed the string that makes up the name inside apostrophes (e.g., ’name@8’). This prevents the linker 
from interpreting the special character in its usual manner. This is also true for file or path names that 
contain spaces (e.g., '\program files\software\mylib’). Normally, the linker would interpret a space or 
blank in a file name as a separator. The special characters are listed below: 
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+ -+-+ 

I Character I Name of Character 


+-+-+ 



Blank 

= 

Equals 

( 

Left Parenthesis 

) 

Right Parenthesis 

r 

Comma 

. 

Period 

{ 

Left Brace 

} 

Right Brace 

@ 

At Sign 

# 

Hash Mark 

"6 

Percentage Symbol 


+-+-+ 
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3.1 The ALIAS Directive 

Formats: All 

The "ALIAS" directive is used to specify an equivalent name for a symbol name. The format of the 
"ALIAS" directive (short form "A") is as follows. 


ALIAS alias_name=symbol_name{, alias_name=symbol_name} 


where description: 

alias_name is the alias name. 

symbol jiame is the symbol name to which the alias name is mapped. 

Consider the following example, 
alias sine=mysine 

When the linker tries to resolve the reference to sine, it will immediately substitute the name my sine for 
sine and begin searching for the symbol mysine. 
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3.2 The ALIGNMENT Option 

Formats: ELF, OS/2, Win 16, Win32 

The "ALIGNMENT" option specifies the alignment for segments in the executable file. The format of the 
"ALIGNMENT" option (short form "A") is as follows. 


OPTION ALIGNMENT=n 


where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

n specifies the alignment for segments in the executable file and must be a power of 2. 

In 16-bit applications, segments in the executable file are pointed to by a segment table. An entry in the 
segment table contains a 16-bit value which is a multiple of the alignment value. Together they form the 
offset of the segment from the start of the segment table. Note that the smaller the value of n the smaller 
the executable file. 

By default, the Open Watcom Linker will automatically choose the smallest value of n possible. You need 
not specify this option unless you want padding between segments in the executable file. 
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3.3 The ANONYMOUSEXPORT Directive 

Formats: Win16, Win32 

The "ANONYMOUSEXPORT" directive is an alternative to the "EXPORT" directive described in "The 
EXPORT Directive" on page 52. The symbol associated with this name will not appear in either the 
resident or the non-resident names table. The entry point is, however, still available for ordinal linking. 

The format of the "ANONYMOUSEXPORT" directive (short form "ANON") is as follows. 

ANONYMOUSEXPORT export{,export} 
or 

ANONYMOUSEXPORT =lbcjile 

export ::= entry_name[.ordinal][=internaljiame] 

where description: 

entry_name is the name to be used by other applications to call the function. 

ordinal is an ordinal value for the function. If the ordinal number is specified, other applications 

can reference the function by using this ordinal number. 

internal jiame is the actual name of the function and should only be specified if it differs from the entry 
name. 

Ibc_Jile is a file specification for the name of a librarian command file. If no file extension is 

specified, a file extension of "lbc" is assumed. The linker will process the librarian 
command file and look for commands to the librarian that are used to create import library 
entries. These commands have the following form. 

++sym.dll_ name[. [altsym] .export_ name] [.ordinal] 

where description: 

sym is the name of a symbol in a Dynamic Link Library. 

dlljiame is the name of the Dynamic Link Library that defines sym. 

altsym is the name of a symbol in a Dynamic Link Library. When omitted, the 

default symbol name is sym. 

export jiame is the name that an application that is linking to the Dynamic Link Library 
uses to reference sym. When omitted, the default export name is sym. 

ordinal is the ordinal value that can be used to identify sym instead of using the 

name export_ name. 

All other librarian commands will be ignored. 
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Notes: 

1. By default, the Open Watcom C and C++ compilers append an underscore to all function 
names. This should be considered when specifying entry_name and internal_name in an 
"ANONYMOUSEXPORT” directive. 

2. If the name contains characters that are special to the linker then the name may be placed inside 
apostrophes (e.g., anonymousexport 'myfunc@8'). 

3. The symbol associated with the entry name will not appear in either the resident or the 
non-resident names table. The entry point is, however, still available for ordinal linking. This 
directive is important when you wish to reduce the number of entries that are placed in the 
resident and non-resident names table. 
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3.4 The AREA Option 

Formats: DOS 


The "AREA" option can be used to set the size of the memory pool in which overlay sections are loaded by 
the dynamic overlay manager. The format of the "AREA" option (short form "AR") is as follows. 


OPTION AREA=n 


where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

The default size of the memory pool for a given application is selected by the Open Watcom Linker and is 
equal to twice the size of the largest overlay. 

It is also possible to add to the memory pool at run-time. If you wish to add to the memory pool at 
run-time, see the section entitled "Increasing the Dynamic Overlay Area" on page 193. 
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3.5 The ARTIFICIAL Option 

Formats: All 

The "ARTIFICIAL" option should only be used if you are developing a Open Watcom C++ application. A 
Open Watcom C++ application contains many compiler-generated symbols. By default, the linker does not 
include these symbols in the map file. The "ARTIFICIAL" option can be used if you wish to include these 
compiler-generated symbols in the map file. 

The format of the "ARTIFICIAL" option (short form "ART") is as follows. 
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3.6 The AUTOSECTION Directive 

Formats: DOS 

The "AUTOSECTION" directive specifies that each object file that appears in a subsequent "FILE" 
directive, up to the next "SECTION" or "END" directive, will be assigned a different overlay. The 
"AUTOSECTION" method of defining overlays is most useful when using the dynamic overlay manager, 
selected by specifying the "DYNAMIC" option. For more information on the dynamic overlay manager, 
see the section entitled "Using Overlays" on page 186. 

The format of the "AUTOSECTION" directive (short form "AUTOS") is as follows. 



where description: 

INTO specifies that all overlays are to be placed into a file, namely ovljile. If "INTO" (short 

form "IN") is not specified, the overlays are placed in the executable file. 

ovl Jile is the file specification for the name of an overlay file. If no file extension is specified, a 

file extension of "ovl" is assumed. 

Placing overlays in separate files has a number of advantages. For example, if your application was linked 
into one file, it may not fit on a single diskette, making distribution of your application difficult. 
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3.7 The AUTOUNLOAD Option 

Formats: NetWare 

The "AUTOUNLOAD" option specifies that a NetWare Loadable Module (NLM) built with this option 
should automatically be unloaded when all of its entry points are no longer in use. This only applies if the 
NLM was automatically loaded by another modules loading. 

The format of the "AUTOUNLOAD" option (short form "AUTOUN") is as follows. 

OPTION A UTOUNLOAD 
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3.8 The BEGIN Directive 

Formats: DOS 

The "BEGIN" directive is used to define the start of an overlay area. The "END" directive is used to define 
the end of an overlay area. An overlay area is a piece of memory in which overlays are loaded. All 
overlays defined between a "BEGIN" directive and the corresponding "END" directive are loaded into that 
overlay area. 

The format of the "BEGIN" directive (short form "B") is as follows. 

BEGIN 

The format of the "END" directive (short form "E") is as follows. 

END 
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CACHE 


3.9 The CACHE Option 

Formats: All 

The "CACHE" and "NOCACHE" options can be used to control caching of object and library files in 
memory by the linker. When neither the "CACHE" nor "NOCACHE" option is specified, the linker will 
only cache small libraries. Object files and large libraries are not cached. The "CACHE" and 
"NOCACHE" options can be used to alter this default behaviour. The "CACHE" option enables the 
caching of object files and large library files while the "NOCACHE" option disables all caching. 

The format of the "CACHE" option (short form "CAC") is as follows. 


OPTION CACHE 


The format of the "NOCACHE" option (short form "NOCAC") is as follows. 


OPTION NOCACHE 


When linking large applications with many object files, caching object files will cause extensive use of 
memory by the linker. On virtual memory systems such as OS/2, Windows NT or Windows 95, this can 
cause extensive page file activity when real memory resources have been exhausted. This can degrade the 
performance of other tasks on your system. For this reason, the OS/2 and Windows-hosted versions of the 
linker do not perform object file caching by default. This does not imply that object file caching is not 
beneficial. If your system has lots of real memory or the linker is running as the only task on the machine, 
object file caching can certainly improve the performance of the linker. 

On single-tasking environments such as DOS, the benefits of improved linker performance outweighs the 
memory demands associated with object file caching. For this reason, object file caching is performed by 
default on these systems. If the memory requirements of the linker exceed the amount of memory on your 
system, the "NOCACHE" option can be specified. 

The QNX operating system is a multi-tasking real-time operating system. However, it is not a virtual 
memory system. Caching object files can consume large amounts of memory. This may prevent other 
tasks on the system from running, a problem that may be solved by using the "NOCACHE" option. 
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CASEEXACT 


3.10 The CASEEXACT Option 

Formats: All 

The "CASEEXACT" option tells the Open Watcom Linker to respect case when resolving references to 
global symbols. That is, "ScanName" and "SCANNAME" represent two different symbols. This is the 
default because the most commonly used languages (C, C++, FORTRAN) are case sensitive. The format of 
the "CASEEXACT" option (short form "C") is as follows. 


OPTION CASEEXACT 


It is possible to override the default by using the "NOCASEEXACT" option. The "NOCASEEXACT" 
option turns off case-sensitive linking. The format of the "NOCASEEXACT" option ( short form 
"NOCASE") is as follows. 


OPTION NOCASEEXACT 


You can specify the "NOCASEEXACT" option in the default directive files wlink. Ink or 
wl system. Ink if required. 

The file wlink. Ink is a special linker directive file that is automatically processed by the Open Watcom 
Linker before processing any other directives. On a DOS, ZDOS, OS/2, or Windows-hosted system, this 
file must be located in one of the paths specified in the PATH environment variable. On a QNX-hosted 
system, this file should be located in the /etc directory. A default version of this file is located in the 
\watcom\binw directory on DOS-hosted systems, the \watcom\binp directory on OS/2-hosted 
systems, the /etc directory on QNX-hosted systems, and the \watcom\binnt directory on Windows 
95 or Windows NT-hosted systems. Note that the file wlink. Ink includes the file wl system. Ink 
which is located in the \watcom\binw directory on DOS, OS/2, or Windows-hosted systems and the 
/etc directory on QNX-hosted systems. 

The files wlink. Ink and wl system. Ink reference the WATCOM environment variable which must 
be set to the directory in which you installed your software. 

The default name of the linker directive file (wlink. Ink) can be overridden by the WLINK_LNK 
environment variable. If the specified file can’t be opened, the default file name will be used. For 
example, if the WLINK_LNK environment variable is defined as follows 

set WLINK_ LNK=my . Ink 

then the Open Watcom Linker will attempt to use a my. Ink directive file, and if that file cannot be 
opened, the linker will revert to using the default wlink . Ink file. 
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CHECK (NetWare) 


3.11 The CHECK Option 

Formats: NetWare 

The "CHECK" option specifies the name of a procedure to execute before an NLM is unloaded. This 
procedure can, for example, inform the operator that the NLM is in use and prevent it from being unloaded. 

The format of the "CHECK" option ( short form "CH" ) is as follows. 

OPTION CHECK=symbol_name 

where description: 

symbol jiame specifies the name of a procedure to execute before the NLM is unloaded. 

If the "CHECK" option is not specified, no check procedure will be called. 
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CHECKSUM (Win32) 


3.12 The CHECKSUM Option 

Formats: Win32 

The "CHECKSUM" option specifies that the linker should create an MS-CRC32 checksum for the current 
image. This is primarily used for DLL’s and device drivers but can be applied to any PE format images. 
The format of the "CHECKSUM" option (no short form) is as follows. 

OPTION CHECKSUM 
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COMMENT 


3.13 The # Directive 

Formats: All 

The "#" directive is used to mark the start of a comment. All text from the "#" character to the end of the 
line is considered a comment. The format of the "#" directive is as follows. 


# comment 


where description: 

comment is any sequence of characters. 

The following directive file illustrates the use of comments, 
file main, trigtest 

# Use my own version of "sin" instead of the 

# library version. 

file mysin 
library \math\trig 
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COMMIT (Win32) 


3.14 The COMMIT Directive 

Formats: Win32 

When the operating system allocates the stack and heap for an application, it does not actually allocate the 
whole stack and heap to the application when it is initially loaded. Instead, only a portion of the stack and 
heap are allocated or committed to the application. Any part of the stack and heap that is not committed 
will be committed on demand. 

The format of the "COMMIT" directive (short form "COM") is as follows. 


COMMIT memjype 

memjype ::= STACK=n I HEAP=n 


where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

n represents the amout of stack or heap that is initially committed to the application. The 
short form for "STACK" is "ST" and the short form for "HEAP" is "H". 

If you do not specify the "COMMIT HEAP" directive then a 4k heap is committed to the application. 

If you do not specify the "COMMIT STACK" directive then the default size is the smaller of 64K or the 
size specified by the "STACK" option. See the section entitled "The STACK Option" on page 163 for 
more information on specifying a stack size. 
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COPYRIGHT (NetWare) 


3.15 The COPYRIGHT Option 

Formats: NetWare 

The "COPYRIGHT" option specifies copyright information that is placed in the executable file. The 
format of the "COPYRIGHT" option (short form "COPYR" ) is as follows. 


OPTION COPYRIGHT ’string ’ 


where description: 

string specifies the copyright information. 
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CUSTOM (NetWare) 


3.16 The CUSTOM Option 

Formats: NetWare 

The format of the "CUSTOM" option (short form "CUST") is as follows. 


OPTION CUSTOM=file_name 


where description: 

filejiame specifies the file name of the custom data file. 

The custom data file is placed into the executable file when the application is linked but is really not part of 
the program. When the application is loaded into memory, the information extracted from a custom data 
file is not loaded into memory. Instead, information is passed to the program (as arguments) which allows 
the access and processing of this information. 
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CVPACK 


3.17 The CVPACK Option 

Formats: All 

This option is only meaningful when generating Microsoft CodeView debugging information. This option 
causes the linker to automatically run the Open Watcom CodeView 4 Symbolic Debugging Information 
Compactor, CVPACK, on the executable that it has created. This is necessary to get the CodeView 
debugging information into a state where the Microsoft CodeView debugger will accept it. 

The format of the "CVPACK" option (short form "CVP") is as follows. 


OPTION CVPACK 


For more information on generating CodeView debugging information into the executable, see the section 
entitled "The DEBUG Directive" on page 38 


The CVPACK Option 
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DEBUG 


3.18 The DEBUG Directive 

Formats: All 

The "DEBUG" directive is used to tell the Open Watcom Linker to generate debugging information in the 
executable file. This extra information in the executable file is used by the Open Watcom Debugger. The 
format of the "DEBUG" directive (short form "D") is as follows. 


DEBUG dbtype [dblist] I 
DEBUG [dblist] 

dbtype ::= DWARF I WATCOM I CODEVIEW I NOVELL 

dblist ::= [db_option{,db_option}] 

db_option ::= LINES I TYPES I LOCALS I ALL 

DEBUG NOVELL only 

db_option ::= ONLYEXPORTS I REFERENCED 


The Open Watcom Linker supports four types of debugging information, "DWARF" (the default), 
"WATCOM", "CODEVIEW", or "NOVELL". 

DWARF (short form "D") specifies that all object files contain DWARF format debugging 

information and that the executable file will contain DWARF debugging information. 

This debugging format is assumed by default when none is specified. 

WATCOM (short form "W") specifies that all object files contain Watcom format debugging 

information and that the executable file will contain Watcom debugging information. This 
format permits the selection of specific classes of debugging information ( dblist) which are 
described below. 


CODEVIEW (short form "C") specifies that all object files contain CodeView (CV4) format debugging 
information and that the executable file will contain CodeView debugging information. 

It will be necessary to run the Microsoft Debugging Information Compactor, CVPACK, on 
the executable that it has created. For information on requesting the linker to automatically 
run CVPACK, see the section entitled "The CVPACK Option" on page 37 Alternatively, 
you can run CVPACK from the command line. 

NOVELL (short form "N") specifies a form of global symbol information that can only be processed 
by the NetWare debugger. 


Note: Except in rare cases, the most appropriate use of the "DEBUG" directive is specifying "DEBUG 
ALL" (short form "D A") prior to any "FILE" or "LIBRARY" directives. This will cause the Open 
Watcom Linker to emit all available debugging information in the default format. 


For the Watcom debugging information format, we can be selective about the types of debugging 
information that we include with the executable file. We can categorize the types of debugging information 
as follows: 
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• global symbol information 

• line numbering information 

• local symbol information 

• typing information 

• NetWare global symbol information 

The following options can be used with the "DEBUG WATCOM" directive to control which of the above 
classes of debugging information is included in the executable file. 

LINES (short form "LI") specifies line numbering and global symbol information. 

LOCALS (short form "LO") specifies local and global symbol information. 

TYPES (short form "T") specifies typing and global symbol information. 

ALL (short form "A") specifies all of the above debugging information. 

ONLYEXPORTS 

(short form "ONL") restricts the generation of global symbol information to exported 
symbols. This option may only be used with Netware executable formats. 

The following options can be used with the "DEBUG NOVELL" directive to control which of the above 
classes of debugging information is included in the executable file. 

ONLYEXPORTS 

(short form "ONL") restricts the generation of global symbol information to exported 
symbols. 

REFERENCED 

(short form "REF") restricts the generation of symbol information to referenced symbols 
only. 

Note: The position of the "DEBUG" directive is important. The level of debugging information 
specified in a "DEBUG" directive only applies to object files and libraries that appear in subsequent 
"FI LE " or "LIBRARY" directives. For example, if "DEBUG WATCOM ALL" was the only "DEBUG" 
directive specified and was also the last linker directive, no debugging information would appear in the 
executable file. 


Only global symbol information is actually produced by the Open Watcom Linker; the other three classes 
of debugging information are extracted from object modules and copied to the executable file. Therefore, 
at compile time, you must instruct the compiler to generate local symbol, line numbering and typing 
information in the object file so that the information can be transferred to the executable file. If you have 
asked the Open Watcom Linker to produce a particular class of debugging information and it appears that 
none is present, one of the following conditions may exist. 

1. The debugging information is not present in the object files. 

2. The "DEBUG" directive has been misplaced. 
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The following sections describe the classes of debugging information. 

3.18.1 Line Numbering Information - DEBUG WATCOM LINES 

The "DEBUG WATCOM LINES" option controls the processing of line numbering information. Line 
numbering information is the line number and address of the generated code for each line of source code in 
a particular module. This allows Open Watcom Debugger to perform source-level debugging. When the 
Open Watcom Linker encounters a "DEBUG WATCOM" directive with a "LINES" or "ALL" option, line 
number information for each subsequent object module will be placed in the executable file. This includes 
all object modules extracted from object files specified in subsequent "FILE" directives and object modules 
extracted from libraries specified in subsequent "LIBRARY" or "FILE" directives. 


Note: All modules for which line numbering information is requested must have been compiled with 
the "dl" or "d2" option. 


A subsequent "DEBUG WATCOM" directive without a "LINES" or "ALL" option terminates the 
processing of line numbering information. 

3.18.2 Local Symbol Information - DEBUG WATCOM LOCALS 

The "DEBUG WATCOM LOCALS" option controls the processing of local symbol information. Local 
symbol information is the name and address of all symbols local to a particular module. This allows Open 
Watcom Debugger to locate these symbols so that you can reference local data and routines by name. 
When the Open Watcom Linker encounters a "DEBUG WATCOM" directive with a "LOCALS" or "ALL" 
option, local symbol information for each subsequent object module will be placed in the executable file. 
This includes all object modules extracted from object files specified in subsequent "FILE" directives and 
object modules extracted from libraries specified in subsequent "LIBRARY" or "FILE" directives. 


Note: All modules for which local symbol information is requested must have been compiled with the 
"d2" option. 


A subsequent "DEBUG WATCOM" directive without a "LOCALS" or "ALL" option terminates the 
processing of local symbol information. 

3.18.3 Typing Information - DEBUG WATCOM TYPES 

The "DEBUG WATCOM TYPES" option controls the processing of typing information. Typing 
information includes a description of all types, structures and arrays that are defined in a module. This 
allows Open Watcom Debugger to display variables according to their type. When the Open Watcom 
Linker encounters a "DEBUG WATCOM" directive with a "TYPES" or "ALL" option, typing information 
for each subsequent object module will be placed in the executable file. This includes all object modules 
extracted from object files specified in subsequent "FILE" directives and object modules extracted from 
libraries specified in subsequent "LIBRARY" or "FILE" directives. 
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Note: All modules for which typing information is requested must have been compiled with the "d2" 
option. 


A subsequent "DEBUG WATCOM" directive without a "TYPES" or "ALL" option terminates the 
processing of typing information. 

3.18.4 All Debugging Information - DEBUG WATCOM ALL 

The "DEBUG WATCOM ALL" option specifies that "LINES", "LOCALS", and "TYPES" options are 
requested. The "LINES" option controls the processing of line numbering information. The "LOCALS" 
option controls the processing of local symbol information. The "TYPES" option controls the processing 
of typing information. Each of these options is described in a previous section. A subsequent "DEBUG 
WATCOM " directive without an "ALL" option discontinues those options which are not specified in the 
list of debug options. 

3.18.5 Global Symbol Information 

Global symbol information consists of all the global symbols in your program and their address. This 
allows Open Watcom Debugger to locate these symbols so that you can reference global data and routines 
by name. When the Open Watcom Linker encounters a "DEBUG" directive, global symbol information for 
all the global symbols appearing in your program is placed in the executable file. 

3.18.6 Global Symbols for the NetWare Debugger - DEBUG NOVELL 

The NetWare operating system has a built-in debugger that can be used to debug programs. When 
"DEBUG NOVELL" is specified, the Open Watcom Linker will generate global symbol information that 
can be used by the NetWare debugger. Note that any line numbering, local symbol, and typing information 
generated in the executable file will not be recognized by the NetWare debugger. Also, WSTRIP cannot be 
used to remove this form of global symbol information from the executable file. 

3.18.7 The ONLYEXPORTS Debugging Option 

The "ONLYEXPORTS" option (short form "ONL") restricts the generation of global symbol information 
to exported symbols (symbols appearing in an "EXPORT" directive). If "DEBUG WATCOM 
ONLYEXPORTS" is specified. Open Watcom Debugger global symbol information is generated only for 
exported symbols. If "DEBUG NOVELL ONLYEXPORTS" is specified, NetWare global symbol 
information is generated only for exported symbols. 

3.18.8 Using DEBUG Directives 

Consider the following directive file. 

debug watcom all 
file modulel 
debug watcom lines 
file module2, module3 
debug watcom 
library mylib 
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It specifies that the following debugging information is to be generated in the executable file. 

1. global symbol information for your program 

2. line numbering, typing and local symbol information for the following object files: 

modulel.obj 

3. line numbering information for the following object files: 

module2.obj 
module3.obj 

Note that if the "DEBUG WATCOM" directive before the "LIBRARY" directive is not specified, line 
numbering information for all object modules extracted from the library "mylib.lib" would be generated in 
the executable file provided the object modules extracted from the library have line numbering information 
present. 


Note: A "DEBUG WATCOM" directive with no option suppresses the processing of line numbering, 
local symbol and typing information for all subsequent object modules. 


Debugging information can use a significant amount of disk space. As shown in the above example, you 
can select only the class of debugging information you want and for those modules you wish to debug. In 
this way, the amount of debugging information in the executable file is minimized and hence the amount of 
disk space used by the executable file is kept to a minimum. 

As you can see from the above example, the position of the "DEBUG WATCOM" directive is important 
when describing the debugging information that is to appear in the executable file. 


Note: If you want all classes of debugging information for all files to appear in the executable file you 
must specify "DEBUG WATCOM ALL" before any "FILE" and "LIBRARY" directives. 


3.18.9 Removing Debugging Information from an Executable File 

A utility called WSTRIP has been provided which takes as input an executable file and removes the 
debugging information placed in the executable file by the Open Watcom Linker. Note that global symbol 
information generated using "DEBUG NOVELL" cannot be removed by WSTRIP. 

For more information on this utility, see the chapter entitled "The Open Watcom Strip Utility" in the Open 
Watcom C/C++ Tools User’s Guide or Open Watcom FORTRAN 77 Tools User’s Guide. 
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DESCRIPTION (OS/2, Win16, Win32) 


3.19 The DESCRIPTION Option 

Formats: OS/2, Win16, Win32 

The "DESCRIPTION" option inserts the specified text into the application or Dynamic Link Library. This 
is useful if you wish to embed copyright information into an application or Dynamic Link Library. The 
format of the "DESCRIPTION" option (short form "DE") is as follows. 


OPTION DESCRIPTION ’string ’ 


where description: 

string is the sequence of characters to be embedded into the application or Dynamic Link Library. 


The DESCRIPTION Option 
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DISABLE 


3.20 The DISABLE Directive 

Formats: All 

The "DISABLE" directive is used to disable the display of linker messages. 

The Open Watcom Linker issues three classes of messages; fatal errors, errors and warnings. Each message 
has a 4-digit number associated with it. Fatal messages start with the digit 3, error messages start with the 
digit 2, and warning messages start with the digit 1. It is possible for a message to be issued as a warning 
or an error. 

If a fatal error occurs, the linker will terminate immediately and no executable file will be generated. 

If an error occurs, the linker will continue to execute so that all possible errors are issued. However, no 
executable file will be generated since these errors do not permit a proper executable file to be generated. 

If a warning occurs, the linker will continue to execute. A warning message is usually informational and 
does not prevent the creation of a proper executable file. However, all warnings should eventually be 
corrected. 

Note that the behaviour of the linker does not change when a message is disabled. For example, if a 
message that normally terminates the linker is disabled, the linker will still terminate but the message 
describing the reason for the termination will not be displayed. For this reason, you should only disable 
messages that are warnings. 

The linker will ignore the severity of the message number. For example, some messages can be displayed 
as errors or warnings. It is not possible to disable the message when it is issued as a warning and display 
the message when it is issued as an error. In general, do not specify the severity of the message when 
specifying a message number. 

The format of the "DISABLE" directive (short form "DISA") is as follows. 


DISABLE msg_num{, msg_num} 


where description: 

msg_num is a message number. See the chapter entitled "Open Watcom Linker Diagnostic 
Messages" on page 243 for a list of messages and their corresponding numbers. 

The following "DISABLE" directive will disable message 28 (an undefined symbol has been referenced). 

disable 28 
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DISTRIBUTE (DOS) 


3.21 The DISTRIBUTE Option 

Formats: DOS 

The "DISTRIBUTE" option specifies that object modules extracted from library files are to be distributed 
throughout the overlay structure. The format of the "DISTRIBUTE" option (short form "DIS") is as 
follows. 


OPTION DISTRIBUTE 


An object module extracted from a library file will be placed in the overlay section that satisfies the 
following conditions. 

1. The symbols defined in the object module are not referenced by an ancestor of the overlay 
section selected to contain the object module. 

2. At least one symbol in the object module is referenced by an immediate descendant of the 
overlay section selected to contain the module. 

Note that libraries specified in the "FIXEDLIB" directive will not be distributed. Also, if a symbol defined 
in a library module is referenced indirectly (its address is taken), the module extracted from the library will 
be placed in the root unless the "NOINDIRECT" option is specified. For more information on the 
"NOINDIRECT" option, see the section entitled "The NOINDIRECT Option" on page 112. 

For more information on overlays, see the section entitled "Using Overlays" on page 186. 
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3.22 The DOSSEG Option 

Formats: All 

The "DOSSEG" option tells the Open Watcom Linker to order segments in a special way. The format of 
the "DOSSEG" option (short form "D") is as follows. 


OPTION DOSSEG 


When the "DOSSEG" option is specified, segments will be ordered in the following way. 

1. all segments not belonging to group "DGROUP" with class "CODE" 

2. all other segments not belonging to group "DGROUP" 

3. all segments belonging to group "DGROUP" with class "BEGDATA" 

4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

5. all segments belonging to group "DGROUP" with class "BSS" 

6. all segments belonging to group "DGROUP" with class "STACK" 

A special segment belonging to class "BEGDATA" is defined when linking with Open Watcom run-time 
libraries. This segment is initialized with the hexadecimal byte pattern "01" and is the first segment in 
group "DGROUP" so that storing data at location 0 can be detected. 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 

When using Open Watcom run-time libraries, it is not necessary to specify the "DOSSEG" option. One of 
the object files in the Open Watcom run-time libraries contains a special record that specifies the 
"DOSSEG" option. 

If no "DOSSEG" option is specified, segments are ordered in the order they are encountered by the Open 
Watcom Linker. 

When the "DOSSEG" option is specified, the Open Watcom Linker defines two special variables. _ edata 
defines the start of the "BSS" class of segments and _ end defines the end of the "BSS" class of segments. 
Your program must not redefine these symbols. 
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3.23 The DYNAMIC Option 

Formats: DOS 

The "DYNAMIC" option tells the Open Watcom Linker to use the dynamic overlay manager. The format 
of the "DYNAMIC" option (short form "DYN") is as follows. 

OPTION DYNAMIC 


Note that the dynamic overlay manager can only be used with applications that have been compiled using 
the "of" option and a big code memory model. The "of" option generates a special prologue/epilogue 
sequence for procedures that is required by the dynamic overlay manager. See the compiler User’s Guide 
for more information on the "of" option. 

For more information on the dynamic overlay manager, see the section entitled "Using Overlays" on page 

186 . 
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ELIMINATE 


3.24 The ELIMINATE Option 

Formats: All 

The "ELIMINATE" option can be used to enable dead code elimination. Dead code elimination is a 
process the linker uses to remove unreferenced segments from the application. The linker will only remove 
segments that contain code; unreferenced data segments will not be removed. 

The format of the "ELIMINATE" option (short form "EL") is as follows. 


OPTION ELIMINATE 


Linking C/C++ Applications 

Typically, a module of C/C++ code contains a number of functions. When this module is 
compiled, all functions will be placed in the same code segment. The chances of each 
function in the module being unreferenced are remote and the usefulness of the 
"ELIMINATE" option is greatly reduced. 

In order to maximize the effect of the "ELIMINATE" option, the "zm" compiler option is 
available to tell the Open Watcom C/C++ compiler to place each function in its own code 
segment. This allows the linker to remove unreferenced functions from modules that 
contain many functions. 

Note, that if a function is referenced by data, as in a jump table, the linker will not be able 
to eliminate the code for the function even if the data that references it is unreferenced. 

Linking FORTRAN 77 Applications 

The Open Watcom FORTRAN 77 compiler always places each function and subroutine in 
its own code segment, even if they are contained in the same module. Therefore when 
linking with the "ELIMINATE" option the linker will be able to eliminate code on a 
function/subroutine basis. 
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END (DOS) 


3.25 The END Directive 

Formats: DOS 

The "BEGIN" directive is used to define the start of an overlay area. The "END" directive is used to define 
the end of an overlay area. An overlay area is a piece of memory in which overlays are loaded. All 
overlays defined between a "BEGIN" directive and the corresponding "END" directive are loaded into that 
overlay area. 

The format of the "BEGIN" directive (short form "B") is as follows. 

BEGIN 

The format of the "END" directive (short form "E") is as follows. 

END 


The END Directive 49 







ENDLINK 


3.26 The ENDLINK Directive 

Formats: All 

The "ENDLINK" directive is used to indicate the end of a new set of linker commands that are to be 
processed after the current set of commands has been processed. The format of the "ENDLINK" directive 
(short form "ENDL") is as follows. 


ENDLINK 


The "STARTLINK" directive, described in "The STARTLINK Directive" on page 166, is used to indicate 
the start of the set of commands. 
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EXIT (NetWare) 


3.27 The EXIT Option 

Formats: NetWare 

The format of the "EXIT" option (short form "EX") is as follows. 

OPTION EXIT=symbol_name 

where description: 

symbol jiame specifies the name of the procedure that is executed when an NLM is unloaded. 

The default name of the exit procedure is "_Stop". 

Note that the exit procedure cannot prevent the NLM from being unloaded. Once the exit procedure has 
executed, the NLM will be unloaded. The "CHECK" option can be used to specify a check procedure that 
can prevent an NLM from being unloaded. 
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3.28 The EXPORT Directive 

Formats: ELF, NetWare, OS/2, Win 16, Win32 

The "EXPORT" directive is used to tell the Open Watcom Linker which symbols are available for import 
by other executables. 

3.28.1 EXPORT - OS/2, Win16, Win32 oniy 

The "EXPORT" directive can be used to define the names and attributes of functions in Dynamic Link 
Libraries that are to be exported. An "EXPORT" definition must be specified for every Dynamic Link 
Library function that is to be made available externally. 

Winl6: An "EXPORT" directive is also required for the "window function". This function must be 

defined by all programs and is called by Windows to provide information to the program. 
Lor example, the window function is called when a window is created, destroyed or resized, 
when an item is selected from a menu, or when a scroll bar is being clicked with a mouse. 

The format of the "EXPORT" directive (short form "EXP") is as follows. 


EXPORT exportf, export} 
or 

EXPORT -Ihcjile 
OS/2 only: 

export ::= entry_name[.ordinal][=internal_name] 
[PRIVATE] [RESIDENT] [iopl_bytes] 

Winl6, Win32 only: 

export ::= entry_name[.ordinal][=internal_name] 
[PRIVATE] [RESIDENT] 


where 
entry _name 
ordinal 

internaljiame 


description: 

is the name to be used by other applications to call the function. 

is an ordinal value for the function. If the ordinal number is specified, other applications 
can reference the function by using this ordinal number. 

is the actual name of the function and should only be specified if it differs from the entry 
name. 


PRIVATE (no short form ) specifies that the function’s entry name should be included in the DLL’s 
export table, but not included in any import library that the linker generates. 

RESIDENT (short form "RES") specifies that the function’s entry name should be kept resident in 
memory (i.e., added to the resident names table). 

By default, the entry name is always made memory resident if an ordinal is not specified 
(i.e., it is implicitly RESIDENT). For 16-bit Windows, the limit on the size of the resident 
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names table is 64K bytes. Memory resident entry names allow the operating system to 
resolve calls more efficiently when the call is by entry name rather than by ordinal. 

If an ordinal is specified and RESIDENT is not specified, the entry name is added to the 
non-resident names table (i.e., it is implicitly non-RESIDENT). If both the ordinal and the 
RESIDENT keyword are specified, the symbol is placed in the resident names table. 

If you do not want an entry name to appear in either the resident or non-resident names 
table, you can use the "ANONYMOUSEXPORT" directive described in "The 
ANONYMOUSEXPORT Directive" on page 22. 

iopl_bytes (OS/2 only) is required for functions that execute with I/O privilege, iopljbytes specifies 
that total size of the function’s arguments in bytes. When such a function is executed, the 
specified number of bytes is copied from the caller’s stack to the I/O-privileged function’s 
stack. The maximum number of bytes allowed is 63. 

Ibc_Jile is a file specification for the name of a librarian command file. If no file extension is 

specified, a file extension of "lbc" is assumed. The linker will process the librarian 
command file and look for commands to the librarian that are used to create import library 
entries. These commands have the following form. 

++sym.dll_ name[.[altsym].export_ name][.ordinal] 

where description: 

sym is the name of a symbol in a Dynamic Link Library. 

dlljiame is the name of the Dynamic Link Library that defines sym. 

altsym is the name of a symbol in a Dynamic Link Library. When omitted, the 

default symbol name is sym. 

export jiame is the name that an application that is linking to the Dynamic Link Library 
uses to reference sym. When omitted, the default export name is sym. 

ordinal is the ordinal value that can be used to identify sym instead of using the 

name export_ name. 

All other librarian commands will be ignored. 

Notes: 

1. By default, the Open Watcom C and C++ compilers append an underscore to all function 
names. This should be considered when specifying entry_name and internal_name in an 
"EXPORT" directive. 

2. If the name contains characters that are special to the linker then the name may be placed inside 
apostrophes (e.g., export ' myfunc@8'). 

3. If the export declspec modifier is used in the source code, it is the equivalent of using the 
following linker directive: 

EXPORT entry_ name RESIDENT 
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3.28.2 EXPORT - ELF only 

The "EXPORT" directive is used to tell the Open Watcom Linker which symbols are available for import 
by other executables. The format of the "EXPORT" directive (short form "EXP") is as follows. 


EXP OR T entry_name {, en try _name} 


where description: 

entry_name is the name of the exported symbol. 

Notes: 

1. By default, the Open Watcom C and C++ compilers append an underscore to all function 
names. This should be considered when specifying entry_name in an "EXPORT" directive. 

2. If the name contains characters that are special to the linker then the name may be placed inside 
apostrophes (e.g., export 'myfunc@8')- 

3.28.3 EXPORT - Netware only 

The "EXPORT" directive is used to tell the Open Watcom Linker which symbols are available for import 
by other NLMs. The format of the "EXPORT" directive (short form "EXP") is as follows. 


EXP OR T entry _name {, en try _name} 


where description: 

entry_name is the name of the exported symbol. 

Notes: 

1. If the name contains characters that are special to the linker then the name may be placed inside 
apostrophes (e.g., export 'myfunc@8'). 
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3.29 The FARCALLS Option 

Formats: All 

The "FARCALLS" option tells the Open Watcom Linker to optimize Far Calls. This is the default setting 
for Open Watcom Linker The format of the "FARCALLS" option (short form "FAR") is as follows. 


OPTION FARCALLS 


The "NOFARCALLS" option turns off Far Calls optimization. The format of the "NOFARCALLS" option 
(short form "NOFAR") is as follows. 


OPTION NOFARCALLS 


You can specify the "NOFARCALLS" option in the default directive files wlink . Ink or 
wlsystem. Ink if required. 

The file wlink. Ink is a special linker directive file that is automatically processed by the Open Watcom 
Linker before processing any other directives. On a DOS, ZDOS, OS/2, or Windows-hosted system, this 
file must be located in one of the paths specified in the PATH environment variable. On a QNX-hosted 
system, this file should be located in the /etc directory. A default version of this file is located in the 
\watcom\binw directory on DOS-hosted systems, the \watcom\binp directory on OS/2-hosted 
systems, the /etc directory on QNX-hosted systems, and the \watcom\binnt directory on Windows 
95 or Windows NT-hosted systems. Note that the file wlink. Ink includes the file wl system. Ink 
which is located in the \watcom\binw directory on DOS, OS/2, or Windows-hosted systems and the 
/etc directory on QNX-hosted systems. 

The files wlink. Ink and wlsystem. Ink reference the WATCOM environment variable which must 
be set to the directory in which you installed your software. 

The default name of the linker directive file (wlink. Ink) can be overridden by the WLINK_LNK 
environment variable. If the specified file can’t be opened, the default file name will be used. For 
example, if the WLINK_LNK environment variable is defined as follows 

set WLINK_ LNK=my. Ink 

then the Open Watcom Linker will attempt to use a my. Ink directive file, and if that file cannot be 
opened, the linker will revert to using the default wlink . Ink file. 
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3.30 The FILE Directive 

Formats: All 


The "FILE" directive is used to specify the object files and library modules that the Open Watcom Linker is 
to process. The format of the "FILE" directive (short form "F") is as follows. 



where description: 

objjile is a file specification for the name of an object file. If no file extension is specified, a file 

extension of "obj" is assumed if you are running a DOS, OS/2 or Windows-hosted version 
of the Open Watcom Linker. Also, if you are running a DOS, OS/2 or Windows-hosted 
version of the Open Watcom Linker, the object file specification can contain wild cards (*, 
?). A file extension of "o" is assumed if you are running a UNIX-hosted version of the 
Open Watcom Linker. 

library_Jile is a file specification for the name of a library file. Note that the file extension of the 

library file (usually "lib") must be specified; otherwise an object file will be assumed. 
When a library file is specified, all object files in the library are included (whether required 
or not). 

obj module is the name of an object module defined in an object or library file. 

Consider the following example. 

Example: 

wlink system my_ os f \math\sin, mycos 

The Open Watcom Linker is instructed to process the following object files; 

\math\sin.obj 

mycos.obj 

The object file "mycos.obj" is located in the current directory since no path was specified. 

More than one "FILE" directive may be used. The following example is equivalent to the preceding one. 

Example: 

wlink system my_ os f \math\sin f mycos 

Thus, other directives may be placed between lists of object files. 

The "FILE" directive can also specify object modules from a library file or object file. Consider the 

following example. 
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Example: 

wlink system my_ os f \math\math.lib(sin) 

The Open Watcom Linker is instructed to process the object module "sin" contained in the library file 
"math.lib" in the directory "\math". 

In the following example, the Open Watcom Linker will process the object module "sin" contained in the 
object file "math.obj" in the directory "\math". 

Example: 

wlink system my_ os f \math\math (sin) 

In the following example, the Open Watcom Linker will include all object modules contained in the library 
file "math.lib" in the directory "\math". 

Example: 

wlink system my_ os f \math\math.lib 
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3.31 The FILLCHAR Option 

Formats: All 

The "FILLCHAR" option (short form "FILL") specifies the byte value used to fill gaps in the output image. 


OPTION FILLCHAR=n 


where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

n specifies the value to be used in blank areas of the output image. The value must be in the range of 0 to 
255, inclusive. 

This option is most useful for raw binary output that will be programmed into an (E)EPROM where a value 
of 255 (Oxff) is preferred. The default value of n is zero. 
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3.32 The FIXEDLIB Directive 

Formats: DOS 

The "FIXEDLIB" directive can be used to explicitly place the modules from a library file in the overlay 
section in which the "FIXEDLIB" directive appears. The format of the "FIXEDLIB" directive (short form 
"FIX") is as follows. 


FIXEDLIB library_Jile{,library_file} 


where description: 

library_Jile is a file specification for the name of a library file. If no file extension is specified, a file 

extension of "lib" is assumed. 

Consider the following example. 

begin 

section filel, file2 
section file3 
fixedlib mylib 
end 

Two overlay sections are defined. The first contains filel and file2 . The second contains file 3 
and all modules contained in the library file "mylib.lib". 

Note that all modules extracted from library files that appear in a "LIBRARY" directive are placed in the 
root unless the "DISTRIBUTE" option is specified. For more information on the "DISTRIBUTE" option, 
see the section entitled "The DISTRIBUTE Option" on page 45. 
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3.33 The FORCEVECTOR Directive 

Formats: DOS 

The "FORCEVECTOR" directive forces the Open Watcom Linker to generate an overlay vector for the 
specified symbols. The format of the "FORCEVECTOR" directive (short form "FORCEVE") is as follows. 

FORCEVECTOR symbol_name{,symboljiame} 

where description: 

symbol jiame is a symbol name. 
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3.34 The FORMAT Directive 

Formats: All 

The "FORMAT" directive is used to specify the format of the executable file that the Open Watcom Linker 
is to generate. The format of the "FORMAT" directive (short form "FORM") is as follows. 


FORMAT form 

form ::= DOS [COM] 

I ZDOS [SYS I IIWD I FSD] 

I RAW [BIN I HEX] 

I WINDOWS [win_dll] [MEMORY] [FONT] 

I WINDOWS VXD [DYNAMIC] 

I WINDOWS NT [TNT I RDOS] [dll_attrs] 

I OS2 [os2_type] [dll_attrs I os2_attrs] 

I PHARLAP [EXTENDED I REX I SEGMENTED] 

I NOVELL [NLM I LAN I DSK I NAM I ’number’] ’description’ 
I QNX [FLAT] 

I ELF [DLL] 

win_dll ::= DLL [INITGLOBAL I INITINSTANCE] 

dll_attrs ::= DLL [INITGLOBAL I INITINSTANCE] 
[TERMINSTANCE I TERMGLOBAL] 

os2_type ::= FLAT \LE\LX 

os2_attrs ::= PM I PMCOMPATIBLE I FULLSCREEN 
I PHYSDEVICE I VIRTDEVICE 


where description: 

DOS (short form "D") tells the Open Watcom Linker to generate a DOS "EXE" file. 

The name of the executable file will have extension "exe". If "COM" is specified, a DOS 
"COM" file will be generated in which case the name of the executable file will have 
extension "com". Note that these default extensions can be overridden by using the 
"NAME" directive to name the executable file. 

Not all programs can be generated in the "COM" format. The following rules must be 
followed. 

1. The program must consist of only one physical segment. This implies that the 
size of the program (code and data) must be less than 64k. 

2. The program must not contain any segment relocation. A warning message will 
be issued by the Open Watcom Linker each time a segment relocation is 
encountered. 
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A DOS "COM" file cannot contain debugging information. If you wish to debug a DOS 
"COM" file, you must use the "SYMFILE" option to instruct the Open Watcom Linker to 
place the debugging information in a separate file. 

For more information on DOS executable file formats, see the chapter entitled "The DOS 
Executable File Format" on page 183. 

(short form "ZD") tells the Open Watcom Linker to generate a ZDOS "EXE" file. 

The name of the executable file will have extension "exe". If "SYS", "HWD" or "FSD" is 
specified, a ZDOS driver file will be generated in which case the name of the executable 
file will have the extension "sys", "hwd" or "fsd". Note that these default extensions can be 
overridden by using the "NAME" directive to name the executable file. 

For more information on ZDOS executable file formats, see the chapter entitled "The 
ZDOS Executable File Format" on page 197. 

(short form "R") tells the Open Watcom Linker to generate a RAW output file. 

If "HEX" is specified, a raw 32-bit output file in Intel Hex format with the extension "hex" 
will be created. When "BIN" is specified or RAW is given without further specification, a 
raw 32-bit image with the extension "bin" will be created. Note that these default 
extensions can be overridden by using the "NAME" directive to name the executable file. 

A raw output file cannot contain debugging information. If you wish to debug a raw file, 
you must use the "SYMFILE" option to instruct the Open Watcom Linker to place the 
debugging information in a separate file. 

For more information on RAW executable file formats, see the chapter entitled "The RAW 
File Format" on page 201. 

tells the Open Watcom Linker to generate a Winl6 (16-bit Windows) executable file. 

The name of the executable file will have extension "exe". If "DLL" (short form "DL") is 
specified, a Dynamic Link Library will be generated; the name of the executable file will 
also have extension "exe". Note that these default extensions can be overridden by using 
the "NAME" directive to name the executable file. 

Specifying "INITGLOBAL" (short form "INITG") will cause Windows to call an 
initialization routine the first time the Dynamic Link Library is loaded. The 
"INITGLOBAL" option should be used with "OPTION ONEAUTODATA" (the default for 
Dynamic Link Libraries). If the "INITGLOBAL" option is used with "OPTION 
MANY AUTODATA", the initialization code will be called once for the first data segment 
allocated but not for subsequent allocations (this is generally not desirable behaviour and 
will likely cause a program fault). 

Specifying "INITINSTANCE" (short form "INITI") will cause Windows to call an 
initialization routine each time the Dynamic Link Library is used by a process. The 
"INITINSTANCE" option should be used with "OPTION MANY AUTODATA" (the 
default for executable programs). 

In either case, the initialization routine is defined by the start address. If neither 
"INITGLOBAL" or "INITINSTANCE" is specified, "INITGLOBAL" is assumed. 
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Specifying "MEMORY" (short form "MEM") indicates that the application will run in 
standard or enhanced mode. If Windows 3.0 is running in standard and enhanced mode, 
and "MEMORY" is not specified, a warning message will be issued. The "MEMORY" 
specification was used in the transition from Windows 2.0 to Windows 3.0. The 
"MEMORY" specification is ignored in Windows 3.1 or later. 

Specifying "FONT" (short form "FO") indicates that the proportional-spaced system font 
can be used. Otherwise, the old-style mono-spaced system font will be used. The "FONT" 
specification was used in the transition from Windows 2.0 to Windows 3.0. The "FONT" 
specification is ignored in Windows 3.1 or later. 

For more information on Windows executable file formats, see the chapter entitled "The 
Winl6 Executable and DLL File Formats" on page 229. 

WINDOWS VXD tells the Open Watcom Linker to generate a Windows VxD file (Virtual Device Driver). 

The name of the file will have extension "386". Note that this default extension can be 
overridden by using the "NAME" directive to name the driver file. 

Specifying "DYNAMIC" (short form "DYN"), dynamicaly loadable driver will be 
generated (only for Windows 3.11 or 9x). By default the Open Watcom Linker generate 
staticaly loadable driver (for Windows 3.x or 9x). 

For more information on Windows Virtual Device Driver file format, see the chapter 
entitled "The Windows Virtual Device Driver File Format" on page 235. 

WINDOWS NT tells the Open Watcom Linker to generate a Win32 executable file ("PE" format). 

If "TNT" is specified, an executable for the Phar Lap TNT DOS extender is created. A 
"PL" format (rather than "PE") executable is created so that the Phar Lap TNT DOS 
extender will always run the application (including under Windows NT). 

If "RDOS" is specified, an executable for the RDOS operating system is created. 

If "DLL" (short form "DL") is specified, a Dynamic Link Library will be generated in 
which case the name of the executable file will have extension "dll". Note that these 
default extensions can be overridden by using the "NAME" directive to name the 
executable file. 

Specifying "INITGLOBAL" (short form "INITG") will cause the initialization routine to be 
called the first time the Dynamic Link Library is loaded. 

Specifying "INITINSTANCE" (short form "INITI") will cause the initialization routine to 
be called each time the Dynamic Link Library is referenced by a process. 

In either case, the initialization routine is defined by the start address. If neither 
"INITGLOBAL" or "INITINSTANCE" is specified, "INITGLOBAL" is assumed. 

It is also possible to specify whether the initialization routine is to be called at DLL 
termination or not. Specifying "TERMGLOBAL" (short form "TERMG") will cause the 
initialization routine to be called when the last instance of the Dynamic Link Library is 
terminated. Specifying "TERMINSTANCE" (short form "TERMI") will cause the 
initialization routine to be called each time an instance of the Dynamic Link Library is 
terminated. Note that the initialization routine is passed an argument indicating whether it 
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is being called during DLL initialization or DLL termination. If "INITINSTANCE" is used 
and no termination option is specified, "TERMINSTANCE" is assumed. If 
"INITGLOBAL" is used and no termination option is specified, "TERMGLOBAL" is 
assumed. 

For more information on Windows NT executable file formats, see the chapter entitled 
"The Win32 Executable and DLL File Formats" on page 239. 

tells the Open Watcom Linker to generate an OS/2 executable file format. 

The name of the executable file will have extension "exe". If "LE" is specified, an early 
form of the OS/2 32-bit linear executable will be generated. This executable file format is 
required by the CauseWay DOS extender, Tenberry Software’s DOS/4G and DOS/4GW 
DOS extenders, and similar products. 

In order to improve load time and minimize the size of the executable file, the OS/2 32-bit 
linear executable file format was changed. If "LX" or "FLAT" (short form "FL") is 
specified, the new form of the OS/2 32-bit linear executable will be generated. This 
executable file format is required by the FlashTek DOS extender and 32-bit OS/2 
executables. 

If "FLAT", "LX" or "LE" is not specified, an OS/2 16-bit executable will be generated. 

If "DLL" (short form "DL") is specified, a Dynamic Link Library will be generated in 
which case the name of the executable file will have extension "dll". Note that these 
default extensions can be overridden by using the "NAME" directive to name the 
executable file. 

Specifying "INITGLOBAL" (short form "INITG") will cause the initialization routine to be 
called the first time the Dynamic Link Library is loaded. The "INITGLOBAL" option 
should be used with "OPTION ONEAUTODATA" (the default for Dynamic Link 
Libraries). If the "INITGLOBAL" option is used with "OPTION MANYAUTODATA", 
the initialization code will be called once for the first data segment allocated but not for 
subsequent allocations (this is generally not desirable behaviour and will likely cause a 
program fault). 

Specifying "INITINSTANCE" (short form "INITI") will cause the initialization routine to 
be called each time the Dynamic Link Library is referenced by a process. The 
"INITINSTANCE" option should be used with "OPTION MANYAUTODATA" (the 
default for executable programs). 

In either case, the initialization routine is defined by the start address. If neither 
"INITGLOBAL" or "INITINSTANCE" is specified, "INITGLOBAL" is assumed. 

For OS/2 32-bit linear executable files, it is also possible to specify whether the 
initialization routine is to be called at DLL termination or not. Specifying 
"TERMGLOBAL" (short form "TERMG") will cause the initialization routine to be called 
when the last instance of the Dynamic Link Library is terminated. Specifying 
"TERMINSTANCE" (short form "TERMI") will cause the initialization routine to be called 
each time an instance of the Dynamic Link Library is terminated. Note that the 
initialization routine is passed an argument indicating whether it is being called during DLL 
initialization or DLL termination. If "INITINSTANCE" is used and no termination option 
is specified, "TERMINSTANCE" is assumed. If "INITGLOBAL" is used and no 
termination option is specified, "TERMGLOBAL" is assumed. 
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If "PM" is specified, a Presentation Manager application will be created. The application 
uses the API provided by the Presentation Manager and must be executed in the 
Presentation Manager environment. 

If "PMCOMPATIBLE" (short form "PMC") is specified, an application compatible with 
Presentation Manager will be created. The application can run inside the Presentation 
Manager or it can run in a separate screen group. An application can be of this type if it 
uses the proper subset of OS/2 video, keyboard, and mouse functions supported in the 
Presentation Manager applications. This is the default. 

If "FULLSCREEN" (short form "FULL") is specified, an OS/2 full screen application will 
be created. The application will run in a separate screen group from the Presentation 
Manager. 

If "PHYSDEVICE" (short form "PHYS") is specified, the executable file is marked as a 
physical device driver. 

If "VIRTDEVICE" (short form "VIRT") is specified, the executable file is marked as a 
virtual device driver. 

For more information on OS/2 executable file formats, see the chapter entitled "The OS/2 
Executable and DLL File Formats" on page 215. 

(short form "PHAR") tells the Open Watcom Linker to generate an executable file that will 
run under Phar Lap’s 386IDOS-Extender. 

There are 4 forms of executable files: simple, extended, relocatable and segmented. If 
"EXTENDED" (short form "EXT") is specified, an extended form of the executable file 
with file extension "exp" will be generated. If "REX" is specified, a relocatable executable 
file with file extension "rex" will be generated. If "SEGMENTED" (short form "SEG") is 
specified, a segmented executable file with file extension "exp" will be generated. If 
neither "EXTENDED", "REX" or "SEGMENTED" is specified, a simple executable file 
with file extension "exp" will be generated. Note that the default file extensions can be 
overridden by using the "NAME" directive to name the executable file. 

The simple form is for flat model 386 applications. It is the only format that can be loaded 
by earlier versions of 386IDOS-Extender (earlier than 1.2). 

The extended form is used for flat model applications that have been linked in a way which 
requires a method of specifying more information for 386IDOS-Extender than possible with 
the simple form. 

The relocatable form is similar to the simple form. Unique to the relocatable form is an 
offset relocation table. This allows the loader to load the program at any location it 
chooses. 

The segmented form is used for embedded system applications like Intel RMX. These 
executables cannot be loaded by 386IDOS-Extender. 

A simple form of the executable file is generated in all but the following cases. 

1. "EXTENDED" is specified in the "FORMAT" directive. 
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2. The "RUNTIME" directive is specified. Options specified by the "RUNTIME" 
directive can only be specified in the extended form of the executable file. 

3. The "OFFSET" option is specified. The value specified in the "OFFSET" option 
can only be specified in the extended form of the executable file. 

4. "REX" is specified in the "FORMAT" directive. In this case, the relocatable 
form will be generated. You must not specify the "RUNTIME" directive or the 
"OFFSET" option when generating the relocatable form. 

5. "SEGMENTED" is specified in the "FORMAT" directive. In this case, the 
segmented form will be generated. 

For more information on Phar Lap executable file formats, see the chapter entitled "The 
Phar Lap Executable File Format" on page 221. 

(short form "NOV") tells the Open Watcom Linker to generate a NetWare executable file, 
more commonly called a NetWare Loadable Module (NLM). 

NLMs are further classified according to their function. The executable file will have a file 
extension that depends on the class of the NLM being generated. The following describes 
the classification of NLMs. 

LAN instructs the Open Watcom Linker to generate a LAN driver. ALAN 

driver is a device driver for Local Area Network hardware. A file 
extension of "lan" is used for the name of the executable file. 

DSK instructs the Open Watcom Linker to generate a disk driver. A file 

extension of "dsk" is used for the name of the executable file. 

NAM instructs the Open Watcom Linker to generate a file system name-space 

support module. A file extension of "nam" is used for the name of the 
executable file. 

MSL instructs the Open Watcom Linker to generate a Mirrored Server Link 

module. The default file extension is "msl" 

CDM instructs the Open Watcom Linker to generate a Custom Device module. 

The default file extension is "cdm" 

HAM instructs the Open Watcom Linker to generate a Host Adapter module. The 

default file extension is "ham" 

NLM instructs the Open Watcom Linker to generate a utility or server 

application. This is the default. A file extension of "nlm" is used for the 
name of the executable file. 

’number’ instructs the Open Watcom Linker to generate a specific type of NLM 

using ’number’. This is a 32 bit value that corresponds to Novell allocated 
NLM types. 

These are the current defined values: 
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1 

2 

3 

4 

5 

6 

7 

8 

9 

10 
11 
12 

13 

14 

15 

16 
21 
22 

23 

24 

25 

26 

27 

28 


Specifies a standard NLM (default extension .NLM) 

Specifies a disk driver module (default extension .DSK) 

Specifies a namespace driver module (default extension 
.NAM) 

Specifies a LAN driver module (default extension .LAN) 
Specifies a utility NLM (default extension .NLM) 
Specifies a Mirrored Server Link module (default .MSL) 
Specifies an Operating System module (default .NLM) 
Specifies a Page High OS module (default .NLM) 
Specifies a Host Adapter module (default .HAM) 
Specifies a Custom Device module (default .CDM) 
Reserved for Novell usage 
Reserved for Novell usage 
Specifies a Ghost module (default .NLM) 

Specifies an SMP driver module (default .NLM) 
Specifies a NIOS module (default .NLM) 

Specifies a CIOS CAD type module (default .NLM) 

Specifies a CIOS CLS type module (default .NLM) 

Reserved for Novell NICI usage 

Reserved for Novell NICI usage 

Reserved for Novell NICI usage 

Reserved for Novell NICI usage 

Reserved for Novell NICI usage 

Reserved for Novell NICI usage 

Reserved for Novell NICI usage 

Reserved for Novell NICI usage 


description is a textual description of the program being linked. 
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For more information on NetWare executable file formats, see the chapter entitled "The 
NetWare O/S Executable File Format" on page 209. 

QNX tells the Open Watcom Linker to generate a QNX executable file. 

If "FLAT" (short form "FL") is specified, a 32-bit flat executable file is generated. 

Under QNX, no file extension is added to the executable file name. 

Under other operating systems, the name of the executable file will have the extension 
"qnx". Note that this default extension can be overridden by using the "NAME" directive 
to name the executable file. 

For more information on QNX executable file formats, see the chapter entitled "The QNX 
Executable File Format" on page 225. 

ELF tells the Open Watcom Linker to generate an ELF format executable file. 

ELF format DLLs can also be created. 

For more information on ELF executable file formats, see the chapter entitled "The ELF 
Executable File Format" on page 205. 

If no "FORMAT" directive is specified, the executable file format will be selected for each of the following 
host systems in the way described. 


DOS If 16-bit object files are encountered, a 16-bit DOS executable will be created. If 32-bit 

object files are encountered, a 32-bit DOS/4G executable will be created. 

OS/2 If 16-bit object files are encountered, a 16-bit OS/2 executable will be created. If 32-bit 

object files are encountered, a 32-bit OS/2 executable will be created. 


QNX If 16-bit object files are encountered, a 16-bit QNX executable will be created. If 32-bit 

object files are encountered, a 32-bit QNX executable will be created. 


Windows NT If 16-bit object files are encountered, a 16-bit Windows executable will be created. If 
32-bit object files are encountered, a 32-bit Win32 executable will be created. 

Windows 95 If 16-bit object files are encountered, a 16-bit Windows executable will be created. If 
32-bit object files are encountered, a 32-bit Win32 executable will be created. 
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3.35 The FULLHEADER Option 

Formats: DOS 

This option is valid for 16-bit DOS "EXE" files. By default, the Open Watcom Linker writes a "MZ" 
executable header which is just large enough to contain all necessary data. The "FULLHEADER" option 
may be used to force the header size to 64 bytes, plus the size of relocation records. The format of the 
"FULLHEADER" option (short form "FULLH") is as follows. 


OPTION FULLHEADER 


Notes: 

1. This option may be useful when creating a 16-bit executable which is to be used as a stub 
program for a non-DOS executable. 

2. This option is not required when using the Open Watcom Linker. It is only needed when the 
non-DOS executable is created using a third-party linker which does not automatically extend 
the header size. 
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3.36 The HEAPSIZE Option 

Formats: OS/2, QNX, Win16, Win32 

The "HEAPSIZE" option specifies the size of the heap required by the application. The format of the 
"HEAPSIZE" option (short form "H") is as follows. 

OPTION HEAPSIZE=n 


where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

n specifies the size of the heap. The default heap size is 0 bytes. The maximum value of n is 65536 (64K) 
for 16-bit applications and 4G for 32-bit applications which is the maximum size of a physical segment. 
Actually, for a particular application, the maximum value of n is 64K or 4G less the size of group 
"DGROUP". 
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3.37 The HELP Option 

Formats: NetWare 

The "HELP" option specifies the file name of an internationalized help file whose language corresponds to 
the message file bound to this NLM. 

The format of the "HELP" option (short form "HE") is as follows. 

OPTION HELP=help Jile 

where description: 

help Jile is the name of the help file. 
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3.38 The HSHIFT Option 

Formats: DOS, OS/2, QNX, Win 16 

The "HSHIFT" defines the relationship between segment and linear address in a segmented executable. 
The format of the "HSHIFT" option is as follows. 


OPTION HSHIFT=n 


where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

n specifies the number of digits to right shift a 32-bit value containing a segment address in its upper 16 bits 
in order to convert it to part of a linear address. In more conventional terms, (16 - n ) is the amount to shift 
a segment value left in order to convert it to part of a linear address. 

The "HSHIFT" Option is useful for non-standard segmented architectures that have different alignment 
between segments and linear addresses, such as the IP cores by ARC, Inc. These cores support a 24-bit 
addressing mode where segment addresses are shifted 8 bits to form part of the linear address. The n value 
and its semantics match the analogous variable used by the compiler for computing addresses in the huge 
memory model. 

The default value of n is 12, representing the 4-bit shift used in conventional x86 CPUs. 


72 


The HSHIFT Option 







IMPFILE (NetWare, OS/2, Win16, Win32) 


3.39 The IMPFILE Option 

Formats: NetWare, OS/2, Win 16, Win32 

The "IMPFILE" option requests the linker to produce a Open Watcom Library Manager command file that 
can be used to create an import library that corresponds to the DLL that is being generated. This option is 
useful in situations where the Open Watcom Linker cannot create an import library file when you have 
specified the "IMPLIB" option (i.e., the linker fails to launch Open Watcom Library Manager). 

The format of the "IMPFILE" option (short form "IMPF") is as follows. 


OPTION IMPFILE[=imp Jile] 


where description: 

imp Jile is a file specification for the name of the command file that can be used to create the import 

library file using the Open Watcom Library Manager. If no file extension is specified, no 
file extension is assumed. 

By default, no command file is generated. Specifying this option causes the linker to generate an import 
library command file. The import library command file contains a list of the entry points in your DLL. 
When this command file is processed by the Open Watcom Library Manager, an import library file will be 
produced. 

If no file name is specified, the import library command file will have a default file extension of "lbc" and 
the same file name as the DLL file. Note that the import library command file will be created in the same 
directory as the DLL file. The DLL file path and name can be specified in the "NAME" directive. 

Alternatively, a library command file path and name can be specified. The following directive instructs the 
linker to generate a import library command file and call it "mylib.lcf" regardless of the name of the 
executable file. 

option impfile=mylib.lcf 

You can also specify a path and/or file extension when using the "IMPFILE=" form of the "IMPFILE" 
option. 
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3.40 The IMPLIB Option 

Formats: NetWare, OS/2, Win16, Win32 

The "IMPLIB" option requests the linker to produce an import library that corresponds to the DLL that is 
being generated. The format of the "IMPLIB" option (short form "IMPL") is as follows. 

OPTION IMPLIB[=imp_lib] 

where description: 

imp_lib is a file specification for the name of the import library file. If no file extension is 

specified, a file extension of "lib" is assumed. 

By default, no library file is generated. Specifying this option causes the Open Watcom Linker to generate 
an import library file. The import library file contains a list of the entry points in your DLL. 

If no file name is specified, the import library file will have a default file extension of "lib" and the same 
file name as the DLL file. Note that the import library file will be created in the same directory as the DLL 
file. The DLL file path and name can be specified in the "NAME" directive. 

Alternatively, a library file path and name can be specified. The following directive instructs the linker to 
generate a library file and call it "mylib.imp" regardless of the name of the executable file. 

option implib=mylib.imp 

You can also specify a path and/or file extension when using the "IMPLIB=" form of the "IMPLIB" option. 

Note: At present, the linker spawns the Open Watcom Library Manager to create the import library file. 
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3.41 The IMPORT Directive 

Formats: ELF, NetWare, OS/2, Win 16, Win32 

The "IMPORT" directive is used to tell the Open Watcom Linker what symbols are defined externally in 
other executables. 

3.41.1 IMPORT - OS/2, Win16, Win32 only 

The "IMPORT" directive describes a function that belongs to a Dynamic Link Library. The format of the 
"IMPORT" directive (short form "IMP") is as follows. 


IMPORT import{,import} 

import ::= internal jiame module_name[.entry_name I ordinal] 


where description: 

internal jiame is the name the application used to call the function. 

module jiame is the name of the Dynamic Link Library. Note that this need not be the same as the file 
name of the executable file containing the Dynamic Link Library. This name corresponds 
to the name specified by the "MODNAME" option when the Dynamic Link Library was 
created. 


entry jiame is the actual name of the function as defined in the Dynamic Link Library. 

ordinal is the ordinal value of the function. The ordinal number is an alternate method that can be 

used to reference a function in a Dynamic Link Library. 

Notes: 

1. By default, the Open Watcom C and C++ compilers append an underscore to all function 
names. This should be considered when specifying internal jiame and entry jiame in an 
"IMPORT" directive. 

2. If the name contains characters that are special to the linker then the name may be placed inside 
apostrophes (e.g., import 'myfunc@8'). 


The preferred method to resolve references to Dynamic Link Libraries is through the use of import 
libraries. See the sections entitled "Using a Dynamic Link Library" on page 218, "Using a Dynamic Link 
Library" on page 232, or "Using a Dynamic Link Library" on page 242 for more information on import 
libraries. 
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3.41.2 IMPORT-ELF only 

The "IMPORT" directive is used to tell the Open Watcom Linker what symbols are defined externally in 
other executables. The format of the "IMPORT" directive (short form "IMP") is as follows. 


IMPOR T externaljiame {, externaljiame} 


where description: 

external jiame is the name of the external symbol. 

Notes: 

1. By default, the Open Watcom C and C++ compilers append an underscore to all function 
names. This should be considered when specifying external jiame in an "IMPORT" directive. 

2. If the name contains characters that are special to the linker then the name may be placed inside 
apostrophes (e.g., import 'myfunc@8')- 

3.41.3 IMPORT - Netware only 

The "IMPORT" directive is used to tell the Open Watcom Linker what symbols are defined externally in 
other NLMs. The format of the "IMPORT" directive (short form "IMP") is as follows. 


IMPOR T external jiame {, external jiame} 


where description: 

external jiame is the name of the external symbol. 

Notes: 

1. If the name contains characters that are special to the linker then the name may be placed inside 
apostrophes (e.g., import 'myfunc@8'). 

If an NLM contains external symbols, the NLMs that define the external symbols must be loaded before the 
NLM that references the external symbols is loaded. 
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3.42 The @ Directive 


The "@" directive instructs the Open Watcom Linker to process directives from an alternate source. The 
format of the " @" directive is as follows. 


@directive_var 

or 

@directive _Jile 


where description: 

directive_var is the name of an environment variable. The directives specified by the value of 
directive_ var will be processed. 

directive_Jile is a file specification for the name of a linker directive file. A file extension of "Ink" is 
assumed if no file extension is specified. 

The environment variable approach to specifying linker directives allows you to specify commonly used 
directives without having to specify them each time you invoke the Open Watcom Linker. If the 
environment variable "wlink" is set as in the following example, 

set wlink=debug watcom all option map, verbose library math 
wlink @wlink 

then each time the Open Watcom Linker is invoked, full debugging information will be generated, a 
verbose map file will be created, and the library file "math.lib" will be searched for undefined references. 

A linker directive file is useful, for example, when the linker input consists of a large number of object files 
and you do not want to type their names on the command line each time you link your program. Note that a 
linker directive file can also include other linker directive files. 

Let the file "memos.Ink" be a directive file containing the following lines. 

system my_ os 
name memos 
file memos 
file actions 
file read 
file msg 
file prompt 
file memmgr 

library \termio\screen 
library \termio\keyboard 

Winl6 only: We must also use the "EXPORT" directive to define the window function. This is done 
using the following directive. 

export window_ function 

Consider the following example. 
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Example: 

wlink @memos 

The Open Watcom Linker is instructed to process the contents of the directive file "memos.Ink". The 
executable image file will be called "memos.exe". The following object files will be loaded from the 
current directory. 

memos.obj 
actions.obj 
read.obj 
msg. ob j 
prompt.obj 
memmgr.obj 

If any unresolved symbol references remain after all object files have been processed, the library files 
"screen.lib" and "keyboard.lib" in the directory "\termio" will be searched (in the order listed). 

Notes: 

1. In the above example, we did not provide the file extension when the directive file was specified. 
The Open Watcom Linker assumes a file extension of "Ink" if none is present. 

2. It is not necessary to list each object file and library with a separate directive. The following 
linker directive file is equivalent. 

system my_ os 
name memos 

file memos,actions,read,msg,prompt,memmgr 
library \termio\screen,\termio\keyboard 

However, if you want to selectively specify what debugging information should be included, the 
first style of directive file will be easier to use. This is illustrated in the following sample 
directive file. 

system my_ os 

name memos 

debug watcom lines 

file memos 

debug watcom all 

file actions 

debug watcom lines 

file read 

file msg 

file prompt 

file memmgr 

debug watcom 

library \termio\screen 

library \termio\keyboard 

3. Information for a particular directive can span directive files. This is illustrated in the following 
sample directive file. 

system my_ os 

file memos, actions, read, msg, prompt, memmgr 
file Sdbgfiles 
library \termio\screen 
library \termio\keyboard 
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The directive file "dbgfiles.lnk" contains, for example, those object files that are used for 
debugging purposes. 
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3.43 The INCREMENTAL Option 

Formats: ELF, OS/2, PharLap, QNX, Win 16, Win32 

The "INCREMENTAL" option can be used to enable incremental linking. Incremental linking is a process 
whereby the linker attempts to modify the existing executable file by changing only those portions for 
which new object files are provided. 

The format of the "INCREMENTAL" option (short form "INC") is as follows. 


OPTION INCREMENTAL[=inc Jile_name ] 


where description: 

inc_Jile_name is a file specification for the name of the incremental information file. If no file extension 
is specified, a file extension of "ilk" is assumed. 

This option engages the incremental linking feature of the linker. This option must be one of the first 
options encountered in the list of directives and options supplied to the linker. If the option is presented too 
late, the linker will issue a diagnostic message. 

By default, the incremental information file has the same name as the program except with an "ilk" 
extension unless the "NAME" directive has not been seen yet. If this is the case then the file is called 
_ wlink.ilk. 

The linker’s incremental linking technique is very resistant to changes in the underlying object files - there 
are very few cases where an incremental re-link is not possible. The options "ELIMINATE" and 
"VFREMOVAL" cannot be used at the same time as incremental linking. 

It is possible, over time, to accumulate unneeded functions in the executable by using incremental linking. 
To guarantee an executable of minimum size, you can cause a full relink by deleting the ".ilk" file or by not 
specifying the "INCREMENTAL" option. 

Do not use a post processor like the Open Watcorn Resource Compiler on the executable file since this will 
damage the data structures maintained by the linker. Add resources to the executable file using the 
"RESOURCE" option which is described in "The RESOURCE Directive" on page 146. 


Note: Only DWARF debugging information is supported with incremental linking. 
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3.44 The INTERNALRELOCS Option 

Formats: OS/2 

The "INTERNALRELOCS" option is used with LX format executables under 32-bit OS/2. By default, 
OS/2 executables do not contain internal relocation information and OS/2 Dynamic Link Libraries do 
contain internal relocation information. This option causes the Open Watcom Linker to include internal 
relocation information in OS/2 LX format executables. 

The format of the "INTERNALRELOCS" option (short form "INT") is as follows. 

OPTION INTERNALRELOCS 
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3.45 The LANGUAGE Directive 

Formats: All 

The "LANGUAGE" directive is used to specify the language in which strings in the Open Watcom Linker 

directives are specified. The format of the "LANGUAGE" directive (short form "LANG") is as follows. 

LANGUAGE lung 

lung ::= JAPANESE I CHINESE I KOREAN 

JAPANESE (short form "JA") specifies that strings are to be handled as if they contained characters 
from the Japanese Double-Byte Character Set (DBCS). 

CHINESE (short form "CH") specifies that strings are to be handled as if they contained characters 
from the Chinese Double-Byte Character Set (DBCS). 

KOREAN (short form "KO") specifies that strings are to be handled as if they contained characters 
from the Korean Double-Byte Character Set (DBCS). 


82 The LANGUAGE Directive 




LARGEADDRESSAWARE (Win32) 


3.46 The LARGEADDRESSAWARE Option 

Formats: Win32 

The "LARGEADDRESSAWARE" option specifies that the application can handle addresses larger than 2 
gigabytes. The linker set appropriate flag to the PE format image header. 

The format of the "LARGEADDRESSAWARE" option (short form "LARGE") is as follows. 

OPTION LARGEADDRESSA WARE 
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3.47 The LIBFILE Directive 

Formats: All 

The "LIBFILE" directive is used to specify the object files that the Open Watcom Linker is to process. The 
format of the "LIBFILE" directive (short form "LIBF") is as follows. 

LIBFILE obj_spec{,obj_spec} 
obj_spec ::= objJile I library_Jile 


description: 

is a file specification for the name of an object file. If no file extension is specified, a file 
extension of "obj" is assumed if you are running a DOS, OS/2 or Windows-hosted version 
of the Open Watcom Linker. Also, if you are running a DOS, OS/2 or Windows-hosted 
version of the Open Watcom Linker, the object file specification can contain wild cards (*, 
?). A file extension of "o" is assumed if you are running a UNIX-hosted version of the 
Open Watcom Linker. 

library_Jile is a file specification for the name of a library file. Note that the file extension of the 

library file (usually "lib") must be specified; otherwise an object file will be assumed. 
When a library file is specified, all object files in the library are included (whether required 
or not). 

The difference between the "LIBFILE" directive and the "FILE" directive is as follows. 

1. When searching for an object or library file specified in a "LIBFILE" directive, the current 
working directory will be searched first, followed by the paths specified in the "LIBPATH" 
directive, and finally the paths specified in the "LIB" environment variable. Note that if the 
object or library file name contains a path, only the specified path will be searched. 

2. Object or library file names specified in a "LIBFILE" directive will not be used to create the 
name of the executable file when no "NAME" directive is specified. 

Essentially, object files that appear in "LIBFILE" directives are viewed as components of a library that 
have not been explicitly placed in a library file. 

Consider the following linker directive file. 

libpath \libs 
libfile mystart 
path \objs 
file filel, file2 

The Open Watcom Linker is instructed to process the following object files: 

\libs\mystart.obj 

\objs\filel.obj 

\objs\file2.obj 

Note that the executable file will have file name "filel" and not "mystart". 


where 
obj _Jile 
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3.48 The LIBPATH Directive 

Formats: All 

The "LIBPATH" directive is used to specify the directories that are to be searched for library files 
appearing in subsequent "LIBRARY" directives and object files appearing in subsequent "LIBFILE" 
directives. The format of the "LIBPATH" directive (short form "LIBP") is as follows. 


LIBPATH [path_name{;path_name}] 


where description: 

pathj/iame is a path name. 

Consider a directive file containing the following linker directives. 

file test 
libpath \math 
library trig 
libfile newsin 

First, the Open Watcom Linker will process the object file "test.obj" from the current working directory. 
The object file "newsin.obj" will then be processed, searching the current working directory first. If 
"newsin.obj" is not in the current working directory, the "\math" directory will be searched. If any 
unresolved references remain after processing the object files, the library file "trig.lib" will be searched. If 
the file "trig.lib" does not exist in the current working directory, the "\math" directory will be searched. 

It is also possible to specify a list of paths in a "LIBPATH" directive. Consider the following example. 

libpath \newmath;\math 
library trig 

When processing undefined references, the Open Watcom Linker will attempt to process the library file 
"trig.lib" in the current working directory. If "trig.lib" does not exist in the current working directory, the 
"\newmath" directory will be searched. If "trig.lib" does not exist in the "\newmath" directory, the "\math" 
directory will be searched. 

If the name of a library file appearing in a "LIBRARY" directive or the name of an object file appearing in 
a "LIBFILE" directive contains a path specification, only the specified path will be searched. 

Note that 

libpath pathl 
libpath path2 

is equivalent to the following. 

libpath path2;pathl 
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3.49 The LIBRARY Directive 

Formats: All 

The "LIBRARY" directive is used to specify the library files to be searched when unresolved symbols 
remain after processing all specified input object files. The format of the "LIBRARY" directive (short form 
"L") is as follows. 


LIBRARY library_Jile{,library_file} 


where description: 

library_Jile is a file specification for the name of a library file. If no file extension is specified, a file 
extension of "lib" is assumed. 

Consider the following example. 

Example: 

wlink system my_ os file trig lib \math\trig, \cmplx\trig 
The Open Watcom Linker is instructed to process the following object file: 
trig.obj 

If any unresolved symbol references remain after all object files have been processed, the following library 
files will be searched: 

\math\trig.lib 
\cmplx\trig.lib 

More than one "LIBRARY" directive may be used. The following example is equivalent to the preceding 
one. 

Example: 

wlink system my_ os f trig lib \math\trig lib \cmplx\trig 
Thus other directives may be placed between lists of library files. 

3.49.1 Searching for Libraries Specified in Environment Variables 

The "LIB" environment variable can be used to specify a list of paths that will be searched for library files. 
The "LIB" environment variable can be set using the "set" command as follows: 

set lib=\graphics\lib;\utility 

Consider the following "LIBRARY" directive and the above definition of the "LIB" environment variable, 
library \mylibs\util, graph 

If undefined symbols remain after processing all object files specified in all "FILE" directives, the Open 
Watcom Linker will resolve these references by searching the following libraries in the specified order. 
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1. the library file "\mylibs\util.lib" 

2. the library file "graph.lib" in the current directory 

3. the library file "\graphics\lib\graph.lib" 

4. the library file "\utility\graph.lib" 

Notes: 

1. If a library file specified in a "LIBRARY" directive contains an absolute path specification, the 
Open Watcom Linker will not search any of the paths specified in the "LIB" environment string 
for the library file. Under QNX, an absolute path specification is one that begins the "/" 
character. Under all other operating systems, an absolute path specification is one that begins 
with a drive specification or the "\" character. 

2. Once a library file has been found, no further elements of the "LIB" environment variable are 
searched for other libraries of the same name. That is, if the library file "\graphics\lib\graph.lib" 
exists, the library file "\utility\graph.lib" will not be searched even though unresolved references 
may remain. 

3.49.2 Converting Libraries Created using Phar Lap 386ILIB 

Phar Lap’s librarian, 386ILIB, creates libraries whose dictionary is a different format from the one used by 
other librarians. For this reason, linking an application using the Open Watcom Linker with libraries 
created using 386ILIB will not work. Library files created using 386ILIB must be converted to the form 
recognized by the Open Watcom Linker. This is achieved by issuing the following WLIB command. 

wlib newlib +pharlib.lib 

The library file "pharlib.lib" is a library created using 386ILIB. The library file "newlib.lib" will be created 
so that the Open Watcom Linker can now process it. 
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3.50 The LINEARRELOCS Option 

Formats: QNX 

The "LINEARRELOCS" option instructs the linker to generate offset fixups in addition to the normal 
segment fixups. The offset fixups allow the system to move pieces of code and data that were loaded at a 
particular offset within a segment to another offset within the same segment. 

The format of the "LINEARRELOCS" option (short form "LI") is as follows. 


OPTION LINEARRELOCS 


88 The LINEARRELOCS Option 




LINKVERSION (Win32) 


3.51 The LINKVERSION Option 

Formats: Win32 

The "LINKVERSION" option specifies that the linker should apply the given major and minor version 
numbers to the PE format image header. If a version number is not specified, then the built-in value of 2.18 
is used. The format of the "LINKVERSION" option (shot! form "LINKV") is as follows. 

OPTION LINKVERSION = major[.minor] 
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LONGLIVED (QNX) 


3.52 The LONGLIVED Option 

Formats: QNX 

The "LONGLIVED" option specifies that the application being linked will reside in memory, or be active, 
for a long period of time (e.g., background tasks). The memory manager, knowing an application is 
"LONGLIVED", allocates memory for the application so as to reduce fragmentation. 

The format of the "LONGLIVED" option ( short form "LO") is as follows. 

OPTION LONGLIVED 
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MANGLEDNAMES 


3.53 The MANGLEDNAMES Option 

Formats: All 

The "MANGLEDNAMES" option should only be used if you are developing a Open Watcom C++ 
application. Due to the nature of C++, the Open Watcom C++ compiler generates mangled names for 
symbols. A mangled name for a symbol includes the following. 

1. symbol name 

2. scoping information 

3. typing information 

This information is stored in a cryptic form with the symbol. When the linker encounters a mangled name 
in an object file, it formats the above information and produces this name in the map file. 

If you would like the linker to produce the mangled name as it appeared in the object file, specify the 
"MANGLEDNAMES" option. 

The format of the "MANGLEDNAMES" option (short form "MANG") is as follows. 


OPTION MANGLEDNAMES 
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MANYAUTODATA (OS/2, Win16) 


3.54 The MANYAUTODATA Option 

Formats: OS/2, Win16 

The "MANYAUTODATA" option specifies that a copy of the automatic data segment (default data 
segment defined by the group "DGROUP"), for the program module or Dynamic Link Library (DLL) being 
created, is made for each instance. The format of the "MANYAUTODATA" option (short form "MANY") 
is as follows. 


OPTION MANYAUTODATA 


The default for a program module is "MANYAUTODATA" and for a Dynamic Link Library is 
"ONEAUTODATA". If you do not want the data area of a DLL to be shared across multiple applications, 
then you should specify "OPTION MANYAUTODATA". 

Winl6: Note, however, that this attribute is not supported by Windows 3.x for 16-bit DLLs. 

You should also see the related section entitled "The FORMAT Directive" on page 61 for information on 
the "INITINSTANCE", "TERMINSTANCE", "INITGLOBAL", and "TERMGLOBAL" DLL attributes. 
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MAP 


3.55 The MAP Option 

Formats: All 

The "MAP" option controls the generation of a map file. The format of the "MAP" option (short form "M") 
is as follows. 


OPTION MAP[=map Jile ] 


where description: 

map Jile is a file specification for the name of the map file. If no file extension is specified, a file 

extension of "map" is assumed. 

By default, no map file is generated. Specifying this option causes the Open Watcom Linker to generate a 
map file. The map file is simply a memory map of your program. That is, it specifies the relative location 
of all global symbols in your program. The map file also contains the size of your program. 

If no file name is specified, the map file will have a default file extension of "map" and the same file name 
as the executable file. Note that the map file will be created in the current directory even if the executable 
file name specified in the "NAME" directive contains a path specification. 

Alternatively, a file name can be specified. The following directive instructs the linker to generate a map 
file and call it "myprog.map" regardless of the name of the executable file. 

option map=myprog 

You can also specify a path and/or file extension when using the "MAP=" form of the "MAP" option. 
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MAXDATA (PharLap) 


3.56 The MAXDATA Option 

Formats: PharLap 

The format of the "MAXDATA" option (short form "MAXD") is as follows. 


OPTION MAXDATA=n 


where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

n specifies the maximum number of bytes, in addition to the memory required by executable image, that 
may be allocated by 386IDOS-Extender at the end of the loaded executable image. No more than n bytes 
will be allocated. 

If the "MAXDATA" option is not specified, a default value of hexadecimal ffffffff is assumed. This means 
that 386IDOS-Extender will allocate all available memory to the program at load time. 
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MAXERRORS 


3.57 The MAXERRORS Option 

Formats: All 

The "MAXERRORS" option can be used to set a limit on the number of error messages generated by the 
linker. Note that this does not include warning messages. When this limit is reached, the linker will issue a 
fatal error and terminate. 

The format of the "MAXERRORS" option (short form "MAXE") is as follows. 

OPTION MAXERRORS=n 

where description: 

n is the maximum number of error messages issued by the linker. 
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MESSAGES (NetWare) 


3.58 The MESSAGES Option 

Formats: NetWare 

The "MESSAGES" option specifies the file name of an internationalized message file that contains the 
default messages for the NLM. This is the name of the default message file to load for NLMs that are 
enabled. Enabling allows the same NLM to display messages in different languages by switching message 
files. 

The format of the "MESSAGES" option (short form "MES") is as follows. 



where description: 

msgjile is the name of the message file. 
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MINDATA (PharLap) 


3.59 The MINDATA Option 

Formats: PharLap 

The format of the "MINDATA" option (short form "MIND") is as follows. 


OPTION MINDATA=n 


where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

n specifies the minimum number of bytes, in addition to the memory required by executable image, that 
must be allocated by 386IDOS-Extender at the end of the loaded executable image. If n bytes are not 
available, the program will not be executed. 

If the "MINDATA" option is not specified, a default value of zero is assumed. This means that 
386IDOS-Extender will load the program as long as there is enough memory for the load image; no extra 
memory is required. 


The MINDATA Option 
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MIXED1632 (OS/2) 


3.60 The MIXED1632 Option 

Formats: OS/2 

The "MIXED1632" option specifies that 16-bit and 32-bit logical segments may be grouped into a single 
physical segment. This applies to both code and data segments. 

The format of the "MIXED1632" option ( short form "MIX") is as follows. 

OPTION MIXED 1632 

This option is useful certain specialized applications, such as OS/2 physical device drivers. In most cases, 
mixing of 16-bit and 32-bit segments should be avoided. 
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MODNAME (OS/2, Win16, Win32) 


3.61 The MODNAME Option 

Formats: OS/2, Win16, Win32 

The "MODNAME" option specifies a name to be given to the module being created. The format of the 
"MODNAME" option (short form "MODN") is as follows. 


OPTION MODNAME=module_name 


where description: 

module jiame is the name of a Dynamic Link Library. 

Once a module has been loaded (whether it be a program module or a Dynamic Link Library), mod_name 
is the name of the module known to the operating system. If the "MODNAME" option is not used to 
specify a module name, the default module name is the name of the executable file without the file 
extension. 
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MODFILE 


3.62 The MODFILE Directive 

Formats: All 

The "MODFILE" directive instructs the linker that only the specified object files have changed. The format 
of the "MODFILE" directive (short form "MODF") is as follows. 


MODFILE objJile{,objJile} 


where description: 

objjile is a file specification for the name of an object file. If no file extension is specified, a file 

extension of "obj" is assumed if you are running a DOS, OS/2 or Windows-hosted version 
of the Open Watcom Linker. Also, if you are running a DOS, OS/2 or Windows-hosted 
version of the Open Watcom Linker, the object file specification can contain wild cards (*, 
?). A file extension of "o" is assumed if you are running a UNIX-hosted version of the 
Open Watcom Linker. 

This directive is used only in concert with incremental linking. This directive tells the linker that only the 
specified object files have changed. When this option is specified, the linker will not check the dates on 
any of the object files or libraries when incrementally linking. 


100 The MODFILE Directive 







MODTRACE 


3.63 The MODTRACE Directive 

Formats: All 

The "MODTRACE" directive instructs the Open Watcom Linker to print a list of all modules that reference 
the symbols defined in the specified modules. The format of the "MODTRACE" directive (short form 
"MODT") is as follows. 

MODTRACE module_name{,modulejiame} 

where description: 

module_name is the name of an object module defined in an object or library file. 

The information is displayed in the map file. Consider the following example. 

Example: 

wlink system my_ os op map file test lib math modt trig 

If the module "trig" defines the symbols "sin" and "cos", the Open Watcom Linker will list, in the map file, 
all modules that reference the symbols "sin" and "cos". 
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MODULE (ELF, NetWare) 


3.64 The MODULE Directive 

Formats: ELF, NetWare 

The "MODULE" directive is used to specify the DLLs or NLMs to be loaded before this executable is 
loaded. The format of the "MODULE" directive (short form "MODU") is as follows. 

MODULE module_name{,module_name} 

where description: 

module jiame is the file name of a DLL or NLM. 

WARNING! Versions 3.0 and 3.1 of the NetWare operating system do not support the automatic 
loading of modules specified in the "MODULE" directive. You must load them manually. 
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MULTILOAD (NetWare) 


3.65 The MULTILOAD Option 

Formats: NetWare 

The "MULTILOAD" option specifies that the module can be loaded more than once by a "load" command. 
The format of the "MULTILOAD" option (short form "MULTIL") is as follows. 


OPTION MULTILOAD 


If the "MULTILOAD" option is not specified, it will not be possible to load the module more than once 
using the "load" command. 
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NAME 


3.66 The NAME Directive 

Formats: All 


The "NAME" directive is used to provide a name for the executable file generated by the Open Watcom 
Linker. The format of the "NAME" directive (short form "N") is as follows. 



where description: 

exe_Jile is a file specification for the name of the executable file. Under UNIX, or if the 

"NOEXTENSION" option was specified, no file extension is appended. In all other cases, 
a file extension suitable for the current executable file format is appended if no file 
extension is specified. 

Consider the following example. 

Example: 

wlink system my_ os name myprog file test, test2, test3 

The linker is instructed to generate an executable file called "myprog.exe" if you are running a DOS, OS/2 

or Windows-hosted version of the linker. If you are running a UNIX-hosted version of the linker, or the 

"NOEXTENSION" option was specified, an executable file called "myprog" will be generated. 

Notes: 

1. No file extension was given when the executable file name was specified. The linker assumes a 
file extension that depends on the format of the executable file being generated. If you are 
running a UNIX-hosted version of the linker, or the "NOEXTENSION" option was specified, no 
file extension will be assumed. The section entitled "The FORMAT Directive" on page 61 
describes the "FORMAT" directive and how the file extension is chosen for each executable file 
format. 

2. If no "NAME" directive is present, the executable file will have the file name of the first object 
file processed by the linker. If the first object file processed is called "test.obj" and no "NAME" 
directive is specified, an executable file called "test.exe" will be generated if you are running a 
DOS or OS/2-hosted version of the linker. If you are running a UNIX-hosted version of the 
linker, or the "NOEXTENSION" option was used, an executable file called "test" will be 
generated. 
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NAMELEN 


3.67 The NAMELEN Option 

Formats: All 

The "NAMELEN" option tells the Open Watcom Linker that all symbols must be uniquely identified in the 
number of characters specified or less. If any symbol fails to satisfy this condition, a warning message will 
be issued. The warning message will state that a symbol has been defined more than once. 

The format of the "NAMELEN" option (short form "NAMEL") is as follows. 


OPTION NAMELEN=n 


where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

Some computer systems, for example, require that all global symbols be uniquely identified in 8 characters. 
By specifying an appropriate value for the "NAMELEN" option, you can ease the task of porting your 
application to other computer systems. 
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NEWFILES (OS/2) 


3.68 The NEWFILES Option 

Formats: OS/2 

The "NEWFILES" option specifies that the application uses the high-performance file system. This option 
is applicable to 16-bit OS/2 applications only. The format of the "NEWFILES" option (short form 
"NEWF") is as follows. 


OPTION NEWFILES 
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NEWSEGMENT (DOS, OS/2, QNX, Win 16) 


3.69 The NEWSEGMENT Directive 

Formats: DOS, OS/2, QNX, Win 16 

This directive is intended for 16-bit segmented applications. By default, the Open Watcom Linker 
automatically groups logical code segments into physical segments. By default, these segments are 64K 
bytes in size. However, the "PACKCODE" option can be used to specify a maximum size for all physical 
segments that is smaller than 64K bytes. 

The "NEWSEGMENT" directive provides an alternate method of grouping code segments into physical 
segments. By placing this directive after a sequence of "FILE" directives, all code segments appearing in 
object modules specified by the sequence of "FILE" directives will be packed into a physical segment. 
Note that the size of a physical segment may vary in size. The format of the "NEWSEGMENT" directive 
(short form "NEW") is as follows. 


NEWSEGMENT 


Consider the following example. 

file filel, file2, file3 

newsegment 

file file4 

file file5 

Code segments immfile I, file2 and fileJ will be grouped into one physical segment. Code segments from 
filt’4 and file5 will be grouped into another physical segment. 

Note that code segments extracted from library files will be grouped into physical segments as well. The 
size of these physical segments is determined by the "PACKCODE" option and is 64k by default. 
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NLMFLAGS (NetWare) 


3.70 The NLMFLAGS Option 

Formats: NetWare 

The "NLMFLAGS" option is used to set bits in the flags field of the header of the Netware executable file. 
The format of the "NLMFLAGS" option (short form "NLMF") is as follows. 

OPTION NLMFLAGS=some_value 

where description: 

some_value is an integer value that is OR’ed into the flags field of the header of the Netware 
executable. 
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NOAUTODATA (OS/2, Win16) 


3.71 The NOAUTODATA Option 

Formats: OS/2, Win16 

The "NOAUTODATA" option specifies that no automatic data segment (default data segment defined by 
the group "DGROUP"), exists for the program module or Dynamic Link Library being created. This option 
applies to 16-bit applications only. The format of the "NOAUTODATA" option (short form "NOA") is as 
follows. 
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NODEFAULTUBS 


3.72 The NODEFAULTUBS Option 

Formats: All 

Special object module records that specify default libraries are placed in object files generated by Open 
Watcom compilers. These libraries reflect the memory and floating-point model that a source file was 
compiled for and are automatically searched by the Open Watcom Linker when unresolved symbols are 
detected. These libraries can exist in the current directory, in one of the paths specified in "LIBPATH" 
directives, or in one of the paths specified in the LIB environment variable. 

Note that all library files that appear in a "LIBRARY" directive are searched before default libraries. The 
"NODEFAULTLIBS" option instructs the Open Watcom Linker to ignore default libraries. That is, only 
libraries appearing in a "LIBRARY" directive are searched. 

The format of the "NODEFAULTLIBS" option (short form "NOD") is as follows. 

OPTION NODEFA ULTLIBS 
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NOEXTENSION 


3.73 The NOEXTENSION Option 

Formats: All 

The "NOEXTENSION" option suppresses automatic addition of an extension to the name of the executable 
file generated by Open Watcom Linker. This affects both names specified explicitly through the "NAME" 
directive as well as default names chosen in the absence of a "NAME" directive. 

The format of the "NOEXTENSION" option (short form "NOEXT") is as follows. 

OPTION NOEXTENSION 


The NOEXTENSION Option 111 







NOINDIRECT (DOS) 


3.74 The NOINDIRECT Option 

Formats: DOS 

The "NOINDIRECT" option suppresses the generation of overlay vectors for symbols that are referenced 
indirectly (their address is taken) when the module containing the symbol is not an ancestor of at least one 
module that indirectly references the symbol. This can greatly reduce the number of overlay vectors and is 
a safe optimization provided there are no indirect calls to these symbols. If, for example, the set of symbols 
that are called indirectly is known, you can use the "VECTOR" option to force overlay vectors for these 
symbols. 

The format of the "NOINDIRECT" option (short form "NOI") is as follows. 



For more information on overlays, see the section entitled "Using Overlays" on page 186. 
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NORELOCS (ONX, Win32) 


3.75 The NORELOCS Option 

Formats: QNX, Win32 

The "NORELOCS" option specifies that no relocation information is to be written to the executable file. 
When the "NORELOCS" option is specified, the executable file can only be run in protected mode and will 
not run in real mode. In real mode, the relocation information is required; in protected mode, the relocation 
information is not required unless your application is running at privilege level 0. 

The format of the "NORELOCS" option (short form "NOR") is as follows. 

OPTION NORELOCS 

where description: 

NORELOCS tells the Open Watcom Linker not to generate relocation information. 
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NOSTDCALL (Win32) 


3.76 The NOSTDCALL Option 

Formats: Win32 

The "NOSTDCALL" option specifies that the characters unique to the_ stdcall calling convention be 

trimmed from all of the symbols that are exported from the DLL being created. The format of the 
"NOSTDCALL" option (short form "NOSTDC") is as follows. 


OPTION NOSTDCALL 


Considering the following declarations. 

Example: 

short PASCAL _export Functionl( short varl, 

long varlong, 
short var2 ); 

short PASCAL _ export Function2( long varlong, 

short var2 ); 

Under ordinary circumstances, these_ stdcall symbols are mapped to "_Functionl @ 12" and 

"_Function2@8" respectively. The "@12" and "@8" reflect the number of bytes in the argument list (short 
is passed as int). When the "NOSTDCALL" option is specified, these symbols are stripped of the and 
"@xx" adornments. Thus they are exported from the DLL as "Functionl" and "Function2". 

This option makes it easier to access functions exported from DLLs, especially when using other software 
languages such as FORTRAN which do not add on the_ stdcall adornments. 


Note: Use the "IMPLIB" option to create an import library for the DLL which can be used with 
software languages that add on the_ stdcall adornments. 
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NOSTUB (OS/2, Win 16, Win32) 


3.77 The NOSTUB Option 

Formats: OS/2, Win16, Win32 

The "NOSTUB" option specifies that no "stub" program is to be placed at the beginning of the executable 
file being generated. The format of the "NOSTUB" option is as follows. 


OPTION NOSTUB 


This option is helpful in cases when the executable file being generated cannot be directly executed by the 
user, such as a device driver, and hence the stub program would be redundant. 
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NO VECTOR (DOS) 


3.78 The NOVECTOR Directive 

Formats: DOS 

The "NOVECTOR" directive forces the Open Watcom Linker to not generate an overlay vector for the 
specified symbols. The format of the "NOVECTOR" directive ( short form "NOV") is as follows. 


NOVECTOR symbol_name{,symbol_name} 


where description: 

symboljiame is a symbol name. 

The linker will create an overlay vector in the following cases. 

1. If a function in section A calls a function in section B and section B is not an ancestor of section 
A, an overlay vector will be generated for the function in section B. See the section entitled 
"Using Overlays" on page 186 for a description of ancestor. 

2. If a global symbol's address is referenced (except by a direct call) and that symbol is defined in 
an overlay section, an overlay vector for that symbol will be generated. 

Note that in the latter case, more overlay vectors may be generated that necessary. Suppose section A 
contains three global functions, / g and h. Function/passes the address of function g to function h who 
can then calls function g indirectly. Also, suppose function g is only called from sections that are ancestors 
of section A. The linker will generate an overlay vector for function g even though none is required. In 
such a case, the "NOVECTOR" directive can be used to remove the overhead associated with calling a 
function through an overlay vector. 
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OBJ ALIGN (ELF, Win32) 


3.79 The OBJALIGN Option 

Formats: ELF, Win32 

The "OBJALIGN" option specifies the alignment for objects in the executable file. The format of the 
"OBJALIGN" option (short form "OBJA") is as follows. 


OPTION OBJALIGN=n 


where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

n must be a value that is a power of 2 and is between 16 bytes and 256 megabytes 
inclusive. The default is 64k. 
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OLDLIBRARY (OS/2, Win16, Win32) 


3.80 The OLDLIBRARY Option 

Formats: OS/2, Win16, Win32 

The "OLDLIBRARY" option is used to preserve the export ordinals for successive versions of a Dynamic 
Link Library. This ensures that any application that references functions in a Dynamic Link Library by 
ordinal will continue to execute correctly. The format of the "OLDLIBRARY" option (short form "OLD") 
is as follows. 


OPTION OLDLIBRAR Y=dll_name 


where description: 

dlljiame is a file specification for the name of a Dynamic Link Library. If no file extension is 
specified, a file extension of "DLL" is assumed. 

Only the current directory or a specified directory will be searched for Dynamic Link Libraries specified in 
the "OLDLIBRARY" option. 
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OFFSET (RAW, ELF, OS/2, PharLap, QNX, Win32) 


3.81 The OFFSET Option 

Formats: RAW, ELF, OS/2, PharLap, QNX, Win32 

For 32-bit RAW applications, the "OFFSET" option specifies the linear base address of the raw output 
image. 

For OS/2, Win32 and ELF applications, the "OFFSET" option specifies the preferred base linear address at 
which the executable or DLL will be loaded. 

For 32-bit PharLap and QNX applications, the "OFFSET" option specifies the offset in the program’s 
segment in which the first byte of code or data is loaded. 

3.81.1 OFFSET-RAW only 

The "OFFSET" option specifies the linear base address of the raw output image. The format of the 
"OFFSET" option (short form "OFF") is as follows. 


OPTION OFFSET=n 


where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

n specifies the offset at which the output image will be located. The following describes a use of the 
"OFFSET" option. 

Example: 

option offset=0xc0000000 

The image will be virtually/physically located to the linear address OxcOOOOOOO. 

3.81.2 OFFSET - OS/2, Win32, ELF only 

The "OFFSET" option specifies the preferred base linear address at which the executable or DLL will be 
loaded. The Open Watcom Linker will relocate the application for the specified base linear address so that 
when it is loaded by the operating system, no relocation will be required. This decreases the load time of 
the application. 

If the operating system is unable to load the application at the specified base linear address, it will load it at 
a different location which will increase the load time since a relocation phase must be performed. 

The format of the "OFFSET" option (short form "OFF") is as follows. 
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OFFSET (RAW, ELF, OS/2, PharLap, QNX, Win32) 


OPTION OFFSET=n 


where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

The "OFFSET" option is used to specify the base linear address (in bytes) at which the program is loaded 
and must be a multiple of 64K. The linker will round the value up to a multiple of 64K if it is not already a 
multiple of 64K. The default base linear address is 64K for OS/2 executables and 4096K for Win32 
executables. For ELF, the default base address depends on the CPU architecture. 

This option is most useful for improving the load time of DLLs, especially for an application that uses 
multiple DLLs. 

3.81.3 OFFSET - PharLap only 

The "OFFSET" option specifies the offset in the program’s segment in which the first byte of code or data 
is loaded. The format of the "OFFSET" option (short form "OFF") is as follows. 


OPTION OFFSET=n 


where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

n specifies the offset (in bytes) at which the program is loaded and must be a multiple of 4K. The Open 
Watcom Linker will round the value up to a multiple of 4K if it is not already a multiple of 4K. 

It is possible to detect NULL pointer references by linking the program at an offset which is a multiple of 
4K. Usually an offset of 4K is sufficient. 
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OFFSET (RAW, ELF, OS/2, PharLap, QNX, Win32) 


Example: 

option offset=4k 

When the program is loaded by 386IDOS-Extender, the pages skipped by the "OFFSET" option are not 
mapped. Any reference to an unmapped area (such as a NUFL pointer) will cause a page fault preventing 
the NUFF reference from corrupting the program. 

3.81.4 OFFSET-QNX only 

The "OFFSET" option specifies the offset in the program’s segment in which the first byte of code or data 
is loaded. This option does not apply to 16-bit QNX applications. The format of the "OFFSET" option 
(short form "OFF") is as follows. 


OPTION OFFSET=n 


where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

n specifies the offset (in bytes) at which the program is loaded and must be a multiple of 4K. The Open 
Watcom Linker will round the value up to a multiple of 4K if it is not already a multiple of 4K. The 
following describes a use of the "OFFSET" option. 

It is possible to detect NULL pointer references by linking the program at an offset which is a multiple of 
4K. Usually an offset of 4K is sufficient. 

Example: 

option offset=4k 

When the program is loaded, the pages skipped by the "OFFSET" option are not mapped. Any reference to 
an unmapped area (such as a NULL pointer) will cause a page fault preventing the NULL reference from 
corrupting the program. 
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3.82 The ONEAUTODATA Option 

Formats: OS/2, Win16 

The "ONEAUTODATA" option specifies that the automatic data segment (default data segment defined by 
the group "DGROUP"), for the program module or Dynamic Link Library (DLL) being created, will be 
shared by all instances. The format of the "ONEAUTODATA" option (short form "ONE") is as follows. 


OPTION ONEAUTODATA 


The default for a Dynamic Link Library is "ONEAUTODATA" and for a program module is 
"MANYAUTODATA". If you do not want the data area of a DLL to be shared across multiple 
applications, then you should specify "OPTION MANYAUTODATA". 

Winl6: Note, however, that this attribute is not supported by Windows 3.x for 16-bit DLLs. 

You should also see the related section entitled "The LORMAT Directive" on page 61 for information on 
the "INITINSTANCE", "TERMINSTANCE", "INITGLOBAL", and "TERMGLOBAL" DLL attributes. 
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3.83 The OPTION Directive 

Formats: All 

The "OPTION" directive is used to specify options to the Open Watcom Linker. The format of the 
"OPTION" directive (shot! form "OP") is as follows. 

OPTION option),optionj 

where description: 

option is any of the linker options available for the executable format that is being generated. 
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3.84 The OPTLIB Directive 

Formats: All 

The "OPTLIB" directive is used to specify the library files to be searched when unresolved symbols remain 
after processing all specified input object files. The format of the "OPTLIB" directive (no short form) is as 
follows. 


OPTLIB library_Jile{,library_file} 


where description: 

library_Jile is a file specification for the name of a library file. If no file extension is specified, a file 

extension of "lib" is assumed. 

This directive is similar to the "LIBRARY" directive except that the linker will not issue a warning 
message if the library file cannot be found. 

Consider the following example. 

Example: 

wlink system my_ os file trig optlib \math\trig, \cmplx\trig 
The Open Watcom Linker is instructed to process the following object file: 
trig.obj 

If any unresolved symbol references remain after all object files have been processed, the following library 
files will be searched: 

\math\trig.lib 
\cmplx\trig.lib 

More than one "OPTLIB" directive may be used. The following example is equivalent to the preceding 
one. 

Example: 

wlink system my_ os f trig optlib \math\trig optlib \cmplx\trig 
Thus other directives may be placed between lists of library files. 

3.84.1 Searching for Optional Libraries Specified in Environment Variables 

The "LIB" environment variable can be used to specify a list of paths that will be searched for library files. 
The "LIB" environment variable can be set using the "set" command as follows: 

set lib=\graphics\lib;\utility 

Consider the following "OPTLIB" directive and the above definition of the "LIB" environment variable, 
optlib \mylibs\util, graph 
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If undefined symbols remain after processing all object files specified in all "FILE" directives, the Open 
Watcom Linker will resolve these references by searching the following libraries in the specified order. 

1. the library file "\mylibs\util.lib" 

2. the library file "graph.lib" in the current directory 

3. the library file "\graphics\lib\graph.lib" 

4. the library file "\utility\graph.lib" 

Notes: 

1. If a library file specified in a "OPTLIB" directive contains an absolute path specification, the 
Open Watcom Linker will not search any of the paths specified in the "LIB" environment string 
for the library file. On UNIX platforms, an absolute path specification is one that begins the "/" 
character. On all other hosts, an absolute path specification is one that begins with a drive 
specification or the "\" character. 

2. Once a library file has been found, no further elements of the "LIB" environment variable are 
searched for other libraries of the same name. That is, if the library file "\graphics\lib\graph.lib" 
exists, the library file "\utility\graph.lib" will not be searched even though unresolved references 
may remain. 


The OPTLIB Directive 125 




ORDER 


3.85 The ORDER Directive 

Formats: All 

The "ORDER" directive is used to specify the order in which classes are placed into the output image, and 
the order in which segments are linked within a class. The directive can optionally also specify the starting 
address of a class or segment, control whether the segment appears in the output image, and facilitate 
copying of data from one segment to another. The "ORDER" Directive is primarily intended for embedded 
(ROMable) targets that do not run under an operating system, or for other special purpose applications. 

The format of the "ORDER" directive ( short form "ORD") is as follows. 


ORDER {CLNAME class_name [class_options]}+ 

c las soptions ::= [SEGADDR=n][OFFSET=n][copy_option][NOEMIT][seglist} 
copy_option ::= [COPY source_class_name] 

seglist := [SEGMENT segjiame [SEGADDR=n][OFFSET=n][NOEMIT]}+ 


where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

class_name is the name of a class defined in one or more object files. If the class is not defined in an 
object file, the class_name and all associated options are ignored. Note that the "ORDER" 
directive does not create classes or segments. Classes specified with "CLNAME" 
keywords will be placed in the output image in the order listed. Any classes that are not 
listed will be placed after the listed ones. 

SEGADDR=n (short form "SEGA") specifies the segment portion of the starting address of the class or 
segment in the output image. It is combined with "OFFSET" to represent a unique linear 
address. "SEGADDR" is only valid for segmented formats. Its use in other contexts is 
undefined. The "HSHIFT" value affects how the segment value is converted to a linear 
address. 

OFFSET=n (short form "OFF") specifies the offset portion of the starting address of the class or 

segment in the output image. It is combined with "SEGADDR" to represent a unique linear 
address. Offset is limited to a range of 0 to 65535 in segmented architectures, but can be a 
larger value for non-segmented architectures, up to the limits of the architecture. 

When "SEGADDR" and/or "OFFSET" are specified, the location counter used to generate 
the executable is advanced to that address. Any gaps are filled with the "FILLCHAR" 
value, except for HEX output format, in which case they are simply skipped. If the location 
counter is already beyond the specified location, an error message is generated. This would 
likely be the result of having specified classes or segments in incorrect order, or not 
providing enough room for preceding ones. Without the "SEGADDR" and "OFFSET" 
options, classes and segments are placed in the executable consecutively, possibly with a 
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small gap in between if required by the alignment specified for the class. If "SEGADDR" 
is specified without corresponding "OFFSET", the offset portion of the address defaults to 
0 . 

COPY (short form "CO") indicates that the data from the segment named source_class_name is to 

be used in this segment. 

NOEMIT (short form "NOE") indicates that the data in this segment should not be placed in the 
executable. 

SEGMENT indicates the order of segments within a class, and possibly other options associated with 
that segment. Segments listed are placed in the executable in the order listed. They must 
be part of the class just named. Any segments in that class not listed will follow the last 
listed segment. The segment options are a subset of the class options and conform to the 
same specifications. 

In ROM-based applications it is often necessary to: 

• Fix the program location 

• Separate code and data to different fixed parts of memory 

• Place a copy of initialized data in ROM (usually right after the code) 

• Prevent the original of the initialized data from being written to the loadfile, since it resides in RAM 
and cannot be saved there. 

The "ORDER" directive caters for these requirements. Classes can be placed in the executable in a specific 
order, with absolute addresses specified for one or more classes, and segments within a class can be forced 
into a specified order with absolute addresses specified for one or more of them. Initialized data can be 
omitted at its target address, and a copy included at a different address. 

Following is a sample "ORDER" directive for an embedded target (AM186ER). The bottom 32K of 
memory is RAM for data. A DGROUP starting address of 0x80:0 is required. The upper portion of 
memory is FLASH ROM. Code starts at address 0xD000:0. The initialized data from DGROUP is placed 
immediately after the code. 

order clname BEGDATA NOEMIT segaddr=0x80 segment _ NULL segment 
_ AFTERNULL 

clname DATA NOEMIT segment _ DATA 
clname BSS 
clname STACK 

clname START segaddr=0xD000 

clname CODE segment BEGTEXT segment _ TEXT 
clname ROMDATA COPY BEGDATA 
clname ROMDATAE 

DGROUP consists of classes "BEGDATA", "DATA", "BSS", "BSS2" and "STACK". Note that these are 
marked "NOEMIT" (except for the BSS classes and STACK which are not initialized, and therefore have 
no data in them anyway) to prevent data from being placed in the loadfile at 0x80:0. The first class of 
DGROUP is given the fixed starting segment address of 0x80 (offset is assumed to be 0). The segments 
"_NULL", "_AFTERNULL" and "_DATA" will be allocated consecutively in that order, and because they 
are part of DGROUP, will all share the same segment portio of the address, with offsets adjusted 
accordingly. 
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The code section consists of classes "START" and "CODE". These are placed beginning at 0xD000:0. 
"START" contains only one segment, which will be first. It will have a CS value of OxDOOO. Code has 
two segments, "BEGTEXT" and "_TEXT" which will be placed after "START", in that order, and packed 
into a single CS value of their own (perhaps OxDOOl in this example), unless they exceed 64K in size, 
which should not be the case if the program was compiled using the small memory model. 

The classes "ROMDATA" and "ROMDATAE" were created in assembly with one segment each and no 
symbols or data in them. The class names can be used to identify the beginning and end of initialized data 
so it can be copied to RAM by the startup code. 

The "COPY" option actually works at the group level, because that is the way it is generally needed. The 
entire data is in DGROUP. "ROMDATA" will be placed in a group of its own called "AUTO". (Note: 
each group mentioned in the map file under the name "AUTO" is a separate group. They are not combined 
or otherwise related in any way, other than they weren't explicitly created by the programmer, compiler or 
assembler, but rather automatically created by the linker in the course of its work.) Therefore there is a 
unique group associated with this class. The "COPY" option finds the group associated with "BEGDATA" 
and copies all the object data from there to "ROMDATA". Specifically, it places a copy of this data in the 
executable at the location assigned to "ROMDATA", and adjusts the length of "ROMDATA" to account for 
this. All symbol references to this data are to its execution address (0x80:0), not where it ended up in the 
executable (for instance 0xD597:0). The starting address of "ROMDATAE" is also adjusted to account for 
the data assigned to "ROMDATA". That way, the program can use the symbol "ROMDATAE" to identify 
the end of the copy of DGROUP. It is also necessary in case more than one "COPY" class exists 
consecutively, or additional code or data need to follow it. 

It should also be noted that the "DOSSEG" option (whether explicitly given to the linker, or passed in an 
object file) performs different class and segment ordering. If the "ORDER" directive is used, it overrides 
the "DOSSEG" option, causing it to be ignored. 
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3.86 The OSDOMAIN Option 

Formats: NetWare 

The "OSDOMAIN" option is used when the application is to run in the operating system domain (ring 0). 
The format of the "OSDOMAIN" option (short form "OSD") is as follows. 

OPTION OSDOMAIN 
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3.87 The OSNAME Option 

Formats: All 

The "OSNAME" option can be used to set the name of the target operating system of the executable file 
generated by the linker. The format of the "OSNAME" option (short form "OSN") is as follows. 


OPTION OSNAME=’string’ 


where description: 

string is any sequence of characters. 

The information specified by the "OSNAME" option will be displayed in the creating a ? executable 
message. This is the last line of output produced by the linker, provided the "QUIET" option is not 
specified. Consider the following example. 

option osname='SuperOS' 

The last line of output produced by the linker will be as follows. 

creating a SuperOS executable 

Some executable formats have a stub executable file that is run under 16-bit DOS. The message displayed 
by the default stub executable file will be modified when the "OSNAME" option is used. The default stub 
executable displays the following message: 


OS/2: 

this 

is 

an OS/2 executable 

Winl6: 

this 

is 

a Windows 

executable 

Win32: 

this 

is 

a Windows 

NT executable 


If the "OSNAME" option used in the previous example was specified, the default stub executable would 
generate the following message. 

this is a SuperOS executable 
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3.88 The OSVERSION Option 

Formats: Win32 

The "OSVERSION" option specifies that the linker should apply the given major and minor version 
numbers to the PE format image header. This specifies the major and minor versions of the operating 
system required to load this image. If a version number is not specified, then the built-in value of 1.11 is 
used. The format of the "OSVERSION" option (short form "OSV") is as follows. 


OPTION OSVERSION = major[.minor] 
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3.89 The OUTPUT Directive 

Formats: All 

The "OUTPUT" directive overrides the normal operating system specific executable format and creates 
either a raw binary image or an Intel Hex file. The format of the "OUTPUT" directive ( short form "OUT") 
is as follows. 


OUTPUT RAW\HEX [OFFSET=n ][HSHIFT=n][STARTREC] 

where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

RAW specifies the output file to be a raw binary and will contain an absolute image of the 

executable’s code and data. Default file extension is "bin". 

HEX specifies the output file to contain a representation of the absolute image of the code and 

data using the Intel standard hex file format. Default file extension is "hex". 

OFFSET=n (short form "OFF") specifies that linear addresses below n should be skipped when 

outputting the executable image. This option does not affect address calculations and is 
intended to avoid unwanted padding when writing executable images that do not start at 
linear address zero. 

HSHIFT defines the relationship between segment values for type 02 records and linear addresses. 

The value n is the number of digits to right shift a 32-bit value containing a segment 
address in its upper 16 bits in order to convert it to part of a linear address. In more 
conventional terms, (16 - n ) is the amount to shift a segment value left in order to convert 
it to part of a linear address. 

STARTREC (short form "ST") specifies that a Starting Address record will be included in Intel Hex 
output. This option is ignored if output type is not Intel hex. 

For raw binary files, the position in the file is the linear address after the offset is subtracted from it. Any 
gaps filled with the value specified through "OPTION FILLCHAR" (default is 0). 

For hex files, the linear address (after subtracting the offset) is used to determine the output record 
generated. Records contain 16 bytes, unless a gap occurs prior to that in which case the record is shorter, 
and a new record starts after the gap. There are three types of Intel Hex records. The oldest and most 
widely used is HEX80, which can only deal with 16-bit addresses. For many ROM-based applications, this 
is enough, especially once an offset has been subtracted. For maximum versatility, all addresses less than 
65536 are generated in this form. 
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The HEX86 standard creates a segmentation that mirrors the CPU segmentation. Type 02 records define 
the segment, and all subsequent addresses are based on that segment value. For addresses above 64K, This 
form is used. A program that understands HEX86 should assume the segment value is zero until an 02 
record is encountered. This preserves backward compatibility with HEX80, and allows the automatic 
selection algorithm used in Open Watcom Linker to work properly. 

Type 02 records are assumed to have segment values that, when shifted left four bits, form a linear address. 
However, this is not suitable for 24-bit segmented addressing schemes. Therefore, Open Watcom Linker 
uses the value specified through "OPTION HSHIFT" to determine the relationship between segments and 
offsets. This approach can work with any 16:16 segmented architecture regardless of the segment 
alignment. The default shift value is 12, representing the conventional 8086 architecture. This is not to be 
confused with the optional "OUTPUT HSHIFT" value discussed below. 

Of course, PROM programmers or third-party tools probably were not designed to work with 
unconventional shift values, hence for cases where code for a 24-bit (or other non-standard) target needs to 
be programmed into a PROM or processed by a third-party tool, the "OUTPUT HSHIFT" option can be 
used to override the "OPTION HSHIFT" value. This would usually be of the form "OUTPUT 
HSHIFT=12" to restore the industry standard setting. The default for "OUTPUT HSHIFT" is to follow 
"OPTION HSHIFT". When neither is specified, the default "OPTION HSHIFT" value of 12 applies, 
providing industry standard compliance. 

If the address exceeds the range of type 02 records (1 MB for HSHIFT=12 and 16 MB for HSHIFT=8), 
type 04 extended linear records are generated, again ensuring seamless compatibility and migration to large 
file sizes. 

If "STARTREC" is specified for "OUTPUT HEX", the penultimate record in the file (just before the end 
record) will be a start address record. The value of the start address will be determined by the module start 
record in an object file, typically the result of an "END start" assembler directive. If the start address is less 
than 65536 (always for 16-bit applications, and where applicable for 32-bit applications), a type 03 record 
with segment and offset values will be emitted. If the start address is equal to or greater than 65536, then a 
type 05 linear starting address record will be generated. Note that neither of these cases depends directly 
on the "HSHIFT" or "OUTPUT HSIFT" settings. If HSHIFT=8, then the segment and offset values for the 
start symbol will be based on that number and used accordingly, but unlike other address information in a 
hex file, this is not derived from a linear address and hence not converted based on the HSHIFT value. 
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3.90 The OVERLAY Directive 

Formats: DOS 

The "OVERLAY" directive allows you to specify the class of segments which are to be overlayed. The 
format of the "OVERLAY" directive (short form "OV") is as follows. 


OVERLAY class{, class} 


where description: 

class is the class name of the segments to be overlayed. 

The "FILE" directive is used to specify the object files that belong to the overlay structure. Each object file 
defines segments that contain code or data. Segments are assigned a class name by the compiler. A class is 
essentially a collection of segments with common attributes. For example, compilers assign class names to 
segments so that segments containing code belong to one class(es) and segments containing data belong to 
another class(es). When an overlay structure is defined, only segments belonging to certain classes are 
allowed in the overlay structure. By default, the Open Watcom Linker overlays all segments whose class 
name ends with "CODE". These segments usually contain the executable code for a program. 

It is also possible to overlay other classes. This is done using the "OVERLAY" directive. For example, 

overlay code, far_ data 

places all segments belonging to the classes "CODE" and "FAR_DATA" in the overlay structure. 

Segments belonging to the class "FAR_DATA" contain only data. The above "OVERLAY" directive 
causes code and data to be overlayed. Therefore, for any module that contains segments in both classes, 
data in segments with class "FAR_DATA" will be in memory only when code in segments with class 
"CODE" are in memory. This results in a more efficient use of memory. Of course the data must be 
referenced only by code in the overlay and it must not be modified. 


WARNING! Care must be taken when overlaying data. If a routine modifies data in an overlayed data 
segment, it should not assume it contains that value if it is invoked again. The data may have been 
overwritten by another overlay. 


Notes: 

1. You should not specify a class in an "OVERLAY" directive that belongs to the group 
"DGROUP". These classes are "BEGDATA", "DATA", "BSS" and "STACK". 

If you are linking object files generated by a compiler that uses a class name that does not end with 
"CODE" for segments containing executable code, the "OVERLAY" directive can be used to identify the 
classes that belong to the overlay structure. Consider the following example. 
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Example: 

overlay codel, code2 

Any segment belonging to the class called "CODE1" or "CODE2" is placed in the overlay structure. 
Segments belonging to a class whose name ends with "CODE" will no longer be placed in the overlay 
structure. 
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3.91 The PACKCODE Option 

Formats: DOS, OS/2, QNX, Win16 

This option is intended for 16-bit segmented applications. By default, the Open Watcom Linker 
automatically groups logical code segments into physical segments. The "PACKCODE" option is used to 
specify the size of the physical segment. The format of the "PACKCODE" option ( short form "PACKC") 
is as follows. 


OPTION PACKCODE=n 


where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

n specifies the size of the physical segments into which code segments are packed. The default value of n 
is 64K for 16-bit applications. Note that this is also the maximum size of a physical segment. To suppress 
automatic grouping of code segments, specify a value of 0 for n. 


Notes: 

1. Only adjacent segments are packed into a physical segment. 

2. Segments belonging to the same group are packed in a physical segment. Segments belonging to 
different groups are not packed into a physical segment. 

3. Segments with different attributes are not packed together unless they are explicitly grouped. 
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3.92 The PACKDATA Option 

Formats: DOS, OS/2, QNX, Win 16 

This option is intended for 16-bit segmented applications. By default, the Open Watcom Linker 
automatically groups logical far data segments into physical segments. The "PACKDATA" option is used 
to specify the size of the physical segment. The format of the "PACKDATA" option (short form 
"PACKD") is as follows. 


OPTION PACKDATA=n 


where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

n specifies the size of the physical segments into which far data segments are packed. The default value of 
n is 64K for 16-bit applications. Note that this is also the maximum size of a physical segment. To 
suppress automatic grouping of far data segments, specify a value of 0 for n. 


Notes: 

1. Only adjacent segments are packed into a physical segment. 

2. Segments belonging to the same group are packed in a physical segment. Segments belonging to 
different groups are not packed into a physical segment. 

3. Segments with different attributes are not packed together unless they are explicitly grouped. 
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3.93 The PATH Directive 

Formats: All 

The "PATH" directive is used to specify the directories that are to be searched for object files appearing in 
subsequent "FILE" directives. When the "PATH" directive is specified, the current directory will no longer 
be searched unless it appears in the "PATH" directive. The format of the "PATH" directive (short form 
"P") is as follows. 


PATH path_name{;path_name} 


where description: 

pathj/iame is a path name. 

Consider a directive file containing the following linker directives. 

path \math 

file sin 

path \stats 

file mean, variance 

It instructs the Open Watcom Linker to process the following object files: 

\math\sin. ob j 
\stats\mean.obj 
\stats\variance.obj 

It is also possible to specify a list of paths in a "PATH" directive. Consider the following example. 

path \math;\stats 
file sin 

First, the linker will attempt to load the file "\math\sin.obj". If unsuccessful, the linker will attempt to load 
the file "\stats\sin.obj". 

It is possible to override the path specified in a "PATH" directive by preceding the object file name in a 
"FILE" directive with an absolute path specification. On UNIX platforms, an absolute path specification is 
one that begins the "/" character. On all other hosts, an absolute path specification is one that begins with a 
drive specification or the "\" character. 

path \math 
file sin 
path \stats 

file mean, \mydir\variance 

The above directive file instructs the linker to process the following object files: 

\math\sin.obj 
\stats\mean.obj 
\mydir\variance.obj 
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3.94 The PRIVILEGE Option 

Formats: QNX 

The "PRIVILEGE" option specifies the privilege level (0, 1, 2 or 3) at which the application will run. The 
format of the "PRIVILEGE" option (short form "PRIV") is as follows. 

OPTION PRIVILEGE^ 

where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

The default privilege level is 0. 
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3.95 The PROTMODE Option 

Formats: OS/2 

The "PROTMODE" option specifies that the application will only run in protected mode. This option 
applies to 16-bit OS/2 applications only. The format of the "PROTMODE" option (short form "PROT") is 
as follows. 


OPTION PROTMODE 
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3.96 The PSEUDOPREEMPTION Option 

Formats: NetWare 

The "PSEUDOPREEMPTION" option specifies that an additional set of system calls will yield control to 
other processes. Multitasking in current NetWare operating systems is non-preemptive. That is, a process 
must give up control in order for other processes to execute. Using the "PSEUDOPREEMPTION" option 
increases the probability that all processes are given an equal amount of CPU time. 

The format of the "PSEUDOPREEMPTION" option (short form "PS") is as follows. 

OPTION PSEUDOPREEMPTION 
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3.97 The QUIET Option 

Formats: All 

The "QUIET" option tells the Open Watcom Linker to suppress all informational messages. Only warning, 
error and fatal messages will be issued. By default, the Open Watcom Linker issues informational 
messages. The format of the "QUIET" option (short form "Q") is as follows. 

OPTION QUIET 
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3.98 The REDEFSOK Option 

Formats: All 

The "REDEFSOK" option tells the Open Watcom Linker to ignore redefined symbols and to generate an 
executable file anyway. By default, warning messages are displayed and an executable file is generated if 
redefined symbols are present. 

The format of the "REDEFSOK" option ( short form "RED" ) is as follows. 

OPTION REDEFSOK 


The "NOREDEFSOK" option tells the Open Watcom Linker to treat redefined symbols as an error and to 
not generate an executable file. By default, warning messages are displayed and an executable file is 
generated if redefined symbols are present. 

The format of the "NOREDEFSOK" option (short form "NORED") is as follows. 

OPTION NOREDEFSOK 
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3.99 The REENTRANT Option 

Formats: NetWare 

The "REENTRANT" option specifies that the module is reentrant. That is, if an NLM is LOADed twice, 
the actual code in the server’s memory is reused. The NLM’s start procedure is called once for each 
LOAD. The format of the "REENTRANT" option (short form "RE") is as follows. 

OPTION REENTRANT 
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REFERENCE 


3.100 The REFERENCE Directive 

Formats: All 

The "REFERENCE" directive is used to explicitly reference a symbol that is not referenced by any object 
file processed by the linker. If any symbol appearing in a "REFERENCE" directive is not resolved by the 
linker, an error message will be issued for that symbol specifying that the symbol is undefined. 

The "REFERENCE" directive can be used to force object files from libraries to be linked with the 
application. Also note that a symbol appearing in a "REFERENCE" directive will not be eliminated by 
dead code elimination. For more information on dead code elimination, see the section entitled "The 
ELIMINATE Option" on page 48. 

The format of the "REFERENCE" directive (short form "REF") is as follows. 


REFERENCE symbol_name{, symbol_name} 


where description: 

symbol jiame is the symbol for which a reference is made. 

Consider the following example, 
reference domino 

The symbol domino will be searched for. The object module that defines this symbol will be linked with 
the application. Note that the linker will also attempt to resolve symbols referenced by this module. 
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RESOURCE (Win32) 


3.101 The RESOURCE Directive 

Formats: Win32 


The "RESOURCE" directive is used to specify resource files to add to the executable file being generated. 
The format of the "RESOURCE" directive (short form "RES") is as follows. 



where description: 

resource Jile is a file specification for the name of the resource file that to be added to the executable 

file. If no file extension is specified, a file extension of "res" is assumed. 
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RESOURCE (OS/2, QNX, Win16, Win32) 


3.102 The RESOURCE Option 

Formats: OS/2, QNX, Win16, Win32 

For 16-bit OS/2 executable files and Win 16 or Win32 executable files, the "RESOURCE" option requests 
the linker to add the specified resource file to the executable file being generated. For QNX executable 
files, the "RESOURCE" option specifies the contents of the resource record. 

3.102.1 RESOURCE - OS/2, Win 16, Win32 only 

The "RESOURCE" option requests the linker to add the specified resource file to the executable file that is 
being generated. The format of the "RESOURCE" option (short form "RES") is as follows. 


OPTION RE SOURCE^resourceJile ] 


where description: 

resource Jile is a file specification for the name of the resource file that is to be added to the executable 
file. If no file extension is specified, a file extension of "RES" is assumed for all but QNX 
format executables. 

The "RESOURCE" option cannot be used for 32-bit OS/2 executables. 

3.102.2 RESOURCE - QNX only 

The "RESOURCE" option specifies the contents of the resource record in QNX executable files. The 
format of the "RESOURCE" option (short form "RES") is as follows. 


OPTION RESOURCE resource Jnfo 
resource _info ::= ’string’ I =resource Jile 


where description: 

resource Jile is a file specification for the name of the resource file. No file extension is assumed. 

string is a sequence of characters which is placed in the resource record. 

If a resource file is specified, the contents of the resource file are included in the resource record. 

The resource record contains, for example, help information and is displayed when the following command 
is executed. 

use <executable> 

QNX also provides the usemsg utility to manipulate the resource record of an executable file. Its use is 
recommended. This utility is described in the QNX "Utilities Reference" manual. 
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RUNTIME (ELF, PharLap, Win32) 


3.103 The RUNTIME Directive 

Formats: ELF, PharLap, Win32 

For Win32 applications, the "RUNTIME" directive specifies the environment under which the application 
will run. 

For PharLap applications, the "RUNTIME" directive describes information that is used by 
386IDOS-Extender to setup the environment for execution of the program. 

For ELF applications, the "RUNTIME" directive specifes ABI type and version under which the 
application will run. 

3.103.1 RUNTIME - Win32 only 

The "RUNTIME" directive specifies the environment under which the application will run. The format of 
the "RUNTIME" directive (short form "RU") is as follows. 


RUNTIME env[=major[.minor]] 

env ::= NATIVE I WINDOWS I CONSOLE I POSIX I OS2 I DOSSTYLE 


where description: 


env=major.minor Specifying a system version in the form "major" or "major.minor" indicates the 
minimum operating system version required for the application. For example, the 
following indicates that the application requires Windows 95. 

runtime windows=4.0 


NATIVE (short form "NAT") indicates that the application is a native Windows NT application. 

WINDOWS (short form "WIN") indicates that the application is a Windows application. 

CONSOLE (short form "CON") indicates that the application is a character-mode (command line 

oriented) application. 


POSIX 


(short form "POS") indicates that the application uses the POSIX subsystem available with 
Windows NT. 


OS2 


indicates that the application is a 16-bit OS/2 1.x application. 


DOSSTYLE (short form "DOS") indicates that the application is a Phar Lap TNT DOS extender 

application that uses INT 21 to communicate to the DOS extender rather than calls to a 
DLL. 
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RUNTIME (ELF, PharLap, Win32) 


3.103.2 RUNTIME - PharLap only 

The "RUNTIME" directive describes information that is used by 386IDOS-Extender to setup the 
environment for execution of the program. The format of the "RUNTIME" directive (short form "RU") is 
as follows. 


RUNTIME run_option{,run_option} 

runjoption ::= MINREAL=n I MAXREAL=n I CALLBUFS=n I MINIBuf=n 
I MAXIBUF=n I NISTACK=n I ISTKSIZE=n 
I REALBREAK=offset I PRIVILEGED I UNPRIVILEGED 

offset ::= n I symbol jiame 

where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

symbol jiame is a symbol name. 

MINREAL (short form "MINR") specifies the minimum number of bytes of conventional memory 

required to be free after a program is loaded by 386IDOS-Extender. Note that this memory 
is no longer available to the executing program. The default value of n is 0 in which case 
386IDOS-Extender allocates all conventional memory for the executing program. The 
Open Watcom Linker truncates the specified value to a multiple of 16. n must be less than 
or equal to hexadecimal 100000 (64K*16). 

MAXREAL (short form "MAXR") specifies the maximum number of bytes of conventional memory 
than can be left free after a program is loaded by 386IDOS-Extender. Note that this 
memory is not available to the executing program. The default value of n is 0 in which 
case 386IDOS-Extender allocates all conventional memory for the executing program, n 
must be less than or equal to hexadecimal ffffO. The Open Watcom Linker truncates the 
specified value to a multiple of 16. 

CALLBUFS (short form "CALLB") specifies the size of the call buffer allocated for switching between 
32-bit protected mode and real mode. This buffer is used for communicating information 
between real-mode and 32-bit protected-mode procedures. The buffer address is obtained 
at run-time with a 386IDOS-Extender system call. The size returned is the size of the 
buffer in kilobytes and is less than or equal to 64. 

The default buffer size is zero unless changed using the "CALLBUFS" option. The Open 
Watcom Linker truncates the specified value to a multiple of 1024. n must be less than or 
equal to 64K. Note that n is the number of bytes, not kilobytes. 

MINIBUF (short form "MINIB") specifies the minimum size of the data buffer that is used when DOS 
and BIOS functions are called. The size of this buffer is particularly important for file I/O. 
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RUNTIME (ELF, PharLap, Win32) 


If your program reads or writes large amounts of data, a large value of n should be 
specified, n represents the number of bytes and must be less than or equal to 64K. The 
default value of n is IK. The Open Watcom Linker truncates the specified value to a 
multiple of 1024. 

MAXIBUF (short form "MAXIB") specifies the maximum size of the data buffer that is used when 
DOS and BIOS functions are called. The size of this buffer is particularly important for 
file I/O. If your program reads or writes large amounts of data, a large value of n should be 
specified, n represents the number of bytes and must be less than or equal to 64K. The 
default value of n is 4K. The Open Watcom Linker truncates the specified value to a 
multiple of 1024. 

NISTACK (short form "NIST") specifies the number of stack buffers to be allocated for use by 

386IDOS-Extender when switching from 32-bit protected mode to real mode. By default, 4 
stack buffers are allocated, n must be greater than or equal to 4. 

ISTKSIZE (short form "ISTK") specifies the size of the stack buffers allocated for use by 

386IDOS-Extender when switching from 32-bit protected mode to real mode. By default, 
the size of a stack buffer is IK. The value of n must be greater than or equal to IK and less 
than or equal to 64K. The Open Watcom Linker truncates the specified value to a multiple 
of 1024. 

REALBREAK (short form "REALB") specifies how much of the program must be loaded into 

conventional memory so that it can be accessed and/or executed in real mode. If n is 
specified, the first n bytes of the program must be loaded into conventional memory. If 
symbol is specified, all bytes up to but not including the symbol must be loaded into 
conventional memory. 

PRIVILEGED (short form "PRIV") specifies that the executable is to run at Ring 0 privilege level. 

UNPRIVILEGED (short form "UNPRIV") specifies that the executable is to run at Ring 3 privilege level 
(i.e., unprivileged). This is the default privilege level. 

3.103.3 RUNTIME - ELF only 

The "RUNTIME" directive specifies the Application Binary Interface (ABI) type and version under which 

the application will run. The format of the "RUNTIME" directive (short form "RU") is as follows. 

RUNTIME ABIVER[=abinum.abiversion] I abispec 
abispec ::= abiname[=abiversion] 

abiname ::= SVR4 I LINUX I FREEBSD I NETBSD I SOLARIS 


where description: 

abi=abinum.abiversion Specifying ABI/OS type and optional version indicates specific ABI that an ELF 
application is written for. This information may affect how the ELF executable will be 
interpreted by the operating system. If ABI version is not specified, zero will be used. A 
list of official ABI types may be found in the System V Application Binary Interface 
specification. 
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RUNTIME (ELF, PharLap, Win32) 


For example, both of the following example indicate that the application requires Linux, 
but does not specify ABI version (numeric value zero). 

runtime linux 
runtime abiver=3.0 


SVR4 

LINUX 

FREEBSD 

NETBSD 

SOLARIS 

ABIVER 


indicates that the application is a generic ELF application conforming to the System V 
Release 4 ABI. This is the default. 

(short form "LIN") indicates that the application is a Linux application. 

(short form "FRE") indicates that the application is a FreeBSD application. 

(short form "NET") indicates that the application is a NetBSD application. 

(short form "SOL") indicates that the application is a Sun Solaris application. 

(short form "ABI") specifies the numeric ABI type and optionally version. This method 
allows specification of ABI types not explicitly supported by the Open Watcom Linker. 
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RWRELOCCHECK (Win 16) 


3.104 The RWRELOCCHECK Option 

Formats: Win16 

The "RWRELOCCHECK" option causes the linker to check for segment relocations to a read/write data 
segment and issue a warning if any are found. This option is useful if you are building a 16-bit Windows 
application that may have more than one instance running at a given time. 

The format of the "RWRELOCCHECK" option ( short form "RWR") is as follows. 

OPTION RWRELOCCHECK 
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SCREENNAME (NetWare) 


3.105 The SCREENNAME Option 

Formats: NetWare 

The "SCREENNAME" option specifies the name of the first screen (the screen that is automatically created 
when an NLM is loaded). The format of the "SCREENNAME" option (short form "SCR" ) is as follows. 


OPTION SCREENNAME ’name’ 


where description: 

name specifies the screen name. 

If the "SCREENNAME" option is not specified, the description text specified in the "FORMAT" directive 
is used as the screen name. 
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SECTION (DOS) 


3.106 The SECTION Directive 

Formats: DOS 

The "SECTION" directive is used to define the start of an overlay. All object files in subsequent "FILE" 
directives, up to the next "SECTION" or "END" directive, belong to that overlay. The format of the 
"SECTION" directive (short form "S") is as follows. 


SECTION [INTO ovl Jile] 


where description: 

INTO specifies that the overlay is to be placed into a separate file, namely ovl Jile. If "INTO" 

(short form "IN") is not specified, the overlay is placed in the executable file. Note that 
more than one overlay can be placed in the same file by specifying the same file name in 
multiple "SECTION" directives. 

ovl Jile is the file specification for the name of an overlay file. If no file extension is specified, a 

file extension of "ovl" is assumed. 

Placing overlays in separate files has a number of advantages. For example, if your application was linked 
into one file, it may not fit on a single diskette, making distribution of your application difficult. 
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SEGMENT (OS/2, ONX, WinlS, Win32) 


3.107 The SEGMENT Directive 

Formats: OS/2, QNX, Win16, Win32 

The "SEGMENT" directive is used to describe the attributes of code and data segments. The format of the 
"SEGMENT" directive (short form "SEG") is as follows. 
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SEGMENT (OS/2, QNX, Win16, Win32) 


SEGMENT seg_desc{,seg_desc} 

seg_desc ::= seg_id {seg_attrs}+ 

seg_id ::= ’seg_name’ I CLASS ’class_name’ I TYPE [CODE I DATA] 

OS/2: 

seg_attrs ::= PRELOAD I LOADONCALL 
I IOPL I NOIOPL 

I EXECUTEONLY I EXECUTEREAD 
I READONLY I READWRITE 
I SHARED I NONSHARED 
I CONFORMING I NONCONFORMING 
I PERMANENT I NONPERMANENT 
I INVALID I RESIDENT 
I CONTIGUOUS I DYNAMIC 

Win32: 

seg_attrs ::= PAGEABLE I NONPAGEABLE 
I SHARED I NONSHARED 

Winl6: 

seg_attrs ::= PRELOAD I LOADONCALL 

I EXECUTEONLY I EXECUTEREAD 
I READONLY I READWRITE 
I SHARED I NONSHARED 
I MOVEABLE I /VAYi/J 
I DISCARDABLE 

VxD: 

seg_attrs ::= PRELOAD I LOADONCALL 
I IOPL I NOIOPL 
I SHARED I NONSHARED 
I DISCARDABLE I NONDISCARDABLE 
I CONFORMING I NONCONFORMING 
I RESIDENT 

QNX: 

seg_cittrs ::= EXECUTEONLY I EXECUTEREAD 
I READONLY I READWRITE 


where description: 

segjiame is the name of the code or data segment whose attributes are being specified. 

class_name is a class name. The attributes will be assigned to all segments belonging to the specified 

class. 

PRELOAD (short form "PR", OS/2, VxD and Winl6 only) specifies that the segment is loaded as soon 
as the executable file is loaded. This is the default. 

LOADONCALL (short form "LO", OS/2, VxD and Winl6 only) specifies that the segment is loaded only 
when accessed. 
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SEGMENT (OS/2, QNX, Win 16, Win32) 


PAGEABLE (short form "PAGE", Win32 only) specifies that the segment can be paged from memory. 
This is the default. 

NONPAGEABLE (short form "NONP", Win32 only) specifies that the segment, once loaded into memory, 
must remain in memory. 

CONFORMING (short form "CON", OS/2 and VxD only) specifies that the segment will assume the I/O 
privilege of the segment that referenced it. By default, the segment is 
"NONCONFORMING". 

NONCONFORMING (short form "NONC", OS/2 and VxD only) specifies that the segment will not 
assume the I/O privilege of the segment that referenced it. This is the default. 

IOPL (short form "I", OS/2 and VxD only) specifies that the segment requires I/O privilege. That 

is, they can access the hardware directly. 

NOIOPL (short form "NOI", OS/2 and VxD only) specifies that the segment does not require I/O 
privilege. This is the default. 

PERMANENT (short form "PERM", OS/2 32-bit only) specifies that the segment is permanent. 

NONPERMANENT (short form "NONPERM", OS/2 32-bit only) specifies that the segment is not 
permanent. 

INVALID (short form "INV", OS/2 32-bit only) specifies that the segment is invalid. 

RESIDENT (short form "RES", OS/2 32-bit and VxD only) specifies that the segment is resident. 

CONTIGUOUS (short form "CONT", OS/2 32-bit only) specifies that the segment is contiguous. 

DYNAMIC (short form "DYN", OS/2 32-bit only) specifies that the segment is dynamic. 

EXECUTEONLY (short form "EXECUTEO", OS/2, QNX and Winl6 only) specifies that the segment can 
only be executed. This attribute should only be specified for code segments. This attribute 
should not be specified if it is possible for the code segment to contain jump tables which is 
the case with the Open Watcom C, C++ and FORTRAN 77 optimizing compilers. 

EXECUTEREAD (short form "EXECUTER", OS/2, QNX and Winl6 only) specifies that the segment can 
only be executed and read. This attribute, the default for code segments, should only be 
specified for code segments. This attribute is appropriate for code segments that contain 
jump tables as is possible with the Open Watcom C, C++ and FORTRAN 77 optimizing 
compilers. 

(short form "READO", OS/2, QNX and Winl6 only) specifies that the segment can only be 
read. This attribute should only be specified for data segments. 

(short form "READW", OS/2, QNX and Winl6 only) specifies that the segment can be 
read and written. This is the default for data segments. This attribute should only be 
specified for data segments. 

(short form "SH") specifies that a single copy of the segment will be loaded and will be 
shared by all processes. 


READONLY 

READWRITE 

SHARED 
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SEGMENT (OS/2, QNX, Win16, Win32) 


NONSHARED (short form "NONS") specifies that a unique copy of the segment will be loaded for each 
process. This is the default. 

MOVEABLE (short form "MOV", Winl6 only) specifies that the segment is moveable. By default, 
segments are moveable. 

FIXED (short form "FIX", Winl6 only) specifies that the segment is fixed. 

DISCARDABLE (short form "DIS", Winl6 and VxD only) specifies that the segment is discardable. By 
default, segments are not discardable. 

NONDISCARD ABLE (short form "NOND", VxD only) specifies that the segment is not discardable. By 
default, segments are not discardable. 


Note: Attributes specified for segments identified by a segment name override attributes specified for 
segments identified by a class name. 


158 The SEGMENT Directive 







SHARELIB (NetWare) 


3.108 The SHARELIB Option 

Formats: NetWare 

The "SHARELIB" option specifies the file name of an NLM to be loaded as a shared NLM. Shared NLMs 
contain global code and global data that are mapped into all memory protection domains. This method of 
loading APIs can be used to avoid ring transitions to call other APIs in other domains. 

The format of the "SHARELIB" option (short form "SHA") is as follows. 

OPTION SHARELIB=shared_nlm 

where description: 

shared_nlm is the file name of the shared NLM. 
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SHOWDEAD 


3.109 The SHOWDEAD Option 

Formats: All 

The "SHOWDEAD" option instructs the linker to list, in the map file, the symbols associated with dead 
code and unused C++ virtual functions that it has eliminated from the link. The format of the 
"SHOWDEAD" option (short form "SHO") is as follows. 

OPTION SHOWDEAD 

The "SHOWDEAD" option works best in concert with the "ELIMINATE" and "VFREMOVAL" options. 
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SMALL (DOS) 


3.110 The SMALL Option 

Formats: DOS 

The "SMALL" option tells the Open Watcom Linker to use the standard overlay manager (as opposed to 
the dynamic overlay manager) and that near calls can be generated to overlay vectors corresponding to 
routines defined in the overlayed portion of your program. The format of the "SMALL" option ( short form 
"SM") is as follows. 


OPTION SMALL 


This option should only be specified in the following circumstances. 

1. Your program has been compiled for a small code memory model. 

2. You are creating an overlayed application. 

3. The code in your program, including overlay areas, does not exceed 64K. 

If the "SMALL" option is not specified and you are creating an overlayed application, the linker will 
generate far calls to overlay vectors. In this case, your application must have been compiled using a big 
code memory model. 
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SORT 


3.111 The SORT Directive 

Formats: All 

The "SORT" directive is used to sort the symbols in the "Memory Map" section of the map file. By default, 
symbols are listed on a per module basis in the order the modules were encountered by the linker. That is, a 
module header is displayed followed by the symbols defined by the module. 

The format of the "SORT" directive (short form "SO") is as follows. 


SORT [GLOBAL] [ALPHABETICAL] 


If the "SORT" directive is specified without any options, as in the following example, the module headers 
will be displayed each followed by the list of symbols it defines sorted by address. 

sort 

If only the "GLOBAL" sort option (short form "GL") is specified, as in the following example, the module 
headers will not be displayed and all symbols will be sorted by address. 

sort global 

If only the "ALPHABETICAL" sort option (short form "ALP") is specified, as in the following example, 
the module headers will be displayed each followed by the list of symbols it defines sorted alphabetically. 

sort alphabetical 

If both the "GLOBAL" and "ALPHABETICAL" sort options are specified, as in the following example, the 
module headers will not be displayed and all symbols will be sorted alphabetically. 

sort global alphabetical 

If you are linking a Open Watcom C++ application, mangled names are sorted by using the base name. The 
base name is the name of the symbol as it appeared in the source file. See the section entitled "The 
MANGLEDNAMES Option" on page 91 for more information on mangled names. 
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3.112 The STACK Option 

Formats: All 

The "STACK" option can be used to increase the size of the stack. The format of the "STACK" option 
(short form "ST") is as follows. 


OPTION STACK=n 


where description: 

n represents a value. The complete form of n is the following. 

[Ox]d{d} [k| m] 

d represents a decimal digit. If Ox is specified, the string of digits represents a hexadecimal 
number. If k is specified, the value is multiplied by 1024. If m is specified, the value is 
multiplied by 1024*1024. 

The default stack size varies for both 16-bit and protected-mode 32-bit applications depending on the 
executable format. You can determine the default stack size by looking at the map file that can be 
generated when an application is linked ("OPTION MAP"). During execution of your program, you may 
get an error message indicating your stack has overflowed. If you encounter such an error, you must link 
your application again, this time specifying a larger stack size using the "STACK" option. 

Example: 

option stack=8192 
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STANDARD (DOS) 


3.113 The STANDARD Option 

Formats: DOS 

The "STANDARD" option instructs the Open Watcom Linker to use the standard overlay manager (as 
opposed to the dynamic overlay manager). Your application must be compiled for a big code memory 
model. The format of the "STANDARD" option (short form "STAN") is as follows. 


OPTION STANDARD 


The standard overlay manager is the default. For more information on overlays, see the section entitled 
"Using Overlays" on page 186. 
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START 


3.114 The START Option 

Formats: All 

The format of the "START" option is as follows. 

OPTION START=symbol_name 

where description: 

symbol jiame specifies the name of the procedure where execution begins. 

For the Netware executable format, the default name of the start procedure is "_Prelude". 
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STARTLINK 


3.115 The STARTLINK Directive 

Formats: All 

The "STARTLINK" directive is used to indicate the start of a new set of linker commands that are to be 
processed after the current set of commands has been processed. The format of the "STARTLINK" 
directive (short form "STARTL") is as follows. 


STARTLINK 


The "ENDLINK" directive is used to indicate the end of the set of commands identified by the 
"STARTLINK" directive. 
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STATICS 


3.116 The STATICS Option 

Formats: All 

The "STATICS" option should only be used if you are developing a Open Watcom C or C++ application. 
The Open Watcom C and C++ compilers produce definitions for static symbols in the object file. By 
default, these static symbols do not appear in the map file. If you want static symbols to be displayed in the 
map file, use the "STATICS" option. 

The format of the "STATICS" option (short form "STAT") is as follows. 

OPTION STATICS 
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STUB (OS/2, Win 16, Win32) 


3.117 The STUB Option 

Formats: OS/2, Win16, Win32 

The "STUB" option specifies an executable file containing a "stub" program that is to be placed at the 
beginning of the executable file being generated. The "stub" program will be executed if the module is 
executed under DOS. The format of the "STUB" option is as follows. 


OPTION STUB=stub_name 


where description: 

stub_name is a file specification for the name of the stub executable file. If no file extension is 
specified, a file extension of "EXE" is assumed. 

The Open Watcom Linker will search all paths specified in the PATH environment variable for the stub 
executable file. The stub executable file specified by the "STUB" option must not be the same as the 
executable file being generated. 
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3.118 The SYMFILE Option 

Formats: All 

The "SYMFILE" option provides a method for specifying an alternate file for debugging information. The 
format of the "SYMFILE" option (short form "SYMF") is as follows. 


OPTION SYMFILE[=symbolJile] 


where description: 

symbol_Jile is a file specification for the name of the symbol file. If no file extension is specified, a file 

extension of "sym" is assumed. 

By default, no symbol file is generated; debugging information is appended at the end of the executable 
file. Specifying this option causes the Open Watcom Linker to generate a symbol file. The symbol file 
contains the debugging information generated by the linker when the "DEBUG" directive is used. The 
symbol file can then be used by Open Watcom Debugger. If no debugging information is requested, no 
symbol file is created, regardless of the presence of the "SYMFILE" option. 

If no file name is specified, the symbol file will have a default file extension of "sym" and the same path 
and file name as the executable file. Note that the symbol file will be placed in the same directory as the 
executable file. 

Alternatively, a file name can be specified. The following directive instructs the linker to generate a 
symbol file and call it "myprog.sym" regardless of the name of the executable file. 

option symf=myprog 

You can also specify a path and/or file extension when using the "SYMFILE=" form of the "SYMFILE" 
option. 

Notes: 

1. This option should be used to debug a DOS "COM" executable file. A DOS "COM" executable 
file must not contain any additional information other than the executable information itself 
since DOS uses the size of the file to determine what to load. 

2. This option should be used when creating a Microsoft Windows executable file. Typically, 
before an executable file can be executed as a Microsoft Windows application, a resource 
compiler takes the Windows executable file and a resource file as input and combines them. If 
the executable file contains debugging information, the resource compiler will strip the 
debugging information from the executable file. Therefore, debugging information must not be 
part of the executable file created by the linker. 
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3.119 The SYMTRACE Directive 

Formats: All 

The "SYMTRACE" directive instructs the Open Watcom Linker to print a list of all modules that reference 
the specified symbols. The format of the "SYMTRACE" directive (short form "SYMT") is as follows. 

SYMTRACE symbol_name{,symboljiame} 

where description: 

symbol jiame is the name of a symbol. 

The information is displayed in the map file. Consider the following example. 

Example: 

wlink system my_ os op map file test lib math symt sin, cos 
The Open Watcom Linker will list, in the map file, all modules that reference the symbols "sin" and "cos". 
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3.120 The SYNCHRONIZE Option 

Formats: NetWare 

The "SYNCHRONIZE" option forces an NLM to complete loading before starting to load other NLMs. 
Normally, the other NLMs are loading during the startup procedure. The format of the "SYNCHRONIZE" 
option (short form "SY") is as follows. 


OPTION SYNCHRONIZE 
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3.121 The SYSTEM Directive 

Formats: All 

There are three forms of the "SYSTEM" directive. 

The first form of the "SYSTEM" directive (short form "SYS") is called a system definition directive. It 
allows you to associate a set of linker directives with a specified name called the system name. This set of 
linker directives is called a system definition block. The format of a system definition directive is as 
follows. 


SYSTEM BEGIN system_name {directive} END 


where description: 

system jiame is a unique system name. 

directive is a linker directive. 

A system definition directive cannot be specified within another system definition directive. 

The second form of the "SYSTEM" directive is called a system deletion directive. It allows you to remove 
the association of a set of linker directives with a system name. The format of a system deletion directive is 
as follows. 

SYSTEM DELETE system jiame 

where description: 

system jiame is a defined system name. 

The third form of the "SYSTEM" directive is as follows. 

SYSTEM system jiame 

where description: 

system jiame is a defined system name. 

When this form of the "SYSTEM" directive is encountered, all directives specified in the system definition 
block identified by system_ name will be processed. 

Let us consider an example that demonstrates the use of the "SYSTEM" directive. The following linker 
directives define a system called statistics. 
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system begin statistics 

format dos 

libpath \libs 

library stats, graphics 

option stack=8k 

end 

They specify that a statistics application is to be created by using the libraries "stats.lib" and "graphics.lib". 
These library files are located in the directory "\libs". The application requires a stack size of 8k and the 
specified format of executable will be generated. 

Suppose the linker directives in the above example are contained in the file "stats.Ink". If we wish to create 
a statistics application, we can issue the following command. 

wlink gstats system statistics file myappl 

As demonstrated by the above example, the "SYSTEM" directive can be used to localize the common 
attributes that describe a class of applications. 

The system deletion directive can be used to redefine a previously defined system. Consider the following 
example. 

system begin at_ dos 

libpath %WATCOM%\lib286 
libpath %WATCOM%\lib286\dos 
format dos A 

end 

system begin n98_ dos 
sys at_ dos A 

libpath %WATCOM%\lib286\dos\n98 

end 

system begin dos 
sys at_ dos A 
end 

If you wish to redefine the definition of the "dos" system, you can specify the following set of directives. 

system delete dos 
system begin dos 
sys n98_ dos A 
end 

This effectively redefines a "dos" system to be equivalent to a "n98_dos" system (NEC PC-9800 DOS), 
rather than the previously defined "at_dos" system (AT-compatible DOS). 

For additional examples on the use of the "SYSTEM" directive, examine the contents of the wlink . ink 
and wlsystem, ink files. 

The file wlink. ink is a special linker directive file that is automatically processed by the Open Watcom 
Linker before processing any other directives. On a DOS, ZDOS, OS/2, or Windows-hosted system, this 
file must be located in one of the paths specified in the PATH environment variable. On a QNX-hosted 
system, this file should be located in the /etc directory. A default version of this file is located in the 
\watcom\binw directory on DOS-hosted systems, the \watcom\binp directory on OS/2-hosted 
systems, the /etc directory on QNX-hosted systems, and the \watcom\binnt directory on Windows 
95 or Windows NT-hosted systems. Note that the file wlink. ink includes the file wl system, ink 
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which is located in the \watcom\binw directory on DOS, OS/2, or Windows-hosted systems and the 
/etc directory on QNX-hosted systems. 

The files wlink. Ink and wlsystem. Ink reference the WATCOM environment variable which must 
be set to the directory in which you installed your software. 

The default name of the linker directive file (wlink. Ink) can be overridden by the WLINK_LNK 
environment variable. If the specified file can’t be opened, the default file name will be used. For 
example, if the WLINK_LNK environment variable is defined as follows 

set WLINK_ LNK=my . Ink 

then the Open Watcom Linker will attempt to use a my. Ink directive file, and if that file cannot be 
opened, the linker will reveit to using the default wlink . Ink file. 

3.121.1 Special System Names 

There are two special system names. When the linker has processed all object files and the executable file 
format has not been determined, and a system definition block has not been processed, the directives 
specified in the "286" or "386" system definition block will be processed. The "386" system definition 
block will be processed if a 32-bit object file has been processed. Furthermore, only a restricted set of 
linker directives is allowed in a "286" and "386" system definition block. They are as follows. 

• FORMAT 

• LIB FILE 

• LIBPATH 

• LIBRARY 
•NAME 

• OPTION 

• RUNTIME (for Phar Lap executable files only) 

• SEGMENT (for OS/2 and QNX executable files only) 
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3.122 The THREADNAME Option 

Formats: NetWare 

The "THREADNAME" option is used to specify the pattern to be used for generating thread names. The 
format of the "THREADNAME" option ( short form "THR" ) is as follows. 


OPTION THREADNAME ’thread_name’ 


where description: 

threadjiame specifies the pattern used for generating thread names and must be a string of 1 to 5 
characters. 

The first thread name is generated by appending "0" to thread_name, the second by appending " 1" to 
thread_name, etc. If the "THREADNAME" option is not specified, the first 5 characters of the description 
specified in the "FORMAT" directive are used as the pattern for generating thread names. 
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3.123 The TOGGLERELOCS Option 

Formats: OS/2 

The "TOGGLERELOCS" option is used with LX format executables under 32-bit DOS/4G only. The 
"INTERNALRELOCS" option causes the Open Watcom Linker to include internal relocation information 
in DOS/4G LX format executables. Having done so, the linker normally clears the "internal fixups done" 
flag in the LX executable header (bit 0x10). The "TOGGLERELOCS" option causes the linker to toggle 
the value of the "internal fixups done" flag in the LX executable header (bit 0x10). This option is used with 
DOS/4G non-zero based executables. Contact Tenberry Software for further explanation. 

The format of the "TOGGLERELOCS" option (short form "TOG") is as follows. 


OPTION TOGGLERELOCS 
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3.124 The UNDEFSOK Option 

Formats: All 

The "UNDEFSOK" option tells the Open Watcom Linker to generate an executable file even if undefined 
symbols are present. By default, no executable file will be generated if undefined symbols are present. 

The format of the "UNDEFSOK" option (short form "U") is as follows. 

OPTION UNDEFSOK 

The "NOUNDEFSOK" option tells the Open Watcom Linker to not generate an executable file if undefined 
symbols are present. This is the default behaviour. 

The format of the "NOUNDEFSOK" option ( short form "NOU") is as follows. 

OPTION NOUNDEFSOK 
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3.125 The VECTOR Directive 

Formats: DOS 

The "VECTOR" directive forces the Open Watcom Linker to generate an overlay vector for the specified 
symbols and is intended to be used when the "NOINDIRECT" option is specified. See the section entitled 
"The NOINDIRECT Option" on page 112 for additional information on the usage of the "VECTOR" 
directive. 

The format of the "VECTOR" directive (short form "VE") is as follows. 


VECTOR symbol_name {, symbol_name} 


where description: 

symboljiame is a symbol name. 

For more information on overlays, see the section entitled "Using Overlays" on page 186. 
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3.126 The VERBOSE Option 

Formats: All 

The "VERBOSE" option controls the amount of information produced by the Open Watcom Linker in the 
map file. The format of the "VERBOSE" option (short form "V") is as follows. 


OPTION VERBOSE 


If the "VERBOSE" option is specified, the linker will list, for each object file, all segments it defines and 
their sizes. By default, this information is not produced in the map file. 
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3.127 The VERSION Option 

Formats: NetWare, OS/2, Win16, Win32 

The "VERSION" option can be used to identify the application so that it can be distinguished from other 
versions (releases) of the same application. 

This option is most useful when creating a DLL or NLM since applications that use the DLL or NLM may 
only execute with a specific version of the DLL or NLM. 

The format of the "VERSION" option (short form "VERS") is as follows. 


OS/2, Win 16, Win32: 

OPTION VERSION=major[.minor] 

Netware: 

OPTION VERSION=major[.minor[.revision]] 

where description: 

major specifies the major version number. 

minor specifies the minor version number and must be less than 100. 

revision specifies the revision. The revision should be a number or a letter. If it is a number, it must 

be less than 27. 
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3.128 The VFREMOVAL Option 

Formats: All 

The "VFREMOVAL" option instructs the linker to remove unused C++ virtual functions. The format of 
the "VFREMOVAL" option (short form "VFR") is as follows. 


OPTION VFREMOVAL 


If the "VFREMOVAL" option is specified, the linker will attempt to eliminate unused virtual functions. In 
order for the linker to do this, the Open Watcom C++ "zv" compiler option must be used for all object files 
in the executable. The "VFREMOVAL" option works best in concert with the "ELIMINATE" option. 


The VFREMOVAL Option 181 




The Open Watcom Linker 


3.129 The XDCDATA Option 

Formats: NetWare 

The "XDCDATA" option specifies the name of a file that contains Remote Procedure Call (RPC) 
descriptions for calls in this NLM. RPC descriptions for APIs make it possible for APIs to be exported 
across memory-protection domain boundaries. 

The format of the "XDCDATA" option (short form "XDC") is as follows. 


OPTION XDCDATA=rpc Jile 


where description: 

rpc_Jile is the name of the file containing RPC descriptions. 


182 The XDCDATA Option 




4 The DOS Executable File Format 


This chapter deals specifically with aspects of DOS executable files. The DOS executable file format will 
only run under the DOS operating system. 

Input to the Open Watcom Linker is specified on the command line and can be redirected to one or more 
files or environment strings. The Open Watcom Linker command line format is as follows. 


WLINK {directive} 


where directive is any of the following: 

ALIAS alias_name=symbol_name{,alias_name=symbol_name} 
AUTOSECTION 

BEGIN {section Jype [INTO ovl_Jile] {directive}} END 
DEBUG dbtype [dblist] I DEBUG [dblist] 

DISABLE msg_num{,msg_n um} 

ENDLINK 

FILE obj_spec{,obj_spec} 

FIXEDLIB library _Jile{, library _file} 

FORCEVECTOR symboljiamef,symboljiame} 

FORMAT DOS [COM] 

LANGUAGE long 
LIBFILE obj Jile{,obj Jile} 

LIBPATH pathjiame {;pathjiame} 

LIBRARY library_Jile{,library_file} 

MODTRACE obj_module{,obj_module} 

NAME exe _Jile 
NEWSEGMENT 

NOVECTOR symbol_name{,symbol jiame} 

OPTION option{,option} 

AREA=n 

ARTIFICIAL 

[NO/CACHE 

[NOjCASEEXACT 

CVPACK 

DISTRIBUTE 

DOSSEG 

DYNAMIC 

ELIMINATE 

[NO]FARC ALLS 

FULLHEADER 

MANGLEDNAMES 

MAP[=map _Jile] 
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MAXERRORS=n 

NAMELEN=n 

NODEFAULTLIBS 

NOEXTENSION 

NOINDIRECT 

OSNAME= ’string ’ 

PACKCODE=n 

PACKDATA=n 

QUIET 

REDEFSOK 

SHOWDEAD 

SMALL 

STACK=n 

STANDARD 

S TAR T=symbol_name 

STATICS 

SYMFILE[=symbolJile] 

[NO]UNDEFSOK 

VERBOSE 

VFREMOVAL 

OPTLIB library_Jile{, library_file} 

OVERLAY class{, class} 

PATH path_name{;path_name} 

REFERENCE symboljiame{,symbol jiame} 

SECTION 

SORT [GLOBAL] [ALPHABETICAL] 

STARTLINK 

SYMTRACE symboljiamef,symboljiame} 

SYSTEM BEGIN system jiame {directive} END 

SYSTEM system jiame 

VE C TOR symbol jiame {, symbol jiame} 

# comment 
@ directive_Jile 

You can view all the directives specific to DOS executable files by simply typing the following: 
wlink ? dos 


Notes: 

1. If the file "wlink.hlp" is located in one of the paths specified in the "PATH" environment 
variable, the contents of that file will be displayed when the following command is issued. 

wlink ? 

2. If all of the directive information does not fit on the command line, type the following. 

wlink 

The prompt "WLINK>" will appear on the next line. You can enter as many lines of directive 
information as required. Press "Ctrl/Z" followed by the "Enter" key to terminate the input of 
directive information if you are running a DOS, ZDOS, OS/2 or Windows NT-hosted version of 
the Open Watcom Linker. Press "Ctrl/D" to terminate the input of directive information if you 
are running a UNIX-hosted version of the Open Watcom Linker. 
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4.1 Memory Layout 

The following describes the segment ordering of an application linked by the Open Watcom Linker. Note 
that this assumes that the "DOSSEG" linker option has been specified. 

1. all segments not belonging to group "DGROUP" with class "CODE" 

2. all other segments not belonging to group "DGROUP" 

3. all segments belonging to group "DGROUP" with class "BEGDATA" 

4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

5. all segments belonging to group "DGROUP" with class "BSS" 

6. all segments belonging to group "DGROUP" with class "STACK" 

A special segment belonging to class "BEGDATA" is defined when linking with Open Watcom run-time 
libraries. This segment is initialized with the hexadecimal byte pattern "01" and is the first segment in 
group "DGROUP" so that storing data at location 0 can be detected. 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 


4.2 The Open Watcom Linker Memory Requirements 

The Open Watcom Linker uses all available memory when linking an application. For DOS-hosted 
versions of the Open Watcom Linker, this includes expanded memory (EMS) and extended memory. It is 
possible for the size of the image being linked to exceed the amount of memory available in your machine, 
particularly if the image file is to contain debugging information. For this reason, a temporary disk file is 
used when all available memory is used by the Open Watcom Linker. 

Normally, the temporary file is created in the current working directory. However, by defining the "tmp" 
environment variable to be a directory, you can tell the Open Watcom Linker where to create the temporary 
file. This can be particularly useful if you have a RAM disk. Consider the following definition of the 
"tmp" environment variable. 

set tmp=\tmp 

The Open Watcom Linker will create the temporary file in the directory "\tmp". 
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4.3 Using Overlays 

Overlays are used primarily for large programs where memory requirements do not permit all portions of 
the program to reside in memory at the same time. An overlayed program consists of a root and a number 
of overlay areas. 

The root always resides in memory. The root usually contains routines that are frequently used. For 
example, a floating-point library might be placed in the root. Also, any modules extracted from a library 
file during the linking process are placed in the root unless the "DISTRIBUTE" option is specified. This 
option tells the Open Watcom Linker to distribute modules extracted from libraries throughout the overlay 
structure. See the section entitled "The DISTRIBUTE Option" on page 45 for information on how these 
object modules are distributed. Libraries can also be placed in the overlay structure by using the 
"FIXEDLIB" directive. See the section entitled "The FIXEDLIB Directive" on page 59 for information on 
how to use this directive. 

An overlay area is a piece of memory shared by various parts of a program. Each overlay area has a 
structure associated with it. This structure defines where in the overlay area sections of a program are 
loaded. Sections of a program that are loaded into an overlay area are called overlays. 

The Open Watcom Linker supports two overlay managers: the standard overlay manager and the dynamic 
overlay manager. The standard overlay manager requires the user to create an overlay structure that defines 
the "call" relationship between the object modules that comprise an application. It is the responsibility of 
the user to define an optimal overlay structure so as to minimize the number of calls that cause overlays to 
be loaded. The "SMALL" and "STANDARD" options select the standard overlay manager. The 
"SMALL" option is required if you are linking an application compiled for a small code memory model. 
The "STANDARD" option is required if you are linking an application compiled for a big code memory 
model. By default, the Open Watcom Linker assumes your application has been compiled using a memory 
model with a big code model. Option "STANDARD" is the default. 

The "DYNAMIC" option, described in the section entitled "The DYNAMIC Option" on page 47, selects 
the dynamic overlay manager. The dynamic overlay manager is more sophisticated than the standard 
overlay manager. The user need not be concerned about the "call" relationship between the object modules 
that comprise an application. Basically, each module is placed in its own overlay. The dynamic overlay 
manager swaps each module (overlay) into a single overlay area. This overlay area is used as a pool of 
memory from which memory for overlays is allocated. The larger the memory pool, the greater the number 
of modules that can simultaneously reside in memory. The size of the overlay area can be controlled by the 
"AREA" option. See the section entitled "The AREA Option" on page 24 for information on using this 
option. 

Note that the dynamic overlay manager can only be used with applications that have been compiled using 
the "of" option and a big code memory model. 

4.3.1 Defining Overlay Structures 

Consider the following directive file. 
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# 

# Define files that belong in the root. 

# 

file fileO, filel 
# 

# Define an overlay area. 

# 

begin 

section file file2 
section file file3, file4 
section file file5 
end 

1. The root consists of fileO and filel. 

2. Three overlays are defined. The first overlay (overlay #1) contains f ile2, the second overlay 
(overlay #2) contains file3 and file4, and the third overlay (overlay #3) contains file5 . 

The following diagram depicts the overlay structure. 

H-K- start of root 

fileO 

filel 

H-1-1-+<- start of overlay 

#1 | #2 | #3 | area 

file2 | file3 | file5 

i f ile4 ' 


Notes: 

1. The 3 overlays are all loaded at the same memory location. Such overlays are called parallel. 

In the previous example, only one overlay area was defined. It is possible to define more than one overlay 
area as demonstrated by the following example. 
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# 

# Define files that belong in the root. 

# 

file fileO, filel 
# 

# Define an overlay area. 

# 

begin 

section file file2 
section file file3, file4 
section file file5 
end 
# 

# Define an overlay area. 

# 

begin 

section file file6 
section file file7 
section file file8 
end 


Two overlay areas are defined. The first is identical to the overlay area defined in the previous example. 

The second overlay area contains three overlays; the first overlay (overlay #4) contains f ile6, the second 
overlay (overlay #5) contains file 7, and the third overlay (overlay #6) contains file 8. 


The following diagram depicts the overlay structure. 


H-+<- start of root 

fileO 

filel 


h-+-+-+ <- 


#1 


f ile2 


#2 


#3 


f ile3 
f ile4 


f ile5 


h-+-+-+ <- 

#4 | #5 | #6 | 

file6 | file7 | file8 

- + - + - + 


start of overlay 
area 


start of overlay 
area 


In the above example, the "AUTOSECTION" directive could have been used to define the overlays for the 
second overlay area. The following example illustrates the use of the "AUTOSECTION" directive. 


188 Using Overlays 








The DOS Executable File Format 


# Define files that belong in the root. 

# 

file fileO, filel 
# 

# Define an overlay area. 

# 

begin 

section file file2 
section file file3, file4 
section file file5 
end 
# 

# Define an overlay area. 

# 

begin 

autosection 
file file6 
file file7 
file file8 
end 


In all of the above examples the overlays are placed in the executable file. It is possible to place overlays in 
separate files by specifying the "INTO" option in the "SECTION" directive that starts the definition of an 
overlay. By specifying the "INTO" option in the "AUTOSECTION" directive, all overlays created as a 
result of the "AUTOSECTION" directive are placed in one overlay file. 


Consider the following example. It is similar to the previous example except for the following. Overlay #1 
is placed in the file "ovll.ovl", overlay #2 is placed in the file "ovl2.ovl", overlay #3 is placed in the file 
"ovl3.ovl" and overlays #4, #5 and #6 are placed in file "ovl4.ovl". 


# 

# Define files that 

# 

file fileO, filel 
# 

# Define an overlay 

# 

begin 

section into ovll 
section into ovl2 
section into ovl3 
end 
# 

# Define an overlay 

# 


belong in the root. 


area. 


file file2 

file file3, file4 

file file5 


area. 


begin 

autosection into ovl4 
file file6 
file file7 
file file8 
end 
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4.3.1.1 The Dynamic Overlay Manager 

Let us again consider the above example but this time we will use the dynamic overlay manager. The 
easiest way to take the above overlay structure and use it with the dynamic overlay manager is to simply 
specify the "DYNAMIC” option. 

option DYNAMIC 

Even though we have defined an overlay structure with more than one overlay area, the Open Watcom 
Linker will allocate one overlay area and overlays from both overlay areas will be loaded into a single 
overlay area. The size of the overlay area created by the Open Watcom Linker will be twice the size of the 
largest overlay area (unless the "AREA" option is used). 

To take full advantage of the dynamic overlay manager, the following sequence of directives should be 
used. 


# 

# Define files that belong in the root. 

# 

file fileO, filel 
# 

# Define an overlay area. 

# 

begin 


autosection 

into 

ovll 

file 

f ile2 



autosection 

into 

ovl2 

file 

f ile3 



file 

f ile4 



autosection 

into 

ovl3 

file 

f ile5 



autosection 

into 

ov!4 

file 

f ile6 



file 

f ile7 



file 

f ile8 




end 

In the above example, each module will be in its own overlay. This will result in a module being loaded 
into memory only when it is required. If separate overlay files are not required, a single 
"AUTOSECTION" directive could be used as demonstrated by the following example. 
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# 

# Define files that belong in the root. 

# 

file fileO, filel 
# 

# Define an overlay area. 

# 

begin 

autosection 
file file2 
file file3 
file file4 
file file5 
file file6 
file file7 
file file8 
end 

4.3.2 Nested Overlay Structures 

Nested overlay structures occur when the "BEGIN"-"END" directives are nested and are only useful if the 
standard overlay manager is being used. If you have selected the dynamic overlay manager, the nesting 
levels will be ignored and each overlay will be loaded into a single overlay area. 

Consider the following directive file. 

# 

# Define files that belong in the root. 

# 

file fileO, filel 
# 

# Define a nested overlay structure. 

# 

begin 

section file file2 
section file file3 
begin 

section file file4, file5 
section file file6 
end 
end 

Notes: 

1. The root contains fileO and filel. 

2. Four overlays are defined. The first overlay (overlay #1) contains file2, the second overlay 
(overlay #2) contains file3, the third overlay (overlay #3) contains file4 and file5, and 
the fourth overlay (overlay #4) contains f ile6 . 

The following diagram depicts the overlay structure. 
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H-K- start of root 

f ileO 
filel 

H- 1 -t-<— start of overlay 

#1 #2 area 

file2 file3 

+-+-+<- start of overlay 

#3 #4 | area 

file4 file6 

file5 


Notes: 

1. Overlay #1 and overlay #2 are parallel overlays. Overlay #3 and overlay #4 are also parallel 
overlays. 

2. Overlay #3 and overlay #4 are loaded in memory following overlay #2. In this case, overlay #2 
is called an ancestor of overlay #3 and overlay #4. Conversely, overlay #3 and overlay #4 are 
descendants of overlay #2. 

3. The root is an ancestor of all overlays. 

Nested overlays are particularly useful when the routines that make up one overlay are used only by a few 
other overlays. In the above example, the routines in overlay #2 would only be used by routines in overlay 
#3 and overlay #4 but not by overlay #1. 

4.3.3 Rules About Overlays 

The Open Watcom Linker handles all the details of loading overlays. No changes to a program have to be 
made if, for example, it becomes so large that you have to change to an overlay structure. Certain rules 
have to be followed to ensure the proper execution of your program. These rules pertain more to the 
organization of the components of your program and less to the way it was coded. 

1. Care should be taken when passing addresses of functions as arguments. Consider the following 


example. 

H-+<- start of root 

main 

H-1-K— start of overlay 

modulea moduleb area 

f h 

g 

+-+-+ 
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Function/passes the address of static function g to function h. Function li then calls function g 
indirectly. Function/and function g are defined in modulea and function h is defined in 
moduleb. Furthermore, suppose that modulea and moduleb are parallel overlays. The linker will 
not generate an overlay vector for function g since it is static so when function h calls function g 
indirectly, unpredictable results may occur. Note that if g is a global function, an overlay vector 
will be generated and the program will execute correctly. 

2. You should organize the overlay structure to minimize the number of times overlays have to be 
loaded into memory. Consider a loop calling two routines, each routine in a different overlay. If 
the overlay structure is such that the overlays are parallel, that is they occupy the same memory, 
each iteration of the loop will cause 2 overlays to be loaded into memory. This will significantly 
increase execution time if the loop is iterated many times. 

3. If a number of overlays have a number of common routines that they all reference, the common 
routines will most likely be placed in an ancestor overlay of the overlays that reference them. 

For this reason, whenever an overlay is loaded, all its ancestors are also loaded. 

4. In an overlayed program, the overlay loader is included in the executable file. If we are dealing 
with relatively small programs, the size of the overlay loader may be larger than the amount of 
memory saved by overlaying the program. In a larger application, the size of the overlayed 
version would be smaller than the size of the non-overlayed version. Note that overlaying a 
program results in a larger executable file but the memory requirements are less. 

5. The symbols "_OVLTAB_", "_OVLSTARTVEC_", "_OVLENDVEC_", 

"_LOVLLDR_", "_NOVLLDR_", "_SOVLLDR_", "_LOVLINIT_", 

"_NOVLINIT_" and "_SOVLINIT_" are defined when you use overlays. Your program 

should not define these symbols. 

6. When using the dynamic overlay manager, you should not take the address of static functions. 
Static functions are not given overlay vectors, so if the module in which the address of a static 
function is taken, is moved by the dynamic overlay manager, that address will no longer point to 
the static function. 

4.3.4 Increasing the Dynamic Overlay Area 

Unless the "AREA" option has been specified, the default size of the dynamic overlay area is twice the size 
of the largest overlay (or module if each module is its own overlay). It is possible to add additional overlay 
areas at run-time so that the dynamic overlay manager can use the additional memory. A routine has been 
provided, called _ ovl_ addarea . This function is defined as follows. 

void far _ ovl_ addarea(unsigned segment,unsigned size); 

The first argument is the segment address of the block memory you wish to add. The second argument is 
the size, in paragraphs, of the memory block. 

In assembly language, the function is called _ ovl_ addarea_ with the first argument being passed in 
register AX and the second argument in register DX. 
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4.3.5 How Overlay Files are Opened 

The overlay manager normally opens overlay files, including executable files containing overlays, in 
compatibility mode. Compatibility mode is a sharing mode. A file opened in compatibility mode means 
that it can be opened any number of times provided that it is not currently opened under one of the other 
sharing modes. In other words, the file must always be opened in compatibility mode. 

The overlay manager keeps most recently used overlay files open for efficiency. This means that any 
application, including the currently executing application, that may want to open an overlay file, must open 
it in compatibility mode. For example, the executing application may have data at the end of the executable 
file that it wishes to access. 

If an application wishes to open the file in a sharing mode other than compatibility mode, the function 
_ ovl_ openf lags has been defined which allows the caller to specify the sharing mode with which the 
overlay files will be opened by the overlay manager. This function is defined as follows. 

unsigned far _ ovl_ openflags (unsigned sharing_ mode) ; 

Legal values for the sharing mode are as follows. 


Sharing Mode 

Value 

compatibility mode 

0x00 

deny read/write mode 

0x01 

deny write mode 

0x02 

deny read mode 

0x03 

deny none mode 

0x04 


The return value is the previous sharing mode used by the overlay manager to open overlay files. 

Note that DOS opens executable files in compatibility mode when loading them for execution. This is 
important for executable files on networks that may be accessed simultaneously by many users. 

In assembly language, the function is called _ ovl_ openf lags_ with its argument being passed in 
register AX. 

4.4 Converting Microsoft Response Files to Directive Files 

A utility called MS2WLINK can be used to convert Microsoft linker response files to Open Watcom Linker 
directive files. The response files must correspond to the linker found in version 7 or earlier of Microsoft 
C. Later versions of response files such as those used with Microsoft Visual C++ are not entirely 
supported. 

The same utility can also convert much of the content of IBM OS/2 LINK386 response files since the 
syntax is similar. 

Input to MS2WLINK is processed in the same way as the Microsoft linker processes its input. The 
difference is that MS2WLINK writes the corresponding Open Watcom Linker directive file to the standard 
output device instead of a creating an executable file. The resulting output can be redirected to a disk file 
which can then be used as input to the Open Watcom Linker to produce an executable file. 
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Suppose you have a Microsoft linker response file called "test.rsp". You can convert this file to a Open 
Watcom Linker directive file by issuing the following command. 

Example: 

ms2wlink Stest.rsp >test.lnk 

You can now use the Open Watcom Linker to link your program by issuing the following command. 

Example: 

wlink @test 

An alternative way to link your application with the Open Watcom Linker from a Microsoft response file is 
to issue the following command. 

Example: 

ms2wlink Stest.rsp | wlink 

Since the Open Watcom Linker gets its input from the standard input device, you do not have to create a 
Open Watcom Linker directive file to link your application. 

Note that MS2WLINK can also process module-definition files used for creating OS/2 applications. 
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5 The ZDOS Executable File Format 


This chapter deals specifically with aspects of ZDOS executable files. The ZDOS executable file format 
will only run under the ZDOS operating system. 

Input to the Open Watcom Linker is specified on the command line and can be redirected to one or more 
files or environment strings. The Open Watcom Linker command line format is as follows. 


WLINK {directive} 


where directive is any of the following: 


ALIAS alias_name=symbol_name{,alias_name=symbol_name} 
DEBUG dbtype [dblist] I DEBUG [dblist] 

DISABLE msg_num{,msg_nurn} 

ENDLINK 

FILE obj_spec{,obj_spec} 

FORMAT ZDOS [SYS I IIWD I FSD] 

LANGUAGE long 
LIBFILE obj Jile{,obj Jile} 

LIBPATH path_name{;path_name} 

LIBRARY library_Jile{,library_file} 

MODFILE obj Jile{,obj Jile} 

MODTRACE objmodule{,obj module} 

NAME exejile 
OPTION option},option} 

ARTIFICIAL 

[NOjCACHE 

[NOjCASEEXACT 

CVPACK 

DOSSEG 

ELIMINATE 

[NO]FARC ALLS 

INCREMENTAL 

MANGLEDNAMES 

MAP[=map _Jile] 

MAXERRORS=n 
NAMELEN=n 
NODEFAULTLIBS 
NOEXTENSION 
OSNAME= ’string ’ 

QUIET 

REDEFSOK 

STACK=n 
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S TAR T=symbol_name 
STATICS 

SYMFILE[=symbolJile] 

[NOJUNDEFSOK 

VERBOSE 

VFREMOVAL 

OPTLIB library_Jile{,library_file} 

PATH path_name{;path_name} 

REFERENCE symbol_name{,symbol jiame} 

SORT [GLOBAL] [ALPHABETICAL] 

STARTLINK 

SYMTRACE symbol_name{,symboljiame} 

SYSTEM BEGIN system jiame {directive} END 
SYSTEM system_name 
# comment 
@ directive_Jile 

You can view all the directives specific to ZDOS executable files by simply typing the following: 

wlink ? zdos 
Notes: 

1. If the file "wlink.hlp" is located in one of the paths specified in the "PATH" environment 
variable, the contents of that file will be displayed when the following command is issued. 

wlink ? 

2. If all of the directive information does not fit on the command line, type the following. 

wlink 

The prompt "WLINK>" will appear on the next line. You can enter as many lines of directive 
information as required. Press "Ctrl/Z" followed by the "Enter" key to terminate the input of 
directive information if you are running a DOS, ZDOS, OS/2 or Windows NT-hosted version of 
the Open Watcom Linker. Press "Ctrl/D" to terminate the input of directive information if you 
are running a UNIX-hosted version of the Open Watcom Linker. 

5.1 Memory Layout 

The following describes the segment ordering of an application linked by the Open Watcom Linker. Note 
that this assumes that the "DOSSEG" linker option has been specified. 

1. all segments not belonging to group "DGROUP" with class "CODE" 

2. all other segments not belonging to group "DGROUP" 

3. all segments belonging to group "DGROUP" with class "BEGDATA" 

4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

5. all segments belonging to group "DGROUP" with class "BSS" 
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6. all segments belonging to group "DGROUP" with class "STACK" 

A special segment belonging to class "BEGDATA" is defined when linking with Open Watcom run-time 
libraries. This segment is initialized with the hexadecimal byte pattern "01" and is the first segment in 
group "DGROUP" so that storing data at location 0 can be detected. 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 


5.2 The Open Watcom Linker Memory Requirements 

The Open Watcom Linker uses all available memory when linking an application. For DOS-hosted 
versions of the Open Watcom Linker, this includes expanded memory (EMS) and extended memory. It is 
possible for the size of the image being linked to exceed the amount of memory available in your machine, 
particularly if the image file is to contain debugging information. For this reason, a temporary disk file is 
used when all available memory is used by the Open Watcom Linker. 

Normally, the temporary file is created in the current working directory. However, by defining the "tmp" 
environment variable to be a directory, you can tell the Open Watcom Linker where to create the temporary 
file. This can be particularly useful if you have a RAM disk. Consider the following definition of the 
"tmp" environment variable. 

set tmp=\tmp 

The Open Watcom Linker will create the temporary file in the directory "\tmp". 

5.3 Converting Microsoft Response Files to Directive Files 

A utility called MS2WLINK can be used to convert Microsoft linker response files to Open Watcom Linker 
directive files. The response files must correspond to the linker found in version 7 or earlier of Microsoft 
C. Later versions of response files such as those used with Microsoft Visual C++ are not entirely 
supported. 

The same utility can also convert much of the content of IBM OS/2 LINK386 response files since the 
syntax is similar. 

Input to MS2WLINK is processed in the same way as the Microsoft linker processes its input. The 
difference is that MS2WLINK writes the corresponding Open Watcom Linker directive file to the standard 
output device instead of a creating an executable file. The resulting output can be redirected to a disk file 
which can then be used as input to the Open Watcom Linker to produce an executable file. 

Suppose you have a Microsoft linker response file called "test.rsp". You can convert this file to a Open 
Watcom Linker directive file by issuing the following command. 
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Example: 

ms2wlink Stest.rsp >test.lnk 

You can now use the Open Watcom Linker to link your program by issuing the following command. 


Example: 

wlink @test 


An alternative way to link your application with the Open Watcom Linker from a Microsoft response file is 
to issue the following command. 

Example: 

ms2wlink Stest.rsp | wlink 

Since the Open Watcom Linker gets its input from the standard input device, you do not have to create a 
Open Watcom Linker directive file to link your application. 

Note that MS2WLINK can also process module-definition files used for creating OS/2 applications. 
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6 The RA W File Format 


This chapter deals specifically with aspects of RAW executable files. 

Input to the Open Watcom Linker is specified on the command line and can be redirected to one or more 
files or environment strings. The Open Watcom Linker command line format is as follows. 


WLINK {directive} 


where directive is any of the following: 


ALIAS alias_name=symbol_name{,alias_name=symbol_name} 
DEBUG dbtype [dblist] I DEBUG [dblist] 

DISABLE msg_n um{,msg_nurn} 

ENDLINK 

FILE obj_spec{,obj_spec} 

FORMAT RAW [BIN I HEX] 

LANGUAGE long 
LIBFILE objJile{,objJile} 

LIBPATH path_name{;path_name} 

LIBRARY library_Jile{,library_file} 

MODFILE obj_file{,obj Jile} 

MODTRACE obj_module{,obj_module} 

NAME exe _Jile 
OPTION option},option} 

ARTIFICIAL 

[NO]CACHE 

[NO]CASEEXACT 

CVPACK 

DOSSEG 

ELIMINATE 

[NO]FARC ALLS 

INCREMENTAL 

MANGLEDNAMES 

MAP[=map _Jile] 

MAXERRORS=n 

NAMELEN=n 

NODEFAULTLIBS 

NOEXTENSION 

OFFSET=n 

OSNAME= ’string ’ 

QUIET 

REDEFSOK 

STACK=n 


The RAW File Format 201 





The Open Watcom Linker 


S TAR T=symbol_name 
STATICS 

SYMFILE[=symbolJile] 

[NOJUNDEFSOK 

VERBOSE 

VFREMOVAL 

OPTLIB library_file{, library_file} 

PATH path jiame{;path jiamej 
REFERENCE symbol_name{,symbol jiame} 

SORT [GLOBAL] [ALPHABETICAL] 

STARTLINK 

SYMTRACE symbol_name{,symboljiame} 

SYSTEM BEGIN system jiame {directive} END 
SYSTEM system_name 
# comment 
@ directive_Jile 

You can view all the directives specific to RAW executable files by simply typing the following: 

wlink ? raw 
Notes: 

1. If the file "wlink.hlp" is located in one of the paths specified in the "PATH" environment 
variable, the contents of that file will be displayed when the following command is issued. 

wlink ? 

2. If all of the directive information does not fit on the command line, type the following. 

wlink 

The prompt "WLINK>" will appear on the next line. You can enter as many lines of directive 
information as required. Press "Ctrl/Z" followed by the "Enter" key to terminate the input of 
directive information if you are running a DOS, ZDOS, OS/2 or Windows NT-hosted version of 
the Open Watcom Linker. Press "Ctrl/D" to terminate the input of directive information if you 
are running a UNIX-hosted version of the Open Watcom Linker. 

6.1 Memory Layout 

The following describes the segment ordering of an application linked by the Open Watcom Linker. Note 
that this assumes that the "DOSSEG" linker option has been specified. 

1. all segments not belonging to group "DGROUP" with class "CODE" 

2. all other segments not belonging to group "DGROUP" 

3. all segments belonging to group "DGROUP" with class "BEGDATA" 

4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

5. all segments belonging to group "DGROUP" with class "BSS" 
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6. all segments belonging to group "DGROUP" with class "STACK" 

A special segment belonging to class "BEGDATA" is defined when linking with Open Watcom run-time 
libraries. This segment is initialized with the hexadecimal byte pattern "01" and is the first segment in 
group "DGROUP" so that storing data at location 0 can be detected. 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 


6.2 The Open Watcom Linker Memory Requirements 

The Open Watcom Linker uses all available memory when linking an application. For DOS-hosted 
versions of the Open Watcom Linker, this includes expanded memory (EMS) and extended memory. It is 
possible for the size of the image being linked to exceed the amount of memory available in your machine, 
particularly if the image file is to contain debugging information. For this reason, a temporary disk file is 
used when all available memory is used by the Open Watcom Linker. 

Normally, the temporary file is created in the current working directory. However, by defining the "tmp" 
environment variable to be a directory, you can tell the Open Watcom Linker where to create the temporary 
file. This can be particularly useful if you have a RAM disk. Consider the following definition of the 
"tmp" environment variable. 

set tmp=\tmp 

The Open Watcom Linker will create the temporary file in the directory "\tmp". 

6.3 Converting Microsoft Response Files to Directive Files 

A utility called MS2WLINK can be used to convert Microsoft linker response files to Open Watcom Linker 
directive files. The response files must correspond to the linker found in version 7 or earlier of Microsoft 
C. Later versions of response files such as those used with Microsoft Visual C++ are not entirely 
supported. 

The same utility can also convert much of the content of IBM OS/2 LINK386 response files since the 
syntax is similar. 

Input to MS2WLINK is processed in the same way as the Microsoft linker processes its input. The 
difference is that MS2WLINK writes the corresponding Open Watcom Linker directive file to the standard 
output device instead of a creating an executable file. The resulting output can be redirected to a disk file 
which can then be used as input to the Open Watcom Linker to produce an executable file. 

Suppose you have a Microsoft linker response file called "test.rsp". You can convert this file to a Open 
Watcom Linker directive file by issuing the following command. 
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Example: 

ms2wlink Stest.rsp >test.lnk 

You can now use the Open Watcom Linker to link your program by issuing the following command. 


Example: 

wlink @test 


An alternative way to link your application with the Open Watcom Linker from a Microsoft response file is 
to issue the following command. 

Example: 

ms2wlink Stest.rsp | wlink 

Since the Open Watcom Linker gets its input from the standard input device, you do not have to create a 
Open Watcom Linker directive file to link your application. 

Note that MS2WLINK can also process module-definition files used for creating OS/2 applications. 
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7 The ELF Executable File Format 


This chapter deals specifically with aspects of ELF executable files. The ELF executable file format will 
only run under the operating systems that support the ELF executable file format. 

Input to the Open Watcom Linker is specified on the command line and can be redirected to one or more 
files or environment strings. The Open Watcom Linker command line format is as follows. 


WLINK {directive} 


where directive is any of the following: 

ALIAS alias_name=symbol_name{,alias_name=symbol_name} 
DEBUG dbtype [dblist] I DEBUG [dblist] 

DISABLE msg_num{,msg_nam} 

ENDLINK 

EXPORT entry_name {,entry_name} 

FILE obj_spec[,obj_spec} 

FORMAT ELF [DLL] 

IMPORT external jiame {,external jiame} 

LANGUAGE long 
LIBFILE obj_Jile{,obj Jile} 

LIBPATH pathjiame [;pathjiame} 

LIBRARY libraryJilef,libraryJile} 

MODFILE obj Jile{,obj Jile} 

MODTRACE objjnodule{,objjnodulej 
MODULE module jiame {, module jiame} 

NAME exe Jile 
OPTION option},option} 

ALIGNMENT=n 

ARTIFICIAL 

[NO {CACHE 

[NOjCASEEXACT 

CVPACK 

DOSSEG 

ELIMINATE 

[NO]FARC ALLS 

INCREMENTAL 

MANGLEDNAMES 

MAP[=map Jile] 

MAXERRORS=n 

NAMELEN=n 

NODEFAULTLIBS 

NOEXTENSION 
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OFFSET=n 
OSNAME= ’string ’ 

QUIET 

REDEFSOK 

SHOWDEAD 

STACK=n 

S TAR T^symboljiame 
STATICS 

SYMFILE[=symbolJile] 

[NOJUNDEFSOK 

VERBOSE 

VFREMOVAL 

OPTLIB library_Jile{,library_file} 

PATH path_name{;path_name} 

REFERENCE symboljiamef,symbol jiame} 

RUNTIME runjoption 

SORT [GLOBAL] [ALPHABETICAL] 

STARTLINK 

SYMTRACE symboljiamef,symboljiame} 

SYSTEM BEGIN system jiame {directive} END 
SYSTEM system jiame 
# comment 
@ directive_Jile 

You can view all the directives specific to ELF executable files by simply typing the following: 

wlink ? elf 
Notes: 

1. If the file "wlink.hlp" is located in one of the paths specified in the "PATH" environment 
variable, the contents of that file will be displayed when the following command is issued. 

wlink ? 

2. If all of the directive information does not fit on the command line, type the following. 

wlink 

The prompt "WLINK>" will appear on the next line. You can enter as many lines of directive 
information as required. Press "Ctrl/Z" followed by the "Enter" key to terminate the input of 
directive information if you are running a DOS, ZDOS, OS/2 or Windows NT-hosted version of 
the Open Watcom Linker. Press "Ctrl/D" to terminate the input of directive information if you 
are running a UNIX-hosted version of the Open Watcom Linker. 


7.1 Memory Layout 

The following describes the segment ordering of an application linked by the Open Watcom Linker. Note 
that this assumes that the "DOSSEG" linker option has been specified. 

1. all segments not belonging to group "DGROUP" with class "CODE" 

2. all other segments not belonging to group "DGROUP" 
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3. all segments belonging to group "DGROUP" with class "BEGDATA" 

4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

5. all segments belonging to group "DGROUP" with class "BSS" 

6. all segments belonging to group "DGROUP" with class "STACK" 

A special segment belonging to class "BEGDATA" is defined when linking with Open Watcom run-time 
libraries. This segment is initialized with the hexadecimal byte pattern "01" and is the first segment in 
group "DGROUP" so that storing data at location 0 can be detected. 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 
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8 The NetWare 0/S Executable File Format 


This chapter deals specifically with aspects of NetWare executable files. The Novell NetWare executable 
file format will only run under NetWare operating systems. 

Input to the Open Watcom Linker is specified on the command line and can be redirected to one or more 
files or environment strings. The Open Watcom Linker command line format is as follows. 


WLINK {directive} 


where directive is any of the following: 

ALIAS alias_name=symbol_name{,alias_name=symbol_name} 
AUTOUNLOAD 

DEBUG dbtype [dblist] I DEBUG [dblist] 

DISABLE msg_n um{,msg_nurn} 

ENDLINK 

EXPORT entry_name {,entry_name} 

FILE obj_spec{,obj_spec} 

FORMAT NOVELL [NLM I LAN I DSK I NAM I ’number’] ’description’ 
IMPORT external jiame {,external jiame} 

LANGUAGE long 
LIBFILE objJile{,objJile} 

LIBPATH pathjiame {;pathjiame} 

LIBRARY library_Jile{,library_file} 

MODTRACE objjnodule{,objjnodulej 
MODULE module jiame {,module jiame} 

NAME exe_Jile 
OPTION option},option} 

ARTIFICIAL 
[NO]CACHE 
[NO]CASEEXACT 
CHECK=symboljiame 
COPYRIGHT ’string’ 

CUSTOM-filejiame 
CVPACK 
DOSSEG 
ELIMINATE 
EXIT—symbolname 
[NO]FARCALLS 
HELP=help Jile 
IMPFILE[=imp Jile] 

IMPLIB[=imp_lib] 

MANGLEDNAMES 
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MAP[=map _Jile] 

MAXERRORS=n 

MESSAGES=msg Jile 

MULTILOAD 

NAMELEN=n 

NLMFLAGS=some_value 

NODEFAULTLIBS 

NOEXTENSION 

OSDOMAIN 

OSNAME= ’string ’ 

PSEUDOPREEMPTION 

QUIET 

REDEFSOK 

SHOWDEAD 

REENTRANT 

SCREENNAME ’name’ 

SHARELIB=shared_nlm 

STACK=n 

S TAR T=symbol_name 
STATICS 

SYMFILE[=symbolJile ] 

SYNCHRONIZE 
THREADNAME ’thread_name’ 

[NO]UNDEFSOK 

VERBOSE 

VERSION=major[.minor[.revision]] 

VFREMOVAL 
XDCDATA=rpc Jile 
OPTLIB library_Jile{, library_file} 

PATH path_name{;path_name} 

REFERENCE symbol_name{,symbol jiame} 

SORT [GLOBAL] [ALPHABETICAL] 

STARTLINK 

SYMTRACE symbol_name{,symboljiame] 

SYSTEM BEGIN system jiame {directive} END 
SYSTEM system_name 
# comment 
@ directive Jile 

You can view all the directives specific to NetWare executable files by simply typing the following: 

wlink ? nov 
Notes: 

1. If the file "wlink.hlp" is located in one of the paths specified in the "PATH" environment 
variable, the contents of that file will be displayed when the following command is issued. 

wlink ? 

2. If all of the directive information does not fit on the command line, type the following. 

wlink 
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The prompt "WLINK>" will appear on the next line. You can enter as many lines of directive 
information as required. Press "Ctrl/Z" followed by the "Enter" key to terminate the input of 
directive information if you are running a DOS, ZDOS, OS/2 or Windows NT-hosted version of 
the Open Watcom Linker. Press "Ctrl/D" to terminate the input of directive information if you 
are running a UNIX-hosted version of the Open Watcom Linker. 


8.1 NetWare Loadable Modules 

NetWare Loadable Modules (NLMs) are executable files that run in file server memory under the NetWare 
operating system. NLMs can be loaded and unloaded from file server memory while the server is running. 
When running they actually become part of the operating system thus acting as building blocks for a server 
environment tailored to your needs. 

There are multiple types of NLMs, each identified by the file extension of the executable file and the 
internal module type number. 

• Utility and server applications (executable files with extension "nlm"). 

• LAN drivers (executable files with extension "lan"). 

• Disk drivers (executable files with extension "dsk"). 

• Modules that define file system name spaces (executable files with extension "nam"). 

• Custom Device modules (executable files with extension "cdm"). 

• Host Adapter modules (executable files with extension "ham"). 

• Mirrored server link modules (executable files with extension "msl"). 

• Module types specified by number. These are the current defined values: 

0 Specifies a standard NLM (default extension .NLM) 

1 Specifies a disk driver module (default extension .DSK) 

2 Specifies a namespace driver module (default extension .NAM) 

3 Specifies a LAN driver module (default extension .LAN) 

4 Specifies a utility NLM (default extension .NLM) 

5 Specifies a Mirrored Server Link module (default .MSL) 

6 Specifies an Operating System module (default .NLM) 

7 Specifies a Page High OS module (default .NLM) 

8 Specifies a Host Adapter module (default .HAM) 

9 Specifies a Custom Device module (default .CDM) 
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10 Reserved for Novell usage 

11 Reserved for Novell usage 

12 Specifies a Ghost module (default .NLM) 

13 Specifies an SMP driver module (default .NLM) 

14 Specifies a NIOS module (default .NLM) 

15 Specifies a CIOS CAD type module (default .NLM) 

16 Specifies a CIOS CLS type module (default .NLM) 

21 Reserved for Novell NICI usage 

22 Reserved for Novell NICI usage 

23 Reserved for Novell NICI usage 

24 Reserved for Novell NICI usage 

25 Reserved for Novell NICI usage 

26 Reserved for Novell NICI usage 

27 Reserved for Novell NICI usage 

28 Reserved for Novell NICI usage 

The Open Watcom Linker can generate all types of NLMs by utilising the numerical value of the module 
type. 

8.2 Memory Layout 

The following describes the segment ordering of an application linked by the Open Watcom Linker. Note 
that this assumes that the "DOSSEG" linker option has been specified. 

1. all segments not belonging to group "DGROUP" with class "CODE" 

2. all other segments not belonging to group "DGROUP" 

3. all segments belonging to group "DGROUP" with class "BEGDATA" 

4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

5. all segments belonging to group "DGROUP" with class "BSS" 

6. all segments belonging to group "DGROUP" with class "STACK" 
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A special segment belonging to class "BEGDATA" is defined when linking with Open Watcom run-time 
libraries. This segment is initialized with the hexadecimal byte pattern "01" and is the first segment in 
group "DGROUP" so that storing data at location 0 can be detected. 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 
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9 The OS/2 Executable and DLL File Formats 


This chapter deals specifically with aspects of OS/2 executable files. The OS/2 16-bit executable file 
format will run under the following operating systems. 

1. 16-bit OS/2 1.x 

2. 32-bit OS/2 2.x, 3.x (Warp) and 4.x 

3. Phar Lap’s 286IDOS-Extender 

The OS/2 32-bit linear executable file format will run under the following operating systems. 

1. OS/2 2.x and later (LX format only) 

2. CauseWay DOS extender, Tenberry Software’s DOS/4G and DOS/4GW DOS extenders, and 
compatible products (LE format only) 

3. FlashTek’s DOS Extender (LX format only) 

Input to the Open Watcom Linker is specified on the command line and can be redirected to one or more 
files or environment strings. The Open Watcom Linker command line format is as follows. 


WLINK {directive} 


where directive is any of the following: 

ALIAS alias_name=symbol_name{,alias_name=symbol_name} 
DEBUG dbtype [dblist] I DEBUG [dblist] 

DISABLE msg_n um{,msg_nurn} 

ENDLINK 

EXPORT export},export} 

EXPORT =lbcjile 
FILE obj_spec{,obj_spec} 

FORMAT OS2 [exejype] [dllJorm I exe_attrs] 

IMPORT import},import} 

LANGUAGE long 
LIBFILE objJile{,objJile} 

LIBPATH path_name{;path_name} 

LIBRARY library_Jile{,library_file} 

MODFILE objJile{,objJile} 

MODTRACE obj module{,objjnodule} 

NAME exe _Jile 

NEWSEGMENT 

PATH path_name{;path_name} 

OPTION option},option} 
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ALIGNMENT=n 

ARTIFICIAL 

[NO]CACHE 

[NOJCASEEXACT 

CVPACK 

DESCRIPTION ’string’ 

DOSSEG 

ELIMINATE 

[NO]FARC ALLS 

HEAP SIZE=n 

IMPFILE[=imp Jile] 

IMPLIB[=imp_lib ] 

INCREMENTAL 

INTERNALRELOCS 

MANGLEDNAMES 

MANYAUTODATA 

MAP[=map Jile] 

MAXERRORS=n 

MIXED1632 

MODNAME=module_name 

NAMELEN=n 

NEWFILES 

NOAUTODATA 

NODEFAULTLIBS 

NOEXTENSION 

NOSTUB 

OFFSET 

OLDLIBRAR Y=dll_name 

ONEAUTODATA 

OSNAME= ’string ’ 

PACKCODE=n 

PACKDATA=n 

PROTMODE 

QUIET 

REDEFSOK 

RESOURCE=resource Jile 

SHOWDEAD 

STACK=n 

S TAR T=symbol_name 

STATICS 

S TUB=stub_name 

SYMFILE[=symbolJile ] 

TOGGLERELOCS 

[NO]UNDEFSOK 

VERBOSE 

VERSION=major[.minor] 

VFREMOVAL 

OPTLIB library Jile{,library Jile} 
REFERENCE symbol_name{,symbol jiame} 
SEGMENT seg_desc{,seg_desc} 

SORT [GLOBAL] [ALPHABETICAL] 
STARTLINK 
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SYMTRACE symbol_name{,.symboljiame} 

SYSTEM BEGIN system jiame {directive} END 
SYSTEM system jiame 
# comment 
@ directive_Jile 

You can view all the directives specific to OS/2 executable files by simply typing the following: 

wlink ? os2 
Notes: 

1. If the file "wlink.hlp" is located in one of the paths specified in the "PATH" environment 
variable, the contents of that file will be displayed when the following command is issued. 

wlink ? 

2. If all of the directive information does not fit on the command line, type the following. 

wlink 

The prompt "WLINK>" will appear on the next line. You can enter as many lines of directive 
information as required. Press "Ctrl/Z" followed by the "Enter" key to terminate the input of 
directive information if you are running a DOS, ZDOS, OS/2 or Windows NT-hosted version of 
the Open Watcom Linker. Press "Ctrl/D" to terminate the input of directive information if you 
are running a UNIX-hosted version of the Open Watcom Linker. 

9.1 Dynamic Link Libraries 

The Open Watcom Linker can generate two forms of executable files; program modules and Dynamic Link 
Libraries. A program module is the executable file that gets loaded by the operating system when you run 
your application. A Dynamic Link Library is really a library of routines that are called by a program 
module but not linked into the program module. The executable code in a Dynamic Link Library is loaded 
by the operating system during the execution of a program module when a routine in the Dynamic Link 
Library is called. 

Program modules are contained in files whose name has a file extension of "exe". Dynamic Link Libraries 
are contained in files whose name has a file extension of "dll". The Open Watcom Linker "LORMAT" 
directive can be used to select the type of executable file to be generated. 

Let us consider some of the advantages of using Dynamic Link Libraries over standard libraries. 

1. Functions in Dynamic Link Libraries are not linked into your program. Only references to the 
functions in Dynamic Link Libraries are placed in the program module. These references are 
called import definitions. As a result, the linking time is reduced and disk space is saved. If 
many applications reference the same Dynamic Link Library, the saving in disk space can be 
significant. 

2. Since program modules only reference Dynamic Link Libraries and do not contain the actual 
executable code, a Dynamic Link Library can be updated without re-linking your application. 
When your application is executed, it will use the updated version of the Dynamic Link Library. 
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3. Dynamic Link Libraries also allow sharing of code and data between the applications that use 
them. If many applications that use the same Dynamic Link Library are executing concurrently, 
the sharing of code and data segments improves memory utilization. 

9.1.1 Creating a Dynamic Link Library 

To create a Dynamic Link Library, you must place the "DLL" keyword following the system name in the 
"SYSTEM" directive. 

system os2v2_ dll 

In addition, you must specify which functions in the Dynamic Link Library are to be made available to 
applications which use it. This is achieved by using the "EXPORT" directive for each function that can be 
called by an application. 

Dynamic Link Libraries can reference other Dynamic Link Libraries. References to other Dynamic Link 
Libraries are resolved by specifying "IMPORT" directives or using import libraries. 

9.1.2 Using a Dynamic Link Library 

To use a Dynamic Link Library, you must tell the Open Watcom Linker which functions are contained in a 
Dynamic Link Library and the name of the Dynamic Link Library. This is achieved in two ways. 

The first method is to use the "IMPORT" directive. The "IMPORT" directive names the function and the 
Dynamic Link Library it belongs to so that the Open Watcom Linker can generate an import definition in 
the program module. 

The second method is to use import libraries. An import library is a standard library which contains object 
modules with special object records that define the functions belonging to a Dynamic Link Library. An 
import library is created from a Dynamic Link Library using the Open Watcom Library Manager. The 
resulting import library can then be specified in a "LIBRARY" directive in the same way one would specify 
a standard library. See the chapter entitled "The Open Watcom Library Manager" in the Open Watcom 
C/C++ Tools User’s Guide or the Open Watcom FORTRAN 77 Tools User’s Guide for more information 
on creating import libraries. 

Using an import library is the preferred method of providing references to functions in Dynamic Link 
Libraries. When a Dynamic Link Library is modified, typically the import library corresponding to the 
modified Dynamic Link Library is updated to reflect the changes. Hence, any directive file that specifies 
the import library in a "LIBRARY" directive need not be modified. However, if you are using "IMPORT" 
directives, you may have to modify the "IMPORT" directives to reflect the changes in the Dynamic Link 
Library. 

9.2 Memory Layout 

The following describes the segment ordering of an application linked by the Open Watcom Linker. Note 
that this assumes that the "DOSSEG" linker option has been specified. 

1. all segments not belonging to group "DGROUP" with class "CODE" 

2. all other segments not belonging to group "DGROUP" 
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3. all segments belonging to group "DGROUP" with class "BEGDATA" 

4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

5. all segments belonging to group "DGROUP" with class "BSS" 

6. all segments belonging to group "DGROUP" with class "STACK" 

A special segment belonging to class "BEGDATA" is defined when linking with Open Watcom run-time 
libraries. This segment is initialized with the hexadecimal byte pattern "01" and is the first segment in 
group "DGROUP" so that storing data at location 0 can be detected. 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 


9.3 Converting Microsoft Response Files to Directive Files 

A utility called MS2WLINK can be used to convert Microsoft linker response files to Open Watcom Linker 
directive files. The response files must correspond to the linker found in version 7 or earlier of Microsoft 
C. Later versions of response files such as those used with Microsoft Visual C++ are not entirely 
supported. 

The same utility can also convert much of the content of IBM OS/2 LINK386 response files since the 
syntax is similar. 

Input to MS2WLINK is processed in the same way as the Microsoft linker processes its input. The 
difference is that MS2WLINK writes the corresponding Open Watcom Linker directive file to the standard 
output device instead of a creating an executable file. The resulting output can be redirected to a disk file 
which can then be used as input to the Open Watcom Linker to produce an executable file. 

Suppose you have a Microsoft linker response file called "test.rsp". You can convert this file to a Open 
Watcom Linker directive file by issuing the following command. 

Example: 

ms2wlink Stest.rsp >test.lnk 

You can now use the Open Watcom Linker to link your program by issuing the following command. 

Example: 

wlink @test 

An alternative way to link your application with the Open Watcom Linker from a Microsoft response file is 
to issue the following command. 
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Example: 

ms2wlink Stest.rsp | wlink 

Since the Open Watcom Linker gets its input from the standard input device, you do not have to create a 
Open Watcom Linker directive file to link your application. 

Note that MS2WLINK can also process module-definition files used for creating OS/2 applications. 
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10 The Phar Lap Executable File Format 


This chapter deals specifically with aspects of Phar Lap 386IDOS-Extender executable files. The Phar Lap 
executable file format will run under the following operating systems. 

1. Phar Lap's 386IDOS-Extender 

2. Open Watcom’s 32-bit Windows supervisor (relocatable format only) 

Input to the Open Watcom Linker is specified on the command line and can be redirected to one or more 
files or environment strings. The Open Watcom Linker command line format is as follows. 


WLINK {directive} 


where directive is any of the following: 


ALIAS alias_name=symbol_name{,alias_name=symbol_name} 
DEBUG dbtype [dblist] I DEBUG [dblist] 

DISABLE msg_num{,msg_num} 

ENDLINK 

FILE obj_spec{,obj_spec} 

FORMAT PHARLAP [EXTENDED I REX I SEGMENTED] 
LANGUAGE lang 
LIBFILE objJile{,objJile} 

LIBPATH path_name{;path_name} 

LIBRARY library_Jile{,library_file} 

MODFILE objJile{,objJile} 

MODTRACE obj_module{,obj_module} 

NAME exe _Jile 
OPTION option),option} 

ARTIFICIAL 

[NO]CACHE 

[ NO ICA S E EX ACT 

CVPACK 

DOSSEG 

ELIMINATE 

[NO]FARC ALLS 

INCREMENTAL 

MANGLEDNAMES 

MAP[=map _Jile] 

MAXDATA=n 

MAXERRORS=n 

MINDATA=n 

NAMELEN=n 

NODEFAULTLIBS 
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NOEXTENSION 
OFFSET=n 
OSNAME= ’string ’ 

QUIET 

REDEFSOK 

SHOWDEAD 

STACK=n 

S TAR T^symboljiame 
STATICS 

SYMFILE[=symbolJile] 

[NO]UNDEFSOK 

VERBOSE 

VFREMOVAL 

OPTLIB library_Jile{,library_Jile} 

PATH path_name{;path_name} 

REFERENCE symboljiamef,symbol jiame} 

RUNTIME run_option{,run_option} 

SORT [GLOBAL] [ALPHABETICAL] 

STARTLINK 

SYMTRACE symbol_name{,symboljiame} 

SYSTEM BEGIN system jiame {directive} END 
SYSTEM system_name 
# comment 
@ directive_Jile 

You can view all the directives specific to Phar Lap 386IDOS-Extender executable files by simply typing 
the following: 

wlink ? phar 

Notes: 

1. If the file "wlink.hlp" is located in one of the paths specified in the "PATH" environment 
variable, the contents of that file will be displayed when the following command is issued. 

wlink ? 

2. If all of the directive information does not fit on the command line, type the following. 

wlink 

The prompt "WLINK>" will appear on the next line. You can enter as many lines of directive 
information as required. Press "Ctrl/Z" followed by the "Enter" key to terminate the input of 
directive information if you are running a DOS, ZDOS, OS/2 or Windows NT-hosted version of 
the Open Watcom Linker. Press "Ctrl/D" to terminate the input of directive information if you 
are running a UNIX-hosted version of the Open Watcom Linker. 
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10.132-bit Protected-Mode Applications 

The Open Watcom Linker generates executable files that run under Phar Lap’s 386IDOS-Extender. 
386IDOS-Extender provides a 32-bit protected-mode environment for programs running under PC DOS. 
Running in 32-bit protected mode allows your program to access all of the memory in your machine. 

Essentially, what 386!DOS-Extender does is provide an interface between your application and DOS 
running in real mode. Whenever your program issues a software interrupt (DOS and BIOS system calls), 
386IDOS-Extender intercepts the requests, transfers data between the protected-mode and real-mode 
address space, and calls the corresponding DOS system function running in real mode. 


10.2 Memory Usage 

When running a program under 386IDOS-Extender, memory for the program is allocated from 
conventional memory (memory below one megabyte) and extended memory. Conventional memory is 
allocated from a block of memory that is obtained from DOS by 386IDOS-Extender at initialization time. 
By default, all available memory is allocated at initialization time; no conventional memory remains free. 
The "MINREAL" and "MAXREAL" options of the "RUNTIME" directive control the amount of 
conventional memory initially left free by 386IDOS-Extender. 

Part of the conventional memory allocated at initialization is required by 386IDOS-Extender. The 
following is allocated from conventional memory for use by 386IDOS-Extender. 

1. A data buffer is allocated and is used to pass data to DOS and BIOS system functions. The size 
allocated is controlled by the "MINIBUF" and "MAXIBUF" options of the "RUNTIME" 
directive. 

2. Stack space is allocated and is used for switching between 32-bit protected mode and real mode. 
The size allocated is controlled by the "NISTACK" and "ISTKSIZE" options of the 
"RUNTIME" directive. 

3. A call buffer is allocated and is used for passing data on function calls between 32-bit protected 
mode and real mode. The size allocated is controlled by the "CALLBUFS" option of the 
"RUNTIME" directive. 

When a program is loaded by 386IDOS-Extender, memory to hold the entire program is allocated. In 
addition, memory beyond the end of the program is allocated for use by the program. By default, all extra 
memory is allocated when the program is loaded. It is assumed that any memory not required by the 
program is freed by the program. The amount of memory allocated at the end of the program is controlled 
by the "MINDATA" and "MAXDATA" options. 

10.3 Memory Layout 

The following describes the segment ordering of an application linked by the Open Watcom Linker. Note 
that this assumes that the "DOSSEG" linker option has been specified. 

1. all "USE16" segments. These segments are present in applications that execute in both real 
mode and protected mode. They are first in the segment ordering so that the "REALBREAK" 
option of the "RUNTIME" directive can be used to separate the real-mode part of the application 
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from the protected-mode part of the application. Currently, the "RUNTIME" directive is valid 
for Phar Lap executables only. 

2. all segments not belonging to group "DGROUP" with class "CODE" 

3. all other segments not belonging to group "DGROUP" 

4. all segments belonging to group "DGROUP" with class "BEGDATA" 

5. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

6. all segments belonging to group "DGROUP" with class "BSS" 

7. all segments belonging to group "DGROUP" with class "STACK" 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 


10.4 The Open Watcom Linker Memory Requirements 

The Open Watcom Linker uses all available memory when linking an application. For DOS-hosted 
versions of the Open Watcom Linker, this includes expanded memory (EMS) and extended memory. It is 
possible for the size of the image being linked to exceed the amount of memory available in your machine, 
particularly if the image file is to contain debugging information. For this reason, a temporary disk file is 
used when all available memory is used by the Open Watcom Linker. 

Normally, the temporary file is created in the current working directory. However, by defining the "tmp" 
environment variable to be a directory, you can tell the Open Watcom Linker where to create the temporary 
file. This can be particularly useful if you have a RAM disk. Consider the following definition of the 
"tmp" environment variable. 

set tmp=\tmp 

The Open Watcom Linker will create the temporary file in the directory "\tmp". 
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11 The QNX Executable File Format 


This chapter deals specifically with aspects of QNX executable files. The QNX executable file format will 
only run under the QNX operating system. 

Input to the Open Watcom Linker is specified on the command line and can be redirected to one or more 
files or environment strings. The Open Watcom Linker command line format is as follows. 


wlink {directive} 


where directive is any of the following: 


ALIAS symbol_name=symboljiame{,symboljiame=symbol_name} 
DEBUG dbtype [dblist] I DEBUG [dblist] 

DISABLE msg_num{,msg_num} 

ENDLINK 

FILE obj_spec[,obj_spec} 

FORMAT QNX [FLAT] 

LANGUAGE 

LIBFILE obj Jile{,obj Jile} 

LIBPATH path _name{:path _name} 

LIBRARY library_Jile{,library_file} 

MODFILE obj Jile{,obj Jile} 

MODTRACE obj_spec[,obj_spec} 

NAME exe _file 
NEWSEGMENT 
OPTION option},option} 

ARTIFICIAL 

[NO]CACHE 

[ NO ICA S E EX ACT 

CVPACK 

DOSSEG 

ELIMINATE 

[NO]FARC ALLS 

HEAP SIZE=n 

INCREMENTAL 

LINEARRELOCS 

LONGLIVED 

MANGLEDNAMES 

MAP[=map _Jile] 

MAXERRORS=n 

NAMELEN=n 

NODEFAULTLIBS 

NOEXTENSION 


The QNX Executable File Format 225 





The Open Watcom Linker 


NORELOCS 
OFFSET=n 
OSNAME= ’string ’ 

PACKCODE=n 

PACKDATA=n 

PRIVILEGED 

QUIET 

REDEFSOK 

RESOURCE[=resource_file I ’string’] 

SHOWDEAD 

STACK=n 

S TAR T=symboljiame 
STATICS 

SYMFILE[=symbolJile ] 

[NO]UNDEFSOK 

VERBOSE 

VFREMOVAL 

OPTLIB library_Jile{,library_file] 

PATH path_name{:path_name] 

REFERENCE symbol_name{,symbol jiame] 

SEGMENT seg_desc{,seg_desc] 

SORT [GLOBAL] [ALPHABETICAL] 

STARTLINK 

SYMTRACE symbol_name{,symboljiame] 

SYSTEM BEGIN system jiame {directive} END 
SYSTEM system jiame 
# comment 
@ directive_Jile 

You can view all the directives specific to QNX executable files by simply typing the following: 

wlink ? qnx 
Notes: 

1. If the file /etc/wlink. hip exists, the contents of that file will be displayed when the 
following command is issued. 

wlink ? 

2. If all of the directive information does not fit on the command line, type the following. 

wlink 

The prompt "WLINK>" will appear on the next line. You can enter as many lines of directive 
information as required. Press "Ctrl/Z" followed by the "Enter" key to terminate the input of 
directive information if you are running a DOS, ZDOS, OS/2 or Windows NT-hosted version of 
the Open Watcom Linker. Press "Ctrl/D" to terminate the input of directive information if you 
are running a UNIX-hosted version of the Open Watcom Linker. 
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11.1 Memory Layout 

The following describes the segment ordering of an application linked by the Open Watcom Linker. Note 
that this assumes that the "DOSSEG" linker option has been specified. 

1. all segments not belonging to group "DGROUP" with class "CODE" 

2. all other segments not belonging to group "DGROUP" 

3. all segments belonging to group "DGROUP" with class "BEGDATA" 

4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

5. all segments belonging to group "DGROUP" with class "BSS" 

6. all segments belonging to group "DGROUP" with class "STACK" 

A special segment belonging to class "BEGDATA" is defined when linking with Open Watcom run-time 
libraries. This segment is initialized with the hexadecimal byte pattern "01" and is the first segment in 
group "DGROUP" so that storing data at location 0 can be detected. 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 


Memory Layout 227 




The Open Watcom Linker 


228 Memory Layout 




12 The Win16 Executable and DLL File Formats 


This chapter deals specifically with aspects of Win 16 executable files. The Win 16 executable file format 
will run under Windows 3.x, Windows 95, and Windows NT. 

Input to the Open Watcom Linker is specified on the command line and can be redirected to one or more 
files or environment strings. The Open Watcom Linker command line format is as follows. 


WLINK {directive} 


where directive is any of the following: 

ALIAS alias_name=symbol_name{,alias _name=symbol_name} 
ANONYMOUSEXPORT export},export} I =lbc Jile 
DEBUG dbtype [dblist] I DEBUG [dblist] 

DISABLE msg_num{,msg_nurn} 

ENDLINK 

EXPORT export},export} 

EXPORT =lbcjile 
FILE obj_spec{,obj_spec} 

FORMAT WINDOWS [dll Jorm] [MEMORY] [FONT] 
IMPORT import],import} 

LANGUAGE long 
LIBFILE objJile[,objJile} 

LIBPATH path_name[;path_name} 

LIBRARY library_Jile{,library_file} 

MODFILE objJile[,objJile} 

MODTRACE obj module[,obj module} 

NAME exejile 

NEWSEGMENT 

PATH path_name[;path_name} 

OPTION option{,option} 

ALIGNMENT=n 
ARTIFICIAL 
[NO/CACHE 
[NO]CASEEXACT 
CVPACK 

DESCRIPTION ’string’ 

DOSSEG 
ELIMINATE 
[NO]FARC ALLS 
HEAP SIZE =n 
IMPFILE[=imp Jile] 

IMPLIB[=imp Jib] 


The Win 16 Executable and DLL File Formats 229 





The Open Watcom Linker 


INCREMENTAL 
MANGLEDNAMES 
MANYAUTODATA 
MAP[=map _Jile[ 

MAXERRORS=n 

MODNA ME=modulename 

NAMELEN=n 

NOAUTODATA 

NODEFAULTLIBS 

NOEXTENSION 

NOSTUB 

OLDLIBRAR Y=dllname 
ONEAUTODATA 
OSNAME= ’string ’ 

PACKCODE=n 

PACKDATA=n 

QUIET 

REDEFSOK 

RESOURCE=resource _Jile 
RWRELOCCHECK 
SHOWDEAD 
STACK=n 

S TAR T=symbol_name 
STATICS 
S TUB-stub jiame 
SYMFILE[=symbolJile] 

[NO]UNDEFSOK 

VERBOSE 

VERSION=major[.minor] 

VFREMOVAL 

OPTLIB library_file{,library_file} 

REFERENCE symboljiamef,symbol jiame} 

SEGMENT seg_desc{,seg_desc} 

SORT [GLOBAL] [ALPHABETICAL] 

STARTLINK 

SYMTRACE symboljiamef,symboljiame} 

SYSTEM BEGIN system jiame {directive} END 
SYSTEM system_name 
# comment 
@ directive_Jile 

You can view all the directives specific to Winl6 executable files by simply typing the following: 

wlink ? win 
Notes: 

1. If the file "wlink.hlp" is located in one of the paths specified in the "PATH" environment 
variable, the contents of that file will be displayed when the following command is issued. 

wlink ? 

2. If all of the directive information does not fit on the command line, type the following. 
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wlink 

The prompt "WLINK>" will appear on the next line. You can enter as many lines of directive 
information as required. Press "Ctrl/Z" followed by the "Enter" key to terminate the input of 
directive information if you are running a DOS, ZDOS, OS/2 or Windows NT-hosted version of 
the Open Watcom Linker. Press "Ctrl/D" to terminate the input of directive information if you 
are running a UNIX-hosted version of the Open Watcom Linker. 

12.1 Fixed and Moveable Segments 

All segments have attributes that tell Windows how to manage the segment. One of these attributes 
specifies whether the segment is fixed or moveable. Moveable segments can be moved in memory to 
satisfy other memory requests. When a segment is moved, all near pointers to that segment are still valid 
since a near pointer references memory relative to the start of the segment. However, far pointers are no 
longer valid once a segment has been moved. Fixed segments, on the other hand, cannot be moved in 
memory. A segment must be fixed if there exists far pointers to that segment that Windows cannot adjust if 
that segment were moved. 

This is a memory-management issue for real-mode Windows only. However, if a DLL is marked as 
"fixed", Windows 3.x will place it in the lower 640K real-mode memory (regardless of the mode in which 
Windows 3.x is running). Since the lower 640K is a limited resource, you normally would want a DLL to 
be marked as "moveable". 

Most segments, including code and data segments, are moveable. Some exceptions exist. If your program 
contains a far pointer, the segment which it references must be fixed. If it were moveable, the segment 
address portion of the far pointer would be invalid when Windows moved the segment. 

All non-Windows programs are assigned fixed segments when they run under Windows. These segments 
must be fixed since there is no information in the executable file that describes how segments are 
referenced. Whenever possible, your application should consist of moveable segments since fixed 
segments can cause memory management problems. 

12.2 Discardable Segments 

Moveable segments can also be discardable. Memory allocated to a discardable segment can be freed and 
used for other memory requests. A "least recently used" (LRU) algorithm is used to determine which 
segment to discard when more memory is required. 

Discardable segments are usually segments that do not change once they are loaded into memory. For 
example, code segments are discardable since programs do not usually modify their code segments. When 
a segment is discarded, it can be reloaded into memory by accessing the executable file. 

Discardable segments must be moveable since they can be reloaded into a different area in memory than the 
area they previously occupied. Note that moveable segments need not be discardable. Obviously, data 
segments that contain read/write data cannot be discarded. 
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12.3 Dynamic Link Libraries 

The Open Watcom Linker can generate two forms of executable files; program modules and Dynamic Link 
Libraries. A program module is the executable file that gets loaded by the operating system when you run 
your application. A Dynamic Link Library is really a library of routines that are called by a program 
module but not linked into the program module. The executable code in a Dynamic Link Library is loaded 
by the operating system during the execution of a program module when a routine in the Dynamic Link 
Library is called. 

Program modules are contained in files whose name has a file extension of "exe". Dynamic Link Libraries 
are contained in files whose name has a file extension of "dll". The Open Watcom Linker "FORMAT" 
directive can be used to select the type of executable file to be generated. 

Let us consider some of the advantages of using Dynamic Link Libraries over standard libraries. 

1. Functions in Dynamic Link Libraries are not linked into your program. Only references to the 
functions in Dynamic Link Libraries are placed in the program module. These references are 
called import definitions. As a result, the linking time is reduced and disk space is saved. If 
many applications reference the same Dynamic Link Library, the saving in disk space can be 
significant. 

2. Since program modules only reference Dynamic Link Libraries and do not contain the actual 
executable code, a Dynamic Link Library can be updated without re-linking your application. 
When your application is executed, it will use the updated version of the Dynamic Link Library. 

3. Dynamic Link Libraries also allow sharing of code and data between the applications that use 
them. If many applications that use the same Dynamic Link Library are executing concurrently, 
the sharing of code and data segments improves memory utilization. 

12.3.1 Creating a Dynamic Link Library 

To create a Dynamic Link Library, you must place the "DLL" keyword following the system name in the 
"SYSTEM" directive. 

system windows_ dll 

In addition, you must specify which functions in the Dynamic Link Library are to be made available to 
applications which use it. This is achieved by using the "EXPORT" directive for each function that can be 
called by an application. 

Dynamic Link Libraries can reference other Dynamic Link Libraries. References to other Dynamic Link 
Libraries are resolved by specifying "IMPORT" directives or using import libraries. 

12.3.2 Using a Dynamic Link Library 

To use a Dynamic Link Library, you must tell the Open Watcom Linker which functions are contained in a 
Dynamic Link Library and the name of the Dynamic Link Library. This is achieved in two ways. 

The first method is to use the "IMPORT" directive. The "IMPORT" directive names the function and the 
Dynamic Link Library it belongs to so that the Open Watcom Linker can generate an import definition in 
the program module. 
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The second method is to use import libraries. An import library is a standard library which contains object 
modules with special object records that define the functions belonging to a Dynamic Link Library. An 
import library is created from a Dynamic Link Library using the Open Watcom Library Manager. The 
resulting import library can then be specified in a "LIBRARY" directive in the same way one would specify 
a standard library. See the chapter entitled "The Open Watcom Library Manager" in the Open Watcom 
C/C++ Tools User’s Guide or the Open Watcom FORTRAN 77 Tools User’s Guide for more information 
on creating import libraries. 

Using an import library is the preferred method of providing references to functions in Dynamic Link 
Libraries. When a Dynamic Link Library is modified, typically the import library corresponding to the 
modified Dynamic Link Library is updated to reflect the changes. Hence, any directive file that specifies 
the import library in a "LIBRARY" directive need not be modified. However, if you are using "IMPORT" 
directives, you may have to modify the "IMPORT" directives to reflect the changes in the Dynamic Link 
Library. 

12.4 Memory Layout 

The following describes the segment ordering of an application linked by the Open Watcom Linker. Note 
that this assumes that the "DOSSEG" linker option has been specified. 

1. all segments not belonging to group "DGROUP" with class "CODE" 

2. all other segments not belonging to group "DGROUP" 

3. all segments belonging to group "DGROUP" with class "BEGDATA" 

4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

5. all segments belonging to group "DGROUP" with class "BSS" 

6. all segments belonging to group "DGROUP" with class "STACK" 

A special segment belonging to class "BEGDATA" is defined when linking with Open Watcom run-time 
libraries. This segment is initialized with the hexadecimal byte pattern "01" and is the first segment in 
group "DGROUP" so that storing data at location 0 can be detected. 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 


12.5 Converting Microsoft Response Files to Directive Files 

A utility called MS2WLINK can be used to convert Microsoft linker response files to Open Watcom Linker 
directive files. The response files must correspond to the linker found in version 7 or earlier of Microsoft 
C. Later versions of response files such as those used with Microsoft Visual C++ are not entirely 
supported. 


The same utility can also convert much of the content of IBM OS/2 LINK386 response files since the 
syntax is similar. 
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Input to MS2WLINK is processed in the same way as the Microsoft linker processes its input. The 
difference is that MS2WLINK writes the corresponding Open Watcom Linker directive file to the standard 
output device instead of a creating an executable file. The resulting output can be redirected to a disk file 
which can then be used as input to the Open Watcom Linker to produce an executable file. 

Suppose you have a Microsoft linker response file called "test.rsp". You can convert this file to a Open 
Watcom Linker directive file by issuing the following command. 

Example: 

ms2wlink Stest.rsp >test.lnk 

You can now use the Open Watcom Linker to link your program by issuing the following command. 

Example: 

wlink @test 

An alternative way to link your application with the Open Watcom Linker from a Microsoft response file is 
to issue the following command. 

Example: 

ms2wlink Stest.rsp | wlink 

Since the Open Watcom Linker gets its input from the standard input device, you do not have to create a 
Open Watcom Linker directive file to link your application. 

Note that MS2WLINK can also process module-definition files used for creating OS/2 applications. 
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This chapter deals specifically with aspects of WinVxD executable files. 

Input to the Open Watcom Linker is specified on the command line and can be redirected to one or more 
files or environment strings. The Open Watcom Linker command line format is as follows. 


WLINK {directive} 


where directive is any of the following: 

ALIAS alias_name=symbol_name{,alias _name=symbol_name} 
DISABLE msg_num{,msg_num} 

ENDLINK 

EXPORT export},export} 

EXPORT =lbc Jile 
FILE obj_spec{,obj_spec} 

FORMAT WINDOWS VXD [DYNAMIC] 

LANGUAGE lang 
LIBFILE objJile{,objJile} 

LIBPATH path_name{;path_name} 

LIBRARY library_Jile{,library_file} 

MODFILE objJile{,objJile} 

MODTRACE obj module{,obj module} 

NAME exe_Jile 

PATH path_name{;path_name} 

OPTION option},option} 

ALIGNMENT=n 
ARTIFICIAL 
[NOJCACHE 
[NOJCASEEXACT 
DESCRIPTION ’string’ 

ELIMINATE 
[NO]FARC ALLS 
HEAP SIZE=n 
IMPFILE[=impJile] 

IMPLIB}=imp Jib] 

INCREMENTAL 
MANGLEDNAMES 
MAP[=map _file] 

MAXERRORS=n 

MODNAME=module_name 

NAMELEN=n 

NODEFAULTLIBS 
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NOEXTENSION 
NOSTUB 
OSNAME=’string’ 

QUIET 

REDEFSOK 

RESOURCE=resource _Jile 

SHOWDEAD 

STACK=n 

S TAR T=symboljiame 
STATICS 
S TUB=stub_name 
SYMFILE[=symbolJile] 

[NO]UNDEFSOK 

VERBOSE 

VERSION=major[.minor] 

VFREMOVAL 

OPTLIB library_Jile{,library_file} 

REFERENCE symboljiame],,symbol jiame} 

SEGMENT seg_desc{,seg_desc} 

SORT [GLOBAL] [ALPHABETICAL] 

STARTLINK 

SYMTRACE symboljiame],,symboljiame] 

SYSTEM BEGIN system jiame [directive] END 
SYSTEM system jiame 
# comment 
@ directive_Jile 

You can view all the directives specific to WinVxD executable files by simply typing the following: 

wlink ? win vxd 
Notes: 

1. If the file "wlink.hlp" is located in one of the paths specified in the "PATH" environment 
variable, the contents of that file will be displayed when the following command is issued. 

wlink ? 

2. If all of the directive information does not fit on the command line, type the following. 

wlink 

The prompt "WLINK>" will appear on the next line. You can enter as many lines of directive 
information as required. Press "Ctrl/Z" followed by the "Enter" key to terminate the input of 
directive information if you are running a DOS, ZDOS, OS/2 or Windows NT-hosted version of 
the Open Watcom Linker. Press "Ctrl/D" to terminate the input of directive information if you 
are running a UNIX-hosted version of the Open Watcom Linker. 
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13.1 Memory Layout 

The following describes the segment ordering of an application linked by the Open Watcom Linker. Note 
that this assumes that the "DOSSEG" linker option has been specified. 

1. all segments not belonging to group "DGROUP" with class "CODE" 

2. all other segments not belonging to group "DGROUP" 

3. all segments belonging to group "DGROUP" with class "BEGDATA" 

4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

5. all segments belonging to group "DGROUP" with class "BSS" 

6. all segments belonging to group "DGROUP" with class "STACK" 

A special segment belonging to class "BEGDATA" is defined when linking with Open Watcom run-time 
libraries. This segment is initialized with the hexadecimal byte pattern "01" and is the first segment in 
group "DGROUP" so that storing data at location 0 can be detected. 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 
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14 The Win32 Executable and DLL File Formats 


This chapter deals specifically with aspects of Win32 executable files. The Win32 executable file format 
will run under Windows 95, Windows NT, Phar Lap’s TNT DOS extender and RDOS. It may also run 
under Windows 3.x using the Win32s subsystem (you are restricted to a subset of the Win32 API). 

Input to the Open Watcom Linker is specified on the command line and can be redirected to one or more 
files or environment strings. The Open Watcom Linker command line format is as follows. 


WLINK {directive} 


where directive is any of the following: 

ALIAS alias_name=symbol_name{,alias_name=symbol_name} 
ANONYMOUSEXPORT export{,export} I =lbc Jile 
COMMIT memjype 
DEBUG dbtype [dblist] I DEBUG [dblist] 

DISABLE msg_num{,msg_n um} 

ENDLINK 

EXPORT export},export} 

EXPORT =lbcjile 
FILE obj_spec{,obj_spec} 

FORMAT WINDOWS NT [TNT I RDOS] [dlljorm] 

IMPORT import},import} 

LANGUAGE lang 
LIBFILE objJile{,objJile} 

LIBPATH path_name{;path_name} 

LIBRARY library_Jile{,library_file} 

MODFILE objJile{,objJile} 

MODTRACE obj_module{,obj jnodule} 

NAME exejile 

PATH path_name{;path_name} 

OPTION option},option} 

ALIGNMENT=n 

ARTIFICIAL 

[NO/CACHE 

[NOJCASEEXACT 

CHECKSUM 

CVPACK 

DESCRIPTION ’string’ 

DOSSEG 
ELIMINATE 
[NO]FARC ALLS 
HEAP SIZE=n 
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IMPFILE[=imp Jile] 

IMPLIB[=imp_lib ] 

INCREMENTAL 

LINKVERSION=major[.minor] 

MANGLEDNAMES 
MAP[=map Jile] 

MAXERRORS=n 

MODNA ME=modulename 

NAMELEN=n 

NODEFAULTLIBS 

NOEXTENSION 

NORELOCS 

NOSTDCALL 

NOSTUB 

OBJALIGN=n 

OFFSET 

OLDLIBRAR Y=dllname 
OSNAME= ’string ’ 

OSVERSION=major[. minor] 

QUIET 

REDEFSOK 

RESOURCE=resource Jile 

SHOWDEAD 

STACK=n 

S TAR T=symbol_name 
STATICS 
S TUB=stub_name 
SYMFILE[=symbolJile] 

[NO]UNDEFSOK 

VERBOSE 

VERSION=major[.minor] 

VFREMOVAL 

OPTLIB library Jile{,library Jile} 

REFERENCE symbol_name{,symbol jiame} 

RUNTIME runjoption 
SEGMENT seg_desc{,seg_desc} 

SORT [GLOBAL] [ALPHABETICAL] 

STARTLINK 

SYMTRACE symbol_name{,symboljiame} 

SYSTEM BEGIN system jiame {directive} END 
SYSTEM system_name 
# comment 
@ directive Jile 

You can view all the directives specific to Win32 executable files by simply typing the following: 

wlink ? nt 
Notes: 

1. If the file "wlink.hlp" is located in one of the paths specified in the "PATH" environment 
variable, the contents of that file will be displayed when the following command is issued. 

wlink ? 
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2. If all of the directive information does not fit on the command line, type the following, 
wlink 

The prompt "WLINK>" will appear on the next line. You can enter as many lines of directive 
information as required. Press "Ctrl/Z" followed by the "Enter" key to terminate the input of 
directive information if you are running a DOS, ZDOS, OS/2 or Windows NT-hosted version of 
the Open Watcom Linker. Press "Ctrl/D" to terminate the input of directive information if you 
are running a UNIX-hosted version of the Open Watcom Linker. 

14.1 Dynamic Link Libraries 

The Open Watcom Linker can generate two forms of executable files; program modules and Dynamic Link 
Libraries. A program module is the executable file that gets loaded by the operating system when you run 
your application. A Dynamic Link Library is really a library of routines that are called by a program 
module but not linked into the program module. The executable code in a Dynamic Link Library is loaded 
by the operating system during the execution of a program module when a routine in the Dynamic Link 
Library is called. 

Program modules are contained in files whose name has a file extension of "exe". Dynamic Link Libraries 
are contained in files whose name has a file extension of "dll". The Open Watcom Linker "LORMAT" 
directive can be used to select the type of executable file to be generated. 

Let us consider some of the advantages of using Dynamic Link Libraries over standard libraries. 

1. Lunctions in Dynamic Link Libraries are not linked into your program. Only references to the 
functions in Dynamic Link Libraries are placed in the program module. These references are 
called import definitions. As a result, the linking time is reduced and disk space is saved. If 
many applications reference the same Dynamic Link Library, the saving in disk space can be 
significant. 

2. Since program modules only reference Dynamic Link Libraries and do not contain the actual 
executable code, a Dynamic Link Library can be updated without re-linking your application. 
When your application is executed, it will use the updated version of the Dynamic Link Library. 

3. Dynamic Link Libraries also allow sharing of code and data between the applications that use 
them. If many applications that use the same Dynamic Link Library are executing concurrently, 
the sharing of code and data segments improves memory utilization. 

14.1.1 Creating a Dynamic Link Library 

To create a Dynamic Link Library, you must place the "DLL" keyword following the system name in the 
"SYSTEM" directive. 

system nt_ dll 

In addition, you must specify which functions in the Dynamic Link Library are to be made available to 
applications which use it. This is achieved by using the "EXPORT" directive for each function that can be 
called by an application. 

Dynamic Link Libraries can reference other Dynamic Link Libraries. References to other Dynamic Link 
Libraries are resolved by specifying "IMPORT" directives or using import libraries. 
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14.1.2 Using a Dynamic Link Library 

To use a Dynamic Link Library, you must tell the Open Watcom Linker which functions are contained in a 
Dynamic Link Library and the name of the Dynamic Link Library. This is achieved in two ways. 

The first method is to use the "IMPORT" directive. The "IMPORT" directive names the function and the 
Dynamic Link Library it belongs to so that the Open Watcom Linker can generate an import definition in 
the program module. 

The second method is to use import libraries. An impoit library is a standard library which contains object 
modules with special object records that define the functions belonging to a Dynamic Link Library. An 
import library is created from a Dynamic Link Library using the Open Watcom Library Manager. The 
resulting import library can then be specified in a "LIBRARY" directive in the same way one would specify 
a standard library. See the chapter entitled "The Open Watcom Library Manager" in the Open Watcom 
C/C++ Tools User’s Guide or the Open Watcom FORTRAN 77 Tools User’s Guide for more information 
on creating import libraries. 

Using an import library is the preferred method of providing references to functions in Dynamic Link 
Libraries. When a Dynamic Link Library is modified, typically the import library corresponding to the 
modified Dynamic Link Library is updated to reflect the changes. Hence, any directive file that specifies 
the import library in a "LIBRARY" directive need not be modified. However, if you are using "IMPORT" 
directives, you may have to modify the "IMPORT" directives to reflect the changes in the Dynamic Link 
Library. 

14.2 Memory Layout 

The following describes the segment ordering of an application linked by the Open Watcom Linker. Note 
that this assumes that the "DOSSEG" linker option has been specified. 

1. all segments not belonging to group "DGROUP" with class "CODE" 

2. all other segments not belonging to group "DGROUP" 

3. all segments belonging to group "DGROUP" with class "BEGDATA" 

4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS" or "STACK" 

5. all segments belonging to group "DGROUP" with class "BSS" 

6. all segments belonging to group "DGROUP" with class "STACK" 

A special segment belonging to class "BEGDATA" is defined when linking with Open Watcom run-time 
libraries. This segment is initialized with the hexadecimal byte pattern "01" and is the first segment in 
group "DGROUP" so that storing data at location 0 can be detected. 

Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized 
data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to 
define the size of the stack used for your application. Segments belonging to the classes "BSS" and 
"STACK" are last in the segment ordering so that uninitialized data need not take space in the executable 
file. 
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The Open Watcom Linker issues three classes of messages; fatal errors, errors and warnings. Each message 
has a 4-digit number associated with it. Fatal messages start with the digit 3, error messages start with the 
digit 2, and warning messages start with the digit 1. It is possible for a message to be issued as a warning 
or an error. 

If a fatal error occurs, the linker will terminate immediately and no executable file will be generated. 

If an error occurs, the linker will continue to execute so that all possible errors are issued. However, no 
executable file will be generated since these errors do not permit a proper executable file to be generated. 

If a warning occurs, the linker will continue to execute. A warning message is usually informational and 
does not prevent the creation of a proper executable file. However, all warnings should eventually be 
corrected. 

The messages listed contain references to %s, %S, %a, %x, %d, %1, and%f. They represent strings 
that are substituted by the Open Watcom Linker to make the error message more precise. 

1. %s represents a string. This may be a segment or group name, or the name of a linker directive 
or option. 

2. %S represents the name of a symbol. 

3. %a represents an address. The format of the address depends on the format of the executable file 
being generated. 

4. %x represents a hexadecimal number. 

5. %d represents integers in the range -32768 and 32767. 

6. %1 represents integers in the range -2147483648 and 2147483647. 

7. %f represents an executable file format such as DOS, ZDOS, WINDOWS, PHARLAP, 
NOVELL, OS2, QNX or ELF. 

The following is a list of all warning and error messages produced by the Open Watcom Linker followed 
by a description of the message. A message may contain more than one reference to "%s". In such a case, 
the description will reference them as "%sn" where n is the occurrence of "%s" in the message. 

MSG 2002 ** internal ** - %s 

If this message occurs, you have found a bug in the linker and should report it. 

MSG 2008 cannot open % si: %s2 

An error occurred while trying to open the file "%sl". The reason for the error is given by 
"%s2". Generally this error message is issued when the linker cannot open a file (e.g., an 
object file or an executable file). 
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MSG 3009 dynamic memory exhausted 

The linker uses all available memory when linking an application. For DOS-hosted 
versions of the linker, this includes expanded memory (EMS) and extended memory. 

When all available memory is used, a spill file will be used. Therefore, unless you are low 
on disk space, the linker will always be able to generate the executable file. Dynamic 
memory is the memory the linker uses to build its internal data structures and symbol table. 
Dynamic memory is the amount of unallocated memory available on your machine 
(including virtual memory for those operating systems that support it). A spill file is not 
used for dynamic memory. If the linker issues this message, it cannot link your application. 
The following are suggestions that may help you in this situation. 

1. Concatenate all your object files into one and specify only the resulting object 
file as input to the linker. For example, if you are linking in a (Z)DOS 
environment, you can issue the following DOS command. 

C>copy/b *.obj all.obj 

This technique only works for OMF-type object files. This significantly reduces 
the size of the file list the linker must maintain. 

2. Object files may contain a record which specifies the module name. This 
information is used by Open Watcom Debugger to locate modules during a 
debugging session and usually contains the full path of the source file. This can 
consume a significant amount of memory when many such object files are being 
linked. If your source is being compiled by the Open Watcom C or C++ 
compiler, you can use the "nm" option to set the module name to just the file 
name. This reduces the amount of memory required by the linker. If your are 
using Open Watcom Debugger to debug your application, you may have to use 
the "set source" command so that the source corresponding to a module can be 
located. 

3. Typically, when you are compiling a program for a large code model, each 
module defines a different "text" segment. If you are compiling your application 
using the Open Watcom C or C++ compiler, you can reduce the number of "text" 
segments that the linker has to process by specifying the "nt" option. The "nt" 
option allows you to specify the name of the "text" segment so that a group of 
object files define the same "text" segment. 

MSG 2010,3010 I/O error processing %sl: %s2 

An error has occurred while processing the file "%sl". The cause of the error is given by 
"%s2". This error is usually detected while reading from object and library files or writing 
to the spill file or executable file. For example, this error would be issued if a "disk full" 
condition existed. 

MSG 2011 invalid object file attribute 

The linker encountered an object file that was not of the format required of an object file. 

MSG 2012 invalid library file attribute 

The linker encountered a library file that was not of the format required of a library file. 
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MSG 3013 


MSG 1014 


MSG 2015 


MSG 2016 


MSG 2017 


MSG 2018 


MSG 1019 


MSG 2020 


break key detected 

The linking process was interrupted by the user from the keyboard. 

stack segment not found 

The linker identifies the stack segment by a segment defined as having the "STACK" 
attribute. This message is issued if no such segment is encountered. This usually happens 
if the linker cannot find the run-time libraries required to link your application. 

bad relocation type specified 

This message is issued if a a relocation is found in an object file which the linker does not 
support. 

%a: absolute target invalid for self-relative relocation 

This message is issued, for example, if a near call or jump is made to an external symbol 
which is defined using the "EQU" assembler directive. "%a" identifies the location of the 
near call or jump instruction. 

bad location specified for self-relative relocation at %a 

This message is issued if a bad fixup is encountered. "%a" defines the location of the 
fixup. 

relocation offset at % a is out of range 

This message is issued when the offset part of a relocation exceeds 64K in a 16-bit 
executable or an Alpha executable. "%a" defines the location of the fixup. The error is 
most commonly caused by errors in coding assembly language routines. Consider a 
module that references an external symbol that is defined in a segment different from the 
one in which the reference occurred. The module, however, specifies that the segment in 
which the symbol is defined is the same segment as the segment that references the symbol. 
This error is most commonly caused when the "EXTRN" assembler directive is placed after 
the "SEGMENT" assembler directive for the segment referencing the symbol. If the 
segment that references the symbol is allocated far enough away from the segment that 
defines the symbol, the linker will issue this message. 

segment relocation at %a 

This message is issued when a 16-bit segment relocation is encountered and "FORMAT 
DOS COM", "FORMAT PHARLAP" or "FORMAT NOVELL" has been specified. None 
of the above executable file formats allow segment relocation. "%a" identifies the location 
of the segment relocation. 

size of group %s exceeds 64k by %1 bytes 

The group "%s" has exceeded the maximum size (64K) allowed for a group in a 16-bit 
executable by "%1" bytes. Usually, the group is "DGROUP" (the default data segment) and 
your application has placed too much data in this group. One of the following may solve 
this problem. 
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MSG 2021 


MSG 2022 


MSG 1023 


MSG 2024 


MSG 2025 


MSG 2026 


1. If you are using the Open Watcom C or C++ compiler, you can place some of 
your data in a far segment by using the "far" keyword when defining data. You 
can also decrease the value of the data threshold by using the "zt" compiler 
option. Any datum whose size exceeds the value of the data threshold will be 
placed in a far segment. 

2. If you are using the Open Watcom FORTRAN 77 compiler, you can decrease 
the value of the data threshold by using the "dt" compiler option. Any datum 
whose size exceeds the value of the data threshold will be placed in a far 
segment. 

size of segment %s exceeds 64k by %1 bytes 

The segment "%s" has exceeded the maximum size (64K) for a segment in a 16-bit 
executable. This usually occurs if you are linking a 16-bit application that has been 
compiled for a small code model and the size of the application has grown in such a way 
that the size of the code segment ("_TEXT") has exceeded 64K. You can overlay your 
application or compile it for a large code model if you cannot reduce the amount of code in 
your application. 

cannot have a starting address with an imported symbol 

When generating an OS/2 executable file, a symbol imported from a DLL cannot be a start 
address. When generating a NetWare executable file, a symbol imported from an NLM 
cannot be a start address. 

no starting address found, using %a 

The starting address defines the location where execution is to begin and must be defined 
by a special "module end" record in one of the object files linked into your application. 

This message is issued if no such record is encountered in which case a default starting 
address, namely "%a", will be used. This usually happens if the linker cannot find the 
run-time libraries required to link your application. 

missing overlay loader 

This message is issued when an overlayed 16-bit DOS executable is being linked and the 
overlay manager has not been encountered. This usually happens if the linker cannot find 
the run-time libraries required to link your application. 

short vector %d is out of range 

This message is issued when the linker is creating an overlayed 16-bit DOS executable and 
"OPTION SMALL" is specified. Since an overlay vector contains a near call to the overlay 
loader followed by a near jump to the routine corresponding to the overlay vector, all code 
including the overlay manager and all overlay vectors must be less than 64K. This message 
is issued if the offset of an overlay vector from the overlay loader or the corresponding 
routine exceeds 64K. 

redefinition of reserved symbol %s 

The linker defines certain reserved symbols. These symbols are "_edata", "_end", 

"_OVLTAB_", "_OVLSTARTVEC_", "_OVLENDVEC_","_LOVLLDR_", 

"_NOVLLDR_", "_SOVLLDR_", "_LOVLINIT_", "_NOVLINIT_" and 
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"_SOVLINIT_". The symbols "_OVLTAB_", "_OVLSTARTVEC_", 

" OVLENDVEC ", " LOVLLDR ", " NOVLLDR ", "_SOVLLDR_", 

" LOVLINIT ", " NOVLINIT " and "_SOVLINIT_" are defined only if you are 

using overlays in 16-bit DOS executables. The symbols "_edata" and "_end" are defined 
only if the "DOSSEG" option is specified. Your application must not attempt to define 
these symbols. "%s" identifies the reserved symbol. 

MSG 1027 redefinition of %S ignored 

The symbol "%S" has been defined by more that one module; the first definition is used. 
This is only a warning message. Note that if a symbol is defined more than once and its 
address is the same in both cases, no warning will be issued. This prevents the warning 
message from being issued when linking FORTRAN 77 modules that contain common 
blocks. 

MSG 1028,2028 %S is an undefined reference 

The symbol "%S" has been referenced but not defined. Check that the spelling of the 
symbol is consistent. If you wish the linker to ignore undefined references, use the 
"UNDEFSOK" option. 

MSG 2029 premature end of file encountered 

This error is issued while processing object files and object modules from libraries and is 
caused if the end of the file or module is reached before the "module end" record is 
encountered. The probable cause is a truncated object file. 

MSG 2030 multiple starting addresses found 

The starting address defines the location where execution is to begin and is defined by a 
"module end" record in a particular object file. This message is issued if more than one 
object file contains a "module end" record that defines a starting address. 

MSG 2031 segment %s is in group %s and group %s 

The segment "%sl" has been defined to be in group "%s2" in one module and in group 
"%s3" in another module. A segment can only belong to one group. 

MSG 1032 record (type Ox%x) not processed 

An object record type not supported by the linker has been encountered. This message is 
issued when linking object modules created by other compilers or assemblers that create 
object files with records that the linker does not support. 

MSG 2033,3033 directive error near ’%s’ 

A syntax error occurred while the linker was processing directives. "%s" specifies where 
the error occurred. 

MSG 2034 %a cannot have an offset with an imported symbol 

An imported symbol is one that was specified in an "IMPORT" directive. Imported 
symbols are defined in Windows or OS/2 16-bit DLLs and in Netware NLMs. References 
to imported symbols must always have an offset value of 0. If "DosWrite" is an imported 
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symbol, then referencing "DosWrite+2" is illegal. "%a" defines the location of the illegal 
reference. 

MSG 1038 DEBUG directive appears after object files 

This message is issued if the first "DEBUG" directive appears after a "FILE" directive. A 
common error is to specify a "DEBUG" directive after the "FILE" directives in which case 
no debugging information for those object files is generated in the executable file. 

MSG 2039 ALIGNMENT value too small 

The value specified in the "ALIGNMENT" option refers to the alignment of segments in 
the executable file. For 16-bit Windows or 16-bit OS/2, segments in the executable file are 
pointed to by a segment table. An entry in the segment table contains a 16-bit value which 
is a multiple of the alignment value. Together they form the offset of the segment from the 
start of the segment table. The smaller the alignment, the bigger the value required in the 
segment table to point to the segment. If this value exceeds 64K, then a larger alignment 
value is required to decrease the size that goes in the segment table. 

MSG 2040 ordinal in IMPORT directive not valid 

The specified ordinal in the "IMPORT" directive is incorrect (e.g., -1). An ordinal number 
must be in the range 0 to 65535. 

MSG 2041 ordinal in EXPORT directive not valid 

The specified ordinal in the "EXPORT" directive is incorrect (e.g., -1). An ordinal number 
must be in the range 0 to 65535. 

MSG 2042 too many IOPL words in EXPORT directive 

The maximum number of IOPL words for a 16-bit executable is 63. 

MSG 1043 duplicate exported ordinal 

This message is issued for ordinal numbers specified in an "EXPORT" directive for 
symbols belonging to DLLs. This message is issued if an ordinal number is assigned to 
two different symbols. A warning is issued and the linker assigns a non-used ordinal 
number to the symbol that caused the warning. 

MSG 1044,2044 exported symbol %s not found 

This message is issued when generating a DLL or NetWare NLM. An attempt has been 
made to define an entry point into a DLL or NLM that does not exist. 

MSG 1045 segment attribute defined more than once 

A segment appearing in a "SEGMENT" directive has been given conflicting or duplicate 
attributes. 

MSG 1046 segment name %s not found 

The segment name specified in a "SEGMENT" directive has not been defined. 
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MSG 1047 


MSG 1048 


MSG 2049 


MSG 1050 


MSG 2051 


MSG 2052 


MSG 2053 


MSG 1054 


MSG 2055 


MSG 2056 


MSG 3057 


class name %s not found 

The class name specified in a "SEGMENT" directive has not been defined. 

inconsistent attributes for automatic data segment 

This message is issued for Windows or OS/2 16-bit executable files. Two conflicting 
attributes were specified for the automatic data segment. For example, "LOADONCALL" 
and "PRELOAD" are conflicting attributes. Only the first attribute is used. 

invalid STUB file 

The stub file is not a valid executable file. The stub file is only used for OS/2 executable 
files and Windows (both Winl6 and Win32) executable files. 

invalid DLL specified in OLDLIBRARY option 

The DLL specified in an "OLDLIBRARY" option is not a valid dynamic link library. 

STUB file name same as executable file name 

When generating an OS/2 or Windows (Winl6, Win32) executable file, the stub file name 
must not be same as the executable file name. 

relocation at %a not in the same segment 

This message is only issued for Windows (Winl6), OS/2, Phar Lap, and QNX executables. 
A relative fixup must relocate to the same segment. "%a" defines the location of the fixup. 

%a: cannot reach a DLL with a relative relocation 

A reference to a symbol in an OS/2 or Windows 16-bit DLL must not be relative. "%a" 
defines the location of the reference. 

debugging information incompatible: using line numbers only 

An attempt has been made to link an object file with out-of-date debugging information. 

%a: frame must be the same as the target in protected mode 

Each relocation consists of three components; the location being relocated, the target (or 
address being referenced), and the frame (the segment to which the target is adjusted). In 
protected mode, the segment of the target must be the same as the frame. "%a" defines the 
location of the fixup. This message does not apply to 32-bit OS/2 and Windows (Win32). 

cannot find library member %s(%s) 

Library member "%s2" in library file "%sl" could not be found. This message is issued if 
the library file could not be found or the library file did not contain the specified member. 

executable format has been established 

This message is issued if there is more than one "FORMAT" directive. 
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MSG 1058 %s option not valid for %s executable 

The option "%sl" can only be specified if an executable file whose format is "%s2" is 
being generated. 

MSG 1059,2059 value for %s too large 

The value specified for option "%s" exceeds its limit. 

MSG 1060 value for %s incorrect 

The value specified for option "%s" is not in the allowable range. 

MSG 1061 multiple values specified for REALBREAK 

The "REALBREAK" option for Phar Lap executables can only be specified once. 

MSG 1062 export and import records not valid for %f 

This message is issued if a reference to a DLL is encountered and the executable file format 
is not one that supports DLLs. The file format is represented by "%f". 

MSG 2063 invalid relocation for flat memory model at %a 

A segment relocation in the flat memory model was encountered. "%a" defines the 
location of the fixup. 

MSG 2064 cannot combine 32-bit segments (%sl) with 16-bit segments (%s2) 

A 32-bit segment "%sl" and a 16-bit segment "%s2" have been encountered. Mixing 
object files created by a 286 compiler and object files created by a 386 compiler is the most 
probable cause of this error. 

MSG 2065 REALBREAK symbol %s not found 

The symbol specified in the "REALBREAK" option for Phar Lap executables has not been 
defined. 

MSG 2066 invalid relative relocation type for an import at %a 

This message is issued only if a NetWare executable file is being generated. An imported 
symbol is one that was specified in an "IMPORT" directive or an import library. Any 
reference to an imported symbol must not refer to the segment of the imported symbol. 

"%a" defines the location of the reference. 

MSG 2067 %a: cannot relocate between code and data in Novell formats 

This message is issued only if a NetWare executable file is being generated. Segment 
relocation is not permitted. "%a" defines the location of the fixup. 

MSG 2068 absolute segment fixup not valid in protected mode 

A reference to an absolute location is not allowed in protected mode. A protected-mode 
application is one that is being generated for ZDOS, OS/2, CauseWay DOS extender, 
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MSG 1069 


MSG 2070 


MSG 2071 


MSG 1072 


MSG 2073 


MSG 2074 


MSG 2075 


MSG 1076 


MSG 1080 


MSG 2082 


Tenberry Software’s DOS/4G or DOS/4GW DOS extender, FlashTek’s DOS extender, 
Phar Lap’s 386IDOS-Extender, Novell’s NetWare operating systems, Windows NT, or 
Windows 95. An absolute location is most commonly defined by the "EQU" assembler 
directive. 

unload CHECK procedure not found 

This message is issued only if a NetWare executable file is being generated. The symbol 
specified in the "CHECK" option has not been defined. 

START procedure not found 

This message is issued only if a NetWare executable file is being generated. The symbol 
specified in the "START" option has not been defined. The default "START" symbol is 
".Prelude". 

EXIT procedure not found 

This message is issued only if a NetWare executable file is being generated. The symbol 
specified in the "EXIT" option has not been defined. The default "STOP" symbol is 
".Stop". 

SECTION directive not allowed in root 

When describing 16-bit overlays, "SECTION" directives must appear between a "BEGIN" 
directive and its corresponding "END" directive. 

bad Novell file format specified 

An invalid NetWare executable file format was specified. Valid formats are NLM, DSK, 
NAM, LAN, MSL, HAM, CDM or a numerical module type. 

circular alias found for %s 

An attempt was made to circularly define the symbol name specified in an ALIAS 
directive. For example: 

ALIAS fool=foo2, foo2=fool 

expecting an END directive 

A "BEGIN" directive is missing its corresponding "END" directive. 

%s option multiply specified 

The option "%s" can only be specified once. 

file %s is a %d-bit object file 

A 32-bit attribute was encountered while generating a 16-bit executable file format, or a 
16-bit attribute was encountered while generating a 32-bit executable file format. 

invalid record type Ox%x 
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MSG 2083 


MSG 2084 


MSG 2086 


MSG 1087 


MSG 3088 


MSG 2089 


MSG 1090 


MSG 2091 


MSG 2092 


An object record type not recognized by the linker has been encountered. This message is 
issued when linking object modules created by other compilers or assemblers that create 
object files with records that the linker does not recognize. 

cannot reference address %a from frame %x 

When generating a 16-bit executable, the offset of a referenced symbol was greater than 
64K from the location referencing it. 

target offset exceeds 64K at %a 

When generating a 16-bit executable, the computed offset for a symbol exceeds 64K. "%a" 
defines the location of the fixup. 

invalid starting address for .COM file 

The value of the segment of the starting address for a 16-bit DOS "COM" file, as specified 
in the map file, must be 0. 

stack segment ignored in .COM file 

A stack segment must not be defined when generating a 16-bit DOS "COM" file. Only a 
single physical segment is allowed in a DOS "COM" file. The stack is allocated from the 
high end of the physical segment. That is, the initial value of SP is hexadecimal FFFE. 

virtual memory exhausted 

This message is similar to the "dynamic memory exhausted" message. The DOS-hosted 
version of the linker has ran out of memory trying to keep track of virtual memory blocks. 
Virtual memory blocks are allocated from expanded memory, extended memory and the 
spill file. 

program too large for a .COM file 

The total size of a 16-bit DOS "COM" program must not exceed 64K. That is, the total 
amount of code and data must be less than 64K since only a single physical segment is 
allowed in a DOS "COM" file. You must decrease the size of your program or generate a 
DOS "EXE" file. 

redefinition of %s by %s ignored 

The symbol "%sl" has been redefined by module "%s2". This message is issued when the 
size specified in the "NAMELEN" option has caused two symbols to map to the same 
symbol. For example, if the symbols routine1 and routine2 are encountered and "OPTION 
NAMELEN=7" is specified, then this message will be issued since the first seven 
characters of the two symbols are identical. 

group %s is in more than one overlay 

A group that spans more than one section in a 16-bit DOS executable has been detected. 

NEWSEGMENT directive appears before object files 

The 16-bit "NEWSEGMENT" directive must appear after a "FILE" directive. 
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MSG 2093 


MSG 2094 


MSG 3097 


MSG 1098 


MSG 2099 


MSG 1101 


MSG 1102 


MSG 1103 


MSG 1105 


MSG 1107 


cannot open %s 

This message is issued when the linker is unable to open a file and is unable to determine 
the cause. 

i/o error processing %s 

This message is issued when the linker has encountered an i/o error while processing the 
file and is unable to determine the cause. This message may be issued when reading from 
object and library files, or writing to the executable and spill file. 

too many library modules 

This message is similar to the "dynamic memory exhausted" message. This message if 
issued when the "DISTRIBUTE" option for 16-bit DOS executables is specified. The 
linker has run out of memory trying to keep track of the relationship between object 
modules extracted from libraries and the overlays they should be placed in. 

Offset option must be a multiple of %dK 

The value specified with the "OFFSET" option must be a multiple of 4K (4096) for Phar 
Fap and QNX executables and a multiple of 64K (65536) for OS/2 and Windows 32-bit 
executables. 

symbol name too long: %s 

The maximum size (approximately 2048) of a symbol has been exceeded. Reduce the size 
of the symbol to avoid this error. 

invalid incremental information file 

The incremental information file is corrupt or from an older version of the compiler. The 
old information file and the executable will be deleted and new ones will be generated. 

object file %s not found for tracing 

A "SYMTRACE" or "MODTRACE" directive contained an object file (namely %s) that 
could not be found. 

library module %s(%s) not found for tracing 

A "SYMTRACE" or "MODTRACE" directive contained an object module (namely module 
%sl in library %s2 ) that could not be found. 

cannot reserve %1 bytes of extra overlay space 

The value specified with the "AREA" option for 16-bit DOS executables results in an 
executable file that requires more than 1 megabyte of memory to execute. 

undefined system name: %s 

The name %s was referenced in a "SYSTEM" directive but never defined by a system 
block definition. 
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MSG 1108 


MSG 1109 


MSG 1110 


MSG 1111 


MSG 3114 


MSG 1115 


MSG 1116 


MSG 1117 


MSG 1118 


MSG 2119 


MSG 2120 


system %s defined more than once 

The name %s has appeared in a system definition block more than once. 

OFFSET option is less than the stack size 

For the QNX operating system, the stack is placed at the front of the executable image and 
thus the initial load address must leave enough room for the stack. 

library members not allowed in libfile 

Only object files are allowed in a "LIBFILE" directive. This message will be issued if a 
module from a library file is specified in a "LIBFILE" directive. 

error in default system block 

The default system block definition (system name "286" for 16-bit applications) and 
(system name "386" for 32-bit applications) contains a directive error. The system name 
"286" or "386" is automatically referenced by the linker when the format of the executable 
cannot be determined (i.e. no "FORMAT" directive has been specified). 

environment name specified incorrectly 

This message is specified if the environment variable is not properly enclosed between two 
percent (%) characters. 

environment name %s not found 

The environment variable %s has not been defined in the environment space. 

overlay area must be at least %1 bytes 

This message is issued if the size of the largest overlay exceeds the size of the overlay area 
specified by the "AREA" option for 16-bit DOS executables. 

segment number too high for a movable entry point 

The segment number of a moveable segment must not exceed 255 for 16-bit executables. 
Reduce the number of segments or use the "PACKCODE" option. 

heap size too large 

This message is issued if the size of the heap, stack and the default data segment (group 
DGROUP) exceeds 64K for 16-bit executables. 

wlib import statement incorrect 

The "EXPORT" directive allows you to specify a library command file. This command file 
is scanned for any librarian commands that create import library entries. An invalid 
command was detected. See the section entitled "The EXPORT Directive" for the correct 
format of these commands. 

application too large to run under DOS 
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MSG 1121 


MSG 3122 


MSG 3123 


MSG 1124 


MSG 1125 


MSG 1126 


MSG 2127 


MSG 3128 


MSG 3129 


MSG 1130 


This message is issued if the size of the 16-bit DOS application exceeds 1M. 

’%s’ has already been exported 

The linker has detected an attempt to export a symbol more than once. For example, a 
name appearing in more than one "EXPORT" directive will cause this message to be 
issued. Also, if you have declared a symbol as an export in your source and have also 
specified the same symbol in an "EXPORT" directive, this message will be issued. This 
message is only a warning. 

no FILE directives found 

This message is issued if no "FILE" directive has been specified. In other words, you have 
specified no object files to link. 

overlays are not supported in this version of the linker 

This version of the linker does not support the creation of overlaid 16-bit executables. 

lazy reference for %S has different default resolutions 

A lazy external reference is one which has two resolutions: a preferred one and a default 
one which is used if the preferred one is not found. In this case, the linker has found two 
lazy references that have the same preferred resolution but different default resolutions. 

multiple aliases found for %S 

The linker has found a name which has been aliased to two different symbols. 

%s has been modified: doing full relink 

The linker has determined that the time stamps on the executable file and symbolic 
information file (.sym) are different. An incremental link will not be done. 

cannot export symbol %S 

An attempt was made to export a symbol defined with an absolute address or to export an 
imported symbol. It is not possible to export these symbols with the "EXPORT" directive. 

directive error near beginning of input 

The linker detected an error at the start of the command line. 

address information too large 

The linker has encountered a segment that appears in more than 11000 object files. An 
empty segment does not affect this limit. This can only occur with Watcom debugging 
information. If this message appears, switch to DWARF debugging information. 

%s is an invalid shared nlm file 

The NLM specified in a "SHAREDNLM" option is not valid. 
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MSG 3131 


MSG 2132 


MSG 1133 


MSG 1134 


MSG 3135 


MSG 1136 


MSG 3137 


MSG 3138 


MSG 3139 


MSG 1140 


MSG 1141 


cannot open spill file: file already exists 

All 26 of the DOS-hosted linker’s possible spill file names are in use. Spill files can 
accumulate when linking on a multi-tasking system and the directory in which the spill file 
is created is identical for each invocation of the linker. 

curly brace delimited list incorrect 

A list delimited by curly braces is not correct. The most likely cause is a missing right 
brace. 

no realbreak specified for 16-bit code 

While generating a Phar Lap executable file, both 16-bit and 32-bit code was linked 
together and no "REALBREAK" option has been specified. A warning message is issued 
since this may be a potential problem. 

%s is an invalid message file 

The file specified in a "MESSAGE" option for NetWare executable files is invalid. 

need exactly 1 overlay area with dynamic overlay manager 

Only a single overlay area is supported by the 16-bit dynamic overlay manager. 

segment relocation to a read/write data segment found at %a(%S) 

The "RWRELOCCHECK" option for 16-bit Windows (Winl6) executables has been 
specified and the linker has detected a segment relocation to a read/write data segment. 
Where the name of the offending symbol is not available, "identifier unavailable" is used. 

too many errors encountered 

This message is issued when the number of error messages issued by the linker exceeds the 
number specified by the "MAXERRORS" option. 

invalid filename ’%s’ 

The linker performs a simple filename validation whenever a filename is specified to the 
linker. For example, a directory specification is not a valid filename. 

cannot have both 16-bit and 32-bit object files 

It is impossible to mix 16-bit code and 32-bit code in the same executable when generating 
a QNX executable file. 

invalid message number 

An invalid message number has been specified in a "DISABLE" directive. 

virtual function table record for %s mismatched 

The linker performs a consistency check to ensure that the C++ compiler has not generated 
incorrect virtual function information. If the message is issued, please report this problem. 
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MSG 1143 


MSG 1145 


MSG 2146 


MSG 3147 


MSG 1148 


MSG 1149 


MSG 1150 


MSG 2151 


MSG 2152 


MSG 2154 


MSG 2155 


not enough memory to sort map file symbols 

There was not enough memory for the linker to sort the symbols in the "Memory Map" 
portion of the map file. This will only occur when the "SORT GLOBAL" option has been 
specified. 

%S is both pure virtual and non-pure virtual 

A function has been declared both as "pure" and "non-pure" virtual. 

%s is an invalid object file 

Something was encountered in the object file that cannot be processed by the linker. 

Ambiguous format specified 

Not enough of the FORMAT directive attributes were specified to enable the linker to 
determine the executable file format. For example, 

FORMAT OS2 

will generate this message. 

Invalid segment type specified 

The segment type must be one of CODE or DATA. 

Only one debugging format can be specified 

The debugging format must be one of Watcom, CodeView, DWARF (default), or Novell. 
You cannot specify multiple debugging formats. 

file %s has code for a different processor 

An object file has been encountered which contains code compiled for a different processor 
(e.g., an Intel application and an Alpha object file). 

big endian code not supported 

Big endian code is not supported by the linker. 

no dictionary found 

No symbol search dictionary was found in a library that the linker attempted to process. 

cannot execute %sl: %s2 

An attempt by the linker to spawn another application failed. The application is specified 
by "%sl" and the reason for the failure is specified by "%s2". 

relocation at % a to an improperly aligned target 

Some relocations in Alpha executables require that the object be aligned on a 4 byte 
boundary. 
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MSG 2156 


MSG 3157 


MSG 1158 


MSG 3159 


MSG 3160 


MSG 1162 


MSG 1163 


MSG 3164 


MSG 1165 


MSG 2166 


MSG 1167 


OPTION INCREMENTAL must be one of the first directives specified 

The option must be specified before any option or directive which modifies the linker’s 
symbol table (e.g., IMPORT, EXPORT, REFERENCE, ALIAS). 

no code or data present 

The linker requires that there be at least 1 byte of either code or data in the executable. 

problem adding resource information 

The resource file is invalid or corrupt. 

incremental linking only supports DWARF debugging information 

When OPTION INCREMENTAL is used, you cannot specify non-DWARF debugging 
information for the executable. You must specify DEBUG DWARF when requesting 
debugging information. 

incremental linking does not support dead code elimination 

When OPTION INCREMENTAL is used, you cannot specify OPTION ELIMINATE. 

relocations on iterated data not supported 

An object file was encountered that contained an iterated data record that requires 
relocation. This is most commonly caused by a module coded in assembly language. 

module has not been compiled with the "zv" option 

When OPTION VFREMOVAL is used, all object files must be compiled with the "zv" 
option. The linker has detected an object file that has not been compiled with this option. 

incremental linking does not support virtual function removal 

When OPTION INCREMENTAL is used, you cannot also specify OPTION 
VFREMOVAL. 

resource file %s too big 

The resource file specified in OPTION RESOURCE was too big to fit inside the QNX 
executable. The maximum size is approximately 32000 bytes. 

both %sl and %s2 marked as starting symbols 

If the linker sees that there is more than one starting address specified in the program and 
they have symbol names associated with them, it will emit this error message. If there is 
more than one starting address specified and at least one of them is unnamed, it will issue 
message 2030. 

NLM internal name (%s) truncated 

This message is issued when generating a NetWare NLM. The output file name as 
specified by the NAME directive has specified a long file name (exceeds 8.3). The linker 
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MSG 3168 


MSG 2169 


MSG 1170 


MSG 1171 


MSG 1172 


MSG 3173 


will truncate the generated file name by using the first eight characters of the specified file 
name and the first three characters of the file extension (if supplied), separated by a period. 

exactly one export must exist for VxD format 

The Windows VxD format requires exactly one export to be present, but an attempt was 
made to build a VxD module with no exports or more than one export. 

location counter already beyond fixed segment address %a 

When creating an image using the OUTPUT directive, a segment was specified with an 
address lower than the current location counter. This would overlay the segment data with 
already existing data at the same address, and is not allowed. 

directive %s can only occur once 

A directive was specified more than once on the Open Watcom Linker command line and 
was ignored. Remove the redundant instances of the directive. 

locally defined symbol %s imported 

An imported symbol (intended to be imported from a DLL) was resolved locally. The 
linker will ignore the symbol defined in a DLL, if provided, and the local reference will be 
used. Ensure that this is the intended behaviour. 

stack size is less than %d bytes. 

The stack size for an executable specified through OPTION STACK is very small. There is 
a high probability that the program will not work correctly. Consider specifying a greater 
stack size. 

default data segment exceeds maximum size by %1 bytes 

The default data segment size in a NE format executable (16-bit OS/2 or Windows) 
exceeds the maximum allowed size. The default data segment includes the data segment 
plus default stack size plus default heap size. The total size must be 64K or less for OS/2 
executables and 65,533 bytes or less for Windows executables. 
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1 Open Watcom C/C++ Application Development 


This document contains guides to application development for several environments including 16-bit DOS, 
32-bit extended DOS, Windows 3.x, 32-bit extended Windows 3.x, Windows NT/2000/XP, Win9x, OS/2, 
and Novell NLMs. It also describes mixed language (C, FORTRAN) application development. It 
concludes with a chapter on some general questions and the answers to them. 

This document covers the following topics: 

• DOS Programming Guide 
Creating 16-bit DOS Applications 

Creating 32-bit Phar Lap 386\DOS-Extender Applications 
Creating 32-bit DOS/4GW Applications 
32-bit Extended DOS Application Development 

• The DOS/4GW DOS Extender 
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Interfacing Visual Basic and Open Watcom C/C++ DLLs 

WIN386 Library Functions and Macros 

32-bit Extended Windows Application Development 

Special Variables for Windows Programming 
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Special Windows API Functions 

• Windows NT Programming Guide 
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2 Creating 16-bit DOS Applications 


This chapter describes how to compile and link 16-bit DOS applications simply and quickly. 

We will illustrate the steps to creating 16-bit DOS applications by taking a small sample application and 
showing you how to compile, link, run and debug it. 

2.1 The Sample Application 

To demonstrate the creation of 16-bit DOS applications using command-line oriented tools, we introduce a 
simple sample program. For our example, we are going to use the famous "hello" program. 

♦include <stdio.h> 

void main() 

{ 

printf ( "Hello world\n" ); 

} 

The C++ version of this program follows: 

♦include <iostream.h> 

void main() 

{ 

cout << "Hello world" << endl; 

} 

The goal of this program is to display the message "Hello world" on the screen. The C version uses the C 
library printf routine to accomplish this task. The C++ version uses the "iostream" library to accomplish 
this task. We will take you through the steps necessary to produce this result. 


2.2 Building and Running the Sample DOS Application 

To compile and link our example program which is stored in the file hello. c, enter the following 
command: 

C>wcl -l=dos hello.c 

The typical messages that appear on the screen are shown in the following illustration. 
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C>wcl -l=dos hello.c 

Open Watcom C/C++16 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
wcc hello.c 

Open Watcom Cl6 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 6 lines, included 155, 0 warnings, 0 errors 

Code size: 17 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 
creating a DOS executable 

Provided that no errors were encountered during the compile or link phases, the "hello" program may now 
be run. 

C>hello 
Hello world 

If you examine the current directory, you will find that two files have been created. These are 
hello, obj (the result of compiling hello, c) and hello. exe (the result of linking hello, obj 
with the appropriate Open Watcom C/C++ libraries). It is hello . exe that is run by DOS when you enter 
the "hello" command. 


2.3 Debugging the Sample DOS Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "hello" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WCL command, this is fairly straightforward. WCL recognizes the Open Watcom C/C++ 
compiler "debug" options and will create the appropriate debug directives for the Open Watcom Linker. 

For example, to compile and link the "hello" program with debugging information, the following command 
may be issued. 

C>wcl -l=dos - 6.2 hello, c 

The typical messages that appear on the screen are shown in the following illustration. 
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C>wcl -l=dos -d2 hello.c 

Open Watcom C/C++16 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
wcc hello.c -d2 

Open Watcom Cl6 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 6 lines, included 155, 0 warnings, 0 errors 

Code size: 23 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 
creating a DOS executable 

The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom C/C++ compiler. WCL will make sure that this debugging information is included in the 
executable file that is produced by the linker. 

The "Code size" value is larger than in the previous example since selection of the "d2" option results in 
fewer code optimizations by default. You can request more optimization by specifying the appropriate 
options. However, you do so at the risk of making it more difficult for yourself to determine the 
relationship between the object code and the original source language code. 


To request the Open Watcom Debugger to assist in debugging the application, the following command may 
be issued. 

C>wd hello 

It would be too ambitious to describe the debugger in this introductory chapter so we refer you to the book 
entitled Open Watcom Debugger User’s Guide. 
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3 Creating 32-bit Phar Lap 386IDOS-Extender 
Applications 


This chapter describes how to compile and link 32-bit Phar Lap 386IDOS-Extender applications simply and 
quickly. 

We will illustrate the steps to creating 32-bit Phar Lap 386IDOS-Extender applications by taking a small 
sample application and showing you how to compile, link, run and debug it. 

3.1 The Sample Application 

To demonstrate the creation of 32-bit Phar Lap 386IDOS-Extender applications using command-line 
oriented tools, we introduce a simple sample program. For our example, we are going to use the famous 
"hello" program. 

♦include <stdio.h> 

void main() 

{ 

printf ( "Hello world\n" ); 

} 

The C++ version of this program follows: 

♦include <iostream.h> 

void main() 

{ 

cout << "Hello world" << endl; 

} 

The goal of this program is to display the message "Hello world" on the screen. The C version uses the C 
library printf routine to accomplish this task. The C++ version uses the "iostream" library to accomplish 
this task. We will take you through the steps necessary to produce this result. 

3.2 Building and Running the Sample 386IDOS-Extender 
Application 

To compile and link our example program which is stored in the file hello. c, enter the following 
command: 

C>wcl386 -l=pharlap hello.c 

The typical messages that appear on the screen are shown in the following illustration. 
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C>wcl386 -l=pharlap hello.c 

Open Watcom C/C++32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 
wcc386 hello.c 

Open Watcom C32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 6 lines, included 174, 0 warnings, 0 errors 

Code size: 24 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Phar Lap simple executable 


Provided that no errors were encountered during the compile or link phases, the "hello" program may now 
be run. 

C>run386 hello 
Hello world 

If you examine the current directory, you will find that two files have been created. These are 
hello, obj (the result of compiling hello, c) and hello. exp (the result of linking hello, obj 
with the appropriate Open Watcom C/C++ libraries). It is hello . exp that is run by DOS when you enter 
the "run386 hello" command. 


3.3 Debugging the Sample 386IDOS-Extender Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "hello" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WCL386 command, this is fairly straightforward. WCL386 recognizes the Open Watcom 
C/C++ compiler "debug" options and will create the appropriate debug directives for the Open Watcom 
Linker. 

For example, to compile and link the "hello" program with debugging information, the following command 
may be issued. 

C>wcl386 -l=pharlap -d2 hello.c 
The typical messages that appear on the screen are shown in the following illustration. 
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C>wcl386 -l=pharlap -d2 hello.c 

Open Watcom C/C++32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

wcc386 hello.c -d2 
Open Watcom C32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 6 lines, included 174, 0 warnings, 0 errors 

Code size: 45 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Phar Lap simple executable 


The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom C/C++ compiler. WCL386 will make sure that this debugging information is included in the 
executable file that is produced by the linker. 

The "Code size" value is larger than in the previous example since selection of the "d2" option results in 
fewer code optimizations by default. You can request more optimization by specifying the appropriate 
options. However, you do so at the risk of making it more difficult for yourself to determine the 
relationship between the object code and the original source language code. 

To request the Open Watcom Debugger to assist in debugging the application, the following command may 
be issued. 

C>wd /trap=pls hello 

It would be too ambitious to describe the debugger in this introductory chapter so we refer you to the book 
entitled Open Watcom Debugger User’s Guide. 
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4 Creating 32-bit D0S/4GW Applications 


This chapter describes how to compile and link 32-bit DOS/4GW applications simply and quickly. 

We will illustrate the steps to creating 32-bit DOS/4GW applications by taking a small sample application 
and showing you how to compile, link, run and debug it. 

4.1 The Sample Application 

To demonstrate the creation of 32-bit DOS/4GW applications using command-line oriented tools, we 
introduce a simple sample program. For our example, we are going to use the famous "hello" program. 

♦include <stdio.h> 

void main() 

{ 

printf( "Hello world\n" ); 

} 

The C++ version of this program follows: 

♦include <iostream.h> 

void main() 

{ 

cout << "Hello world" << endl; 

} 

The goal of this program is to display the message "Hello world" on the screen. The C version uses the C 
library printf routine to accomplish this task. The C++ version uses the "iostream" library to accomplish 
this task. We will take you through the steps necessary to produce this result. 


4.2 Building and Running the Sample D0S/4GW Application 

To compile and link our example program which is stored in the file hello . c, enter the following 
command: 

C>wcl386 -l=dos4g hello.c 

The typical messages that appear on the screen are shown in the following illustration. 
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C>wcl386 -l=dos4g hello.c 

Open Watcom C/C++32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 
wcc386 hello.c 

Open Watcom C32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 6 lines, included 174, 0 warnings, 0 errors 

Code size: 24 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 
creating a DOS/4G executable 

Provided that no errors were encountered during the compile or link phases, the "hello" program may now 
be run. 

C>hello 
Hello world 

If you examine the current directory, you will find that two files have been created. These are 
hello, obj (the result of compiling hello, c) and hello. exe (the result of linking hello, obj 
with the appropriate Open Watcom C/C++ libraries). It is hello . exe that is run by DOS when you enter 
the "hello" command. 


4.3 Debugging the Sample D0S/4GW Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "hello" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WCL386 command, this is fairly straightforward. WCL386 recognizes the Open Watcom 
C/C++ compiler "debug" options and will create the appropriate debug directives for the Open Watcom 
Linker. 

For example, to compile and link the "hello" program with debugging information, the following command 
may be issued. 

C>wcl386 -l=dos4g -d2 hello.c 
The typical messages that appear on the screen are shown in the following illustration. 
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C>wcl386 -l=dos4g -d2 hello.c 

Open Watcom C/C++32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

wcc386 hello.c -d2 
Open Watcom C32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 6 lines, included 174, 0 warnings, 0 errors 

Code size: 45 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 
creating a DOS/4G executable 

The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom C/C++ compiler. WCL386 will make sure that this debugging information is included in the 
executable file that is produced by the linker. 

The "Code size" value is larger than in the previous example since selection of the "d2" option results in 
fewer code optimizations by default. You can request more optimization by specifying the appropriate 
options. However, you do so at the risk of making it more difficult for yourself to determine the 
relationship between the object code and the original source language code. 

To request the Open Watcom Debugger to assist in debugging the application, the following command may 
be issued. 

C>wd /trap=rsi hello 

It would be too ambitious to describe the debugger in this introductory chapter so we refer you to the book 
entitled Open Watcom Debugger User’s Guide. 
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5 32-bit Extended DOS Application Development 


5.1 Introduction 


The purpose of this chapter is to anticipate common programming questions for 32-bit extended DOS 
application development. Note that these programming solutions may be DOS-extender specific and 
therefore may not work for other DOS extenders. 

The following topics are discussed in this chapter: 

• How can I write directly to video memory using a DOS extender? 

• How do I get information about free memory in the 32-bit environment? 

• How do I access the first megabyte in the extended DOS environment? 

• How do I spawn a protected-mode application? 

• How can I use the mouse interrupt (0x33) with DOS/4GW? 

• How do I simulate a real-mode interrupt with DOS/4GW? 

• How do you install a bi-modal interrupt handler with DOS/4GW? 

Please refer to the DOS Protected-Mode Interface (DPMI) Specification for information on DPMI 
services. In the past, the DPMI specification could be obtained free of charge by contacting Intel Literature 
JP26 at 800-548-4725 or by writing to the address below. We have been advised that the DPMI 
specification is no longer available in printed form. 

Intel Literature JP26 
3065 Bowers Avenue 
P.O. Box 58065 
Santa Clara, California 
U.S.A. 95051-8065 

However, the DPMI 1.0 specification can be obtained from the Intel ftp site. Here is the URL. 

ftp: //ftp. intel. com/pub/IAL/software_ specs/dpmivl. zip 

This ZIP file contains a Postscript version of the DPMI 1.0 specification. 
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5.2 How can I write directly to video memory using a DOS 
extender? 


Many programmers require access to video RAM in order to directly manipulate data on the screen. Under 
DOS, it was standard practice to use a far pointer, with the segment part of the far pointer set to the screen 
segment. Under DOS extenders, this practice is not so standard. Each DOS extender provides its own 
method for accessing video memory. 

5.2.1 Writing to Video Memory under Tenberry Software DO S/4 GW 

Under DOS/4GW, the first megabyte of physical memory is mapped as a shared linear address space. This 
allows your application to access video RAM using a near pointer set to the screen’s linear address. The 
following program demonstrates this method. 

/* 

SCREEN.C - This example shows how to write directly 
to screen memory under the D0S/4GW dos-extender. 

Compile & Link: wcl386 -l=dos4g SCREEN 

*/ 

#include <stdio.h> 

#include <dos.h> 

/* 

Under D0S/4GW, the first megabyte of physical memory 
(real-mode memory) is mapped as a shared linear address 
space. This allows your application to access video RAM 
using its linear address. The DOS segment:offset of 
B800:0000 corresponds to a linear address of B8000. 

*/ 

♦define SCREEN_ AREA 0xb800 

♦ define SCREEN_ LIN_ ADDR ( (SCREEN_ AREA) « 4) 

♦define SCREEN_ SIZE 80*25 
void main() 

{ 

char *ptr; 

int i; 

/* Set the pointer to the screen's linear address */ 

ptr = (char * ) SCREEN_ LIN_ ADDR; 

for( i = 0; i < SCREEN_ SIZE - 1; i++ ) { 

*ptr = '*'; 

ptr += 2 * sizeof ( char ); 

} 

} 

Please refer to the chapter entitled "Linear Executables" on page 43 for more information on how 
DOS/4GW maps the first megabyte. 
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5.2.2 Writing to Video Memory under the Phar Lap 386IDOS-Extender 

The Phar Lap DOS extender provides screen access through the special segment selector OxlC. This 
allows far pointer access to video RAM from a 32-bit program. The following example illustrates this 
technique. 

/* 

SCREENPL.C - This example shows how to write directly 
to screen memory under the Phar Lap DOS extender. 

Compile & Link: wcl386 -l=pharlap SCREENPL 

*/ 

♦include <stdio.h> 

♦include <dos.h> 

/* 

Phar Lap allows access to screen memory through a 
special selector. Refer to "Hardware Access" in 
Phar Lap's documentation for details. 

*/ 

♦ define PL_ SCREEN_ SELECTOR Oxlc 
♦define SCREEN_ SIZE 80*25 
void main() 

{ 

/* Need a far pointer to use the screen selector */ 
char far *ptr; 
int i; 

/* Make a far pointer to screen memory */ 
ptr = MK_ FP ( PL_ SCREEN_ SELECTOR, 0 ) ; 
for( i = 0; i < SCREEN_ SIZE - 1; i++ ) { 

*ptr = '*'; 

ptr += 2 * sizeof ( char ); 

} 

} 

It is also possible to map screen memory into your near memory using Phar Lap system calls. Please refer 
to the chapter entitled "386IDOS-Extender System Calls" in Phar Lap’s 386\DOS-Extender Reference 
Manual for details. 


5.3 How do I get information about free memory in the 32-bit 
environment? 


Under a virtual memory system, programmers are often interested in the amount of physical memory they 
can allocate. Information about the amount of free memory that is available is always provided under a 
DPMI host, however, the manner in which this information is provided may differ under various 
environments. Keep in mind that in a multi-tasking environment, the information returned to your task 
from the DPMI host can easily become obsolete if other tasks allocate memory independently of your task. 
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5.3.1 Getting Free Memory Information under D0S/4GW 

D0S/4GW provides a DPMI interface through interrupt 0x31. This allows you to use DPMI service 
0x0500 to get free memory information. The following program illustrates this procedure. 

/* 

MEMORY.C - This example shows how to get information 
about free memory using DPMI call 0500h under DOS/4GW. 

Note that only the first field of the structure is 
guaranteed to contain a valid value; any field that 
is not returned by DOS/4GW is set to -1 (OFFFFFFFFh). 

Compile & Link: wcl386 -l=dos4g memory 

*/ 

♦include <i86.h> 

♦include <dos.h> 

♦include <stdio.h> 

♦define DPMI_ INT 0x31 

struct meminfo { 

unsigned LargestBlockAvail; 
unsigned MaxUnlockedPage; 
unsigned LargestLockablePage; 
unsigned LinAddrSpace; 
unsigned NumFreePagesAvail; 
unsigned NumPhysicalPagesFree; 
unsigned TotalPhysicalPages; 
unsigned FreeLinAddrSpace; 
unsigned SizeOfPageFile; 
unsigned Reserved[3]; 

} Meminfo; 

void main() 

{ 

union REGS regs; 
struct SREGS sregs; 

regs.x.eax = 0x00000500; 
memset( Ssregs, 0, sizeof(sregs) ); 

sregs.es = FP_ SEG( SMemlnfo ); 
regs.x.edi = FP_ OFF( SMemlnfo ); 
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} 


int386x( DPMI_ INT, &regs, &regs, Ssregs ); 
printf( "Largest available block (in bytes): %lu\n", 
Memlnfo.LargestBlockAvail ); 
printf ( "Maximum unlocked page allocation: %lu\n", 
Memlnfo.MaxUnlockedPage ); 
printf ( "Pages that can be allocated and locked: " 
"%lu\n", Memlnfo.LargestLockablePage ); 
printf( "Total linear address space including " 
"allocated pages: %lu\n", 

Memlnfo.LinAddrSpace ); 

printf ( "Number of free pages available: %lu\n", 

Memlnfo.NumFreePagesAvail ); 
printf ( "Number of physical pages not in use: %lu\n", 
Memlnfo.NumPhysicalPagesFree ); 
printf ( "Total physical pages managed by host: %lu\n", 
Memlnfo.TotalPhysicalPages ); 
printf ( "Free linear address space (pages): %lu\n", 
Memlnfo.FreeLinAddrSpace ); 

printf ( "Size of paging/file partition (pages): %lu\n", 
Memlnfo.SizeOfPageFile ); 


Please refer to the chapter entitled "Interrupt 31H DPMI Functions" on page 61 for more information on 
DPMI services. 


5.3.2 Getting Free Memory Information under the Phar Lap 386IDOS-Extender 

Phar Lap provides memory statistics through 386IDOS-Extender System Call 0x2520. The following 
example illustrates how to use this system call from a 32-bit program. 

/* 

MEMPLS40.C - This is an example of how to get the 
amount of physical memory present under Phar Lap 
386|DOS-Extender v4.0. 

Compile & Link: wcl386 -l=pharlap MEMPLS40 

*/ 

♦include <dos.h> 

♦include <stdio.h> 

typedef struct { 

unsigned data[25]; 

} pharlap_ mem_ status; 

/* Names suggested in Phar Lap documentation */ 

♦define APHYSPG 5 

♦define SYSPHYSPG 7 

♦define NFREEPG 21 

unsigned long memavail( void ) 

{ 

pharlap_ mem_ status status; 
union REGS regs; 
unsigned long amount; 
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regs.h.ah = 0x25; 
regs.h.al = 0x20; 
regs.h.bl = 0; 

regs.x.edx = (unsigned int) Sstatus; 
intdos( &regs, &regs ); 

/* equation is given in description for nfreepg */ 

amount = status.data[ APHYSPG ]; 

amount += status.data[ SYSPHYSPG ]; 

amount += status.data[ NFREEPG ]; 

return( amount * 4096 ); 


void main() 
{ 

printf( 

} 


"%lu bytes of memory available\n", 
memavail () ); 


Please refer to the chapter entitled "386IDOS-Extender System Calls" in Phar Lap’s 386\DOS-Extender 
Reference Manual for more information on 386IDOS-Extender System Calls. 


5.3.3 Getting Free Memory Information in the 32-bit Environment under 
Windows 3.x 

Windows 3.x provides a DPMI host that you can access from a 32-bit program. The interface to this host is 
a 16-bit interface, hence there are some considerations involved when calling Windows 3.x DPMI services 
from 32-bit code. If a pointer to a data buffer is required to be passed in ES:DI, for example, an 
AllocAliasl6() may be used to get a 16-bit far pointer that can be passed to Windows 3.x through these 
registers. Also, an int86() call should be issued rather than an int386() call. The following program 
demonstrates the techniques mentioned above. 

/* 

MEMWIN.C - This example shows how to get information 
about free memory with DPMI call 0x0500 using Windows 
as a DPMI host. Note that only the first field of the 
structure is guaranteed to contain a valid value; any 
field that is not returned by the DPMI implementation 
is set to -1 (OFFFFFFFFh). 

Compile & Link: wcl386 -l=win386 -zw memwin 
Bind: wbind -n memwin 

*/ 

#include <windows.h> 

♦include <i86.h> 

♦include <dos.h> 

♦include <stdio.h> 
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struct meminfo { 

unsigned LargestBlockAvail; 
unsigned MaxUnlockedPage; 
unsigned LargestLockablePage; 
unsigned LinAddrSpace; 
unsigned NumFreePagesAvail; 
unsigned NumPhysicalPagesFree; 
unsigned TotalPhysicalPages; 
unsigned FreeLinAddrSpace; 
unsigned SizeOfPageFile; 
unsigned Reserved[3]; 

} Meminfo; 

♦define DPMI_ INT 0x31 

void main() 

{ 

union REGS regs; 
struct SREGS sregs; 

DWORD mi_ 16 ; 

regs.w.ax = 0x0500; 
mi_16 = AllocAliasl6( SMemlnfo ); 
sregs.es = HIWORD ( mi_16 ); 
regs.x.di = LOWORD ( mi_16 ); 

int86x( DPMI_ INT, &regs, Sregs, Ssregs ); 

printf( "Largest available block (in bytes): %lu\n", 

Meminfo.LargestBlockAvail ); 
printf( "Maximum unlocked page allocation: %lu\n", 

Meminfo.MaxUnlockedPage ); 
printf ( "Pages that can be allocated and locked: " 

"%lu\n", Meminfo.LargestLockablePage ); 
printf( "Total linear address space including " 

"allocated pages: %lu\n", 

Meminfo.LinAddrSpace ); 

printf ( "Number of free pages available: %lu\n", 

Meminfo.NumFreePagesAvail ); 
printf ( "Number of physical pages not in use: %lu\n", 

Meminfo.NumPhysicalPagesFree ); 
printf ( "Total physical pages managed by host: %lu\n", 

Meminfo.TotalPhysicalPages ); 
printf( "Free linear address space (pages): %lu\n", 

Meminfo.FreeLinAddrSpace ); 

printf ( "Size of paging/file partition (pages): %lu\n", 

Meminfo.SizeOfPageFile ); 

FreeAliasl6( mi_ 16 ) ; 

} 

Please refer to the DOS Protected-Mode Interface (DPMI) Specification for information on DPMI 
services. In the past, the DPMI specification could be obtained free of charge by contacting Intel Literature 
JP26 at 800-548-4725 or by writing to the address below. We have been advised that the DPMI 
specification is no longer available in printed form. 

Intel Literature JP26 
3065 Bowers Avenue 
P.O. Box 58065 
Santa Clara, California 
U.S.A. 95051-8065 
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However, the DPMI 1.0 specification can be obtained from the Intel ftp site. Here is the URL. 

ftp: //ftp. intel. com/pub/IAL/software_ specs/dpmivl. zip 

This ZIP file contains a Postscript version of the DPMI 1.0 specification. 

5.4 How do I access the first megabyte in the extended DOS 
environment? 

Many programmers require access to the first megabyte of memory in order to look at key low memory 
addresses. Under DOS, it was standard practice to use a far pointer, with the far pointer set to the 
segmented address of the memory area that was being inspected. Under DOS extenders, this practice is not 
so standard. Each DOS extender provides its own method for accessing the first megabyte of memory. 

5.4.1 Accessing the First Megabyte under Tenberry Software D0S/4GW 

Under DOS/4GW, the first megabyte of physical memory - the real memory - is mapped as a shared linear 
address space. This allows your application to access the first megabyte of memory using a near pointer set 
to the linear address. The following program demonstrates this method. This example is similar to the 
screen memory access example. 

/* 

KEYSTAT.C - This example shows how to get the keyboard 
status under DOS/4GW by looking at the ROM BIOS 
keyboard status byte in low memory. 

Compile & Link: wcl386 -l=dos4g keystat 

*/ 

♦include <stdio.h> 

♦include <dos.h> 

/* 

Under DOS, the keyboard status byte has a segmented 
address of 0x0040:0x0017. This corresponds to a 
linear address of 0x417. 

*/ 

♦ define LOW_ AREA 0x417 

void main() 

{ 

/* Only need a near pointer in the flat model */ 
char *ptr; 

/* Set pointer to linear address of the first 
status byte */ 
ptr = (char *)LOW_AREA; 

/* Caps lock state is in bit 6 */ 
if( *ptr & 0x40 ) { 

puts( "Caps Lock on" ); 

} 
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/* Num lock state is in bit 5 */ 
if( *ptr & 0x20 ) { 

puts( "Num Lock on" ); 

} 

/* Scroll lock state is in bit 4 */ 
if( *ptr & 0x10 ) { 

puts( "Scroll Lock on" ); 

} 

} 

Please refer to the chapter entitled "Linear Executables" on page 43 for more information on how 
DOS/4GW maps the first megabyte. 

5.4.2 Accessing the First Megabyte under the Phar Lap 386IDOS-Extender 

The Phar Lap DOS extender provides access to real memory through the special segment selector 0x34. 
This allows far pointer access to the first megabyte from a 32-bit program. The following example 
illustrates this technique. 

/* 

KEYSTAPL.C - This example shows how to get the keyboard 
status under 386|DOS-Extender by looking at the ROM 
BIOS keyboard status byte in low memory. 

Compile & Link: wcl386 -l=pharlap keystapl 

*/ 

♦include <stdio.h> 

♦include <dos.h> 

/* 

Under DOS, the keyboard status byte has a segmented 
address of 0x0040:0x0017. This corresponds to a 
linear address of 0x417. 

*/ 

void main() 

{ 

/* We require a far pointer to use selector 
for 1st megabyte */ 
char far *ptr; 

/* Set pointer to segmented address of the first 
status byte */ 
ptr = MK_ FP ( 0x34, 0x417 ); 

/* Caps lock state is in bit 6 */ 
if( *ptr & 0x40 ) { 

puts( "Caps Lock on" ); 

} 

/* Num lock state is in bit 5 */ 
if( *ptr & 0x20 ) { 

puts( "Num Lock on" ); 

} 

/* Scroll lock state is in bit 4 */ 
if( *ptr & 0x10 ) { 

puts( "Scroll Lock on" ); 

} 

} 
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Please refer to the chapter entitled "Program Environment" in Phar Lap’s 386\DOS-Extender Reference 
Manual for more information on segment selectors available to your program. 

5.5 How do I spawn a protected-mode application? 

Sometimes applications need to spawn other programs as part of their execution. In the extended DOS 
environment, spawning tasks is much the same as under DOS, however it should be noted that the only 
mode supported is P_WAIT. The P_OVERLAY mode is not supported since the DOS extender cannot be 
removed from memory by the application (this is also the reason why the exec() functions are unsupported). 
The other modes are for concurrent operating systems only. 

Also, unless the application being spawned is bound or stubbed, the DOS extender must be spawned with 
the application and its arguments passed in the parameter list. 

5.5.1 Spawning Protected-Mode Applications Under Tenberry Software 
D0S/4GW 


In the case of DOS/4GW, some real-mode memory must be set aside at run time for spawning the DOS 
extender, otherwise the spawning application could potentially allocate all of system memory. The real 

memory can be reserved from within your program by assigning the global variable_ minreal the 

number of bytes to be set aside. This variable is referenced in <stdlib.h>. The following two 
programs demonstrate how to spawn a DOS/4GW application. 

/* 

SPWNRD4G.C - The following program demonstrates how to 
spawn another D0S/4GW application. 

Compile and link: wcl386 -l=dos4g spwnrd4g 

*/ 

♦include <process.h> 

♦include <stdio.h> 

♦include <stdlib.h> 


/* D0S/4GW var for WLINK MINREAL option */ 
unsigned_near_minreal = 100*1024; 

void main() 

{ 

int app2_ exit_ code; 


} 


puts( "Spawning a protected-mode application..." 

"using spawnlpO with P_ WAIT" ); 
app2_ exit_ code = spawnlp ( P_ WAIT, "dos4gw", 

"dos4gw", "spwndd4g", NULL ); 
printf ( "Application #2 returned with exit code %d\n", 

app2_ exit_ code ) ; 
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/* 

SPWNDD4G.C - Will be spawned by the SPWNRD4G program. 
Compile & Link: wcl386 -l=dos4g spwndd4g 

*/ 

♦include <stdio.h> 

♦include <stdlib.h> 

void main() 

{ 

puts( "\nApplication #2 spawned\n" ); 

/* Send back exit code 59 */ 
exit( 59 ); 

} 


5.5.2 Spawning Protected-Mode Applications Under Phar Lap 
386IDOS-Extender 


In the case of the Phar Lap 386IDOS-Extender, some real-mode memory must be set aside at link time for 
spawning the DOS extender, otherwise the spawning application will be assigned all the system memory at 
startup. This is done at link time by specifying the runtime minreal and runtime maxreal options, as 
demonstrated by the following programs. 

/* 

SPWNRPLS.C - The following program demonstrates how to 

spawn a Phar Lap application. 

Compile & Link: 

wcl386 -l=pharlap -"runt minr=300K,maxr=400K" spwnrpls 

*/ 

♦include <process.h> 

♦include <stdio.h> 


void main() 

{ 

int app2_ exit_ code; 


puts( "Spawning a protect-mode application..." 

"using spawnlpO with P_ WAIT" ); 
puts( "Spawning application ♦2..." ); 
app2_ exit_ code = spawnlp ( P_ WAIT, "run386", 

"run386", "spwndpls", NULL ); 


} 


printf ( "Application #2 returned with exit code %d", 
app2_ exit_ code ) ; 
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/* 

SPWNDPLS.C - Will be spawned by the SPWNRPLS program. 
Compile & Link: wcl386 -l=pharlap spwndpls 

*/ 

♦include <stdio.h> 

♦include <stdlib.h> 

void main() 

{ 

puts( "\nApplication #2 spawned\n" ); 

/* Exit with error code 59 */ 
exit( 59 ); 

} 


5.6 How Can I Use the Mouse Interrupt (0x33) with D0S/4GW? 

Several commonly used interrupts are automatically supported in protected mode with DOS/4GW. The 
DOS extender handles the switch from protected mode to real mode and manages any intermediate 
real-mode data buffers that are required. To use a supported interrupt, set up the register information as 
required for the interrupt and use one of the int386() or int386x() library functions to execute the interrupt. 
For calls that are not supported by DOS/4GW, you can use the DPMI function. Simulate a Real-Mode 
Interrupt (0x0300). This process is described in the next section. 

Since the mouse interrupt (0x33) is quite commonly used, DOS/4GW provides protected-mode support for 
the interrupt and any mouse data buffer that is required. The following example demonstrates how a 
programmer could use the Microsoft standard mouse interrupt (0x33) from within a DOS/4GW application. 

/* 

mouse.c - The following program demonstrates how 
to use the mouse interrupt (0x33) with DOS/4GW. 

Compile and link: wcl386 -l=dos4g mouse 

*/ 

♦include <stdio.h> 

♦include <dos.h> 

♦include <i86.h> 

/* Data touched at mouse callback time — they are 
in a structure to simplify calculating the size 
of the region to lock. 

*/ 

struct callback_ data { 


int 


right_ 

button 

int 


mouse_ 

event; 

unsigned 

short 

mouse_ 

code; 

unsigned 

short 

mouse_ 

bx; 

unsigned 

short 

mouse_ 

cx; 

unsigned 

short 

mouse_ 

dx; 

signed short 

mouse_ 

si; 

signed short 

mouse_ 

di; 


} cbd = { 0 }; 
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/* Set up data buffer for mouse cursor bitmap */ 
unsigned short cursor [] = { 

/* 16 words of screen mask */ 

0x3fff, /*0011111111111111*/ 

Oxlfff, /*0001111111111111*/ 

OxOfff, /*0000111111111111*/ 

0x07ff, /*0000011111111111*/ 

0x03ff, /*0000001111111111*/ 

OxOlff, /*0000000111111111*/ 

OxOOff, /*0000000011111111*/ 

0x007f, /*0000000001111111*/ 

OxOlff, /*0000000111111111*/ 

OxlOff, /*0001000011111111*/ 

OxbOff, /*1011000011111111*/ 

Oxf87f, /*1111100001111111*/ 

Oxf87f, /*1111100001111111*/ 

Oxfc3f, /*1111110000111111*/ 

0xfc3f, /*1111110000111111*/ 

Oxfelf, /*1111111000011111*/ 


/* 16 words of cursor mask */ 
0x0000, /*0000000000000000*/ 
0x4000, /*0100000000000000*/ 
0x6000, /*0110000000000000*/ 
0x7000, /*0111000000000000*/ 
0x7800, /*0111100000000000*/ 
0x7c00, /*0111110000000000*/ 
0x7e00, /*0111111000000000*/ 
0x7f00, /*0111111100000000*/ 
0x7c00, /*0111110000000000*/ 
0x4600, /*0100011000000000*/ 
0x0600, /*0000011000000000*/ 
0x0300, /*0000001100000000*/ 
0x0300, /*0000001100000000*/ 
0x0180, /*0000000110000000*/ 
0x0180, /*0000000110000000*/ 
OxOOcO, 7*0000000011000000*/ 


int lock_ region( void *address, unsigned length ) 

{ 

union REGS regs; 

unsigned linear; 

/* Thanks to DOS/4GW's zero-based flat memory 
model, converting a pointer of any type to 
a linear address is trivial. 

*/ 

linear = (unsigned)address; 

/* DPMI Lock Linear Region */ 
regs.w.ax = 0x600; 

/* Linear address in BX:CX */ 
regs.w.bx = (unsigned short)(linear >> 16); 
regs.w.cx = (unsigned short)(linear & OxFFFF); 
/* Length in SI:DI */ 

regs.w.si = (unsigned short)(length >> 16); 
regs.w.di = (unsigned short)(length & OxFFFF); 
int386( 0x31, &regs, &regs ); 

/* Return 0 if lock failed */ 
return( !regs.w.cflag ); 

} 


How Can I Use the Mouse Interrupt (0x33) with DOS/4GW? 


29 




DOS Programming Guide 


#pragma off ( check_ stack ) 

void _ loadds far click_ handler ( int max, int mbx, 

int mcx, int mdx, 
int msi, int mdi ) 

{ 

#pragma aux click_ handler parm [EAX] [EBX] [ECX] \ 

[EDX] [ESI] [EDI] 

cbd.mouse_ event = 1; 

cbd.mouse_ code = (unsigned short)max; 
cbd.mouse_bx = (unsigned short) mbx; 
cbd.mouse_ cx = (unsigned short)mcx; 

cbd.mouse_ dx = (unsigned short)mdx; 

cbd.mouse_ si = (signed short)msi; 

cbd.mouse_ di = (signed short)mdi; 

if ( cbd.mouse_ code & 8 ) 
cbd. right_ button = 1; 

} 

/* Dummy function so we can calculate size of 
code to lock (cbc_ end - click_ handler) . 

*/ 

void cbc_ end ( void ) 

{ 

} 

#pragma on ( check_ stack ) 

void main (void) 

{ 

struct SREGS sregs; 

union REGS inregs, outregs; 

int installed = 0; 

unsigned char orig_ mode = 0; 

unsigned short far *ptr; 
void (far *function_ ptr) (); 

segread( &sregs ); 

/* get original video mode */ 

inregs.w.ax = OxOfOO; 

int386( 0x10, Sinregs, Soutregs ); 

orig_ mode = outregs . h. al; 

/* goto graphics mode */ 

inregs.h.ah = 0x00; 
inregs.h.al = 0x6; 

int386( 0x10, Sinregs, Soutregs ); 

printf( "Previous Mode = %u\n", orig_ mode ); 
printf( "Current Mode = %u\n", inregs.h.al ); 

/* check for mouse driver */ 

inregs.w.ax = 0; 

int386( 0x33, &inregs, &outregs ); 
if( installed = (outregs.w.ax == Oxffff) ) 
printf( "Mouse installed...\n" ); 

else 

printf( "Mouse NOT installed...\n" ); 
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if( installed ) { 

/* lock callback code and data (essential under VMM!) 
note that click_ handler, although it does a far 
return and is installed using a full 48-bit pointer, 
is really linked into the flat model code segment 
— so we can use a regular (near) pointer in the 
lock_ region () call. 

*/ 

if( (! lock_ region( &cbd, sizeof( cbd ) )) |j 

(! lock_ region ( (void near *) click_ handler, 

(char *)cbc_end - (char near *) click_ handler )) ) 

{ 

printf( "locks failed\n" ) ; 

} else { 

/* show mouse cursor */ 

inregs.w.ax = Oxl; 

int386( 0x33, Sinregs, Soutregs ); 

/* set mouse cursor form */ 


inregs.w.ax = 
inregs.w.bx = 
inregs.w.cx = 
ptr = 
inregs.x.edx = 
sregs.es = 
int386x( 0x33, 


0x9; 

0x0; 

0x0; 

cursor; 

FP_ OFF ( ptr ) ; 

FP_ SEG ( ptr ) ; 
Sinregs, Soutregs, 


&sregs ); 


/* install click watcher */ 


inregs.w.ax = OxC; 
inregs.w.cx = 0x0002 + 0x0008; 

function_ ptr = ( void (far *) ( void ) ) click_ handler; 
inregs.x.edx = FP_ OFF ( function_ ptr ); 
sregs.es = FP_ SEG ( function_ ptr ); 

int386x( 0x33, Sinregs, Soutregs, Ssregs ); 


while ( ! cbd. right_ button ) { 

if ( cbd.mouse_ event ) { 

printf( "Ev %04hxh BX 


CX %hu DX %hu 


%hu 

"SI %hd DI %hd\n", 
cbd.mouse_ code, cbd.mouse_ bx, 
cbd.mouse_ cx, cbd.mouse_ dx, 
cbd.mouse_ si, cbd.mouse_ di ) ; 
cbd.mouse_ event = 0; 


/* check installation again (to clear watcher) */ 
inregs.w.ax = 0; 

int386( 0x33, Sinregs, &outregs ); 
if( outregs.w.ax == Oxffff ) 

printf( "DONE : Mouse still installed...\n" ); 

else 

printf( "DONE : Mouse NOT installed...\n" ); 

printf( "Press Enter key to return to original mode\n" ); 

getc( stdin ); 

inregs.h.ah = 0x00; 

inregs.h.al = orig_ mode; 

int386( 0x10, Sinregs, &outregs ); 
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5.7How Do I Simulate a Real-Mode Interrupt with D0S/4GW? 

Some interrupts are not supported in protected mode with DOS/4GW but they can still be called using the 
DPMI function. Simulate Real-Mode Interrupt (0x0300). Information that needs to be passed down to the 
real-mode interrupt is transferred using an information data structure that is allocated in the protected-mode 
application. The address to this protected-mode structure is passed into DPMI function 0x0300. 

DOS/4GW will then use this information to set up the real-mode registers, switch to real mode and then 
execute the interrupt in real mode. 

If your protected-mode application needs to pass data down into the real-mode interrupt, an intermediate 
real-mode buffer must be used. This buffer can be created using DPMI function 0x0100 to allocate 
real-mode memory. You can then transfer data from the protected-mode memory to the real-mode memory 
using a far pointer as illustrated in the "SIMULATE.C" example. 

The following example illustrates how to allocate some real-mode memory, transfer a string of characters 
from protected mode into the real-mode buffer, then set up and call the Interrupt 0x0021 function to create 
a directory. The string of characters are used to provide the directory name. This example can be adapted 
to handle most real-mode interrupt calls that aren't supported in protected mode. 

/* 

SIMULATE.C - Shows how to issue a real-mode interrupt 
from protected mode using DPMI call 300h. Any buffers 
to be passed to DOS must be allocated in DOS memory 
This can be done with DPMI call lOOh. This program 
will call DOS int 21, function 39h, "Create 
Directory". 

Compile & Link: wcl386 -l=dos4g simulate 

*/ 

#include <i86.h> 

#include <dos.h> 

♦include <stdio.h> 

♦include <string.h> 

static struct rminfo { 
long EDI; 
long ESI; 
long EBP; 

long reserved. by_ system; 

long EBX; 

long EDX; 

long ECX; 

long EAX; 

short flags; 

short ES,DS,FS,GS,IP,CS,SP,SS; 

} RMI; 
void main() 

{ 

union REGS regs; 
struct SREGS sregs; 
int interrupt_ no=0x31; 
short selector; 
short segment; 
char far *str; 

/* DPMI call lOOh allocates DOS memory */ 
memset(&sregs,0,sizeof(sregs)); 
regs.w.ax=0x0100; 
regs.w.bx=0x0001; 

int386x( interrupt_ no, &regs, &regs, &sregs); 
segment=regs.w.ax; 
selector=regs.w.dx; 
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/* Move string to DOS real-mode memory */ 
str=MK_ FP (selector, 0) ; 

_fstrcpy( str, "myjunk" ); 


/* Set up real-mode call structure */ 
memset(&RMI,0,sizeof(RMI)); 

RMI.EAX=0x00003900; /* call service 39h ah=0x39 */ 

RMI.DS=segment; /* put DOS segioff into DS:DX*/ 


RMI.EDX=0; /* DOS ignores EDX high word 

/* Use DPMI call 300h to issue the DOS interrupt 

regs.w.ax = 0x0300; 

regs.h.bl = 0x21; 

regs.h.bh = 0; 

regs.w.cx = 0; 

sregs.es = FP_ SEG (&RMI) ; 

regs.x.edi = FP_ OFF (&RMI) ; 

int386x( interrupt_ no, &regs, &regs, &sregs ); 


5.8 How do you install a bi-modal interrupt handler using 
DOS/4GW? 


Due to the nature of the protected-mode/real-mode interface, it is often difficult to handle high speed 
communications with hardware interrupt handlers. For example, if you install your communications 
interrupt handler in protected mode, you may find that some data is lost when transmitting data from a 
remote machine at the rate of 9600 baud. This occurs because the data arrived at the communication port 
while the machine was in the process of transferring the previous interrupt up to protected mode. Data will 
also be lost if you install the interrupt handler in real mode since your program, running in protected mode, 
will have to switch down into real mode to handle the interrupt. The reason for this is that the data arrived 
at the communication port while the DOS extender was switching between real mode and protected mode, 
and the machine was not available to process the interrupt. 

To avoid the delay caused by switching between real-mode and protected mode to handle hardware 
interrupts, install interrupt handlers in both real-mode and protected-mode. During the execution of a 
protected-mode program, the system often switches down into real-mode for DOS system calls. If a 
communications interrupt occurs while the machine is in real-mode, then the real-mode interrupt handler 
will be used. If the interrupt occurs when the machine is executing in protected-mode, then the 
protected-mode interrupt handler will be used. This enables the machine to process the hardware interrupts 
faster and avoid the loss of data caused by context switching. 

Installing the interrupt handlers in both protected-mode and real-mode is called bi-modal interrupt 
handling. The following program is an example of how to install both handlers for Interrupt OxOC (also 
known as COM1 or IRQ4). The program writes either a ’P’ to absolute address 0xB8002 or an ’R’ to 
absolute address 0xB8000. These locations are the first two character positions in screen memory for a 
color display. As the program runs, you can determine which interrupt is handling the COM1 port by the 
letter that is displayed. A mouse attached to COM1 makes a suitable demo. Type on the keyboard as you 
move the mouse around. The ESC key can be used to terminate the program. Transmitted data from a 
remote machine at 9600 baud can also be used to test the COM1 handling. 
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/* 

BIMODAL.C - The following program demonstrates how 
to set up a bi-modal interrupt handler for DOS/4GW 

Compile and link: wcl386 -l=dos4g bimodal bimo.obj 

*/ 

#include <stdio.h> 

#include <conio.h> 

#include <dos.h> 

#define D32RealSeg(P) ((((DWORD) (P)) » 4) & OxFFFF) 

#define D32RealOff(P) (((DWORD) (P)) & OxF) 

typedef unsigned int WORD; 
typedef unsigned long DWORD; 

extern void coml_ init (void) ; 

extern void _ interrupt pmhandler (void); 

extern void_interrupt_far rmhandler (void) ; 

void *D32DosMemAlloc (DWORD size) 

{ 

union REGS r; 

r.x.eax = 0x0100; /* DPMI allocate DOS memory */ 

r.x.ebx = (size + 15) » 4; /* Number of paragraphs requested */ 
int386 (0x31, &r, &r); 

if( r.x.cflag ) /* Failed */ 

return ((DWORD) 0); 

return (void *) ((r.x.eax & OxFFFF) << 4); 

} 

void main (void) 

{ 

union REGS r; 

struct SREGS sr; 

void *lowp; 

void far *fh; 

WORD orig_ pm_ sel; 

DWORD orig_pm_off; 

WORD orig_ rm_ seg; 

WORD orig_ rm_ off; 

int c; 

/* Save the starting protected-mode handler address */ 
r.x.eax = 0x350C; /* DOS get vector (INT OCh) */ 

sr.ds = sr.es = 0; 
int386x (0x21, &r, &r, &sr); 
orig_ pm_ sel = (WORD) sr.es; 
orig_ pm_ off = r.x.ebx; 

/* 

Save the starting real-mode handler address using DPMI 
(INT 31h). 

*/ 

r.x.eax = 0x0200; /* DPMI get real mode vector */ 

r.h.bl = OxOC; 

int386 (0x31, &r, &r) ; 

orig_ rm_ seg = (WORD) r.x.ecx; 

orig_ rm_ off = (WORD) r.x.edx; 

/* 

Allocate 128 bytes of DOS memory for the real-mode 
handler, which must of course be less than 128 bytes 
long. Then copy the real-mode handler into that 
segment. 

*/ 

if(! ( lowp = D32DosMemAlloc(128) ) ) { 

printf ("Couldn't get low memory!\n"); 
exit (1); 

} 

memcpy (lowp, (void *) rmhandler, 128); 
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/* 

Install the new protected-mode vector. Because INT OCh 
is in the auto-passup range, its normal "passdown" 
behavior will change as soon as we install a 
protected-mode handler. After this next call, when a 
real mode INT OCh is generated, it will be resignalled 
in protected mode and handled by pmhandler. 

*/ 

r.x.eax = 0x250C; /* DOS set vector (INT OCh) */ 

fh = (void far *) pmhandler; 
r.x.edx = FP_ OFF (fh) ; 

/* DS:EDX == &handler */ 
sr.ds = FP_ SEG (fh) ; 
sr.es = 0; 

int386x (0x21, &r, &r, &sr); 

/* 

Install the new real-mode vector. We do this after 
installing the protected-mode vector in order to 
override the "passup" behavior. After the next call, 
interrupts will be directed to the appropriate handler, 
regardless of which mode we are in when they are 
generated. 

*/ 

r.x.eax = 0x0201; 
r.h.bl = OxOC; 

/* CX:DX == real mode Shandler */ 
r.x.ecx = D32RealSeg(lowp) ; 
r.x.edx = D32RealOff(lowp); 
int386 (0x31, &r, &r) ; 

/* 

Initialize COM1. 

*/ 

coml_ init () ; 

puts( "Move mouse, transmit data; ESC to quit\n" ); 

while( 1 ) { 

if ( kbhitO ) { 

if( ( (c = getch ()) & Oxff ) == 27 ) 
break; 
putch (c); 

} 

delay ( 1 ); 

} 

/* 

Clean up. 

*/ 

r.x.eax = 0x250C; /* DOS set vector (INT OCh) */ 

r.x.edx = orig_pm_off; 

sr.ds = orig_pm_sel; /* DS:EDX == Shandler */ 
sr.es = 0; 

int386x (0x21, &r, &r, &sr); 

r.x.eax = 0x0201; /* DPMI set real mode vector */ 

r.h.bl = OxOC; 

/* CX:DX == real mode Shandler */ 
r.x.ecx = (DWORD) orig_ rm_ seg; 
r.x.edx = (DWORD) orig_rm_off; 
int386 (0x31, &r, &r) ; 

} 


You will also need to create the following assembler code module. The first part provides the interrupt 
handling routine for the real-mode interrupt handler. The second provides the protected-mode version of 
the interrupt handler. 
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• ~k ~k 

;** bimo.asm: 

;** Assembler code for real-mode and protected-mode 
;** INT OxC interrupt handlers to support the INT OxC 
;** interrupt in both modes 

• * * 

.386 
• * * 

;** The real-mode interrupt handler is in a 16-bit code 
;** segment so that the assembler will generate the right 
;** code. We will copy this code down to a 16-bit segment 
;** in low memory rather than executing it in place. 


_ TEXT16 SEGMENT BYTE PUBLIC USE16 
ASSUME csTEXT16 

PUBLIC rmhandler_ 
rmhandler_ : 

push es 

push bx 

mov bx,0B800h 

mov es,bx 

sub bx,bx 

mov WORD PTR es:[bx],0720h 

mov WORD PTR es:[bx+2],0720h 

mov BYTE PTR es:[bx],'R' 


pop 

bx 

pop 

es 

push 

ax 

push 

dx 

mov 

dx,03FAh 

in 

al, dx 

mov 

dx,03F8h 

in 

al, dx 

mov 

dx,020h 

mov 

al, dl 

out 

dx, al 

pop 

dx 

pop 

iret 

ax 


TEXT16 ENDS 


CODE' 


ES = 0xB800 
BX = 0 

Clear 2 char cells 
Write R to memory 


Read ports so 
interrupts can 
continue to be 
generated 

Send EOI 


• * * 

.** The protected-mode interrupt handler is in a 32-bit code 
;** segment. Even so, we have to be sure to force an IRETD 
;** at the end of the handler, because MASM doesn't generate 
;** one. This handler will be called on a 32-bit stack by 
;** DOS/4GW. 




.** _ DATA is the flat model data segment, which we load into 
;** ES so we can write to absolute address 0xB8000. (In the 
;** flat model, DS is based at 0.) 

_ DATA SEGMENT BYTE PUBLIC USE32 'DATA' 

_ DATA ENDS 
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DGROUP GROUP _ DATA 


TEXT SEGMENT BYTE PUBLIC USE32 'CODE' 
ASSUME cs TEXT 


PUBLIC 
coml_ init_ 
mov 
mov 
int 
mov 
lea 
in 
lea 
in 
or 
out 
lea 
in 
mov 
in 
in 
and 
out 
lea 
mov 
out 
ret 

PUBLIC 

pmhandler_ 

push 

push 

mov 

mov 

mov 

mov 

mov 

pop 

pop 

push 

push 

mov 

in 

mov 

in 

mov 

mov 

out 

pop 

pop 

iretd 


coml_ init. 


ax,0F3h 
dx, 0 
14h 

bx,03F8h 
dx,[bx+5] 
al, dx 
dx,[bx+4] 
al, dx 
al, 8 
dx, al 
dx,[bx+2] 
al, dx 
dx, bx 
al, dx 
al,21h 
al,OEFh 
21h,al 
dx,[bx+1] 
al, 1 
dx, al 

pmhandler. 


; 9600,n,8,1 
; coml 

; Initialize COM1 
; COM1 port space 
; line status reg 

; modem control reg 

; enable OUT2 int 

; int id register 

; data receive reg 

; interrupt mask reg 
; force IRQ4 unmask 

; int enable reg 

; enable received int 


es 

bx 

bx,DGROUP 
es, bx 

ebx,0B8000h ; ES:EBX=flat:0B8000h 

DWORD PTR es:[ebx],07200720h ; Clear cells 

BYTE PTR es:[ebx+2],'P' ; Write P to memory 
bx 
es 


ax 

dx 


dx, 03FAh 
al, dx 
dx,03F8h 
al, dx 
dx,020h 
al, dl 
dx, al 
dx 
ax 


Read ports so 
interrupts can 
continue to be 
generated 

Send EOI 


TEXT ENDS 
END 
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6 The Tenberry Software D0S/4GW DOS Extender 


The chapters in this section describe the 32-bit Tenberry Software DOS/4GW DOS Extender which is 
provided with the Open Watcom C/C++ package. DOS/4GW is a subset of Tenberry Software’s DOS/4G 
product. DOS/4GW is customized for use with the Open Watcom C/C++ package. Key differences are: 

• DOS/4GW will only execute programs built with a Open Watcom 32-bit compiler such as Open 
Watcom C/C++ and linked with its run-time libraries. 

• The DOS/4GW virtual memory manager (VMM), included in the package, is restricted to 32MB of 
memory. 

• DOS/4GW does not provide extra functionality such as TSR capability and VMM performance 
tuning enhancements. 

If your application has requirements beyond those provided by DOS/4GW, you may wish to acquire 
DOS/4GW Professional or DOS/4G from: 

Tenberry Software, Inc. 

PO Box 20050 

Fountain Hills, Arizona 

U.S.A 85269-0050 

WWW: http://www.tenberry.com/dos4g/ 

Email: info@tenberry.com 

Phone: 1.480.767.8868 

Fax: 1.480.767.8709 

Programs developed to use the restricted version of DOS/4GW which is included in the Open Watcom 
C/C++ package can be distributed on a royalty-free basis, subject to the licensing terms of the product. 
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7 Linear Executables 


To build a linear executable, compile and link it as described in the chapter entitled "Creating 32-bit 
DOS/4GW Executables". The resulting file will not run independently: you can run it under the Open 
Watcorn Debugger, Tenberry Software Instant-D debugger, or with the standalone "DOS4GW.EXE". 


7.1 The Linear Executable Format 


DOS/4GW works with files that use the Linear Executable (LE) file format. The format represents a 
protected-mode program in the context of a 32-bit 386 runtime environment with linear to physical address 
translation hardware enabled. It uses a flat address space. 

This file format is similar to the Segmented Executable (NE) format used in OS/2 1.x and MS Windows. 
Both support Dynamic Linking, Resources, and are geared toward protected-mode programs. Both formats 
use tables of "counted ASCII" names, and they use similar relocation formats. 

Both formats begin with a DOS style stub program that sophisticated loaders skip. This stub program 
executes when the DOS/4GW loader is not present, displaying the message. This program cannot run in 
DOS mode. 

When the Open Watcom Linker is used to link a DOS/4GW application, it automatically replaces the 
default stub program with one that calls DOS4GW. 

7.1.1 The Stub Program 

The stub at the beginning of a linear executable is a real-mode program that you can modify as you like. 

For example, you can: 

• make the stub program do a checksum on the "DOS4GW.EXE" file to make sure it’s the correct 
version. 

• copy protect your program. 

• specify a search path for the "DOS4GW.EXE" file. 

• add command line arguments. 

The SRC directory contains source code for a sample stub program. "WSTUB.C" is a simple example, a 
good base to start from when you construct your own stub. Please note that you will require a 16-bit C 
compiler to compile a new stub program. Following is the code in "WSTUB.C": 
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♦include <stdio.h> 

♦include <stdlib.h> 

♦include <process.h> 

♦include <errno.h> 

♦include <string.h> 

/* Add environment strings to be searched here */ 
char *paths_ to_ check [ ] = { 

"D0S4GPATH", 

"PATH"}; 

char *dos4g_ path() 

{ 

static char fullpath[80]; 
int i; 

for( i = 0; 

i < sizeof( paths_ to_ check ) / sizeof( paths_ to_ check[0] ); 

i++ ) { 

_ searchenvl "dos4gw.exe", paths_ to_ check[i], fullpath ); 
if( fullpath[0] ) return] sfullpath ); 

} 

for( i = 0; 

i < sizeof] paths_ to_ check ) / sizeof] paths_ to_ check[0] ); 

i++ ) { 

_ searchenv] "dos4g.exe", paths_ to_ check[i], fullpath ); 
if] fullpath[0] ) return] sfullpath ); 

} 

return] "dos4gw.exe" ); 

} 


main] int argc, char *argv[] ) 

{ 

char *av[4]; 

auto char cmdline[128]; 


av[0] = dos4g_ path(); 
av[1] = argv[0]; 
av[2] = getcmd] cmdline ); 
av[3] = NULL; 

♦ifdef QUIET 

putenv( "DOS4G=QUIET" ); 
♦endif 

execvp( av[0], av ); 
puts] "Stub exec failed:" 
puts ( av[0] ); 
puts( strerror( errno ) ) ; 

exit ( 1 ) ; 

} 


/* Locate the DOS/4G loader */ 
/* name of executable to run */ 
/* command line */ 

/* end of list */ 

/* disables DOS/4G Copyright banner */ 


/* indicate error */ 


7.2 Memory Use 

This section explains how a DOS/4GW application uses the memory on a 386-based PC/AT. The basic 
memory layout of an AT machine consists of 640KB of DOS memory, 384KB of upper memory, and an 
undetermined amount of extended memory. DOS memory and upper memory together compose real 
memory, the memory that can be addressed when the processor is running in real mode. 
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Figure 1. Basic Memory Layout 

Under DOS/4GW, the first megabyte of physical memory — the real memory — is mapped as a shared 
linear address space. This allows your application to use absolute addresses in real memory, to access 
video RAM or BIOS ROM, for example. Because the real memory is available to all processes, you are not 
guaranteed to be able to allocate a particular area in real memory: another process may have allocated it 
already. 

Most code and data is placed in a paged linear address space starting at 4MB. The linear address space 
starts at 4MB, the first address in the second page table, to avoid conflicts with VCPI system software. 

This split mapping — an executable that is linked to start at 4MB in the linear address space, with the first 
MB in the address space mapped to the first MB of physical memory — is called a split flat model. 

The illustration below shows the layout of physical memory on the left, and the layout of the linear address 
space on the right. 
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Figure 2. Physical Memory/Linear Address Space 


The 1KB label in the diagram indicates the top of the real-mode interrupt vectors. 4KB marks the end of 
the first page. 
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8 Configuring D0S/4GW 


This chapter explains various options that can be specified with the DOS4G environment variable 
including how to suppress the banner that is displayed by DOS/4GW at startup. It also explains how to use 
the DOS16M environment variable to select the switch mode setting, if necessary, and to specify the range 
of extended memory in which DOS/4GW will operate. DOS/4GW is based on Tenberry Software’s 
DOS/16M 16-bit Protected-Mode support; hence the DOS16M environment variable name remains 
unchanged. 


8.1 The D0S4G Environment Variable 

A number of options can be selected by setting the DOS4G environment variable. The syntax for setting 
options is: 

set D0S4G=optionl,option2, . . . 

Do not insert a space between DOS4G and the equal sign. A space to the right of the equal sign is optional. 
Options: 

QUIET Use this option to suppress the DOS/4GW banner. 

The banner that is displayed by DOS/4GW at startup can be suppressed by issuing the 
following command: 

set DOS4G=quiet 

Note: Use of the quiet switch is only permitted pursuant to the terms and conditions of the 
WATCOM Software License Agreement and the additional redistribution rights described 
in the Getting Started manual. Under these terms, suppression of the copyright by using 
the quiet switch is not permitted for applications which you distribute to others. 

VERBOSE Use this option to maximize the information available for postmortem debugging. 

Before running your application, issue the following command: 

set D0S4G=verbose 

Reproduce the crash and record the output. 

NULLP Use this option to trap references to the first sixteen bytes of physical memory. 

Before running your application, issue the following command: 
set D0S4G=nullp 

To select a combination of options, list them with commas as separators. 


The D0S4G Environment Variable 


47 




The D0S/4GW DOS Extender 


Example: 

set D0S4G=nullp,verbose 

8.2 Changing the Switch Mode Setting 

In almost all cases, DOS/4GW programs can detect the type of machine that is running and automatically 
choose an appropriate real- to protected-mode switch technique. For the few cases in which this default 
setting does not work we provide the DOS16M DOS environment variable, which overrides the default 
setting. 

Change the switch mode settings by issuing the following command: 
set DOS16M=value 

Do not insert a space between DOS16M and the equal sign. A space to the right of the equal sign is 
optional. 

The table below lists the machines and the settings you would use with them. Many settings have 
mnemonics, listed in the column "Alternate Name", that you can use instead of the number. Settings that 
you must set with the DOS16M variable have the notation req’d in the first column. Settings you may use 
are marked option , and settings that will automatically be set are marked auto. 


Status 

Machine 

Setting 

Alternate 

Name 

Comment 

auto 

386/486 w/ DPMI 

0 

None 

Set automatically if DPMI is active 

req'd 

NEC 98-series 

1 

9801 

Must be set for NEC 98-series 

auto 

PS/2 

2 

None 

Set automatically for PS/2 

auto 

386/486 

3 

386, 80386 

Set automatically for 386 or 486 

auto 

386 

INBOARD 

None 

386 with Intel Inboard 

req’d 

Fujitsu FMR-70 

5 

None 

Must be set for Fujitsu FMR-70 

auto 

386/486 w/ VCPI 

11 

None 

Set automatically if VCPI detected 

req’d 

Hitachi B32 

14 

None 

Must be set for Hitachi B32 

req’d 

OKI if800 

15 

None 

Must be set for OKI if800 

option 

IBM PS/55 

16 

None 

May be needed for some PS/55s 


The following procedure shows you how to test the switch mode setting. 

1. If you have one of the machines listed below, set the DOS16M environment variable to the 
value shown for that machine and specify a range of extended memory. For example, if your 
machine is a NEC 98-series, set DOS16M=1 02M-4M. See the section entitled "Fine Control 
of Memory Usage" on page 49 in this chapter for more information about setting the memory 
range. 
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Machine 

Setting 

NEC 98-series 

1 

Fujitsu FMR-60,-70 

5 

Hitachi B32 

14 

OKI if800 

15 


Before running DOS/4GW applications, check the switch mode setting by following this 
procedure: 

2. Run PMINFO and note the switch setting reported on the last line of the display. (PMINFO, 
which reports on the protected-mode resources available to your programs, is described in more 
detail in the chapter entitled "Utilities" on page 87) 

If PMINFO runs, the setting is usable on your machine. 

3. If you changed the switch setting, add the new setting to your AUTOEXEC.BAT file. 

Note: PMINFO will run successfully on 286 machines. If your DOS/4GW application does not run, and 
PMINFO does, check the CPU type reported on the first line of the display. 

You are authorized (and encouraged) to distribute PMINFO to your customers. You may also include a 
copy of this section in your documentation. 

8.3 Fine Control of Memory Usage 

In addition to setting the switch mode as described above, the DOS16M environment variable enables you 
to specify which portion of extended memory DOS/4GW will use. The variable also allows you to instruct 
DOS/4GW to search for extra memory and use it if it is present. 

8.3.1 Specifying a Range of Extended Memory 

Normally, you don't need to specify a range of memory with the DOS16M variable. You must use the 
variable, however, in the following cases: 

• You are running on a Fujitsu FMR-series, NEC 98-series, OKI if800-series or Hitachi B-series 
machine. 

• You have older programs that use extended memory but don't follow one of the standard disciplines. 

• You want to shell out of DOS/4GW to use another program that requires extended memory. 

If none of these conditions applies to you, you can skip this section. 

The general syntax is: 

set DOS16M= [switch_ mode] [@start_ address [- end_ address] ] [:size] 

In the syntax shown above, start_ address, end_ address andsize represent numbers, expressed 
in decimal or in hexadecimal (hex requires a Ox prefix). The number may end with a K to indicate an 
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address or size in kilobytes, or an M to indicate megabytes. If no suffix is given, the address or size is 
assumed to be in kilobytes. If both a size and a range are specified, the more restrictive interpretation is 
used. 


The most flexible strategy is to specify only a size. However, if you are running with other software that 
does not follow a convention for indicating its use of extended memory, and these other programs start 
before DOS/4GW, you will need to calculate the range of memory used by the other programs and specify a 
range for DOS/4GW programs to use. 


DOS/4GW ignores specifications (or parts of specifications) that conflict with other information about 
extended memory use. Below are some examples of memory usage control: 


set DOS16M= 1 @2m-4m 

set DOS16M= :1M 

set DOS16M= @2m 
set DOS16M= @ 0 - 5m 


Mode 1, for NEC 98-series machines, and use extended memory 
between 2.0 and 4.0MB. 

Use the last full megabyte of extended memory, or as much as 
available limited to 1MB. 

Use any extended memory available above 2MB. 

Use any available extended memory from 0.0 (really 1.0) to 
5.0MB. 


set DOS16M= :0 


Use no extended memory. 


As a default condition DOS/4GW applications take all extended memory that is not otherwise in use. 
Multiple DOS/4GW programs that execute simultaneously will share the reserved range of extended 
memory. Any non-DOS/4GW programs started while DOS/4GW programs are executing will find that 
extended memory above the start of the DOS/4GW range is unavailable, so they may not be able to run. 
This is very safe. There will be a conflict only if the other program does not check the BIOS configuration 
call (Interrupt 15H function 88H, get extended memory size). 


To create a private pool of extended memory for your DOS/4GW application, use the PRIVATXM 
program, described in the chapter entitled "Utilities" on page 87. 


The default memory allocation strategy is to use extended memory if available, and overflow into DOS 
(low) memory. 


In a VCPI or DPMI environment, the start_ address andend_ address arguments are not 
meaningful. DOS/4GW memory under these protocols is not allocated according to specific addresses 
because VCPI and DPMI automatically prevent address conflicts between extended memory programs. 
You can specify a size for memory managed by VCPI or DPMI, but DOS/4GW will not necessarily 
allocate this memory from the highest available extended memory address, as it does for memory managed 
under other protocols. 


8.3.2 Using Extra Memory 

Some machines contain extra non-extended, non-conventional memory just below 16MB. When 
DOS/4GW runs on a Compaq 386, it automatically uses this memory because the memory is allocated 
according to a certain protocol, which DOS/4GW follows. Other machines have no protocol for allocating 
this memory. To use the extra memory that may exist on these machines, set DOS16M with the + option. 

set DOS16M=+ 
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Setting the + option causes DOS/4GW to search for memory in the range from FA0000 to FFFFFF and 
determine whether the memory is usable. DOS/4GW does this by writing into the extra memory and 
reading what it has written. In some cases, this memory is mapped for DOS or BIOS usage, or for other 
system uses. If DOS/4GW finds extra memory that is mapped this way, and is not marked read-only, it will 
write into that memory. This will cause a crash, but won’t have any other effect on your system. 


8.4 Setting Runtime Options 

The DOS16M environment variable sets certain runtime options for all DOS/4GW programs running on the 

same system. 

To set the environment variable, the syntax is: 

set DOS16M= [ switch_ mode_ setting] ''options . 

Note: Some command line editing TSRs, such as CED, use the caret ( A ) as a delimiter. If you want to set 

DOS16M using the syntax above while one of these TSRs is resident, modify the TSR to use a different 

delimiter. 

These are the options: 

0x01 check A20 line — This option forces DOS/4GW to wait until the A20 line is enabled before 

switching to protected mode. When DOS/4GW switches to real mode, this option suspends 
your program’s execution until the A20 line is disabled, unless an XMS manager (such as 
HIMEM.SYS) is active. If an XMS manager is running, your program’s execution is 
suspended until the A20 line is restored to the state it had when the CPU was last in real 
mode. Specify this option if you have a machine that runs DOS/4G W hut is not truly 
AT-compatible. For more information on the A20 line, see the section entitled 
"Controlling Address Line 20" on page 52. 

0x02 prevent initialization ofVCPI — By default, DOS/4GW searches for a VCPI server and, if 

one is present, forces it on. This option is useful if your application does not use EMS 
explicitly, is not a resident program, and may be used with 386-based EMS simulator 
software. 

0x04 directly pass down keyboard status calls — When this option is set, status requests are 

passed down immediately and unconditionally. When disabled, pass-downs are limited so 
the 8042 auxiliary processor does not become overloaded by keyboard polling loops. 

0x10 restore only changed interrupts — Normally, when a DOS/4GW program terminates, all 

interrupts are restored to the values they had at the time of program startup. When you use 
this option, only the interrupts changed by the DOS/4GW program are restored. 

0x20 set new memory to 00 -- When DOS/4GW allocates a new segment or increases the size of a 

segment, the memory is zeroed. This can help you find bugs having to do with 
uninitialized memory. You can also use it to provide a consistent working environment 
regardless of what programs were run earlier. This option only affects segment allocations 
or expansions that are made through the DOS/4GW kerne I (with DOS function 48H or 
4AH). This option does not affect memory allocated with a compiler’s malloc function. 

0x40 set new memory to FF — When DOS/4GW allocates a new segment or increases the size of 

a segment, the memory is set to OxFF bytes. This is helpful in making reproducible cases 
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of bugs caused by using uninitialized memory. This option only affects segment 
allocations or expansions that are made through the DOS/4GW kernel (with DOS function 
48H or 4AH). This option does not affect memory allocated with a compiler’s malloc 
function. 

0x80 new selector rotation — When DOS/4GW allocates a new selector, it usually looks for the 

first available (unused) selector in numerical order starting with the highest selector used 
when the program was loaded. When this option is set, the new selector search begins after 
the last selector that was allocated. This causes new selectors to rotate through the range. 
Use this option to find references to stale selectors, i.e., segments that have been cancelled 
or freed. 


8.5 Controlling Address Line 20 

This section explains how DOS/4GW uses address line 20 (A20) and describes the related DOS16M 
environment variable settings. It is unlikely that you will need to use these settings. 

Because the 8086 and 8088 chips have 20-bit address spaces, their highest addressable memory location is 
one byte below 1MB. If you specify an address at 1MB or over, which would require a twenty-first bit to 
set, the address wraps back to zero. Some parts of DOS depend on this wrap, so on the 286 and 386, the 
twenty-first address bit is disabled. To address extended memory, DOS/4GW enables the twenty-first 
address bit (the A20 line). The A20 line must be enabled for the CPU to run in protected mode, but it may 
be either enabled or disabled in real mode. 

By default, when DOS/4GW returns to real mode, it disables the A20 line. Some software depends on the 
line being enabled. DOS/4GW recognizes the most common software in this class, the XMS managers 
(such as HIMEM.SYS), and enables the A20 line when it returns to real mode if an XMS manager is 
present. For other software that requires the A20 line to be enabled, use the A2 0 option. The A2 0 option 
makes DOS/4GW restore the A20 line to the setting it had when DOS/4GW switched to protected mode. 

Set the environment variable as follows: 

set DOS16M=A20 

To specify more than one option on the command line, separate the options with spaces. 

The DOS16M variable also lets you to specify the length of the delay between a DOS/4GW instruction to 
change the status of the A20 line and the next DOS/4GW operation. By default, this delay is 1 loop 
instruction when DOS/4GW is running on a 386 machine. In some cases, you may need to specify a longer 
delay for a machine that will run DOS/4GW but is not truly AT-compatible. To change the delay, set 
DOS16M to the desired number of loop instructions, preceded by a comma: 

set DOS16M=,loops 


52 


Controlling Address Line 20 




9 VMM 


The Virtual Memory Manager (VMM) uses a swap file on disk to augment RAM. With VMM you can use 
more memory than your machine actually has. When RAM is not sufficient, part of your program is 
swapped out to the disk file until it is needed again. The combination of the swap file and available RAM 
is the virtual memory. 

Your program can use VMM if you set the DOS environment variable, DOS4GVM, as follows. To set the 
DOS4GVM environment variable, use the format shown below. 

set D0S4GVM= [option[#value]] [option[#value]] 

A "#" is used with options that take values since the DOS command shell will not accept "=". 

If you set DOS4GVM equal to 1, the default parameters are used for all options. 

Example: 

C>set D0S4GVM=1 


9.1 VMM Default Parameters 


VMM parameters control the options listed below. 


MINMEM 

MAXMEM 

SWAPMIN 

SWAPINC 


The minimum amount of RAM managed by VMM. The default is 512KB. 

The maximum amount of RAM managed by VMM. The default is 4MB. 

The minimum or initial size of the swap file. If this option is not used, the size of the 
swap file is based on VIRTUALSIZE (see below). 

The size by which the swap file grows. 


SWAPNAME The swap file name. The default name is "DOS4GVM.SWP". By default the file is in 
the root directory of the current drive. Specify the complete path name if you want to 
keep the swap file somewhere else. 


DELETESWAP Whether the swap file is deleted when your program exits. By default the file is not 
deleted. Program startup is quicker if the file is not deleted. 


VIRTU ALSIZE The size of the virtual memory space. The default is 16MB. 


VMM Default Parameters 
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9.2 Changing the Defaults 

You can change the defaults in two ways. 

1. Specify different parameter values as arguments to the DOS4GVM environment variable, as 
shown in the example below. 

set DOS4GVM=deleteswap maxmem#8192 

2. Create a configuration file with the filetype extension ".VMC", and use that as an argument to 
the DOS4GVM environment variable, as shown below. 

set DOS4GVM=@NEW4G.VMC 

9.2.1 The. VMC File 

A ".VMC" file contains VMM parameters and settings as shown in the example below. Comments are 
permitted. Comments on lines by themselves are preceded by an exclamation point (!). Comments that 
follow option settings are preceded by white space. Do not insert blank lines: processing stops at the first 
blank line. 

!Sample .VMC file 

!This file shows the default parameter values. 

minmem = 512 At least 512K bytes of RAM is required, 

maxmem = 4096 Uses no more than 4MB of RAM 

virtualsize = 16384 Swap file plus allocated memory is 16MB 

!To delete the swap file automatically when the program exits, add 
!deleteswap 

!To store the swap file in a directory called SWAPFILE, add 
!swapname = c:\swapfile\dos4gvm.swp 
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10 Interrupt 21H Functions 


When you call an Interrupt 21H function under DOS/4GW, the 32-bit registers in which you pass values are 
translated into the appropriate 16-bit registers, since DOS works only with 16 bits. However, you can use 
32-bit values in your DOS calls. You can allocate blocks of memory larger than 64KB or use an address 
with a 32-bit offset, and DOS/4GW will translate the call appropriately, to use 16-bit registers. When the 
Interrupt 21H function returns, the value is widened - placed in a 32-bit register, with the high order bits 
zeroed. 

DOS/4GW uses the following rules to manage registers: 

• When you pass a parameter to an Interrupt 21H function that expects a 16-bit quantity in a general 
register (for example, AX), pass a 32-bit quantity in the corresponding extended register (for 
example, EAX). When a DOS function returns a 16-bit quantity in a general register, expect to 
receive it (with high-order zero bits) in the corresponding extended register. 

• When an Interrupt 21H function expects to receive a 16:16 pointer in a segment:general register pair 
(for example, ES:BX), supply a 16:32 pointer using the same segment register and the corresponding 
extended general register (ES:EBX). DOS/4GW will copy data and translate pointers so that DOS 
ultimately receives a 16:16 real-mode pointer in the correct registers. 

• When DOS returns a 16:16 real-mode pointer, DOS/4GW translates the segment value into an 
appropriate protected-mode selector and generates a 32-bit offset that results in a 16:32 pointer to the 
same location in the linear address space. 

• Many DOS functions return an error code in AX if the function fails. DOS/4GW checks the status of 
the carry flag, and if it is set, indicating an error, zero-extends the code for EAX. It does not change 
any other registers. 

• If the value is passed or returned in an 8-bit register (AL or AH, for example), DOS/4GW puts the 
value in the appropriate location and leaves the upper half of the 32-bit register untouched. 

The table below lists all the Interrupt 21h functions. For each, it shows the registers that are widened or 
narrowed. Footnotes provide additional information about some of the interrupts that require special 
handling. Following the table is a section that provides a detailed explanation of interrupt handling under 
DOS/4GW. 
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Function 

Purpose 

Managed Registers 

00H 

Terminate Process 

None 

OlH 

Character Input with Echo 

None 

02H 

Character Output 

None 

03H 

Auxiliary Input 

None 

04H 

Auxiliary Output 

None 

05 H 

Print Character 

None 

06H 

Direct Console I/O 

None 

07H 

Unfiltered Character Input Without Echo 

None 

08H 

Character Input Without Echo 

None 

09H 

Display String 

EDX 

OAH 

Buffered Keyboard Input 

EDX 

OBH 

Check Keyboard Status 

None 

OCH 

Flush Buffer, Read Keyboard 

EDX 

ODH 

Disk Reset 

None 

OEH 

Select Disk 

None 

OFH 

Open File with FCB 

EDX 

10H 

Close File with FCB 

EDX 

11H 

Find First File 

EDX 

12H 

Find Next File 

EDX 

13H 

Delete File 

EDX 

14H 

Sequential Read 

EDX 

15H 

Sequential Write 

EDX 

16H 

Create File with FCB 

EDX 

17H 

Rename File 

EDX 

19H 

Get Current Disk 

None 

1AH 

Set DTA Address 

EDX 

1BH 

Get Default Drive Data 

Returns in EBX, ECX, and EDX 

1CH 

Get Drive Data 

Returns in EBX, ECX, and EDX 

21H 

Random Read 

EDX 

22H 

Random Write 

EDX 

23H 

Get File Size 

EDX 

24H 

Set Relative Record 

EDX 

25H 

Set Interrupt Vector 

EDX 

26H 

Create New Program Segment Prefix 

None 

27H 

Random Block Read 

EDX, returns in ECX 

28H 

Random Block Write 

EDX, returns in ECX 

29H 

Parse Filename ESI, EDI, returns in EAX, ESI and EDI (1.) 

2AH 

Get Date 

Returns in ECX 

2BH 

Set Date 

None 

2CH 

Get Time 

None 

2DH 

Set Time 

None 

2EH 

Set/Reset Verify Flag 

None 

2FH 

Get DTA Address 

Returns in EBX 

30H 

Get MS-DOS Version Number 

Returns in ECX 

31H 

Terminate and Stay Resident 

None 

33H 

Get/Set Control-C Check Flag 

None 

34H 

Return Address of InDOS Flag 

Returns in EBX 

35H 

Get Interrupt Vector 

Returns in EBX 

36H 

Get Disk Free Space 

Returns in EAX, EBX, ECX, and EDX 
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38H 


Get/Set Current Country 

EDX, returns in EBX 

39H 


Create Directory 

EDX 

3AH 


Remove Directory 

EDX 

3BH 


Change Current Directory 

EDX 

3CH 


Create File with Flandle 

EDX, returns in EAX 

3DH 


Open File with Flandle 

EDX, returns in EAX 

3EH 


Close File 

None 

3FH 


Read File or Device 

EBX, ECX, EDX, returns in EAX (2.) 

40H 


Write File or Device 

EBX, ECX, EDX, returns in EAX (2.) 

41H 


Delete File 

EDX 

42H 


Move File Pointer 

Returns in EDX, EAX 

43H 


Get/Set File Attribute 

EDX, returns in ECX 

44H 


IOCTL 

(3.) 


00H 

Get Device Information 

Returns in EDX 


01H 

SetDevice Information 

None 


02H 

Read Control Data from CDD 

EDX, returns in EAX 


03H 

Write Control Data to CDD 

EDX, returns in EAX 


04H 

Read Control Data from BDD 

EDX, returns in EAX 


05 H 

Write Control Data to BDD 

EDX, returns in EAX 


06H 

Check Input Status 

None 


07 H 

Check Output Status 

None 


08H 

Check if Block Device is Removeable 

Returns in EAX 


09H 

Check if Block Device is Remote 

Returns in EDX 


OAH 

Check if Flandle is Remote 

Returns in EDX 


OBH 

Change Sharing Retry Count 

None 


OCH 

Generic I/O Control for Character Devices EDX 


ODH 

Generic I/O Control for Block Devices 

EDX 


OEH 

Get Logical Drive Map 

None 


OFH 

Set Logical Drive Map 

None 

45 H 


Duplicate File Flandle 

Returns in EAX 

46H 


Force Duplicate File Flandle 

None 

47 H 


Get Current Directory 

ESI 

48H 


Allocate Memory Block 

Returns in EAX 

49H 


Free Memory Block 

None 

4AH 


Resize Memory Block 

None 

4BH 


Load and Execute Program (EXEC) 

EBX, EDX (4.) 

4CH 


Terminate Process with Return Code 

None 

4DH 


Get Return Code of Child Process 

None 

4EH 


Find First File 

EDX 

4FH 


Find Next File 

None 


52H Get List of Lists 

54H Get Verify Flag 

56H Rename File 

57H Get/Set Date/Time of File 

58H Get/Set Allocation Strategy 

59H Get Extended Error Information 

5AH Create Temporary File 

5BH Create New File 

5CH Lock/Unlock File Region 

5EH Network Machine Name/Printer Setup 

00H Get Machine Name 
02H Set Printer Setup String 


(not supported) 
None 
EDX, EDI 
Returns in ECX, and EDX 
Returns in EAX 
Returns in EAX 
EDX, returns in EAX and EDX 
EDX, returns in EAX 
None 

EDX 

ESI 


Interrupt 21H Functions 57 




The D0S/4GW DOS Extender 


03H Get Printer Setup String 
5FH Get/Make Assign List Entry 

02H Get Redirection List Entry 
03H Redirect Device 
04H Cancel Device Redirection 


EDI, returns in ECX 

ESI, EDI, returns in ECX 
ESI, EDI 
ESI 


62H Get Program Segment Prefix Address 

63H Get Lead Byte Table (version 2.25 only) 

65H Get Extended Country Information 

66H Get or Set Code Page 

67H Set Handle Count 


Returns in EBX 
Returns in ESI 
EDI 
None 
None 


This list of functions is excerpted from The MS-DOS Encyclopedia, Copyright (c) 1988 by Microsoft Press. 

All Rights Reserved. 

1. For Function 29H, DS:ESI and ES:EDI contain pointer values that are not changed by the call. 

2. You can read and write quantities larger than 64KB with Functions 3FH and 40H. DOS/4GW 
breaks your request into chunks smaller than 64KB, and calls the DOS function once for each 
chunk. 

3. You can’t transfer more than 64KB using Function 44h, subfunctions 02H, 03H, 04H, or 05H. 
DOS/4GW does not break larger requests into DOS-sized chunks, as it does for Functions 3FH 
and 40H. 

4. When you call Function 4B under DOS/4GW, you pass it a data structure that contains 16:32 bit 
pointers. DOS/4GW translates these into 16:16 bit pointers in the structure it passes to DOS. 


10.1 Functions 25H and 35H: Interrupt Handling in Protected 
Mode 


By default, interrupts that occur in protected mode are passed down: the entry in the IDT points to code in 
DOS/4GW that switches the CPU to real mode and resignals the interrupt. If you install an interrupt 
handler using Interrupt 21H, Function 25H, that handler will get control of any interrupts that occur while 
the processor is in protected mode. If the interrupt for which you installed the handler is in the autopassup 
range, your handler will also get control of interrupts signalled in real mode. 

The autopassup range runs from 08H to 2EH inclusive, but excluding 21H. If the interrupt is in the 
autopassup range, the real-mode vector will be modified when you install the protected-mode handler to 
point to code in the DOS/4GW kernel. This code switches the processor to protected mode and resignals 
the interrupt-where your protected-mode handler will get control. 

10.1.132-Bit Gates 

The DOS/4GW kernel always assigns a 32-bit gate for the interrupt handlers it installs. It does not 
distinguish between 16-bit and 32-bit handlers for consistency with DPMI. 

This 32-bit gate points into the DOS/4GW kernel. When DOS/4GW handles the interrupt, it switches to its 
own 16-bit stack, and from there it calls the interrupt handler (yours or the default). This translation is 
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transparent to the handler, with one exception: since the current stack is not the one on which the interrupt 
occurred, the handler cannot look up the stack for the address at which the interrupt occurred. 

10.1.2 Chaining 16-bit and 32-bit Handlers 

If your program hooks an interrupt, write a normal service routine that either handles the interrupt and 
IRETs or chains to the previous handler. As part of handling the interrupt, your handler can PUSHF/CALL 
to the previous handler. The handler must IRET (or IRETD) or chain. 

For each protected-mode interrupt, DOS/4GW maintains separate chains of 16-bit and 32-bit handlers. If 
your 16-bit handler chains, the previous handler is a 16-bit program. If your 32-bit handler chains, the 
previous handler is a 32-bit program. 

If a 16-bit program hooks a given interrupt before any 32-bit programs hook it, the 16-bit chain is executed 
first. If all the 16-bit handlers unhook later and a new 16-bit program hooks the interrupt while 32-bit 
handlers are still outstanding, the 32-bit handlers will be executed first. 

If the first program to hook an interrupt is 32-bit, the 32-bit chain is executed first. 

10.1.3 Getting the Address of the Interrupt Handler 

When you signal Interrupt 21H, Function 35, it always returns a non-null address even if no other program 
of your bitness (i.e., 16-bit or 32-bit) has hooked the interrupt. The address points to a dummy handler that 
looks to you as though it does an IRET to end the chain. This means that you can’t find an unused interrupt 
by looking for a NULL pointer. Since this technique is most frequently used by programs that are looking 
for an unclaimed real-mode interrupt on which to install a TSR, it shouldn’t cause you problems. 
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111nterrupt 31H DPMI Functions 


When a D0S/4GW application runs under a DPMI host, such as Windows 3.1 in enhanced mode, an OS/2 
virtual DOS machine, 386Max (with DEBUG=DPMIXCOPY), or QEMM/QDPMI (with EXTCHKOFF), 
the DPMI host provides the DPMI services, not DOS/4GW. The DPMI host also provides virtual memory, 
if any. Performance (speed and memory use) under different DPMI hosts varies greatly due to the quality 
of the DPMI implementation. 

DPMI services are accessed using Interrupt 31H. 

The following describes the services provided by DOS/4GW and DOS/4GW Professional in the absence of 
a DPMI host. DOS/4GW supports many of the common DPMI system services. Not all of the services 
described below are supported by other DPMI hosts. 

Some of the information in this chapter was obtained from the the DOS Protected-Mode Interface (DPMI) 
specification. It is no longer in print; however the DPMI 1.0 specification can be obtained from the Intel 
ftp site. Here is the URL. 

ftp: //ftp. intel. com/pub/IAL/software_ specs/dpmivl. zip 


This ZIP file contains a Postscript version of the DPMI 1.0 specification. 

11.1 Using Interrupt 31H Function Calls 

Interrupt 31H DPMI function calls can be used only by protected-mode programs. 

The general ground rules for Interrupt 31H calls are as follows: 

• All Interrupt 31H calls modify the AX register. Unsupported or unsuccessful calls return an error 
code in AX. Other registers are saved unless they contain specified return values. 

• All Interrupt 31H calls modify flags: Unsupported or unsuccessful calls return with the carry flag 
set. Successful calls clear the carry flag. Only memory management and interrupt flag management 
calls modify the interrupt flag. 

• Memory management calls can enable interrupts. 

• All calls are reentrant. 

The flag and register information for each call is listed in the following descriptions of supported Interrupt 

31H function calls. 
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11.2 lnt31H Function Calls 

The Interrupt 31H subfunction calls supported by DOS/4GW are listed below by category: 

• Local Descriptor Table (LDT) management services 

• DOS memory management services 

• Interrupt services 

• Translation services 

• DPMI version 

• Memory management services 

• Page locking services 

• Demand paging performance tuning services 

• Physical address mapping 

• Virtual interrupt state functions 

• Vendor specific extensions 

• Coprocessor status 

Only the most commonly used Interrupt 31H function calls are supported in this version. 

11.2.1 Local Descriptor Table (LDT) Management Services 

Function 0000H This function allocates a specified number of descriptors from the LDT and returns the 
base selector. Pass the following information: 

AX = 0000H 

CX = number of descriptors to be allocated 

If the call succeeds, the carry flag is clear and the base selector is returned in AX. If the 
call fails, the carry flag is set. 

An allocated descriptor is set to the present data type, with a base and limit of zero. The 
privilege level of an allocated descriptor is set to match the code segment privilege level of 
the application. To find out the privilege level of a descriptor, use the lar instruction. 

Allocated descriptors must be filled in by the application. If more than one descriptor is 
allocated, the returned selector is the first of a contiguous array. Use Function 0003H to 
get the increment for the next selector in the array. 

Function 0001H This function frees the descriptor specified. Pass the following information: 
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ax = 0001H 

BX = the selector to free 

Use the selector returned with function OOOOh when the descriptor was allocated. To free 
an array of descriptors, call this function for each descriptor. Use Function 0003H to find 
out the increment for each descriptor in the array. 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. 

You can use this function to free the descriptors allocated for the program’s initial CS, DS, 
and SS segments, but you should not free other segments that were not allocated with 
Function OOOOH or Function 000DH. 

Function 0002H This function converts a real-mode segment to a descriptor that a protected-mode 
program can address. Pass the following information: 

AX = 0002H 

BX = real-mode segment address 

If the call succeeds, it clears the carry flag and returns the selector mapped to the real-mode 
segment in AX. If the call fails, the carry flag is set. 

If you call this function more than once with the same real-mode segment address, you get 
the same selector value each time. The descriptor limit is set to 64KB. 

The purpose of this function is to give protected-mode programs easy access to commonly 
used real-mode segments. However, because you cannot modify or free descriptors created 
by this function, it should be used infrequently. Do not use this function to get descriptors 
for private data areas. 

To examine real-mode addresses using the same selector, first allocate a descriptor, and 
then use Function 0007H to change the linear base address. 

Function 0003H This function returns the increment value for the next selector. Use this function to get 
the value you add to the base address of an allocated array of descriptors to get the next 
selector address. Pass the following information: 

AX = 0003H 

This call always succeeds. The increment value is returned in AX. This value is always a 
power of two, but no other assumptions can be made. 

Function 0006H This function gets the linear base address of a selector. Pass the following information: 

AX = 0006H 
BX = selector 

If the call succeeds, the carry flag is clear and CX:DX contains the 32-bit linear base 
address of the segment. If the call fails, it sets the carry flag. 

If the selector you specify in BX is invalid, the call fails. 

Function 0007H This function changes the base address of a specified selector. Only descriptors allocated 
through Function OOOOH should be modified. Pass the following information: 
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AX = 0007H 
BX = selector 

CX:DX = the new 32-bit linear base address for the segment 

If the call succeeds, the carry flag is clear; if unsuccessful, the carry flag is set. 

If the selector you specify in BX is invalid, the call fails. 

Function 0008H This function sets the upper limit of a specified segment. Use this function to modify 
descriptors allocated with Function 0000H only. Pass the following information: 

AX = 0008H 
BX = selector 

CX:DX = 32-bit segment limit 

If the call succeeds, the carry flag is clear; if unsuccessful, the carry flag is set. 

The call fails if the specified selector is invalid, or if the specified limit cannot be set. 

Segment limits greater than 1MB must be page-aligned. This means that limits greater than 
1MB must have the low 12 bits set. 

To get the limit of a segment, use the 32-bit form of lsl for segment limits greater than 
64KB. 

Function 0009H This function sets the descriptor access rights. Use this function to modify descriptors 
allocated with Function 0000H only. To examine the access rights of a descriptor, use the 
lar instruction. Pass the following information: 

AX = 0009H 
BX = selector 

CL = Access rights/type byte 

CH = 386 extended access rights/type byte 

If the call succeeds, the carry flag is clear; if unsuccessful, the carry flag is set. If the 
selector you specify in BX is invalid, the call fails. The call also fails if the access 
rights/type byte does not match the format and meet the requirements shown in the figures 
below. 
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The access rights/type byte passed in CL has the format shown in the figure below. 


p 

DPL 

1 

C/D 

E/C 

W/R 

A 

7 

6 5 

4 

3 

2 

1 

0 


* 

0 => Not accessed 
v 1 => Accessed 

Data: 0 => Read, 1=> R/W 
, r Code: Must be 1 (readable) 

Data: 0=> Exp-up, 1=> Exp-dn 
v Code: Must be 0 (non-conform) 

0 => Data, 1=> Code 


Must be 1 


Must equal caller’s CPL 


0 = > Absent, 1=> Present 


Figure 3. Access Rights/Type 
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The extended access rights/type byte passed in CH has the following format. 


G 

B/D 

0 

Avl 

Reserved 

7 

6 

5 

4 

3 2 10 


Ignored 


▼ 

Can be 0 or 1 

▼ 

Must be 0 

▼ 

0 => Default 16-bit., 1=> Default 32-bit 

T 

0 => Byte Granular, 1=> Page Granular 


Figure 4. Extended Access Rights/Type 

Function 000AH This function creates an alias to a code segment. This function creates a data descriptor 
that has the same base and limit as the specified code segment descriptor. Pass the 
following information: 

AX = 000AH 

BX = code segment selector 

If the call succeeds, the carry flag is clear and the new data selector is returned in AX. If 
the call fails, the carry flag is set. The call fails if the selector passed in BX is not a valid 
code segment. 

To deallocate an alias to a code segment, use Function 0001H. 

After the alias is created, it does not change if the code segment descriptor changes. For 
example, if the base or limit of the code segment change later, the alias descriptor stays the 
same. 

Function 000BH This function copies the descriptor table entry for a specified descriptor. The copy is 
written into an 8-byte buffer. Pass the following information: 

AX = 000BH 
BX = selector 

ES:EDI = a pointer to the 8-byte buffer for the descriptor copy 
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If the call succeeds, the carry flag is clear and ES:ED1 contains a pointer to the buffer that 
contains a copy of the descriptor. If the call fails, the carry flag is set. The call fails if the 
selector passed in BX is invalid or unallocated. 

Function 000CH This function copies an 8-byte buffer into the LDT for a specified descriptor. The 
descriptor must first have been allocated with Function 0000H. Pass the following 
information: 

AX = 000CH 
BX = selector 

ES:EDI = a pointer to the 8-byte buffer containing the descriptor 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. The call fails if 
the descriptor passed in BX is invalid. 

The type byte, byte 5, has the same format and requirements as the access rights/type byte 
passed to Function 0009H in CL. The format is shown in the first figure presented with the 
description of Function 0009H. 

The extended type byte, byte 6, has the same format and requirements as the extended 
access rights/type byte passed to Function 0009H in CH, except that the limit field can have 
any value, and the low order bits marked reserx’ed are used to set the upper 4 bits of the 
descriptor limit. The format is shown in the second figure presented with the description of 
Function 0009H. 

Function 000DH This function allocates a specific LDT descriptor. Pass the following information: 

AX = 000DH 
BX = selector 

If the call succeeds, the carry flag is clear and the specified descriptor is allocated. If the 
call fails, the carry flag is set. 

The call fails if the specified selector is already in use, or if it is not a valid LDT descriptor. 
The first lOh (16 decimal) descriptors are reserved for this function, and should not be used 
by the host. Some of these descriptors may be in use, however, if another client application 
is already loaded. 

To free the descriptor, use Function 0001H. 

11.2.2 DOS Memory Management Services 

Function 0100H This function allocates memory from the DOS free memory pool. This function returns 
both the real-mode segment and one or more descriptors that can be used by 
protected-mode applications. Pass the following information: 

AX = 0100H 

BX = the number of paragraphs (16-byte blocks) requested 

If the call succeeds, the carry flag is clear. AX contains the initial real-mode segment of 
the allocated block and DX contains the base selector for the allocated block. 
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If the call fails, the carry flag is set. AX contains the DOS error code. If memory is 
damaged, code 07H is returned. If there is not enough memory to satisfy the request, code 
08H is returned. BX contains the number of paragraphs in the largest available block of 
DOS memory. 

If you request a block larger than 64KB, contiguous descriptors are allocated. Use 
Function 0003H to find the value of the increment to the next descriptor. The limit of the 
first descriptor is set to the entire block. Subsequent descriptors have a limit of 64KB, 
except for the final descriptor, which has a limit of blocksize MOD 64KB. 

You cannot modify or deallocate descriptors allocated with this function. Function 101H 
deallocates the descriptors automatically. 

Function 0101H This function frees a DOS memory block allocated with function 0100H. Pass the 
following information: 

AX = 0101H 

DX = selector of the block to be freed 

If the call succeeds, the carry flag is clear. 

If the call fails, the carry flag is set and the DOS error code is returned in AX. If the 
incorrect segment was specified, code 09H is returned. If memory control blocks are 
damaged, code 07H is returned. 

All descriptors allocated for the specified memory block are deallocated automatically and 
cannot be accessed correctly after the block is freed. 

Function 0102H This function resizes a DOS memory block allocated with function 0100H. Pass the 
following information: 

AX = 0102H 

BX = the number of paragraphs (16-byte blocks) in the resized block 
DX = selector of block to resize 

If the call succeeds, the carry flag is clear. 

If the call fails, the carry flag is set, the maximum number of paragraphs available is 
returned in BX, and the DOS error code is returned in AX. If memory code blocks are 
damaged, code 07H is returned. If there isn’t enough memory to increase the size as 
requested, code 08H is returned. If the incorrect segment is specified, code 09h is returned. 

Because of the difficulty of finding additional contiguous memory or descriptors, this 
function is not often used to increase the size of a memory block. Increasing the size of a 
memory block might well fail because other DOS allocations have used contiguous space. 
If the next descriptor in the LDT is not free, allocation also fails when the size of a block 
grows over the 64KB boundary. 

If you shrink the size of a memory block, you may also free some descriptors allocated to 
the block. The initial selector remains unchanged, however; only the limits of subsequent 
selectors will change. 
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11.2.3 Interrupt Services 

Function 0200H This function gets the value of the current task’s real-mode interrupt vector for the 
specified interrupt. Pass the following information: 

AX = 0200H 

BL = interrupt number 

This call always succeeds. All 100H (256 decimal) interrupt vectors are supported by the 
host. When the call returns, the carry flag is clear, and the segment: offset of the 
real-mode interrupt handler is returned in CX:DX. 

Because the address returned in CX is a segment, and not a selector, you cannot put it into a 
protected-mode segment register. If you do, a general protection fault may occur. 

Function 0201H This function sets the value of the current task’s real-mode interrupt vector for the 
specified interrupt. Pass the following information: 

AX = 0201H 

BL = interrupt number 

CX:DX = segment:offset of the real-mode interrupt handler 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. 

The address passed in CX:DX should be a real-mode segment: of f set, such as 
function 0200H returns. For this reason, the interrupt handler must reside in DOS 
addressable memory. You can use Function 0100H to allocate DOS memory. This version 
does not support the real-mode callback address function. 

If you are hooking a hardware interrupt, you have to lock all segments involved. These 
segments include the segment in which the interrupt handler runs, and any segment it may 
touch at interrupt time. 

Function 0202H This function gets the processor exception handler vector. This function returns the 
CS:EIP of the current protected-mode exception handler for the specified exception 
number. Pass the following information: 

AX = 0202H 

BL = exception/fault number (OOh - lFh) 

If the call succeeds, the carry flag is clear and the selector: offset of the 
protected-mode exception handler is returned in CX:EDX. If it fails, the carry flag is set. 

The value returned in CX is a valid protected-mode selector, not a real-mode segment. 

Function 0203H This function sets the processor exception handler vector. This function allows 

protected-mode applications to intercept processor exceptions that are not handled by the 
DPMI environment. Programs may wish to handle exceptions such as "not present segment 
faults" which would otherwise generate a fatal error. Pass the following information: 
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AX = 0203H 

BL = exception/fault number (OOh - lFh) 

CX:EDX = selectorroffset of the exception handler 

If the call succeeds, the carry flag is clear. If it fails, the carry flag is set. 

The address passed in CX must be a valid protected-mode selector, such as Function 204H 
returns, and not a real-mode segment. A 32-bit implementation must supply a 32-bit offset 
in the EDX register. If the handler chains to the next handler, it must use a 32-bit interrupt 
stack frame to do so. 

The handler should return using a far return instruction. The original SS:ESP, CS:EIP and 
flags on the stack, including the interrupt flag, will be restored. 

All fault stack frames have an error code. However the error code is only valid for 
exceptions 08h, OAh, OBh, OCh, ODh, and OEh. 

The handler must preserve and restore all registers. 

The exception handler will be called on a locked stack with interrupts disabled. The 
original SS, ESP, CS, and EIP will be pushed on the exception handler stack frame. 

The handler must either return from the call by executing a far return or jump to the next 
handler in the chain (which will execute a far return or chain to the next handler). 

The procedure can modify any of the values on the stack pertaining to the exception before 
returning. This can be used, for example, to jump to a procedure by modifying the CS:EIP 
on the stack. Note that the procedure must not modify the far return address on the stack — 
it must return to the original caller. The caller will then restore the flags, CS:EIP and 
SS:ESP from the stack frame. 

If the DPMI client does not handle an exception, or jumps to the default exception handler, 
the host will reflect the exception as an interrupt for exceptions 0, 1, 2, 3, 4, 5 and 7. 
Exceptions 6 and 8 - lFh will be treated as fatal errors and the client will be terminated. 

Exception handlers will only be called for exceptions that occur in protected mode. 

Function 0204H This function gets the CS:EIP selector: offset of the current protected-mode 
interrupt handler for a specified interrupt number. Pass the following information: 

AX = 0204H 

BL = interrupt number 

This call always succeeds. All 100H (256 decimal) interrupt vectors are supported by the 
host. When the call returns, the carry flag is clear and CX:EDX contains the 
protected-mode selector: offset of the exception handler. 

A 32-bit offset is returned in the EDX register. 

Function 020511 This function sets the address of the specified protected-mode interrupt vector. Pass the 
following information: 
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AX = 0205H 

BL = interrupt number 

CX:EDX = selector:offset of the exception handler 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. 

The address passed in CX must be a valid protected-mode selector, such as Function 204H 
returns, and not a real-mode segment. A 32-bit implementation must supply a 32-bit offset 
in the EDX register. If the handler chains to the next handler, it must use a 32-bit interrupt 
stack frame to do so. 

11.2.4 Translation Services 

These services are provided so that protected-mode programs can call real-mode software that DPMI does 
not support directly. The protected-mode program must set up a data structure with the appropriate register 
values. This "real-mode call structure" is shown below. 
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Offset 

Register 

00H 

EDI 

04H 

ESI 

08H 

EBP 

OCH 

Reserved by system 

10H 

EBX 

14H 

EDX 

18H 

ECX 

1CH 

EAX 

20H 

Flags 

22H 

ES 

24H 

DS 

26H 

FS 

28H 

GS 

2AH 

IP 

2CH 

CS 

2EH 

SP 

3 OH 

SS 


After the call or interrupt is complete, all real-mode registers and flags except SS, SP, CS, and IP will be 
copied back to the real-mode call structure so that the caller can examine the real-mode return values. 

The values in the segment registers should be real-mode segments, not protected-mode selectors. 

The translation services will provide a real-mode stack if the SS:SP fields are zero. However, the stack 
provided is relatively small. If the real-mode procedure/interrupt routine uses more than 30 words of stack 
space then you should provide your own real-mode stack. 

Function 0300H This function simulates a real-mode interrupt. This function simulates an interrupt in real 
mode. It will invoke the CS:IP specified by the real-mode interrupt vector and the handler 
must return by executing an iret. Pass the following information: 
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AX = 0300H 

BL = interrupt number 

BH = flags Bit 0=1 resets the interrupt controller and A20 line. Other flags are 
reserved and must be 0. 

CX = number of words to copy from protected-mode stack to real-mode stack 
ES:EDI = the selectorroffset of real-mode call structure 

If the call fails, the carry flag is set. 

If the call succeeds, the carry flag is clear and ES:EDI contains the selector : offset 
of the modified real-mode call structure. 

The CS:IP in the real-mode call structure is ignored by this service. The appropriate 
interrupt handler will be called based on the value passed in BL. 

The flags specified in the real-mode call structure will be pushed on the real-mode stack 
iret frame. The interrupt handler will be called with the interrupt and trace flags clear. 

It is up to the caller to remove any parameters that were pushed on the protected-mode 
stack. 

The flag to reset the interrupt controller and the A20 line is ignored by DPMI 
implementations that run in Virtual 8086 mode. It causes DPMI implementations that 
return to real mode to set the interrupt controller and A20 address line hardware to its 
normal real-mode state. 

Function 0301H (DOS/4GW Professional only) This function calls a real-mode procedure with a FAR 

return frame. The called procedure must execute a FAR return when it completes. Pass the 
following information: 

AX = 0301H 

BH = flags Bit 0=1 resets the interrupt controller and A20 line. Other flags reserved 
and must be 0. 

CX = Number of words to copy from protected-mode to real-mode stack 
ES:EDI = selectorroffset of real-mode call structure 

If the call succeeds, the carry flag is clear and ES:EDI contains the selector : offset 
of modified real-mode call structure. 

If the call fails, the carry flag is set. 

Notes: 

1. The CS:IP in the real-mode call structure specifies the address of the real-mode 
procedure to call. 

2. The real-mode procedure must execute a FAR return when it has completed. 

3. If the SS:SP fields are zero then a real-mode stack will be provided by the DPMI 
host. Otherwise, the real-mode SS:SP will be set to the specified values before 
the procedure is called. 

4. When the Int 3lh returns, the real-mode call structure will contain the values that 
were returned by the real-mode procedure. 
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5. It is up to the caller to remove any parameters that were pushed on the 
protected-mode stack. 

6. The flag to reset the interrupt controller and A20 line is ignored by DPMI 
implementations that run in Virtual 8086 mode. It causes DPMI 
implementations that return to real mode to set the interrupt controller and A20 
address line hardware to its normal real-mode state. 

Function 0302H (DOS/4GW Professional only) This function calls a real-mode procedure with an iret 
frame. The called procedure must execute an iret when it completes. Pass the following 
information: 

AX = 0302H 

BH = flags Bit 0=1 resets the interrupt controller and A20 line. Other flags reserved 
and must be 0. 

CX = Number of words to copy from protected-mode to real-mode stack 
ES:EDI = selectorroffset of real-mode call structure 

If the call succeeds, the carry flag is clear and ES:EDI contains the selector : offset 
of modified real-mode call structure. 

If the call fails, the carry flag is set. 

Notes: 

1. The CS:IP in the real-mode call structure specifies the address of the real-mode 
procedure to call. 

2. The real-mode procedure must execute an iret when it has completed. 

3. If the SS:SP fields are zero then a real-mode stack will be provided by the DPMI 
host. Otherwise, the real-mode SS:SP will be set to the specified values before 
the procedure is called. 

4. When the Int 3lh returns, the real-mode call structure will contain the values that 
were returned by the real-mode procedure. 

5. The flags specified in the real-mode call structure will be pushed the real-mode 
stack iret frame. The procedure will be called with the interrupt and trace 
flags clear. 

6. It is up to the caller to remove any parameters that were pushed on the 
protected-mode stack. 

7. The flag to reset the interrupt controller and A20 line is ignored by DPMI 
implementations that run in Virtual 8086 mode. It causes DPMI 
implementations that return to real mode to set the interrupt controller and A20 
address line hardware to its normal real-mode state. 

Function 0303H (DOS/4GW Professional only) This function allocates a real-mode callback address. This 
service is used to obtain a unique real-mode SEG:OFFSET that will transfer control from 
real mode to a protected-mode procedure. 
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At times it is necessary to hook a real-mode interrupt or device callback in a 
protected-mode driver. For example, many mouse drivers call an address whenever the 
mouse is moved. Software running in protected mode can use a real-mode callback to 
intercept the mouse driver calls. Pass the following information: 

AX = 0303H 

DS:ESI = selectorroffset of procedure to call 
ES:EDI = selector: offset of real-mode call structure 

If the call succeeds, the carry flag is clear and CX:DX contains the segment: offset of 
real-mode callback address. 

If the call fails, the carry flag is set. 

Callback Procedure Parameters 

Interrupts disabled 

DS:ESI = selector:offset of real-mode SS:SP 
ES:EDI = selector:offset of real-mode call structure 
SS:ESP = Locked protected-mode API stack 
All other registers undefined 

Return from Callback Procedure 

Execute an IRET to return 

ES:EDI = selector:offset of real-mode call structure 
to restore (see note) 


Notes: 

1. Since the real-mode call structure is static, you must be careful when writing 
code that may be reentered. The simplest method of avoiding reentrancy is to 
leave interrupts disabled throughout the entire call. However, if the amount of 
code executed by the callback is large then you will need to copy the real-mode 
call structure into another buffer. You can then return with ES:EDI pointing to 
the buffer you copied the data to — it does not have to point to the original real 
mode call structure. 

2. The called procedure is responsible for modifying the real-mode CS:IP before 
returning. If the real-mode CS:IP is left unchanged then the real-mode callback 
will be executed immediately and your procedure will be called again. Normally 
you will want to pop a return address off of the real-mode stack and place it in 
the real-mode CS:IP. The example code in the next section demonstrates 
chaining to another interrupt handler and simulating a real-mode iret. 

3. To return values to the real-mode caller, you must modify the real-mode call 
structure. 

4. Remember that all segment values in the real-mode call structure will contain 
real-mode segments, not selectors. If you need to examine data pointed to by a 
real-mode seg:offset pointer, you should not use the segment to selector service 
to create a new selector. Instead, allocate a descriptor during initialization and 
change the descriptor’s base to 16 times the real-mode segment’s value. This is 
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important since selectors allocated though the segment to selector service can 
never be freed. 

5. DPMI hosts should provide a minimum of 16 callback addresses per task. 

The following code is a sample of a real-mode interrupt hook. It hooks the DOS Int 21h 
and returns an error for the delete file function (AH=41h). Other calls are passed through 
to DOS. This example is somewhat silly but it demonstrates the techniques used to hook a 
real mode interrupt. Note that since DOS calls are reflected from protected mode to real 
mode, the following code will intercept all DOS calls from both real mode and protected 
mode. 
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• •k'k-k-k-k-k'k'k'k'k'k'k-k-k-k-k-k'k'k'k-k-k'k-k-k'k-k-k-k-k'k-k-k'k'k'k-k-k'k-k'k'k'k'k'k'k'k'k'k'k'k'k-k-k 

; This procedure gets the current Int 21h real-mode 
; Seg:Offset, allocates a real-mode callback address, 

; and sets the real-mode Int 21h vector to the call- 
; back address. 

• •k-k'k'k-k'k'k'k'kic'k'kicic'k-k'k'k'k'k'k-k'k'k'k'k'k'k'k-k'k'k-k-k'k'k-k-kic'k'k-k'k'k'k'k-k'k'k'k'k'k'k'k 

Initialization_ Code: 


; Create a code segment alias to save data in 

mov ax, OOOAh 

mov bx, cs 

int 31h 

j c ERROR 

mov ds, ax 

ASSUMES DS,_ TEXT 


; Get current Int 21h real-mode SEG:OFFSET 


mov 

ax, 0200h 


mov 

bl, 21h 


int 

31h 


jc 

ERROR 


mov 

[Orig_ Real_ 

Seg], cx 

mov 

[Orig_ Real_ 

Offset], 


; Allocate a real-mode callback 


mov ax, 0303h 

push ds 

mov bx, cs 

mov ds, bx 

mov si, OFFSET My_ Int_ 21_ Hook 

pop es 

mov di, OFFSET My_ Real_ Mode_ Call_ St rue 

int 31h 

j c ERROR 

; Hook real-mode int 21h with the callback address 

mov ax, 0201h 

mov bl, 21h 

int 31h 

jc ERROR 

• •k'k'k'k-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k-k'k'k-k'k'k'k'k-k'k'k'k'k'kic-k-k'k'k'k'k'k'k'k-k'k'k'k'k'k'k'kicic 

; This is the actual Int 21h hook code. It will return 
; an "access denied" error for all calls made in real 
; mode to delete a file. Other calls will be passed 
; through to DOS. 

; ENTRY: 

; DS:SI -> Real-mode SS:SP 

; ES:DI -> Real-mode call structure 

; Interrupts disabled 

; EXIT: 

; ES:DI -> Real-mode call structure 

• ******************************************************* 


My_ Int_ 21_ Hook: 

emp es : [di . RealMode_ AH] , 41h 

jne Chain_ To_ DOS 

; This is a delete file call (AH=41h). Simulate an 
; iret on the real-mode stack, set the real-mode 
; carry flag, and set the real-mode AX to 5 to indicate 
; an access denied error. 
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cld 

lodsw 


; Get 

real-mode 

ret 

IP 

mov 

es: 

[di . RealMode_ IP ] , 

ax 



lodsw 


; Get 

real-mode 

ret 

CS 

mov 

es: 

[di . RealMode_ CS ] , 

ax 



lodsw 


; Get 

real-mode 

flags 

or 

ax. 

1 ; Set 

carry flag 


mov 

es: 

[di.RealMode_ Flags 

] , ax 



add 

es: 

[di . RealMode_ SP ] , 

6 



mov 

es: 

[di .RealMode_ AX] , 

5 



jmp 

My_ 

. Hook_ Exit 





; Chain to original Int 21h vector by replacing the 
; real-mode CS:IP with the original Seg:Offset. 

Chain_ To_ DOS: 


mov 

ax, cs : [Orig_Real_ 

Seg] 

mov 

es:[di.RealMode_ CS 

] i ax 

mov 

ax, cs:[Orig_ Real_ 

Offset 

mov 

es:[di.RealMode_ IP 

] t ax 


My_ Hook_ Exit: 

iret 


Function 0304H (DOS/4GW Professional only) This function frees a real-mode callback address that was 
allocated through the allocate real-mode callback address service. Pass the following 
information: 

AX = 0304H 

CX:DX = Real-mode callback address to free 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. 

Notes: 

1. Real-mode callbacks are a limited resource. Your code should free any break 
point that it is no longer using. 


11.2.5 DPMI Version 

Function 0400H This function returns the version of DPMI services supported. Note that this is not 

necessarily the version of any operating system that supports DPMI. It should be used by 
programs to determine what calls are legal in the current environment. Pass the following 
information: 

AX = 0400H 

The information returned is: 

AH = Major version 
AL = Minor version 

BX = Flags Bit 0 = 1 if running under an 80386 DPMI implementation. Bit 1 = 1 if 
processor is returned to real mode for reflected interrupts (as opposed to 
Virtual 8086 mode). Bit 2 = 1 if virtual memory is supported. Bit 3 is 
reserved and undefined. All other bits are zero and reserved for later use. 

CL = Processor type 
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02 = 80286 
03 = 80386 
04 = 80486 
05 = Pentium 

DH = Current value of virtual master PIC base interrupt 
DL = Current value of virtual slave PIC base interrupt 
Carry flag clear (call cannot fail) 

11.2.6 Memory Management Services 

Function 0500H This function gets information about free memory. Pass the following information: 

AX = 0500H 

ES:EDI = the selector:offset of a 30H byte buffer. 

If the call fails, the carry flag is set. 

If the call succeeds, the carry flag is clear and ES:EDI contains the selector : offset 
of a buffer with the structure shown in the figure below. 


Offset 

Description 

00H 

Fargest available block, in bytes 

04H 

Maximum unlocked page allocation 

08H 

Fargest block of memory (in pages) that could 
be allocated and then locked 

0CH 

Total linear address space size, in pages, including 
already allocated pages 

10H 

Total number of free pages and pages currently 
unlocked and available for paging out 

14H 

Number of physical pages not in use 

18H 

Total number of physical pages managed by host 

1CH 

Free linear address space, in pages 

20H 

Size of paging/file partition, in pages 

n 

Reserved 


Only the first field of the structure is guaranteed to contain a valid value. Any field that is 
not returned by DOS/4GW is set to -1 (OFFFFFFFFH). 
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Function 0501H This function allocates and commits linear memory. Pass the following information: 

AX = 0501H 

BX:CX = size of memory to allocate, in bytes. 

If the call succeeds, the carry flag is clear, BX:CX contains the linear address of the 
allocated memory, and SI:DI contains the memory block handle used to free or resize the 
block. If the call fails, the carry flag is set. 

No selectors are allocated for the memory block. The caller must allocate and initialize 
selectors needed to access the memory. 

If VMM is present, the memory is allocated as unlocked, page granular blocks. Because of 
the page granularity, memory should be allocated in multiples of 4KB. 

Function 0502H This function frees a block of memory allocated through function 0501H. Pass the 
following information: 

AX = 0502H 

SI:DI = handle returned with function 0501H when memory was allocated 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. You must also 
free any selectors allocated to point to the freed memory block. 

Function 0503H This function resizes a block of memory allocated through the 0501H function. If you 
resize a block of linear memory, it may have a new linear address and a new handle. Pass 
the following information: 

AX = 0503H 

BX:CX = new size of memory block, in bytes 

SI:DI = handle returned with function 0501H when memory was allocated 

If the call succeeds, the carry flag is clear, BX:CX contains the new linear address of the 
memory block, and SI:DI contains the new handle of the memory block. If the call fails, 
the carry flag is set. 

If either the linear address or the handle has changed, update the selectors that point to the 
memory block. Use the new handle instead of the old one. 

You cannot resize a memory block to zero bytes. 

11.2.7 Page Locking Services 

These services are only useful under DPMI implementations that support virtual memory. Although 
memory ranges are specified in bytes, the actual unit of memory that will be locked will be one or more 
pages. Page locks are maintained as a count. When the count is decremented to zero, the page is unlocked 
and can be swapped to disk. This means that if a region of memory is locked three times then it must be 
unlocked three times before the pages will be unlocked. 
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Function 0600H This function locks a specified linear address range. Pass the following information: 

AX = 0600H 

BX:CX = starting linear address of memory to lock 
SI:DI = size of region to lock (in bytes) 

If the call fails, the carry flag is set and none of the memory will be locked. 

If the call succeeds, the carry flag is clear. If the specified region overlaps part of a page at 
the beginning or end of a region, the page(s) will be locked. 

Function 0601H This function unlocks a specified linear address range that was previously locked using 
the "lock linear region" function (0600h). Pass the following information: 

AX = 0601H 

BX:CX = starting linear address of memory to unlock 
SI:DI = size of region to unlock (in bytes) 

If the call fails, the carry flag is set and none of the memory will be unlocked. An error 
will be returned if the memory was not previously locked or if the specified region is 
invalid. 

If the call succeeds, the carry flag is clear. If the specified region overlaps part of a page at 
the beginning or end of a region, the page(s) will be unlocked. Even if the call succeeds, 
the memory will remain locked if the lock count is not decremented to zero. 

Function 0604H This function gets the page size for Virtual Memory (VM) only. This function returns the 
size of a single memory page in bytes. Pass the following information: 

AX = 0604H 

If the call succeeds, the carry flag is clear and BX:CX = Page size in bytes. 

If the call fails, the carry flag is set. 

11.2.8 Demand Paging Performance Tuning Services 

Some applications will discard memory objects or will not access objects for long periods of time. These 
services can be used to improve the performance of demand paging. 

Although these functions are only relevant for DPMI implementations that support virtual memory, other 
implementations will ignore these functions (it will always return carry clear). Therefore your code can 
always call these functions regardless of the environment it is running under. 

Since both of these functions are simply advisory functions, the operating system may choose to ignore 
them. In any case, your code should function properly even if the functions fail. 

Function 0702H (DOS/4GW Professional only) This function marks a page as a demand paging candidate. 

This function is used to inform the operating system that a range of pages should be placed 
at the head of the page out candidate list. This will force these pages to be swapped to disk 
ahead of other pages even if the memory has been accessed recently. However, all memory 
contents will be preserved. 
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This is useful, for example, if a program knows that a given piece of data will not be 
accessed for a long period of time. That data is ideal for swapping to disk since the 
physical memory it now occupies can be used for other purposes. Pass the following 
information: 

AX = 0702H 

BX:CX = Starting linear address of pages to mark 
SI:DI = Number of bytes to mark as paging candidates 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. 

Notes: 

1. This function does not force the pages to be swapped to disk immediately. 

2. Partial pages will not be discarded. 

Function 0703H (DOS/4GW Professional only) This function discards page contents. This function 
discards the entire contents of a given linear memory range. It is used after a memory 
object that occupied a given piece of memory has been discarded. 

The contents of the region will be undefined the next time the memory is accessed. All 
values previously stored in this memory will be lost. Pass the following information: 

AX = 0703H 

BX:CX = Starting linear address of pages to discard 
SI:DI = Number of bytes to discard 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. 

Notes: 

1. Partial pages will not be discarded. 

11.2.9 Physical Address Mapping 

Memory mapped devices such as network adapters and displays sometimes have memory mapped at 
physical addresses that lie outside of the normal 1Mb of memory that is addressable in real mode. Under 
many implementations of DPMI, all addresses are linear addresses since they use the paging mechanism of 
the 80386. This service can be used by device drivers to convert a physical address into a linear address. 
The linear address can then be used to access the device memory. 

Function 0800H This function is used for Physical Address Mapping. 

Some implementations of DPMI may not support this call because it could be used to 
circumvent system protection. This call should only be used by programs that absolutely 
require direct access to a memory mapped device. 

Pass the following information: 
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AX = 0800H 

BX:CX = Physical address of memory 
SI:DI = Size of region to map in bytes 

If the call succeeds, the carry flag is clear and BX:CX = Linear Address that can be used to 
access the physical memory. 

If the call fails, the carry flag is set. 

Notes: 

1. Under DPMI implementations that do not use the 80386 paging mechanism, the 
call will always succeed and the address returned will be equal to the physical 
address parameter passed into this function. 

2. It is up to the caller to build an appropriate selector to access the memory. 

3. Do not use this service to access memory that is mapped in the first megabyte of 
address space (the real-mode addressable region). 

Function 0801H This function is used to free Physical Address Mapping. Pass the following information: 

AX = 0801H 

BX:CX = Linear address returned by Function 0800H. 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. 

Notes: 

1. The client should call this function when it is finished using a device previously 
mapped to linear addresses with the Physical Address Mapping function 
(Function 0800H). 

11.2.10 Virtual Interrupt State Functions 

Under many implementations of DPMI, the interrupt flag in protected mode will always be set (interrupts 
enabled). This is because the program is running under a protected operating system that cannot allow 
programs to disable physical hardware interrupts. However, the operating system will maintain a "virtual" 
interrupt state for protected-mode programs. When the program executes a CLI instruction, the program’s 
virtual interrupt state will be disabled, and the program will not receive any hardware interrupts until it 
executes an STI to reenable interrupts (or calls service 0901h). 

When a protected-mode program executes a PUSHF instruction, the real processor flags will be pushed 
onto the stack. Thus, examining the flags pushed on the stack is not sufficient to determine the state of the 
program’s virtual interrupt flag. These services enable programs to get and modify the state of their virtual 
interrupt flag. 

The following sample code enters an interrupt critical section and then restores the virtual interrupt state to 
it’s previous state. 
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; Disable interrupts and get previous interrupt state 

mov ax, 0900h 

int 31h 

; At this point AX = 0900h or 0901h 


; Restore previous state (assumes AX unchanged) 
int 31h 

Function 0900H This function gets and disables Virtual Interrupt State. This function will disable the 
virtual interrupt flag and return the previous state of the virtual interrupt flag. Pass the 
following information: 

AX = 0900H 

After the call, the carry flag is clear (this function always succeeds) and virtual interrupts 
are disabled. 

AL = 0 if virtual interrupts were previously disabled. 

AL = 1 if virtual interrupts were previously enabled. 

Notes: 

1. AH will not be changed by this procedure. Therefore, to restore the previous 
state, simply execute an Int 3 lh. 

Function 0901H This function gets and enables the Virtual Interrupt State. This function will enable the 
virtual interrupt flag and return the previous state of the virtual interrupt flag. Pass the 
following information: 

AX = 0901H 

After the call, the carry flag is clear (this function always succeeds) and virtual interrupts 
are enabled. 

AL = 0 if virtual interrupts were previously disabled. 

AL = 1 if virtual interrupts were previously enabled. 

Notes: 

1. AH will not be changed by this procedure. Therefore, to restore the previous 
state, simply execute an Int 3 lh. 

Function 0902H This function gets the Virtual Interrupt State. This function will return the current state of 
the virtual interrupt flag. Pass the following information: 
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AX = 0902H 

After the call, the carry flag is clear (this function always succeeds). 

AL = 0 if virtual interrupts are disabled. 

AL = 1 if virtual interrupts are enabled. 

11.2.11 Vendor Specific Extensions 

Some DOS extenders provide extensions to the standard set of DPMI calls. This call is used to obtain an 
address which must be called to use the extensions. The caller points DS:ESI to a null terminated string 
that specifies the vendor name or some other unique identifier to obtain the specific extension entry point. 

Function 0A00H This function gets Tenberry Software’s API Entry Point. Pass the following information: 

AX = 0A00H 

DS:ESI = Pointer to null terminated string "RATIONAL DOS/4G" 

If the call succeeds, the carry flag is clear and ES:EDI = Extended API entry point. DS, 

FS, GS, EAX, EBX, ECX, EDX, ESI, and EBP may be modified. 

If the call fails, the carry flag is set. 

Notes: 

1. Execute a far call to call the API entry point. 

2. All extended API parameters are specified by the vendor. 

3. The string comparison used to return the API entry point is case sensitive. 

11.2.12 Coprocessor Status 

Function 0E00H This function gets the coprocessor status. Pass the following information: 

AX = 0E00H 

If the call succeeds, the carry flag is clear and AX contains the coprocessor status. 

Bit Significance 

0 MPv (MP bit in the virtual MSW/CRO). 

0 = Numeric coprocessor is disabled for this client. 

1 = Numeric coprocessor is disabled for this client. 

1 EMv (EM bit in the virtual MSW/CRO). 

0 = Client is not emulating coprocessor instructions. 

1 = Client is emulating coprocessor instructions. 

2 MPr (MP bit from the actual MSW/CRO). 

0 = Numeric coprocessor is not present. 

1 = Numeric coprocessor is present. 
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1 EMr (EM bit from the actual MSW/CRO). 

0 = Host is not emulating coprocessor instructions. 

1 = Host is emulating coprocessor instructions. 

4-7 Coprocessor type. 

00H = no coprocessor. 

02H = 80287 

03H = 80387 

04H = 80486 with numeric coprocessor 

05 H = Pentium 

8-15 Not applicable. 

If the call fails, the carry flag is set. 

Notes: 

1. If the real EM (EMr) bit is set, the host is supplying or is capable of supplying 
floating-point emulation. 

2. If the MPv bit is not set, the host may not need to save the coprocessor state for 
this virtual machine to improve system performance. 

3. The MPr bit setting should be consistent with the setting of the coprocessor type 
information. Ignore MPr bit information if it is in conflict with the coprocessor 
type information. 

4. If the virtual EM (EMv) bit is set, the host delivers all coprocessor exceptions to 
the client, and the client is performing its own floating-point emulation (wether 
or not a coprocessor is present or the host also has a floating-point emulator). In 
other words, if the EMv bit is set, the host sets the EM bit in the real CRO while 
the virtual machine is active, and reflects coprocessor not present faults (int 7) to 
the virtual machine. 

5. A client can determine the CPU type with int 31H Function 0400H, but a client 
should not draw any conclusions about the presence or absence of a coprocessor 
based on the CPU type alone. 

Function 0E01H This function sets coprocessor emulation. Pass the following information: 

AX = 0E01H 

BX = coprocessor bits 

Bit Significance 

0 New value of MPv bit for client’s virtual CRO. 

0 = Disable numeric coprocessor for this client. 

1 = Enable numeric coprocessor for this client. 

1 New value of EMv bit for client’s virtual CRO. 

0 = client will not supply coprocessor emulation. 

1 = client will supply coprocessor emulation. 

2-15 Not applicable. 

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set. 
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This chapter describes the Tenberry Software DOS/4GW utility programs provided with the Open Watcom 

C/C++ package. Each program is described using the following format: 

Purpose: This is a brief statement of what the utility program does. More specific information is provided 
under "Notes". 

Syntax: This shows the syntax of the program. The fixed portion of each command is in a 

typewriter font, while variable parts of the command are in italics. Optional parts are 
enclosed in [brackets]. 

Notes: These are explanatory remarks noting major features and possible pitfalls. We explain anything 

special that you might need to know about the program. 

See Also: This is a cross-reference to any information that is related to the program. 

Example: You'll find one or more sample uses of the utility program with an explanation of what the 
program is doing. 

Some of the utilities are DOS/4G W-bascd, protected-mode programs. To determine which programs run in 

protected mode and which in real, run the program. If you see the DOS/4GW banner, the program runs in 

protected mode. 
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12.1 D0S4GW 


Purpose: Loads and executes linear executables. 

Syntax: linear_executable 

Notes: The stub program at the beginning of the linear executable invokes this program, which loads the 

linear executable and starts up the DOS extender. The stub program must be able to find 
DOS4GW: make sure it is in the path. 
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12.2 PMINFO 

Purpose: Measures the performance of protected/real-mode switching and extended memory. 

Syntax: PMINFO. EXE 

Notes: We encourage you to distribute this program to your users. 

The time-based measurements made by PMINFO may vary slightly from run to run. 

Example: The following example shows the output of the PMINFO program on a 386 AT-compatible 
machine. 


Opminfo 

Protected Mode and Extended Memory Performance Measurement — 5.00 
Copyright (c) Tenberry Software, Inc. 1987 - 1993 


DOS memory Extended memory 


CPU performance equivalent to 67.0 MHz 80486 


736 

640 

651 

22.0 (3.0) 
42.9 (3.0) 


8012 
15360 
7887 
18.9 (4.0) 
37.0 (4.0) 


K bytes configured (according to BIOS). 

K bytes physically present (SETUP). 

K bytes available for DOS/16M programs. 
MB/sec word transfer rate (wait states) . 
MB/sec 32-bit transfer rate (wait states). 


Overall cpu and memory performance (non-floating point) for typical 
DOS programs is 10.36 ae 1.04 times an 8MHz IBM PC/AT. 


Protected/Real switch rate = 36156/sec (27 usec/switch, 15 up + 11 down), 
DOS/16M switch mode 11 (VCPI). 


The top information line shows that the CPU performance is equivalent to a 67.0 MHz 80486. 
Below are the configuration and timings for both the DOS memory and extended memory. If the 
computer is not equipped with extended memory, or none is available for DOS/4GW, the 
extended memory measurements may be omitted 

The line "according to BIOS" shows the information provided by the BIOS (interrupts 12h and 
15h function 88h). The line "SETUP", if displayed, is the configuration obtained directly from 
the CMOS RAM as set by the computer’s setup program. It is displayed only if the numbers are 
different from those in the BIOS line. They will be different for computers where the BIOS has 
reserved memory for itself or if another program has allocated some memory and is intercepting 
the BIOS configuration requests to report less memory available than is physically configured. 
The "DOS/16M memory range", if displayed, shows the low and high addresses available to 
DOS/4GW in extended memory. 

Below the configuration information is information on the memory speed (transfer rate). 
PMINFO tries to determine the memory architecture. Some architectures will perform well 
under some circumstances and poorly under others; PMINFO will show both the best and worst 
cases. The architectures detected are cache, interleaved, page-mode (or static column), and 
direct. Measurements are made using 32-bit accesses and reported as the number of megabytes 
per second that can be transferred. The number of wait states is reported in parentheses. The 
wait states can be a fractional number, like 0.5, if there is a wait state on writes but not on reads. 
Memory bandwidth (i.e., how fast the CPU can access memory) accounts for 60% to 70% of the 
performance for typical programs (that are not heavily dependent on floating-point math). 
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A performance metric developed by Tenberry Software is displayed, showing the expected 
throughput for the computer relative to a standard 8MHz IBM PC/AT (disk accesses and floating 
point are excluded). Finally, the speed with which the computer can switch between real and 
protected mode is displayed, both as the maximum number of round-trip switches that can occur 
per second, and the time for a single round-trip switch, broken out into the real-to-protected (up) 
and protected-to-real (down) components. 
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12.3 PRIVATXM 


Purpose: Creates a private pool of memory for DOS/4GW programs. 

Syntax: PRIVATXM [ —r ] 

Notes: This program may be distributed to your users. 

Without PRIVATXM, a DOS/4GW program that starts up while another DOS/4GW program is 
active uses the pool of memory built by the first program. The new program cannot change the 
parameters of this memory pool, so setting DOS16M to increase the size of the pool has no 
effect. To specify that the two programs use different pools of memory, use PRIVATXM. 

PRIVATXM marks the active DOS/4GW programs as private, preventing subsequent DOS/4GW 
programs from using the same memory pool. The first DOS/4GW program to start after 
PRIVATXM sets up a new pool of memory for itself and any subsequent DOS/4GW programs. 
To release the memory used by the private programs, use the PRIVATXM -r option. 

PRIVATXM is a TSR that requires less than 500 bytes of memory. It is not supported under 
DPMI. 

Example: The following example creates a 512KB memory pool that is shared by two DOS/4GW TSRs. 
Subsequent DOS/4GW programs use a different memory pool. 


C>set DO SI 6M= :512 
C>TSR1 
C>TSR2 
C>PRIVA TXM 
C>set DO SI 6M= 
C>PR OGRAM3 
C>PRIVA TXM -R 


Specifies the size of the memory pool. 

Sets up the memory pool at startup. 

This TSR shares the pool built by TSR1. 

Makes subsequent DOS/4GW programs use a new memory pool. 
Specifies an unlimited size for the new pool. 

This program uses the new memory pool. 

Releases the 512KB memory pool used by the TSRs. (If the TSRs 
shut down, their memory is not released unless PRIVATXM is 
released.) 
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12.4 RMINFO 


Purpose: Supplies configuration information and the basis for real/protected-mode switching in your 
machine. 

Syntax: RMINFO. EXE 

Notes: This program may be distributed to your users. 

RMINFO starts up DOS/4GW, but stops your machine just short of switching from real mode to 
protected mode and displays configuration information about your computer. The information 
shown by RMINFO can help determine why DOS/4GW applications won't run on a particular 
machine. Run RMINFO if PMINFO does not run to completion. 

Example: The following example shows the output of the RMINFO program on an 386 AT-compatible 
machine. 


Orminfo 


DOS/16M Real Mode Information Program 5.00 
Copyright (C) Tenberry Software 


Machine and Environment: 
Processor: 

Machine type: 

A20 now: 

A20 switch rigor: 

DPMI host found 
Switching Functions: 

To PM switch: 

To RM switch: 

Nominal switch mode: 
Switch control flags: 
Memory Interfaces: 

DPMI may provide: 
Contiguous DOS memory: 


Inc. 1987 - 1993 


i386, coprocessor present 
10 (AT-compatible) 
enabled 
disabled 


DPMI 

DPMI 

0 

0000 

16384K returnable 
463K 


The information provided by RMINFO includes: 

Machine and Environment: 

Processor: processor type, coprocessor present/not present 

Machine type: 
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(NEC 9801) 

(PS/2-compatible) 

(AT-compatible) 

(FM R) 

(AT&T 6300+) 

(AT-compatible) 

(C&T 230 chipset) 

(AT-compatible) 

(AT-compatible) 

(Acer) 

(Zenith) 

(Hitachi) 

(Okidata) 

(PS/55) 

A20 now: Current state of Address line 20. 

A20 switch rigor: Whether DOS4GW rigorously controls enabling and disabling of Address line 
20 when switching modes. 


PS feature flag 

XMS host found Whether your system has any software using extended memory under the XMS 
discipline. 

VCPI host found Whether your system has any software using extended memory under the 
VCPI discipline. 

page table 0 at: xOOOh 

DPMI host found 

DOS/16M resident with private/public memory 

Switching Functions: 

A20 switching: 

To PM switch: reset catch: 

pre-PM prep: 
post-PM-switch: 

To RM switch: 

pre-RM prep: 
reset method: 
post-reset: 
reset uncatch: 

Nominal switch mode: x 

Switch control flags: xxxxh 


RMINFO 
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Memory Interfaces: 

(VCPI remapping in effect) 

DPMI may provide: xxxxxK returnable 

VCPI may provide: xxxxxK returnable 

Top-down 

Other16M 

Forced 

Contiguous DOS memory: 
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13 Error Messages 


The following lists DOS/4G error messages, with descriptions of the circumstances in which the error is 
most likely to occur, and suggestions for remedying the problem. Some error messages pertaining to 
features — like DLLs — that are not supported in DOS/4GW will not arise with that product. In the 
following descriptions, references to DOS/4G, DOS4G, or DOS4G.EXE may be replaced by DOS/4GW, 
DOS4GW, or DOS4GW.EXE should the error message arise when using DOS/4GW. 

13.1 Kernel Error Messages 

This section describes error messages from the DOS/16M kernel embedded in DOS/4G. Kernel error 
messages may occur because of severe resource shortages, corruption of DOS4GW.EXE, corruption of 
memory, operating system incompatibilities, or internal errors in DOS/4GW. All of these messages are 
quite rare. 

0. involuntary switch to real mode 

The computer was in protected mode but switched to real mode without going through DOS/16M. This 
error most often occurs because of an unrecoverable stack segment exception (stack overflow), but can 
also occur if the Global Descriptor Table or Interrupt Descriptor Table is corrupted. Increase the stack 
size, recompile your program with stack overflow checking, or look into ways that the descriptor tables 
may have been overwritten. 

1. not enough extended memory 

2. not a DOS/16M executable <filename> 

DOS4G.EXE, or a bound DOS/4G application, has probably been corrupted in some way. Rebuild or 
recopy the file. 

3. no DOS memory for transparent segment 

4. cannot make transparent segment 

5. too many transparent segments 

6. not enough memory to load program 

There is not enough memory to load DOS/4G. Make more memory available and try again. 

7. no relocation segment 

8. cannot open file <filename> 

The DOS/16M loader cannot load DOS/4G, probably because DOS has run out of file units. Set a 
larger FILES= entry in CONFIG.SYS, reboot, and try again. 
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9. cannot allocate tstack 

There is not enough memory to load DOS/4G. Make more memory available and try again. 

10. cannot allocate memory for GDT 

There is not enough memory to load DOS/4G. Make more memory available and try again. 

11. no passup stack selectors — GDT too small 

This error indicates an internal error in DOS/4G or an incompatibility with other software. 

12. no control program selectors — GDT too small 

This error indicates an internal error in DOS/4G or an incompatibility with other software. 

13. cannot allocate transfer buffer 

There is not enough memory to load DOS/4G. Make more memory available and try again. 

14. premature EOF 

DOS4G.EXE, or a bound DOS/4G application, has probably been corrupted in some way. Rebuild or 
recopy the file. 

15. protected mode available only with 386 or 486 

DOS/4G requires an 80386 (or later) CPU. It cannot run on an 80286 or earlier CPU. 

16. cannot run under OS/2 

17. system software does not follow VCPI or DPMI specifications 

Some memory resident program has put your 386 or 486 CPU into Virtual 8086 mode. This is done to 
provide special memory services to DOS programs, such as EMS simulation (EMS interface without 
EMS hardware) or high memory. In this mode, it is not possible to switch into protected mode unless 
the resident software follows a standard that DOS/16M supports (DPMI, VCPI, and XMS are the most 
common). Contact the vendor of your memory management software. 

18. you must specify an extended memory range (SET DOS16M= ) 

On some Japanese machines that are not IBM AT-compatible, and have no protocol for managing 
extended memory, you must set the DOS16M environment variable to specify the range of available 
extended memory. 

19. computer must be AT- or PS/2- compatible 

20. unsupported DOS16M switchmode choice 

21. requires DOS 3.0 or later 

22. cannot free memory 

This error probably indicates that memory was corrupted during execution of your program. 
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23. no memory for VCPI page table 

There is not enough memory to load DOS/4G. Make more memory available and try again. 

24. VCPI page table address incorrect 
This is an internal error. 

25. cannot initialize VCPI 

This error indicates an incompatibility with other software. DOS/16M has detected that VCPI is 
present, but VCPI returns an error when DOS/16M tries to initialize the interface. 

26. 8042 timeout 

27. extended memory is configured but it cannot be allocated 

28. memory error, avail loop 

This error probably indicates that memory was corrupted during execution of your program. Using an 
invalid or stale alias selector may cause this error. Incorrect manipulation of segment descriptors may 
also cause it. 

29. memory error, out of range 

This error probably indicates that memory was corrupted during execution of your program. Writing 
through an invalid or stale alias selector may cause this error. 

30. program must be built -AUTO for DPMI 

31. protected mode already in use in this DPMI virtual machine 

32. DPMI host error (possibly insufficient memory) 

33. DPMI host error (need 64K XMS) 

34. DPMI host error (cannot lock stack) 

Any of these errors (32, 33, 34) probably indicate insufficient memory under DPMI. Under Windows, 
you might try making more physical memory available by eliminating or reducing any RAM drives or 
disk caches. You might also try editing DEFAULT.PIF so that at least 64KB of XMS memory is 
available to non-Windows programs. Under OS/2, you want to increase the DPMI_MEMORY_FIMIT 
in the DOS box settings. 

35. General Protection Fault 

This message probably indicates an internal error in DOS/4G. Faults generated by your program should 
cause error 2001 instead. 

36. The DOS16M.386 virtual device driver was never loaded 

37. Unable to reserve selectors for DOS16M.386 Windows driver 
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38. Cannot use extended memory: HIMEM.SYS not version 2 

This error indicates an incompatibility with an old version of HIMEM.SYS. 

39. An obsolete version of DOS16M.386 was loaded 

40. not enough available extended memory (XMIN) 

This message probably indicates an incompatibility with your memory manager or its configuration. 
Try configuring the memory manager to provide more extended memory, or change memory managers. 


13.2 D0S/4G Errors 

1000 "can’t hook interrupts" 

A DPMI host has prevented DOS/4G from loading. Please contact Tenberry Technical Support. 

1001 "error in interrupt chain" 

DOS/4G internal error. Please contact Tenberry Technical Support. 

1003 "can’t lock extender kernel in memory" 

DOS/4G couldn’t lock the kernel in physical memory, probably because of a memory shortage. 

1004 "syntax is DOS4G <executable.xxx>" 

You must specify a program name. 

1005 "not enough memory for dispatcher data" 

There is not enough memory for DOS/4G to manage user-installed interrupt handlers properly. Free 
some memory for the DOS/4G application. 

1007 "can’t find file <program> to load" 

DOS/4G could not open the specified program. Probably the file didn't exist. It is possible that 
DOS ran out of file handles, or that a network or similar utility has prohibited read access to the 
program. Make sure that the file name was spelled correctly. 

1008 "can’t load executable format for file <filename> [<error code>]" 

DOS/4G did not recognize the specified file as a valid executable file. DOS/4G can load linear 
executables (LE and LX) and EXPs (BW). The error code is for Tenberry Software’s use. 

1009 "program <filename> is not bound" 

This message does not occur in DOS/4G, only DOS/4GW Professional; the latter requires that the 
DOS extender be bound to the program file. The error signals an attempt to load 

1010 "can’t initialize loader <loader> [<error code>]" 
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D0S/4G could not initialize the named loader, probably because of a resource shortage. Try making 
more memory available. If that doesn’t work, please contact Tenberry Technical Support. The error 
code is for Tenberry Software’ use. 

1011 "VMM initialization error [<error code>]" 

DOS/4G could not initialize the Virtual Memory Manager, probably because of a resource shortage. 
Try making more memory available. If that doesn't work, please contact Tenberry Technical 
Support. The error code is for Tenberry Software’ use. 

1012 "<filename> is not a WATCOMprogram" 

This message does not occur in DOS/4G, only DOS/4GW and DOS/4GW Professional. Those 
extenders only support WATCOM 32-bit compilers. 

1013 "int 31h initialization error" 

DOS/4G was unable to initialize the code that handles Interrupt 31h, probably because of an internal 
error. Please call Tenberry Technical Support. 

1100 "assertion \"<statement>\" failed (<file>:<line>)" 

DOS/4G internal error. Please contact Tenberry Technical Support. 

1200 "invalid EXP executable format " 

DOS/4G tried to load an EXP, but couldn’t. The executable file is probably corrupted. 

1201 "program must be built -AUTO for DPMI" 

Under DPMI, DOS/4G can only load EXPs that have been linked with the GLU -AUTO or -DPMI 
switch. 

1202 "can’t allocate memory for GDT" 

There is not enough memory available for DOS/4G to build a Global Descriptor Table. Make more 
memory available. 

1203 "premature EOF" 

DOS/4G tried to load an EXP but couldn’t. The file is probably corrupted. 

1204 "not enough memory to load program" 

There is not enough memory available for DOS/4G to load your program. Make more memory 
available. 

1301 "invalid linear executable format" 

DOS/4G cannot recognize the program file as a LINEXE format. Make sure that you specified the 
correct file name. 

1304 "file I/O seek error" 
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D0S/4G was unable to seek to a file location that should exist. This usually indicates truncated 
program files or problems with the storage device from which your program loads. Run CHKDSK 
or a similar utility to begin determining possible causes. 

1305 "file I/O read error" 

DOS/4G was unable to read a file location that should contain program data. This usually indicates 
truncated program files or problems with the storage device from which your program loads. Run 
CHKDSK or a similar utility to begin determining possible causes. 

1307 "not enough memory" 

As it attempted to load your program, DOS/4G ran out of memory. Make more memory available, 
or enable VMM. 

1308 "can’t load requested program" 

1309 "can’t load requested program " 

1311 "can’t load requested program " 

1312 "can’t load requested program" 

DOS/4G cannot load your program for some reason. Contact Tenberry Technical Support. 

1313 "can’t resolve external references " 

DOS/4G was unable to resolve all references to DLLs for the requested program, or the program 
contained unsupported fixup types. Use EXEHDR or a similar LINEXE dump utility to see what 
references your program makes and what special fixup records might be present. 

1314 "not enough lockable memory" 

As it attempted to load your program, DOS/4G encountered a refusal to lock a virtual memory 
region. Some memory must be locked in order to handle demand-load page faults. Make more 
physical memory available. 

1315 "can’t load requested program" 

1316 "can’t load requested program" 

DOS/4G cannot load your program for some reason. Contact Tenberry Technical Support. 

1317 "program has no stack" 

DOS/4G reports this error when you try to run a program with no stack. Rebuild your program, 
building in a stack. 

2000 "deinitializing twice" 

DOS/4G internal error. Please contact Tenberry Technical Support. 

2001 "exception <exception_number> (<exception_description>) at <selector:offset>" 
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Your program has generated an exception. For information about interpreting this message, see the 
file COMMON.DOC. 

2002 "transfer stack overflow at <selector:offset>" 

Your program has overflowed the DOS/4G transfer stack. For information about interpreting this 
message, see the file COMMON.DOC. 

2300 " can’t find <DLL>.<ordinal> - referenced from <module>" 

DOS/4G could not find the ordinal listed in the specified DLL, or it could not find the DLL at all. 
Correct or remove the reference, and make sure that DOS/4G can find the DLL. 

DOS/4G looks for DLLs in the following directories: 

• The directory specified by the Libpath32 configuration option (which defaults to the directory 
of the main application file). 

• The directory or directories specified by the LIBPATH32 environment variable. 

• Directories specified in the PATFl. 

2301 "can’t find <DLL>.<name> - referenced from <module>” 

DOS/4G could not find the entry point named in the specified module. Correct or remove the 
reference, and make sure that DOS/4G can find the DLL. 

2302 "DLL modules not supported" 

This DOS/4GW Professional error message arises when an application references or tries to 
explicitly load a DLL. DOS/4GW Professional does not support DLLs. 

2303 "internal LINEXE object limit reached" 

DOS/4G currently handles a maximum of 128 LINEXE objects, including all .DLL and .EXE files. 
Most .EXE or .DLL files use only three or four objects. If possible, reduce the number of objects, or 
contact Tenberry Technical Support. 

2500 "can’t connect to extender kernel" 

DOS/4G internal error. Please contact Tenberry Technical Support. 

2503 "not enough disk space for swapping - <count> byes required" 

VMM was unable to create a swap file of the required size. Increase the amount of disk space 
available. 

2504 "can’t create swap file \<filename>\" " 

VMM was unable to create the swap file. This could be because the swap file is specified for a 
nonexistent drive or on a drive that is read-only. Set the SWAPNAME parameter to change the 
location of the swap file. 
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2505 "not enough memory for <table>" 

VMM was unable to get sufficient extended memory for internal tables. Make more memory 
available. If <table> is page buffer, make more DOS memory available. 

2506 "not enough physical memory (minmem)" 

There is less physical memory available than the amount specified by the MINMEM parameter. 
Make more memory available. 

2511 "swap out error [<error code>]" 

Unknown disk error. The error code is for Tenberry Software’ use. 

2512 "swap in error [<error code>]" 

Unknown disk error. The error code is for Tenberry Software’ use. 

2514 "can’t open trace file" 

VMM could not open the VMM.TRC file in the current directory for writing. If the directory 
already has a VMM.TRC file, delete it. If not, there may not be enough memory on the drive for the 
trace file, or DOS may not have any more file handles. 

2520 "can’t hook int 3lh" 

DOS/4G internal error. Please contact Tenberry Technical Support. 

2523 "page fault on non-present mapped page" 

Your program references memory that has been mapped to a nonexistent physical device, using 
DPMI function 508h. Make sure the device is present, or remove the reference. 

2524 "page fault on uncommitted page" 

Your program references memory reserved with a call to DPMI function 

504h, but never committed (using a DPMI 507h or 508h call). Commit the memory before you reference 
it. 

3301 "unhandledEMPTYFWD, GATE16, or unknown relocation" 

3302 "unhandled ALIAS 16 reference to unaliased object" 

3304 "unhandled or unknown relocation " 

If your program was built for another platform that supports the LINEXE format, it may contain a 
construct that DOS/4G does not currently support, such as a call gate. This message may also occur 
if your program has a problem mixing 16- and 32-bit code. A linker error is another likely cause. 
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14 D0S/4GW Commonly Asked Questions 


The following information has been provided by Tenberry Software, Inc. for their DOS/4GW and 
DOS/4GW Professional product. The content of this chapter has been edited by Open Watcom. In most 
cases, the information is applicable to both products. 

This chapter covers the following topics: 

• Access to technical support 

• Differences within the DOS/4G product line 

• Addressing 

• Interrupt and exception handling 

• Memory management 

• DOS, BIOS, and mouse services 

• Virtual memory 

• Debugging 

• Compatibility 


14.1 Access to Technical Support 

la. How to reach technical support. 

Here are the various ways you may contact Tenberry Software for technical support. 

WWW: http://www.tenberry.com/dos4g/ 

Email: 4gwhelp@tenberry.com 

Phone: 1.480.767.8868 

Fax: 1.480.767.8709 

Mail: Tenberry Software, Inc. 

PO Box 20050 

Fountain Hills, Arizona 

U.S.A 85269-0050 

PLEASE GIVE YOUR SERIAL NUMBER WHEN YOU CONTACT TENBERRY. 
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lb. When to contact Open Watcom, when to contact Tenberry. 

Since DOS/4GW Professional is intended to be completely compatible with DOS/4GW, you may wish 
to ascertain whether your program works properly under DOS/4GW before contacting Tenberry 
Software for technical support. (This is likely to be the second question we ask you, after your serial 
number.) 

If your program fails under both DOS/4GW and DOS/4GW Professional, and you suspect your own 
code or a problem compiling or linking, you may wish to contact Open Watcom first. Tenberry 
Software support personnel are not able to help you with most programming questions, or questions 
about using the Open Watcom tools. 

If your program only fails with DOS/4GW Professional, you have probably found a bug in DOS/4GW 
Professional, so please contact us right away. 

lc. Telephone support. 

Tenberry Software’s hours for telephone support are 9am-6pm EST. Please note that telephone support 
is free for the first 30 days only. A one-year contract for continuing telephone support on DOS/4GW 
Professional is US$500 per developer, including an update subscription for one year, to customers in the 
United States and Canada; for overseas customers, the price is $600. Site licenses may be negotiated. 

There is no time limit on free support by fax, mail, or electronic means. 

l d. References. 

The DOS/4GW documentation from Open Watcom is the primary reference for DOS/4GW Professional 
as well. Another useful reference is the DPMI specification. In the past, the DPMI specification could 
be obtained free of charge by contacting Intel Literature. We have been advised that the DPMI 
specification is no longer available in printed form. 

However, the DPMI 1.0 specification can be obtained at: 

http://www.delorie.com/djgpp/doc/dpmi/ 


Online HTML as well as a downloadable archive are provided. 


14.2 Differences Within the D0S/4G Product Line 


2a. DOS/4GW Professional versus DOS/4GW 

DOS/4GW Professional was designed to be a higher-performance version of DOS/4GW suitable for 
commercial applications. Here is a summary of the advantages of DOS/4GW Professional with respect 
to DOS/4GW: 

• Extender binds to the application program file 

• Extender startup time has been reduced 

• Support for Open Watcom floating-point emulator has been optimized 

• Virtual memory manager performance has been greatly improved 
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• Under VMM, programs are demand loaded 

• Virtual address space is 4 GB instead of 32 MB 

• Extender memory requirements have been reduced by more than 50K 

• Extender disk space requirements have been reduced by 40K 

• Can omit virtual memory manager to save 50K more disk space 

• Support for INT 3lh functions 301h-304h and 702h-703h 

DOS/4GW Professional is intended to be fully compatible with programs written for DOS/4GW 1.9 and 
up. The only functional difference is that the extender is bound to your program instead of residing in a 
separate file. Not only does this help reduce startup time, but it eliminates version-control problems 
when someone has both DOS/4GW and DOS/4GW Professional applications present on one machine. 

2b. DOS/4GW Professional versus DOS/4G. 

DOS/4GW Professional is not intended to provide any other new DOS extender functionality. Tenberry 
Software’s top-of-the-line 32-bit extender, DOS/4G, is not sold on a retail basis but is of special interest 
to developers who require more flexibility (such as OEMs). DOS/4G offers these additional features 
beyond DOS/4GW and DOS/4GW Professional: 

• Complete documentation 

• DLL support 

• TSR support 

• Support for INT 31h functions 301h-306h, 504h-50Ah, 702h-703h 

•AC language API that offers more control over interrupt handling and program loading, as well 
as making it easier to use the extender 

• An optional (more protected) nonzero-based flat memory model 

• Remappable error messages 

• More configuration options 

• The D32 debugger, GLU linker, and other tools 

• Support for other compilers besides Open Watcom 

• A higher level of technical support 

• Custom work is available (e.g., support for additional executable formats, operating system API 
emulations, mixed 16-bit and 32-bit code) 

Please contact Tenberry Software if you have questions about other products (present or future) in the 
DOS/4G line. 
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2c. DPMI functions supported by DOS/4GW. 

Note that when a DOS/4GW application runs under a DPMI host, such as Windows 3.1 in enhanced 
mode, an OS/2 virtual DOS machine, 386Max (with DEBUG=DPMIXCOPY), or QDPMI (with 
EXTCHKOFF), the DPMI host provides the DPMI services, not DOS/4GW. The DPMI host also 
provides virtual memory, if any. Performance (speed and memory use) under different DPMI hosts 
varies greatly due to the quality of the DPMI implementation. 

These are the services provided by DOS/4GW and DOS/4GW Professional in the absence of a DPMI 
host. 

0000 Allocate LDT Descriptors 

0001 Free LDT Descriptor 

0002 Map Real-Mode Segment to Descriptor 

0003 Get Selector Increment Value 

0006 Get Segment Base Address 

0007 Set Segment Base Address 

0008 Set Segment Limit 

0009 Set Descriptor Access Rights 

000A Create Alias Descriptor 

000B Get Descriptor 

000C Set Descriptor 

000D Allocate Specific LDT Descriptor 

0100 Allocate DOS Memory Block 

0101 Free DOS Memory Block 

0102 Resize DOS Memory Block 

0200 Get Real-Mode Interrupt Vector 

0201 Set Real-Mode Interrupt Vector 

0202 Get Processor Exception Handler 

0203 Set Processor Exception Handler 

0204 Get Protected-Mode Interrupt Vector 

0205 Set Protected-Mode Interrupt Vector 

0300 Simulate Real-Mode Interrupt 

0301 Call Real-Mode Procedure with Far Return Frame (DOS/4GW Professional only) 

0302 Call Real-Mode Procedure with IRET Frame (DOS/4GW Professional only) 

0303 Allocate Real-Mode Callback Address (DOS/4GW Professional only) 

0304 Free Real-Mode Callback Address (DOS/4GW Professional only) 

0400 Get DPMI Version 

0500 Get Free Memory Information 

0501 Allocate Memory Block 

0502 Free Memory Block 

0503 Resize Memory Block 

0600 Lock Linear Region 

0601 Unlock Linear Region 

0604 Get Page Size (VM only) 

0702 Mark Page as Demand Paging Candidate (DOS/4GW Professional only) 
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0703 Discard Page Contents (DOS/4GW Professional only) 

0800 Physical Address Mapping 

0801 Free Physical Address Mapping 

0900 Get and Disable Virtual Interrupt State 

0901 Get and Enable Virtual Interrupt State 

0902 Get Virtual Interrupt State 

OA 00 Get Tenberry Software API Entry Point 

0E00 Get Coprocessor Status 

0E01 Set Coprocessor Emulation 

14.3 Addressing 

3a. Converting between pointers and linear addresses. 

Because DOS/4GW uses a zero-based flat memory model, converting between pointers and linear 
addresses is trivial. A pointer value is always relative to the current segment (the value in CS for a code 
pointer, or in DS or SS for a data pointer). The segment bases for the default DS, SS, and CS are all 
zero. Hence a near pointer is exactly the same thing as a linear address: a null pointer points to linear 
address 0, and a pointer with value 0x10000 points to linear address 0x10000. 

3b. Converting between code and data pointers. 

Because DS and CS have the same base address, they are natural aliases for each other. To create a data 
alias for a code pointer, merely create a data pointer and set it equal to the code pointer. It’s not 
necessary for you to create your own alias descriptor. Similarly, to create a code alias for a data pointer, 
merely create a code pointer and set it equal to the data pointer. 

3c. Converting between pointers and low memory addresses. 

Linear addresses under 1 MB map directly to physical memory. Hence the real-mode interrupt vector 
table is at address 0, the BIOS data segment is at address 0x400, the monochrome video memory is at 
address OxBOOOO, and the color video memory is at address 0xB8000. To read and write any of these, 
you can just use a pointer set to the proper address. You don't need to create a far pointer, using some 
magic segment value. 

3d. Converting between linear and physical addresses. 

Linear addresses at or above 1 MB do not map directly to physical memory, so you can not in general 
read or write extended memory directly, nor can you tell how a particular block of extended memory 
has been used. 

DOS/4GW supports the DPMI call INT 31h/800h, which maps physical addresses to linear addresses. 

In other words, if you have a peripheral device in your machine that has memory at a physical address 
of 256 MB, you can issue this call to create a linear address that points to that physical memory. The 
linear address is the same thing as a near pointer to the memory and can be manipulated as such. 

There is no way in a DPMI environment to determine the physical address corresponding to a given 
linear address. This is part of the design of DPMI. You must design your application accordingly. 
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3e. Null pointer checking. 

D0S/4GW will trap references to the first sixteen bytes of physical memory if you set the environment 
variable DOS4G=NULLP. This is currently the only null-pointer check facility provided by 
DOS/4GW. 

As of release 1.95, DOS/4GW traps both reads and writes. Prior to this, it only trapped writes. 

You may experience problems if you set DOS4G=NULLP and use some versions of the Open Watcom 
Debugger with a 1.95 or later extender. These problems have been corrected in later versions of the 
Open Watcom Debugger. 

14.4 Interrupt and Exception Handling 

4a. Handling asynchronous interrupts. 

Under DOS/4GW, there is a convenient way to handle asynchronous interrupts and an efficient way to 
handle them. 

Because your CPU may be in either protected mode (when 32-bit code is executing) or real mode (a 
DOS or BIOS call) when a hardware interrupt comes in, you have to be prepared to handle interrupts in 
either mode. Otherwise, you may miss interrupts. 

You can handle both real-mode and protected-mode interrupts with a single handler, if 1) the interrupt 
is in the auto-passup range, 8 to 2Eh; and 2) you install a handler with INT 21h/25h or _dos_setvect(); 

3) you do not install a handler for the same interrupt using any other mechanism. DOS/4GW will route 
both protected-mode interrupts and real-mode interrupts to your protected-mode handler. This is the 
convenient way. 

The efficient way is to install separate real-mode and protected-mode handlers for your interrupt, so 
your CPU won't need to do unnecessary mode switches. Writing a real-mode handler is tricky; all you 
can reasonably expect to do is save data in a buffer and IRET. Your protected-mode code can 
periodically check the buffer and process any queued data. (Remember, protected-mode code can 
access data and execute code in low memory, but real-mode code can’t access data or execute code in 
extended memory.) 

For performance, it doesn’t matter how you install the real-mode handler, but we recommend the DPMI 
function INT 31h/201h for portability. 

It does matter how you install the protected-mode handler. You can’t install it directly into the IDT, 
because a DPMI provider must distinguish between interrupts and exceptions and maintain separate 
handler chains. Installing with INT 31h/205h is the recommended way to install your protected-mode 
handler for both performance and portability. 

If you install a protected-mode handler with INT 21h/25h, both interrupts and exceptions will be 
funneled to your handler, to mimic DOS. Since DPMI exception handlers and interrupt handlers are 
called with different stack frames, DOS/4GW executes a layer of code to cover these differences up; the 
same layer is used to support the DOS/4G API (not part of DOS/4GW). This layer is the reason that 
hooking with INT 21h/25h is less efficient than hooking with INT 31h/205h. 


108 Interrupt and Exception Handling 




D0S/4GW Commonly Asked Questions 


4b. Handling asynchronous interrupts in the second IRQ range. 

Because the second IRQ range (normally INTs 70h-77h) is outside the DOS/4GW auto-passup range 
(8-2Eh, excluding 2 lh) you may not handle these interrupts with a single handler, as described above 
(the "convenient" method). You must install separate real-mode and protected-mode handlers (the 
"efficient" method). 

DOS/4G does allow you to specify additional passup interrupts, however. 

4c. Asynchronous interrupt handlers and DPMI. 

The DPMI specification requires that all code and data referenced by a hardware interrupt handler 
MUST be locked at interrupt time. A DPMI virtual memory manager can use the DOS file system to 
swap pages of memory to and from the disk; because DOS is not reentrant, a DPMI host is not required 
to be able to handle page faults during asynchronous interrupts. Use INT 31h/600h (Lock Linear 
Region) to lock an address range in memory. 

If you fail to lock all of your code and data, your program may run under DOS/4GW, but fail under the 
DOS/4GW Virtual Memory Manager or under another DPMI host such as Windows or OS/2. 

You should also lock the code and data of a mouse callback function. 

4d. Open Watcom signal() function and Ctrl-Break. 

In earlier versions of the Open Watcom C/C++ library, there was a bug that caused signal(SIGBREAK) 
not to work. Calling signal(SIGBREAK) did not actually install an interrupt handler for Ctrl-Break 
(INT lBh), so Ctrl-Break would terminate the application rather than invoking the signal handler. 

With these earlier versions of the library, you could work around this problem by hooking INT lBh 
directly. With release 10.0, this problem has been fixed. 

4e. More tips on writing hardware interrupt handlers. 

• It’s more like handling interrupts in real mode than not. 

The same problems arise when writing hardware interrupt handlers for protected mode as arise for real 
mode. We assume you know how to write real-mode handlers; if our suggestions don't seem clear, 
you might want to brush up on real-mode interrupt programming. 

• Minimize the amount of time spent in your interrupt handlers. 

When your interrupt handlers are called, interrupts are disabled. This means that no other system tasks 
can be performed until you enable interrupts (an STI instruction) or until your handler returns. In 
general, it’s a good idea to handle interrupts as quickly as possible. 

• Minimize the amount of time spent in the DOS extender by installing separate real-mode and 
protected-mode handlers. 

If you use a passup interrupt handler, so that interrupts received in real mode are resignalled in 
protected mode by the extender, your application has to switch from real mode to protected mode to 
real mode once per interrupt. Mode switching is a time-consuming process, and interrupts are disabled 
during a mode switch. Therefore, if you’re concerned about performance, you should install separate 
handlers for real-mode and protected-mode interrupts, eliminating the mode switch. 
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• If you can’t just set a flag and return, enable interrupts (STI). 

Handlers that do more than just set a flag or store data in a buffer should re-enable interrupts as soon as 
it’s safe to do so. In other words, save your registers on the stack, establish your addressing 
conventions, switch stacks if you’re going to — and then enable interrupts (STI), to give priority to 
other hardware interrupts. 

• If you enable interrupts (STI), you should disable interrupts (CLI). 

Because some DPMI hosts virtualize the interrupt flag, if you do an STI in your handler, you should be 
sure to do a CLI before you return. (CLI, then switch back to the original stack if you switched away, 
then restore registers, then IRET.) If you don't do this, the IRET will not necessarily restore the 
previous interrupt flag state, and your program may crash. This is a difference from real-mode 
programming, and it tends to show up as a problem when you try running your program in a Windows 
or OS/2 DOS box for the first time (but not before). 

• Add a reentrancy check. 

If your handler doesn’t complete its work by the time the next interrupt is signalled, then interrupts can 
quickly nest to the point of overflowing the transfer stack. This is a design flaw in your program, not 
in the DOS extender; a real-mode DOS program can have exactly the same behavior. If you can 
conceive of a situation where your interrupt handler can be called again before the first instance 
returns, you need to code in a reentrancy check of some sort (before you switch stacks and enable 
interrupts (STI), obviously). 

Remember that interrupts can take different amounts of time to execute on different machines; the CPU 
manufacturer, CPU speed, speed of memory accesses, and CMOS settings (e.g. "system BIOS 
shadowing") can all affect performance in subtle ways. We recommend you program defensively and 
always check for unexpected reentry, to avoid transfer stack overflows. 

• Switch to your own stack. 

Interrupt handlers are called on a stack that typically has only a small amount of stack available (512 
bytes or less). If you need to use more stack than this, you have to switch to your own stack on entry 
into the handler, and switch back before returning. 

If you want to use C run-time library functions, which are compiled for flat memory model (SS == DS, 
and the base of CS == the base of DS), you need to switch back to a stack in the flat data segment first. 

Note that switching stacks by itself won’t prevent transfer stack overflows of the kind described above. 

14.5 Memory Management 

5a. Using the realloc() function. 

In versions of Open Watcom C/C++ prior to 9.5b, there was a bug in the library implementation of 
realloc() under DOS/4GW and DOS/4GW Professional. This bug was corrected by Open Watcom in 
the 9.5b release. 
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5b. Using all of physical memory. 

D0S/4GW Professional is currently limited to 64 MB of physical memory. We do not expect to be able 
to fix this problem for at least six months. If you need more than 64 MB of memory, you must use 
virtual memory. 

14.6 DOS, BIOS, and Mouse Services 

6a. Speeding up file I/O. 

The best way to speed up DOS file I/O in DOS/4GW is to write large blocks (up to 65535 bytes, or the 
largest number that will fit in a 16-bit int) at a time from a buffer in low memory. In this case, 
DOS/4GW has to copy the least amount of data and make the fewest number of DOS calls in order to 
process the I/O request. 

Low memory is allocated through INT 31h/0100h, Allocate DOS Memory Block. You can convert the 
real-mode segment address returned by INT 31h/0100h to a pointer (suitable for passing to setvbuf()) by 
shifting it left four bits. 

6b. Spawning. 

It is possible to spawn one DOS/4GW application from another. However, two copies of the DOS 
extender will be loaded into memory. DOS/4G supports loading of multiple programs atop a single 
extender, as well as DLLs. 

6c. Mouse callbacks. 

DOS/4GW Professional now supports the INT 3lh interface for managing real-mode callbacks. 
However, you don’t need to bother with them for their single most important application: mouse 
callback functions. Just register your protected-mode mouse callback function as you would in real 
mode, by issuing INT 33h/OCh with the event mask in CX and the function address in ES:EDX, and 
your function will work as expected. 

Because a mouse callback function is called asynchronously, the same locking requirement exists for a 
mouse callback function as for a hardware interrupt handler. See (4c) above. 

6d. VESA support. 

While DOS/4GW automatically handles most INT lOh functions so that you can you can issue them 
from protected mode, it does not translate the INT lOh VESA extensions. The workaround is to use 
INT 31h/300h (Simulate Real-Mode Interrupt). 


14.7 Virtual Memory 

7a. Testing for the presence of VMM. 

INT 31h/400h returns a value (BX, bit 2) that tells if virtual memory is available. Under a DPMI host 
such as Windows 3.1, this will be the host’s virtual memory manager, not DOS/4GW's. 
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You can test for the presence of a DOS/4G-family DOS extender with INT 31h/0A00h, with a pointer 
to the null-terminated string "RATIONAL DOS/4G" in DS:ESI. If the function returns with carry clear, 
a DOS/4G-family extender is running. 

7b. Reserving memory for a spawned application. 

If you spawn one DOS/4GW application from another, you should set the DELETES WAP 
configuration option (i.e., SET DOS4GVM=deleteswap) so that the two applications don't try to use the 
same swap file. You should also set the MAXMEM option low enough so that the parent application 
doesn't take all available physical memory; memory that’s been reserved by the parent application is 
not available to the child application. 

7c. Instability under VMM. 

A program that hooks hardware interrupts, and works fine without VMM but crashes sporadically with 
it, probably needs to lock the code and data for its hardware interrupt handlers down in memory. 
DOS/4GW does not support page faults during hardware interrupts, because DOS services may not be 
available at that time. See (4c) and (6c) above. 

Memory can be locked down with INT 31h/600h (Lock Linear Region). 

7d. Running out of memory with a huge virtual address space. 

Because DOS/4GW has to create page tables to describe your virtual address space, we recommend that 
you set your VIRTUALSIZE parameter just large enough to accommodate your program. If you set 
your VIRTUALSIZE to 4 GB, the physical memory occupied by the page tables will be 4 MB, and that 
memory will not be available to DOS/4GW. 

7e. Reducing the size of the swap file. 

DOS/4GW will normally create a swap file equal to your VIRTUALSIZE setting, for efficiency. 
However, if you set the SWAPMIN parameter to a size (in KB), DOS/4GW will start with a swap file 
of that size, and will grow the swap file when it has to. The SWAPINC value (default 64 KB) controls 
the incremental size by which the swap file will grow. 

7f Deleting the swap file. 

The DELETESWAP option has two effects: telling DOS/4GW to delete the swap file when it exits, and 
causing DOS/4GW to provide a unique swap file name if an explicit SWAPNAME setting was not 
given. 

DELETESWAP is required if one DOS/4GW application is to spawn another; see (7b) above. 

7g. Improving demand-load performance of large static arrays. 

DOS/4GW demand-loading feature normally cuts the load time of a large program drastically. 

However, if your program has large amounts of global, zero-initialized data (storage class BSS), the 
Open Watcom startup code will explicitly zero it (version 9.5a or earlier). Because the zeroing 
operation touches every page of the data, the benefits of demand-loading are lost. 

Demand loading can be made fast again by taking advantage of the fact that DOS/4GW automatically 
zeroes pages of BSS data as they are loaded. You can make this change yourself by inserting a few 
lines into the startup routine, assembling it (MASM 6.0 will work), and listing the modified object 
module first when you link your program. 
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Here are the changes for \watcom\src:\startup\38 6\cstart3r . asm (startup module from 
the C/C++ 9.5 compiler, library using register calling conventions). You can modify the workaround 
easily for other Open Watcom compilers: 


; cstart3r.asm, circa line 332 
; end of _ BSS segment (start of STACK) 


mov 

ecx,offset 

DGROUP 

_ end 



; 

start of _ BSS segment 

mov 

edi,offset 

DGROUP 

_ edata 

— 


-; 

RSI OPTIMIZATION 

mov 

eax, edi 

; 

minimize _ BSS initialization loop 

or 

eax, OFFFh 

; 

compute address of first page after 

inc 

eax 

; 

start of _ BSS 

cmp 

eax, ecx 

; 

if _ BSS extends onto that page. 

jae 

allzero 

; 

then we can rely on the loader 

mov 

ecx, eax 


zeroing the remaining pages 




END RSI OPTIMIZATION 

sub 

ecx,edi 

; 

calc # of bytes in _ BSS segment 

mov 

dl, cl 

; 

save bottom 2 bits of count in edx 

shr 

ecx, 2 

; 

calc # of dwords 

sub 

eax,eax 

; 

zero the _ BSS segment 

rep 

stosd 

; 


mov 

cl, dl 

; 

get bottom 2 bits of count 

and 

cl, 3 

; 


rep 

stosb 

; 



Note that the 9.5b and later versions of the Open Watcom C library already contain this enhancement. 

7h. How should I configure VM for best performance? 

Here are some recommendations for setting up the DOS/4GW virtual memory manager. 

VIRTUALSIZE Set to no more than twice the total amount of memory (virtual and otherwise) your 

program requires. If your program has 16 MB of code and data, set to 32 MB. (There 
is only a small penalty for setting this value larger than you will need, but your program 
won't run if you set it too low.) See (7d) above. 

MINMEM Set to the minimum hardware requirement for running your application. (If you require 
a 2 MB machine, set to 2048). 

MAXMEM Set to the maximum amount of memory you want your application to use. If you don't 
spawn any other applications, set this large (e.g., 32000) to make sure you can use all 
available physical memory. If you do spawn, see (7b) above. 

SWAPMIN Don’t use this if you want the best possible VM performance. The trade-off is that 
DOS/4GW will create a swap file as big as your VIRTU ALSIZE. 

SWAPINC Don't use this if you want the best possible VM performance. 

DELETESWAP DOS/4GW’s VM will start up slightly slower if it has to create the swap file afresh 
each time. However, unless your swap file is very large, DELETESWAP is a 
reasonable choice; it may be required if you spawn another DOS/4GW program at the 
same time. See (7b) above. 
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14.8 Debugging 

8a. Attempting to debug a bound application. 

You can’t debug a bound application. The 4GWBIND utility (included with DOS/4GW Professional) 
will allow you to take apart a bound application so that you can debug it: 

4GWBIND -U <boundapp.exe> <yourapp.exe> 

8b. Debugging with an old version of the Open Watcom debugger. 

DOS/4GW supports versions 8.5 and up of the Open Watcom C, C++ and FORTRAN compilers. 
However, in order to debug your unbound application with a Open Watcom debugger, you must have 
version 9.5a or later of the debugger. 

If you have an older version of the debugger, we strongly recommend that you contact Open Watcom to 
upgrade your compiler and tools. The only way to debug a DOS/4GW Professional application with an 
old version of the debugger is to rename 4GWPRO.EXE to DOS4GW.EXE and make sure that it’s 
either in the current directory or the first DOS4GW.EXE on the DOS PATH. 

Tenberry will not provide technical support for this configuration; it’s up to you to keep track of which 
DOS extender is which. 

8c. Meaning of "unexpected interrupt" message/error 2001. 

In version 1.95 of DOS/4GW, we revised the "unexpected interrupt" message to make it easier to 
understand. 

For example, the message: 

Unexpected interrupt OE (code 0) at 168:10421034 


is now printed: 

error (2001) : exception OEh (page fault) at 168:10421034 


followed by a register dump, as before. 


This message indicates that the processor detected some form of programming error and signaled an 
exception, which DOS/4GW trapped and reported. Exceptions which can be trapped include: 

OOh divide by zero 

Olh debug exception OR null pointer used 

03h breakpoint 

04h overflow 

05h bounds 

06h invalid opcode 

07h device not available 

08h double fault 

09h overrun 

OAh invalid TSS 

OBh segment not present 

OCh stack fault 

ODh general protection fault 

OEh page fault 
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When you receive this message, this is the recommended course of action: 

1. Record all of the information from the register dump. 

2. Determine the circumstances under which your program fails. 

3. Consult your debugger manual, or an Intel 386, 486 or Pentium Programmer’s Reference 
Manual, to determine the circumstances under which the processor will generate the reported 
exception. 

4. Get the program to fail under your debugger, which should stop the program as soon as the 
exception occurs. 

5. Determine from the exception context why the processor generated an exception in this 
particular instance. 

8d. Meaning of "transfer stack overflow" message/error 2002. 

In version 1.95 of DOS/4GW, we added more information to the "transfer stack overflow" message. 

The message (which is now followed by a register dump) is printed: 

error (2002): transfer stack overflow 

on interrupt <number> at <address> 


This message means DOS/4GW detected an overflow on its interrupt handling stack. It usually 
indicates either a recursive fault, or a hardware interrupt handler that can’t keep up with the rate at 
which interrupts are occurring. The best way to understand the problem is to use the VERBOSE option 
in DOS/4GW to dump the interrupt history on the transfer stack; see (8e) below. 

He. Making the most of a DOS/4GW register dump. 

If you can’t understand your problem by running it under a debugger, the DOS/4GW register dump is 
your best debugging tool. To maximize the information available for postmortem debugging, set the 
environment variable DOS4G to VERBOSE, then reproduce the crash and record the output. 


Here’s a typical register dump with VERBOSE turned on, with annotations. 


1 

2 
3 


4 


5 

6 
7 


DOS/4GW error (2001): exception 


OEh (page fault) 

at 170:0042C1B2 


TSF32 : prev_ tsf32 
SS 178 DS 

EAX 1F000000 EBX 
ESI E EDI 


67D8 

178 ES 
0 ECX 
0 EBP 


CS : IP 170 : 0042C1B2 ID 0E COD 


178 FS 
43201C EDX 
431410 ESP 
0 FLG 


0 GS 
E 

4313FC 

10246 


20 


cs= 

170, 

USE32, 

page 

granular. 

limit 

FFFFFFFF, 

base 

0, 

acc 

CF9B 

ss= 

178, 

USE32, 

page 

granular. 

limit 

FFFFFFFF, 

base 

0, 

acc 

CF93 

DS= 

178, 

USE32, 

page 

granular. 

limit 

FFFFFFFF, 

base 

0, 

acc 

CF93 

ES= 

178, 

USE32, 

page 

granular. 

limit 

FFFFFFFF, 

base 

0, 

acc 

CF93 

FS= 

0, 

USE16, 

byte 

granular. 

limit 

0 f 

base 

15, 

acc 

0 

GS= 

20, 

USE16, 

byte 

granular. 

limit 

FFFF, 

base 

6AA0, 

acc 

93 


CR0: PG:1 ET:1 TS:0 EM:0 MP:0 PE:1 CR2: 1F000000 CR3: 9067 
Crash address (unrelocated) = 1:000001B2 

Opcode stream: 8A 18 31 D2 88 DA EB 0E 50 68 39 00 43 00 E8 ID 
Stack: 


8 0178:004313FC 000E 0000 0000 0000 C2D5 0042 C057 0042 0170 0000 0000 0000 

0178:00431414 0450 0043 0452 0043 0000 0000 1430 0043 CBEF 0042 011C 0000 

0178:0043142c C568 0042 0000 0000 0000 0000 0000 0000 F248 0042 F5F8 0042 

0178:00431444 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 

0178:0043145c 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 

0178:00431474 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 

9 Last 4 ints: 21 @ 170:42CF48/21 @ 170:42CF48/21 @ 170:42CF48/E @ 170:42C1B2/ 
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1. The error message includes a synopsis of the problem. In this case, the processor signaled a 
page fault exception while executing at address 170:0042C1B2. 

2. The prev_tsf32 field is not usually of interest. 

3. These are the register values at the time of the exception. The interrupt number and error 
code (pushed on the stack by the processor for certain exceptions) are also printed. 

4. The descriptors referenced by each segment register are described for your convenience. 
USE32 segments in general belong to your program; USE16 segments generally belong to 
the DOS extender. Here, CS points to your program’s code segment, and SS, DS, and ES 
point to your data segment. FS is NULL and GS points to a DOS extender segment. 

5. The control register information is not of any general interest, except on a page fault, when 
CR2 contains the address value that caused the fault. Since EAX in this case contains the 
same value, an attempt to dereference EAX could have caused this particular fault. 

6. If the crash address (unrelocated) appears, it tells you where the crash occurred relative to 
your program’s link map. You can therefore tell where a crash occurred even if you can’t 
reproduce the crash in a debugger. 

7. The opcode stream, if it appears, shows the next 16 bytes from the code segment at the point 
of the exception. If you disassemble these instructions, you can tell what instructions caused 
the crash, even without using a debugger. In this case, 8A 18 is the instruction mov 

bl, [eax] . 

8. 72 words from the top of the stack, at the point of the exception, may be listed next. You 
may be able to recognize function calls or data from your program on the stack. 

9. The four interrupts least to most recently handled by DOS/4GW in protected mode are listed 
next. In this example, the last interrupt issued before the page fault occurred was an INT 21h 
(DOS call) at address 170:42CF48. Sometimes, this information provides helpful context. 


Here’s an abridged register dump from a stack overflow. 


1 

2 


3 


4 

5 


DOS/4GW error (2002) 


transfer stack overflow 

on interrupt 70h at 170:0042C002 


TSF32: prev_ tsf32 48C8 
SS C8 DS 170 

EAX AAAAAAAA EBX BBBBBBBB 
ESI 51515151 EDI D1D1D1D1 
CS:IP 170:0042C002 ID 70 

Previous TSF: 

TSF32 : prev_ tsf32 498C 
SS C8 DS 170 

EAX AAAAAAAA EBX BBBBBBBB 
ESI 51515151 EDI D1D1D1D1 
CS:IP 170:0042C002 ID 70 

Previous TSF: 

TSF32: prev_ tsf32 67E4 
SS 178 DS 170 

EAX AAAAAAAA EBX BBBBBBBB 
ESI 51515151 EDI D1D1D1D1 
CS:IP 170:0042C039 ID 70 
Opcode stream: CF 66 B8 62 
Last 4 ints: 70 @ 170:42C002/70 @ 170:42C002/70 @ 170:42C002/70 @ 170:42C002/ 


ES 

28 

FS 

0 

GS 

20 

ECX 

CCCCCCCC 

EDX 

DDDDDDDD 



EBP 

B1B1B1B1 

ESP 

4884 



COD 

0 

FLG 

2 



ES 

28 

FS 

0 

GS 

20 

ECX 

CCCCCCCC 

EDX 

DDDDDDDD 



EBP 

B1B1B1B1 

ESP 

4960 



COD 

0 

FLG 

2 



ES 

28 

FS 

0 

GS 

20 

ECX 

CCCCCCCC 

EDX 

DDDDDDDD 



EBP 

B1B1B1B1 

ESP 

42FFE0 



COD 

0 

FLG 

202 



: 25 

66 8C CB 

66 : 

8E DB BA 00 CO 

42 00 


1. We overflowed the transfer stack while trying to process an interrupt 70h at 170:0042C002. 
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2. The entire interrupt history from the transfer stack is printed next. The prev_tsf32 numbers 
increase as we progress from most recent to least recent interrupt. All of these interrupts are 
still pending, which is why we ran out of stack space. 

3. Before we overflowed the stack, we got the same interrupt at the same address. For a 
recursive interrupt situation, this is typical. 

4. The oldest frame on the transfer stack shows the recursion was touched off at a slightly 
different address. Looking at this address may help you understand the recursion. 

5. The opcode stream and last four interrupt information comes from the newest transfer stack 
frame, not the oldest. 


14.9 Compatibility 

9a. Running DOS/4GW applications from inside Lotus 1-2-3. 

In order to run DOS/4GW applications while "shelled out" from Lotus 1-2-3, you must use the 
PR1VATXM program included with your Open Watcom compiler. Otherwise, 1-2-3 will take all of the 
memory on your machine and prevent DOS/4GW from using it. 

Before starting 1-2-3, you must set the DOS16M environment variable to limit Lotus’ memory use (see 
your Open Watcom manual). After shelling out, you must run PRIVATXM, then clear the DOS16M 
environment variable before running your application. 

9b. EMM386.EXE provided with DOS 6.0. 

We know of at least three serious bugs in the EMM386.EXE distributed with MS-DOS 6.0, one 
involving mis-counting the amount of available memory, one involving mapping too little of the High 
Memory Area (HMA) into its page tables, and one involving allocation of EMS memory. Version 1.95 
of DOS/4GW contains workarounds for some of these problems. 

If you are having problems with DOS/4GW and you are using an EMM386.EXE dated 3-10-93 at 
6:00:00, or later, you may wish to try the following workarounds, in sequence, until the problem goes 
away. 


• Configure EMM386 with both the NOEMS and NOVCPI options. 

• Convert the DEVICEHIGH statements in your CONFIG.SYS to DEVICE statements, and 
remove the LH (Load High) commands from your AUTOEXEC.BAT. 

• Run in a Windows DOS box. 

• Replace EMM386 with another memory manager, such as QEMM-386, 386Max, or an older 
version of EMM386. 

• Run with HIMEM.SYS alone. 

You may also wish to contact Microsoft Corporation to inquire about the availability of a fix. 
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9c. Spawning under OS/2 2.1. 

We know of a bug in OS/2 2.1 that prevents one DOS/4GW application from spawning another over 
and over again. The actual number of repeated spawns that are possible under OS/2 varies from 
machine to machine, but is generally about 30. 

This bug also affects programs running under other DOS extenders, and we have not yet found a 
workaround, other than linking your two programs together as a single program. 

9d. "DPMI host error: cannot lock stack". 

This error message almost always indicates insufficient memory, rather than a real incompatibility. If 
you see it under an OS/2 DOS box, you probably need to edit your DOS Session settings and make 
DPMI_MEMORY_LIMIT larger. 

9e. Bug in Novell TCPIP driver. 

Some versions of a program from Novell called TCPIP.EXE, a real-mode program, will cause the high 
words of EAX and EDX to be altered during a hardware interrupt. This bug breaks protected-mode 
software (and other real-mode software that uses the 80386 registers). Novell has released a newer 
version of TCPIP that fixes the problem; contact Novell to obtain the fix. 

9f. Bugs in Windows NT. 

The initial release of Windows NT includes a DPMI host, DOSX.EXE, with several serious bugs, some 
of which apparently cannot be worked around. We cannot warranty operation of DOS/4GW under 
Windows NT at this time, but we are continuing to exercise our best efforts to work around these 
problems. 


You may wish to contact Microsoft Corporation to inquire about the availability of a new version of 
DOSX.EXE. 
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15 Creating 16-bit Windows 3.x Applications 


This chapter describes how to compile and link 16-bit Windows 3.x applications simply and quickly. In 
this chapter, we look at applications written to exploit the Windows 3.x Application Programming Interface 
(API). 

We will illustrate the steps to creating 16-bit Windows 3.x applications by taking a small sample 
application and showing you how to compile, link, run and debug it. 

Note - It is supposed you are working on the host with Windows 3.x installed. If you are on the host with 
any other operating system you should setup INCLUDE environment variable correctly to compile for 
16-bit Windows 3.x target. 

You can do that by command (DOS, OS/2, NT) 

set INCLUDE=%WATCOM%\h;%WATCOM%\h\win 

or by command (LINUX) 

export INCLUDE=$WATCOM/h:$WATCOM/h/win 

15.1 The Sample GUI Application 

To demonstrate the creation of 16-bit Windows 3.x applications, we introduce a simple sample program. 
The following example is the "hello" program adapted for Windows. 

♦include <windows.h> 

int PASCAL WinMain( HANDLE hlnstance, HANDLE hPrevInst, 

LPSTR lpCmdLine, int nCmdShow ) 

{ 

MessageBox( NULL, "Hello world", 

"Open Watcora C/C++ for Windows", 

MB_ OK | MB_ TASKMODAL ) ; 

return( 0 ) ; 

} 

The goal of this program is to display the message "Hello world" on the screen. The MessageBox 
Windows API function is used to accomplish this task. We will take you through the steps necessary to 
produce this result. 
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15.2 Building and Running the GUI Application 

To compile and link our example program which is stored in the file hello. c, enter the following 
command: 

C>wcl -l=windows -bt=windows hello.c 


The typical messages that appear on the screen are shown in the following illustration. 

C>wcl -l=windows -bt=windows hello.c 

Open Watcom C/C++16 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

wcc hello.c -bt=windows 
Open Watcom Cl6 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 10 lines, included 6500, 0 warnings, 0 errors 

Code size: 37 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows 16-bit executable 


If you examine the current directory, you will find that two files have been created. These are 
hello, obj (the result of compiling hello, c) and hello.exe (the result of linking hello, obj 
with the appropriate Open Watcom C/C++ libraries). 

The resultant 16-bit Windows 3.x application HELLO. EXE can now be run under Windows 3.x. 

15.3 Debugging the GUI Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "hello" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WCL command, this is fairly straightforward. WCL recognizes the Open Watcom C/C++ 
compiler "debug" options and will create the appropriate debug directives for the Open Watcom Linker. 

For example, to compile and link the "hello" program with debugging information, the following command 
may be issued. 

C>wcl -l=windows -bt=windows -d2 hello.c 
The typical messages that appear on the screen are shown in the following illustration. 
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C>wcl -l=windows -bt=windows -d2 hello.c 
Open Watcom C/C++16 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

wcc hello.c -bt=windows -d2 
Open Watcom Cl6 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 10 lines, included 6500, 0 warnings, 0 errors 

Code size: 58 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows 16-bit executable 


The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom C/C++ compiler. WCL will make sure that this debugging information is included in the 
executable file that is produced by the linker. 

The "Code size" value is larger than in the previous example since selection of the "d2" option results in 
fewer code optimizations by default. You can request more optimization by specifying the appropriate 
options. However, you do so at the risk of making it more difficult for yourself to determine the 
relationship between the object code and the original source language code. 

To request the Open Watcom Debugger to assist in debugging the application, select the Open Watcom 
Debugger icon. It would be too ambitious to describe the debugger in this introductory chapter so we refer 
you to the book entitled Open Watcom Debugger User’s Guide. 
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16 Porting Non-GUI Applications to 16-bit 
Windows 3.x 


Generally, an application that is to run in a windowed environment must be written in such a way as to 
exploit the Windows Application Programming Interface (API). To take an existing character-based (i.e., 
non-graphical) application that ran under a system such as DOS and adapt it to run under Windows can 
require some considerable effort. There is a steep learning curve associated with the API function libraries. 

This chapter describes how to create a Windows application quickly and simply from an application that 
does not use the Windows API. The application will make use of Open Watcom’s default windowing 
support. 

Suppose you have a set of C/C++ applications that previously ran under a system like DOS and you now 
wish to run them under Windows 3.x. To achieve this, you can simply recompile your application with the 
appropriate options and link with the appropriate libraries. We provide a default windowing system that 
turns your character-mode application into a simple Windows 3.x Graphical User Interface (GUI) 
application. 

Normally, a Windows 3.x GUI application makes use of user-interface tools such as menus, icons, scroll 
bars, etc. However, an application that was not designed as a windowed application (such as a DOS 
application) can run as a GUI application. This is achieved by our default windowing system. The 
following sections describe the default windowing system. 


16.1 Console Device in a Windowed Environment 


In a C/C++ application that runs under DOS, stdin (C++ tin) and stdout (C+ + cout) are connected to the 
standard input and standard output devices respectively. It is not a recommended practice to read directly 
from the standard input device or write to the standard output device when running in a windowed 
environment. For this reason, a default windowing environment is created for C/C++ applications that read 
from stdin (C++ tin) or write to stdout (C++ cout). When your application is started, a window is created 
in which output to stdout (C++ cout) is displayed and input from stdin (C++ tin) is requested. 

In addition to the standard I/O device, it is also possible to perform I/O to the console by explicitly opening 
a file whose name is "CON". When this occurs, another window is created and displayed. This window is 
different from the one created for standard input and standard output. In fact, every time you open the 
console device a different window is created. This provides a simple multi-windowing system for multiple 
streams of data to and from the console device. 
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16.2 The Sample Non-GUI Application 

To demonstrate the creation of 16-bit Windows 3.x applications, we introduce a simple sample program. 

For our example, we are going to use the famous "hello" program. 

♦include <stdio.h> 

void main() 

{ 

printf( "Hello world\n" ) ; 

} 

The C++ version of this program follows: 

♦include <iostream.h> 

void main() 

{ 

cout << "Hello world" << endl; 

} 

The goal of this program is to display the message "Hello world" on the screen. The C version uses the C 
library printf routine to accomplish this task. The C++ version uses the "iostteam" library to accomplish 
this task. We will take you through the steps necessary to produce this result. 


16.3 Building and Running the Non-GUI Application 

Very little effort is required to port an existing C/C++ application to Windows 3.x. 

You must compile and link the file hello. c specifying the "bw" option. 

C>wcl -l=windows -bw -bt=windows hello.c 
The typical messages that appear on the screen are shown in the following illustration. 

C>wcl -l=windows -bw -bt=windows hello.c 
Open Watcom C/C++16 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

wcc hello.c -bw -bt=windows 
Open Watcom Cl6 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 6 lines, included 155, 0 warnings, 0 errors 

Code size: 17 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows 16-bit executable 
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If you examine the current directory, you will find that two files have been created. These are 
hello, obj (the result of compiling hello, c) and hello.exe (the result of linking hello, obj 
with the appropriate Open Watcom C/C++ libraries). 

The resultant 16-bit Windows 3.x application HELLO. EXE can now be run under Windows 3.x as a 
Windows GUI application. 

16.4 Debugging the Non-GUI Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "hello" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WCL command, this is fairly straightforward. WCL recognizes the Open Watcom C/C++ 
compiler "debug" options and will create the appropriate debug directives for the Open Watcom Linker. 

For example, to compile and link the "hello" program with debugging information, the following command 
may be issued. 

C>wcl -l=windows -bw -bt=windows -d2 hello.c 
The typical messages that appear on the screen are shown in the following illustration. 


C>wcl -l=windows -bw -bt=windows -d2 hello.c 
Open Watcom C/C++16 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

wcc hello.c -bw -bt=windows -d2 
Open Watcom C16 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 6 lines, included 155, 0 warnings, 0 errors 

Code size: 23 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows 16-bit executable 


The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom C/C++ compiler. WCL will make sure that this debugging information is included in the 
executable file that is produced by the linker. 

The "Code size" value is larger than in the previous example since selection of the "d2" option results in 
fewer code optimizations by default. You can request more optimization by specifying the appropriate 
options. However, you do so at the risk of making it more difficult for yourself to determine the 
relationship between the object code and the original source language code. 
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To request the Open Watcom Debugger to assist in debugging the application, select the Open Watcom 
Debugger icon. It would be too ambitious to describe the debugger in this introductory chapter so we refer 
you to the book entitled Open Watcom Debugger User’s Guide. 

16.5 Default Windowing Library Functions 

A few library functions have been written to enable some simple customization of the default windowing 
system’s behaviour. The following functions are supplied: 

_dwDelete On Close 

int _ dwDeleteOnClose( int handle ) ; 

This function tells the console window that it should close itself when the file is closed. You must 
pass to it the handle associated with the opened console. 

_dwSetAboutDlg 

int _ dwSetAboutDlg( const char *title, const char *text ); 

This function sets the about dialog box of the default windowing system. The "title" points to the 
string that will replace the current title. If title is NULL then the title will not be replaced. The 
"text" points to a string which will be placed in the about box. To get multiple lines, embed a new 
line after each logical line in the string. If "text" is NULL, then the current text in the about box 
will not be replaced. 

_dwSetApp Title 

int _ dwSetAppTitle( const char *title ); 

This function sets the main window’s title. 

_dwSetCon Title 

int _ dwSetConTitle( int handle, const char *title ); 

This function sets the console window’s title which corresponds to the handle passed to it. 
_dwShutDown 

int _ dwShutDown ( void ) ; 

This function shuts down the default windowing I/O system. The application will continue to 
execute but no windows will be available for output. 

_dwYield 


int _dwYield( void ); 

This function yields control back to the operating system, thereby giving other processes a chance 
to run. 

These functions are described more fully in the WATCOM C Library Reference. 
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17 Creating 32-bit Windows 3.x Applications 


This chapter describes how to compile and link 32-bit Windows 3.x applications simply and quickly. In 
this chapter, we look at applications written to exploit the Windows 3.x Application Programming Interface 
(API). 

We will illustrate the steps to creating 32-bit Windows 3.x applications by taking a small sample 
application and showing you how to compile, link, run and debug it. 

Note - It is supposed you are working on the host with Windows 3.x installed. If you are on the host with 
any other operating system you should setup INCLUDE environment variable correctly to compile for 
32-bit Windows 3.x target. 

You can do that by command (DOS, OS/2, NT) 

set INCLUDE=%WATCOM%\h;%WATCOM%\h\win 

or by command (LINUX) 

export INCLUDE=$WATCOM/h:$WATCOM/h/win 

17.1 The Sample GUI Application 

To demonstrate the creation of 32-bit Windows 3.x applications, we introduce a simple sample program. 
The following example is the "hello" program adapted for Windows. 

♦include <windows.h> 

int PASCAL WinMain( HANDLE hlnstance, HANDLE hPrevInst, 

LPSTR lpCmdLine, int nCmdShow ) 

{ 

MessageBox( NULL, "Hello world", 

"Open Watcora C/C++ for Windows", 

MB_ OK | MB_ TASKMODAL ) ; 

return( 0 ) ; 

} 

The goal of this program is to display the message "Hello world" on the screen. The MessageBox 
Windows API function is used to accomplish this task. We will take you through the steps necessary to 
produce this result. 


The Sample GUI Application 129 




Windows 3.x Programming Guide 


17.2 Building and Running the GUI Application 

To compile and link our example program which is stored in the file hello. c, enter the following 
command: 

C>wcl386 -l=win386 -bt=windows hello.c 
The typical messages that appear on the screen are shown in the following illustration. 

C>wcl386 -l=win386 -bt=windows hello.c 
Open Watcom C/C++32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

wcc386 hello.c -bt=windows 
Open Watcom C32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 10 lines, included 6500, 0 warnings, 0 errors 

Code size: 41 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows 32-bit executable 


If you examine the current directory, you will find that two files have been created. These are 
hello, obj (the result of compiling hello, c) and hello. rex (the result of linking hello, obj 
with the appropriate Open Watcom C/C++ libraries). The ".rex" file must now be combined with Open 
Watcom’s 32-bit Windows supervisor WIN3 8 6 . EXT using the Open Watcom Bind utility. WBIND . EXE 
combines your 32-bit application code and data (".rex" file) with the 32-bit Windows supervisor. The 
process involves the following steps: 

1. WBIND copies WIN386.EXT into the current directory. 

2. WBIND . EXE optionally runs the resource compiler on the 32-bit Windows supervisor so that the 
32-bit executable can have access to the applications resources. 

3. WBIND . EXE concatenates WIN38 6 . EXT and the ".rex" file, and creates a ".exe" file with the 
same name as the ".rex" file. 

The following describes the syntax of the WBIND command. 


WBIND file_spec [-d] [-n] [-q] [-s supervisor] [-R rc_options] 


The square brackets [ ] denote items which are optional. 
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WBIND 

file_spec 

■d 


-q 


-s supervisor 


-R rcjjptions 


is the name of the Open Watcom Bind utility, 
is the name of the 32-bit Windows EXE to bind, 
requests that a 32-bit DLL be built. 

indicates that the resource compiler is NOT to be invoked. 

requests that WBIND run in quiet mode (no informational messages are 
displayed). 

specifies the path and name of the Windows supervisor to be bound with the 
application. If not specified, a search of the paths listed in the PATH 
environment variable is performed. If this search is not successful and the 
WATCOM environment variable is defined, the %WATCOM%\BINW directory is 
searched. 

all options after -R are passed to the resource compiler. 


To bind our example program, the following command may be issued: 
C>wbind hello -n 


If the "s" option is specified, it must identify the location of the WIN386 . EXT file or the W386DLL . EXT 
file (if you are building a DLL). 

Example: 

C>wbind hello -n -s c:\watcom\binw\win386.ext 

If the "s" option is not specified, then the WATCOM environment variable must be defined or the "BINW" 
directory must be listed in your PATH environment variable. 

Example: 

C>set watcom=c:\watcom 
or 

Opath c : \watcom\binw; c : \dos; c : \windows 
The resultant 32-bit Windows 3.x application HELLO. EXE can now be run under Windows 3.x. 


17.3 Debugging the GUI Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "hello" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WCL386 command, this is fairly straightforward. WCL386 recognizes the Open Watcom 
C/C++ compiler "debug" options and will create the appropriate debug directives for the Open Watcom 
Linker. 

For example, to compile and link the "hello" program with debugging information, the following command 
may be issued. 
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C>wcl386 -l=win386 -bt=windows -d2 hello.c 

The typical messages that appear on the screen are shown in the following illustration. 

C>wcl386 -l=win386 -bt=windows -d2 hello.c 
Open Watcom C/C++32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

wcc386 hello.c -bt=windows -d2 
Open Watcom C32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 10 lines, included 6500, 0 warnings, 0 errors 

Code size: 66 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows 32-bit executable 


The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom C/C++ compiler. WCL386 will make sure that this debugging information is included in the 
executable file that is produced by the linker. 

The "Code size" value is larger than in the previous example since selection of the "d2" option results in 
fewer code optimizations by default. You can request more optimization by specifying the appropriate 
options. However, you do so at the risk of making it more difficult for yourself to determine the 
relationship between the object code and the original source language code. 

Once again, the ".rex" file must be combined with Open Watcom’s 32-bit Windows supervisor 
WIN38 6 . EXT using the Open Watcom Bind utility. This step is described in the previous section. 

To request the Open Watcom Debugger to assist in debugging the application, select the Open Watcom 
Debugger icon. It would be too ambitious to describe the debugger in this introductory chapter so we refer 
you to the book entitled Open Watcom Debugger User’s Guide. 
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18 Porting Non-GUI Applications to 32-bit 
Windows 3.x 


Generally, an application that is to run in a windowed environment must be written in such a way as to 
exploit the Windows Application Programming Interface (API). To take an existing character-based (i.e., 
non-graphical) application that ran under a system such as DOS and adapt it to run under Windows can 
require some considerable effort. There is a steep learning curve associated with the API function libraries. 

This chapter describes how to create a Windows application quickly and simply from an application that 
does not use the Windows API. The application will make use of Open Watcom’s default windowing 
support. 

Suppose you have a set of C/C++ applications that previously ran under a system like DOS and you now 
wish to run them under Windows 3.x. To achieve this, you can simply recompile your application with the 
appropriate options and link with the appropriate libraries. We provide a default windowing system that 
turns your character-mode application into a simple Windows 3.x Graphical User Interface (GUI) 
application. 

Normally, a Windows 3.x GUI application makes use of user-interface tools such as menus, icons, scroll 
bars, etc. However, an application that was not designed as a windowed application (such as a DOS 
application) can run as a GUI application. This is achieved by our default windowing system. The 
following sections describe the default windowing system. 


18.1 Console Device in a Windowed Environment 


In a C/C++ application that runs under DOS, stdin (C++ tin) and stdout (C+ + cout) are connected to the 
standard input and standard output devices respectively. It is not a recommended practice to read directly 
from the standard input device or write to the standard output device when running in a windowed 
environment. For this reason, a default windowing environment is created for C/C++ applications that read 
from stdin (C++ tin) or write to stdout (C++ cout). When your application is started, a window is created 
in which output to stdout (C++ cout) is displayed and input from stdin (C++ tin) is requested. 

In addition to the standard I/O device, it is also possible to perform I/O to the console by explicitly opening 
a file whose name is "CON". When this occurs, another window is created and displayed. This window is 
different from the one created for standard input and standard output. In fact, every time you open the 
console device a different window is created. This provides a simple multi-windowing system for multiple 
streams of data to and from the console device. 
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18.2 The Sample Non-GUI Application 

To demonstrate the creation of 32-bit Windows 3.x applications, we introduce a simple sample program. 

For our example, we are going to use the famous "hello" program. 

♦include <stdio.h> 

void main() 

{ 

printf( "Hello world\n" ) ; 

} 

The C++ version of this program follows: 

♦include <iostream.h> 

void main() 

{ 

cout << "Hello world" << endl; 

} 

The goal of this program is to display the message "Hello world" on the screen. The C version uses the C 
library printf routine to accomplish this task. The C++ version uses the "iostteam" library to accomplish 
this task. We will take you through the steps necessary to produce this result. 


18.3 Building and Running the Non-GUI Application 

Very little effort is required to port an existing C/C++ application to Windows 3.x. 

You must compile and link the file hello. c specifying the "bw" option. 

C>wcl386 -l=win386 -bw -bt=windows hello.c 
The typical messages that appear on the screen are shown in the following illustration. 

C>wcl386 -l=win386 -bw -bt=windows hello.c 
Open Watcom C/C++32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

wcc386 hello.c -bw -bt=windows 
Open Watcom C32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 6 lines, included 174, 0 warnings, 0 errors 

Code size: 24 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows 32-bit executable 
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If you examine the current directory, you will find that two files have been created. These are 
hello, obj (the result of compiling hello, c) and hello. rex (the result of linking hello, obj 
with the appropriate Open Watcom C/C++ libraries). The ".rex" file must now be combined with Open 
Watcom’s 32-bit Windows supervisor WIN3 8 6 . EXT using the Open Watcom Bind utility. WBIND . EXE 
combines your 32-bit application code and data (".rex" file) with the 32-bit Windows supervisor. The 
process involves the following steps: 

1. WBIND copies WIN386.EXT into the current directory. 

2. WBIND . EXE optionally runs the resource compiler on the 32-bit Windows supervisor so that the 
32-bit executable can have access to the applications resources. 

3. WBIND . EXE concatenates WIN38 6 . EXT and the ".rex" file, and creates a ".exe" file with the 
same name as the ".rex" file. 

The following describes the syntax of the WBIND command. 


WBIND file_spec [-d] [-n] [-q] [-s supervisor] [-R rc_options] 


The square brackets [ ] denote items which are optional. 


WBIND 

file_spec 

■d 


-q 


-s supervisor 


-R rc_options 


is the name of the Open Watcom Bind utility, 
is the name of the 32-bit Windows EXE to bind, 
requests that a 32-bit DLL be built. 

indicates that the resource compiler is NOT to be invoked. 

requests that WBIND run in quiet mode (no informational messages are 
displayed). 

specifies the path and name of the Windows supervisor to be bound with the 
application. If not specified, a search of the paths listed in the PATH 
environment variable is performed. If this search is not successful and the 
WATCOM environment variable is defined, the %WATCOM%\BINW directory is 
searched. 

all options after -R are passed to the resource compiler. 


To bind our example program, the following command may be issued: 
C>wbind hello -n 


If the "s" option is specified, it must identify the location of the WIN386 . EXT file or the W386DLL . EXT 
file (if you are building a DLL). 
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Example: 

C>wbind hello -n -s c:\watcom\binw\win386.ext 

If the "s" option is not specified, then the WATCOM environment variable must be defined or the "BINW" 
directory must be listed in your PATH environment variable. 


Example: 

C>set watcom=c:\watcom 
or 

Opath c : \watcom\binw; c : \dos; c : \windows 

The resultant 32-bit Windows 3.x application HELLO. EXE can now be run under Windows 3.x as a 
Windows GUI application. 


18.4 Debugging the Non-GUI Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "hello" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WCL386 command, this is fairly straightforward. WCL386 recognizes the Open Watcom 
C/C++ compiler "debug" options and will create the appropriate debug directives for the Open Watcom 
Linker. 

For example, to compile and link the "hello" program with debugging information, the following command 
may be issued. 

C>wcl386 -l=win386 -bw -bt=windows -d2 hello.c 
The typical messages that appear on the screen are shown in the following illustration. 

C>wcl386 -l=win386 -bw -bt=windows -d2 hello.c 
Open Watcom C/C++32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

wcc386 hello.c -bw -bt=windows -d2 
Open Watcom C32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 6 lines, included 174, 0 warnings, 0 errors 

Code size: 45 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 

Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows 32-bit executable 


The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom C/C++ compiler. WCL386 will make sure that this debugging information is included in the 
executable file that is produced by the linker. 
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The "Code size" value is larger than in the previous example since selection of the "d2" option results in 
fewer code optimizations by default. You can request more optimization by specifying the appropriate 
options. However, you do so at the risk of making it more difficult for yourself to determine the 
relationship between the object code and the original source language code. 

Once again, the ".rex" file must be combined with Open Watcom’s 32-bit Windows supervisor 
WIN38 6 . EXT using the Open Watcom Bind utility. This step is described in the previous section. 

To request the Open Watcom Debugger to assist in debugging the application, select the Open Watcom 
Debugger icon. It would be too ambitious to describe the debugger in this introductory chapter so we refer 
you to the book entitled Open Watcom Debugger User’s Guide. 

18.5 Default Windowing Library Functions 

A few library functions have been written to enable some simple customization of the default windowing 
system’s behaviour. The following functions are supplied: 

_dwDeleteOnClose 

int _ dwDeleteOnClose( int handle ) ; 

This function tells the console window that it should close itself when the file is closed. You must 
pass to it the handle associated with the opened console. 

_dwSetAboutDlg 

int _ dwSetAboutDlg( const char *title, const char *text ); 

This function sets the about dialog box of the default windowing system. The "title" points to the 
string that will replace the current title. If title is NULL then the title will not be replaced. The 
"text" points to a string which will be placed in the about box. To get multiple lines, embed a new 
line after each logical line in the string. If "text" is NULL, then the current text in the about box 
will not be replaced. 

_dwSetAppTitle 

int _ dwSetAppTitle( const char *title ); 

This function sets the main window’s title. 

_dwSetCon Title 

int _ dwSetConTitle( int handle, const char *title ); 

This function sets the console window’s title which corresponds to the handle passed to it. 
_dwShutDown 

int _ dwShutDown ( void ) ; 

This function shuts down the default windowing I/O system. The application will continue to 
execute but no windows will be available for output. 
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dwYield 


int _ dwYield ( void ); 

This function yields control back to the operating system, thereby giving other processes a chance 
to run. 

These functions are described more fully in the WATCOM C Library Reference. 
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19 The Open Watcom 32-bit Windows 3.x Extender 


Open Watcom C/C++ contains the necessary tools and libraries to create 32-bit applications for Windows 
3.x. Using Open Watcom C/C++ gives the programmer the benefits of a 32-bit flat memory model and 
access to the full Windows API (along with the usual C/C++ library functions). 

The general model of the environment is as follows: The 32-bit flat memory model program is linked 
against a special 32-bit Windows library. This library contains the necessary information to invoke special 
16-bit functions, which lie in the supervisor (WIN38 6 . EXT) . The 32-bit program is then bound (using 
WBIND . EXE ) with the supervisor to create a Windows executable. At the same time as the 32-bit 
program is being bound, the resource compiler is run on the supervisor, and all the resources for the 
application are placed there. When the application is started, the supervisor obtains the 32-bit memory, 
relocates the 32-bit application into the memory, and invokes the 32-bit application. 

All Windows functions are invoked from the supervisor, and all callback routines lie within the supervisor. 
The local heap resides within the supervisor as well. 

If you are starting from a 16-bit Windows application, most of the code will not change when you port it to 
the 32-bit Windows environment. However, because of the nature of the Windows API and its implicit 
dependencies on a 16-bit environment, some source changes are necessary. These source changes are 
minimal, and are backwards compatible with the 16-bit environment. 


19.1 Pointers 


Throughout this document, there will be references to both near and far , and 16-bit and 32-bit pointers. 
Since this can rapidly become confusing, some initial explanations will be given here. 

A far pointer is a pointer that is composed of both a selector and an offset. A selector determines a specific 
region of memory, and the offset is relative to the start of this region. A near pointer is a pointer that has 
an offset only, the selector is automatically assumed by the CPU. 

The problem with far pointers is the selector overhead. Using a far pointer is much more expensive than 
using a near pointer. This is the advantage of the 32-bit flat memory model - all pointers within the 
program are near, and yet you can address up to 4 gigabytes of memory. 

A 16-bit near pointer occupies 2 bytes of memory (i.e., the offset is 16 bits long). This pointer can 
reference up to 64K of data. 

A 16-bit far pointer occupies 4 bytes of memory. There is a 16-bit selector and a 16-bit offset. This 
pointer can reference up to 64K of data. 

A 32-bit near pointer occupies 4 bytes of memory (i.e., the offset is 32 bits long). This pointer can 
reference up to 4 gigabytes of data. 

A 32-bit far pointer occupies 6 bytes of memory. There is a 16-bit selector and a 32-bit offset. This 
pointer can reference up to 4 gigabytes of data. 


Pointers 139 




Windows 3.x Programming Guide 


Windows, in general, uses 16-bit far pointers to pass information around. These 16-bit far pointers can also 
be used by a 32-bit Windows application. Using a special macro, MK_FP32 , the offset of the 16-bit far 
pointer is extended from 16 bits to 32 bits, and the pointer becomes a 32-bit far pointer. The 32-bit far 
pointer is then used by the application to access the data (note that offsets still must be less than 64K, since 
the selector is still for a 64K data area). 

19.2 Implementation Overview 

This section provides an overview of the issues that require consideration when creating a 32-bit Windows 
application for a 16-bit Windows environment. 

First, all modules have to be recompiled for the 32-bit flat memory model with a compiler capable of 
generating 32-bit instructions. Many Windows API functions take int as a parameter. This int is from the 
16-bit world, and is 2 bytes long. In the 32-bit world, this int becomes 4 bytes long. Since Windows is 
only expecting two bytes of data, all occurrences of int have to be changed to short in WINDOWS . H. 

Pointers to data passed to Windows are all far pointers. We will be passing pointers to data in our 32-bit 
flat address space, and these pointers are near pointers. By simply getting rid of all far keywords in 
WINDOWS . H, all pointers will now be passed as 32-bit near pointers. As well, notice that these 32-bit near 
pointers are the same size as as their 16-bit far pointer counterparts (4 bytes). This is good, since all data 
structures containing pointers will remain the same size. 

Windows cannot be called from 32-bit code on a 32-bit stack. This means that in order to call the API 
functions, it is necessary to write a set of cover functions that will accept the parameters, switch into a 
16-bit environment, and then call Windows. There is another issue, though. Windows only understands 
16-bit pointers, so before calling Windows, all pointers being passed to Windows must be converted to 
16-bit far pointers. 

It turns out that Windows can also call back to your application. Windows can only call 16-bit code, 
though, so there is a need for a bridge from the 16-bit side to the 32-bit side. It is necessary to allocate 
16-bit call back routines that can be passed to Windows. These call back routines will then switch into the 
32-bit environment and call whatever 32-bit function is required. The 32-bit call back has to be declared as 
a far function, since it is necessary to issue a far call to enter it from the 16-bit side. If it is a far function, 
then the compiler will generate the appropriate code for it to return from the far call. 

Once Windows calls you back, it can hand you 16-bit far pointers in a long (4 byte) parameter. This 
pointer can only be used in the 32-bit environment if it is a 32-bit far pointer, not a 16-bit far pointer. The 
conversion is simple: the 16-bit offset is extended to a 32-bit offset (the high word is zeroed out). Any far 
pointer that Windows hands to you must be converted in this way. 

Sometimes, a Windows application wants to call a procedure in a DLL. The procedure address is a 16-bit 
far pointer. It is not possible to issue an indirect call to this address from the 32-bit environment, so some 
sort of interface is needed. This interface would switch into the 16-bit environment, and then call the 16-bit 
function. 

These issues, along with other minor items, are handled by Open Watcom C/C++, and are discussed in 
more technical detail in later sections. 
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19.3 System Structure 
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Figure 6. 32-bit Application Structure 

19.4 System Overview 

• WIN38 6 . EXT is the key component of a 32-bit Windows application. It is a 16-bit Windows 
application which contains: 

• All application resources. 

• A 16-bit local heap. 

• A 16-bit stack. 

• W38 6DLL. EXT is similar to WIN38 6 . EXT, only it provides a DLL interface. 

WIN386 . EXT is bound to your 32-bit application to create a 32-bit application that will run under 
Windows 3.x. WIN3 8 6 . EXT provides the following functionality: 
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• supervisor to bring the 32-bit application into memory and start it running. 

• "glue" functions to connect to Windows for both API and DOS functionality. This interface is 
designed to transparently set up the calling functions’ pointers and parameters to their 16-bit 
counterparts. 

• "glue-back" functions to allow Windows to call back 32-bit routines. 

• special code to allow debugging of 32-bit applications. 

• WINDOWS . H has been specially modified for use in the 32-bit Windows environment. As well, it 
contains all special definitions for 32-bit applications. 

• WIN38 6 . LIB contains all the necessary library functions to connect to the 32-bit supervisor 
WIN38 6 . EXT . All Windows API calls and Open Watcom C/C++ library DOS calls are found here. 

• The standard C/C++ library functions, specially modified to run in the 32-bit environment, are 
located in the \WATCOM\LIB386\WIN directory. 

• WBIND . EXE merges your 32-bit executable and the appropriate Supervisor into a single executable. 


19.5 Steps to Obtaining a 32-bit Application 

The following is an overview of the procedure for creating a 32-bit Windows Application: 

1. If you are starting with a 16-bit Windows application, you must adapt your source code to the 
32-bit environment. 

2. You must compile the application using a 32-bit compiler. 

3. You must link the application with the 32-bit libraries. 

4. You must bind the 32-bit application with the 32-bit supervisor. 

5. You can then run and/or debug the application. 
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This chapter includes the following topics: 

• WINDOWS. H 

• Environment Notes 

• Floating-point Emulation 

• Multiple Instances 

• Pointer Handling 

• When To Convert Incoming Pointers 

• When To Convert Outgoing Pointers 

• SendMessage and SendDlgltemMessage 

• GlobalAlloc and LocalAlloc 

• Callback Function Pointers 

• Window Sub-classing 

• Calling 16-bit DLLs 

• Making DLL Calls Transparent 

• Far Pointer Manipulation 

• _16 Functions 


20.1 WINDOWS.H 


When developing programs, make sure WINDOWS . H is included as the first include file in all source files. 
This header file contains only the following lines: 

#ifdef _ WINDOWS. 16_ 

♦include <winl6.h> 

♦ else 

♦ include <_win386.h> 

♦endif 

The file WIN16 . H is the regular 16-bit Windows header file, and is only conditionally included for 16-bit 
Windows applications. The file _ WIN386 . H contains all the prototypes and macros for the 32-bit 
environment, as well as including and modifying WIN16 . H . These modifications are changing int to 
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short, and changing the far keyword to nothing. These changes (that ONLY apply to things defined in 
WIN16 . H) cause all integers to be 16-bit integers, and all LP... pointer types to be near pointers. 

Other include files for Windows must be specifically requested by defining macros before including 
WINDOWS . H . This is required so that the same changes made to the primary Windows header file will 
apply to routines declared in the other header files. 


Macro name 

File included 

Mefine IN CL UDE_COMMDLG_H 

COMMDLG.H 

Mefine INCLUDE_CUSTCNTL_H 

CUSTCNTL.H 

Mefine IN CL UDE_DDE_H 

DDE . H 

Mefine INCLUDE_DDEML_H 

DDEML.H 

Mefine INCLUDE_DRIVINIT_H 

DRIVINIT.H 

Mefine INCLUDE_LZEXPAND_H 

LZEXPAND.H 

Mefine INCLUDE_MMSYSTEM_H 

MMSYSTEM.H 

Mefine IN CL UDE_OLE_H 

OLE.H 

Mefine INCLUDE_PENWIN_H 

PENWIN.H 

Mefine IN CL UDE_PENWOEM_H 

PENWOEM.H 

Mefine IN CL UDE_PRINT_H 

PRINT.H 

Mefine IN CL UDE_SHELLAPI_H 

SHELLAPI,H 

Mefine INCLUDE_STRESS_H 

STRESS,H 

Mefine INCLUDE_TOOLHELP_H 

TOOLHELP,H 

Mefine IN CL UDE_VER_H 

VER.H 


20.2 Environment Notes 


• The Windows functions Catch and Throw save only the 16-bit state. Instead of these functions, use 
the setjmp and longjmp functions. 

• The 32-bit Windows Supervisor uses the first 256 bytes of the 32-bit application’s stack to save state 
information. If this is corrupted, your application will abnormally terminate. 

• The 32-bit Windows Supervisor provides resources for up to 512 callback routines. Note that this 
restriction is only on the maximum number of active callbacks. 

20.3 Floating-point Emulation 

The file WEMU387.386 is included to support floating-point emulation for 32-bit applications running 
under Windows. This file is installed in the [386Enh] section of your SYSTEM. INI file. By using the 
floating-point emulator, your application can be compiled with the "fpi87" option to use inline 
floating-point instructions, and it will run on a machine without a numeric coprocessor. 

Only one of WEMU387.386 and WDEBUG .386 may be installed in your [ 3 8 6Enh ] section. 

WEMU 387.386 may be distributed with your application. 
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20.4 Multiple Instances 

Since the 32-bit application resides in a flat memory space, it is NOT possible to share code with other 
instances. This means that you must register new window classes with callbacks into the new instance’s 
code space. A simple way of accomplishing this is as follows: 

int PASCAL WinMain( HANDLE hlnstance, 

HANDLE hPrevInstance; 

LPSTR lpCmdLine, 
int nCmdShow ); 

{ 

WNDCLASS wc; 

HWND hWnd 

char class[32]; 

wc.style = NULL; 

wc.lpfnWndProc = (LPVOID) MainWndProc; 
wc.cbClsExtra = 0; 
wc.cbWndExtra = 0; 
wc.hlnstance = hlnstance; 

wc.hlcon = Loadlcon( NULL, IDI_ APPLICATION ); 

wc.hCursor = LoadCursor( NULL, IDC_ ARROW ); 

wc.hbrBackground = GetStockObject( WHITE_ BRUSH ); 

wc.IpszMenuName = "Menu"; 

sprintf( class,"Class%d",hlnstance ); 

wc.IpszClassName = class; 

RegisterClass ( &wc ); 
hWnd = CreateWindow( 
class, 

"Application", 

WS_ OVERLAPPEDWINDOW, 

CW_ USEDEFAULT, 

CW_ USEDEFAULT, 

CW_ USEDEFAULT, 

CW_ USEDEFAULT, 

NULL, 

NULL, 

hlnstance, 

NULL 

) ; 

The variable class contains a unique name based on the instance of the application. 


20.5 Pointer Handling 

Windows 3.x is a 16-bit operating system. Function pointers that Windows deals with are 16-bit far 
pointers, and any data you communicate to Windows with are 16-bit far pointers. 16-bit far pointers 
occupy 4 bytes of data, and are capable of addressing up to 64K. For data objects larger than 64K, huge 
pointers are used (a sequence of far pointers that map out consecutive 64K segments for the data object). 
16-bit far pointers are expensive to use due to the overhead of selector loads (each time you use the pointer, 
a segment register must have a value put in it). 16-bit huge pointers are even more expensive: not only is 
there the overhead of selector loads, but a run-time call is necessary to perform any pointer arithmetic. 
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In a 32-bit flat memory model, such as that of the Open Watcom C/C++ for Windows environment, all 
pointers are 32-bit near pointers (occupying 4 bytes of data as well ). However, these pointers may access 
objects of up to 4 gigabytes in size, and there is no selector load overhead. 

All Windows defined pointer types (e.g., LPSTR) are by default near pointers, not far pointers. To obtain a 
far pointer, the far keyword must be explicitly coded, i.e., char far *foo, rather than LPSTR foo. 

A 32-bit near pointer is the same size as a 16-bit far pointer, so that all Windows pointers are the same size 
in the 32-bit flat memory model as they are in the original 16-bit segmented model. 

For a 32-bit environment to communicate with Windows 3.x, there are some considerations. All pointers 
sent to Windows must be converted from 32-bit near pointers to 16-bit far pointers. These conversions are 
handled by the Supervisor. 

It is important to remember that all API functions which accept pointers (with the exception of functions 
that accept function pointers) accept 32-bit near pointers in this 32-bit model. If you attempt to pass a 
32-bit far pointer, the conversion will not take place correctly. 

16-bit far pointers to data may be passed into the API functions, and the Supervisor will not do any 
conversion. 

Incoming pointers must be converted from 16-bit far pointers to 32-bit far pointers. This conversion is a 
trivial one: the offset portion of the 16-bit far pointer is extended to 32-bits. Pointers from Windows are 
by their nature far (that is, the data is pointed to by its own selector), and must be used as far in the 32-bit 
environment. Of course, conversions are only required if you actually need to reference the pointer. 

Function pointers (i.e., pointers to callback routines) used by Windows are not converted from 32-bit to 
16-bit. Rather, a 16-bit thunking layer that transfers control from the 16-bit environment to the 32-bit 
environment must be used. This thunking layer is provided by the Supervisor. 

20.5.1 When To Convert Incoming Pointers 

Whenever you wish to use a pointer passed to you by Windows, you must convert it to a 32-bit far pointer. 
If you are passed a 16-bit far pointer, the macro MK_FP32 can be used to convert it to a 32-bit far pointer. 
If you are passed a 16-bit near pointer (e.g., from LocalLock ), then the macro MK_LOCAL32 can be used 
to convert it to a 32-bit far pointer. 

Some places where pointer conversion may be required are: 

• LocalLock 

• GlobalLock 

• the IParam in a window callback routine (if it is a pointer) 

20.5.2 When To Convert Outgoing Pointers 

Typically, there is no need to do any kind of conversions on your pointers when passing them to Windows. 
The Supervisor handles all 32-bit to 16-bit translations for you, in the case of the regular Windows API 
functions. However, if you are passing a 32-bit pointer to some other 16-bit application in the Windows 
environment, then pointer conversions must by done. There are two types of "outgoing" pointers: data 
pointers and function pointers. 

Function pointers (to callback routines) must have a thunking layer provided, using the GetProcl6 function 
(this is explained in detail in a later section). 
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Data pointers can be translated from 32-bit to 16-bit using the AllocAlias 16 and AllocHugeAlias 16 
functions. These functions create 16-bit far pointers that have the same linear address as the 32-bit near 
pointer that was converted. 

It is important to remember that when passing a pointer to a data structure in this fashion, any pointers in 
the data structure must also be converted. 

The Supervisor will convert any pointers that it knows about; but there are some complications created by 
the fact that Windows allows you to pass pointers in functions that are prototyped to take a long integer. 

The Windows API functions SendMessage and SendDlgltemMessage rely on other fields determining the 
nature of the long data item that they accept; this is discussed in detail in the next section. 


20.5.2.1 SendMessage and SendDlgltemMessage 

SendMessage and SendDlgltemMessage have special cover functions that determine when the long integer 
is really a pointer and needs to be converted. These cover functions are used automatically, unless the 
macro NOCOVERSENDS is defined before including WINDOWS . H as in the following example. 

♦define NOCOVERSENDS 
♦include <windows.h> 

SendMessage and SendDlgltemMessage will do pointer conversions automatically using AllocAlias 16 and 
FreeAliasl6 (unless NOCOVERSENDS is defined) for the following message types: 

• combo boxes (CB_ messages) 

• edit controls (EM_ messages) 

• list boxes (LB_ messages) 

• certain windows messages (WM_ messages); 


The messages that are intercepted by the cover functions for SendMessage and SendDlgltemMessage are: 


CB_ ADDSTRING CB_ DIR CB_ FINDSTRING 

CB_ FINDSTRINGEXACT CB_ GETLBTEXT CB_ INSERTSTRING 

CB_ SELECTSTRING 


EM_ GETLINE 
EM_ SETRECT 


EM_ GETRECT EM_ REPLACESEL 

EM_ SETRECTNP EM_ SETTABSTOPS 


LB_ ADDSTRING LB_ DIR 

LB_ FINDSTRINGEXACT LB_ GETITEMRECT 
LB_ GETTEXT LB_ INSERTSTRING 

LB_ SETTABSTOPS 


LB_ FINDSTRING 
LB_ GETSELITEMS 
LB_ SELECTSTRING 


WM_ MDI CREATE 


WM_ NCCALCSIZE 


Note that for SendMessage and SendDlgltemMessage , some of the messages may NOT require pointer 
conversion: 

• CB_ADDSTRING, CB_FINDSTRING, CB_FINDSTRINGEXACT, CB_INSERTSTRING will not 
need a conversion if the combo box was created as owner-draw style without CBS_HASSTRINGS 
style. 

• LB_ADDSTRING, LB_FINDSTRING, LB_FINDSTRINGEXACT, LB JNSERTSTRING will not 
need a conversion if the list box was created as owner-draw style without LBS_HASSTRINGS style. 
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The macro NOCOVERSENDS should be defined in modules where messages like these are being sent. 
With these messages, the IParam data item does not contain a pointer, and the automatic pointer conversion 
would be incorrect. By doing 

#define NOCOVERSENDS 
♦include "windows.h" 

modules that send messages like the above will not have the pointer conversion performed. 

20.5.3 GlobalAlloc and LocalAlloc 

The functions GlobalAlloc and LocalAlloc are the typical way of allocating memory in the 16-bit Windows 
environment. In the 32-bit environment, there is no need to use these functions. The only time 
GlobalAlloc is needed is when allocating shared memory, i.e., GMEM_DDESHARE. 

The C runtime functions malloc and free manipulate your 32-bit near heap for you. By using these 
functions to allocate memory, you may create data objects as large as the enhanced mode Windows 
memory manager will permit. 

20.5.4 Callback Function Pointers 

To access a callback function, an instance of it must be created using MakeProcInstance. This creates a 
"thunk" (a special piece of code) that automatically puts the application’s data segment into the AX 
register, and then calls the specified callback function. 

In Windows 3.x, it is not possible to do a MakeProcInstance directly on a 32-bit callback routine, since 
Windows 3.x does not understand 32-bit applications. Therefore, it is necessary to use a 16-bit callback 
routine that passes control to the 32-bit callback routine. This 16-bit callback routine is automatically 
created by the Supervisor when using any of the standard Windows API functions that accept a callback 
routine. 

The 16-bit callback routine for a 32-bit application is a special layer that transfers the parameters from a 
16-bit stack to the 32-bit stack, and then passes control to 32-bit code. These 16-bit callback routines are 
found in the Supervisor. The function GetProcl6 provides pointers to these 16-bit callback routines. 

However, it is not often necessary to use the GetProcl6 function to obtain a 16-bit/32-bit callback interface 
function. 

In the general case, one would have to write code as follows: 
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♦define NOAUTOPROCS 
♦include <windows.h> 

CALLBACKPTR pCb; 

FARPROC fpProc; 

pCb = GetProcl6( A_ Function, GETPROC_ callbacktype ); 
fpProc = MakeProcInstance( pCb, hlnstance ); 

/* do stuff */ 

Do_ it ( ..., fpProc, ... ) ; 

/* do more stuff */ 

FreeProcInstance( fpProc ); 

ReleaseProcl6( pCb ); 

It is not necessary to use this general code in the case of the regular Windows API functions. The 
following functions will automatically allocate the correct 16-bit/32-bit callback interface functions: 

• ChooseColor 

• ChooseFont 

• Correct Writing 

• CreateDialog 

• CreateDialoglndirect 

• CreateDialoglndirectParam 

• CreateDialogParam 

• Ddelnitialize 

• DialogBox 

• DialogBoxIndirect 

• DialogBoxIndirectParam 

• DialogBoxParam 

• DictionarySearch 

• EnumChildWindows 

• EnumFontFamilies 

• EnumFonts 

• EnumMetaFile 

• EnumObjects 

• EnumProps 

• EnumSymbols 

• EnumTaskWindows 

• EnumWindows 

• Escape (SETABORTPROC option) 

• FindText 

• GetOpenFileName 

• GetSaveFileName 

• GlobalNotify 

• GrayString 

• LineDDA 

• mciSetYieldProc 

• mmioInstalllOProc 

• NotifyRegister 

• PrintDlg 
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• ProcessWriting 

• Recognize 

• RecognizeData 

• RegisterClass 

• ReplaceText 

• SetClassLong (GCL_WNDPROC option) 

• SetPenHook 

• SetResourceHandler 

• SetTimer 

• SetWindowLong (GWL_WNDPROC option) 

• SetWindowsHook 

• SetWindowsHookEx 

• Trainlnk 

As well, the following functions are covered to provide support for automatic creation of 16-bit callback 
routines: 

• FreeProcInstance 

• MakeProcInstance 

• UnhookWindowsHook 

If you need to get a callback that is not used by one of the above functions, then you must code the general 
case. Typically, this is required when a DLL needs a callback routine. In modules where this is necessary, 
you define the macro NOAUTOPROCS before you include WINDOWS . H as in the following example. 

♦define NOAUTOPROCS 
♦include <windows.h> 

Be careful of the following when using NOAUTOPROCS. 

1. The call to MakeProcInstance and FreeProcInstance for the callback function occurs in a 
module with NOAUTOPROCS defined. 

2. No Windows API functions (listed above) are used in the module with NOAUTOPROCS 
defined. If they are, you must code the general case to use them. 

Note that NOAUTOPROCS is in effect on a module-to-module basis only. 

You can avoid using NOAUTOPROCS on a call-by-call basis, if you do the following: 

♦undef <function> 

<function> 

Note: re-defining is only needed if you want to 

use a covered version of the function later on. 

♦define <function> _ Cover_ <function> 

For example: 

{ 

♦undef SetWindowsHook 
♦undef MakeProcInstance 

FARPROC fp,oldfp; 

CALLBACKPTR cbp; 


150 Pointer Handling 




Windows 3.x 32-bit Programming Overview 


cbp = GetProcl6 ( CallbackHook, GETPROC_ CALLBACK ); 
fp = MakeProcInstance( cbp, hlnstance ); 
oldfp = SetWindowsHook( WH_ CALLWNDPROC, fp ); 


} 

This allows you to add general case code in the same module, without having to break the module into two 
parts. 

RegisterClass automatically does a GetProcl6 for the callback function, unless the macro NOCOVERRC is 
specified before including WINDOWS . H as in the following example. 

♦define NOCOVERRC 
♦include <windows.h> 


20.5.4.1 Window Sub-classing 


Sub-classing a Windows control in the 32-bit environment is straightforward. In fact, the code is identical 
to the code used in the 16-bit environment. A simple example is: 

FARPROC fpOldProc; 


long FAR PASCAL SubClassProc( HWND hWnd, 

unsigned message, 
WORD wParam, 

LONG IParam ) 


{ 


} 


/* 

* code for sub-classing here 
*/ 

return ( CallWindowProc( fpOldProc, hWnd, message, 

wParam, IParam ) ); 


void SubClassDemo( void ) 


HWND hControl; 

F ARP ROC fp; 

extern HANDLE Programlnstance; 

/* assume hControl gets created in here */ 

fpOldProc = (FARPROC) GetWindowLong( hControl, GWL_ WNDPROC ); 
fp = MakeProcInstance( SubClassProc, Programlnstance ); 
SetWindowLong ( hControl, GWL_ WNDPROC, (LONG) fp ); 

/* set it back */ 

SetWindowLong( hControl, GWL_ WNDPROC, (LONG) fpOldProc ); 
FreeProcInstance( fp ); 


Note that SetWindowLong is covered to recognize GWL_WNDPROC and automatically creates a 16-bit 
callback for the 32-bit callback. When replacing the callback routine with the original 16-bit routine, the 
covered version of SetWindowLong recognizes that the function is not a 32-bit callback, and so passes the 
pointer right through to Windows unchanged. 


Pointer Handling 151 




Windows 3.x Programming Guide 


20.6 Calling 16-bit DLLs 

A 16-bit function in a DLL can be called using the _Calll6 function. The first argument to _Calll6 is the 
address of the 16-bit function. This address is usually obtained by calling GetProcAddress with the name 
of the desired function. The second argument to _Calll6 is a string identifying the types of the parameters 
to be passed to the 16-bit function. 

Character Parameter Type 

c call a ’cdecT function as opposed to a ’pascal’ function (if specified, it must be listed first) 

b unsigned BYTE 

w 16-bit WORD 

d 32-bit DWORD 

/ double precision floating-point 

p 32-bit flat pointer (converted to 16:16 far pointer) 

The 16-bit function must use either the PASCAL or CDECL calling convention. PASCAL calling 
convention is the default. If the function uses the CDECL calling convention, then you must specify the 
letter "c" as the first character of the argument type string. 

Pointer types will automatically be converted from 32-bit near pointers to 16-bit far pointers before the 
function is invoked. Note that this pointer is only valid over the period of the call; after control returns to 
the 32-bit application, the 16-bit pointer created by the Supervisor is no longer valid. 

The return value from _Calll6 is a DWORD. 


♦include <windows.h> 

HANDLE hDrv; 

FARPROC lpfn; 
int cb; 

if( (hDrv = LoadLibrary ("foo.dll")) < 32 ) 
return FALSE; 

if( !(lpfn = GetProcAddress (hDrv, "ExtDeviceMode")) ) 
return FALSE; 

/* 

* now, invoke the function 
*/ 

cb = (WORD) _ Calll6 ( 


lpfn. 

// 

address of function 

"wwdppddw", 

// 

parameter type info 

hwnd. 

// 

parameters ... 

hDrv, 



NULL, 




"POSTSCRIPT PRINTER", 
"LPT1", 

NULL, 

NULL, 

0 

); 
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20.6.1 Making DLL Calls Transparent 

This section gives an example of how to make your source code look as if you are calling the 16-bit DLL 
directly. 

Assume there are 3 functions that you want to call in the 16-bit DLL, with prototypes as follows: 

HWND FAR PASCAL Initialize! WORD start_ code ); 

BOOL FAR PASCAL DoStuf f ( HWND win_ hid, HDC win_ dc ) ; 
void FAR PASCAL Finish! void ); 

A fragment from the header file that you would include in your 32-bit application would be as follows: 

extern FARPROC InitializeAddr; 
extern FARPROC DoStuffAddr; 
extern FARPROC FinishAddr; 

♦ define Initialize ( start_ code ) \ 

_Calll6( InitializeAddr, "w", (WORD) start_ code ) 

♦ define DoStuff ( win_ hid, data ) \ 

_Calll6( DoStuffAddr, "wp", (HWND) win_ hid, (LPVOID)data ) 

♦ define Finish! void ) _Calll6( FinishAddr, "" ) 

The header file fragment gives external references for the function addresses for each function, and sets up 
macros do a _Calll6 for each of the functions. 

At start up, you would call the following function: 

/* 

* LoadDLL - get DLL ready for 32-bit use 
*/ 

BOOL LoadDLL( void ) 

{ 

HANDLE dll; 

dll = LoadLibrary ( "chart.dll" ); 
if( dll < 32 ) return! FALSE); 

InitializeAddr = GetProcAddress( dll, "Initialize" ); 
DoStuffAddr = GetProcAddress( dll, "DoStuff" ) ; 

FinishAddr = GetProcAddress( dll, "Finish" ); 
return ( TRUE ); 

} 

This function loads the 16-bit DLL and gets the addresses for all of the entry points in the DLL. By 
including the header file with all the macros in it, you can code calls to the DLL functions as if you were 
calling the functions directly. For example: 

♦include <windows.h> 

♦include "fragment.h" 
char *data = "the data"; 

void TestDLL( void ) 

{ 

HWND res; 
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if( !LoadDLL () ) { 

MessageBox ( NULL, "Could not load DLL", 
"Error", MB_ OK ); 

return; 

} 

res = Initialize( 1 ); 

DoStuff( res, data ); 

Finish(); 

} 


20.7 Far Pointer Manipulation 

The following C library functions are available for manipulating far data. These are useful when using 
pointers obtained by MK_FP32 and MK_LOCAL32. 

Memory manipulation: 

• _fmemccpy 

• _fmemchr 

• _fmemcmp 

• _fmemcpy 

• _fmemicmp 

• _fmemmove 

• _fmemset 

String manipulation: 

• _fstrcat 

• _fstrchr 

• _fstrcmp 

• _fstrcpy 

• _fstrcspn 

• _fstricmp 

• _fstrlen 

• _fstrlwr 

• _fstrncat 

• _fstrncmp 

• _fstrncpy 

• _fstrnicmp 

• _fstrnset 

• _fstrpbrk 

• _fstrrchr 

• _fstrrev 

• _fstrset 

• _fstrspn 

• _fstrtok 

• _fstrupr 
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20.8 16 Functions 


Every Windows API function that accepts a pointer has a corresponding _16 function. The _16 version of 
the function will not convert any of the pointers that it accepts; it will assume that all pointers are 16-bit far 
pointers already. This applies to both data and function pointers. 


Some sample code demonstrating the use for this is: 


void ReadEditBuffer( char *fname, HWND hwndEdit ) 

{ 


int 

HANDLE 
char far 
LPSTR 
WORD 
/* 


f ile; 
hText; 

*flpData; 
lpData; 
f Helen; 


* no error checking is performed; we just 

* assume everything works for this example. 
*/ 


file = _ lopen( fname, 0); 
filelen = _llseek( file, 0L, 2 ); 


hText = (HANDLE) SendMessage( hwndEdit, 

0, 0L ); 

LocalReAlloc( hText, filelen+1, LHND ); 
f lpData = MK_ LOCAL32 ( LocalLock ( hText 
lpData = (LPSTR) MK_FP16( flpB ); 
_16_lread( file, lpData, filelen ); 

_ lclose ( file ); 


EM_ GETHANDLE, 

) ); 


} 

This example reads the contents of a file into the buffer of an edit window. Because the edit window’s 
memory is located in the local heap, which is the Supervisor’s heap, the MK_LOCAL32 function is needed 
to access the data. The MK_FP16 macro compresses the 32-bit far pointer into a 16-bit far pointer, which 
can then be used by the _16_lread function. 
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21 Windows 32-Bit Dynamic Link Libraries 

21.1 Introduction to 32-Bit DLLs 


Open Watcom C/C++ allows the creation of 32-bit Dynamic Link Libraries (DLL). In fact, 32-bit DLLs 
are simpler to write than 16-bit DLLs. A 16-bit DLL runs on the caller’s stack, and thus DS != SS. This 
creates difficulties in the small and medium memory models because near pointers to local variables are 
different from near pointers to global variables. The 32-bit DLL runs on its own stack, in the usual flat 
memory space, which eliminates these concerns. 

There is a special version of the supervisor, W386DLL. EXT that performs a similar job to WIN38 6 . EXT . 
However, the 32-bit DLL supervisor is a 16-bit Windows DLL, rather than a 16-bit Windows application. 
On the first use of the 32-bit DLL, the DLL supervisor loads the 32-bit DLL and invokes the 32-bit 
initialization routine (the DLL’s WinMain routine). The initialization routine declares all entry points (via 
Def ineDLLEntry) and performs any other necessary initialization. An index number in the range 1 to 
128 is used to identify all external 32-bit DLL routines. Def ineDLLEntry is used to assign an index 
number to each routine, as well as to identify the arguments. 

The DLL supervisor contains a general entry point for Windows applications to call into called 
Win386LibEntry . It also contains 128 specific entry points called DLL1 to DLL128 which correspond 
to the entry points established via Def ineDLLEntry (the first argument to Def ineDLLEntry is an 
index number in the range 1 to 128). These entry points are FAR PASCAL functions. All applications call 
into the 32-bit DLL via these entry points. They build the necessary stack frame and switch to the 32-bit 
DLL’s data space. 

If you call via Win386LibEntry then you pass the DLL entry point number or index (1 to 128) as the 
last argument. Win3 8 6LibEntry uses this index number to call the appropriate 32-bit DLL routine. 

From a pseudo-code point of view, the 16-bit supervisor might look like the following: 
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DLLl:: set index=l 

invoke 32bitDLLindirect 

DLL2:: set index=2 

invoke 32bitDLLindirect 


DLL128:: set index=128 

invoke 32bitDLLindirect 

Win386LibEntry:: 

set index from index_ argument 
invoke 32bitDLLindirect 

32bitDLLindirect: 

set up stack frame 

switch to 32-bit data space 

call indirect registration_ list[ index ] 


When you are creating a 32-bit DLL, keep in mind that the entry points you define may be invoked by a 
16-bit application as well as a 32-bit application. It is for this reason that all far pointers passed to a 32-bit 
DLL are 16-bit far pointers. Hence, whenever a pointer is passed as an argument to a 32-bit DLL entry 
point and you wish to access the data it points to, you must convert the pointer appropriately. 


21.2 A Sample 32-bit DLL 

Let us begin our discussion of DLLs by showing the code for a simple DLL. The source code for these 
examples is provided in the \WATCOM\SAMPLES\DLL directory. We describe how to compile and link 
the examples in the section entitled "Creating and Debugging Dynamic Link Libraries" on page 162. The 
code for this DLL can be compiled with the 16-bit compiler to produce a 16-bit DLL and it can can be 
compiled with the 32-bit compiler to produce a 32-bit DLL. The example illustrates the fundamental 
differences between the two types of DLLs. The 32-bit DLL has a WinMain routine and the 16-bit DLL 
has a LibMain routine. 


Example: 

/* 

* DLL.C 
*/ 

♦include <stdio.h> 
♦include <windows.h> 


♦if defined(_ 
♦define DLL 
♦ else 

♦define DLL 
♦endif 


.386 _ )/* if we 

ID "DLL32" 

/* else we 
ID "DLL16" 


are 

are 


doing a 
doing a 


32-bit DLL 
16-bit DLL 


*/ 


*/ 
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long FAR PASCAL _export FooMel(WORD wl, DWORD w2, WORD w3) 

{ 

char buff[128] ; 

sprintf( buff, "FooMel: wl=%hx, w2=%lx, w3=%hx", 
wl, w2, w3 ); 

MessageBox ( NULL, buff, DLL_ ID, MB_ OK ); 
return( wl + w2 ) ; 


long FAR PASCAL _export FooMe2( DWORD wl, WORD w2 ) 

{ 

char buff[128]; 

sprintf( buff, "FooMe2: wl=%lx, w2=%hx", wl, w2 ); 
MessageBox ( NULL, buff, DLL_ ID, MB_ OK ) ; 
return ( wl + 1 ); 


#if defined(_386_)/* if we are doing a 32-bit DLL */ 

long PASCAL WinMain( HANDLE hlnstance, 

HANDLE hPrevInstance, 

LPSTR IpszCmdLine, 
int nCmdShow ) 

{ 

if ( DefineDLLEntry ( 1, (void *) FooMel, DLL_WORD, 

DLL_ DWORD, DLL_ WORD, DLL_ ENDLIST )) { 

return( 0 ); 

} 

if ( DefineDLLEntry( 2, (void *) FooMe2, DLL_ DWORD, 

DLL_ WORD, DLL_ ENDLIST ) ) { 

return( 0 ); 

} 

MessageBox( NULL, "32-bit DLL Started", DLL_ ID, MB_ OK ); 
return( 1 ); 

} 

#else /* else we are doing a 16-bit DLL */ 

BOOL FAR PASCAL LibMain( HANDLE hlnstance, 

WORD wDataSegment, 

WORD wHeapSize, 

LPSTR IpszCmdLine ) 

{ 

#if 0 
/* 

We can't use MessageBox here since static binding is 
used and a message queue has not been created by the 
time DLL16 is loaded. 

*/ 

MessageBox( NULL, "16-bit DLL Started", DLL_ ID, MB_ OK ); 
#endif 

return( TRUE ); 

} 

#endif 

To create a 16-bit DLL from this code, the following steps must be performed. 
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Example: 

C>wcc dll /me /bt=windows /zu /fo=dlll6 
C>wlink system windows_ dll file dlll6 
Owlib -n dill6 +dlll6.dll 


To create a 32-bit DLL from this code, the following steps must be performed. 

Example: 

C>wcc386 dll /bt=windows /fo=dll32 
C>wlink system win386 file dll32 
C>wbind -n -d dll32 

There are two entry points defined, FooMel (index number 1) and FooMe2 (index number 2). FooMel 
accepts three arguments: a WORD, a DWORD, and a WORD. FooMe2 accepts two arguments: a 
DWORD and a WORD. 

WinMain returns zero to notify Windows that the DLL initialization failed, and returns a one if 
initialization succeeds. 

WinMain accepts the same arguments as the WinMain procedure of a regular Windows program, 
however, only two arguments are used, hlnstance is the DLL handle and IpszCmdLine is the 
command line passed to the DLL. 

21.3 Calling Functions in a 32-bit DLL from a 16-bit 
Application 

The following is a 16-bit Windows program that demonstrates how to call the two routines defined in our 
DLL example. 

Example: 

/* 

* EXE16.C 
*/ 

♦include <stdio.h> 

♦include <windows.h> 

♦define Add3 1 

♦define Add2 2 

typedef long (FAR PASCAL *FPROC)(); 

typedef long (FAR PASCAL *FARPR0C1)(WORD, DWORD, WORD, int); 

typedef long (FAR PASCAL *FARPR0C2)(DWORD, WORD, int); 

long FAR PASCAL FooMel( WORD, DWORD, WORD ); 
long FAR PASCAL FooMe2( DWORD, WORD ); 
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int PASCAL WinMain( HANDLE hlnstance, 

HANDLE hPrevInstance, 

LPSTR IpszCmdLine, 
int nCmdShow ) 

{ 

FPROC fp; 

HANDLE hlib; 

long cb; 

char buff[128]; 

MessageBox( NULL, "16-bit EXE Started", "EXE16", MB_ OK ); 

/* Do the 16-bit demo using static binding */ 
cb = FooMel( 0x666, 0x77777111, 0x6969 ); 
sprintf( buff, "RC1 = %lx", cb ); 

MessageBox( NULL, buff, "EXE16", MB_ OK ); 

cb = FooMe2( 0x12345678, 0x8888 ); 
sprintf( buff, "RC2 = %lx", cb ); 

MessageBox( NULL, buff, "EXE16", MB_ OK ); 

/* Do the 32-bit demo */ 

hlib = LoadLibrary( "dll32.dll" ); 

fp = (FPROC) GetProcAddress( hlib, "Win386LibEntry" ); 

cb = (*(FARPROC1)fp)( 0x666, 0x77777111, 0x6969, Add3 ); 
sprintf( buff, "RC1 = %lx", cb ); 

MessageBox( NULL, buff, "EXE16", MB_ OK ); 

cb = (*(FARPROC2)fp)( 0x12345678, 0x8888, Add2 ); 
sprintf( buff, "RC2 = %lx", cb ); 

MessageBox( NULL, buff, "EXE16", MB_ OK ); 

return( 0 ); 

} 

Note that the last argument of a call to the 32-bit DLL routine is the index number of the 32-bit DLL 
routine to use. To create the 16-bit sample Windows executable from this code, the following steps must 
be performed. 

Example: 

C>wcc exel6 /bt=windows 

C>wlink system windows file exel6 library dlll6 


21.4 Writing a 16-bit Cover for the 32-bit DLL 

The following is a suggested way to make a 32-bit DLL behave just like a 16-bit DLL from the point of 
view of the person trying to use the DLL. 

Create a library of cover functions for each of the entry points. Each library entry would call the 32-bit 
DLL using the appropriate index number. 
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For example, assume we have 3 functions in our DLL, Initialize, DoStuf f, and Finish. 
Assume Initialize takes an integer, DoStuf f takes an integer and a pointer, and Finish takes 
nothing. We could build a 16-bit library as follows: 


Example: 

♦include <windows.h> 

typedef long (FAR PASCAL *FPROC)(); 
extern long FAR PASCAL Win386LibEntry(); 
FPROC LibEntry = Win386LibEntry; 

BOOL Initialize( int parm ) 

{ 

return( LibEntry( parm, 1 ) ); 

} 

int DoStuff( int parml, LPVOID parm2 ) 

{ 

return( LibEntry( parml, parm2, 2 ) ); 

} 


void Finish( void ) 

{ 

LibEntry( 3 ); 

} 


21.5 Creating and Debugging Dynamic Link Libraries 

In the following sections, we will take you through the steps of compiling, linking, and debugging both 
16-bit and 32-bit Dynamic Link Libraries (DLLs). 

We will use example programs that are provided in source-code form in the Open Watcom C/C++ package. 
The files described in this chapter are located in the directory \WATCOM\SAMPLES\DLL . The following 
files are provided: 


GEN16.C 

GEN16.LNK 
GEN32. C 

GEN32.LNK 

DLL16.C 

DLL16.LNK 

DLL32.C 

DLL32.LNK 


is the source code for a generic 16-bit Windows application that calls functions 
in a 32-bit Windows DLL. 

is the linker directive file for linking the 16-bit Windows application. 

is the source code for a generic 32-bit Windows application that calls functions 
in both 16-bit and 32-bit Windows DLLs. 

is the linker directive file for linking the 32-bit Windows application. 

is the source code for a simple 16-bit DLL containing one library routine. 

is the linker directive file for linking the 16-bit Windows DLL. 

is the source code for a more complex 32-bit DLL containing three library 
routines. 

is the linker directive file for linking the 32-bit Windows DLL. 
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EXE16.C is the source code for a generic 16-bit Windows application that calls functions 

in both 16-bit and 32-bit Windows DLLs. 

DLL.C is the source code for a DLL containing three library routines. The source code 

for this DLL can be used to create both 16-bit and 32-bit DLLs. 

MAKEFILE is a makefile for compiling and linking the programs described above. 

21.5.1 Building the Applications 

To create the DLLs and test applications, we will use the WATCOM Open Watcom Make utility and the 
supplied makefile. 

Example: 

C>wmake -f makefile 

21.5.2 Installing the Examples under Windows 

Start up Microsoft Windows 3.x if you have not already done so. Add the EXE16 . EXE file to one of your 
Window groups using the Microsoft Program Manager. 

1. Select the "New..." entry from the "File" menu of the Microsoft Windows Program Manager. 

2. Select "Program Item" from the "New Program Object" window and press the "OK" button. 

3. Enter "DLL Test" as a description for the EXE 16 program. Enter the full path to the EXE 16 
program as a command line. 

Example: 

Description: Test 

Command Line: c:\work\dll\exel6.exe 

21.5.3 Running the Examples 

Start the 16-bit application by double clicking on its icon. A number of message boxes are presented. You 
may wish to compare the output in each message box with the source code of the program to determine if 
the correct results are being obtained. Click on the "OK" button as each of them are displayed. 

21.5.4 Debugging a 32-bit DLL 

The Open Watcom Debugger can be used to debug a DLL. To debug a 32-bit DLL, a "breakpoint" 
instruction must be inserted into the source code for the DLL at the "WinMain" entry point. This is done 
using the "pragma" compiler directive. We have already added the breakpoint to the source code for the 
32-bit DLL. 
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Example: 

extern void Breakpoint( void ) ; 
♦pragma aux Breakpoint = Oxcc; 

int PASCAL WinMain( HANDLE hlnstance, 

HANDLE xl, 

LPSTR lpCmdLine, 
int x2 ) 

{ 

Breakpoint(); 

DefineDLLEntry( 1, (void *) Libl, 

DLL_ WORD, 
DLL_ DWORD, 
DLL_ WORD, 


Start up Microsoft Windows 3.x if you have not already done so. Start the debugger by double-clicking on 
the Open Watcom Debugger icon. At the prompt, enter the path specification for the application. When 
the debugger has successfully loaded EXE 16, start execution of the program. When the breakpoint is 
encountered in the 32-bit DLL, the debugger is re-entered. The debugger will automatically skip past the 
breakpoint. 

From this point on, you can symbolically debug the 32-bit DLL. You might, for example, set breakpoints 
at the start of each DLL routine to debug each of them as they are called. 

21.5.5 Summary 

Note that the "WinMain" entry point is only called once, at the start of any application requesting it. After 
this, the "WinMain" entry point is no longer called. You may have to restart Windows to debug this section 
of code a second or third time. 
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22 Interfacing Visual Basic and Open Watcom 
C/C++ DLLs 

22.1 Introduction to Visual Basic and DLLs 


This chapter describes how to interface Microsoft Visual Basic 3.0 applications and 32-bit Dynamic Link 
Libraries (DLLs) created by Open Watcom C/C++. It describes how to write functions for a 32-bit DLL, 
how to compile and link them, and how to call these functions from Visual Basic. One of the proposed 
techniques involves the use of a set of cover functions in a 16-bit DLL so, indirectly, this chapter also 
describes interfacing to 16-bit DLLs. 

It is possible to invoke the Win38 6LibEntry function (Open Watcom’s 32-bit function entry point, 
described below) directly from Visual Basic. However, this technique limits the arguments that can be 
passed to a 32-bit DLL. The procedure and problems are explained below. 

To work around the problem, a 16-bit DLL can be created, that covers the 32-bit DLL. Within the 16-bit 
DLL, we will place cover functions that will call the corresponding 32-bit function in the 32-bit DLL. We 
illustrate the creation of the 16-bit DLL using the 16-bit C compiler in Open Watcom C/C++. 

Before we begin our example, there are some important technical issues to consider. 

The discussion in this chapter assumes that you, the developer, have a working knowledge of Visual Basic, 
including how to bring up the general declarations screen, how to create command buttons, and how to 
associate code with command buttons. You must use Visual Basic 3.0 or later. Visual Basic Version 2.x 
will not work because of a deficiency in this product regarding the calling of functions in DLLs. 

For the purposes of the following discussion, you should have installed both the 16-bit and 32-bit versions 
of Open Watcom C/C++, as well as version 3.0 or later of Visual Basic. Ensure that the PATH, 
INCLUDE and WINDOWS_INCLUDE environment variables are defined to include at least the 
directories indicated. We have assumed that Open Watcom C/C++ is installed in the c : \watcom 
directory, and Visual Basic is in the c:\vb directory: 

set path=c:\watcom\binw;c:\vb;c:\dos;c:\windows 

set include=c:\watcom\h 

set windows_ include=c:\watcom\h\win 

Open Watcom’s 32-bit DLL supervisor contains a general entry point for Windows applications to call into 
called Win386LibEntry. It also contains 128 specific entry points called DLL1 to DLL128 which 
correspond to the entry points established via Def ineDLLEntry (the first argument to 
Def ineDLLEntry is an index number in the range 1 to 128). All applications call into the 32-bit DLL 
via these entry points. They build the necessary stack frame and switch to the 32-bit DLL’s data space. 

If you call via Win386LibEntry then you pass the DLL entry point number or index (1 to 128) as the 
last argument. Win3 8 6LibEntry uses this index number to call the appropriate 32-bit DLL routine. 

In many languages and programs (such as C and Microsoft Excel), function calls are very flexible. In other 
words, a function can be called with different argument types each time. This is generally necessary for 
calling Win38 6LibEntry in a 32-bit extended DLL function. The reason is that this function takes the 
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same arguments as the function being called, as well as the index number of the called function. After the 
32-bit flat model has been set up, Win38 6LibEntry then calls this function. In Visual Basic, once a 
function is declared as having certain arguments, it cannot be redeclared. For example, suppose we have a 
declaration as follows: 

Example: 

Declare Function Win386LibEntry Lib "c:\path\vbdll32.dll" 

=> (ByVal vl As Integer, ByVal v2 As Long, ByVal 

=> v3 As Integer, ByVal I As Integer) As Long 

(Note: the => means to continue the statement on the same line.) In this example, we could only call a 
function in any 32-bit extended DLL with a 16-bit integer as the first and third argument, and a 32-bit 
integer as the second argument. There are three ways to work around this deficiency in Visual Basic: 

1. Use the Visual Basic "Alias" attribute to declare Win38 6LibEntry differently for each DLL 
routine. Reference the different DLL routines using these aliases. 

2. Use the specific entry point, one of DLL1 through DLL128, corresponding to the DLL routine 
that you want to call. Each entry point can be described to take different arguments. We can 
still use the "Alias" attribute to make the link between the name we use in the Visual Basic 
function and the name in the 32-bit extended DLL. This is the method that we will use in the 
"Direct Call" technique discussed below. It is simpler to use since it requires one less argument 
(you don't require the index number). 

3. Use a method which involves calling functions in a 16-bit "cover" DLL written in a 
flexible-argument language, which then calls the functions in the 32-bit DLL. This is the 
"Indirect Call" method discussed below. 


22.2 A Working Example 

The best way to demonstrate these techniques is through an example. This example consists of a Visual 
Basic application with 3 push buttons. The first push button invokes a direct call to a 32-bit DLL which 
will display a message window with its arguments, the second push button invokes an indirect call to the 
same function through a 16-bit DLL, and the third button exits the Visual Basic application. 

To create a Visual Basic application: 

(1) Start up a new project folder from the "File" menu. 

(2) Select "View Form" from the "Project" window. 

(3) Draw three command buttons on the form by selecting command buttons from the "Toolbox" 
window. 

(4) Change the caption on each button. To do this, highlight the first button. Then, open the 
"Properties" window. Double click on the "Caption window", and change the caption to "Direct call". 
Highlight the second button, and change its caption to "Indirect call". Highlight the third, changing 
the caption to "Exit". 

Now, your Visual Basic application should have three push buttons, "Direct call", "Indirect call", and 
"Exit". 
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(5) Double click on the "Direct Call" button. 

An edit window will pop up. Enter the following code: 

Sub Commandl_ Click () 

Dim varl, var2 As Integer 
Dim varlong, worked As Long 

varl = 230 
varlong = 215 
var2 = 32 

worked = Add3(varl, varlong, var2) 

Print worked 

worked = Add2(varlong, var2) 

Print worked 
End Sub 

(6) Double click on the "Indirect Call" button. 

Another edit window will pop up. Enter the following code: 

Sub Command2_ Click () 

Dim varl, var2 As Integer 
Dim varlong, worked As Long 

varl = 230 
varlong = 215 
var2 = 32 

worked = Functionl ( varl, varlong, var2 ) 

Print worked 

worked = Function2( varlong, var2 ) 

Print worked 
End Sub 

(7) Double click on the "Exit" command button and enter the following code in the pop-up window: 

Sub Command3_ Click () 

End 
End Sub 

(8) Select "View Code" from the "Project" window. To interface these Visual Basic functions to the 
DLLs, the following code is needed in the 

Object: [general] Proc: [declarations] 

section of the code. This code assumes that VBDLL32 . DLL and COVER1 6 . DLL are in the 
c : \path directory. Modify the pathnames appropriately if this is not the case. (Note: the => means 
to continue the statement on the same line.) 
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Declare Function Functionl Lib "c:\path\coverl6.dll" 

=> (ByVal vl As Integer, ByVal v2 As Long, 

=> ByVal v3 As Integer) As Long 

Declare Function Function2 Lib "c:\path\coverl6.dll" 

=> (ByVal vl As Long, ByVal v2 As Integer) As Long 

Declare Function Add3 Lib "c:\path\vbdll32.dll" 

=> Alias "DLL1" 

=> (ByVal vl As Integer, ByVal v2 As Long, 

=> ByVal v3 As Integer) As Long 

Declare Function Add2 Lib "c:\path\vbdll32.dll" 

=> Alias "DLL2" 

=> (ByVal vl As Long, ByVal v2 As Integer) As Long 

Now, when all of the code below is compiled correctly, and the Visual Basic program is run, the "Direct 
call" button will call the DLL1 and DLL2 functions directly, aliased as the functions Add3 and Add2 
respectively. The "Indirect call" button will call the 16-bit DLL, which will then call the 32-bit DLL, for 
both Functionl and Function2 . To run the Visual Basic program, select "Start" from the "Run" 
menu. 


22.3 Sample Visual Basic DLL Programs 

The sample programs provided below are for a 32-bit DLL, and a 16-bit cover DLL, which will call the two 
functions contained in the 32-bit DLL. 

22.3.1 Source Code for VBDLL32.DLL 

/* 

* VBDLL32.C 
*/ 

#include <stdio.h> 

#include <windows.h> /* required for all Windows applications */ 

long FAR PASCAL Add3( short varl, long varlong, short var2 ) 

{ 

char buf [128]; 

sprintf( buf, "Add3: varl=%d, varlong=%ld, var2=%d", 
varl, varlong, var2 ); 

MessageBox( NULL, buf, "VBDLL32", MB_ OK | MB_ TASKMODAL ); 
return( varl + varlong + var2 ) ; 


long FAR PASCAL Add2( long varlong, short var2 ) 

{ 

char buf[128]; 

sprintf( buf, "Add2: varlong=%ld, var2=%d", varlong, var2 ); 
MessageBox( NULL, buf, "VBDLL32", MB_ OK | MB_ TASKMODAL ); 
return( varlong + var2 ) ; 
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♦pragma off (unreferenced); 

int PASCAL WinMain(HANDLE hlnstance, HANDLE xl, LPSTR lpCmdLine, int x2) 
♦pragma on (unreferenced) ; 

{ 

DefineDLLEntry ( 1, (void *) Add3, DLL_ WORD, DLL_ DWORD, DLL_ WORD, 

DLL_ ENDLIST ) ; 

DefineDLLEntry ( 2, (void *) Add2, DLL_ DWORD, DLL_ WORD, DLL_ ENDLIST ); 
return ( 1 ) ; 

} 


22.3.2 Source code for C0VER16.DLL 

The functions in this 16-bit DLL will call the functions in the 32-bit DLL, VBDLL32 . DLL, shown above, 
with the appropriate Win38 6LibEntry call for each function. 

/* 

* COVERl6.C 
*/ 

♦include <stdio.h> 

#include <windows.h> /* required for all Windows applications */ 

typedef long (FAR PASCAL *FPROC)(); 

FPROC DLL_ 1; 

FPROC DLL_ 2; 

long FAR PASCAL _export Functionl( short varl, 

long var2, 
short var3 ) 

{ 

return ( (long) DLL_ 1 ( varl, var2, var3 ) ); 

} 

long FAR PASCAL _export Function2( long varl, short var2 ) 

{ 

return ( (long) DLL_ 2 ( varl, var2 ) ); 

} 

#pragma off (unreferenced); 

BOOL FAR PASCAL LibMain( HANDLE hlnstance, WORD wDataSegment, 

WORD wHeapSize, LPSTR IpszCmdLine ) 

#pragma on (unreferenced); 

{ 

HANDLE hlib; 

/* Do our DLL initialization */ 
hlib = LoadLibrary( "vbdll32.dll" ); 
if( hlib < 32 ) { 

MessageBox( NULL, 

"Make sure your PATH contains VBDLL32.DLL", 

"COVERl 6 " , MB_ OK | MB_ ICONEXCLAMATION ); 
return( FALSE ); 

} 

DLL_ 1 = (FPROC) GetProcAddress( hlib, "DLL1" ); 

DLL_ 2 = (FPROC) GetProcAddress( hlib, "DLL2" ); 
return( TRUE ); 

} 
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22.4 Compiling and Linking the Examples 

To create the 32-bit DLL VBDLL32 . DLL, type the following at the command line (make sure that 
VBDLL32 . c is in your current directory): 

wcl386 vbdll32 -bt=windows -bd -d2 -l=win386 

wbind vbdll32 -d -n 

To create the 16-bit DLL COVER16 . DLL, type the following at the command line (make sure that 
COVER16 . C are in your current directory): 

wcl cover16 -me -bt=windows -bd -zu -d2 -l=windows_ dll 
Notes: 

1. The "me" option selects the compact memory model (small code, big data). The code for 16-bit 
DLLs must be compiled with one of the big data models. 

2. The "bd" option indicates that a DLL will be created from the object files. 

3. The "bt" option selects the "windows" target. This option causes the C or C++ compiler to 
generate Windows prologue/epilogue code sequences which are required for Microsoft Windows 
applications. It also causes the compiler to use the WINDOWS_INCLUDE environment 
variable for header file searches. It also causes the compiler to define the macro 

_WINDOWS _and, for the 32-bit C or C++ compiler only, the macxo_ WINDOWS_ 38 6_ 

4. The "zu" option is used when compiling 16-bit code that is to be placed in a Dynamic Link 
Library (DLL) since the SS register points to the stack segment of the calling application upon 
entry to the function. 

5. The "d2" option is used to disable optimizations and include debugging information in the object 
file and DLL. The techniques for debugging DLLs are described in the chapter entitled 
"Windows 32-Bit Dynamic Link Libraries" on page 157. 

You are now ready to run the Visual Basic application. 
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23 WIN386 Library Functions and Macros 


Each special Windows function or macro in the Open Watcom C/C++ library is described in this chapter. 
Each description consists of a number of subsections: 

Synopsis: This subsection gives the header files that should be included within a source file that references the 

function or macro. It also shows an appropriate declaration for the function or for a function that could be 
substituted for a macro. This declaration is not included in your program; only the header file(s) should be 
included. 

When a pointer argument is passed to a function and that function does not modify the item indicated by 
that pointer, the argument is shown with const before the argument. For example, 

const char *string 

indicates that the array pointed at by string is not changed. 

Description: This subsection is a description of the function or macro. 

Returns: This subsection describes the return value (if any) for the function or macro. 

Errors: This subsection describes the possible errno values. 

See Also: This optional subsection provides a list of related functions or macros. 

Example: This optional subsection consists of one or more examples of the use of the function. The examples are 
often just fragments of code (not complete programs) for illustration purposes. 

Classification: This subsection provides an indication of where the function or macro is commonly found. The 

functions or macros in this section are all classified as "WIN386" (i.e., they pertain to 32-bit Windows 
programming). 


WIN386 Library Functions and Macros 171 




AllocAlias16 


Synopsis: #include <windows.h> 

DWORD AllocAliasl6( void *ptr ); 

Description: The AllocAliasl6 function obtains a 16-bit far pointer equivalent of a 32-bit near pointer. These 
pointers are used when passing data pointers to Windows through functions that have DWORD 
arguments, and for any pointers within data structures passed this way. 

Returns: The AllocAliasl6 function returns a 16-bit far pointer usable by Windows, or returns 0 if the alias 

cannot be allocated. 

See Also: FreeAliasl6 

Example: #include <windows.h> 

DWORD mcs_ 16; 

/* 

* Send a message to a MDI client to create a window. 

* _ 16SendMessage is used for this example, since it will 

* not do any pointer conversions automatically. 

*/ 

MDIOREATESTRUCT mcs; 

mcs.szTitle = (LPSTR) AllocAliasl6( "c:Wfoo.bar" ); 
mcs.szClass = (LPSTR) AllocAliasl6( "mdichild" ); 
mcs.hOwner = hlnst; 

mcs.x = mcs.cx = (int) CW_ USEDEFAULT; 
mcs.y = mcs.cy = (int) CW_ USEDEFAULT; 
mcs.style = 0; 

/* tell the MDI Client to create the child */ 

mcs_16 = AllocAliasl6 ( &mcs ); 

hwnd = (WORD) _ 16SendMessage( hwndMDIClient, 

WM_ MDI CREATE, 

0, 

(LONG) mcs_ 16 ); 

FreeAliasl6( mcs_16 ); 

FreeAliasl6( (DWORD) mcs.szClass ); 

FreeAliasl6( (DWORD) mcs.szTitle ); 

Classification: WIN386 
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AllocHugeAlias16 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 


♦include <windows.h> 

DWORD AllocHugeAliasl6( void *ptr, DWORD size ); 

The AllocHugeAliasl6 function obtains a 16-bit far pointer to a 32-bit memory object that is size bytes 
in size. This is similar to the function AllocAliasl 6, except that AllocAliasl 6 will only give 
16-bit far pointers to 32-bit memory objects of up to 64K in size. To get 16-bit far pointers to 32-bit 
memory objects larger than 64K, AllocHugeAliasl 6 should be used. 

The AllocHugeAliasl6 function returns a 16-bit far pointer usable by Windows, or returns 0 if the alias 
cannot be allocated. 

AllocAliasl6, FreeAliasl6, FreeHugeAliasl6 

♦include <windows.h> 

♦include <malloc.h> 

♦define SIZE 300000 

DWORD alias; 
void *tmp; 

tmp = malloc( SIZE ); 

alias = AllocHugeAliasl6( tmp, SIZE ); 

/* Windows calls using the alias ... */ 

FreeHugeAliasl6( alias, SIZE ); 

WIN386 
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Call16 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


♦include <windows.h> 

DWORD _ Calll6( FARPROC lpFunc, char *fmt, ... ); 

The _Calll6 function performs the same function as GetlndirectFunctionHandle, 
InvokelndirectFunctionHandle and FreelndirectFunctionHandle but is much 
easier to use. The first argument lpFunc is the address of the 16-bit function to be called. This address 
is usually obtained by calling GetProcAddress with the name of the desired function. The second 
argument fmt is a string identifying the types of the parameters to be passed to the 16-bit function. 

Character Parameter Type 

c call a ’cdecT function as opposed to a ’pascal’ function (if specified, it must be listed 

first) 

b unsigned BYTE 

w 16-bit WORD 

d 32-bit DWORD 

/ double precision floating-point 

p 32-bit flat pointer (converted to 16:16 far pointer) 

The 16-bit function must use either the PASCAL or CDECL calling convention. PASCAL calling 
convention is the default. If the function uses the CDECL calling convention, then you must specify the 
letter "c" as the first character of the argument type string. 

Pointer types will automatically be converted from 32-bit near pointers to 16-bit far pointers before the 
function is invoked. Note that this pointer is only valid over the period of the call; after control returns 
to the 32-bit application, the 16-bit pointer created by the Supervisor is no longer valid. 

The _Calll6 function returns a 32-bit DWORD which represents the return value from the 16-bit 
function that was called. 

GetlndirectFunctionHandle, FreelndirectFunctionHandle 
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CaU16 


♦include <windows.h> 

HANDLE hDrv; 

FARPROC lpfn; 
int cb; 

if( (hDrv = LoadLibrary ("foo.dll")) < 32 ) 
return FALSE; 

if( !(lpfn = GetProcAddress (hDrv, "ExtDeviceMode")) ) 
return FALSE; 

/* 

* now, invoke the function 
*/ 

cb = (WORD) _ Calll6 ( 


lpfn. 

// 

address of function 

"wwdppddw", 

// 

parameter type info 

hwnd. 

// 

parameters ... 

hDrv, 



NULL, 




"POSTSCRIPT PRINTER", 
"LPT1", 

NULL, 

NULL, 

0 

); 

Classification: WIN386 
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DefineDLLEntry 


Synopsis: #include <windows.h> 

int DefineDLLEntry( int index, void * routine, ... ); 

Description: The DefineDLLEntry function defines an index number for the 32-bit DLL procedure routine. The 
parameter index defines the index number that must be used in order to invoke the 32-bit FAR 
procedure routine. The variable argument list defines the types of parameters that will be received by 
the 32-bit DLL routine. Valid parameter types are: 

DLL_PTR 16-bit far pointer 

DLL_DWORD 32-bits 

DLLJWORD 16-bits 

DLLjCHAR 8-bits 

DLL_ENDLIST Marks the end of the variable argument list. 

Note that all pointers are received as 16-bit far pointers. To access the data from the 32-bit DLL, the 
MK_ FP32 macro must be applied. The data can then be accessed with the resulting 32-bit far pointer. 

Returns: The DefineDLLEntry function returns zero if successful, and a non-zero value otherwise. 

Example: #include <windows.h> 

int FAR PASCAL FooMe( WORD wl, DWORD w2, WORD w3 ) 

{ 

char str[128]; 

sprintf( str, "wl=%hx, w2=%lx, w3=%hx", wl, w2, w3 ); 

MessageBox( NULL, str, "DLL Test", MB_ OK ); 
return( wl + w2 ); 

} 

int PASCAL WinMain( HANDLE hlnstance, HANDLE xl, 

LPSTR lpCmdLine, int x2 ) 

{ 

DefineDLLEntry( 1, (PROCPTR) FooMe, DLL_ WORD, 

DLL_ DWORD, DLL_ WORD, DLL_ ENDLIST ); 

MessageBox( NULL, "32-bit DLL Started", "Test", MB_ OK ); 
return( 1 ) ; 

} 

Classification: WIN386 
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DefineUserProcW 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


♦include <windows.h> 

int DefineUserProcl6( int typ, PROCPTR routine, ... ); 

The DefineUserProcl6 function defines the arguments accepted by the user defined callback procedure 
routine. There may be up to 32 user defined callbacks. The parameter typ indicates which one of 
GETPROC_ USERDEFINED_ 1 througlGETPROC_ USERDEFINED_ 32 is being defined (see 
GetProcl 6). The callback routine must be declared as FAR PASCAL, or as FAR cdecl. The 
variable argument list defines the types of parameters that will be received by the user defined callback 
procedure routine. Valid parameter types are: 


UDP16_PTR 
UDP16_D WORD 
UDP16WORD 
UDP16CIIAR 
UDP16_CDECL 

UDP16_ENDLIS T 


16-bit far pointer 
32-bits 
16-bits 
8-bits 

callback routine will be declared as type cdecl rather than as type PASCAL. 
This keyword may be placed anywhere before the UDP16_ ENDLIST 
keyword. 

Marks the end of the variable argument list. 


Once the DefineUserProcl6 function has been used to declare the user callback routine, then 
GetProcl 6 may be used to get a 16-bit function pointer that may be used by Windows. 


The DefineUserProcl6 function returns zero if it succeeds; and non-zero if it fails. 


GetProcl6 


♦include <windows.h> 

WORD FAR PASCAL Test ( DWORD a, WORD b ) 

{ 

char foo[128]; 

sprintf( foo, "a=%lx, b=%hx", a, b ) ; 
MessageBox( NULL, foo, "TEST", MB_ OK ); 
return( 0x123 ); 
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DefineUserProc16 


int DefineTest( void ) 

{ 

FARPROC cb; 

Def ineUserProcl6 ( GETPROC_ USERDEFINED_ 1, 

(PROCPTR) Test, 

UDP16_ DWORD, 

UDP16_ WORD, 

UDP16_ ENDLIST ); 

cb = GetProcl6 ( (PROCPTR) Test, GETPROC_ USERDEFINED_ 1 ); 
/* 

* cb may then be used whenever a pointer to the 

* callback is required by 16-bit Windows 
*/ 


Classification: WIN386 
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FreeAlias16 


Synopsis: #include <windows.h> 

void FreeAliasl6( DWORD fpl6 ); 

Description: FreeAliasl6 frees a 16-bit far pointer alias for a 32-bit near pointer that was allocated with 

AllocAliasl 6. This is important to do when there is no further use for the pointer since there are a 
limited number of 16-bit aliases available (due to limited space in the local descriptor table). 

Returns: The FreeAliasl6 function returns nothing. 

See Also: AllocAliasl 6 

Example: #include <windows.h> 

DWORD mcs_ 16; 

/* 

* Send a message to a MDI client to create a window. 

* _ 16SendMessage is used for this example, since it will 

* not do any pointer conversions automatically. 

*/ 

MDIOREATESTRUCT mcs; 

mcs.szTitle = (LPSTR) AllocAliasl6( "c:\\foo.bar" ); 
mcs.szClass = (LPSTR) AllocAliasl6( "mdichild" ); 
mcs.hOwner = hlnst; 

mcs.x = mcs.cx = (int) CW_ USEDEFAULT; 
mcs.y = mcs.cy = (int) CW_ USEDEFAULT; 
mcs.style = 0; 

/* tell the MDI Client to create the child */ 

mcs_16 = AllocAliasl6 ( &mcs ); 

hwnd = (WORD) _ 16SendMessage( hwndMDIClient, 

WM_ MDI CREATE, 

0, 

(LONG) mcs_16 ) ; 

FreeAliasl6( mcs_16 ); 

FreeAliasl6( (DWORD) mcs.szClass ); 

FreeAliasl6( (DWORD) mcs.szTitle ); 

Classification: WIN386 
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FreeHugeAlias16 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 


#include <windows.h> 

void FreeHugeAliasl6( DWORD fpl6, DWORD size ); 

FreeHugeAliasl6 frees a 16-bit far pointer alias that was allocated with AllocHugeAliasl6. The 
size of the original 32-bit memory object must be specified. It is important to use 
FreeHugeAliasl 6 when there is no further use for the pointer, since there are a limited number of 
16-bit aliases available (due to limited space in the local descriptor table). 

The FreeHugeAliasl6 function returns nothing. 

AllocHugeAliasl6, AllocAliasl6, FreeAliasl6 

#include <windows.h> 

♦include <malloc.h> 

♦define SIZE 300000 

DWORD alias; 
void *tmp; 

tmp = malloc( SIZE ); 

alias = AllocHugeAliasl6( tmp, SIZE ); 

/* windows calls using the alias ... */ 

FreeHugeAliasl6( alias, SIZE ); 

WIN386 
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FreelndirectFunctionHandle 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


#include <windows.h> 

void FreelndirectFunctionHandle( HINDIR handle ); 
FreelndirectFunctionHandle frees a handle that was obtained using 

GetlndirectFunctionHandle. This is important to do when there is no further use for the 
pointer since there are a limited number of 16-bit aliases available (due to limited space in the local 
descriptor table). 

The FreelndirectFunctionHandle function returns nothing. 


_ Calll6,GetIndirectFunctionHandle, InvokelndirectFunction 
♦include <windows.h> 

HANDLE hDrv; 

FARPROC lpfn; 

if( (hDrv = LoadLibrary( "foo.lib" )) < 32 ) 
return FALSE; 

if( !(lpfn = GetProcAddress( hDrv, "ExtDeviceMode" )) ) 

return FALSE; 

#ifdef WINDOWS. 386 

hlndir = GetlndirectFunctionHandle( 
lpfn, 

INDIR_ WORD, 

INDIR_ WORD, 

INDIR_ DWORD, 

INDIR_ PTR, 

INDIR_ PTR, 

INDIR_ DWORD, 

INDIR_ DWORD, 

INDIR_ WORD, 

INDIR_ ENDLIST ); 

cb = (WORD) InvokelndirectFunction( 
hlndir, 
hwnd, 
hDrv, 

NULL, 

"POSTSCRIPT PRINTER", 

"LPT1", 

NULL, 

NULL, 

o ) ; 

FreelndirectFunctionHandle( hlndir ) ; 
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FreelndirectFunctionHandle 


#else 

cb = lpfn( hwnd, 
hDrv, 

NULL, 

"POSTSCRIPT 
"LPT1", 
NULL, 

NULL, 

0 ); 

#endif 

Classification: WIN386 


PRINTER", 


182 WIN386 Library Functions and Macros 




GetlndirectFunctionHandle 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


♦include <windows.h> 

HINDIR GetlndirectFunctionHandle( FARPROC prc, ... ) ; 

The GetlndirectFunctionHandle function gets a handle for a 16-bit procedure that is to be invoked 
indirectly. The procedure is assumed to have PASCAL calling convention, unless the INDIR_ CDECL 
parameter is used, to indicate that Microsoft C calling convention is to be used. The 16-bit far pointer 
prc is supplied to GetlndirectFunctionHandle, and a list of the type of each parameter (in the order that 
they will be passed to the 16-bit function). The parameter types are: 


INDIR_D WORD 
INDIRWORD 
INDIRCIIAR 
INDIR_PTR 

INDIRCDECL 

INDIR_ENDLIST 


A DWORD will be passed. 

A WORD will be passed. 

A char will be passed. 

A pointer will be passed. This is only used if pointer conversion from 32-bit 
to 16-bit is required, otherwise; INDIR_DWORD is specified. 

This option may be included anywhere in the list before the 

INDIR_ ENDLIST keyword. When this is used, the calling convention used 

to invoke the 16-bit function will be the Microsoft C calling convention. 

Marks the end of the parameter list. 


There is no substitute for this function when compiling for 16-bit Windows. In order to make the code 

16-bit Windows compatible, conditional code (based on the_WINDOWS_386_macro) should be 

placed around the GetlndirectFunctionHandle usage (see the example). 


This handle is a data structure that was created using the mal loc function. To free the handle, just use 
one of the FreelndirectFunctionHandle or free functions. 


You may find it easier to use _ Cal 116 rather than GetlndirectFunctionHandle followed by a call to 
InvokeIndirectFunction. 


The GetlndirectFunctionHandle function returns a handle to the indirect function, or NULL if a handle 
could not be allocated. This handle is used in conjunction with InvokelndirectFunction to call 
the 16-bit procedure. 

_ Calll6,FreeIndirectFunctionHandle, InvokelndirectFunction 


♦include <windows.h> 

HANDLE hDrv; 
FARPROC lpfn; 


if ( 
if ( 


(hDrv = LoadLibrary( "foo.lib" 
return FALSE; 

!(lpfn = GetProcAddress( hDrv, 
return FALSE; 


)) < 32 ) 

"ExtDeviceMode" ) ) ) 
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GetlndirectFunctionHandle 


#ifdef WINDOWS. 386 

hlndir = GetlndirectFunctionHandle( 
Ipfn, 

INDIR_ WORD, 

INDIR_ WORD, 

INDIR_ DWORD, 

INDIR_ PTR, 

INDIR_ PTR, 

INDIR_ DWORD, 

INDIR_ DWORD, 

INDIR_ WORD, 

INDIR_ ENDLIST ); 


cb = (WORD) InvokelndirectFunction( 
hlndir, 
hwnd, 
hDrv, 

NULL, 

"POSTSCRIPT PRINTER", 
"LPT1", 

NULL, 

NULL, 

o ) ; 

FreelndirectFunctionHandle( hlndir ) ; 
#else 

cb = lpfn( hwnd, 
hDrv, 

NULL, 

"POSTSCRIPT PRINTER", 

"LPT1", 

NULL, 

NULL, 

0 ); 

#endif 

Classification: WIN386 
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GetProc16 


Synopsis: #include <windows.h> 

CALLBACKPTR GetProcl6( PROCPTR fen, long type ); 

Description: The GetProcl6 function returns a 16-bit far function pointer suitable for use as a Windows callback 

function. This callback function will invoke the 32-bit far procedure specified by fen. The types of 

callback functions that may be allocated are: 

GETPROCJCALLBACK This is the most common form of callback; suitable as the callback routine 
for a window. The callback has the form: 

long FAR PASCAL WProc( HWND, unsigned, 

WORD, LONG ); 

GETPROCA BORTPROC This is the callback type used for trapping abort requests when printing. 

The callback has the form: 

int FAR PASCAL AbortProc( HDC, WORD ); 

GETPROC_ENUMCHILDWINDOWS This callback is used with the EnumChildWindows 
Windows function. The callback function has the form 

BOOL FAR PASCAL EnumChildWindowsFunc( 

HWND, DWORD ); 

GETPROCENUM FONTS This callback type is used with the EnumFonts Windows function. The 
callback has the form: 

int FAR PASCAL EnumFontsFunc( LPLOGFONT, 

LPTEXTMETRICS, short, LPSTR ); 

GETPROCENUM METAFILE This callback is used with the EnumMetaFile Windows function. 
The callback function has the form: 

int FAR PASCAL EnumMetaFileFunc( HDC, 

LPHANDLETABLE, LPMETARECORD, 
short, LPSTR ); 

GETPROC ENUMOBJECTS This callback is used with the EnumOb jects Windows function. The 
callback function has the form: 

int FAR PASCAL EnumObjectsFunc( LPSTR, LPSTR ); 

GETPROC_ENUMPROPS_FIXED_DS This callback is used with the EnumProps Windows 

function, when the fixed data segments callback is needed. The callback function has the 
form: 


int FAR PASCAL EnumPropsFunc( 

HWND, LPSTR, HANDLE ); 

GETPROC-ENUMPROPS_MOVEABLE_DS This callback is used with the EnumProps Windows 
function, when the moveable data segments callback is needed. The callback function 
has the form: 

int FAR PASCAL EnumPropsFunc( 

HWND, WORD, PSTR, HANDLE ); 
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GetProc16 


Returns: 


GETPROC_ENUMTASKWINDOWS This callback is used with the EnumTaskWindows Windows 
function. The callback function has the form: 

int FAR PASCAL EnumTaskWindowsFunc( 

HWND, DWORD ); 

GETPROC_ENUMWINDOWS This callback is used with the EnumWindows Windows function. 
The callback function has the form: 

int FAR PASCAL EnumWindowsFunc( HWND, DWORD ); 

GETPROCJGLOBALNOTIFY This callback is used with the GlobalNotif y Windows function. 
The callback function has the form: 

int FAR PASCAL GlobalNotifyFunc( HANDLE ); 

GETPROCJGRAYSTRING This callback is used with the GrayString Windows function. The 
callback function has the form: 

int FAR PASCAL GrayStringFunc( 

HDC, DWORD, short ); 

GETPROC_LINEDDA This callback is used with the LineDDA Windows function. The callback 
function has the form: 

void FAR PASCAL LineDDAFunc( 

short, short, LPSTR ); 

GETPROC_SETRESOURCEHANDLER This callback is used with the SetResourceHandler 
Windows function. The callback function has the form: 

int FAR PASCAL SetResourceHandlerFunc( 

HANDLE, HANDLE, HANDLE ); 

GETPROC_SETTIMER This callback is used with the SetTimer Windows function. The callback 
function has the form: 

int FAR PASCAL SetTimerFunc( 

HWND, WORD, short, DWORD ); 

GETPROC_SETWINDOWSHOOK This callback is used with the SetWindowsHook Windows 
function. The callback function has the form: 

int FAR PASCAL SetWindowsHookFunc( 
short, WORD, DWORD ); 

GETPROC_USERDEFINED_x This callback is used in conjunction with Def ineUserProcl 6 
function to create a callback routine with an arbitrary set of parameters. Up to 32 user 
defined callbacks are allowed, they are identified by using 

GETPROC_USERDEFINED_l through GETPROC_USERDEFINED_32. The user 
defined callback must be declared as a FAR PASCAL function, or as a FAR cdecl 
function. 

The GetProcl6 function returns a 16-bit far pointer to a callback procedure. This pointer may then be 

fed to any Windows function that requires a pointer to a function within the 32-bit program. Note that 

the callback function within the 32-bit program must be declared as FAR. 
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GetProc16 


See Also: ReleaseProcl6 

Example: #include <windows.h> 

CALLBACKPTR cbp; 

FARPROC IpProcAbout; 

/* 

* Get a 16-bit callback routine to point at 

* our About dialogue procedure, then create 

* the dialogue. We use _ 16 versions of 

* MakeProcInstance, DialogBox, and 

* FreeProcInstance because they do not do 

* any magic work on the callback routines. 

*/ 

cbp = GetProcl6( (PROCPTR) About, 

GETPROC_ CALLBACK ) ; 

IpProcAbout = _ 16MakeProcInstance ( cbp, hlnst ); 

_ 16DialogBox ( hlnst, 

"AboutBox", 
hWnd, 

IpProcAbout ); 

_ 16FreeProcInstance( IpProcAbout ); 

ReleaseProcl6( cbp ); 

Classification: WIN386 
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InvokelndirectFunction 


Synopsis: 

Description: 


Returns: 

See Also: 
Example: 


♦include <windows.h> 

long InvokelndirectFunction( HINDIR handle, ... ); 

The InvokelndirectFunction function invokes the 16-bit function pointed to by the specified handle. 
The handle must have been previously allocated using the GetlndirectFunctionHandle 
function. The handle is followed by the list of parameters to be passed to the 16-bit function. 

If you specified INDIR_ PTR as a parameter when allocating the handle, then a 16-bit pointer is 
allocated for a 32-bit pointer that you pass. However, this pointer is freed when the 16-bit function 
being invoked returns. 

There is no substitute for this function when compiling for 16-bit Windows. In order to make the code 

16-bit Windows compatible, conditional code (based on the_WINDOWS_386_macro) should be 

placed around the InvokelndirectFunction usage (see the example). 

The InvokelndirectFunction function returns the value which the 16-bit function returned. If the 16-bit 
function returns a short rather than a long, the result must be typecast. 


_ Calll6,FreeIndirectFunctionHandle, GetlndirectFunctionHandle 

♦include <windows.h> 

HANDLE hDrv; 

FARPROC lpfn; 

HINDIR hlndir; 
int cb; 

if( (hDrv = LoadLibrary( "foo.lib" )) < 32 ) 
return FALSE; 

if( !(lpfn = GetProcAddress( hDrv, "ExtDeviceMode" )) ) 

return FALSE; 

♦ ifdef WINDOWS. 386 

hlndir = GetlndirectFunctionHandle( 
lpfn, 

INDIR_ WORD, 

INDIR_ WORD, 

INDIR_ DWORD, 

INDIR_ PTR, 

INDIR_ PTR, 

INDIR_ DWORD, 

INDIR_ DWORD, 

INDIR_ WORD, 

INDIR_ ENDLIST ); 
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IrivokelndirectFunction 


cb = (WORD) InvokelndirectFunction( 
hlndir, 
hwnd, 
hDrv, 

NULL, 

"POSTSCRIPT PRINTER", 
"LPT1", 

NULL, 

NULL, 

o ) ; 

FreelndirectFunctionHandle( hlndir ) ; 
#else 

cb = lpfn( hwnd, 
hDrv, 

NULL, 

"POSTSCRIPT PRINTER", 

"LPT1", 

NULL, 

NULL, 

0 ); 

#endif 

Classification: WIN386 
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MapAliasToFlat 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 


#include <windows.h> 

void *MapAliasToFlat( DWORD alias ) ; 

The MapAliasToFlat function returns a 32-bit near pointer equivalent of a pointer allocated previously 
with AllocAliasl6 or AllocHugeAliasl6. This is useful if you are communicating with a 
16-bit application that is returning pointers that you previously gave it. 

The MapAliasToFlat function returns a 32-bit near pointer usable by the 32-bit application. 

AllocAliasl6, AllocHugeAliasl6 

♦include <windows.h> 

DWORD alias; 
void *ptr; 

alias = (DWORD) AllocAliasl6( Salias ); 
alias += 5; 

ptr = MapAliasToFlat( alias ) ; 

if( ptr == ((char *)&alias + 5) ) { 

MessageBox( NULL,"It Worked"MB_ OK ); 

} else { 

MessageBox( NULL,"It Failed"MB_ OK ); 

} 

WIN386 
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MK FP16 


Synopsis: 

Description: 


Returns: 
See Also: 
Example: 


Classification: 


♦include <windows.h> 

DWORD MK_ FP16 ( void far * fp32 ); 

The MK_FP16 function converts a 32-bit far pointer to a 16-bit far pointer. The 16-bit pointer is 
created by simply removing the high word of the offset of the 32-bit pointer. 

The 32-bit far pointer must be one that was obtained by using MK_ FP32 to extend a 16-bit pointer. 

This is useful whenever it is necessary to pass a 16-bit far pointer a parameter to a Windows function 
though an _16 function. 

The MK_FP16 returns a 16-bit far pointer. 

MK_ LOCAL32JMK_ FP32 

♦include <windows.h> 

DRAWITEMSTRUCT FAR *lpdis; 

RECT rc; 

DWORD alias; 

/* 

* The drawitem struct was passed as a long, so we 

* have to convert it to a 32 bit far pointer. 

* Then, we want the 16 bit far pointer of the rcltem 

* element so we can pass it to CopyRect (_ 16CopyRect 

* is a version of CopyRect that does not convert 

* the pointers it was given). 

*/ 

case WM_ DRAWITEM: 

lpdis = MK_ FP32 ( (void *) IParam ); 
alias = AllocAliasl6 ( > ); 

_ 16CopyRect( (LPRECT) alias, 

(LPRECT) MK_ FP16 ( &lpdis->rcltem ) ); 

FreeAliasl6( alias ); 

WIN386 
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MK FP32 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 


#include <windows.h> 

void far *MK_ FP32 ( void * fpl6 ); 

The MK_FP32 function converts a 16-bit far pointer to a 32-bit far pointer. This is needed whenever 
Windows returns a 16-bit far pointer, and access to the data is needed by the 32-bit program. 

The MK_FP32 returns a 32-bit far pointer. 

MK_ LOCAL32JMK_ FP16 

#include <windows.h> 

MEASUREITEMSTRUCT far *mis; 

case WM_ MEASURE ITEM: 

/* 

* Windows has passed us a 16 bit far pointer 

* to the measure item data structure. We 

* use MK_ FP32 to make that pointer a 32-bit far 

* pointer, which enables us to access the data. 

*/ 

mis = MK_ FP32 ( (void *) IParam ); 
mis->itemHeight = MEASUREITEMHEIGHT; 
mis->itemWidth = MEASUREITEMWIDTH; 
return TRUE; 

WIN386 
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MK L0CAL32 


Synopsis: #include <windows.h> 

void far *MK_ LOCAL32( void * fpl6 ); 

Description: The MK_LOCAL32 function converts a 16-bit near pointer to a 32-bit far pointer. This is needed 
whenever Windows returns a 16-bit near pointer that is to be accessed by the 32-bit program. 

Returns: The MK_LOCAL32 returns a 32-bit far pointer. 

See Also: MK_ FP32JMK_ FP16 

Example: #include <windows.h> 

WORD ich,cch; 
char *pch; 
char far *fpch; 

HANDLE hT; 

/* 

* Request the data from an edit window; copy it 

* into a local buffer so that it can be passed 

* to TextOut 
*/ 

ich = (WORD) SendMessage( hwndEdit, 

EM_ LINEINDEX, 
iLine, 

OL ); 

cch = (WORD) SendMessage( hwndEdit, 

EM_ LINELENGTH, 
ich, 

OL ); 

fpch = MK_ LOCAL32 ( LocalLock ( hT ) ) ; 

pch = alloca( cch ) ; 

_ fmemcpy( pch, fpch + ich, cch ); 

TextOut( hdc, 0, yExtSoFar, (LPSTR) pch, cch ); 

LocalUnlock ( hT ); 

Classification: WIN386 
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PASS_ WORD_AS_POINTER 

Synopsis: #include <windows.h> 

void *PASS_ WORD_ AS_ POINTER ( DWORD dw ); 

Description: Some Windows API functions have pointer parameters that do not always take pointers. Sometimes 

these parameters are pure data. In order to stop the supervisor from trying to convert the data into a 
16-bit far pointer, the PASS_WORD_AS_POINTER function is used. 

Returns: The PASS_WORD_AS_POINTER returns a 32-bit "near" pointer, that is really the parameter dw. 

Example: #include <windows.h> 

Func ( PASS_ WORD_ AS_ POINTER ( 1 ) ); 

Classification: WIN386 
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ReleaseProc16 


Synopsis: 

Description: 

Returns: 

See Also: 
Example: 


Classification: 


#include <windows.h> 

void ReleaseProcl6( CALLBACKPTR cbp ); 

ReleaseProcl6 releases the callback function allocated by GetProcl 6. Since the callback routines are 
a limited resource, it is important to release the routines when they are no longer required. 

The ReleaseProcl6 function returns nothing. 

GetProcl6 

#include <windows.h> 

CALLBACKPTR cbp; 

FARPROC IpProcAbout; 

/* 

* Get a 16-bit callback routine to point at 

* our About dialogue procedure, then create 

* the dialogue. We use _ 16 versions of 

* MakeProcInstance, DialogBox, and 

* FreeProcInstance because they do not do 

* any magic work on the callback routines. 

*/ 

cbp = GetProcl6( (PROCPTR) About, 

GETPROC_ CALLBACK ) ; 

IpProcAbout = _ 16MakeProcInstance ( cbp, hlnst ); 

_ 16DialogBox( hlnst, 

"AboutBox", 
hWnd, 

IpProcAbout ); 

_ 16FreeProcInstance( IpProcAbout ); 

ReleaseProcl6( cbp ); 

WIN386 


WIN386 Library Functions and Macros 195 




Windows 3.x Programming Guide 


196 WIN386 Library Functions and Macros 




24 32-bit Extended Windows Application 
Development 


The purpose of this chapter is to anticipate some common questions about 32-bit Windows application 
development. 

The following topics are discussed in this chapter: 

• Can you call 16-bit code from a 32-bit Windows application? 

• Can I WinExec another Windows application? 

• How do I add my Windows resources? 

• All function pointers passed to Windows must be 16-bit far pointers, correct? 

• Why are 32-bit callback routines FAR? 

• Why use the _16 API functions? 

• What about pointers in structures? 

• When do I use MK_FP32? 

• What is the difference between AllocAliasl6 and MK_FP16? 


24.1 Can you call 16-bit code from a 32-bit Windows 
application? 

A 32-bit Windows application can make a call to 16-bit code through the use of the Open Watcom 
_ Calll6 orlnvokelndirectFunction procedures. These functions ensure that the Open Watcom 
Windows Supervisor prepares the stack for the 16-bit call and return to the 32-bit code. The 32-bit 
application uses LoadLibrary function to bring the 16-bit DLF into memory and then calls the 16-bit 
procedures. To invoke 16-bit procedures, use GetProcAddress to get the 16-bit far pointer to the 
function. Use the _ Cal 116 procedure to call the 16-bit function since it is simpler to use than the 
GetlndirectFunctionHandle, InvokelndirectFunction, and 
FreelndirectFunctionHandle sequence. An example of this process is provided under the 
_ Calll6 Windows library function description. 

This method can be used to call any 16-bit Dynamic Fink Fibrary (DFF) procedure or any 32-bit extended 
DLF procedure from within a 32-bit application, including DLLs that are available as products through 
Independent Software Vendors (ISVs). 


24.2 Can I WinExec another Windows application? 

As far as Windows is concerned, the WinExec was made by a 16-bit application, and the application 
specified will be started. This new application can be a 16-bit application or another 32-bit application that 
was implemented with Open Watcom C/C++ 
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24.3 How do I add my Windows resources? 

The WBIND utility automatically runs the resource compiler to add the resources to the 32-bit Windows 
supervisor (since the supervisor is a 16-bit Windows application). Note that resource compiler options may 
be specified by using the "R" option of WBIND. 

24.4 All function pointers passed to Windows must be 16-bit 
far pointers, correct? 

All function pointers passed to Windows must be 16-bit far pointers since no translation is applied to any 
function pointers passed to Windows. Translation is often not possible, since any functions that Windows 
is to call back must be exported, and only 16-bit functions can be exported. 

A 16-bit far pointer to a function is obtained in one of two ways: either Windows gives it to you (via 
GetProcAddr, for example), or you obtain a pointer from the supervisor, via GetProcl 6. 

Function pointers obtained from Windows may either be fed into other Windows functions requiring 
function pointers, or called indirectly by using _ Calll6orby using the 
GetlndirectFunctionHandle, InvokelndirectFunction, and 
FreelndirectFunctionHandle sequence. 

The function GetProcl 6 returns a 16-bit far pointer to a callback function that Windows can use. This 
callback function will direct control into the desired 32-bit routine. 


24.5 Why are 32-bit callback routines FAR? 

The callback routines are declared as FAR so that the compiler will generate a far return from the 
procedure. This is necessary since the 32-bit callback routine is "far" called from the supervisor. 

The callback routine is still "near" in the sense that it lies within the 32-bit flat address space of the 
application. This means that GetProcl 6 only needs the offset of the 32-bit callback function in order to 
set up the 16-bit procedure to call back correctly. Thus, GetProcl 6 accepts type PROCPTR which is in 
fact only 4 bytes long. The compiler will provide the offset only, which is, as already stated, all that is 
needed. 


24.6 Why use the_16 API functions? 

The regular Windows API functions used in Open Watcom C/C++ automatically convert any pointers to 
16-bit far pointers for use by Windows. Sometimes, you may have a set of pointers that are 16-bit far 
pointers already (e.g., obtained from GlobalLock), and do not need any conversion. The "_16..." API 
functions do not convert pointers, they simply pass them on directly to Windows. See the appendix entitled 
"Special Windows API Functions" on page 205 for a list of the "_16..." API functions. 
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24.7 What about pointers in structures? 

Pointers in structures will be converted if the Windows API function actually takes a pointer to that 
structure (i.e., if it is possible for the supervisor to identify that structure). There are few functions that 
accept pointers to structures containing pointers. One such function is RegisterClass which accepts a 
pointer to a WNDCLASS structure. 

If Windows has you passing a pointer to a structure through a 32-bit integer argument, then it is not 
possible for the supervisor to identify that as a pointer that needs conversion. It is also not possible for the 
supervisor to convert any pointers contained in the structure, since it is not aware that it is a structure (as far 
as the supervisor is concerned, that data is what Windows said it was - a 32-bit integer). In this case, it is 
necessary to get 16-bit far pointer equivalents to the 32-bit near pointers that you want to pass. Use 
AllocAliasl6 for this. 


24.8 When do I use MK_FP32? 

MK_ FP32 is used to convert all 16-bit far pointers to 32-bit far pointers that can be used by your 32-bit 
application. For example, to access the memory returned by GlobalLock requires the use of MK_ FP32. 
To access any pointer passed to you (in a callback routine) requires the use of MK_ FP32 if you want access 
to that data in your 32-bit application. 

24.9 What is the difference between AllocAlias16 and 
MK_FP16? 


AllocAliasl 6 actually gets a new selector that points at the same memory as the 32-bit near pointer, 
whereas MK_ FP1 6 squishes a 32-bit far pointer back into a 16-bit far pointer (i.e., it reverses MK_ FP32). 


24.10 Tell Me More About Thunking and Aliases 


Consider the following example. 

dwAlias = AllocAliasl6( pszSomething ); 
hwnd = CreateWindowEx( 

OL, // extendedStyle 

"classname", // class name 

ii ii 

WS_ POPUP I WS_ VISIBLE I WS_ CLIPSIBLINGS | WS_ HSCROLL | 
WS_ BORDER | WS_ CAPTION |WS_ SYSMENU, 


o 

o 

>1 

// 

x, y, cx, cy 

hwndParent, 

// 

hwndParent 

NULL, 

// 

control ID 

g_ app. hinst, 

// 

hlnstance 

(void FAR*)dwAlias); 

// 

lpCreateParams 


FreeAliasl6( dwAlias ); 

When I get the lpCreateParams parameter in WM_ CREATE, I don’t get the originaldwAlias but 
something else which looks like another alias to me. So the question is: Must the CreateWindowEx 
parameter lpCreateParams be "thunked" or is this done automatically by the supervisor? 
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Thunks are always created for function pointers. Aliases are always created for data pointers. There are 3 
data pointer parameters in the CreateWindowEx function call. Aliases are created for all three pointers 
The lpCreateParams argument is a pointer to a struct which contains 3 pointers. Aliases are not 
created for the 3 pointers inside the struct. If you need to have this done, then you will have to create the 
aliases yourself. If you create aliases for the parameters to CreateWindowEx, then you must call the 
_ 16CreateWindowEx function which will not create any aliases. 

Here is some further information on thunks (which are created for function pointers). There is code in the 
supervisor that ttys (note the word trys) to determine if the user has already created a thunk and, if so, 
avoids creating a double thunk which will always generate a GPF. The best policy is to let the supervisor 
automatically create all thunks for you unless you have a very specific reason not to, in which case you 
should call the _16 version of the function. 

Here is some further information on aliases (which are created for data pointers). There is no way for the 
supervisor to determine if a value is a 32-bit flat pointer or an alias for the pointer. So if you pass in an 
alias to the non _16 version of the function, the supervisor will create an alias for the alias which will end 
up pointing to the wrong memory location. If you are going to create the alias, then you must call the _16 
version of the function. 
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25 Special Variables for Windows Programming 


_ AO 00 

_ BOOO 

_ B800 

_C000 

_ DOOO 

_ EOOO 

_ FOOO 

LocalPtr 


A selector for addressing the real-mode segment OxAOOO. 
A selector for addressing the real-mode segment OxBOOO. 
A selector for addressing the real-mode segment 0xB800. 
A selector for addressing the real-mode segment OxCOOO. 
A selector for addressing the real-mode segment OxDOOO. 
A selector for addressing the real-mode segment OxEOOO. 
A selector for addressing the real-mode segment OxFOOO. 
The selector for the supervisor’s data area. 


Special Variables for Windows Programming 201 




Windows 3.x Programming Guide 


202 Special Variables for Windows Programming 




26 Definitions of Windows Terms 


CALLBACKPTR 

DWORD 

HINDIR 

PROCPTR 

WORD 


Pointer to a 16-bit callback routine; used to call into 32-bit functions. 

An unsigned long. 

A handle to 16-bit function that needs to be called indirectly. 

A pointer to a 32-bit callback routine. Although the callback routine is declared 
as far, only the 32-bit offset is used. 

An unsigned short. 
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27 Special Windows API Functions 


On rare occasions, you want to use 16-bit far pointers directly in a Windows function. Since all Windows 
functions in the 32-bit environment are expecting 32-bit near pointers, you cannot simply use the 16-bit far 
pointer directly in the function. 

The following functions are special versions of Windows API functions that do NOT convert any of the 
pointers from 32-bit to 16-bit. There are _16 versions of all Windows API functions that accept data 
pointers. 

_16 Add Atom 

_ 16 AddFontResource 

_16AdjustWindowRect 

_16AdjustWindowRectEx 

_ 16 AnimateP alette 

_16AnsiLower 

_ 16 AnsiLowerBuff 

_16AnsiToOem 

_16AnsiToOemBuff 

_16AnsiUpper 

_16AnsiUpperBuff 

_ 16BuildCommDCB 

_16CallMsgFilter 

_16ChangeMenu 

_16ClientToScreen 

_16ClipCursor 

_ 16CopyMetaFile 

_16CopyRect 

_16CreateBitmap 

_ 16CreateBitmapIndirect 

_ 16CreateBmshIndirect 

_ 16CreateCursor 

_16CreateDC 

_16CreateDialog 

_ 16CreateDialoglndirect 

_ 16CreateDialogIndirectParam 

_ 16CreateDialogParam 

_ 16CreateDIBitmap 

_ 16CreateEllipticRgnIndirec t 

_16CreateFont 

_ 16CreateFontIndirect 

_16CreateIC 

_16CreateIcon 

_ 16CreateMetaFile 

_16CreatePalette 

_ 16CreatePenIndirect 

_ 16CreatePolygonRgn 

_ 16CreatePolyPolygonRgn 

_16CreateRectRgnIndirect 
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16Create Window 
16Create WindowEx 
16DialogBox 
16DialogBoxIndirect 
16DialogBoxIndirectParam 
16DialogBoxParam 
16DispatchMessage 
16DlgDirList 
16DlgDirListComboBox 
16DlgDirSelect 
16DlgDirSelectComboBox 
16DPtoLP 
16DrawFocusRect 
16DrawText 
16EndPaint 

16EnumChild Windows 

16EnumFonts 

16EnumMetaFile 

16EnumObjects 

16EnumProps 

16EnumTaskWindows 

16EnumWindows 

16EqualRect 

16Escape 

16ExtTextOut 

16FillRect 

16FindAtom 

16FindResource 

16FindWindow 

16FrameRect 

16FreeProcInstance 

16Get AtomN ame 

16GetBitmapBits 

16GetCaretPos 

16GetCharWidth 

16GetClassInfo 

16GetClassN ame 

16GetClientRect 

16GetClipboardFormatN ame 

16GetClipBox 

16GetCodeInfo 

16GetCommError 

16GetCommState 

16GetCursorPos 

16GetDIBits 

16GetDlgItemInt 

16GetDlgItemText 

16GetEnvironment 

16GetKeyboardS tate 

16GetKeyN ameT ext 

16GetMenuString 

16GetMetaFile 

16GetModuleFileN ame 

16GetModuleHandle 
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16GetObject 

16GetPaletteEn tries 

16GetPriorityClipboardFormat 

16GetPri vateProfilelnt 

16GetPrivateProfileString 

16GetProc Address 

16GetProfileInt 

16GetProfileString 

16GetProp 

16GetRgnBox 

16GetScrollRange 

16GetSy stemDirectory 

16GetSy stemPaletteEntries 

16GetT abbedT extExtent 

16GetT empFileN ame 

16GetT extExtent 

16GetTextFace 

16GetT extMetrics 

16GetUpdateRect 

16GetWindo wRect 

16GetWindo wsDirectory 

16GetW indo wText 

16Global Add Atom 

16GlobalFind Atom 

16GlobalGet AtomN ame 

16GlobalNotify 

16GrayString 

16InflateRect 

16IntersectRect 

16InvalidateRect 

16InvertRect 

16IsDialogMessage 

16IsRectEmpty 

16LineDDA 

16 Load Accelerators 

16LoadBitmap 

16LoadCursor 

16LoadIcon 

16LoadLibrary 

16LoadMenu 

16LoadMenuIndirec t 

16LoadModule 

16LoadString 

16LPtoDP 

16MakeProcInstance 

16MapDialogRect 

16MessageBox 

160emToAnsi 

160emTo AnsiBuff 

160ffsetRect 

160penComm 

160penFile 

160utputDebugString 

16PlayMetaFileRecord 
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16Polygon 

16Polyline 

16PolyPolygon 

16PtInRect 

16ReadComm 

16RectInRegion 

16RectVisible 

16RegisterClipboardFormat 

16RegisterWindowMessage 

16RemoveFontResource 

16RemoveProp 

16ScreenToClient 

16ScrollDC 

16Scroll Window 

16SetBitmapBits 

16SetCommState 

16SetDIBits 

16SetDIBitsToDevice 

16SetDlgItemText 

16 S e tEn vironment 

16SetKeyboardState 

16SetPalette Entries 

16SetProp 

16SetRect 

16SetRectEmpty 

16SetResourceHandler 

16SetSysColors 

16SetTimer 

16SetWindowsF[ook 

16SetWindowText 

16StretchDIBits 

16T abbedTextOut 

16TextOut 

16ToAscii 

16TrackPopupMenu 

16Translate Accelerator 

16TranslateMDISys Accel 

16TranslateMessage 

16U nhook W indowsPIook 

16UnionRect 

16UnregisterClass 

16ValidateRect 

16WinExec 

16WinHelp 

16WriteComm 

16 WritePrivateProfileString 

16 WriteProfileString 

16_lread 

16_lwrite 
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28 Windows NT Programming Overview 


Windows NT supports both non-windowed character-mode applications and windowed Graphical User 
Interface (GUI) applications. In addition, Windows NT supports Dynamic Link Libraries and applications 
with multiple threads of execution. 

We have supplied all the necessary tools for native development on Windows NT. You can also cross 
develop for Windows NT using either the DOS-hosted compilers and tools, the Windows 95-hosted 
compilers and tools, or the OS/2-hosted compilers and tools. 

Note - If you are on the host with operating system other then 32-bit Windows, you should setup 
INCLUDE environment variable correctly to compile for 32-bit Windows target. 

You can do that by command (DOS, OS/2, Windows 3.x) 

set INCLUDE=%WATCOM%\h;%WATCOM%\h\nt 

or by command (LINUX) 

export INCLUDE=$WATCOM/h:$WATCOM/h/nt 

Testing and debugging of your Windows NT application must be done on Windows NT or Windows 95. 

If you are creating a character-mode application, you may also be interested in a special DOS extender 
from Phar Lap (TNT) that can run your Windows NT character-mode application under DOS. 


28.1 Windows NT Programming Note 

When doing Win32 programming, you should use the /ei and /zp4 options to compile C and C++ code with 
the Open Watcom compilers since this adjusts the compilers to match the default Microsoft compiler 
behaviour. Some Microsoft software relies on the default behaviour of their own compiler regarding the 
treatment of enums and structure packing alignment. 

28.2 Windows NT Character-mode Versus GUI 


Basically, there are two classes of C/C++ applications that can run in a windowed environment like 
Windows NT. 

The first are those C/C++ applications that do not use any of the Win32 API functions; they are strictly 
C/C++ applications that do not rely on the features of a particular operating system. 

• This Application must be created as Windows NT Character-mode Application. 
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The second class of C/C++ applications are those that actually call Win32 API functions directly. These 
are applications that have been tailored for the Win32 operating environment. There can occure two 
application types. 

• First one uses GUI interface then it must be created as Windows NT GUI Application. 

• Second one uses only character console (no GUI) then it must be created as Windows NT 
Character-mode Application 

A subsequent chapters deal with the creation of different application types for Windows NT target. 
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29 Creating Windows NT GUI Applications 


This chapter describes how to compile and link Windows NT GUI applications simply and quickly. In this 
chapter, we look at applications written to exploit the Windows NT Application Programming Interface 
(API). 

We will illustrate the steps to creating Windows NT GUI applications by taking a small sample application 
and showing you how to compile, link, run and debug it. 

29.1 The Sample GUI Application 

To demonstrate the creation of Windows NT GUI applications, we introduce a simple sample program. 

The following example is the "hello" program adapted for Windows. 

♦include <windows.h> 

int PASCAL WinMain( HANDLE hlnstance, HANDLE hPrevInst, 

LPSTR lpCmdLine, int nCmdShow ) 

{ 

MessageBox( NULL, "Hello world", 

"Open Watcora C/C++ for Windows", 

MB_ OK | MB_ TASKMODAL ) ; 

return( 0 ) ; 

} 

The goal of this program is to display the message "Hello world" on the screen. The MessageBox 
Windows API function is used to accomplish this task. We will take you through the steps necessary to 
produce this result. 


29.2 Building and Running the GUI Application 

To compile and link our example program which is stored in the file hello. c, enter the following 
command: 

C>wcl386 -l=nt_ win -bt=nt hello.c 
The typical messages that appear on the screen are shown in the following illustration. 
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C>wcl386 -l=nt_ win -bt=nt hello.c 

Open Watcom C/C++32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

wcc386 hello.c -bt=nt 
Open Watcom C32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 10 lines, included 6500, 0 warnings, 0 errors 

Code size: 41 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows NT windowed executable 


If you examine the current directory, you will find that two files have been created. These are 
hello, obj (the result of compiling hello, c) and hello.exe (the result of linking hello, obj 
with the appropriate Open Watcom C/C++ libraries). 

The resultant Windows NT GUI application HELLO. EXE can now be run under Windows NT. 

29.3 Debugging the GUI Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "hello" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WCL3 8 6 command, this is fairly straightforward. WCL3 8 6 recognizes the Open Watcom 
C/C++ compiler "debug" options and will create the appropriate debug directives for the Open Watcom 
Linker. 

For example, to compile and link the "hello" program with debugging information, the following command 
may be issued. 

C>wcl386 -l=nt_ win -bt=nt -d2 hello.c 
The typical messages that appear on the screen are shown in the following illustration. 
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C>wcl386 -l=nt_ win -bt=nt -d2 hello.c 
Open Watcom C/C++32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

wcc386 hello.c -bt=nt -d2 
Open Watcom C32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 10 lines, included 6500, 0 warnings, 0 errors 

Code size: 66 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows NT windowed executable 


The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom C/C++ compiler. WCL3 8 6 will make sure that this debugging information is included in the 
executable file that is produced by the linker. 

The "Code size" value is larger than in the previous example since selection of the "d2" option results in 
fewer code optimizations by default. You can request more optimization by specifying the appropriate 
options. However, you do so at the risk of making it more difficult for yourself to determine the 
relationship between the object code and the original source language code. 

To request the Open Watcom Debugger to assist in debugging the application, select the Open Watcom 
Debugger icon. It would be too ambitious to describe the debugger in this introductory chapter so we refer 
you to the book entitled Open Watcom Debugger User’s Guide. 
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30 Creating Windows NT Character-mode 
Applications 


This chapter describes how to compile and link Windows NT Character-mode applications simply and 
quickly. In this chapter, we look at applications written to exploit the Windows NT Application 
Programming Interface (API). 

We will illustrate the steps to creating Windows NT Character-mode applications by taking a small sample 
application and showing you how to compile, link, run and debug it. 

30.1 The Sample Character-mode Application 

To demonstrate the creation of Windows NT Character-mode applications, we introduce a simple sample 
program. The following example is the "hello" program adapted for Windows. 

♦include <stdio.h> 

void main() 

{ 

printf ( "Hello world\n" ); 

} 

The goal of this program is to display the message "Hello world" on the screen. The C library printf 
routine is used to accomplish this task. We will take you through the steps necessary to produce this result. 

30.2 Building and Running the Character-mode Application 

To compile and link our example program which is stored in the file hello. c, enter the following 
command: 

C>wcl386 -l=nt -bt=nt hello.c 
The typical messages that appear on the screen are shown in the following illustration. 
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C>wcl386 -l=nt -bt=nt hello.c 

Open Watcom C/C++32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

wcc386 hello.c -bt=nt 
Open Watcom C32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 10 lines, included 6500, 0 warnings, 0 errors 

Code size: 41 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows NT Character-mode executable 


If you examine the current directory, you will find that two files have been created. These are 
hello, obj (the result of compiling hello, c) and hello.exe (the result of linking hello, obj 
with the appropriate Open Watcom C/C++ libraries). 

The resultant Windows NT Character-mode application HELLO. EXE can now be run under Windows NT. 

30.3 Debugging the Character-mode Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "hello" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WCL3 8 6 command, this is fairly straightforward. WCL3 8 6 recognizes the Open Watcom 
C/C++ compiler "debug" options and will create the appropriate debug directives for the Open Watcom 
Linker. 

For example, to compile and link the "hello" program with debugging information, the following command 
may be issued. 

C>wcl386 -l=nt -bt=nt -d2 hello.c 
The typical messages that appear on the screen are shown in the following illustration. 
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C>wcl386 -l=nt -bt=nt -d2 hello.c 

Open Watcom C/C++32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

wcc386 hello.c -bt=nt -d2 
Open Watcom C32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 10 lines, included 6500, 0 warnings, 0 errors 

Code size: 66 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating a Windows NT Character-mode executable 


The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom C/C++ compiler. WCL3 8 6 will make sure that this debugging information is included in the 
executable file that is produced by the linker. 

The "Code size" value is larger than in the previous example since selection of the "d2" option results in 
fewer code optimizations by default. You can request more optimization by specifying the appropriate 
options. However, you do so at the risk of making it more difficult for yourself to determine the 
relationship between the object code and the original source language code. 

To request the Open Watcom Debugger to assist in debugging the application, select the Open Watcom 
Debugger icon. It would be too ambitious to describe the debugger in this introductory chapter so we refer 
you to the book entitled Open Watcom Debugger User’s Guide. 
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31 Windows NT Multi-threaded Applications 


This chapter describes how to create multi-threaded applications. A multi-threaded application is one 
whose tasks are divided among several threads of execution. A process is an executing application and the 
resources it uses. A thread is the smallest unit of execution within a process. Each thread has its own stack 
and a set of machine registers and shares all resources with its parent process. The path of execution of one 
thread does not affect that of another; each thread is an independent entity. 

Typically, an application has a single thread of execution. In this type of application, all tasks, once 
initiated, are completed before the next task begins. In contrast, tasks in a multi-threaded application can 
be performed concurrently since more than one thread is executing at once. For example, each thread may 
be designed to perform a separate task. 

31.1 Programming Considerations 

Since a multi-threaded application consists of many threads of execution, there are a number of issues that 
you must consider. 

Since threads share the resources of its parent, it may be necessary to serialize access to these resources. 

For example, if your application has a function that displays information on the console and is used by all 
threads, it is necessary to allow only one thread to use that function at any time. That is, once a thread calls 
that function, the function should ensure that no other thread displays information until all information for 
the initial thread has been displayed. An example of such a function is the print f library function. 

Another issue that must be considered when creating multi-threaded applications is global variables. If you 
have global variables that contain thread-specific information, there must be an instance of each global 
variable for each thread. An example of such a variable is the errno global variable defined in the 
run-time libraries. If an error condition was created by a thread, you would not want it to affect the 
execution of other threads. Therefore, each thread should contain its own instance of this variable. 

31.2 Creating Threads 

Each application initially contains a single thread. The run-time libraries contain two functions that create 
and terminate threads of execution. The function _ beginthread creates a thread of execution and the 
function _ endthread ends a thread of execution. The macro_ threadid can be used to determine the 
current thread identifier. 
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WARNING! If any thread calls a library function, you must use the _ beginthread function to 
create the thread. Do not use the CreateThread API function. 


31.2.1 Creating a New Thread 

The _ beginthread function creates a new thread. It is defined as follows. 

unsigned long _ beginthread ( void (*start_ address) (void *), 

unsigned stack_ size, 
void *arglist); 

where description: 

start_address is the address of the function that will be called when the newly created thread is executed. 

When the thread returns from that function, the thread will be terminated. Note that a call 
to the _ endthread function will also terminate the thread. 

stack_size specifies the size of the stack to be allocated by the operating system for the new thread. 
The stack size should be a multiple of 4K. 

arglist is passed as an argument to the function specified by start_ address . If no argument 

is required, a value of NULL can be specified. 

If a new thread is successfully created, the thread identifier of the new thread is returned. Otherwise, a 
value of -1 is returned. 

The header file process . h contains the definition of the _ beginthread function. 

Another thread related function for Windows NT is _ beginthreadex. See the Open Watcom C 
Library Reference for more information. 

31.2.2 Terminating the Current Thread 

The _ endthread function terminates the current thread. It is defined as follows, 
void _ endthread ( void ) 

The header file process . h contains the definition of the _ endthread function. 

31.2.3 Getting the Current Thread Identifier 

The _ threadid macro can be used to determine the current thread identifier. It is defined as follows. 

int *_threadid(void) ; 

#define _threadid (_threadid()) 

The header file stddef . h contains the definition of the _ threadid macro. 
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31.3 A Multi-threaded Example 

Let us create a simple multi-threaded application. 

♦include <process.h> 

♦include <stdio.h> 

♦include <stddef.h> 

♦include <windows.h> 

static volatile int NumThreads; 

static volatile int HoldThreads; 

CRITICAL_ SECTION CriticalSection; 

♦ define NUM_ THREADS 5 

♦define STACK_ SIZE 8192 

static void a_ thread( void *arglist ) 

/***********************************/ 

{ 

while( HoldThreads ) { 

Sleep( 1 ); 

} 

printf ( "Hi from thread %d\n", *_ threadid ); 

EnterCriticalSection ( sCriticalSection ); 

—NumThreads; 

LeaveCriticalSection ( SCriticalSection ); 

_ endthread(); 

} 

int main( void ) 

/**************/ 

{ 

int i; 

printf( "Initial thread id = %d\n", *_ threadid ); 

NumThreads = 0; 

HoldThreads = 1; 

InitializeCriticalSection( SCriticalSection ) ; 

/* initial thread counts as 1 */ 

for ( i = 2; i <= NUM_ THREADS; ++i ) { 

if ( _ beginthread ( a_ thread, STACK_ SIZE, NULL ) == -1 ) { 

printf( "creation of thread %d failed\n", i ); 

} else { 

++NumThreads; 

} 

} 

HoldThreads = 0; 

while( NumThreads != 0 ) { 

Sleep ( 1 ); 

} 

DeleteCriticalSection ( SCriticalSection ); 
return( 0 ) ; 

} 

Note: 

1. In the function a_ thread,EnterCriticalSection and LeaveCriticalSection 
are called when we modify the variable NumThreads . This ensures that the action of 
extracting the value of NumThreads from memory, incrementing the value, and storing the 
new result into memory, occurs without interruption. If these functions were not called, it would 
be possible for two threads to extract the value of NumThreads from memory before an update 
occurred. 

Let us assume that the file mthread. c contains the above example. Before compiling the file, make sure 
that the WATCOM environment variable is set to the directory in which you installed Open Watcom 
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C/C++. Also, the INCLUDE environment variable must include the \watcom\h\nt and \watcom\h 
directories ("YWATCOM" is the directory in which Open Watcom C/C++ was installed). 

We can now compile and link the application by issuing the following command. 

C:\>wcl386 -bt=nt -bm -l=nt mthread 

The "bm" option must be specified since we are creating a multi-threaded application. If your 
multi-threaded application contains more than one module, each module must be compiled using the "bm" 
switch. 

The "1" option specifies the target system for which the application is to be linked. The system name nt is 
defined in the file wl system. Ink which is located in the "BINW" subdirectory of the directory in which 
you installed Open Watcom C/C++. 

The multi-threaded application is now ready to be run. 
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32 Windows NT Dynamic Link Libraries 


A dynamic link library, like a standard library, is a library of functions. When an application uses functions 
from a standard library, the library functions referenced by the application become part of the executable 
module. This form of linking is called static linking. When an application uses functions from a dynamic 
link library, the library functions referenced by the application are not included in the executable module. 
Instead, the executable module contains references to these functions which are resolved when the 
application is loaded. This form of linking is called dynamic linking. 

Let us consider some of the advantages of using dynamic link libraries over standard libraries. 

1. Functions in dynamic link libraries are not linked into your program. Only references to the 
functions in dynamic link libraries are placed in the program module. These references are 
called import definitions. As a result, the linking time is reduced and disk space is saved. If 
many applications reference the same dynamic link library, the saving in disk space can be 
significant. 

2. Since program modules only reference dynamic link libraries and do not contain the actual 
executable code, a dynamic link library can be updated without re-linking your application. 

When your application is executed, it will use the updated version of the dynamic link library. 

3. Dynamic link libraries also allow sharing of code and data between the applications that use 
them. If many applications that use the same dynamic link library are executing concurrently, 
the sharing of code and data segments improves memory utilization. 

32.1 Creating Dynamic Link Libraries 

Once you have developed the source for a library of functions, a number of steps are required to create a 
dynamic link library containing those functions. 

First, you must compile your source using the "bd" compiler option. This option tells the compiler that the 
module you are compiling is part of a dynamic link library. Once you have successfully compiled your 
source, you must create a linker directive file that describes the attributes of your dynamic link library. The 
following lists the most common linker directives required to create a dynamic link library. 

1. The "SYSTEM" directive is used to specify that a dynamic link library is to be created. 

2. The "EXPORT" directive is used to to specify which functions in the dynamic link library are to 
be exported. 

Specifying exports in the source code 

The "EXPORT" directive need not be used when the symbols to be exported are 

declared with the_declspec ( dllexport ) modifier in the source code. 

Such symbols are exported automatically, through special records inserted into 
the object files by the compiler. 
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Exporting C++ symbols and classes 

Symbols exported via the "EXPORT" directive have to be entered in their 
mangled form. This makes it rather awkward to export C++ functions, classes or 
global objects. These symbols also often reference other compiler-generated 
symbols (invisible to the user) that need be exported together with the 

class/object. Using the_ declspec ( dllexport ) method of exporting 

symbols is the preferred solution. 

3. The "OPTION" directive is used to specify attributes such as the name of the dynamic link 
library and how to allocate the automatic data segment when the dynamic link library is 
referenced. 

4. The "SEGMENT" directive is used to specify attributes of segments. For example, a segment 
may be read-only or read-write. 

Once the dynamic link library is created, you must allow access to the dynamic link library to client 
applications that wish to use it. This can be done by creating an impoit library for the dynamic link library 
or creating a linker directive file that contains "IMPORT" directives for each of the entry points in the 
dynamic link library. 

32.2 Creating a Sample Dynamic Link Library 

Let us now create a dynamic link library using the following example. 

♦include <stdio.h> 

#include <windows.h> 

#if defined(_cplusplus) 

#define EXPORTED extern "C" _declspec( dllexport ) 

#else 

#define EXPORTED _declspec( dllexport ) 

#endif 

DWORD Tlslndex; /* Global Thread Local Storage index */ 

/* Error checking should be performed in following code */ 

BOOL APIENTRY LibMain( HANDLE hinstDLL, 

DWORD fdwReason, 

LPVOID lpvReserved ) 

{ 

switch( fdwReason ) { 

case DLL_ PROCESS_ ATTACH: 

/* do process initialization */ 

/* create TLS index */ 

Tlslndex = TlsAllocO; 
break; 

case DLL_ THREAD_ ATTACH: 

/* do thread initialization */ 

/* allocate private storage for thread */ 

/* and save pointer to it */ 

TlsSetValue( Tlslndex, malloc(200) ); 
break; 
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case DLL_ THREAD_ DETACH: 

/* do thread cleanup */ 

/* get the TLS value and free associated memory */ 

free( TlsGetValue( Tlslndex ) ) ; 

break; 

case DLL_ PROCESS_ DETACH: 

/* do process cleanup */ 

/* free TLS index */ 

TlsFree ( Tlslndex ); 
break; 

} 

return( 1 ); /* indicate success */ 

/* returning 0 indicates initialization failure */ 


EXPORTED void dll_ entry_ 1 ( void ) 

{ 

printf ( "Hi from dll entry #l\n" ); 

} 


EXPORTED void dll_ entry_ 2 ( void ) 

{ 

printf ( "Hi from dll entry #2\n" ); 

} 


Arguments: 

hinstDLL This is a handle for the DLL. It can be used as a argument to other functions such as 
GetModuleFileName. 

fdwReason This argument indicates why LibMain is being called. It can have one of the following 
values: 

Value Meaning 

DLL_PROCESS_ATTACH This value indicates that the DLL is attaching to the address 
space of the current process as a result of the process starting up or as a 
result of a call to LoadLibrary. A DLL can use this opportunity to 
initialize any instance data or to use the TlsAlloc function to allocate a 
Thread Local Storage (TLS) index. 

During initial process startup or after a call to LoadLibrary, the 
operating system scans the list of loaded DLLs for the process. For each 
DLL that has not already been called with the DLL_ PROCESS_ ATTACH 
value, the system calls the DLL’s LibMain entry-point. This call is made 
in the context of the thread that caused the process address space to change, 
such as the primary thread of the process or the thread that called 
LoadLibrary. 

DLL_THREAD_ATTACH This value indicates that the current process is creating a new 
thread. When this occurs, the system calls the LibMain entry-point of all 
DLLs currently attached to the process. The call is made in the context of 
the new thread. DLLs can use this opportunity to initialize a Thread Local 
Storage (TLS) slot for the thread. A thread calling the DLL’s LibMain 
with the DLL_ PROCESS_ ATTACH value does not calLibMain with the 
DLL_ THREAD_ ATTACH value. Note thaLibMain is called with this 
value only by threads created after the DLL is attached to the process. 
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When a DLL is attached by LoadLibrary, existing threads do not call 
the LibMain entry-point of the newly loaded DLL. 

DLL_THREAD_DETACH This value indicates that a thread is exiting normally. If the 
DLL has stored a pointer to allocated memory in a TLS slot, it uses this 
opportunity to free the memory. The operating system calls the LibMain 
entry-point of all currently loaded DLLs with this value. The call is made 
in the context of the exiting thread. There are cases in which LibMain is 
called for a terminating thread even if the DLL never attached to the thread. 
For example, LibMain is never called with the DLL_ THREAD_ ATTACH 
value in the context of the thread in either of these two situations: 

• The thread was the initial thread in the process, so the system called 
LibMain with the DLL_ PROCESS_ ATTACH value. 

• The thread was already running when a call to the LoadLibrary 
function was made, so the system never called LibMain for it. 

DLL_PROCESS_DETACH This value indicates that the DLL is detaching from the 
address space of the calling process as a result of either a normal 
termination or of a call to FreeLibrary. The DLL can use this 
opportunity to call the TlsFree function to free any TLS indices 
allocated by using TlsAlloc and to free any thread local data. When a 
DLL detaches from a process as a result of process termination or as a 
result of a call to FreeLibrary, the operating system does not call the 
DLL’s LibMain with the DLL_ THREAD_ DETACH value for the 
individual threads of the process. The DLL is only given 
DLL_ PROCESS_ DETACH notification. DLLs can take this opportunity to 
clean up all resources for all threads attached and known to the DLL. 

IpvReserved This argument specifies further aspects of DLL initialization and cleanup. If f dwReason 
is DLL_ PROCESS_ ATTACH,lpvReserved is NULL for dynamic loads and 
non-NULL for static loads. If f dwReason is DLL_ PROCESS_ DETACH, 
IpvReserved is NULL if LibMain has been called by using FreeLibrary and 
non-NULL if LibMain has been called during process termination. 

Return Value When the system calls the LibMain function with the DLL_ PROCESS_ ATTACH value, 
the function returns TRUE (1) if initialization succeeds or FALSE (0) if initialization fails. 

If the return value is FALSE (0) when LibMain is called because the process uses the 
LoadLibrary function, LoadLibrary returns NULL. 

If the return value is FALSE (0) when LibMain is called during process initialization, the 
process terminates with an error. To get extended error information, call 
GetLastError. 

When the system calls LibMain with any value other than DLL_ PROCESS_ ATTACH, 
the return value is ignored. 

Assume the above example is contained in the file dll samp. c . We can compile the file using the 

following command. Note that we must specify the "bd" compiler option. 

C:\>wcc386 -bd dllsamp 
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Before we can link our example, we must create a linker directive file that describes the attributes and entry 
points of our dynamic link library. The following is a linker directive file, called dllsamp.lnk, that 
can be used to create the dynamic link library. 

system nt_ dll initinstance terminstance 
export dll_ entry_ 1_ 
export dll_ entry_ 2_ 
file dllsamp 

Notes: 

1. The "SYSTEM" directive specifies that we are creating a Windows NT dynamic link library. 

2. When a dynamic link library uses the Open Watcom C/C++ run-time libraries, an automatic data 
segment is created each time a new process accesses the dynamic link library. For this reason, 
initialization code must be executed when a process accesses the dynamic link library for the 
first time. To achieve this, "INITINSTANCE" must be specified in the "SYSTEM" directive. 
Similarly, "TERMINSTANCE" must be specified so that the termination code is executed when 
a process has completed its access to the dynamic link library. If the Open Watcom C/C++ 
run-time libraries are not used, these options are not required. 

3. The "EXPORT" directive specifies the entry points into the dynamic link library. Note that the 
names specified in the "EXPORT" directive are appended with an underscore. This is the 
default naming convention used when compiling using the register-based calling convention. No 
underscore is required when compiling using the stack-based calling convention. 

We can now create our dynamic link library by issuing the following command. 

C:\>wlink @dllsamp 

A file called dllsamp. dll will be created. 

32.3 Using Dynamic Link Libraries 

It is assumed that all symbols imported by a client application were declared with a_ declspec ( 

dllimport ) modifier when the client application was compiled. At the link stage we have to tell the 
linker which dynamic libraries the client application should link to. Once we have created a dynamic link 
library, we must allow other applications to access the functions available in the dynamic link library. 

There are two ways to achieve this. 

The first method is to create a linker directive file which contains an "IMPORT" directive for all entry 
points in the dynamic link library. The "IMPORT" directive provides the name of the entry point and the 
name of the dynamic link library. When creating an application that references a function in the dynamic 
link library, this linker directive file would be included as part of the linking process that created the 
application. 

The second method is to use import libraries. An import library is a standard library that is created from a 
dynamic link library by using the Open Watcom Library Manager. It contains object modules that describe 
the entry points in a dynamic link library. The resulting import library can then be specified in a 
"LIBRARY" directive in the same way one would specify a standard library. 

Using an import library is the preferred method of providing references to functions in dynamic link 
libraries. When a dynamic link library is modified, typically the impoit library corresponding to the 
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modified dynamic link library is updated to reflect the changes. Hence, any directive file that specifies the 
import library in a "LIBRARY" directive need not be modified. However, if you are using "IMPORT" 
directives, you may have to modify the "IMPORT" directives to reflect the changes in the dynamic link 
library. 

Let us create an import library for our sample dynamic link library we created in the previous section. We 
do this by issuing the following command. 

C:\>wlib dllsamp +dllsamp.dll 

A standard library called dllsamp. lib will be created. 

Suppose the following sample program, contained in the file dlltest. c, calls the functions from our 
sample dynamic link library. 

♦include <stdio.h> 

♦include <process.h> 

♦if defined(_cplusplus) 

♦define IMPORTED extern "C" _declspec( dllimport ) 

♦else 

♦define IMPORTED _declspec( dllimport ) 

♦endif 

IMPORTED void dll_ entry_ 1 ( void ) ; 

IMPORTED void dll_ entry_ 2 ( void ) ; 

♦define STACK_ SIZE 8192 

static void thread ( void *arglist ) 

{ 

printf ( "Hi from thread\n" ); 

_ endthread(); 

} 

int main( void ) 

{ 

unsigned long tid; 
dll_ entry_ 1 () ; 

tid = _ beginthread ( thread, STACK_ SIZE, NULL ); 
dll_ entry_ 2 () ; 
return( 0 ); 

} 


We can compile and link our sample application by issuing the following command. 

C:\>wcl386 -bm -l=nt dlltest dllsamp.lib 

If we had created a linker directive file of "IMPORT" directives instead of an import library for the 
dynamic link library, the linker directive file, say dllimps . Ink, would be as follows. 

import dll_ entry_ 1_ dllsamp 
import dll_ entry_ 2_ dllsamp 

Note that the names specified in the "IMPORT" directive are appended with an underscore. This is the 
default naming convention used when compiling using the register-based calling convention. No 
underscore is required when compiling using the stack-based calling convention. 

To compile and link our sample application, we would issue the following command. 

C:\>wcl386 -bm -l=nt dlltest -"Sdllimps" 
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32.4 The Dynamic Link Library Data Area 

The Open Watcom C/C++ 32-bit run-time library does not support the general case operation of DLLs in 
an execution environment where there is only one instance of the DATA segment (DGROUP) for that 
DLL. 

There are two cases that can lead to a DLL executing with only one instance of the DGROUP. 

1. DLLs linked for 32-bit OS/2 without the MANY AUTODATA option. 

2. DLLs linked for the Win32 API and executing under Win32s. 

In these cases the run-time library startup code detects that there is only one instance of the DGROUP when 
a second process attempts to attach to the DLL. At that point, it issues a diagnostic for the user and then 
notifies the operating system that the second process cannot attach to the DLL. 

Developers who require DLLs to operate when there is only one instance of the DGROUP can suppress the 
function which issues the diagnostic and notifies the operating system that the second process cannot attach 
to the DLL. 

Doing so requires good behaviour on the part of processes attaching to the DLL. This good behaviour 
consists primarily of ensuring that the first process to attach to the DLL is also the last process to detach 
from the DLL thereby ensuring that the DATA segment is not released back to the free memory pool. 

To suppress the function which issues the diagnostic and notifies the operating system that the second 
process cannot attach to the DLL, the developer must provide a replacement entry point with the following 
prototype: 

int_disallow_ single_ dgroup ( int ) ; 

This function should return zero to indicate that the detected single copy of the DATA segment is allowed. 
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33 Creating Windows NT POSIX Applications 


This chapter describes how to compile and link POSIX applications for Windows NT. There are a number 
of issues to consider. 

1. Open Watcom does not provide its own POSIX libraries. You must use those included with the 
Microsoft Win32 SDK. They are libcpsx. lib, psxdll. lib and psxrtl. lib . If you 
installed the Win32 SDK component when you installed the Open Watcom software, you will 
find these libraries in the %WATCOM%\lib386\nt directory. 

2. Since you will be using Microsoft POSIX libraries compiled by the Microsoft compiler, you 

must follow the calling conventions used by Microsoft (i.e., the_cdecl convention). The 

Open Watcom compiler can generate these calling conventions provided that the POSIX library 
routines are all properly prototyped. 

3. Open Watcom does not provide its own header files for use with the Microsoft POSIX libraries. 
The Microsoft Win32 SDK includes only a subset of the headers required for calling the POSIX 
library routines. If you installed the Win32 SDK component when you installed the Open 
Watcom software, you will find these headers in the %WATCOM%\sdk\posix\h and 
%WATCOM%\sdk\posix\h\sys directories. Take a look at these directories to see what is 
and what is not included. 

4. If you have the Microsoft compiler, then you will likely have access to the missing header files. 
If you do not have the Microsoft compiler, then you will have to define prototypes for any of the 
POSIX library routines that you use for which no prototypes are defined in any of the POSIX 
header files. 

5. There is one exception to the generation of the_cdecl calling convention for appropriately 

prototyped functions. This is the main function. Since many Microsoft sample programs 

inappropriately declare the main function as_ cdecl, it was necessary to make a special 

case in the Open Watcom compilers to ignore the_ cdecl attribute when used for this entry 

point. To work around this problem, a special pragma is used. This is shown in the following 
example. 

6. Since we are going to use the Microsoft POSIX libraries rather than the Open Watcom libraries, 
we will use the "zl" compile option to instruct the Open Watcom compiler not to include 
references to Open Watcom libraries in the object files. 

To illustrate the creation of a POSIX application, we will use a simple example. This program displays an 
identifying banner and then displays its arguments one at a time. 

Example: 
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[POSIXSMP.C] 

♦include <unistd.h> 

// The Win32 SDK doesn't provide a complete set of 
// headers for the libraries (e.g., no stdio.h). 

extern int_cdecl printf( char *, ... ) ; 

// Note: the "_cdecl" attribute is ignored for main() . 

int _cdecl main( int argc, char **argv ) 

{ 

int i; 

printf( "POSIX sample program\n" ) ; 
for( i = 0 ; i < argc ; i++ ) { 

printf( "%d: %s\n", i, argv[i] ); 

} 

return 0; 

} 

// Since the "_cdecl" attribute is ignored, 

// make sure that parms go on the stack for main 
// and that main gets the _ in the right place by 
// using a pragma to do so. 

♦pragma aux main *" parm []; 

// The compiler emits references to these symbols, 

// so make sure they get defined here to prevent 
// unresolved references. 

int _ cstart_ ; 

♦pragma aux _ cstart_ 

int_argc; 

♦pragma aux _argc 

The example program illustrates some of the special considerations required for using the Microsoft POSIX 
libraries rather than the Open Watcom libraries. There are also some special link time issues and these are 
addressed in the following sample "makefile". 

Example: 

[MAKEFILE] 

posixsmp.exe : posixsmp.c posix.add makefile, 
set nt_ include= 

set include=$(%watcom)\sdk\posix\h;$(%watcom)\sdk\posix\h\sys 
wcc386 —bt=nt -oaxt -zl posixsmp.c 

wlink @posix.add file posixsmp sys nt_ posix option map 

posix.add : 

%create posix.add 

%append posix.add system begin nt_ posix 

%append posix.add option osname='Windows NT character-mode posix' 

%append posix.add libpath %WATCOM%\lib386\nt 
%append posix.add option nodefaultlib 

%append posix.add option start=_PosixProcessStartup 

%append posix.add lib { libcpsx.lib psxrtl.lib psxdll.lib } 

%append posix.add format windows nt A 
%append posix.add runtime posix 
%append posix.add end 
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A new "nt_posix" system is defined in the posix. add file. This file is generated automatically by the 
makefile. 

That is about all there is to creating a Windows NT POSIX application. One final note - make sure when 

using the Microsoft headers that all the library routines that you use are declared as_cdecl otherwise 

your application will not run correctly. 
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34 Creating 16-bit OS/21.x Applications 


An OS/2 application can be one of the following; a fullscreen application, a PM-compatible application, or 
a Presentation Manager application. A fullscreen application runs in its own screen group. A 
PM-compatible application will run in an OS/2 fullscreen environment or in a window in the Presentation 
Manager screen group but does not take direct advantage of menus, mouse or other features available in the 
Presentation Manager. A Presentation Manager application has full access to the complete set of 
user-interface tools such as menus, icons, scroll bars, etc. 

This chapter deals with the creation of OS/2 fullscreen applications. For information on creating 
Presentation Manager applications, refer to the section entitled "Programming for OS/2 Presentation 
Manager" on page 257. 

We will illustrate the steps to creating 16-bit OS/2 1.x applications by taking a small sample application 
and showing you how to compile, link, run and debug it. 

34.1 The Sample Application 

To demonstrate the creation of 16-bit OS/2 1.x applications using command-line oriented tools, we 
introduce a simple sample program. For our example, we are going to use the famous "hello" program. 

♦include <stdio.h> 

void main() 

{ 

printf ( "Hello world\n" ); 

1 

The C++ version of this program follows: 

♦include <iostream.h> 

void main() 

{ 

cout << "Hello world" << endl; 

} 

The goal of this program is to display the message "Flello world" on the screen. The C version uses the C 
library printf routine to accomplish this task. The C++ version uses the "iostream" library to accomplish 
this task. We will take you through the steps necessary to produce this result. 
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34.2 Building and Running the Sample OS/21.x Application 

To compile and link our example program which is stored in the file hello. c, enter the following 
command: 

[C:\]wcl -l=os2 hello.c 

The typical messages that appear on the screen are shown in the following illustration. 

[C:\]wcl -l=os2 hello.c 

Open Watcom C/C++16 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
wcc hello.c 

Open Watcom Cl6 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 6 lines, included 155, 0 warnings, 0 errors 

Code size: 17 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating an OS/2 16-bit executable 


Provided that no errors were encountered during the compile or link phases, the "hello" program may now 
be run. 

[C:\]hello 
Hello world 

If you examine the current directory, you will find that two files have been created. These are 
hello, obj (the result of compiling hello, c) and hello.exe (the result of linking hello, obj 
with the appropriate Open Watcom C/C++ libraries). It is hello . exe that is run by OS/2 when you enter 
the "hello" command. 


34.3 Debugging the Sample OS/21.x Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "hello" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WCL command, this is fairly straightforward. WCL recognizes the Open Watcom C/C++ 
compiler "debug" options and will create the appropriate debug directives for the Open Watcom Linker. 

For example, to compile and link the "hello" program with debugging information, the following command 
may be issued. 

[C:\]wcl -l=os2 -d2 hello.c 
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The typical messages that appear on the screen are shown in the following illustration. 

[C:\]wcl -l=os2 -d2 hello.c 

Open Watcom C/C++16 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
wcc hello.c -d2 

Open Watcom Cl6 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 6 lines, included 155, 0 warnings, 0 errors 

Code size: 23 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating an OS/2 16-bit executable 


The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom C/C++ compiler. WCL will make sure that this debugging information is included in the 
executable file that is produced by the linker. 

The "Code size" value is larger than in the previous example since selection of the "d2" option results in 
fewer code optimizations by default. You can request more optimization by specifying the appropriate 
options. However, you do so at the risk of making it more difficult for yourself to determine the 
relationship between the object code and the original source language code. 

For OS/2, you should also include the BINP \DLL directory in the "LIBPATH" directive of the system 
configuration file CONFIG. SYS . It contains the Open Watcom Debugger Dynamic Link Libraries 
(DLLs). 


Example: 

libpath=c:\watcom\binp\dll 

To request the Open Watcom Debugger to assist in debugging the application, the following command may 
be issued. 

[C:\]wd hello 

It would be too ambitious to describe the debugger in this introductory chapter so we refer you to the book 
entitled Open Watcom Debugger User’s Guide. 


Debugging the Sample OS/2 1.x Application 241 




OS/2 Programming Guide 


242 Debugging the Sample OS/21.x Application 




35 Creating 32-bit OS/2 Applications 


An OS/2 application can be one of the following; a fullscreen application, a PM-compatible application, or 
a Presentation Manager application. A fullscreen application runs in its own screen group. A 
PM-compatible application will run in an OS/2 fullscreen environment or in a window in the Presentation 
Manager screen group but does not take direct advantage of menus, mouse or other features available in the 
Presentation Manager. A Presentation Manager application has full access to the complete set of 
user-interface tools such as menus, icons, scroll bars, etc. 

This chapter deals with the creation of OS/2 fullscreen applications. For information on creating 
Presentation Manager applications, refer to the section entitled "Programming for OS/2 Presentation 
Manager" on page 257. 

We will illustrate the steps to creating 32-bit OS/2 applications by taking a small sample application and 
showing you how to compile, link, run and debug it. 

35.1 The Sample Application 

To demonstrate the creation of 32-bit OS/2 applications using command-line oriented tools, we introduce a 
simple sample program. For our example, we are going to use the famous "hello" program. 

♦include <stdio.h> 

void main() 

{ 

printf ( "Hello world\n" ); 

1 

The C++ version of this program follows: 

♦include <iostream.h> 

void main() 

{ 

cout << "Hello world" << endl; 

} 

The goal of this program is to display the message "Flello world" on the screen. The C version uses the C 
library printf routine to accomplish this task. The C++ version uses the "iostream" library to accomplish 
this task. We will take you through the steps necessary to produce this result. 
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35.2 Building and Running the Sample OS/2 Application 

To compile and link our example program which is stored in the file hello. c, enter the following 
command: 

[C:\]wcl386 -1=os2v2 hello.c 

The typical messages that appear on the screen are shown in the following illustration. 

[C:\]wcl386 -1=os2v 2 hello.c 

Open Watcom C/C++32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 
wcc386 hello.c 

Open Watcom C32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 6 lines, included 174, 0 warnings, 0 errors 

Code size: 24 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating an OS/2 32-bit executable 


Provided that no errors were encountered during the compile or link phases, the "hello" program may now 
be run. 

[C:\]hello 
Hello world 

If you examine the current directory, you will find that two files have been created. These are 
hello, obj (the result of compiling hello, c) and hello.exe (the result of linking hello, obj 
with the appropriate Open Watcom C/C++ libraries). It is hello . exe that is run by OS/2 when you enter 
the "hello" command. 


35.3 Debugging the Sample OS/2 Application 

Let us assume that you wish to debug your application in order to locate an error in programming. In the 
previous section, the "hello" program was compiled with default compile and link options. When 
debugging an application, it is useful to refer to the symbolic names of routines and variables. It is also 
convenient to debug at the source line level rather than the machine language level. To do this, we must 
direct both the compiler and linker to include additional debugging information in the object and executable 
files. Using the WCL3 8 6 command, this is fairly straightforward. WCL3 8 6 recognizes the Open Watcom 
C/C++ compiler "debug" options and will create the appropriate debug directives for the Open Watcom 
Linker. 

For example, to compile and link the "hello" program with debugging information, the following command 
may be issued. 
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[C:\]wcl386 -1=os2v2 -d2 hello.c 

The typical messages that appear on the screen are shown in the following illustration. 

[C:\]wcl386 -1=os2v2 -d2 hello. c 

Open Watcom C/C++32 Compile and Link Utility 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

wcc386 hello.c -d2 
Open Watcom C32 Optimizing Compiler 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1984-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details. 

hello.c: 6 lines, included 174, 0 warnings, 0 errors 

Code size: 45 

Open Watcom Linker 

Copyright (c) 2002-2015 the Open Watcom Contributors. All Rights Reserved. 
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved. 

Source code is available under the Sybase Open Watcom Public License. 

See http://www.openwatcom.org/ for details, 
loading object files 
searching libraries 

creating an OS/2 32-bit executable 


The "d2" option requests the maximum amount of debugging information that can be provided by the Open 
Watcom C/C++ compiler. WCL3 8 6 will make sure that this debugging information is included in the 
executable file that is produced by the linker. 

The "Code size" value is larger than in the previous example since selection of the "d2" option results in 
fewer code optimizations by default. You can request more optimization by specifying the appropriate 
options. However, you do so at the risk of making it more difficult for yourself to determine the 
relationship between the object code and the original source language code. 

To request the Open Watcom Debugger to assist in debugging the application, the following command may 
be issued. 

[C:\]wd hello 

It would be too ambitious to describe the debugger in this introductory chapter so we refer you to the book 
entitled Open Watcom Debugger User’s Guide. 
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36 OS/2 2.x Multi-threaded Applications 


This chapter describes how to create multi-threaded applications. A multi-threaded application is one 
whose tasks are divided among several threads of execution. A process is an executing application and the 
resources it uses. A thread is the smallest unit of execution within a process. Each thread has its own stack 
and a set of machine registers and shares all resources with its parent process. The path of execution of one 
thread does not affect that of another; each thread is an independent entity. 

Typically, an application has a single thread of execution. In this type of application, all tasks, once 
initiated, are completed before the next task begins. In contrast, tasks in a multi-threaded application can 
be performed concurrently since more than one thread is executing at once. For example, each thread may 
be designed to perform a separate task. 

36.1 Programming Considerations 

Since a multi-threaded application consists of many threads of execution, there are a number of issues that 
you must consider. 

Since threads share the resources of its parent, it may be necessary to serialize access to these resources. 

For example, if your application has a function that displays information on the console and is used by all 
threads, it is necessary to allow only one thread to use that function at any time. That is, once a thread calls 
that function, the function should ensure that no other thread displays information until all information for 
the initial thread has been displayed. An example of such a function is the print f library function. 

Another issue that must be considered when creating multi-threaded applications is global variables. If you 
have global variables that contain thread-specific information, there must be an instance of each global 
variable for each thread. An example of such a variable is the errno global variable defined in the 
run-time libraries. If an error condition was created by a thread, you would not want it to affect the 
execution of other threads. Therefore, each thread should contain its own instance of this variable. 

36.2 Creating Threads 

Each application initially contains a single thread. The run-time libraries contain two functions that create 
and terminate threads of execution. The function _ beginthread creates a thread of execution and the 
function _ endthread ends a thread of execution. The macro_ threadid can be used to determine the 
current thread identifier. 
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WARNING! If any thread calls a library function, you must use the _ beginthread function to 
create the thread. Do not use the DosCreateThread API function. 


36.2.1 Creating a New Thread 

The _ beginthread function creates a new thread. It is defined as follows. 

int _ beginthread ( void (*start_ address) (void *), 

void *stack_ bottom, 
unsigned stack_ size, 
void *arglist ); 

description: 

is the address of the function that will be called when the newly created thread is executed. 
When the thread returns from that function, the thread will be terminated. Note that a call 
to the _ endthread function will also terminate the thread. 

specifies the bottom of the stack to be used by the thread. Note that this argument is 
ignored as it is only needed to simplify the port of OS/2 1 .x multi-threaded applications to 
OS/2 2.x. Under OS/2 2.x, the operating system allocates the stack for the new thread. A 
value of NULL may be specified. 

specifies the size of the stack to be allocated by the operating system for the new thread. 
The stack size should be a multiple of 4K. 

is passed as an argument to the function specified by start_ address . If no argument 
is required, a value of NULL can be specified. 

If a new thread is successfully created, the thread identifier of the new thread is returned. Otherwise, a 
value of -1 is returned. 

The header file process . h contains the definition of the _ beginthread function. 

36.2.2 Terminating the Current Thread 

The _ endthread function terminates the current thread. It is defined as follows, 
void _ endthread ( void ) 

The header file process . h contains the definition of the _ endthread function. 

36.2.3 Getting the Current Thread Identifier 

The _ threadid macro can be used to determine the current thread identifier. It is defined as follows. 

int *_threadid(void) ; 

#define _threadid (_threadid()) 

The header file stddef . h contains the definition of the _ threadid macro. 


where 

start_address 

stack_bottom 

stack_size 

arglist 
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36.3 A Multi-threaded Example 

Let us create a simple multi-threaded application. The source code for this example can be found in 
\watcom\samples\os2. 

♦include <process.h> 

♦include <stdio.h> 

♦include <stddef.h> 

♦define INCL_ DOS 
♦include <os2.h> 

static volatile int NumThreads; 

static volatile int HoldThreads; 

♦ define NUM_ THREADS 5 

♦define STACK_ SIZE 32768 

static void a_ thread( void *arglist ) 

/***********************************/ 

{ 

while( HoldThreads ) { 

DosSleep( 1 ); 

} 

printf ( "Hi from thread %d\n", *_ threadid ); 

DosEnterCritSec () ; 

—NumThreads; 

DosExitCritSec(); 

_ endthread(); 

} 

int main( void ) 

/**************/ 

{ 

int i; 

printf( "Initial thread id = %d\n", *_ threadid ); 

NumThreads = 0; 

HoldThreads = 1; 

/* initial thread counts as 1 */ 

for ( i = 2; i <= NUM_ THREADS; ++i ) { 

if ( _ beginthread( a_ thread, NULL, STACK_ SIZE, NULL ) == -1 ) { 

printf( "creation of thread %d failed\n", i ); 

} else { 

++NumThreads; 

} 

} 

HoldThreads = 0; 

while( NumThreads != 0 ) { 

DosSleep( 1 ); 

} 

return ( 0 ) ; 

} 

Note: 

1. In the function a_ thread, DosEnterCritSec and DosExitCritSec are called when 
we modify the variable NumThreads . This ensures that the action of extracting the value of 
NumThreads from memory, incrementing the value, and storing the new result into memory, 
occurs without interruption. If these functions were not called, it would be possible for two 
threads to extract the value of NumThreads from memory before an update occurred. 

Let us assume that the file mthread. c contains the above example. Before compiling the file, make sure 
that the WATCOM environment variable is set to the directory in which you installed Open Watcom 
C/C++. Also, the INCLUDE environment variable must include the \watcom\h\os2 and \watcom\h 
directories ("YWATCOM" is the directory in which Open Watcom C/C++ was installed). 
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We can now compile and link the application by issuing the following command. 

[C:\]wcl386 -bt=os2 -bm -1=os2v2 mthread 

The "bm" option must be specified since we are creating a multi-threaded application. If your 
multi-threaded application contains more than one module, each module must be compiled using the "bm" 
switch. 

The "1" option specifies the target system for which the application is to be linked. The system name 
os2v2 is defined in the file wlsystem. Ink which is located in the "BINW" subdirectory of the 
directory in which you installed Open Watcom C/C++. 

The multi-threaded application is now ready to be run. 


36.4 Thread Limits 


There is a limit to the number of threads an application can create under 16-bit OS/2. The default limit is 
32. This limit can be adjusted by statically initializing the unsigned global variable_ MaxThreads . 

Under 32-bit OS/2, there is no limit to the number of threads an application can create. However, due to 
the way in which multiple threads are supported in the Open Watcom libraries, there is a small performance 
penalty once the number of threads exceeds the default limit of 32 (this number includes the initial thread). 
If you are creating more than 32 threads and wish to avoid this performance penalty, you can redefine the 
threshold value of 32. You can statically initialize the global variable_ MaxThreads . 

By adding the following line to your multi-threaded application, the new threshold value will be set to 48. 

unsigned _MaxThreads = { 48 }; 
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37 OS/2 2.x Dynamic Link Libraries 


A dynamic link library, like a standard library, is a library of functions. When an application uses functions 
from a standard library, the library functions referenced by the application become part of the executable 
module. This form of linking is called static linking. When an application uses functions from a dynamic 
link library, the library functions referenced by the application are not included in the executable module. 
Instead, the executable module contains references to these functions which are resolved when the 
application is loaded. This form of linking is called dynamic linking. 

Let us consider some of the advantages of using dynamic link libraries over standard libraries. 

1. Functions in dynamic link libraries are not linked into your program. Only references to the 
functions in dynamic link libraries are placed in the program module. These references are 
called import definitions. As a result, the linking time is reduced and disk space is saved. If 
many applications reference the same dynamic link library, the saving in disk space can be 
significant. 

2. Since program modules only reference dynamic link libraries and do not contain the actual 
executable code, a dynamic link library can be updated without re-linking your application. 
When your application is executed, it will use the updated version of the dynamic link library. 

3. Dynamic link libraries also allow sharing of code and data between the applications that use 
them. If many applications that use the same dynamic link library are executing concurrently, 
the sharing of code and data segments improves memory utilization. 

37.1 Creating Dynamic Link Libraries 

Once you have developed the source for a library of functions, a number of steps are required to create a 
dynamic link library containing those functions. 

First, you must compile your source using the "bd" compiler option. This option tells the compiler that the 
module you are compiling is part of a dynamic link library. Once you have successfully compiled your 
source, you must create a linker directive file that describes the attributes of your dynamic link library. The 
following lists the most common linker directives required to create a dynamic link library. 

1. The "SYSTEM" directive is used to specify that a dynamic link library is to be created. 

2. The "EXPORT" directive is used to to specify which functions in the dynamic link library are to 
be exported. 

Specifying exports in the source code 

The "EXPORT" directive need not be used when the symbols to be exported are 

declared with the_export type qualifier in the source code. Such symbols 

are exported automatically, through special records inserted into the object files 
by the compiler. 
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3. The "OPTION" directive is used to specify attributes such as the name of the dynamic link 
library and how to allocate the automatic data segment when the dynamic link library is 
referenced. 

4. The "SEGMENT" directive is used to specify attributes of segments. For example, a segment 
may be read-only or read-write. 

Once the dynamic link library is created, you must allow access to the dynamic link library to client 
applications that wish to use it. This can be done by creating an import library for the dynamic link library 
or creating a linker directive file that contains "IMPORT" directives for each of the entry points in the 
dynamic link library. 

37.2 Creating a Sample Dynamic Link Library 

Let us now create a dynamic link library using the following example. 

♦include <stdio.h> 

♦include <os2.h> 

♦ if defined(_cplusplus) 

♦define EXTERNC extern "C" 

♦else 

♦define EXTERNC 
♦endif 

unsigned APIENTRY LibMain( unsigned hmod, unsigned termination ) 

{ 

if( termination ) { 

/* DLL is detaching from process */ 

} else { 

/* DLL is attaching to process */ 

} 

return( 1 ); 

} 


EXTERNC void dll_ entry_ 1 ( void ) 

{ 

printf ( "Hi from dll entry #l\n" ); 

} 


EXTERNC void dll_ entry_ 2 ( void ) 

{ 

printf ( "Hi from dll entry #2\n" ); 

} 


32-bit OS/2 DLLs can include a LibMain entry point when you are using the Open Watcom C/C++ 
run-time libraries. 


Arguments: 

hmod This is a handle for the DLL. 


termination A 0 value indicates that the DLL is attaching to the address space of the current process as a 
result of the process starting up or as a result of a call to DosLoadModule. A DLL can 
use this opportunity to initialize any instance data. 

A non-zero value indicates that the DLL is detaching from the address space of the calling 
process as a result of either a normal termination or of a call to DosFreeModule. 

Return Value The LibMain function returns 1 if initialization succeeds or 0 if initialization fails. 
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If the return value is 0 when LibMain is called because the process uses the 
DosLoadModule function, DosLoadModule returns an error. 

If the return value is 0 when LibMain is called during process initialization, the process 
terminates with an error. 

Assume the above example is contained in the file dll samp. c . We can compile the file using the 
following command. Note that we must specify the "bd" compiler option. 

[C:\]wcc386 -bd dllsamp 

Before we can link our example, we must create a linker directive file that describes the attributes and entry 
points of our dynamic link library. The following is a linker directive file, called dllsamp. Ink, that 
can be used to create the dynamic link library. 

system os2v2 dll initinstance terminstance 

option manyautodata 

export dll_ entry_ 1_ 

export dll_ entry_ 2_ 

file dllsamp 

Notes: 

1. The "SYSTEM" directive specifies that we are creating a 32-bit OS/2 dynamic link library. 

2. The "MANYAUTODATA" option specifies that the automatic data segment is allocated for 
every instance of the dynamic link library. This option must be specified only for a dynamic link 
library that uses the Open Watcom C/C++ run-time libraries. If the Open Watcom C/C++ 
run-time libraries are not used, this option is not required. Our example does use the Open 
Watcom C/C++ run-time libraries so we must specify the "MANYAUTODATA" option. 

As was just mentioned, when a dynamic link library uses the Open Watcom C/C++ run-time 
libraries, an automatic data segment is created each time a process accesses the dynamic link 
library. For this reason, initialization code must be executed when a process accesses the 
dynamic link library for the first time. To achieve this, "INITINSTANCE" must be specified in 
the "SYSTEM" directive. Similarly, "TERMINSTANCE" must be specified so that the 
termination code is executed when a process has completed its access to the dynamic link 
library. If the Open Watcom C/C++ run-time libraries are not used, these options are not 
required. 

3. The "EXPORT" directive specifies the entry points into the dynamic link library. Note that the 
names specified in the "EXPORT" directive are appended with an underscore. This is the 
default naming convention used when compiling using the register-based calling convention. No 
underscore is required when compiling using the stack-based calling convention. 

We can now create our dynamic link library by issuing the following command. 

[C:\]wlink Sdllsamp 

A file called dllsamp. dll will be created. 
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37.3 Using Dynamic Link Libraries 

Once we have created a dynamic link library, we must allow other applications to access the functions 
available in the dynamic link library. There are two ways to achieve this. 

The first method is to create a linker directive file which contains an "IMPORT" directive for all entry 
points in the dynamic link library. The "IMPORT" directive provides the name of the entry point and the 
name of the dynamic link library. When creating an application that references a function in the dynamic 
link library, this linker directive file would be included as part of the linking process that created the 
application. 

The second method is to use import libraries. An import library is a standard library that is created from a 
dynamic link library by using the Open Watcom Library Manager. It contains object modules that describe 
the entry points in a dynamic link library. The resulting impoit library can then be specified in a 
"LIBRARY" directive in the same way one would specify a standard library. 

Using an import library is the preferred method of providing references to functions in dynamic link 
libraries. When a dynamic link library is modified, typically the impoit library corresponding to the 
modified dynamic link library is updated to reflect the changes. Hence, any directive file that specifies the 
import library in a "LIBRARY" directive need not be modified. However, if you are using "IMPORT" 
directives, you may have to modify the "IMPORT" directives to reflect the changes in the dynamic link 
library. 

Let us create an import library for our sample dynamic link library we created in the previous section. We 
do this by issuing the following command. 

[C:\]wlib dllsamp +dllsamp.dll 

A standard library called dllsamp. lib will be created. 

Suppose the following sample program, contained in the file dlltest. c, calls the functions from our 
sample dynamic link library. 

♦include <stdio.h> 

#if defined(_cplusplus) 

♦define EXTERNC extern "C" 

♦else 

♦define EXTERNC 
♦endif 

EXTERNC void dll_ entry_ 1 ( void ) ; 

EXTERNC void dll_ entry_ 2 ( void ) ; 
int main( void ) 

{ 

dll_ entry_ 1 () ; 
dll_ entry_ 2 () ; 
return( 0 ); 

} 


We can compile and link our sample application by issuing the following command. 

[C:\]wcl386 -1=os2v2 dlltest dllsamp.lib 

If we had created a linker directive file of "IMPORT" directives instead of an import library for the 
dynamic link library, the linker directive file, say dllimps . Ink, would be as follows. 

import dll_ entry_ 1_ dllsamp 
import dll_ entry_ 2_ dllsamp 
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Note that the names specified in the "IMPORT" directive are appended with an underscore. This is the 
default naming convention used when compiling using the register-based calling convention. No 
underscore is required when compiling using the stack-based calling convention. 

To compile and link our sample application, we would issue the following command. 

[C:\]wcl386 -1=os2v2 dlltest -"Sdllimps" 

37.4 The Dynamic Link Library Data Area 

The Open Watcom C/C++ 32-bit run-time library does not support the general case operation of DLLs in 
an execution environment where there is only one instance of the DATA segment (DGROUP) for that 
DLL. 

There are two cases that can lead to a DLL executing with only one instance of the DGROUP. 

1. DLLs linked for 32-bit OS/2 without the MANY AUTODATA option. 

2. DLLs linked for the Win32 API and executing under Win32s. 

In these cases the run-time library startup code detects that there is only one instance of the DGROUP when 
a second process attempts to attach to the DLL. At that point, it issues a diagnostic for the user and then 
notifies the operating system that the second process cannot attach to the DLL. 

Developers who require DLLs to operate when there is only one instance of the DGROUP can suppress the 
function which issues the diagnostic and notifies the operating system that the second process cannot attach 
to the DLL. 

Doing so requires good behaviour on the part of processes attaching to the DLL. This good behaviour 
consists primarily of ensuring that the first process to attach to the DLL is also the last process to detach 
from the DLL thereby ensuring that the DATA segment is not released back to the free memory pool. 

To suppress the function which issues the diagnostic and notifies the operating system that the second 
process cannot attach to the DLL, the developer must provide a replacement entry point with the following 
prototype: 

int_disallow_ single_ dgroup ( int ) ; 

This function should return zero to indicate that the detected single copy of the DATA segment is allowed. 

37.5 Dynamic Link Library Initialization/Termination 

Each dynamic link library (DLL) has an initialization and termination routine associated with it. The 
initialization routine can either be called the first time any process accesses the DLL ("INITGLOBAL" is 
specified at link time) or each time a process accesses the DLL ("INITINSTANCE" is specified at link 
time). Similarly, the termination routine can either be called when all processes have completed their 
access of the DLL ("TERMGLOBAL" is specified at link time) or each time a process completes its access 
of the DLL ("TERMINSTANCE" is specified at link time). 
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For a DLL that uses the C/C++ run-time libraries, initialization and termination of the C/C++ run-time 
environment is performed automatically. It is also possible for a DLL to do its own special initialization 
and termination process. 

The C/C++ run-time environment provides two methods for calling user-written DLL initialization and 
termination code. 

1. If you provide your own version of LibMain then it will be called for initialization and 
termination. The use of LibMain is described earlier in this chapter. 

2. If you do not provide your own version of LibMain then a default version is linked in from the 

library. This version will call_dll_ initialize for DLL initialization and 

_dll_ terminate for DLL termination. Default stub versions of these two routines are 

included in the run-time library. If you wish to perform additional initialization/termination that 
is specific to your dynamic link library, you may write your own versions of these routines. 

Once the C/C++ run-time environment is initialized, the routine_dll_ initialize is called. After 

the C/C++ run-time environment is terminated, the routine_dll_ terminate is called. This last point 

is important since it means that you cannot do any run-time calls in the termination routine. 

The initialization and termination routines return an integer. A value of 0 indicates failure; a value of 1 
indicates success. The following example illustrates sample initialization/termination routines. 

♦include <stdlib.h> 

♦ define WORKING_ SIZE (64 * 1024) 

char *WorkingStorage; 

♦if defined(_cplusplus) 

♦define EXTERNC extern "C" 

♦else 

♦define EXTERNC 
♦endif 

void_dll_ finalize ( void ); 

EXTERNC int_dll_ initialize ( void ) 

{ 

WorkingStorage = malloc( WORKING_ SIZE ) ; 
if( WorkingStorage == NULL ) return( 0 ); 

atexit (_dll_ finalize ) ; 

return( 1 ); 

} 


void_dll_ finalize ( void ) 

{ 

free( WorkingStorage ); 

} 


EXTERNC int _dll_ terminate( void ) 

{ 

return( 1 ); 

} 


EXTERNC void dll_ entry ( void ) 

{ 

/* use array WorkingStorage */ 

} 


In the above example, the process initialization routine allocates storage that the dynamic link library needs, 
the routine dll_ entry uses the storage, and the process termination routine frees the storage allocated in 
the initialization routine. 
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Basically, there are two classes of C/C++ applications that can run in a windowed environment. 

The first are those C/C++ applications that do not use any of the Presentation Manager API functions; they 
are strictly C/C++ applications that do not rely on the features of a particular operating system. 

The second class of C/C++ applications are those that actually call Presentation Manager API functions 
directly. These are applications that have been tailored for the Presentation Manager operating 
environment. 

It is assumed that the reader is familiar with the concepts of Presentation Manager programming. 

38.1 Porting Existing C/C++ Applications 

Suppose you have a set of C/C++ applications that previously ran under DOS and you now wish to run 
them under OS/2. To achieve this, simply recompile your application and link with the appropriate 
libraries. Depending on the method with which you linked your application, it can run in an OS/2 
fullscreen environment, a PM-compatible window, or as a Presentation Manager application. An OS/2 
fullscreen application runs in its own screen group. A PM-compatible application will run in an OS/2 
fullscreen environment or in a window in the Presentation Manager screen group but does not take direct 
advantage of menus, mouse or other features available in the Presentation Manager. A Presentation 
Manager application has full access to the complete set of user-interface tools such as menus, icons, scroll 
bars, etc. However, porting a console oriented application to Presentation Manager often requires 
significant effort and a substantial redesign of the application. 

38.1.1 An Example 

Very little effort is required to port an existing C/C++ application to OS/2. Let us try to run the following 
sample program (contained in the file hello . c). 

♦include <stdio.h> 

int main( void ) 

/**************/ 

{ 

printf( "Hello world!\n" ); 
return( 0 ) ; 

} 

An equivalent C++ program follows: 
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♦include <iostream.h> 

int main( void ) 

{ 

cout << "Hello world" << endl; 
return ( 0 ) ; 

} 

First we must compile the file hello . c by issuing the following command. 

[C:\]wcc386 hello 

Once we have successfully compiled the file, we can link it by issuing the following command. 

[C:\]wlink sys os2v2 file hello 
It is also possible to compile and link in one step, by issuing the following command. 

[C:\]wcl386 -1=os2v2 hello 

This will create a PM-compatible application. If you wish to create a fullscreen application, link with the 
following command. 

[C:\]wlink sys os2v2 fullscreen file hello 


38.2 Calling Presentation Manager API Functions 

It is also possible for a C/C++ application to create its own windowing environment. This is achieved by 
calling PM API functions directly from your C/C++ program. The techniques for developing these 
applications can be found in the OS/2 Technical Library. 

A number of C/C++ include files (files with extension . h) are provided which define Presentation Manager 
data structures and constants. They are located in the \watcom\h\os2 directory. These include files are 
roughly equivalent to the C/C++ header files that are available with the IBM OS/2 Developer’s Toolkit. 

A sample C/C++ Presentation Manager application is also located in the \watcom\samples\os2 
directory. It is contained in the files shapes . c (C variant) and shapes . cpp (C++ variant, nearly 
identical). The file shapes . c contains the following. 

#include <stdlib.h> 

#define INCL_ WIN 
#define INCL_ GPI 
#include <os2.h> 

int SizeX; 

int SizeY; 

HWND FrameHandle; 

HMQ hMessageQueue; 

HAB AnchorBlock; 
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static int Random( int high ) 

{ 

return( ( (double)rand() / 32767 ) * high ); 

} 


static void NewColor( HPS ps ) 

{ 

GpiSetColor( ps, Random( 15 ) + 1 ); 

} 


/* Draw a rectangular shape of random size and color at random position */ 
static void DrawEllipse(HWND hwndWindow) 

{ 


POINTL 

HPS 

static int 
int 


ptl; 

ps; 

Odd = 0; 
parml,parm2; 


ps = WinGetPS( hwndWindow ) ; 
ptl.x = Random( SizeX ); 
ptl.y = Random( SizeY ); 

GpiMove( ps, &ptl ); 
ptl.x = Random( SizeX ); 
ptl.y = Random( SizeY ); 
parml = Random( 50 ); 
parm2 = Random( 50 ); 
if( Random( 10 ) >= 5 ) { 

NewColor( ps ) ; 

GpiBox ( ps, DRO_ FILL, &ptl, 0, 0 ); 

NewColor ( ps ); 

GpiBox ( ps, DRO_ OUTLINE, &ptl, 0, 0 ); 

} else { 

NewColor( ps ); 

GpiBox ( ps, DRO_ FILL, &ptl, parml, parm2 ); 

NewColor ( ps ); 

GpiBox ( ps, DRO_ OUTLINE, &ptl, parml, parm2 ); 


Odd++; 

Odd &= 1; 

WinReleasePS ( ps ); 


/* Client window procedure */ 

MRESULT EXPENTRY MainDriver( HWND hwnd, USHORT msg, MPARAM mpl, MPARAM mp2 ) 

{ 

HPS ps; 

RECTL rcl; 

switch( msg ) { 

case WM_ CREATE: 

/* Start a 150ms timer on window creation */ 

WinStartTimer( AnchorBlock, hwnd, 1, 150 ) ; 
break; 

case WM_ TIMER: 

/* Draw another ellipse on each timer tick */ 

DrawEllipse( hwnd ); 
return( 0 ); 
case WM_ SIZE: 

/* Remember new dimensions when window is resized */ 

SizeX = SHORT1FROMMP( mp2 ); 

SizeY = SHORT2FROMMP( mp2 ); 
return( 0 ); 
case WM_ PAINT: 

/* Handle paint events */ 

ps = WinBeginPaint( hwnd, NULL, NULL ); 

WinQueryWindowRect( hwnd, &rcl ); 

WinFillRect ( ps, &rcl, CLR_ WHITE ); 

WinEndPaint( ps ); 
return( 0 ); 
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} 

/* Let the default window procedure handle all other messages */ 
return( WinDefWindowProc( hwnd, msg, mpl, mp2 ) ); 


int main() 

{ 

ULONG style; 

QMSG qmsg; 

HWND WinHandle; 

/* Initialize windowing and create message queue */ 

AnchorBlock = Winlnitialize( 0 ); 
if( AnchorBlock == 0 ) return( 0 ); 

hMessageQueue = WinCreateMsgQueue( AnchorBlock, 0 ); 
if( hMessageQueue == 0 ) return( 0 ) ; 

/* Register window class */ 

if( !WinRegisterClass( AnchorBlock, "Watcom", (PFNWP)MainDriver, 

CS_ SIZEREDRAW, 0 ) ) { 

return( 0 ); 

} 

/* Create frame and client windows */ 

Style = FCF_ TITLEBAR | FCF_ SYSMENU | FCF_ SIZEBORDER | FCF_ MINMAX | 
FCF_ SHELLPOSITION | FCF_ TASKLIST; 

FrameHandle = WinCreateStdWindow( HWND_ DESKTOP, WS_ VISIBLE, sstyle, 

"Watcom", 

"Shapes - C sample", 

0, NULL, 0, SWinHandle ); 

/* If window creation failed, exit immediately! */ 
if( FrameHandle == 0 ) return( 0 ); 

/* Message loop */ 

while( WinGetMsg( AnchorBlock, &qmsg, NULL, 0, 0 ) ) { 

WinDispatchMsg( AnchorBlock, &qmsg ); 

} 

/* Shut down and clean up */ 

WinDestroyWindow( FrameHandle ); 

WinDestroyMsgQueue( hMessageQueue ) ; 

WinTerminate( AnchorBlock ) ; 

return( 1 ); 

} 

You can compile, link and run this demonstration by issuing the following commands. 

[C:\]wcl386 -1=os2v 2_ pm shapes 
[C:\]shapes 
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39 Developing an OS/2 Physical Device Driver 


In this chapter, we discuss the development of Physical Device Drivers (PDD) for OS/2. The tools used in 
the creation of the sample PDD are: 

• the 16-bit Open Watcom C compiler 

• the Open Watcom Assembler 

• the Open Watcom Make utility 

The sample Physical Device Driver that we are going to build, HRTIMER. SYS, provides access to a high 
resolution timer. Additional sources of information on PDDs can be found in the following: 

1. OS/2 2.0 Technical Library - Physical Device Driver Reference 

2. Writing OS/2 2.1 Device Drivers in C by Steve .1. Mastrianni 

3. An OS/2 High Resolution Software Timer by Derek Williams, an article which appeared in the 
Fall 1991 issue of IBM Personal Systems Developer magazine. The source code for this device 
driver was adapted from the magazine article. For detailed information on the way this device 
driver works, please read that article. 

HRTIMER. SYS is a 16-bit device driver which runs under OS/2 1.x and 2.x/3.x. It has a resolution of 840 
nanoseconds (i.e., 1 tick of the Intel 8253/8254 timer = 840 nanoseconds). 

Here are some notes on creating Physical Device Drivers using Open Watcom software tools. 

1. A Physical Device Driver is linked as a DLL. 

2. The first segment must be a data segment, the next a code segment. 

3. By default only the first two segments remain after initialization, extra segments have to be 
marked IOPL. 

4. The assembler file, DEVSEGS . ASM, defines the segment ordering. 

5. #pragma dataseg and #pragma codeseg are used to get various pieces of code and data 
into the correct segments. 

6. The _ HEADER segment contains the device header and must be at the beginning of the data 
segment. 

7. The _ INITCODE and_ INITDATA segments are used to place initialization code and data at the 
end so it can be discarded by OS/2. 

To compile the source code for the 16-bit Physical Device Drivers, we use the following options: 
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-bt=os2 

build target is OS/2 

-ms 

16-bit small code/small data model 

-5 

Pentium optimizations (this is optional) 

-omi 

inline math and intrinsic functions (this is optional) 

-s 

no stack checking 

-zdp 

DS is pegged to DGROUP 

-zff 

FS floats, i.e. not fixed to a segment 

-Zgf 

GS floats, i.e. not fixed to a segment 

-zu 

SS != DGROUP 

-zl 

remove default library information 


To link the object code for the 16-bit Physical Device Drivers, we use the following options: 
name hrtimer.sys to name the executable file. 

sys os2 dll initglobal to link a 16-bit OS/2 DLL. Specifying INITGLOBAL will cause the 

initialization routine to be called the first time the dynamic link library is loaded. 

option map to generate a map file. 

option quiet to minimize the number of linker informational messages. 

lib os2 to include the 16-bit OS2 . LIB library file. 

file ... to include the component object files of the device driver. 

The sample files used to create the Physical Device Driver and the programs that use it are located in the 
\WATC0M\SRC\0S2\PDD directory. The Physical Device Driver files are: 

DEVSEGS.ASM This small assembler file orders the segment definitions in the executable file. 

Data Segments _ HEADER 
CONST 
C0NST2 
_ DATA 
_ BSS 

_ INITDATA (discardable) 

Code Segments _ TEXT 

_ INITCODE (discardable) 

HEADER.C The first thing that must follow the EXE Header is the Device Driver Header. 

STRATEGY.C This is the resident portion of the Strategy routine. 

STRATINI.C This is the discardable portion of the Strategy routine, the initialization code and 

data. 


262 Developing an OS/2 Physical Device Driver 




Developing an OS/2 Physical Device Driver 


HRTIMER.H 

This 

HRDEV.H 

This 

DEVHDR.H 

This 


3-2, 

DEVDEFS.H 

This 

DEVREQP.H 

This 

DEVAUX.H 

This 


The demonstration program files are: 

HRTEST.C 


TIMER.C 


This file is a sample C program that shows how to use the device driver to calculate elapsed 
times. It demonstrates how to open the device driver, read timestamps from it and close it. 
It factors in the overhead of the read and has a function that is used to calculate elapsed 
time from a start and stop timestamp. 

This file is a sample C program that can be used to time other applications. It also uses the 
device driver. 


To build the device driver and demonstration programs, set your current directory to 
\WATC0M\SRC\0S2\PDD and type: 


wmake 

To install the device driver, put the following statement in your CONFIG. SYS file. 
DEVTCE=\WATC0M\SRC\0S2\PDD\HRTIMER.SYS 


You must then reboot OS/2. 

To run the test program, use the following command-line: 

HRTEST [milliseconds] 

For [milliseconds ] , you can enter any number (e.g., 2000 which is 2 seconds). 

HRTEST . EXE will issue a DosSleep for the amount of milliseconds specified or will use a default if no 
command-line parameter is given. It will get a timestamp from the device driver before and after the 
DosSleep and will calculate the elapsed time of that sleep and display the results. It will do this 
continuously until Ctrl/C or Ctrl/Break is pressed. 

Keep in mind that DosSleep has a granularity of 32 milliseconds. Any discrepancy between the number of 
milliseconds used for the DosSleep and the elapsed time results from the timer are the fault of this 
granularity, not a problem with the timer. DosSleep is used solely as a convenient method of displaying the 
capabilities of the driver. 

To run the timer program, use the following command-line: 

TIMER program_ name [program_ args ] 

For example, to time an OS/2 Directory command, issue the following command. 
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Example: 

timer cmd /c dir c: 
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40 Creating NetWare 386 NLM Applications 


Open Watcom C/C++ supports version 4.0 of the Netware 386 API. We include the following components: 
header files Header files for the Netware 4.0 API are located in the \WATCOM\NOVH directory. 
import libraries 

Import libraries for the Netware 4.0 API are located in the \WATCOM\NOVI directory. 

libraries The C/C++ libraries for Netware 4.0 is located in the \WATCOM\LIB3 8 6 and 

\ WATCOM\LIB 3 8 6\ NETWARE directories. 

debug servers Servers for remote debugging of Netware 4.0 NLMs are located in the \WATCOM\NLM 
directory. The same directory also contains the Open Watcom Execution Sampler for 
NLMs. 

Applications built for version 4.0 will run on 4.1. We do not include support for any API specific to 
version 4.1. Netware developers must use the support included with Open Watcom C/C++ version 10.0 or 
greater since the version supplied by Novell only works with Open Watcom C/C++ version 9.5. Netware 
4.1 support requires modification to the header files supplied by Novell. Contact Novell for more 
information. 

The following special notes apply to developing applications for NetWare. 

1. You must compile your source files with the "-bt=NETWARE" option. This will cause the 
compiler to: 

• use the small memory model instead of the flat memory model, 

• use stack-based calling conventions, 

• search the NETWARE_INCLUDE environment variable before searching the 
INCLUDE environment variable, and 

• reference a special startup symbol,_ WATCOM_ Prelude, in the libraries. 

2. You must compile your source files with the small memory model option ("ms"). This is 
accomplished by specifying the "-bt=NETWARE" option. 

3. You must compile your source files with one of the stack-based calling convention options ("3s", 
"4s" or "5s"). This is accomplished by specifying the "-bt=NETWARE" option. 

4. You must set the NETWARE_INCLUDE environment variable to point to the 
\WATCOM\NOVH directory. This environment variable will be searched first when you compile 
with the "-bt=NETWARE" option. Alternatively, you can set the INCLUDE environment 
variable to include \WATCOM\NOVH before other include directories. 

5. If you are using the compile and link utility WCL386, you must use the following options: 
”-l=NETWARE -bt=NETWARE". 

6. You must specify 
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system NETWARE 


when linking an NLM. This is automatic if you are using WCL386 and the "-1=NETWARE" 
option. 

7. If you are using other Netware APIs such as NWSNUT, then you must include module and 
import statements as input to the Open Watcom Linker. 


Example: 

module nwsnut 

import @%WATCOM%\novi\nwsnut.imp 

This is done automatically for the C Library (CLIB.IMP). The following import lists have been 
provided for Netware API libraries. 

AIO. IMP 
APPLETLK.IMP 
BSD.IMP 
CLIB.IMP 
DSAPI.IMP 
MATHLIB.IMP 
NWSNUT.IMP 
SOCKLIB.IMP 
STREAMS.IMP 
TLI.IMP 


268 Creating NetWare 386 NLM Applications 




Mixed Language Programming 



Mixed Language Programming 


270 




411nter-Language calls: C and FORTRAN 


The purpose of this chapter is to anticipate common questions about mixed-language development using 
Open Watcom C/C++ and Open Watcom FORTRAN 77. 

The following topics are discussed in this chapter: 

• Symbol Naming Convention 

• Argument Passing Convention 

• Memory Model Compatibility 

• Integer Type Compatibility 

• How do I pass integers from C to a FORTRAN function? 

• How do I pass integers from FORTRAN to a C function? 

• How do I pass a string from a C function to FORTRAN? 

• How do I pass a string from FORTRAN to a C function? 

• How do I access a FORTRAN common block from within C? 

• How do I call a C function that accepts a variable number of arguments? 

41.1 Symbol Naming Convention 

The symbol naming convention describes how a symbol in source form is mapped to its object form. 
Because of this mapping, the name generated in the object file may differ from its original source form. 

Default symbol naming conventions vary between compilers. Open Watcom C/C++ prefixes an underscore 
character to the beginning of variable names and appends an underscore to the end of function names 
during the compilation process. Open Watcom FORTRAN 77 converts symbols to upper case. Auxiliary 
pragmas can be used to resolve this inconsistency. 

Pragmas are compiler directives which can provide several capabilities, one of which is to provide 
information used for code generation. When calling a FORTRAN subprogram from C, we want to instruct 
the compiler NOT to append the underscore at the end of the function name and to convert the name to 
upper case. This is achieved by using the following C auxiliary pragma: 

♦pragma aux ftnname " A "; 

The " A " character tells the compiler to convert the symbol name "ftnname" to upper case; no underscore 
character will be appended. This solves potential linker problems with "ftnname" since (by C convention) 
the linker would attempt to resolve a reference to "ftnname_". 
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When calling C functions from FORTRAN, we need to instruct the compiler to add the underscore at the 
end of the function name, and to convert the name to lower case. Since the FORTRAN compiler 
automatically converts identifiers to uppercase, it is necessary to force the compiler to emit an equivalent 
lowercase name. Both of these things can be done with the following FORTRAN auxiliary pragma: 

*$pragma aux CNAME "!_ " 

There is another less convenient way to do this as shown in the following: 

*$pragma aux CNAME "cname_ " 

In the latter example, the case of the name in quotation marks is preserved. 

Use of these pragmas resolves the naming differences, however, the issue of argument passing must still be 
resolved. 


41.2 Argument Passing Convention 

In general, C uses call-by-value (passes argument values) while FORTRAN uses call-by-reference (passes 
pointers to argument values). This implies that to pass arguments to a FORTRAN subprogram we must 
pass the addresses of arguments rather than their values. C uses the "&" character to signify "address of". 

Example: 

result = ftnname( &arg ) ; 

When calling a C function from FORTRAN, the pragma used to correct the naming conventions must also 
instruct the compiler that the C function is expecting values, not addresses. 

*$pragma aux CNAME "!_ " parm (value) 

The "parm (value)" addition instructs the FORTRAN compiler to pass values, instead of addresses. 

Character data (strings) are an exception to the general case when used as arguments. In C, strings are not 
thought of as a whole entity, but rather as an "array of characters". Since strings are not considered scalar 
arguments, they are referenced differently in both C and FORTRAN. This is described in more detail in a 
following section. 


41.3 Memory Model Compatibility 

While it is really not an issue with the 32-bit compilers (both use the default "flat" memory model), it is 
important to know that the default memory model used in Open Watcom FORTRAN 77 applications is the 
"large" memory model ("ml") with "medium" and "huge" memory models as options. Since the 16-bit 
Open Watcom C/C++ default is the "small" memory model, you must specify the correct memory model 
when compiling your C/C++ code with the 16-bit C or C++ compiler. 
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41.4 Linking Considerations 

When both C/C++ and FORTRAN object files are combined into an executable program or dynamic link 
library, it is important that you list a least one of the FORTRAN object files first in the Open Watcom 
Linker (WLINK) "FILES" directive to guarantee the proper search order of the FORTRAN and C run-time 
libraries. If you place a C/C++ object file first, you may inadvertently cause the wrong version of run-time 
initialization routines to be loaded by the linker. 

41.5 Integer Type Compatibility 

In general, the number of bytes used to store an integer type is implementation dependent. In FORTRAN, 
the default size of an integer type is always 4 bytes, while in C/C++, the size is architecture dependent. The 
size of an "int" is 2 bytes for the 16-bit Open Watcom C/C++ compilers and 4 bytes for the 32-bit 
compilers while the size of a "long" is 4 bytes regardless of architecture. It is safest to prototype the 
function in C, specifying exactly what size integers are being used. The byte sizes are as follows: 

1. LONG-4 bytes 

2. SHORT - 2 bytes 

Since FORTRAN uses a default of 4 bytes, we should specify the "long" keyword in C for integer types. 
Example: 

long int ftnname( long int *, long int *, long int * ); 

In this case, "ftnname" takes three "pointers to long ints" as arguments, and returns a "long int". By 
specifying that the arguments are pointers, and not values, and by specifying "long int" for the return type, 
this prototype has solved the problems of argument passing and integer type compatibility. 


41.6 How do I pass integers from Ctoa FORTRAN function? 

The following Open Watcom C/C++ routine passes three integers to a FORTRAN function that returns an 
integer value. 


/* MIX1C.C - This C program calls a FORTRAN function to 

* compute the max of three numbers. 

★ 


* Compile/Link: 

★ 

*/ 


wcl /ml 
wcl386 


mixlc mixlf.obj 
mixlc mixlf.obj 


/fe=mixl 
/fe=mixl 


♦include <stdio.h> 


♦pragma aux tmax3 " A "; 

long int tmax3( long int *, long int *, 


long int * ); 
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void main() 

{ 

long int result; 
long int i, j, k; 

1 = -i; 
j = 12; 
k = 5; 

result = tmax3( &i, &j, &k ); 
printf ( "Maximum is %ld\n", result ); 

} 

The FORTRAN function: 

* MIX1F.F0R - This FORTRAN function accepts three integer 

* arguments and returns their maximum. 

* Compile: wfc[386] mixlf.for 

integer function tmax3( arga, argb, argc ) 
integer arga, argb, argc 

tmax3 = arga 

if ( argb .gt. tmax3 ) tmax3 = argb 
if ( argc .gt. tmax3 ) tmax3 = argc 
end 


41.7 How do I pass integers from FORTRAN to a C function? 

The following Open Watcom FORTRAN 77 routine passes three integers to a Open Watcom C/C++ 
function that returns an integer value. 

* MIX2F.F0R - This FORTRAN program calls a C function to 

* compute the max of three numbers. 

* 

* Compile/Link: wfl[386] mix2f mix2c.obj /fe=mix2 

*$pragma aux tmax3 "!_ " parm (value) 

program mix2f 

integer*4 tmax3 
integer*4 result 
integer*4 i, j, k 

i = -1 

j = 12 

k = 5 

result = tmax3( i, j, k ) 
print *, 'Maximum is ', result 
end 

The C function "tmax3" is shown below. 
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/* MIX2C.C - This C function accepts 3 integer arguments 

* and returns their maximum. 

★ 

* Compile: wcc /ml mix2c 

* wcc386 mix2c 
*/ 


long int tmax3( 

long int 

arga. 



long int 

argb. 

{ 

long int 


long int 

argc ) 


result; 


result = 

arga; 


if( argb 

> 

result ) 

result = argb; 

if( argc 

> 

result ) 

result = argc; 


return( result ) ; 

} 


41.8 How do I pass a string from a C function to FORTRAN? 

Character strings are referenced differently in C and FORTRAN. The C language terminates its strings 
with a null character as an End-Of-String (EOS) marker. In this case, C need not store the length of the 
string in memory. FORTRAN, however, does not use any EOS marker; hence it must store each string’s 
length in memory. 

The structure FORTRAN uses to keep track of character data is called a "string descriptor" which consists 
of a pointer to the character data (2, 4, or 6 bytes, depending on the data model) followed by an unsigned 
integer length (2 bytes or 4 bytes, depending on the data model). 


system option size of pointer size of length 


16-bit 

/MM 

16 bits 

16 

bits 

16-bit 

/ML 

32 bits 

16 

bits 

32-bit 

/MF 

32 bits 

32 

bits 

32-bit 

/ML 

48 bits 

32 

bits 


In order to access character data, FORTRAN needs to have access to the data’s string descriptor. Hence, 
FORTRAN expects a pointer to a string descriptor to be passed as an argument for character data. 

Passing string arguments between C and FORTRAN is a simple task of describing a struct type in C 
containing the two fields described above. The first field must contain the pointer to the character data, and 
the second field must contain the length of the string being passed. A pointer to this structure can then be 
passed to FORTRAN. 

* MIX3F.F0R - This FORTRAN program calls a function written 

* in C that passes back a string. 

* 

* Compile/Link: wfl[386] mix3f mix3c.obj /fe=mix3 

program mix3f 

character*80 sendstr 
character*80 cstring 
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cstring = sendstr() 

print *, cstring(1:lentrim(cstring)) 
end 

The C function "sendstr" is shown below. 

/* MIX3C.C - This C function passes a string back to its 

* calling FORTRAN program. 

★ 

* Compile: wcc /ml mix3c 

* wcc386 mix3c 
*/ 

♦include <string.h> 

♦pragma aux sendstr " A "; 

typedef struct descriptor { 
char *addr; 

unsigned len; 

} descriptor; 

void sendstr( descriptor *ftn_ str_ desc ) 

{ 

ftn_ str_ desc->addr = "This is a C string"; 

ftn_ str_ desc->len = strlen ( ftn_ str_ desc->addr ); 

} 


41.9 How do I pass a string from FORTRAN toaC function? 

By default, FORTRAN passes the address of the string descriptor when passing strings. If the C function 
knows it is being passed a string descriptor address, then it is very similar to the above example. If the C 
function is expecting normal C-type strings, then a FORTRAN pragma can be used to pass the string 
correctly. When the Open Watcom FORTRAN 77 compiler pragma to pass by value is used for strings, 
then just a pointer to the string is passed. 

Example: 

*$pragma aux cname "!_ " parm (value) 

The following example FORTRAN mainline defines a string, and passes it to a C function that prints it out. 

* MIX4F.F0R - This FORTRAN program calls a function written 

* in C and passes it a string. 

* 

* Compile/Link: wfl[386] mix4f mix4c.obj /fe=mix4 
*$pragma aux cstr " !_ " parm (value) 
program mix4f 
character*80 forstring 

forstring = 'This is a FORTRAN string'//char(0) 

call cstr ( forstring ) 

end 
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The C function: 

/* MIX4C.C - This C function prints a string passed from 

* FORTRAN. 

★ 

* Compile: wcc /ml mix4c 

* wcc386 mix4c 
*/ 

♦include <stdio.h> 

void cstr ( char *instring ) 

{ 

printf( "%s\n", instring ); 

} 

41.10 How do I access a FORTRAN common block from 
within C? 

The following code demonstrates a technique for accessing a FORTRAN common block in a C routine. 
The C routine defines an extern struct to correspond to the FORTRAN common block. 

* MIX5F.F0R - This program shows how a FORTRAN common 

* block can be accessed from C. 

* 

* Compile/Link: wfl[386] mix5f mix5c.obj /fe=mix5 

program mix5f 
external put 
common/cblk/i,j 

i=12 

j=10 

call put 

print *, 'i = ', i 
print *, ' j = ' , j 
end 

The C function: 

/* MIX5C.C - This code shows how to access a FORTRAN 

* common block from C. 

* 

* Compile: wcc /ml mix5c 

* wcc386 mix5c 
*/ 

♦include <stdio.h> 

♦pragma aux put " A "; 

♦pragma aux cblk " A "; 
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#ifdef _ 386_ 

♦define FAR 
♦ else 

♦define FAR far 
♦endif 


extern struct cb { 
long int i,j; 

} FAR cblk; 

void put( void ) 

{ 

printf ( "i = %ld\n", cblk.i ); 
printf ( "j = %ld\n", cblk.j ); 
cblk.i++; 
cblk.j++; 

} 


For the 16-bit C compiler, the common block "cblk" is described as far to force a load of the segment 
portion of the address. Otherwise, since the object is smaller than 32K (the default data threshold), it is 
assumed to be located in the DGROUP group which is accessed through the SS segment register. 


41.11 How do I call a C function that accepts a variable 
number of arguments? 

One capability that C possesses is the ability to define functions that accept variable number of arguments. 
This feature is not present, however, in the definition of the FORTRAN 77 language. As a result, a special 
pragma is required to call these kinds of functions. 

*$pragma aux printf "!_ " parm (value) caller [] 

The "caller" specifies that the caller will pop the arguments from the stack. The "[]" indicates that there are 
no arguments passed in registers because the printf function takes a variable number of arguments 
passed on the stack. The following example is a FORTRAN function that uses this pragma. It calls the 
printf function to print the value 47 on the screen. 

* MIX6.F0R - This FORTRAN program calls the C 

* printf function. 

* Compile/Link: wfl[386] mix6 

*$pragma aux printf "!_ " parm (value) caller [] 
program mix6 

character cr/zOd/, nullchar/zOO/ 

call printf ( 'Value is %ld.'//cr//nullchar, 47 ) 
end 

For more information on the pragmas that are used extensively during inter-language programming, please 
refer to the chapter entitled "Pragmas" in both the Open Wcitcom C/C++ User’s Guide and the Open 
Watcom FORTRAN 77 User’s Guide. 
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42 Commonly Asked Questions and Answers 


As with any sophisticated piece of software, there are topics that are not directly addressed by the 
descriptive portions of the manuals. The purpose of this chapter is to anticipate common questions 
concerning Open Watcom C/C++. It is difficult to predict what topics will prove to be useful but with that 
in mind, we hope that this chapter will help our customers make full use of Open Watcom C/C++. 

A number of example programs are presented throughout. The source text for these files can be found in 
the \WATCOM\SAMPLES\GOODIES directory. 

The purpose of this chapter is to present some of the more commonly asked questions from our users and 
the answers to these questions. The following topics are discussed: 

• How do I determine my current patch level? 

• How do I convert to Open Watcom C/C++? 

• What should I know about optimization? 

• Why can’t the compiler find "stdio.h"? 

• How do I resolve an "Undefined Reference" linker error? 

• Why aren’t my variables set to zero? 

• What does "size of DGROUP exceeds 64K" mean for 16-bit applications? 

• What does "NULL assignment detected" mean in 16-bit applications? 

• What does "Stack Overflow!" mean? 

• Why do I get redefinition errors from WLINK? 

• How can I open more than 20 files at a time? 

• How can I see my source files in the debugger? 

• What is the difference between the "dl" and "d2" compiler options? 

42.1 Determining my current patch level 

In an effort to immediately correct any problems discovered in the originally shipped product. Open 
Watcom provides patches as a continued service to its customers. To determine the current patch level of 
your Open Watcom software, a TECHINFO utility program has been provided. This program will display 
your current environment variables, the patch level of various Open Watcom software programs, and other 
pertinent information, such as your AUTOEXEC. BAT and CONFIG. SYS files. This information proves to 
be very useful when reporting a problem to the Technical Support team. 

To run TECHINFO, you must ensure the Open Watcom environment variable has been set to the directory 
where your Open Watcom software has been installed. TECHINFO will pause after each screenful of 
information. The output is also placed in the file TECHINFO. OUT. 

Below is an example of some partial output produced by running the TECHINFO utility: 
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Example: 

WATCOM's Techinfo Utility, Version 1.4 
Current Time: Thu Oct 27 15:58:34 1994 


WATCOM 

415 Phillip St. 
Waterloo, Ontario 
CANADA N2L 3X2 


Phone: (519) 884-0702 
Fax: (519) 747-4971 


-WATCOM C Environment Variables - 

WATCOM=<c:\watcom> 

EDPATH=<c:\watcom\eddat> 

INCLUDE=<c:\watcom\h;c:\watcom\h\os2> 

FINCLUDE=<c:\watcom\src\fortran;c:\watcom\src\fortran\win> 
LIBOS2=<c:\watcom\lib28 6\os2;c:\watcom\lib28 6> 

PATH=<c:\dos;c:\windows;c:\watcom\binw> 

TMP=<h:\temp> 

File 'c:\watcom\binw\wcc386.exe' has been patched to level ' .d' 

...etc... 


In this example, the software has been patched to level "d". In most cases, all tools will share a common 
patch level. However, there are instances where certain tools have been patched to one level while others 
are patched to a different level. For example, the compiler may be patched to level "d" while the debugger 
is only patched to level "c". Basically, this means that there were no debugger changes in the D-level 
patches. 

If you run the TECHINFO utility, and determine that you are not at the current patch level, it is 
recommended that you update your software. Patches are available on Open Watcom’s bulletin board. 
Open Watcom’s FTP site and CompuServe. They are available 24 hours a day. Patches are also available 
on the current release CD-ROM. Each patch will include a batch file that allows you to apply the patches 
to your existing software. Note that patches must be applied in sequential order, as each patch depends on 
the previous one. 


42.2 Converting to Open Watcom C/C++ 

There are some common steps involved in converting C programs written for other compilers. Conversion 
from UNIX and other IBM-compatible PC compilers will be covered in detail later. There are six major 
problems with most programs that are ported to Open Watcom C/C++. The assumptions that most foreign 
programs make that may be invalid when using Open Watcom C/C++ are: 

1. sizeofl pointer ) == sizeofl int) 

(true for 16-bit systems except "far" pointers, true for 32-bit systems except "far" pointers) 

2. sizeofl long ) == sizeoli int) 

(not tme for 16-bit systems) 

3. sizeofl short ) == sizeof( int) 

(not tme for 32-bit systems) 

4. arguments are always passed on the stack 

5. dereferencing the NULL pointer 

6. "char" is either signed or unsigned 
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These assumptions are very easy to make when developing programs for only one system. The first point 
becomes important when you move a program to 80x86 systems. Depending on the memory model, the 
size of an integer might not equal the size of a pointer. You might ask how this assumption is made in 
programs. The C language will assume that a function returns an integer unless told otherwise. If a 
programmer does not declare a function as returning a pointer, the compiler will generate code which 
would convert an integer to a pointer. On other systems, where the size of an integer is equal to the size of 
a pointer this would amount to nothing because no conversion was necessary (to change size). The older C 
compilers did not worry about warning the programmer about this condition and as such this error is 
imbedded in a lot of older C code. As C was moved to other machines, it became apparent that this 
assumption was no longer valid for all machines. The 80x86 architecture can have 16-bit integers and 
32-bit pointers (in the compact, large, and huge memory models), which means that more care must be 
taken when working with declarations (converting an int to a 32-bit pointer will result in a segment value of 
0x0000 or Oxffff). Similarly, the 386 architecture can have 32-bit integers and 48-bit pointers. 

The Open Watcom C/C++ compiler will complain about incorrect pointer and integer mixing thus making 
programs compiled with Open Watcom C/C++ much more portable. For instance, if the Open Watcom 
C/C++ compiler complains about your usage of the "malloc" memory allocation function then you probably 
forgot to include "<stdlib.h>" which contains the prototype of the "malloc" function. 

Example: 

extern void *malloc( unsigned ) ; 

The Open Watcom C/C++ compiler was complaining about you trying to assign an integer (the value 
returned by "malloc") to a pointer. By including the header file with the correct prototype, the Open 
Watcom C/C++ compiler can validate that you are in fact assigning a pointer value to a pointer. 

Passing arguments on the stack has been the method used by most older compilers because it allowed the C 
library function "printf" to work with a variable number of arguments. Older C compilers catered to a few 
functions by forcing all the argument handling to be handled by the caller of the function. With the advent 
of the ANSI (and later ISO) standard, which forced all functions expecting a variable number of arguments 
to be declared properly, compilers can generate smaller code for routines that did not require a variable 
number of arguments. 

Example: 

/* function accepting two arguments */ 

extern FILE *fopen( char *, char * ); 

/* function accepting a variable number of arguments */ 

extern int printf( char *, ... ); 

The Open Watcom C/C++ compiler takes advantage of this part of the ISO/ANSI standard by passing 
arguments in registers (for the first few arguments). If there are not enough registers for all of the 
arguments, the rest of the arguments are passed on the stack but the routine being called is responsible for 
removing them from the stack. By default, the Open Watcom C/C++ compiler uses this calling convention 
because it results in faster procedure calls and smaller code. The Open Watcom C/C++ calling convention 
carries with it a responsibility to ensure that all functions are prototyped correctly before they are used. For 
instance, if a procedure is called with too few arguments, the assumptions that the code generator made 
(while generating the code) will be invalidated. The code generator assumes that AX (EAX for the 32-bit 
compiler) and any other registers used to pass arguments will be modified by the called function. The code 
generator also assumes that the exact amount of arguments pushed on the stack will be removed by the 
function that is called. It is important to recognize this aspect of the Open Watcom C/C++ compiler 
because the program will simply not work unless the caller and the function being called strictly agree on 
the number and types of the arguments being passed. See the "Assembly Language Considerations" 
chapter in the Open Watcom C/C++ User’s Guide for more details. 
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Some compilers allow the NULL pointer to be dereferenced and return NULL (we have never understood 
the rationale behind this, nor why some compilers continue to support this type of code). Leaving the 
aesthetics of this type of code behind, using the NULL dereferencing assumption in a program will ensure 
that the program will not be portable. Source code which contains the NULL dereferencing assumption 
must be corrected before it will work with Open Watcom C/C++. 

Programs that assume that the "char" type is "signed" should use the Open Watcom C/C++ compiler "j" 
option. The "j" option will indicate to the Open Watcom C/C++ compiler that the "char" type is "signed" 
rather than the default "unsigned". 

42.2.1 Conversion from UNIX compilers 

The ISO/ANSI standard for C (which Open Watcom C/C++ adheres to) is very similar to UNIX C. Most 
of the effort in converting UNIX C programs will involve replacing references to library functions (such as 
the CURSES library). There are many third-party libraries which are implementations of UNIX libraries 
on IBM-compatible Personal Computers. There is a common problem which many older UNIX programs 
exhibit, namely, functions that accept a variable number of arguments are coded in many different ways. 
Functions accepting a variable number of arguments must be coded according to the ISO standard if they 
are to work with Open Watcom C/C++. We will code an example of a function which will return the 
maximum of a list of positive integers. 

/* 

variable number of arguments example 

* / 

♦include <stdarg.h> 

int MaxList ( int how_ many, ... ) 

{ 

va_ list args; 
int max; 

max = 0; 

va_ start ( args, how_ many ); 
while ( how_ many > 0 ) { 

value = va_ arg ( args, int ); 
if( value > max ) { 

max = value; 

} 

} 

va_ end ( args ) ; 
return( max ) ; 

} 

Notice that the standard header file STDARG. H must be included in any source file which defines a 
function that handles a variable number of arguments. The function "MaxList" must be prototyped 
correctly in other source files external to the source file containing the definition of "MaxList". 

extern int MaxList( int how_ many, ... ); 

See the Open Watcom C Library Reference manual description of "va_arg" for a more complete 
description of variable number of arguments handling. 
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42.2.2 Conversion from IBM-compatible PC compilers 

Most of the compilers available for IBM-compatible PCs have been following the ISO/ANSI standard and, 
as such, the majority of programs will not require extensive source changes. There are problems with 
programs that use compiler-specific library functions. The use of compiler-specific library functions can be 
dealt with in two different ways: 

1. use equivalent Open Watcom C/C++ library functions 

2. write your own library functions 

If portability must be maintained with the other compiler, the predefined macro "_ WATCOMC _" can be 

used to conditionally compile the correct code for the Open Watcom C/C++ compiler. 

The default calling convention for the Open Watcom C/C++ compiler is different from the calling 
convention used by other compilers for Intel-based personal computers. The Open Watcom C/C++ calling 
convention is different because it will pass some arguments in registers (thus reducing the overhead of a 
function call) rather than pushing all of the arguments on the stack. The Open Watcom C/C++ compiler is 
flexible enough to use different calling conventions on a per function basis. Converting code from other 
compilers usually involves recompiling the C source files and setting up prototypes (to use the older calling 
convention) for functions written in assembly language. For instance, if you have the functions 
"video_init", "video_put", and "video_get" written in assembly language, you can use the following 
prototypes in any source file which uses these functions. 

♦include <stddef.h> 

extern int cdecl video_ init ( void ) ; 

extern void cdecl video_ put ( int row,int col,char ch,int attr ); 
extern char cdecl video_ get ( int row, int col ) ; 

The inclusion of the STDDEF . H header file defines the "cdecl" calling convention. The Open Watcom 
C/C++ compiler will ensure that any calls to these three functions will adhere to the "cdecl" calling 
conventions. The Open Watcom C/C++ compiler will put a trailing underscore character (as opposed 
to the beginning of the name for the "cdecl" convention) on any function names to ensure that the program 
will not link register calling convention calls to "cdecl" convention functions (or vice versa). If the linker 
indicates that functions defined in assembler files cannot be resolved, it could be a result of not prototyping 
the functions properly as "cdecl" functions. 
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Hint: (16-bit applications only) Most 16-bit C compilers (including Open Watcom C/C++) have a 
"large" memory model which means that four byte pointers are used for both code and data references. 
A subtle point to watch out for involves differences between memory model definitions of different 
compilers. The "cdecl" calling convention allows functions to assume that the DS segment register 
points to the group "DGROUP". The Open Watcom C/C++ large memory model has what is called a 
"floating DS". Any function used for the large memory model cannot assume that the DS segment 
register points to the group "DGROUP". There are a few possible recourses. 

1. The assembly code could save and restore the DS segment register and set DS to DGROUP 
in order to conform to the Open Watcom C/C++ convention. If there are only a few accesses 
to DGROUP data, it is advisable to use the SS segment register which points to DGROUP in 
the large memory model. 

2. The assembly function could be described using a pragma that states that DS should point to 
"DGROUP" before calling the function. 

#pragma aux _Setcolor parm loadds 

In the above example, _Setcolor is the sample function being described. 

3. The final alternative would be the use of the "zdp" compiler option. The "zdp" option 
informs the code generator that the DS register must always point to "DGROUP". This is the 
default in the small, medium and flat memory models. Note that "flat" is a 32-bit memory 
model only. 


42.3 What you should know about optimization 

The C/C++ language contains features which allow simpler compilers to generate code of reasonable 
quality. Register declarations and imbedding assignments in expressions are two of the ways that C allows 
the programmer to "help" the compiler generate good quality code. An important point about the Open 
Watcom C/C++ compiler is that it is not as important (as it is with other compilers) to "help" the compiler. 
In order to make good decisions about code generation, the Open Watcom C/C++ compiler uses modern 
optimization techniques. 


Hint: The definitive reference on compiler design is the "dragon" book "Compilers - Principles, 
Techniques, and Tools", Alfred V. Aho, Ravi Sethi, and Jeffrey D. Ullman, published by 
Addison-Wesley, Reading, Massachusetts, 1986. The authors of the "dragon" book advocate a 
conservative approach to code generation where optimizations must preserve the semantics of the 
original program. The conservative approach is used throughout the Open Watcom C/C++ compiler to 
ensure that programmers can use the compiler without worrying about the semantics of their program 
being changed. The programmer can request that potentially unsafe optimizations be performed. With 
regard to the "oa" (ignore aliasing) option provided by the Open Watcom C/C++ compiler, the compiler 
only ignores aliasing of global variables rather than ignore aliasing totally like other compilers. 


There are certain pieces of information which the compiler cannot derive from the source code. The 
"#pragma" compiler directive is used to provide extra information to the compiler. It is necessary to have a 
complete understanding of both C/C++ and the machine architecture (i.e., 80x86) before using the powerful 
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pragma compiler directives. See the "Pragmas" chapter in the Open Watcom C/C++ User’s Guide for 
more details. 

Debugging optimized programs is difficult because variables can be assigned to different locations (i.e., 
memory or registers) in different parts of the function. The "d2" compiler option will restrict the amount of 
optimization so that variables occupy one location and can be easily displayed. It follows that the "d2" 
option is useful for initial development but production programs should be compiled with only the "dl" 
option for the best code quality. Before you distribute your application to others, you may wish to use the 
Open Watcom Strip Utility (WSTRIP) to remove debugging information from the executable image on disk 
thereby reducing disk space requirements. 


Hint: The "d2" compiler option will generate symbolic information (for every local variable) and line 
number information for the source file. The "dl" compiler option will only generate line number 
information for the source file. The use of these options determines what kind of information will be 
available for the particular module during the debugging session. 


Incorrect programs can sometimes work when compiled with the "d2" option and not work when compiled 
with the "dl" option. One way this sort of problem arises involves local arrays. 

void example( void ) 

{ 

int i; 
int a[10]; 

for( i = 0; i <= 10; ++i ) 
a [i] = i; 

do_ something ( a ); 

} 


The "for" loop initializes one too many array elements but the version compiled with the "d2" option will 
overwrite the variable "i" without causing any problems. The same function compiled with the "dl" option 
would have the variable "i" in a register. The erroneous access of "a[10] M would modify a value that is used 
to restore a register when the function returns. The register would be "restored" with an incorrect value and 
this would affect the execution of the function that called this function. The above example shows how a 
program can work when compiled with the "d2" option and stop working when compiled with the "dl" 
option. You should always test your program fully with all the modules compiled with the "dl" option to 
protect yourself from any surprises. 


42.4 The compiler cannot find "stdio.h" 

The standard header files are usually located in the sub-directory that the Open Watcom C/C++ compiler is 
installed in. Suppose that the header files are located in the sub-directory c:\watcom\h. If the 
compiler indicates (through an error message) that it is unable to locate the file STD 10. H, we have 
forgotten something. There are two ways to indicate to the Open Watcom C/C++ compiler the location of 
the standard header files. 

1. use the INCLUDE environment variable 

2. use the "i" option (Open Watcom C/C++, Open Watcom Compile and Link) 

The use of the environment variable is the simplest way to ensure that the include files will be found. For 
instance, if you include the following line in your system initialization file, AUTOEXEC . BAT, 
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set include=c:\watcom\h 

the Open Watcom C/C++ compiler will be able to find the standard include files. The use of the "i" option 
is another way to give the directory name of the standard include files. 

Example: 

C>wcc myfile.c -ic:\watcom\h 
or 

C>wcc386 myfile.c -ic:\watcom\h 
or 

C>wpp myfile.cpp -ic:\watcom\h 
or 

C>wpp386 myfile.cpp -ic:\watcom\h 

The usual manner that these methods are combined is as follows. The INCLUDE environment variable is 
used to give the location of the standard C library header files. Any directories of header files local to a 
specific programming project are often candidates for the "i" option method. See the "Open Watcom 
C/C++ #include File Processing" section of the chapter entitled "The Open Watcom C/C++ Compilers" in 
the Open Watcom C/C++ User’s Guide for more details. 

42.5 Resolving an "Undefined Reference" linker error 

The Open Watcom Linker builds an executable file by a process of resolving references to functions or data 
items that are declared in other source files. Certain conditions arise that cause the linker to generate an 
"Undefined Reference" error message. An "Undefined Reference" error message will be displayed by the 
linker when it cannot find a function or data item that was referenced in the program. Verify that you have 
included all the required object modules in the linker command and that you are linking with the correct 
libraries. There are a couple of "undefined references" that require some explanation. 

_cstart_ The unresolved reference for _ cstart_ indicates that the linker cannot find the C/C++ 

run-time libraries. The 16-bit C run-time libraries for the small memory model are 
clibs . lib and, either maths .lib, or math87s . lib . The 32-bit C run-time 
libraries for the flat memory model compiled for the register-based argument passing 
model are clib3r . lib and, either math3r . lib, or math387r . lib . Ensure that 
the WATCOM environment variable is set to the directory that Open Watcom C/C++ was 
installed in. 

_Jltused_ The _ fltused_ undefined reference indicates that floating-point arithmetic has been 
used in the modules that exhibit this error. The remedy is to ensure that the linker can find 
the appropriate math library. For the 16-bit small memory model, it is either 
maths . lib, or math87s . lib For the 32-bit register-based argument passing model, it 
is either math3r . lib, or math387r . lib depending on which floating-point option is 
used. Ensure that the WATCOM environment variable is set to the directory that Open 
Watcom C/C++ was installed in. 

_small_code_ If this undefined reference occurs when you are trying to create a 16-bit application, we 
have saved you many hours of debugging! The reason for this undefined reference is that 
the "main" entry point has been compiled for a big code model (in any one of medium, 
large, or huge memory models). Any of the modules that have this undefined reference 
have been compiled for a small code model (in any one of small or compact memory 
models) and as such do not have the correct return instructions. You should recompile the 
modules so that all the modules are compiled for the same memory model. Combining 
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source modules compiled for different memory models is very difficult and often leads to 
strange bugs. If your program has special considerations and this reference causes you 
problems, there is a "work-around". You could resolve the reference with a PUBLIC 
declaration in an assembler file or code the following in Open Watcom C/C++. 

/* rest of your module */ 

void _ small_ code ( void ) 

{ } 

The code generator will generate a single RET instruction with the public symbol 
_ small_ code_ attached to it. The common epilogue optimizations will probably 
combine this function with another function’s RET instruction and you will not even pay 
the small penalty of one byte of extra code. 

There may be another cause of this problem, the "main" function must be entered in lower 
case letters ("Main" or "MAIN" are not identified as being the same as "main" by the 
compiler). The compiler will identify the module that contains the definition of the 
function "main" by creating the public definition of either _ small_ code_ or 
_ big_ code_ depending on the memory model it was compiled in. 

_big_code_ Your module that contains the "main" entry point has been compiled with a 16-bit small 

code model (small or compact). The modules that have this undefined reference have been 
compiled in 16-bit big code models (medium, large, or huge). You should recompile the 
modules so that all the modules are compiled in the same memory model. See the 
explanation for _ small_ code_ for more details. 

main_ All C programs, except applications developed specifically for Microsoft Windows, must 

have a function called "main". The name "main" must be in lower case for the compiler to 
generate the appropriate information in the "main" module. 

WINMAIN All Windows programs must have a function called "WinMain". The function "WinMain" 
must be declared "pascal" in order that the compiler generate the appropriate name in the 
"WinMain" module. 


42.6 Why my variables are not set to zero 

The linker is the program that handles the organization of code and data and builds the executable file. C 
guarantees that all global and static uninitialized data will contain zeros. The "BSS" region contains all 
uninitialized global and static data for C programs (the name "BSS" is a remnant of the early UNIX C 
compilers). Most C compilers take advantage of this situation by not explicitly storing all the zeros to 
achieve smaller executable file sizes. In order for the program to work correctly, there must be some code 
(that will be executed before "main") that will clear the "BSS" region. The code that is executed before 
"main" is called "startup" code. The linker must indicate to the startup code where the "BSS" region is 
located. In order to do this, the Open Watcom Linker (WLINK) treats the "BSS" segment (region) in a 
special manner. The special variables ’_edata’ and ’_end’ are constructed by the Open Watcom Linker so 
that the startup code knows the beginning and end of the "BSS" region. 

Some users may prefer to use the linker provided by another compiler vendor for development. In order to 
have the program execute correctly, some extra care must be taken with other linkers. For instance, with 
the Microsoft linker (LINK) you must ensure that the ’/DOSSEG’ command line option is used. With the 
Phar Lap Linker, you must use the "-DOSORDER" command line option. In general, if you must use other 
linkers, extract the module that contains _ cstart fromclib? . lib (? will change depending on the 
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memory model) and specify the object file containing _ cstart as the first object file to be processed by 
the linker. The object file will contain the information necessary for the linker to build the executable file 
correctly. 


42.7 What does "size of DGROUP exceeds 64K“ mean for 
16-bit applications ? 

This question applies to 16-bit applications. There are two types of segments in which data is stored. The 
two types of segments are classified as "near" and "far". There is only one "near" segment while there may 
be many "far" segments. The single "near" segment is provided for quick access to data but is limited to 
less than 64K in size. Conversely, the "far" segments can hold more than 64K of data but suffer from a 
slight execution time penalty for accessing the data. The "near" segment is linked by arranging for the 
different parts of the "near" segment to fall into a group called DGROUP. See the section entitled 
"Memory Layout" in the Open Watcom Linker User’s Guide for more details. 

The 8086 architecture cannot support segments larger than 64K. As a result, if the size of DGROUP 
exceeds 64K, the program cannot execute correctly. The basic idea behind solving this problem is to move 
data out of the single "near" segment into one or more "far" segments. Of course, this solution does not 
come without any penalties. The penalty is paid in decreased execution speed as a result of accessing "far" 
data items. The magnitude of this execution speed penalty depends on the behavior of the program and, as 
such, cannot be predicted (i.e., we cannot say that the program will take precisely 5% longer to execute). 
The specific solution to this problem depends on the memory model being used in the compilation of the 
program. 

If you are compiling with the tiny, small, or medium memory models then there are two possible solutions. 
The first solution involves changing the program source code so that any large data items are declared as 
"far" data items and accessed with "far" pointers. The addition of the "far" keyword into the source code 
makes the source code non-portable but this might be an acceptable tradeoff. See the "Advanced Types" 
chapter in the Open Watcom C Language Reference manual for details on the use of the "near" and "far" 
keywords. The second solution is to change memory models and use the large or compact memory model. 
The use of the large or compact memory model allows the compiler to use "far" segments to store data 
items that are larger than 32K. 

The large and compact memory models will only allocate data items into "far" segments if the size of the 
data item exceeds 32K. If the size of DGROUP exceeds 64K then a good solution is to reduce the size 
threshold so that smaller data items will be stored into "far" segments. The relevant compiler option to 
accomplish this task is "zt<num>". The "zt" option sets a data size threshold which, if exceeded, will 
allocate the data item in "far" segments. For instance, if the option "ztlOO" is used, any data item larger 
than 100 bytes will be allocated in "far" segments. A good starting value for the data threshold is 32 bytes 
(i.e., "zt32"). The number of compilations necessary to reduce the size of DGROUP for a successful link 
with WLINK depends on the program. Minimally, any files which allocate a lot of data items should be 
recompiled. The "zt<num>" option should be used for all subsequent compiles, but the recompilation of all 
the source files in the program is not necessary. If the "DGROUP exceeds 64K" WLINK error persists, the 
threshold used in the "zt<num>" option should be reduced and all of the source files should be recompiled. 
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42.8 What does “NULL assignment detected" mean in 16-bit 
applications? 

This question applies to 16-bit applications. The C language makes use of the concept of a NULL pointer. 
The NULL pointer cannot be dereferenced according to the ISO standard. The Open Watcom C/C++ 
compiler cannot signal the programmer when the NULL address has been written to or read from because 
the Intel-based personal computers do not have the necessary hardware support. The best that the run-time 
system can do is help programmers find these sorts of errors through indirect means. The lower 32 bytes of 
"near" memory have been seeded with 32 bytes of the value 0x01. The C run-time function "_exit" checks 
these 32 bytes to ensure that they have not been written over. Any modification of these 32 bytes results in 
the "NULL assignment error" being printed before the program terminates. 

Here is an overview of a good debugging technique for this sort of error: 

1. use the Open Watcom Debugger to debug the program 

2. let the program execute 

3. find out what memory has been incorrectly modified 

4. set a watchpoint on the modified memory address 

5. restart the program with the watchpoint active 

6. let the program execute, for a second time 

7. when the memory location is modified, execution will be suspended 

We will go through the commands that are executed for this debugging session. First of all, we invoke the 
Open Watcom Debugger from the command line as follows: 

C>wd myprog 

Once we are in the debugger type: 

DBG>go 

The program will now execute to completion. At this point we can look at the output screen with the 
debugger command, "FLIP". 

DBG>flip 

We would see that the program had the run-time error "NULL assignment detected". At this point, all we 
have to do is find out what memory locations were modified by the program. 

The following command will display the lower 16 bytes of "near" memory. 

DBG>examine_nullarea 

The command should display 16 bytes of value 0x01. Press the space bar to display the next 16 bytes of 
memory. This should also display 16 bytes of value 0x01. Notice that the following data has two bytes 
which have been erroneously modified by the program. 

_nullarea 01 01 56 12 01 01 01 01-01 01 01 01 01 01 01 01 

_nullarea+16 01 01 01 01 01 01 01 01-01 01 01 01 01 01 01 01 

The idea behind this debugging technique is to set a watchpoint on the modified memory so that execution 
of the program will be suspended when it modifies the memory. The following command will "watch" the 
memory for you. 
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DBG>watch _ nullarea+2 

There has to be a way to restart the program without leaving the Open Watcom Debugger so that the 
watchpoint is active during a subsequent execution of the program. The Open Watcom Debugger 
command "NEW" will reload the program and prepare for a new invocation of the program. 

DBG>new 

DBG>go 

The Open Watcom Debugger command "GO" will start execution of the program. You may notice that the 
program executes much slower than usual but eventually the debugger will show the part of the program 
that modified the two bytes. At this point, you might want to clear the watchpoint and proceed to debug 
why the memory was modified. The command to clear the watchpoint is: 

DBG>watch/clear 1 

The "1" indicates that you want watchpoint number 1 to be cleared. Typing "WATCH" by itself will print 
out all active watchpoints. The above technique is generally useful for any type of memory overwrite error 
provided you know which memory location has been overwritten. 


Hint: The Open Watcom Debugger allows many commands to have short forms. For instance, the 
"EXAMINE" command can be shortened to an "E". We used the full commands in the examples for 
clarity. 


42.9 What "Stack Overflow!" means 


The memory used for local variables is allocated from the function call stack although the Open Watcom 
compilers will often use registers for local variables. The size of the function call stack is limited at 
link-time and it is possible to exceed the amount of stack space during execution. The Open Watcom 
run-time library will perform checks whenever a large amount of stack space is required by a function but it 
is up to the user to check stack requirements before calling a Open Watcom run-time function. Compiling 
programs with stack checking will ensure that there is enough stack space to call a Open Watcom run-time 
function. 

There are various ways of protecting against stack overflow errors. First, one should minimize the number 
of recursive functions used in an application program. This can be done by recoding recursive functions to 
use loops. Keep the amount of stack used in functions to a minimum by using and reusing static arrays 
whenever possible. These techniques will reduce the amount of stack space required but there still may be 
times where the default amount of stack space is insufficient. The Open Watcom Linker (WLINK) allows 
the user to set the amount of stack space at link-time through the directive "OPTION STACK=size" where 
size may be specified in bytes with an optional "k" suffix for kilobytes (1024 bytes). 
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Example: 

option stack=9k 

Debugging a program that reports a stack overflow error can be accomplished with the following sequence. 

1. Load your application into the debugger 

2. Set a breakpoint at_STKOVERFLOW 

3. Run the application until the breakpoint at_STKOVERFLOW is triggered 

4. Issue the debugger "show calls" command. This will display a stack traceback giving you the 
path of calls that led up to the stack overflow situation. 

The solution to the stack overflow problem at this point depends on the programmer. 


42.10 Why redefinition errors are issued from WLINK 

This question comes up often in discussions about porting old UNIX or Microsoft C programs. The 
problem stems from the forgiving nature of early UNIX linkers. In early C code, it was common to define 
header files like this: 

Example: 

/* define global variables */ 
int line_ count; 
int word_ count; 
int char_ count; 

The header file would then be included in many different modules. The C compiler would generate a 
definition of each variable in each module and leave it to the linker to pick one and resolve all references to 
one variable. The development of the ANSI C standard made this practice non-conforming. The Open 
Watcom C compiler is an ISO/ANSI C compiler and as such, is not required to support this obsolete 
behavior. The effect is that WLINK will report redefinition errors. The header file must be coded in such a 
way that the variables are defined in one module. One way to do this is as follows: 

Example: 

#ifdef DEFINE_ HERE 
#define GLOBAL 
#else 

#define GLOBAL extern 
#endif 

/* define global variables */ 

GLOBAL int line_ count; 

GLOBAL int word_ count; 

GLOBAL int char_ count; 

In most modules, the macro "DEFINE_HERE" will not be defined so the file will be equivalent to: 
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Example: 

/* define global variables */ 
extern int line_ count; 
extern int word_ count; 
extern int char_ count; 

In one module, the macro "DEFINE_HERE" must be defined before the header file is included. This can 
be done by defining the macro on the command line or by coding like this: 

Example: 

♦define DEFINE_ HERE 
♦include "globals.h" 


42.11 How more than 20 files at a time can be opened 

The number of file handles allowed by Open Watcom C/C++ is initialized to 20 in stdio . h, but this can 
be changed by the application developer. To change the number of file handles allowed with Open 
Watcom C/C++, follow the steps outlined below. 

1. Let n represent the number of files the application developer wishes to have open. Ensure that 
the stdin, stdout, stderr, stdaux, and stdprn files are included in the count. 

2. Change the CONFIG. SYS file to include "files=n" where "n" is the number of file handles 
required by the application plus an additional 5 handles for the standard files (this applies to 
DOS 5.0). The number "n" may vary depending on your operating system and version. If you 
are running a network such as Novell’s NetWare, this will also affect the number of available 
file handles. In this case, you may have to increase the number specified in the "files=n" 
statement. 

3. Add a call to _ grow_ handles in your application. 

The following example illustrates the use of _ grow_ handles . 


Example: 

/* 

★ 

■k 

★ 

★ 

★ 

★ 

★ 

★ 

*/ 


HANDLES,C 

This C program grows the number of file handles so 
more than 16 files can be opened. This program 
illustrates the interaction between _ grow_ handles and 
the DOS 5.0 file system. If you are running a network 
such as Novell's NetWare, this will also affect the 
number of available file handles. In the actual trial, 
FILES=40 was specified in CONFIG.SYS. 
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♦include <stdio.h> 


void main() 

{ 

int i, j, maxh, maxo; 
FILE *temp_ files[50]; 


for( i = 25; i < 40; i++ ) { 

/* count 5 for stdin,stdout,stderr,stdaux,stdprn */ 
printf( "Trying for %2.2d handles...", 5 + i ); 
maxh = _ grow_ handles ( 5 + i ) ; 
maxo = 0; 

for( j = 0; j < maxh; j++ ) { 

temp_ files [ j ] = tmpfileO; 
if( temp_ files[j] == NULL )break; 
maxo++; 


printf ( " %d/%d temp files opened\n", maxo, maxh ); 
for( j = 0; j < maxo; j++ ) { 

fclose ( temp_ files[j] ); 


} 


} 


42.12 How source files can be seen in the debugger 

The selection and use of debugging information is important for getting the most out of the Open Watcom 
Debugger. If you are not able to see your source code in the Open Watcom Debugger source window, 
there are three areas where things may have gone wrong, namely: 

1. using the correct option for the Open Watcom C/C++. 

2. using the correct directives for the Open Watcom Linker. 

3. using the right commands in the Open Watcom Debugger. 

The Open Watcom C/C++ compiler takes C/C++ source and creates an object file containing the generated 
code. By default, no debugging information is included in the object file. The compiler will output 
debugging information into the object file if you specify a debugging option during the compile. There are 
two levels of debugging information that the compiler can generate: 

1. Line numbers and local variables ("d2" option) 

2. Line numbers ("dl" option) 

The options are used to determine how much debugging information will be visible when you are 
debugging a particular module. If you use the "d2" option, you will be able to see your source file and 
display your local variables. The "dl" option will display the source but will not give you access to local 
variable information. 

The Open Watcom Linker (WLINK) is the tool that puts together a complete program and sets up the 
debugging information for all the modules in the executable file. There is a linker directive that indicates to 
the linker when it should include debugging information from the modules. There are five levels of 
debugging information that can be collected during the link. These are: 

1. global names (DEBUG) 
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2. global names, line numbers (DEBUG LINE) 

3. global names, types (DEBUG TYPES) 

4. global names, local variables (DEBUG LOCALS) 

5. all of the above (DEBUG ALL) 

Notice that global names will always be included in any request for debugging information. The debugging 
options can be combined 

DEBUG LINE, TYPES 

with the above directive resulting in full line number and typing information being available during 
debugging. The directives are position dependent so you must precede any object files and libraries with 
the debugging directive. For instance, if the file my link. Ink contained: 

# 

# invoke with: wlink @mylink 

# 

file main 

debug line 

file input, output 

debug all 

file process 

then the modules input and output will have global names and source line information available during 
debugging. All debugging information in the module process will be available during debugging. 


Hint: A subtle point to debugging information is that all the modules will have global names available 
if any debugging directive is used. In the above example, the module main will have global name 
information even though it does not have a DEBUG directive preceding it. 


It is preferable to have one DEBUG directive before any FILE and LIBRARY directives. You might 
wonder if this increases the size of the executable file so that it will occupy too much memory during 
debugging. The debugging information is loaded "on demand" by the debugger during the debugging 
session. A small amount of memory (40k default, selectable with the Open Watcom Debugger "dynamic" 
command line option) is used to hold the most recently used module debugging information. In practice, 
this approach saves a lot of memory because most debugging information is never used. The overhead of 
accessing the disk for debugging information is negligible compared to accessing the source file 
information. In other words, you can have as much debugging information as you want included in the 
executable file without sacrificing memory required by the program. See the section entitled "The DEBUG 
Directive" in the Open Watcom Linker User’s Guide for more details. 

If the previous steps have been followed, you should be well on your way to debugging your programs with 
source line information. There are instances where the Open Watcom Debugger cannot find the 
appropriate source file even though it knows all the line numbers. The problem that has surfaced involves 
how the source file is associated with the debugging information of the module. The original location of 
the source file is included in the debugging information for a module. The name that is included in the 
debugging information is the original name that was on the Open Watcom C/C++ command line. If the 
original filename is no longer valid (i.e., you have moved the executable to another directory), the Open 
Watcom Debugger must be told where to find the source files. The Open Watcom Debugger "Source Path" 
menu item (under "File") can be used to supply new directories to search for source files. If your source 
files are located in two directories, the following paths can be added in the Open Watcom Debugger: 
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c: \program\c\*.c 
c:\program\new\c\* . c 

The character indicates where the module name will be inserted while the Open Watcom Debugger is 
searching for the source file. See the description of the "Source Path" menu item in the Open Watcom 
Debugger User’s Guide for more details. 

42.13 The difference between the "dl" and "d2" compiler 
options 

The reason that there are two levels of debugging information available is that the code optimizer can 
perform many more optimizations and still maintain "dl" (line) information. The "d2" option forces the 
code optimizer to ensure that any local variable can be displayed at any time in the function. To illustrate 
why this results in less optimum code being generated for a function, let us look at a simple array 
initialization. 

extern int a[100]; 

void init_ a( void ) 

{ 

int i; 

for( i = 0; i < 100; ++i ) { 

a[i] = 3*i; 

} 

} 

The code optimizer will ensure that you can print the value of the variable "i" at any time during the 
execution of the loop. The "d2" option will always generate code and debugging information so that you 
can print the value of any variable during the execution of the function. In order to get the best code 
possible and still see your source file while debugging, the "dl" option only generates line number 
information into the object file. With line number information, much better code can be generated. Here is 
the C equivalent of the code generated for the array initialization example. 

extern int a[100]; 

void init_ a( void ) 

{ 


int 

*tl; 


int 

t2; 


/* 

for( i = 0; i < 

100; ++i 

tl 

= a; 


t2 

= 0; 


do 

{ 



/* a[i] = 3*i; 

*/ 


*tl = t2; 



++t 1; 



12 += 3; 


/* 

} */ 


} while( tl != a + 

100 ); 


} 
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Common Problems 


The above code executes very quickly but notice that the variable "i" has been split into two different 
variables. One of the variables handles the use of "i" as an array index and the other handles the calculation 
of "3*i". The debugging of programs that have undergone extensive optimization can be difficult, but with 
the source line information it is much easier. To summarize, use the "d2" compiler option if you are 
developing a module and you would like to be able to display each local variable. The "dl" compiler 
option will give you line number information and the best generated code possible. There is absolutely no 
reason not to specify the "dl" option because the code quality will be identical to code generated without 
the "dl" option. 
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1 The Open Watcom C/C++ Compile and Link 
Utility 


The Open Watcom C/C++ Compile and Link Utility is designed for generating applications, simply and 
quickly, using a single command line. On the command line, you can list source file names as well as 
object file names. Source files are either compiled or assembled based on file extension; object files and 
libraries are simply included in the link phase. Options can be passed on to both the compiler and linker. 


1.1 WCL/WCL386 Command Line Format 

The format of the command line is: 


WCL [files] [options] 
WCL386 [files] [options] 


The square brackets [ ] denote items which are optional. 

WCL is the name of the Open Watcom Compile and Link utility that invokes the 16-bit compiler. 


WCL386 is the name of the Open Watcom Compile and Link utility that invokes the 32-bit compiler. 


The files and options may be specified in any order. The Open Watcom Compile and Link utility uses the 
extension of the file name to determine if it is a source file, an object file, or a library file. Files with 
extensions of "OBJ" and "LIB" are assumed to be object files and library files respectively. Files with 
extensions of "ASM" are assumed to be assembler source files and will be assembled by the Open Watcom 
Assembler. Files with any other extension, including none at all, are assumed to be C/C++ source files and 
will be compiled. Pattern matching characters ("*" and "?") may be used in the file specifications. 


If no file extension is specified for a file name then the Open Watcom Compile and Link utility will check 
for a file with one of the following extensions. 


Order 

Name.Ext 

Assumed to 

be 

1. 

file.ASM 

Assembler source 

2. 

file.CXX 

C++ 

source 

code 

3. 

file.CPP 

C++ 

source 

code 

4 . 

file.CC 

C++ 

source 

code 

5. 

file.C 

C 

source 

code 


It checks for each file in the order listed. By default, the Open Watcom Assembler will be selected to 
compile files with the extension "ASM". By default, the Open Watcom C++ compiler will be selected to 
compile files with any of the extensions "CXX", "CPP" or "CC". By default, the Open Watcom C compiler 
will be selected to compile a file with a "C" extension. The default selection of compiler can be overridden 
by the "cc" and "cc++" options, described below. 
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Options are prefixed with a slash (/) or a dash (—) and may be specified in any order. Options can include 
any of the Open Watcom C/C++ compiler options plus some additional options specific to the Open 
Watcom Compile and Link utility. A summary of options is displayed on the screen by simply entering the 
"WCL" or "WCL386" command with no arguments. 

1.2 Open Watcom Compile and Link Options Summary 

General options: Description: 

c compile the files only, do not link them 

cc treat source files as C code 

cc++ treat source files as C++ code 

y ignore the WCL/WCL386 environment variable 

Compiler options: Description: 

0 (16-bit only) 8088 and 8086 instructions (default for 16-bit) 

1 (16-bit only) 188 and 186 instructions 

2 (16-bit only) 286 instructions 

3 (16-bit only) 386 instructions 

4 (16-bit only) 486 instructions 

5 (16-bit only) Pentium instructions 

6 (16-bit only) Pentium Pro instructions 

3r (32-bit only) generate 386 instructions based on 386 instruction timings and use 

register-based argument passing conventions 

3s (32-bit only) generate 386 instructions based on 386 instruction timings and use 

stack-based argument passing conventions 

4r (32-bit only) generate 386 instructions based on 486 instruction timings and use 

register-based argument passing conventions 

4s (32-bit only) generate 386 instructions based on 486 instruction timings and use 

stack-based argument passing conventions 

5r (32-bit only) generate 386 instructions based on Intel Pentium instruction timings and use 

register-based argument passing conventions (default for 32-bit) 

5s (32-bit only) generate 386 instructions based on Intel Pentium instruction timings and use 

stack-based argument passing conventions 

6r (32-bit only) generate 386 instructions based on Intel Pentium Pro instruction timings and 

use register-based argument passing conventions 

6s (32-bit only) generate 386 instructions based on Intel Pentium Pro instruction timings and 

use stack-based argument passing conventions 
ad[=<file_name>] generate make style automatic dependency file 

adbs force path separators generated in auto-dependency files to backslashes 

add[=<file_name>] specify source dependency name generated in make style auto-dependency file 

adhp[=<file_name>] specify path to use for headers with no path given 

adfs force path separators generated in auto-dependency files to forward slashes 

adt[=<target_name>] specify target name generated in make style auto-dependency file 

be build target is a console application 

bd build target is a Dynamic Link Library (DLL) 

bg build target is a GUI application 

bm build target is a multi-thread environment 

br build target uses DLL version of C/C++ run-time libraries 
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bt[=<os>] build target for operating system <os> 

bw build target uses default windowing support 

dO (C++ only) no debugging information 

dl line number debugging information 

dl+ (C only ) line number debugging information plus typing information for global symbols 

and local structs and arrays 

d2 full symbolic debugging information 

d2i (C++ only) d2 and debug inlines; emit inlines as external out-of-line functions 

d2s (C++ only) d2 and debug inlines; emit inlines as static out-of-line functions 

d2t (C++ only) full symbolic debugging information, without type names 

d3 full symbolic debugging with unreferenced type names ,* 

d3i (C++ only) d3 plus debug inlines; emit inlines as external out-of-line functions 

d3s (C++ only) d3 plus debug inlines; emit inlines as static out-of-line functions 

d<name>[=text] preprocessor #define name [text] 

d+ allow extended -d macro definitions 

db generate browsing information 

e<number> set error limit number (default is 20) 

ecc set default calling convention to_cdecl 

ecd set default calling convention to_stdcall 

ecf set default calling convention to_fastcall 

ecp set default calling convention to_pascal 

ecr set default calling convention to_fortran 

ecs set default calling convention to_syscall 

ecw set default calling convention to_watcall (default) 

ee call epilogue hook routine 

ef use full path names in error messages 

ei force enum base type to use at least an int 

em force enum base type to use minimum 

en emit routine name before prologue 

ep[<number>] call prologue hook routine with number of stack bytes available 
eq do not display error messages (they are still written to a file) 

er (C++ only) do not recover from undefined symbol errors 

et Pentium profiling 

ew (C++ only) generate less verbose messages 

ez (32-bit only) generate Phar Lap Easy OMF-386 object file 

fc=<file_name> (C++ only) specify file of command lines to be batch processed 
fh[q][=<file_name>] use precompiled headers 

fhd store debug info for pre-compiled header once (DWARF only) 

fhr (C++ only) force compiler to read pre-compiled header 

fhw (C++ only) force compiler to write pre-compiled header 

fhwe (C++ only) don't include pre-compiled header warnings when "we" is used 

fi=<file_name> force file_name to be included 

fo=<file_name> set object or preprocessor output file specification 


fpc 

fpi 


fpi87 


generate calls to floating-point library 

(16-bit only) generate in-line 80x87 instructions with emulation (default) 

(32-bit only) generate in-line 387 instructions with emulation (default) 
(16-bit only) generate in-line 80x87 instructions 


(32-bit only) generate in-line 387 instructions 
fp2 generate in-line 80x87 instructions 

fp3 generate in-line 387 instructions 
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fp5 generate in-line 80x87 instructions optimized for Pentium processor 

fp6 generate in-line 80x87 instructions optimized for Pentium Pro processor 

fpd enable generation of Pentium FDIV bug check code 

fpr generate 8087 code compatible with older versions of compiler 

fr=<file_name> set error file specification 

ft (C++ only) try truncated (8.3) header file specification 

fti (C only) track include file opens 

fx (C++ only) do not try truncated (8.3) header file specification 

fzh (C++ only) do not automatically append extensions for include files 

fzs (C++ only) do not automatically append extensions for source files 

g=<codegroup> set code group name 

h{w,d,c} set debug output format (Open Watcom, Dwarf, CodeView) 

i=<directory> add directory to list of include directories 
j change char default from unsigned to signed 

k (C++ only) continue processing files (ignore errors) 

mff,s,m,c,l,h} memory model — mf=flat ms=small mm=medium mc=compact ml=large mh=huge 
(default is "ms" for 16-bit and Netware, "mf" for 32-bit) 
nc=<name> set name of the code class 
nd=<name> set name of the "data" segment 
nm=<name> set module name different from filename 
nt=<name> set name of the "text" segment 
o{a,b,c,d,eJ'J+,h,i,i+,k,l,l+,m,n,o,p,r,s,t,u,x,z} control optimization 
pil preprocessor ignores #line directives 

p{e,l,c,w=<num>} preprocess file only, sending output to standard output; "c" include comments; "e" 

encrypt identifiers (C++ only); "1" include #line directives; w=<num> wrap output lines 
at <num> columns (zero means no wrap) 
q operate quietly 

r save/restore segment registers 

ri return chars and shorts as ints 

s remove stack overflow checks 

sg generate calls to grow the stack 

st touch stack through SS first 

t=<num> (C++ only) set tab stop multiplier 

u<name> preprocessor #undef name 

v output function declarations to .def file (with typedef names) 

vc... (C++ only) VC++ compatibility options 

w<number> set warning level number (default is wl) 

wcd=<num> warning control: disable warning message <num> 

wce=<num> warning control: enable warning message <num> 

we treat all warnings as errors 

wo (C only) (16-bit only) warn about problems with overlaid code 

wx set warning level to maximum setting 

x preprocessor ignores environment variables 

xd (C++ only) disable exception handling (default) 

xdt (C++ only) disable exception handling (same as "xd") 

xds (C++ only) disable exception handling (table-driven destructors) 

xr (C++ only) enable RTTI 

xs (C++ only) enable exception handling 

xst (C++ only) enable exception handling (direct calls for destruction) 

xss (C++ only) enable exception handling (table-driven destructors) 

xx ignore default directories for file search (,,../h,../c,...) 

z{a,e} disable/enable language extensions (default is ze) 
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zam 

zat 

zc 

zd{f,p} 

zdl 

zev 

zf 

zf{f,p} 

zfw 

Zg 

Zg{f,p} 

zkO 

zkOu 

zkl 

zk2 

zkl 

zku=<codepage> 

zl 

zld 

zlf 

zls 

zm 

zmf 

zp[{l,2,4,8,16}] 

zpw 

zq 

zri 

zro 

zs 

zt<number> 

zu 

zv 

zw 

zW 

zWs 

zz 


disable all predefined old extension macros (keyword macros, non-ISO names) 
(C++ only) disable alternative tokens 
place literal strings in code segment 

allow DS register to "float" or "peg" it to DGROUP (default is zdp) 

(32-bit only) load DS register directly from DGROUP 

(C only, Unix extension) enable arithmetic on void derived types 

(C++ only) let scope of for loop initialization extend beyond loop 

allow FS register to be used (default for all but flat memory model) or not be used 

(default for flat memory model) 

generate FWAIT instructions on 386 and later 

output function declarations to .def (without typedef names) 

allow GS register to be used or not used 

double-byte char support for Kanji 

translate Kanji double-byte characters to UNICODE 

double-byte char support for Chinese/Taiwanese 

double-byte char support for Korean 

double-byte char support if current code page has lead bytes 
load UNICODE translate table for specified code page 
suppress generation of library file names and references in object file 
suppress generation of file dependency information in object file 
add default library information to object files 

remove automatically inserted symbols (such as runtime library references) 

place each function in separate segment (near functions not allowed) 

place each function in separate segment (near functions allowed) 

set minimal structure packing (member alignment) 

output warning when padding is added in a struct/class 

operate quietly 

inline floating point rounding code 
omit floating point rounding code 
syntax check only 

set data threshold (default is zt32767) 
do not assume that SS contains segment of DGROUP 
(C++ only) enable virtual function removal optimization 
Microsoft Windows prologue/epilogue code sequences 

(16-bit only) Microsoft Windows optimized prologue/epilogue code sequences 
(16-bit only) Microsoft Windows smart callback sequences 
remove "@size" from_stdcall function names (10.0 compatible) 


See the Open Watcom C/C++ User’s Guide for a full description of compiler options. 


Linker options: Description: 

bcl=<system name> Compile and link for the specified system name. See the section for link option '1=’ 
below and the linker user guide for available system names. This is equivalent to 
specifying -bt=<system name> and -l=<system name>. 
k<stack_size> set stack size 

fd[=<directive_Jile>] keep directive file and, optionally, rename it (default name is "_WCL_.LNK"). 

fe=<executable> name executable file 

fm[=<map_Jile>] generate map file and name it (optional) 

Ip (16-bit only) create an OS/2 protected-mode program 

Ir (16-bit only) create a DOS real-mode program 

l=<system_name> link a program for the specified system. Among the supported systems are: 
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286 16-bit DOS executables (synonym for "DOS") under DOS and NT hosted 

platforms; 16-bit OS/2 executables (synonym for "OS2") under 32-bit 
OS/2 hosted OS/2 session. 

386 32-bit DOS executables (synonym for "DOS4G") under DOS; 32-bit NT 

character-mode executables (synonym for "NT") under Windows NT; 
32-bit OS/2 executables (synonym for "OS2V2") under 32-bit OS/2 
hosted OS/2 session. 

COM 16-bit DOS "COM" files 

DOS 16-bit DOS executables 

DOS4G 32-bit Tenberry Software DOS Extender executables 

DOS4GNZ 32-bit Tenberry Software DOS Extender non-zero base executables 
NETWARE 32-bit Novell NetWare 386 NLMs 

NOVELL 32-bit Novell NetWare 386 NLMs (synonym for NETWARE) 

NT 32-bit Windows NT character-mode executables 

NT_DLL 32-bit Windows NT DLLs 

NT_WIN 32-bit Windows NT windowed executables 

OS2 16-bit OS/2 Vl.x executables 

OS2_DLL 16-bit OS/2 DLLs 

OS2_PM 16-bit OS/2 PM executables 

OS2V2 32-bit OS/2 executables 

OS2V2_DLL 32-bit OS/2 DLLs 

OS2 V2_PM 32-bit OS/2 PM executables 

PHARLAP 32-bit PharLap DOS Extender executables 

QNX 16-bit QNX executables 

QNX386 32-bit QNX executables 

TNT 32-bit Phar Lap TNT DOS-style executable 

WIN386 32-bit extended Windows 3.x executables/DLLs 

WIN95 32-bit Windows 9x executables/DLLs 

WINDOWS 16-bit Windows executables 

WINDOWS_DLL 16-bit Windows Dynamic Link Libraries 

X32R 32-bit FlashTek (register calling convention) executables 

X32RV 32-bit FlashTek Virtual Memory (register calling convention) executables 

X32S 32-bit FlashTek (stack calling convention) executables 

X32SV 32-bit FlashTek Virtual Memory (stack calling convention) executables 

These names are among the systems identified in the Open Watcom Linker initialization 
file, "WLSYSTEM.LNK". The Open Watcom Linker "SYSTEM" directives, found in 
this file, are used to specify default link options for particular (operating) systems. Users 
can augment the Open Watcom Linker initialization file with their own system definitions 
and these may be specified as an argument to the "1=" option. The "system_name" 
specified in the "1=" option is used to create a "SYSTEM system_name" Open Watcom 
Linker directive when linking the application. 

@<directive_Jile> include additional directive file 
"linker directives" allows use of any linker directive 

1.3 WCUWCL386 Environment Variables 

The WCL environment variable can be used to specify commonly used WCL options. The WCL386 
environment variable can be used to specify commonly used WCL386 options. These options are 
processed before options specified on the command line. 
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Example: 

C>set wcl=-dl -ot 
C>set wcl386=-dl -ot 

The above example defines the default options to be "dl" (include line number debugging information in 
the object file), and "ot" (favour time optimizations over size optimizations). 

Whenever you wish to specify an option that requires the use of an "=" character, you can use the "#" 
character in its place. This is required by the syntax of the "SET" command. 

Once the appropriate environment variable has been defined, those options listed become the default each 
time the WCL or WCL386 command is used. 

The WCL environment variable is used by WCL only. The WCL386 environment variable is used by 
WCL386 only. Both WCL and WCL386 pass the relevant options to the Open Watcom C/C++ compiler 
and linker. This environment variable is not examined by the Open Watcom C/C++ compiler or the linker 
when invoked directly. 


Hint: If you are running DOS and you use the same WCL or WCL386 options all the time, you may 
find it handy to place the "SET WCL" or "SET WCL386" command in your DOS system initialization 
file, AUTOEXEC . BAT . If you are running OS/2 and you use the same WCL or WCL386 options all 
the time, you may find it handy to place the "SET WCL" or "SET WCL386" command in your OS/2 
system initialization file, CONFIG. SYS . 


1.4 WCL/WCL386 Command Line Examples 

For most small applications, the WCL or WCL386 command will suffice. We have only scratched the 
surface in describing the capabilities of the WCL and WCL386 commands. The following examples 
describe the WCL and WCL386 commands in more detail. 

Suppose that your application is contained in three files called apdemo . c, aputils . c, and 
apdata. c . We can compile and link all three files with one command. 

Example 1: 

C>wcl -d2 apdemo.c aputils.c apdata.c 
C>wcl386 -d2 apdemo.c aputils.c apdata.c 

The executable program will be stored in apdemo . exe since apdemo appeared first in the list. Each of 
the three files is compiled with the "d2" debug option. Debugging information is included in the executable 
file. 

We can issue a simpler command if the current directory contains only our three C/C++ source files. 

Example 2: 

C>wcl -d2 *.c 
C>wcl386 -d2 *.c 

WCL or WCL386 will locate all files with the ".c" filename extension and compile each of them. The name 
of the executable file will depend on which of the C/C++ source files is found first. Since this is a 
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somewhat haphazard approach to naming the executable file, WCL and WCL386 have an option, "fe", 
which will allow you to specify the name to be used. 

Example 3: 

C>wcl -d2 -fe=apdemo *.c 
C>wcl386 -d2 -fe=apdemo *.c 

By using the "fe" option, the executable file will always be called apdemo. exe regardless of the order of 
the C/C++ source files in the directory. 

If the directory contains other C/C++ source files which are not part of the application then other tricks may 
be used to identify a subset of the files to be compiled and linked. 

Example 4: 

C>wcl -d2 -fe=apdemo ap*.c 
C>wcl386 -d2 -fe=apdemo ap*.c 

Here we compile only those C/C++ source files that begin with the letters "ap". 

In our examples, we have recompiled all the source files each time. In general, we will only compile one of 
them and include the object code for the others. 

Example 5: 

C>wcl -d2 -fe=apdemo aputils.c ap*.obj 
C>wcl386 -d2 -fe=apdemo aputils.c ap*.obj 

The source file aputils . c is recompiled and apdemo . ob j and apdata . ob j are included when 
linking the application. The ".obj" filename extension indicates that this file need not be compiled. 

Example 6: 

C>wcl -fe=demo *.c utility.obj 
C>wcl386 -fe=demo *.c utility.obj 

All of the C/C++ source files in the current directory are compiled and then linked with utility .obj to 
generate demo . exe . 

Example 7: 

C>set wcl=-mm -dl -ox -k4096 

C>wcl -fe=grdemo gr*.c graph.lib -fd=grdemo 

C>set wcl386=-dl -ox -k4096 

C>wcl386 -fe=grdemo gr*.c graph.lib -fd=grdemo 

All C/C++ source files beginning with the letters "gr" are compiled and then linked with graph . lib to 
generate grdemo . exe which uses a 4K stack. The temporary linker directive file that is created by WCL 
or WCL386 will be kept and renamed to grdemo . Ink . 
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Example 8: 

C>set libos2=c:\watcom\lib286\os2;c:\os2 
C>set lib=c:\watcom\lib286\dos;c:\watcom\lib286 
C>set wcl=-mm -lp 

C>wcl grdemol \watcom\lib286\os2\graphp.obj phapi.lib 

The file grdemol is compiled for the medium memory model and then linked with graphp. ob j and 
phapi . lib to generate grdemol. exe which is to be used with Phar Lap’s 286 DOS Extender. The 
"lp" option indicates that an OS/2 format executable is to be created. The file graphp. ob j in the 
directory "\WATCOM\LIB286\OS2" contains special initialization code for Phar Lap’s 286 DOS Extender. 
The file phapi . lib is part of the Phar Lap 286 DOS Extender package. The LIBOS2 environment 
variable must include the location of the OS/2 libraries and the LIB environment variable must include the 
location of the DOS libraries (in order to locate graph. lib). The LIBOS2 environment variable must 
also include the location of the OS/2 file doscalls . lib which is usually "C:\OS2". 

For more complex applications, you should use the "Make" utility. 
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2 The Open Watcom C/C++ POSIX-like Compiler 
Driver 


The Open Watcom C/C++ POSIX-like Compiler Driver is designed for generating applications, simply and 
quickly, using a single command line. On the command line, you can list source file names as well as 
object file names. Source files are either compiled or assembled based on file extension; object files and 
libraries are simply included in the link phase. Options can be passed on to both the compiler and linker. 


2.1 owcc Command Line Format 

The format of the command line is: 


owcc [options] [files] 


The square brackets [ ] denote items which are optional. 

The files and options may be specified in any order. The owcc utility uses the extension of the file name to 
determine if it is a source file, an object file, or a library file. Files with extensions of "o" and "lib" are 
assumed to be object files and library files respectively. Files with extensions of "asm" are assumed to be 
assembler source files and will be assembled by the Open Watcom Assembler. Files with any other 
extension, including none at all, are assumed to be C/C++ source files and will be compiled. Pattern 
matching characters ("*" and "?") may be used in the file specifications. 

If no file extension is specified for a file name then the owcc utility will check for a file with one of the 
following extensions. 


Order 

Name.Ext 

Assumed to 

be 

1. 

file.asm 

Assembler source 

2. 

file.cxx 

C++ 

source 

code 

3. 

file.cpp 

C++ 

source 

code 

4 . 

file.cc 

C++ 

source 

code 

5. 

file.c 

C 

source 

code 


It checks for each file in the order listed. By default, the Open Watcom Assembler will be selected to 
compile files with the extension "asm". By default, the Open Watcom C++ compiler will be selected to 
compile files with any of the extensions "cxx", "cpp" or "cc". By default, the Open Watcom C compiler 
will be selected to compile a file with a "c" extension. The default selection of compiler can be overridden 
by the "-x" option, described below. 

Options are prefixed with a dash (—) and may be specified in any order. Option names were chosen to 
resemble those of the GNU Compiler Collection (a.k.a. GCC). They are translated into Open Watcom 
C/C++ options, or to directives for the Open Watcom C/C++ wlink utility, accordingly. A summary of 
options is displayed on the screen by running the compiler driver like this: "owcc -?". If run without any 
arguments the compiler driver just displays its name and hints towards the option. 
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2.2 owcc Options Summary 

General options: Description: 

c compile the files only, do not link them 

S compile the source file(s), then run the Open Watcom C/C++ disassembler on the 

generated object file(s) instead of linking them. Please note that this leaves you with both 
an object file and an assembly source file. Unix compilers traditionally compile by 
generating asm source and pass that to the assembler, so there, the "-S" option is done by 
stopping short of assembling the file. Open Watcom C/C++ compiles directly to object 
files, so we need the disassembler to achieve a similar effect. 
x {c,c++} treat all source files as written in the specified programming language, regardless of 

filename suffix. 

o <filename> Change the name of the generated file. If only the preprocessor is run, this sends the 

preprocessed output to a file instead of the standard output stream. If only compilation is 
done, this allows to change the name of the object file. If compilation and disassembly is 
done, this changes the name of the assembly source file. If owcc runs the linker, this 
changes the name of the generated executable or DLL. 
v operate verbosely, displaying the actual command lines used to invoke the compiler and 

linker, and passing flags to them to operate verbosely, too. 
zq operate quietly (default). This is the opposite of the "-v" option. 

Compiler options: Description: 

march=i{,l,2,3}86,axp,mips,ppc which CPU architecture instruction set is used 
mtnne=i{3,4,5,6}86 which x86 CPU type to optimize for 
mregparm=l use register-based argument passing conventions (default) 
mregparm=0 use stack-based argument passing conventions 
MMD generate auto depend makefile fragment 

MF <file> change name of makefile style auto depend file. Without this option, the filename is the 

same as the the base name of the source file, with a suffix of ".d". 

MT <target> specify target name generated in makefile style auto depend different than that of the 
object file name 

mconsole build target is a console application 

shared build target is a Dynamic Link Library (DLL) 

mwindows build target is a GUI application 

mthreads build target is a multi-thread environment 

mrtdll build target uses DLL version of C/C++ run-time libraries 

mdefault-windowing build target uses default windowing support 

gO (C++ only) no debugging information 

gl line number debugging information 

gl+ (C only) line number debugging information plus typing information for global symbols 

and local structs and arrays 

g2 full symbolic debugging information 

g2i (C++ only) d2 and debug inlines; emit inlines as external out-of-line functions 

g2s (C++ only) d2 and debug inlines; emit inlines as static out-of-line functions 

g2t (C++ only) full symbolic debugging information, without type names 

g3 full symbolic debugging with unreferenced type names ,* 

g3i (C++ only) d3 plus debug inlines; emit inlines as external out-of-line functions 

g3s (C++ only) d3 plus debug inlines; emit inlines as static out-of-line functions 

g{w,d,c} set debug output format (Open Watcom, Dwarf, CodeView) 
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D<ncime>[=text] preprocessor #define name [text] 

D+ allow extended -D macro definitions 

Jbrowser generate browsing information 

Wstop-after-errors=<number> set error limit number (default is 20) 
mabi={cdecl,stdcalljastcall,pascalfortran,syscall,watcall} set default calling convention 
fhook-epilogue call epilogue hook routine 

fmessage-full-path use full path names in error messages 
fno-short-enum force enum base type to use at least an int 
fshort-enum force enum base type to use minimum 

femit-names emit routine name before prologue 

fhook-prologue[=<number>] call prologue hook routine with number of stack bytes available 

include <file_name> force file_name to be included in front of the source file text 

fo=<file_name> set object or preprocessor output file specification 

msoft-float generate calls to floating-point library 

fpmath=287 generate in-line 80x87 instructions 

fpmath=387 generate in-line 387 instructions 

fptune=586 generate in-line 80x87 instructions optimized for Pentium processor 

fptune=686 generate in-line 80x87 instructions optimized for Pentium Pro processor 

fr=<file_name> enable error file creation and specify its name 
H (C only ) track include file opens 

I add directory to the list of include directories 

fsigned-char change char default from unsigned to signed 
k (C++ only) continue processing files (ignore errors) 

mcmodel={f,s,m,c,l,h} select a memory model from these choices: 

/ flat 

s small 

m medium 

c compact 

/ large 

h huge 

t compile code for the small memory model and then use the Open 

Watcom Linker to generate a "COM" file 

The default is small for 16-bit and Netware, flat for 32-bit targets. 

OO turn off all optimization 

Ol enable some optimazion 

02 enable most of the usual optimizations 

03 enable even more optimizations 

fno-strict-aliasing relax alias checking 
fguess-branch-probability branch prediction 
fno-optimize-sibling-calls disable call/ret optimization 
finline-functions expand functions inline 
f inline-limit-num which functions to expand inline 
fno-omit-frame-pointer generate traceable stack frames 
fno-omit-leaf-frame-pointer generate more stack frames 
frerun-optimizer enable repeated optimizations 

finline-intrinsics[-max] inline intrinsic functions [-max: more aggressively] 

fschedule-prologue control flow entry/exit seq. 

floop-optimize perform loop optimizations 

funroll-loops perform loop unrolling 

finline-math generate inline math functions 
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funsafe-math-optimizations numerically unstable floating-point 
ffloat-store improve floating-point consistency 

fschedule-insns re-order instructions to avoid stalls 
fkeep-duplicates ensure unique addresses for functions 
fignore-line-directives preprocessor ignores #line directives 

E preprocess sources, sending output to standard output or filename selected via -o 

C include original comments in -E output 

P don’t include #line directives in -E output 

fcpp-wrap=<num> wrap output lines at <num> columns (zero means no wrap ) 
ftabstop=<num> (C++ only) set tab stop multiplier 
fno-stack-check remove stack overflow checks 
fgrow-stack generate calls to grow the stack 
fstack-probe touch stack through SS first 

V <name> preprocessor #undef name 

fwrite-def output function declarations to .def file (with typedef names) 

w turn off all warnings (same as WlevelO) 

Wall turn on most warnings, but not all (same as Wlevel4) 

Wlevel<number> set warning level number (default is wl) 

Wextra set warning level to maximum setting 

Wno-n<num> warning control: disable warning message <num> 

Wn<num> warning control: enable warning message <num> 

Werror treat all warnings as errors 

Woverlay (C only) warn about problems with overlaid code 

frtti (C++ only) enable RTTI 

fno-eh (C++ only) disable exception handling (default) 

fell (C++ only) enable exception handling 

fell-direct (C++ only) enable exception handling (direct calls for destruction) 

fell-table (C++ only) enable exception handling (table-driven destructors) 

std={c89,c99,ow} select language dialect; c89 is (almost) strictly ANSI/ISO standard C89 only, c99 enables 
C99 support (may be incomplete), ow enables all Open Watcom C/C++ extensions. 
fno-writable-strings place literal strings in code segment 

fvoid-ptr-arithmetics (C only, Unix extension) enable arithmetic on void derived types 
fwrite-def-witliout-typedefs output function declarations to .def (without typedef names) 
fnostdlib suppress generation of library file names and references in object file 

ffunction-sections place each function in separate segment (near functions not allowed) 
fpack-struct=[{l,2,4,8,16}] set minimal structure packing (member alignment) 

Wpadded output warning when padding is added in a struct/class 

finline-fp-rounding inline floating point rounding code 
fomit-fp-rounding omit floating point rounding code 
fnonconst-initializers allow non-constant initializers 
fsyntax-only syntax check only 

See the Open Watcom C/C++ User’s Guide for a full description of compiler options. 

Linker options: Description: 

b <target name> Compile and link for the specified target system name. See the section linker user guide 
for available system names. The linker will effectively receive a -l=<target name> 
option, owcc looks up <system name> in a specification table "specs.owe" to find out 
which of the Open Watcom C utilities to run. One those options will be -bt=<os>, where 
<os> is the generic target platform name, and usually less specific than the linker <system 
name>. Among the supported systems are: 
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286 16-bit DOS executables (synonym for "DOS") under DOS and NT hosted 

platforms; 16-bit OS/2 executables (synonym for "OS2") under 32-bit 
OS/2 hosted OS/2 session. 

386 32-bit DOS executables (synonym for "DOS4G") under DOS; 32-bit NT 

character-mode executables (synonym for "NT") under Windows NT; 
32-bit OS/2 executables (synonym for "OS2V2") under 32-bit OS/2 
hosted OS/2 session. 

COM 16-bit DOS "COM" files 

DOS 16-bit DOS executables 

DOS4G 32-bit Tenberry Software DOS/4G DOS Extender executables 

DOS4GNZ 32-bit Tenberry Software DOS/4G DOS Extender non-zero base 

executables 

NETWARE 32-bit Novell NetWare 386 NLMs 

NOVELL 32-bit Novell NetWare 386 NLMs (synonym for NETWARE) 

NT 32-bit Windows NT character-mode executables 

NT_DLL 32-bit Windows NT DLLs 

NT_WIN 32-bit Windows NT windowed executables 

OS2 16-bit OS/2 Vl.x executables 

OS2_DLL 16-bit OS/2 DLLs 

OS2_PM 16-bit OS/2 PM executables 

OS2V2 32-bit OS/2 executables 

OS2V2_DLL 32-bit OS/2 DLLs 

OS2 V2_PM 32-bit OS/2 PM executables 

PHARLAP 32-bit PharLap DOS Extender executables 

QNX 16-bit QNX executables 

QNX386 32-bit QNX executables 

TNT 32-bit Phar Lap TNT DOS-style executable 

WIN386 32-bit extended Windows 3.x executables/DLLs 

WIN95 32-bit Windows 9x executables/DLLs 

WINDOWS 16-bit Windows executables 

WINDOWS_DLL 16-bit Windows Dynamic Link Libraries 

X32R 32-bit FlashTek (register calling convention) executables 

X32RV 32-bit FlashTek Virtual Memory (register calling convention) executables 

X32S 32-bit FlashTek (stack calling convention) executables 

X32SV 32-bit FlashTek Virtual Memory (stack calling convention) executables 

These names are among the systems identified in the Open Watcom Linker initialization 
file, "wlsystem.lnk". The Open Watcom Linker "SYSTEM" directives, found in this file, 
are used to specify default link options for particular (operating) systems. Users can 
augment the Open Watcom Linker initialization file with their own system definitions 
and these may be specified as an argument to the "1=" option. The "system_name" 
specified in the "1=" option is used to create a "SYSTEM system_name" Open Watcom 
Linker directive when linking the application. 
mstack-size=<size> set stack size 

fd[=<directive_file>] keep linker directive file generated by this tool and, optionally, rename it (default 
name is "_owcc_.Ink"). 

fm[=<map_Jile>] generate map file, optionally specify its name. 

s strip symbolic information not strictly required to run from executable. 

Wl, "directives " send any supplementary directives directly to the linker 

Wl,@<file> include additional linker directives from <file>. This is actually just a special case of - Wl 
used to pass the linker’s @ directive to pull in directives from <file> 
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2.3 owcc Command Line Examples 

For most small applications, the owcc command will suffice. We have only scratched the surface in 
describing the capabilities of the owcc command. The following examples describe the owcc commands in 
more detail. 

Suppose that your application is contained in three files called apdemo . c, aputils . c, and 
apdata . c . We can compile and link all three files with one command. 

Example 1: 

C>owcc -g apdemo.c aputils.c apdata.c 

The executable program will be stored in a. out. Each of the three files is compiled with the "g" debug 
option. Debugging information is included in the executable file. 

We can issue a simpler command if the current directory contains only our three C/C++ source files. 

Example 2: 

C>owcc -g *.c 

owcc will locate all files with the ".c" filename extension and compile each of them. The default name of 
the executable file will be a. out. Since it is only possible to have one executable with the name a . out 
in a directory, owcc has an option, "o", which will allow you to specify the name to be used. 

Example 3: 

C>owcc -g -o apdemo *.c 

By using the "o" option, the executable file will always be called apdemo . 

If the directory contains other C/C++ source files which are not part of the application then other tricks may 
be used to identify a subset of the files to be compiled and linked. 

Example 4: 

C>owcc -g -o apdemo ap*.c 

Here we compile only those C/C++ source files that begin with the letters "ap". 

In our examples, we have recompiled all the source files each time. In general, we will only compile one of 
them and include the object code for the others. 

Example 5: 

C>owcc -g -o apdemo aputils.c ap*.obj 

The source file aputils . c is recompiled and apdemo . ob j and apdata . ob j are included when 
linking the application. The ".obj" filename extension indicates that this file need not be compiled. 

Example 6: 

C>owcc -o demo *.c utility.obj 

All of the C/C++ source files in the current directory are compiled and then linked with utility .obj to 
generate demo . The temporary linker directive file that is created by owcc will be kept and renamed to 
grdemo. Ink. 

For more complex applications, you should use a "Make" utility. 
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3 The Open Watcom Assembler 


3.1 Introduction 

This chapter describes the Open Watcom Assembler. It takes as input an assembler source file (a file with 
extension ".asm") and produces, as output, an object file. 

The Open Watcom Assembler command line syntax is the following. 

WASM [options] [d:][path]filename[.ext] [options] [@env_var] 

The square brackets [ ] denote items which are optional. 

WASM is the name of the Open Watcom Assembler. 

d: is an optional drive specification such as "A:", "B:", etc. If not specified, the default drive 

is assumed. 

path is an optional path specification such as "\PROGRAMS\ASM\". If not specified, the 

current directory is assumed. 

filename is the file name of the assembler source file to be assembled. 

ext is the file extension of the assembler source file to be assembled. If omitted, a file 

extension of ".asm" is assumed. If the period "." is specified but not the extension, the file 
is assumed to have no file extension. 

options is a list of valid options, each preceded by a slash ("/") or a dash Options may be 

specified in any order. 

The options supported by the Open Watcom Assembler are: 

/ 0,1,2,3,4, 5, 6} {pj [r, s} 

0 same as ".8086" 

1 same as ".186" 

2{p} same as ".286" or ”.286p" 

3{p} same as ".386" or ".386p" (also defines "_386_" and changes the default 

USE attribute of segments from "USE16" to "USE32") 

4{p} same as ".486" or ".486p" (also defines "_386_" and changes the default 

USE attribute of segments from "USE16" to "USE32") 

5{p} same as ".586" or ".586p" (also defines "_386_" and changes the default 

USE attribute of segments from "USE16" to "USE32") 

6{p} same as ".686" or ".686p" (also defines "_386_" and changes the default 

USE attribute of segments from "USE16" to "USE32") 
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p 

protect mode 

add r 

defines "_REGISTER_" 

add s 

defines "_STACK_" 

Example: 

-2 

-3p -4pr -5p 


bt=<os> defines "_<os>_" and checks the "<os>_INCLUDE" environment variable for include 

files 

c do not output OMF COMENT records that allow WDISASM to figure out when data bytes 

have been placed in a code segment 
d<name>[=text] define text macro 
dl line number debugging support 

e stop reading assembler source file at END directive. Normally, anything following the 

END directive will cause an error. 
e<number> set error limit number 

fe=<file_name> set error file name 
fo=<file_name> set object file name 
fi=<file_name> force <file_name> to be included 


fpc 

same as ".no87" 

fpi 

inline 80x87 instructions with emulation 

fpi87 

inline 80x87 instructions 

fpO 

same as ".8087" 

fp2 

same as ".287" or ”.287p" 

fp3 

same as ".387" or ”.387p" 

fp5 

same as ".587" or ”.587p" 

fp6 

same as ".687" or ”.687p" 


i=<directory> add directory to list of include directories 

j or s force signed types to be used for signed values 

m{t,s,m,c,l,hj} memory model: (Tiny, Small, Medium, Compact, Large, Huge, Flat) 


-mt 

Same as ".model tiny" 

-ms 

Same as ".model small" 

-mm 

Same as ".model medium" 

-me 

Same as ".model compact" 

-ml 

Same as ".model large" 

-mh 

Same as ".model huge" 

-mf 

Same as ".model flat" 


Each of the model directives also defines "_<model>_" (e.g., ".model small" defines 

"_SMALL_"). They also affect whether something like "foo proc" is considered a "far" 

or "near" procedure. 

set data segment name 

set module name 

set name of text segment 

allow C form of octal constants 

set compatibility mode - watcom, masm or tasm, if <mode> is not specified then masm is 
used, default mode is watcom 
remove file dependency information 
operate quietly 

remove "@size" from STDCALL function names 

don't mangle STDCALL symbols (WASM backward compatible) 

print this message 


nd=<name> 

nm=<name> 

nt—<name> 

o 

zcm=<mode> 

zld 

zq or q 

zz 

zzo 

? or h 
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w<number> set warning level number 

we treat all warnings as errors 

wx set warning level to maximum setting 

3.2 Assembler Directives, Operators and Assembly Opcodes 

It is not the intention of this chapter to describe assembly-language programming in any detail. You should 
consult a book that deals with this topic. However, we present an alphabetically ordered list of the 
directives, opcodes and register names that are recognized by the assembler. 


.186 

.286 

.287 

.386 

.486 

. 48 6p 

. 686 

. 68 6p 

addr 

alias 

and 

assume 

casemap 

catstr 

comment 

.const 

. data 

.data? 

df 

.dosseg 

dq 

dt 

dword 

echo 

elseif 

end 

endm 

endp 

eq 

equ 

. errb 

.errdef 

. erre 

.erridn 

.errndef 

.errnz 

exitm 

extern 

far 

.fardata 

fore 

fword 

group 

gt 

. if 

if 

ifb 

if def 

ife 

if idn 

ifndef 

include 

irp 

irpe 

le 

length 

. list 

.listall 

.listmacroall 

local 

lroffset 

It 

.mmx 

mod 

ne 

near 

.nolist 

offset 

org 

oword 

proc 

proto 

purge 

pushcontext 

.radix 

record 

. sail 

sbyte 

segment 

. seq 

sizeof 

.stack 

struct 

subtitle 

tbyte 

textequ 

title 

typedef 

uses 

.while 


,286c 

. 28 6p 

. 386p 

.387 

.586 

. 586p 

.8086 

.8087 

align 

.alpha 

.break 

byte 

. code 

comm 

. continue 

. cref 

db 

dd 

dosseg 

dp 

dup 

dw 

. else 

else 

.endif 

endif 

ends 

. endw 

equ2 

. err 

.errdif 

.errdifi 

.erridni 

.errnb 

even 

. exit 

externdef 

extrn 

.fardata? 

for 

ge 

global 

high 

highword 

if 1 

if 2 

ifdif 

ifdifi 

ifidni 

if nb 

includelib 

invoke 

. k3d 

label 

lengthof 

. Ifcond 

. listif 

.listmacro 

low 

lowword 

macro 

mask 

.model 

name 

. no87 

. nocref 

opattr 

option 

page 

popcontext 

ptr 

public 

pword 

qword 

.repeat 

repeat 

sdword 

seg 

.sfcond 

size 

. startup 

struc 

subttl 

sword 

. tfcond 

this 

union 

. until 

width 

word 
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.xcref 

.xlist 

. xmm3 


aaa 

aad 

adc 

add 

addsd 

addss 

and 

andnpd 

andps 

arpl 

bsf 

bsr 

btc 

btr 

calif 

cbw 

cld 

elflush 

cmc 

cmova 

cmovbe 

cmovc 

cmovge 

cmovl 

cmovnae 

cmovnb 

cmovne 

cmovng 

cmovnle 

cmovno 

cmovnz 

cmovo 

cmovpo 

cmovs 

cmpeqpd 

cmpeqps 

cmplepd 

cmpleps 

cmpltpd 

cmpltps 

cmpneqpd 

cmpneqps 

cmpnlepd 

cmpnleps 

cmpnltpd 

cmpnltps 

cmpordpd 

cmpordps 

cmppd 

cmpps 

cmpsd 

cmpss 

cmpunordps 

cmpunordsd 

cmpxchg8b 

comisd 

cvtdq2pd 

cvtdq2ps 

cvtpd2ps 

cvtpi2pd 

cvtps2pd 

cvtps2pi 

cvtsi2sd 

cvtsi2ss 

cvttpd2dq 

cvttpd2pi 

cvttsd2si 

cvttss2si 

daa 

das 

divpd 

divps 

emms 

enter 

f add 

f addp 

f chs 

f clex 

fcmove 

fcmovnb 

fcmovnu 

fcmovu 

fcomip 

f comp 

fdecstp 

fdisi 

f divr 

fdivrp 

f f ree 

f iadd 

f idiv 

fidivr 

fincstp 

finit 

fisttp 

f isub 

fid 

fldl 

fldenvd 

fldenvw 

fldlg2 

fldln2 

fmul 

fmulp 

f neni 

fninit 

fnrstord 

fnrstorw 

fnsavew 

fnstcw 

fnstenvw 

fnstsw 


. xmm . xmm2 


aam 

aas 

addpd 

addps 

addsubpd 

addsubps 

andnps 

andpd 

bound 

bp 

bswap 

bt 

bts 

call 

cdq 

clc 

cli 

cits 

cmovae 

cmovb 

cmove 

cmovg 

cmovle 

cmovna 

cmovnbe 

cmovnc 

cmovnge 

cmovnl 

cmovnp 

cmovns 

cmovp 

cmovpe 

cmovz 

cmp 

cmpeqsd 

cmpeqss 

cmplesd 

cmpless 

cmpltsd 

cmpltss 

cmpneqsd 

cmpneqss 

cmpnlesd 

cmpnless 

cmpnltsd 

cmpnltss 

cmpordsd 

cmpordss 

cmps 

cmpsb 

cmpsw 

cmpunordpd 

cmpunordss 

cmpxchg 

comiss 

cpuid 

cvtpd2dq 

cvtpd2pi 

cvtpi2ps 

cvtps2dq 

cvtsd2si 

cvtsd2ss 

cvtss2sd 

cvtss2si 

cvttps2dq 

cvttps2pi 

cwd 

cwde 

dec 

div 

divsd 

divss 

f 2 xml 

f abs 

fbld 

fbstp 

fcmovb 

fcmovbe 

fcmovnbe 

fcmovne 

f com 

f comi 

fcompp 

f cos 

fdiv 

fdivp 

f emms 

feni 

f icom 

ficomp 

fild 

f imul 

fist 

f istp 

fisubr 

flat 

f ldcw 

fldenv 

fldl2e 

fldl2t 

f 1dpi 

f ldz 

fnclex 

fndisi 

f nop 

fnrstor 

fnsave 

fnsaved 

fnstenv 

fnstenvd 

fpatan 

fprem 
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fpreml 

fptan 

frndint 

frstor 

frstord 

frstorw 

f save 

fsaved 

fsavew 

fscale 

fsetpm 

f sin 

fsincos 

f sqrt 

f St 

f stew 

fstenv 

f stenvd 

fstenvw 

f stp 

f stsw 

f sub 

f subp 

f subr 

fsubrp 

ftst 

fucom 

fucomi 

fucomip 

fucomp 

fucompp 

fwait 

f xam 

fxch 

fxrstor 

fxsave 

fxtract 

fyl2x 

fyl2xpl 

haddpd 

haddps 

hit 

hsubpd 

hsubps 

idiv 

imul 

in 

inc 

ins 

insb 

insd 

insw 

int 

into 

invd 

invlpg 

iret 

iretd 

iretdf 

iretf 

ja 

jae 

jb 

jbe 

jc 

jcxz 

je 

jeexz 

jg 

jge 

jl 

jle 

jmp 

jmpf 

jna 

jnae 

jnb 

jnbe 

jnc 

jne 

jng 

jnge 

jnl 

jnle 

jno 

jnp 

jns 

jnz 

jo 

jP 

jpe 

jpo 

js 

jz 

lahf 

lar 

lddqu 

ldmxcsr 

Ids 

lea 

leave 

les 

Ifence 

lfs 

lgdt 

lgs 

lidt 

lldt 

lmsw 

lock 

lods 

lodsb 

lodsd 

lodsw 

loop 

loopd 

loope 

looped 

loopew 

loopne 

loopned 

loopnew 

loopnz 

loopnzd 

loopnzw 

loopw 

loopz 

loopzd 

loopzw 

lsl 

lss 

ltr 

maskmovdqu 

maskmovq 

maxpd 

maxps 

maxsd 

maxss 

mfence 

minpd 

minps 

minsd 

minss 

monitor 

mov 

movapd 

movaps 

movd 

movddup 

movdq2q 

movdqa 

movdqu 

movhlps 

movhpd 

movhps 

movlhps 

movlpd 

movlps 

movmskpd 

movmskps 

movntdq 

movnti 

movntpd 

movntps 

movntq 

movq 

movq2dq 

movs 

movsb 

movsd 

movshdup 

movsldup 

movss 

movsw 

movsx 

movupd 

movups 

movzx 

mul 

mulpd 

mulps 

mulsd 

mulss 

mwait 

near 

neg 

nop 

not 

or 

orpd 

orps 

out 

outs 

outsb 

outsd 

outsw 

packssdw 

packsswb 

packuswb 

paddb 

paddd 

paddq 

paddsb 

paddsw 

paddusb 

paddusw 

paddw 

pand 

pandn 

pause 

pavgb 

pavgusb 

pavgw 

pempeqb 

pempeqd 

pempeqw 

pcmpgtb 

pcmpgtd 

pcmpgtw 

pextrw 

pf 2id 

pf 2iw 

pf acc 

pf add 

pfcmpeq 

pfempge 

pfempgt 

pfmax 

pfmin 

pfmul 

pfnacc 

pfpnacc 

pf rep 

pfrcpitl 

pfrcpit2 

pfrsqitl 
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pfrsqrt 

pf sub 

pi2fw 

pinsrw 

pmaxub 

pminsw 

pmulhrw 

pmulhuw 

pmuludq 

pop 

popf 

popf d 

prefetchnta 

prefetchtO 

prefetchw 

psadbw 

pshuflw 

pshufw 

psllq 

psllw 

psrld 

psrldq 

psubb 

psubd 

psubsw 

psubusb 

pswapd 

punpckhbw 

punpckhwd 

punpcklbw 

punpcklwd 

push 

pushd 

pushf 

pxor 

rcl 

rcr 

rdmsr 

rep 

repe 

rept 

repz 

retf 

retf d 

ror 

rsm 

sahf 

sal 

seas 

scasb 

seta 

setae 

setc 

sete 

setl 

setle 

setnb 

setnbe 

setng 

setnge 

setno 

setnp 

seto 

setp 

sets 

setz 

shl 

shld 

shrd 

shufpd 

sldt 

smsw 

sqrtps 

sqrtsd 

std 

sti 

stosb 

stosd 

sub 

subpd 

subss 

sysenter 

ucomisd 

ucomiss 

unpcklpd 

unpcklps 

wait 

wbinvd 

xchg 

xlat 

xorpd 

xorps 

ah 

al 

bl 

bx 

crO 

cr2 

cs 

cx 

dl 

drO 

dr3 

dr 6 

dx 

eax 

ecx 

edi 

esi 

esp 

mmO 

mml 

mm4 

mm 5 

si 

ss 


pfsubr 

pi2fd 

pmaddwd 

pmaxsw 

pminub 

pmovmskb 

pmulhw 

pmullw 

popa 

popad 

por 

prefetch 

prefetchtl 

prefetcht2 

pshufd 

pshufhw 

pslld 

pslldq 

psrad 

psraw 

psrlq 

psrlw 

psubq 

psubsb 

psubusw 

psubw 

punpekhdq 

punpckhqdq 

punpckldq 

punpcklqdq 

pusha 

pushad 

pushfd 

pushw 

repps 

repss 

rdpmc 

rdtsc 

repne 

repnz 

ret 

retd 

retn 

rol 

rsqrtps 

rsqrtss 

sar 

sbb 

scasd 

scasw 

setb 

setbe 

setg 

setge 

setna 

setnae 

setnc 

setne 

setnl 

setnle 

setns 

setnz 

setpe 

setpo 

sfence 

sgdt 

short 

shr 

shufps 

sidt 

sp 

sqrtpd 

sqrtss 

stc 

stmxcsr 

stos 

stosw 

str 

subps 

subsd 

sysexit 

test 

unpekhpd 

unpekhps 

verr 

verw 

wrmsr 

xadd 

xlatb 

xor 


ax 

bh 

eh 

cl 

cr3 

cr4 

dh 

di 

drl 

dr2 

dr7 

ds 

ebp 

ebx 

edx 

es 

f s 

gs 

mm2 

mm3 

mm6 

mm 7 

St 

stO 
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stl 

st2 

st3 

st4 

st5 

st6 

st7 

tr3 

tr4 

tr5 

tr 6 

tr7 

xmmO 

xmml 

xmm2 

xmm3 

xmm4 

xmm5 

xmm6 

xmm7 

i supported Directives 



Other assemblers support directives that this assembler does not. 

The following is a list of directives that 

are ignored by the Open Watcom Assembler (use of these directives results in a warning message). 

.alpha 

. cref 

. Ifcond 

. list 

. listall 

. listif 

.listmacro 

.listmacroall 

.nocref 

. nolist 

page 

. sail 

. seq 

.sfcond 

subtitle 

subttl 

.tfcond 

title 

.xcref 

.xlist 

The following is a list of directives that are flagged by the Open Watcom Assembler (use of these directives 

results in an error message). 



addr 

.break 

casemap 

catstr 

. continue 

echo 

. else 

endmacro 

.endif 

. endw 

. exit 

high 

highword 

. if 

invoke 

low 

lowword 

lroffset 

mask 

opattr 

option 

popcontext 

proto 

purge 

pushcontext 

.radix 

record 

.repeat 

. startup 

this 

typedef 

union 


. until 


.while 


width 


3.4 Open Watcom Assembler Specific 

There are a few specific features in Open Watcom Assembler 


3.4.1 Naming convention 


Convention 


Procedure 

Name 


Variable 

Name 


C 

WATCOM_ C 

SYSCALL 

STDCALL 

STDCALL 

STDCALL 

BASIC 

FORTRAN 

PASCAL 


*' 


*' 


see section Open Watcom 

' *' 

*@nn' 

’ *' 


' -k ' 
r a r 
r a r 
r a r 


r * r 
r * r 

r * f 

r * r 


name mangier 


r a r 
r a r 
r a r 


see note 1 
see note 2 
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Notes: 

1. In STDCALL procedures name ’nn’ is overall parametrs size in bytes. ’@nn’ is suppressed 
when -zz command line option is used (WATCOM 10.0 compatibility). 

2. STDCALL symbols mangling is suppressed by -zzo command line option (WASM backward 
compatible). 


3.4.2 Open Watcom "C" name mangier 

Command line Procedure Variable 

option Name Name 


0 , 1,2 

3,4,5,6 with r 
3,4,5,6 with s 


3.4.3 Calling convention 


Convention 

Vararg 

Parameters 
passed by 

Parameters 

order 

Cleanup caller 
stack 

C 

yes 

stack 

right to left 

no 

WATCOM_ C 

yes 

registers 

right to left 

see note 1 


yes 

stack 

right to left 

no 

SYSCALL 

yes 

stack 

right to left 

no 

STDCALL 

yes 

stack 

right to left 

yes see note 2 

BASIC 

no 

stack 

left to right 

yes 

FORTRAN 

no 

stack 

left to right 

yes 

PASCAL 

no 

stack 

left to right 

yes 


Notes: 

1. If any parameter is passed on the stack then WASM automaticaly cleanup caller stack. 

2. For STDCALL procedures WASM automaticaly cleanup caller stack, except case when vararg 
parameter is used. 

3.5 Open Watcom Assembler Diagnostic Messages 

1 Size doesn’t match with previous definition 

2 Invalid instruction with current CPU setting 

3 LOCK prefix is not allowed on this instruction 

4 REP prefix is not allowed on this instruction 

5 Invalid memory pointer 

6 Cannot use 386 addressing mode with current CPU setting 
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7 Too many base registers 

8 Invalid index register 

9 Scale factor must be 1, 2, 4 or 8 

10 invalid addressing mode with current CPU setting 

11 ESP cannot be used as index 

12 Too many base/index registers 

13 Memory offset cannot reference to more than one label 

14 Offset must be relocatable 

15 Memory offset expected 

16 Invalid indirect memory operand 

17 Cannot mix 16 and 32-bit registers 

18 CPU type already set 

19 Unknown directive 

20 Expecting comma 

21 Expecting number 

22 Invalid label definition 

23 Invalid use of SHORT, NEAR, FAR operator 

24 No memory 

25 Cannot use 386 segment register with current CPU setting 

26 POP CS is not allowed 

27 Cannot use 386 register with current CPU setting 

28 Only MOV can use special register 

29 Cannot use TR3, TR4, TR5 in current CPU setting 

30 Cannot use SHORT with CALL 

31 Only SHORT displacement is allowed 

32 Syntax error 

33 Prefix must be followed by an instruction 
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34 No size given before ’PTR’ operator 

35 Invalid IMUL format 

36 Invalid SHLD/SHRD format 

37 Too many commas 

38 Syntax error: Unexpected colon 

39 Operands must be the same size 

40 Invalid instruction operands 

41 Immediate constant too large 

42 Can not use short or near modifiers with this instruction 

43 Jump out of range 

44 Displacement cannot be larger than 32k 

45 Initializer value too large 

46 Symbol already defined 

47 Immediate data too large 

48 Immediate data out of range 

49 Can not transfer control to stack symbol 

50 Offset cannot be smaller than WORD size 

51 Can not take offset of stack symbol 

52 Can not take segment of stack symbol 

53 Segment too large 

54 Offset cannot be larger than 32k 

55 Operand 2 too big 

56 Operand 1 too small 

57 Too many arithmetic operators 

58 Too many open square brackets 

59 Too many close square brackets 

60 Too many open brackets 
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61 Too many close brackets 

62 Invalid number digit 

63 Assembler Code is too long 

64 Brackets are not balanced 

65 Operator is expected 

66 Operand is expected 

67 Too many tokens in a line 

68 Bracket is expected 

69 Illegal use of register 

70 Illegal use of label 

71 Invalid operand in addition 

72 Invalid operand in subtraction 

73 One operand must be constant 

74 Constant operand is expected 

75 A constant operand is expected in addition 

76 A constant operand is expected in subtraction 

77 A constant operand is expected in multiplication 

78 A constant operand is expected in division 

79 A constant operand is expected after a positive sign 

80 A constant operand is expected after a negative sign 

81 Label is not defined 

82 More than one override 

83 Label is expected 

84 Only segment or group label is allowed 

85 Only register or label is expected in override 

86 Unexpected end of file 

87 Label is too long 
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88 This feature has not been implemented yet 

89 Internal Error #1 

90 Can not take offset of group 

91 Can not take offset of segment 

92 Invalid character found 

93 Invalid operand size for instruction 

94 This instruction is not supported 

95 size not specified — BYTE PTR is assumed 

96 size not specified — WORD PTR is assumed 

97 size not specified — DWORD PTR is assumed 

500 Segment parameter is defined already 

501 Model parameter is defined already 

502 Syntax error in segment definition 

503 ’AT’ is not supported in segment definition 

504 Segment definition is changed 

505 Lname is too long 

506 Block nesting error 

507 Ends a segment which is not opened 

508 Segment option is undefined 

509 Model option is undefined 

510 No segment is currently opened 

511 Lname is used already 

512 Segment is not defined 

513 Public is not defined 

514 Colon is expected 

515 A token is expected after colon 

516 Invalid qualified type 
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51 7 Qualified type is expected 

518 External definition different from previous one 

519 Memory model is not found in .MODEL 

520 Cannot open include file 

521 Name is used already 

522 Library name is missing 

523 Segment name is missing 

524 Group name is missing 

525 Data emitted with no segment 

526 Seglocation is expected 

527 Invalid register 

528 Cannot address with assumed register 

529 Invalid start address 

530 Label is already defined 

531 Token is too long 

532 The line is too long after expansion 

533 A label is expected after colon 

534 Must be associated with code 

535 Procedure must have a name 

536 Procedure is alreadly defined 

537 Language type must be specified 

538 End of procedure is not found 

539 Local variable must immediately follow PROC or MACRO statement 

540 Extra character found 

541 Cannot nest procedures 

542 No procedure is currently defined 

543 Procedure name does not match 
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544 Vararg requires C calling convention 

545 Model declared already 

546 Model is not declared 

547 Backquote expected 

548 COMMENT delimiter expected 

549 End directive required at end of file 

550 Nesting level too deep 

551 Symbol not defined 

552 Insert Stupid warning #1 here 

553 Insert Stupid warning #2 here 

554 Spaces not allowed in command line options 

555 Error: 

556 Source File 

557 No filename specified. 

558 Out of Memory 

559 Cannot Open File - 

560 Cannot Close File - 

561 Cannot Get Start of Source File - 

562 Cannot Set to Start of Source File - 

563 Command Line Contains More Than 1 File To Assemble 

564 include path %s. 

565 Unknown option %s. Use /? for list of options. 

566 read more command tine from %s. 

567 Internal error in %s(%u) 

568 OBJECT WRITE ERROR !! 

569 NO LOR PHARLAP !! 

570 Parameter Required 
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571 Expecting closing square bracket 

572 Expecting file name 

573 Floating point instruction not allowed with /fpc 

574 Too many errors 

575 Build target not recognised 

576 Public constants should be numeric 

577 Expecting symbol 

578 Do not mix simplified and full segment definitions 

579 Parms passed in multiple registers must be accessed separately, use %s 

580 Ten byte variables not supported in register calling convention 

581 Parameter type not recognised 

582 forced error: 

583forced error: Value not equal to 0 : %d 
584forced error: Value equal to 0: %d 
585forced error: symbol defined: %s 
586forced error: symbol not defined: %s 
587forced error: string blank : <%s> 

588forced error: string not blank : <%s> 

589forced error: strings not equal: <%s> : <%s> 

590forced error: strings equal: <%s> : <%s> 

591 included by file %s(%d) 

592 macro called from file %s(%d) 

593 Symbol %s not defined 

594 Extending jump 

595 Ignoring inapplicable directive 

596 Unknown symbol class ’%s ’ 

597 Symbol class for ’%s ’ already established 
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598 number must be a power of 2 

599 alignment request greater than segment alignment 

600 ’%s ’ is already defined 

601 %u unclosed conditional directive(s) detected 
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4 The Open Watcom Library Manager 

4.1 Introduction 


The Open Watcom Library Manager can be used to create and update object library files. It takes as input 
an object file or a library file and creates or updates a library file. For OS/2, Winl6 and Win32 
applications, it can also create impoit libraries from Dynamic Link Libraries. 

An object library is essentially a collection of object files. These object files generally contain utility 
routines that can be used as input to the Open Watcom Linker to create an application. The following are 
some of the advantages of using library files. 

1. Only those modules that are referenced will be included in the executable file. This eliminates 
the need to know which object files should be included and which ones should be left out when 
linking an application. 

2. Libraries are a good way of organizing object files. When linking an application, you need only 
list one library file instead of several object files. 

The Open Watcom Library Manager currently runs under the following operating systems. 

•DOS 

•OS/2 

• QNX 

• Windows 


4.2 The Open Watcom Library Manager Command Line 

The following describes the Open Watcom Library Manager command line. 


WLIB [options_1 ] lib_file [options_2] [cmdjist] 


The square brackets "[]" denote items which are optional. 

lib_Jile is the file specification for the library file to be processed. If no file extension is specified, 

a file extension of "lib" is assumed. 

options_l is a list of valid options. Options may be specified in any order. If you are using a DOS, 
OS/2 or Windows-hosted version of the Open Watcom Library Manager, options are 
preceded by a "/" or "—" character. If you are using a UNIX-hosted version of the Open 
Watcom Library Manager, options are preceded by a "—" character. 
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options_2 is a list of valid options. These options are only permitted if you are running a DOS, OS/2 

or Windows-hosted version of the Open Watcom Library Manager and must be preceded 
by a "/" character. The "—" character cannot be used as an option delimiter for options 
following the library file name since it will be interpreted as a delete command. 

cmd_list is a list of commands to the Open Watcom Library Manager specifying what operations are 

to be performed. Each command in cmdjist is separated by a space. 

The following is a summary of valid options. Items enclosed in square brackets "[]" are optional. Items 
separated by an or-bar "I" and enclosed in parentheses "()" indicate that one of the items must be specified. 
Items enclosed in angle brackets "<>" are to be replaced with a user-supplied name or value (the "<>" are 
not included in what you specify). 

? display the usage message 

b suppress creation of backup file 

c perform case sensitive comparison 

d=<output_directory> 

directory in which extracted object modules will be placed 
fa output AR format library (host default ar format) 

fab output AR format library (BSD ar format) 

fac output AR format library (COFF ar format) 

fag output AR format library (GNU ar format) 

fm output MLIB format library 

fo output OMF format library 

li display the usage message 

ia generate AXP import records 

ii generate X86 import records 

ip generate PPC import records 

ie generate ELF import records 

ic generate COFF import records 

io generate OMF import records 

i(r\n)(n\o) imports for the resident/non-resident names table are to be impoited by name/ordinal. 
l[=<list_file>] create a listing file 
m display C++ mangled names 

n always create a new library 

o=<output_file> 

set output file name for library 
p=<record_size> 

set library page size (supported for "OMF" library format only) 
pa set optimal library page size automaticaly (supported for "OMF" library format only) 

q suppress identification banner 

s strip line number records from object files (supported for "OMF" library format only) 

t remove path information from module name specified in THEADR records (supported for 

"OMF" library format only) 
v do not suppress identification banner 

x extract all object modules from library 

zld strip file dependency info from object files (supported for "OMF" library format only) 

The following sections describe the operations that can be performed on a library file. Note that before 
making a change to a library file, the Open Watcom Library Manager makes a backup copy of the original 
library file unless the "o" option is used to specify an output library file whose name is different than the 
original library file, or the "b" option is used to suppress the creation of the backup file. The backup copy 
has the same file name as the original library file but has a file extension of "bak". Hence, Iib_file should 
not have a file extension of "bak". 
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4.3 Open Watcom Library Manager Module Commands 

The following is a summary of basic Open Watcom Library Manager module manipulation commands: 

+ add module to a library 

remove module from a library 

* or: extract module from a library (: is used with a UNIX-hosted version of the Open Watcom 

Library Manager, otherwise * is used) 

++ add import library entry 

4.4 Adding Modules to a Library File 

An object file can be added to a library file by specifying a +obj_file command where obj_file is the file 
specification for an object file. If you are using a DOS, OS/2 or Windows-hosted version of the Open 
Watcom Library Manager, a file extension of "obj" is assumed if none is specified. If you are using a 
UNIX-hosted version of the Open Watcom Library Manager, a file extension of "o" is assumed if none is 
specified. If the library file does not exist, a warning message will be issued and the library file will be 
created. 

Example: 

wlib mylib +myobj 

In the above example, the object file "myobj" is added to the library file "mylib.lib". 

When a module is added to a library, the Open Watcom Library Manager will issue a warning if a symbol 
redefinition occurs. This will occur if a symbol in the module being added is already defined in another 
module that already exists in the library file. Note that the module will be added to the library in any case. 

It is also possible to combine two library files together. The following example adds all modules in the 
library "newlib.lib" to the library "mylib.lib". 

Example: 

wlib mylib +newlib.lib 

Note that you must specify the "lib" file extension. Otherwise, the Open Watcom Library Manager will 
assume you are adding an object file. 

4.5 Deleting Modules from a Library File 

A module can be deleted from a library file by specifying a -mod_name command where mod_name is the 
file name of the object file when it was added to the library with the directory and file extension removed. 
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Example: 

wlib mylib -myobj 

In the above example, the Open Watcom Library Manager is instructed to delete the module "myobj" from 
the library file "mylib.lib". 

It is also possible to specify a library file instead of a module name. 

Example: 

wlib mylib -oldlib.lib 

In the above example, all modules in the library file "oldlib.lib" are removed from the library file 
"mylib.lib". Note that you must specify the "lib" file extension. Otherwise, the Open Watcom Library 
Manager will assume you are removing an object module. 

4.6 Replacing Modules in a Library File 

A module can be replaced by specifying a -+mod_name or +-mod_name command. The module 
mod_name is deleted from the library. The object file "mod_name" is then added to the library. 

Example: 

wlib mylib —l-myobj 

In the above example, the module "myobj" is replaced by the object file "myobj". 

It is also possible to merge two library files. 

Example: 

wlib mylib —Hupdlib.lib 

In the above example, all modules in the library file "updlib.lib" replace the corresponding modules in the 
library file "mylib.lib". Any module in the library "updlib.lib" not in library "mylib.lib" is added to the 
library "mylib.lib". Note that you must specify the "lib" file extension. Otherwise, the Open Watcom 
Library Manager will assume you are replacing an object module. 


4.7 Extracting a Module from a Library File 

A module can be extracted from a library file by specifying a *mod_name |=file_name] command for a 
DOS, OS/2 or Windows-hosted version of the Open Watcom Library Manager or a :mod_name 
[=file_name] command for a UNIX-hosted version of the Open Watcom Library Manager. The module 
mod_name is not deleted but is copied to a disk file. If mod_name is preceded by a path specification, the 
output file will be placed in the directory identified by the path specification. If mod_name is followed by 
a file extension, the output file will contain the specified file extension. 
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Example: 

wlib mylib *myobj DOS, OS/2 or Windows-hosted 

or 

wlib mylib :myobj UNIX-hosted 

In the above example, the module "myobj" is copied to a disk file. The disk file will be an object file with 
file name "myobj". If you are running a DOS, OS/2 or Windows-hosted version of the Open Watcom 
Library Manager, a file extension of "obj" will be used. If you are running a UNIX-hosted version of the 
Open Watcom Library Manager, a file extension of "o" will be used. 

Example: 

wlib mylib *myobj.out DOS, OS/2 or Windows-hosted 

or 

wlib mylib :myobj.out UNIX-hosted 

In the above example, the module "myobj" will be extracted from the library file "mylib.lib" and placed in 
the file "myobj.out" 

The following form of the extract command can be used if the module name is not the same as the output 
file name. 

Example: 

wlib mylib *myobj=newmyobj.out DOS, OS/2 or Windows-hosted 
or 

wlib mylib :myobj=newmyobj.out UNIX-hosted 

You can extract a module from a file and have that module deleted from the library file by specifying a 
*-mod_name command for a DOS, OS/2 or Windows-hosted version of the Open Watcom Library 
Manager or a :-mod_name command for a UNIX-hosted version of the Open Watcom Library Manager. 
The following example performs the same operations as in the previous example but, in addition, the 
module is deleted from the library file. 

Example: 

wlib mylib *-myobj.out DOS, OS/2 or Windows-hosted 
or 

wlib mylib :-myobj.out UNIX-hosted 
Note that the same result is achieved if the delete operator precedes the extract operator. 


4.8 Creating Import Libraries 

The Open Watcom Library Manager can also be used to create impoit libraries from Dynamic Link 
Libraries. Import libraries are used when linking OS/2, Winl6 or Win32 applications. 

Example: 

wlib implib +dynamic.dll 

In the above example, the following actions are performed. For each external symbol in the specified 
Dynamic Link Library, a special object module is created that identifies the external symbol and the actual 
name of the Dynamic Link Library it is defined in. This object module is then added to the specified 
library. The resulting library is called an import library. 
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Note that you must specify the "dll" file extension. Otherwise, the Open Watcom Library Manager will 
assume you are adding an object file. 

4.9 Creating Import Library Entries 

An import library entry can be created and added to a library by specifying a command of the following 
form. 

++sym.dll_ name[.[altsym].export_ name][.ordinal] 

where description: 

sym is the name of a symbol in a Dynamic Link Library. 

dlljiame is the name of the Dynamic Link Library that defines sym. 

altsym is the name of a symbol in a Dynamic Link Library. When omitted, the default symbol 

name is sym. 

export jiame is the name that an application that is linking to the Dynamic Link Library uses to reference 
sym. When omitted, the default export name is sym. 

ordinal is the ordinal value that can be used to identify sym instead of using the name 

export_ name. 

Example: 

wlib math ++_ sin.trig.sin.1 

In the above example, an import library entry will be created for symbol sin and added to the library 

"math.lib". The symbol sin is defined in the Dynamic Link Library called "trig.dll" as_sin . When an 

application is linked with the library "math.lib", the resulting executable file will contain an import by 
ordinal value 1. If the ordinal value was omitted, the resulting executable file would contain an import by 
name sin. 


4.10 Commands from a File or Environment Variable 


The Open Watcom Library Manager can be instructed to process all commands in a disk file or 
environment variable by specifying the @name command where name is a file specification for the 
command file or the name of an environment variable. A file extension of "lbc" is assumed for files if none 
is specified. The commands must be one of those previously described. 

Example: 

wlib mylib gmycmd 

In the above example, all commands in the environment variable "mycmd" or file "mycmd.lbc" are 
processed by the Open Watcom Library Manager. 
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4.11 Open Watcom Library Manager Options 

The following sections describe the list of options allowed when invoking the Open Watcom Library 
Manager. 

4.11.1 Suppress Creation of Backup File - "b" Option 

The "b" option tells the Open Watcom Library Manager to not create a backup library file. In the following 
example, the object file identified by "new" will be added to the library file "mylib.lib". 

Example: 

wlib -b mylib +new 

If the library file "mylib.lib" already exits, no backup library file ("mylib.bak") will be created. 

4.11.2 Case Sensitive Symbol Names - "c" Option 

The "c" option tells the Open Watcom Library Manager to use a case sensitive compare when comparing a 
symbol to be added to the library to a symbol already in the library file. This will cause the names "myrtn" 
and "MYRTN" to be treated as different symbols. By default, comparisons are case insensitive. That is the 
symbol "myrtn" is the same as the symbol "MYRTN". 

4.11.3 Specify Output Directory - "d" Option 

The "d" option tells the Open Watcom Library Manager the directory in which all extracted modules are to 
be placed. The default is to place all extracted modules in the current directory. 

In the following example, the module "mymod" is extracted from the library "mylib.lib". If you are 
running a DOS, OS/2 or Windows-hosted version of the Open Watcom Library Manager, the module will 
be placed in the file "\obj\mymod.obj". If you are running a UNIX-hosted version of the Open Watcom 
Library Manager, the module will be placed in the file "/o/mymod.o". 

Example: 

wlib -d=\obj mymod DOS, OS/2 or Windows-hosted 

or 

wlib -d=/o mymod UNIX-hosted 

4.11.4 Specify Output Format ■ "f" Option 

The "f" option tells the Open Watcom Library Manager the format of the output library. The default output 
format is determined by the type of object files that are added to the library when it is created. The possible 
output format options are: 


fa output AR format library, host OS default ar format 

fab output AR format library, BSD ar format 

fac output AR format library, COFF ar format 
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fag 

output 

fin 

output 

fo 

output 


AR format library, GNU ar format 
MLIB format library 
OMF format library 


4.11.5 Generating Imports -"/" Option 

The "i" option can be used to describe type of import library to create. 
id generate AXP import records 

ii generate X86 import records 

ip generate PPC import records 

ie generate ELF import records 

ic generate COFF import records 

io generate OMF import records 


When creating import libraries from Dynamic Link Libraries, import entries for the names in the resident 
and non-resident names tables are created. The "i" option can be used to describe the method used to 
import these names. 

iro Specifying "iro" causes imports for names in the resident names table to be imported by 

ordinal. 

irn Specifying "irn" causes imports for names in the resident names table to be imported by 

name. This is the default. 

it to Specifying "ino" causes imports for names in the non-resident names table to be imported 

by ordinal. This is the default. 

inn Specifying "inn" causes imports for names in the non-resident names table to be imported 

by name. 

Example: 

wlib -iro -inn implib +dynamic.dll 

Note that you must specify the "dll" file extension for the Dynamic Link Library. Otherwise an object file 
will be assumed. 

4.11.6 Creating a Listing File - "I" Option 

The "1" (lower case "L") option instructs the Open Watcom Library Manager to produce a list of the names 
of all symbols that can be found in the library file to a listing fde. The file name of the listing file is the 
same as the file name of the library file. The file extension of the listing file is "1st". 
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Example: 

wlib -1 mylib 

In the above example, the Open Watcom Library Manager is instructed to list the contents of the library file 
"mylib.lib" and produce the output to a listing file called "mylib.1st". 

An alternate form of this option is -l=list_ file . With this form, you can specify the name of the 
listing file. When specifying a listing file name, a file extension of "1st" is assumed if none is specified. 

Example: 

wlib -l=mylib.out mylib 

In the above example, the Open Watcom Library Manager is instructed to list the contents of the library file 
"mylib.lib" and produce the output to a listing file called "mylib.out". 

You can get a listing of the contents of a library file to the terminal by specifying only the library name on 
the command line as demonstrated by the following example. 

Example: 

wlib mylib 

4.11.7 Display C++ Mangled Names - "m" Option 

The "m" option instructs the Open Watcom Library Manager to display C++ mangled names rather than 
displaying their demangled form. The default is to interpret mangled C++ names and display them in a 
somewhat more intelligible form. 

4.11.8 Always Create a New Library - "n" Option 

The "n" option tells the Open Watcom Library Manager to always create a new library file. If the library 
file already exists, a backup copy is made (unless the "b" option was specified). The original contents of 
the library are discarded and a new library is created. If the "n" option was not specified, the existing 
library would be updated. 

Example: 

wlib -n mylib +myobj 

In the above example, a library file called "mylib.lib" is created. It will contain a single object module, 
namely "myobj", regardless of the contents of "mylib.lib" prior to issuing the above command. If 
"mylib.lib" already exists, it will be renamed to "mylib.bak". 

4.11.9 Specifying an Output File Name - "o" Option 

The "o" option can be used to specify the output library file name if you want the original library to remain 
unchanged and a new library created. 
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Example: 

wlib -o=newlib libl +lib2.1ib 

In the above example, the modules from "libl.lib" and "lib2.1ib" are added to the library "newlib.lib". Note 
that since the original library remains unchanged, no backup copy is created. Also, if the "1" option is used 
to specify a listing file, the listing file will assume the file name of the output library. 

4.11.10 Specifying a Library Record Size - "p" and "pa" Options 

The "p" option specifies the record size in bytes for each record in the library file. The record size must be 
a power of 2 and in the range 16 to 32768. If the record size is less than 16, it will be rounded up to 16. If 
the record size is greater than 16 and not a power of 2, it will be rounded up to the nearest power of 2. The 
default record size is 256 bytes. 

Each entry in the dictionary of a library file contains an offset from the start of the file which points to a 
module. The offset is 16 bits and is a multiple of the record size. Since the default record size is 256, the 
maximum size of a library file for a record size of 256 is 256*64K. If the size of the library file increases 
beyond this size, you must increase the record size. 

Example: 

wlib -p=512 libl +lib2.1ib 

In the above example, the Open Watcom Library Manager is instructed to create/update the library file 
"libl.lib" by adding the modules from the library file "lib2.1ib". The record size of the resulting library file 
is 512 bytes. 

The "pa" option specifies the record size is determined automaticaly to be minimal in size. 

Example: 

wlib -pa libl +lib2.1ib 

In the above example, the Open Watcom Library Manager is instructed to create/update the library file 
"libl.lib" by adding the modules from the library file "lib2.1ib". The record size of the resulting library file 
is optimal (minimal) regardles of what each library page size is. 

4.11.11 Operate Quietly ■ "q" Option 

The "q" option suppressing the banner and copyright notice that is normally displayed when the Open 
Watcom Library Manager is invoked. 

Example: 

wlib -q -1 mylib 

4.11.12 Strip Line Number Records - "s" Option 

The "s" option tells the Open Watcom Library Manager to remove line number records from object files 
that are being added to a library. Line number records are generated in the object file if the "dl" option is 
specified when compiling the source code. 
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Example: 

wlib -s mylib +myobj 

4.11.13 Trim Module Name - T Option 

The "t" option tells the Open Watcom Library Manager to remove path information from the module name 
specified in THEADR records in object files that are being added to a library. The module name is created 
from the file name by the compiler and placed in the THEADR record of the object file. The module name 
will contain path information if the file name given to the compiler contains path information. 

Example: 

wlib -t mylib +myobj 

4.11.14 Operate Verbosely - "v" Option 

The "v" option enables the display of the banner and copyright notice when the Open Watcom Library 
Manager is invoked. 

Example: 

wlib -v -1 mylib 

4.11.15 Explode Library File - "x" Option 

The "x" option tells the Open Watcom Library Manager to extract all modules from the library. Note that 
the modules are not deleted from the library. Object modules will be placed in the current directory unless 
the "d" option is used to specify an alternate directory. 

In the following example all modules will be extracted from the library "mylib.lib" and placed in the 
current directory. 

Example: 

wlib -x mylib 

In the following example, all modules will be extracted from the library "mylib.lib". If you are running a 
DOS, OS/2 or Windows-hosted version of the Open Watcom Library Manager, the module will be placed 
in the "\obj" directory. If you are running a UNIX-hosted version of the Open Watcom Library Manager, 
the module will be placed in the file "/o" directory. 

Example: 

wlib -x -d=\obj mylib DOS, OS/2 or Windows-hosted 
or 

wlib -x -d=/o mylib UNIX-hosted 


4.12 Librarian Error Messages 

The following messages may be issued by the Open Watcom Library Manager. 
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Error! Could not open object file ’%s’. 

Object file ’%s’ could not be found. This message is usually issued when an attempt is 
made to add a non-existent object file to the library. 

Error! Could not open library file ’%s ’. 

The specified library file could not be found. This is usually issued for input library files. 
For example, if you are combining two library files, the library file you are adding is an 
input library file and the library file you are adding to or creating is an output library file. 

Error! Invalid object module in file ’%.v ’ not added. 

The specified file contains an invalid object module. 

Error! Dictionary too large. Recommend split library into two libraries. 

The size of the dictionary in a library file cannot exceed 64K. You must split the library 
file into two separate library files. 

Error! Redefinition of module ’%.v ’ in file ’%s ’. 

This message is usually issued when an attempt is made to add a module to a library that 
already contains a module by that name. 

Warning! Redefinition of symbol ’%.v ’ in file ’%.v ’ ignored. 

This message is issued if a symbol defined by a module already in the library is also 
defined by a module being added to the library. 

Error! Library too large. Recommend split library into two libraries or try a larger page_bound than 
%xH. The record size of the library file does not allow the library file to increase beyond its 

current size. The record size of the library file must be increased using the "p" option. 

Error! Expected ’%s ’ in ’%s ’ but found ’%s’. 

An error occurred while scanning command input. 

Warning! Could not find module ’%s’ for deletion. 

This message is issued if an attempt is made to delete a module that does not exist in the 
library. 

Error! Could not find module ’%s’ for extraction. 

This message is issued if an attempt is made to extract a module that does not exist in the 
library. 

Error! Could not rename old library for backup. 

The Open Watcom Library Manager creates a backup copy before making any changes 
(unless the "b" option is specified). This message is issued if an error occurred while trying 
to rename the original library file to the backup file name. 

Warning! Could not open library ’%.v ’: will be created. 

The specified library does not exist. It is usually issued when you are adding to a 
non-existent library. The Open Watcom Library Manager will create the library. 

Warning! Output library name specification ignored. 

This message is issued if the library file specified by the "o" option could not be opened. 

Warning! Could not open library ’%s ’ and no operations specified: will not be created. 

This message is issued if the library file specified on the command line does not exist and 
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no operations were specified. For example, asking for a listing file of a non-existent library 
will cause this message to be issued. 

Warning! Could not open listing file ’%s 

The listing file could not be opened. For example, this message will be issued when a "disk 
full" condition is present. 

Error! Could not open output library. 

The output library could not be opened. 

Error! Unable to write to output library. 

An error occurred while writing to the output library. 

Error! Unable to write to extraction file ’%s’. 

This message is issued when extracting an object module from a library file and an error 
occurs while writing to the output file. 

Error! Out of Memory. 

There was not enough memory to process the library file. 

Error! Could not open file ’%s’. 

This message is issued if the output file for a module that is being extracted from a library 
could not be opened. 

Error! Library ’%.v ’ is invalid. Contents ignored. 

The library file does not contain the correct header information. 

Error! Library ’%s ’ has an invalid page size. Contents ignored. 

The library file has an invalid record size. The record size is contained in the library header 
and must be a power of 2. 

Error! Invalid object record found in file ’%s 

The specified file contains an invalid object record. 

Error! No library specified on command line. 

This message is issued if a library file name is not specified on the command line. 

Error! Expecting library name. 

This message is issued if the location of the library file name on the command line is 
incorrect. 

Warning! Invalid file name ’%s ’. 

This message is issued if an invalid file name is specified. For example, a file name longer 
that 127 characters is not allowed. 

Error! Could not open command file ’%s ’. 

The specified command file could not be opened. 

Error! Could notread from file ’%s ’. Contents ignored as command input. 

An error occurred while reading a command file. 
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5.1 Introduction 

This chapter describes the Open Watcom Disassembler. It takes as input an object file (a file with 
extension ".obj") and produces, as output, the Intel assembly language equivalent. The Open Watcom 
compilers do not produce an assembly language listing directly from a source program. Instead, the Open 
Watcom Disassembler can be used to generate an assembly language listing from the object file generated 
by the compiler. 

The Open Watcom Disassembler command line syntax is the following. 

WDIS [options] [d:][path]filename[.ext] [options] 


The square brackets [ ] denote items which are optional. 

WDIS is the name of the Open Watcom Disassembler. 

d: is an optional drive specification such as "A:", "B:", etc. If not specified, the default drive 

is assumed. 

path is an optional path specification such as "\PROGRAMS\OBJ\". If not specified, the current 

directory is assumed. 

filename is the file name of the object file to disassemble. 

ext is the file extension of the object file to disassemble. If omitted, a file extension of ".obj" is 

assumed. If the period "." is specified but not the extension, the file is assumed to have no 
file extension. 


options is a list of valid options, each preceded by a slash ("/") or a dash Options may be 

specified in any order. 

The options supported by the Open Watcom Disassembler are: 


a 

e 

ff 

fi 

fp 

fr 

/« 

i=<char> 
l[=<list_file>] 


write assembly instructions only to the listing file 

include list of external names 

print FPU emulator fixups as comment line 

use alternate indexing format [80(x)86 only] 

do not use instruction name pseudonyms 

do not use register name pseudonyms [Alpha only] 

instructions/registers in upper case 

redefine the initial character of internal labels (default: L) 
create a listing file 
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m leave C++ names mangled 

p include list of public names 

s[=<source _Jile>] 

using object file source line information, imbed original source lines into the output file 
The following sections describe the list of options. 

5.2 Changing the Internal Label Character - "i=<char>" 

The "i" option permits you to specify the first character to be used for internal labels. Internal labels take 
the form "Ln" where "n" is one or more digits. The default character "L" can be changed using the "i" 
option. The replacement character must be a letter (a-z, A-Z). A lowercase letter is converted to 
uppercase. 

Example: 

C>wdis calendar -i=x 


5.3 The Assembly Format Option ■ “a" 

The "a" option controls the format of the output produced to the listing file. When specified, the Open 
Watcom Disassembler will produce a listing file that can be used as input to an assembler. 

Example: 

C>wdis calendar -a -l=calendar.asm 

In the above example, the Open Watcom Disassembler is instructed to disassemble the contents of the file 
calendar . ob j and produce the output to the file calendar. asm so that it can be assembled by an 
assembler. 


5.4 The External Symbols Option - "e" 

The "e" option controls the amount of information produced in the listing file. When specified, a list of all 
externally defined symbols is produced in the listing file. 

Example: 

C>wdis calendar -e 

In the above example, the Open Watcom Disassembler is instructed to disassemble the contents of the file 
calendar . ob j and produce the output, with a list of all external symbols, on the screen. A sample list 
of external symbols is shown below. 
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List of external symbols 


Symbol 


_iob 

0000032f 

00000210 

_CHK 

00000381 

00000343 

Box_ 

000000f2 


Calendar_ 

000000a7 

00000079 

ClearScreen_ 

00000016 


fflush_ 

00000334 

00000215 

int386_ 

000003af 

00000372 

Line_ 

000002db 

000002b5 

localtime_ 

00000028 


memset_ 

00000308 


PosCursor_ 

0000031e 

OOOOOlel 

printf_ 

00000327 

00000208 

strlen_ 

00000108 


time_ 

OOOOOOld 



OOOOOlf4 00000158 00000139 
000002eb 00000237 OOOOOOcb 00000006 

00000049 

000001f9 0000015d 0000013e 
00000293 00000274 0000025a 

00000148 00000123 000000b6 
OOOOOlec 00000150 00000131 


Each externally defined symbol is followed by a list of location counter values indicating where the symbol 
is referenced. 

The "e" option is ignored when the "a" option is specified. 

5.5 The FPU emulator fixups Option ■ "ff" 

The "ff' option causes the FPU emulator fixups will be printed as comment line before Intel FPU 
instruction. 


; FPU fixup FIDRQQ 

fid tbyte ptr [bx] 

5.6 The Alternate Addressing Form Option ■ "fi" 

The "fi" option causes an alternate syntactical form of the based or indexed addressing mode of the 80x86 
to be used in an instruction. For example, the following form is used by default for Intel instructions. 

mov ax,-2[bp] 

If the "fi" option is specified, the following form is used, 
mov ax,[bp-2] 

5.7 The No Instruction Name Pseudonyms Option - "fp" 

By default, AXP instruction name pseudonyms are emitted in place of actual instruction names. The Open 
Watcom AXP Assembler accepts instruction name pseudonyms. The "fp" option instructs the Open 
Watcom Disassembler to emit the actual instruction names instead. 
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5.8 The No Register Name Pseudonyms Option - "fr" 

By default, AXP register names are emitted in pseudonym form. The Open Watcom AXP Assembler 
accepts register pseudonyms. The "fr" option instructs the Open Watcom Disassembler to display register 
names in their non-pseudonym form. 

5.9 The Uppercase Instructions/Registers Option - "fu" 

The "fu" option instructs the Open Watcom Disassembler to display instruction and register names in 
uppercase characters. The default is to display them in lowercase characters. 

5.10 The Listing Option - "l[=<list_file>]" 

By default, the Open Watcom Disassembler produces its output to the terminal. The "1" (lowercase L) 
option instructs the Open Watcom Disassembler to produce the output to a listing file. The default file 
name of the listing file is the same as the file name of the object file. The default file extension of the 
listing file is . 1st. 

Example: 

C>wdis calendar -1 

In the above example, the Open Watcom Disassembler is instructed to disassemble the contents of the file 
calendar . ob j and produce the output to a listing file called calendar . 1st. 

An alternate form of this option is "l=<list_file>". With this form, you can specify the name of the listing 
file. When specifying a listing file, a file extension of ,1st is assumed if none is specified. 

Example: 

C>wdis calendar -l=calendar.lis 

In the above example, the Open Watcom Disassembler is instructed to disassemble the contents of the file 
calendar . ob j and produce the output to a listing file called calendar . lis . 

5.11 The Public Symbols Option ■ "p" 

The "p" option controls the amount of information produced in the listing file. When specified, a list of all 
public symbols is produced in the listing file. 

Example: 

C>wdis calendar -p 

In the above example, the Open Watcom Disassembler is instructed to disassemble the contents of the file 
calendar . ob j and produce the output, with a list of all exported symbols, to the screen. A sample list 
of public symbols is shown below. 

The following is a list of public symbols in 80x86 code. 
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List of public symbols 

SYMBOL SECTION OFFSET 


main_ _ TEXT 000002C0 

void near Box( int, int, int, int ) 

_ TEXT 00000093 

void near Calendar( int, int, int, int, int, char near * ) 

_ TEXT 0000014A 

void near ClearScreen() _ TEXT 00000000 

void near Line( int, int, int, char, char, char ) 

_ TEXT 00000036 

void near PosCursor( int, int ) 

_ TEXT 0000001A 

The following is a list of public symbols in Alpha AXP code. 

List of public symbols 


SYMBOL 



SECTION OFFSET 

main 




.text 

000004F0 

void 

near 

Box( int. 

int. 

int. 

int ) 





. text 

00000148 

void 

near 

Calendar( 

int. 

int. 

int, int, int, char near * 





.text 

00000260 

void 

near 

ClearScreen() 

.text 

00000000 

void 

near 

Line( int. 

int 

, int. 

char, char, char ) 





.text 

00000060 

void 

near 

PosCursor( 

int 

, int 

) 





.text 

00000028 


The "p" option is ignored when the "a" option is specified. 

5.12 Retain C++ Mangled Names - "m" 

The "m" option instructs the Open Watcom Disassembler to retain C++ mangled names rather than 
displaying their demangled form. The default is to interpret mangled C++ names and display them in a 
somewhat more intelligible form. 

5.13 The Source Option ■ "s[=<source_file>]" 

The "s" option causes the source lines corresponding to the assembly language instructions to be produced 
in the listing file. The object file must contain line numbering information. That is, the "dl" or "d2" option 
must have been specified when the source file was compiled. If no line numbering information is present in 
the object file, the "s" option is ignored. 

The following defines the order in which the source file name is determined when the "s" option is 
specified. 

1. If present, the source file name specified on the command line. 

2. The name from the module header record. 

3. The object file name. 

In the following example, we have compiled the source file mysrc. c with "dl" debugging information. 
We then disassemble it as follows: 
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Example: 

C>wdis mysrc -s -1 

In the above example, the Open Watcom Disassembler is instructed to disassemble the contents of the file 
mysrc . ob j and produce the output to the listing file mysrc . 1st. The source lines are extracted from 
the file mysrc . c . 

An alternate form of this option is "s=<source_file>". With this form, you can specify the name of the 
source file. 

Example: 

C>wdis mysrc -s=myprog.c -1 

The above example produces the same result as in the previous example except the source lines are 
extracted from the file myprog. c . 

5.14 Art Example 

Consider the following program contained in the file hello . c . 


#include <stdio.h> 

void main() 

{ 

printf ( "Hello world\n" ); 

} 


Compile it with the "dl" option. An object file called hello. ob j will be produced. The "dl" option 
causes line numbering information to be generated in the object file. We can use the Open Watcom 
Disassembler to disassemble the contents of the object file by issuing the following command. 

C>wdis hello -1 -e -p -s -fu 

The output will be written to a listing file called hello . 1st (the "1" option was specified"). It will 
contain a list of external symbols (the "e" option was specified), a list of public symbols (the "p" option was 
specified) and the source lines corresponding to the assembly language instructions (the "s" option was 
specified). The source input file is called hello. c. The register names will be displayed in upper case 
(the "fu" option was specified). The output, shown below, is the result of using the Open Watcom C++ 
compiler. 

The following is a disassembly of 80x86 code. 
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Module: HELLO.C 

GROUP: ' DGROUP' CONST, CONST2DATA, _ BSS 
Segment: _ TEXT DWORD USE32 0000001A bytes 


♦include <stdio.h> 
void main() 


0000 




main_ : 


0000 

68 

08 

00 

00 00 

PUSH 

0x00000008 

0005 

E8 

00 

00 

00 00 

CALL 

_CHK 

{ 

printf( 

.. 

Hello world\n 

" ) ; 


000A 

68 

00 

00 

00 00 

PUSH 

offset L$1 

000F 

E8 

00 

00 

00 00 

CALL 

printf_ 

0014 

83 

C4 

04 


ADD 

ESP,0x00000004 

} 

0017 

31 

CO 



XOR 

EAX,EAX 

0019 

C3 




RET 


Routine 

Size: 

26 

bytes. 

Routine 

Base: _ TEXT + 0000 


No disassembly errors 


List of external references 
SYMBOL 


_CHK 0006 

printf_ 0010 

Segment: CONST DWORD USE32 0000000D bytes 
0000 L$1: 

0000 48 65 6C 6C 6F 20 77 6F 72 6C 64 0A 00 Hello world.. 


BSS Size: 0 bytes 
List of public symbols 

SYMBOL SECTION OFFSET 

main_ _ TEXT 00000000 

The following is a disassembly of Alpha AXP code. 
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,new_ section .text, "crx4" 


#include <stdio.h> 
void main() 

0000 main: 


0000 

23DEFFF0 

LDA 

SP,-0x10(SP) 

0004 

B75E0000 

STQ 

RA,(SP) 

{ 

printf( "Hello world\n" 

); 


0008 

261F0000 

LDAH 

A0, h / 'L$0 (R31) 

oooc 

22100000 

LDA 

A0,1~L$0(A0) 

0010 

43F00010 

SEXTL 

A0, A0 

0014 

D3400000 

BSR 

RA,j^printf 

} 

0018 

201F0000 

MOV 

0x00000000,V0 

001C 

A75E0000 

LDQ 

RA, (SP) 

0020 

23DE0010 

LDA 

SP,0x10(SP) 

0024 

6BFA8001 

RET 

(RA) 


Routine Size: 40 bytes. Routine Base: .text + 0000 
No disassembly errors 


List of external references 
SYMBOL 


printf 


0014 


.new_ section .const, "drw4" 

0000 L$0: 

0000 48 65 6C 6C 6F 20 77 6F 72 6C 64 0A 00 00 00 00 Hello world 

.new_ section .const2, "drw4" 

.new_ section .data, "drw4" 

.new_ section .bss, "urw4" 

0000 .bss: 

BSS Size: 0 bytes 


.new_ section .pdata, "dr2" 

0000 // Procedure descriptor for main 


main 

// 

BeginAddress 

0 

main+0x28 

// 

EndAddress 

40 

00000000 

// 

ExceptionHandler 

0 

00000000 

// 

HandlerData 

0 

main+0x8 

// 

PrologEnd 

8 


.new_ section .drectve, "iRrO" 


0000 

2D 

64 

65 

66 

61 

75 

6C 

74 

6C 

69 

62 

3A 

63 

6C 

69 

62 

-defaultlib:clib 

0010 

20 

2D 

64 

65 

66 

61 

75 

6C 

74 

6C 

69 

62 

3A 

70 

6C 

69 

-defaultlib:pli 

0020 

62 

20 

2D 

64 

65 

66 

61 

75 

6C 

74 

6C 

69 

62 

3A 

6D 

61 

b -defaultlib:ma 


0030 

74 68 20 00 


th 

List of 

public symbols 



SYMBOL 


SECTION 

OFFSET 

main 


. text 

00000000 
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Let us create a form of the listing file that can be used as input to an assembler. 
C>wdis hello -l=hello.asm -r -a 


The output will be produced in the file hello . asm. The output, shown below, is the result of using the 
Open Watcom C++ compiler. 


The following is a disassembly of 80x86 code. 


.387 
. 38 6p 

PUBLIC 

main_ 





EXTRN 

_ CHK:BYTE 




EXTRN 

print f_ : BYTE 



EXTRN 

_wcpp_ 3_ 

. data_ 

init_ fs_ root_ : 


EXTRN 

_ cstart_ : BYTE 


DGROUP 

GROUP 

CONST, 

CONST2 

, _ DATA 

,_ BSS 

_ TEXT 

SEGMENT 

DWORD 

PUBLIC 

USE32 

'CODE' 


ASSUME CS :_ TEXT, DS : 

DGROUP 

, SS:DGROUP 

main__ : 






PUSH 

0x00000008 




CALL 

near ptr _ 

. _ CHK 




PUSH 

offset L$1 




CALL 

near ptr printf_ 




ADD 

ESP,0x00000004 




XOR 

EAX,EAX 





RET 






_ TEXT 

ENDS 





CONST 

L$ 1: 

SEGMENT 

DWORD 

PUBLIC 

USE32 

'DATA' 


DB 

0x48, 

0x65, i 

0x6c, 0x6c, 0x6f, 0x20 


DB 

0x72, 

0x6c, i 

0x64, 0x0a, 0x00 

CONST 

ENDS 





CONST2 

SEGMENT 

DWORD 

PUBLIC 

USE32 

'DATA' 

CONST2 

ENDS 





_ DATA 

SEGMENT 

DWORD 

PUBLIC 

USE32 

'DATA' 

_ DATA 

ENDS 





_ BSS 

SEGMENT 

DWORD 

PUBLIC 

USE32 

'BSS' 

_ BSS 

ENDS 






END 






0x6f 


The following is a disassembly of Alpha AXP code. 


.globl 

main 

.extrn 

printf 

. extrn 

_ cstart_ 

. new_ section 

.text, "crx4" 

main: 


LDA 

$SP,-0x10($SP) 

STQ 

$RA,($SP) 

LDAH 

$A0,h A 'L$0'($ ZERO) 

LDA 

$A0,1 A 'L$0'($A0) 

SEXTL 

$A0,$A0 

BSR 

$RA, j^printf 

MOV 

0x00000000,$V0 

LDQ 

$RA, ($SP) 

LDA 

$SP,0x10($SP) 

RET 

$ZERO,($RA),0x00000001 
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.new_ section .const, n drw4" 
'L$0': 



.asciiz 

"Hello world\n" 





.byte 

0x00, 0x00, 0x00 




new_ section 

. pdata, "dr2" 





// 0000 

Procedure descriptor for main 



. long 

main 

// 

BeginAddress 

0 


. long 

main+0x28 

// 

EndAddress 

40 


. long 

00000000 

// 

ExceptionHandler 

0 


. long 

00000000 

// 

HandlerData 

0 


. long 

main+0x8 

// 

PrologEnd 

8 

new_ section 

.drectve. 

"iRrO" 





.asciiz "-defaultlib:clib -defaultlib:plib -defaultlib:math 
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6 Optimization of Far Calls 


Optimization of far calls can result in smaller executable files and improved performance. It is most useful 
when the automatic grouping of logical segments into physical segments takes place. Note that, by default, 
automatic grouping is performed by the Open Watcom Linker. 

The Open Watcom C, C++ and FORTRAN 77 compilers automatically enable the far call optimization. 

The Open Watcom Linker will optimize far calls to procedures that reside in the same physical segment as 
the caller. For example, a large code model program will probably contain many far calls to procedures in 
the same physical segment. Since the segment address of the caller is the same as the segment address of 
the called procedure, only a near call is necessary. A near call does not require a relocation entry in the 
relocation table of the executable file whereas a far call does. Thus, the far call optimization will result in 
smaller executable files that will load faster. Furthermore, a near call will generally execute faster than a 
far call, particularly on 286 and 386-based machines where, for applications running in protected mode, 
segment switching is fairly expensive. 

The following describes the far call optimization, 
following sequences of code. 

push cs seg 

call near label push 

nop call 

Notes: 

1. The nop or seg ss instruction is present since a call far label instruction is five bytes. The push 
cs instruction is one byte and the call near label instruction is three bytes. The seg ss instruction 
is used because it is faster than the nop instruction. 

2. The called procedure will still use a retf instruction but since the code segment and the near 
address are pushed on the stack, the far return will execute correctly. 

3. The position of the padding instruction is chosen so that the return address is word aligned. A 
word aligned return address improves performance. 

4. When two consecutive call far label instructions are optimized and the first call far label 
instruction is word aligned, the following sequence replaces both call far label instructions. 


push 

CS 


call 

near 

labell 

seg 

ss 


push 

cs 


seg 

cs 


call 

near 

label2 


5. If your program contains only near calls, this optimization will have no effect. 

A far jump optimization is also performed by the Open Watcom Linker. This has the same benefits as the 
far call optimization. A jmp far label instruction to a location in the same segment will be replaced by the 
following sequence of code. 


The call far label instruction is converted to one of the 


ss 

cs 

near label 
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jmp near label 

mov ax,ax 

Note that for 32-bit segments, this instruction becomes mov eax, eax. 


6.1 Far Call Optimizations for Non-Open Watcom Object 
Modules 


The far call optimization is automatically enabled when object modules created by the Open Watcom C, 
C++, or FORTRAN 77 compilers are linked. These compilers mark those segments in which this 
optimization can be performed. The following utility can be used to enable this optimization for object 
modules that have been created by other compilers or assemblers. 

6.1.1 The Open Watcom Far Call Optimization Enabling Utility 

Only DOS, OS/2 and Windows-hosted versions of the Open Watcom Far Call Optimization Enabling 
Utility are available. A QNX-hosted version is not necessary since QNX-hosted development tools that 
generate object files, generate the necessary information that enables the far call optimization. 

The format of the Open Watcom Far Call Optimization Enabling Utility is as follows. Items enclosed in 
square brackets are optional; items enclosed in braces may be repeated zero or more times. 


FCENABLE { [option] [file] } 


where description: 

option is an option and must be preceded by a dash (’-’) or slash (’/’). 

file is a file specification for an object file or library file. If no file extension is specified, a file 

extension of "obj" is assumed. Wild card specifiers may be used. 

The following describes the command line options. 

b Do not create a backup file. By default, a backup file will be created. The backup file 

name will have the same file name as the input file and a file extension of "bob" for object 
files and "bak" for library files. 

c Specify a list of class names, each separated by a comma. This enables the far call 

optimization for all segments belonging to the specified classes. 

s Specify a list of segment names, each separated by a comma. This enables the far call 

optimization for all specified segments. 

x Specify a list of ranges, each separated by a comma, for which no far call optimizations are 

to be made. A range has the following format. 
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seg_ name start-end 
or 

seg_ name start:length 

seg_name is the name of a segment, start is an offset into the specified segment defining 
the start of the range, end is an offset into the specified segment defining the end of the 
range, length is the number of bytes from start to be included in the range. All values are 
assumed to be hexadecimal. 


Notes: 

1. If more than one class list or segment list is specified, only the last one is used. A class or 
segment list applies to all object and library files regardless of their position relative to the class 
or segment list. 

2. A range list applies only to the first object file following the range specification. If the object 
file contains more than one module, the range list will only apply to the first module in the object 
file. 

The following examples illustrate the use of the Open Watcom Far Call Optimization Enabling Utility. 
Example: 

fcenable -c code *.obj 

In the above example, the far call optimization will be enabled for all segments belonging to the "code" 
class. 

Example: 

fcenable -s _ text *.obj 

In the above example, the far call optimization will be enabled for all segments with name "_text". 

Example: 

fcenable -x special 0:400 asmfile.obj 

In the above example, the far call optimization will be disabled for the first lk bytes of the segment named 
"special" in the object file "asmfile". 

Example: 

fcenable -x special 0-ffffffff asmfile.obj 

In the above example, the far call optimization will be disabled for the entire segment named "special" in 
the object file "asmfile". 
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7 The Open Watcom Exe2bin Utility 


The exe2bin utility strips off the header of a DOS executable file and applies any necessary fixups. In 
addition, it is able to display the header and relocations of an executable file in human readable format. 

When DOS executes a program (supplied as an ".exe" file) it first reads the header of the executable file 
and ensures there is enough memory to load the program. If there is, DOS loads the file — excluding the 
header — to memory. Before jumping to the entry point, DOS has to adjust a number of certain locations 
that depend on the load address of the program. These adjustments consist of the addition of the load 
address to each entry in the above mentioned list of relocations. These relocations are part of the header of 
an executable file. The load address may vary from invocation to invocation, this creates the need for the 
existence of relocations. 

As exe2bin strips the executable header, the relocations are lost (among other things). This would render 
the resulting output useless, if exe2bin were not to apply the relocations as part of the conversion process. 
Just like DOS, exe2bin therefore needs to know the load address. This is supplied via an argument to 
exe2bin. 

Some programs do not rely on the address they are being loaded at, and consequently do not contain any 
relocations. In this case exe2bin merely copies the contents of the input file (apart from the header) to the 
output file. 

The phrase "binary part" (also "binary data") is used as a technical term in the documentation of exe2bin. It 
denotes the data following the header. The length of the binary data is determined by the header entries 
"Size mod 512", "Number of pages" and "Size of header". It is not directly related to the actual size of the 
input file. 


Note: Although Open Watcom Exe2bin is capable of producing DOS ".COM" executables, this 
functionality is only provided for compatibility with other tools. The preferred way of generating 
".COM" executables is to use the Open Watcom Linker with directive "format dos com". Refer 
to the Open Watcom Linker Guide for details. 


7.1 The Open Watcom Exe2bin Utility Command Line 

The format of the Open Watcom Exe2bin command line is as follows. Items enclosed in square brackets 
("[ ]") are optional. 


EXE2BIN [options] exe_Jile [bin _Jile] 
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where 

options 


exe _Jile 


description: 


is a list of options, each preceded by a dash On non-UNIX platforms, a slash ("/") 

may be also used instead of a dash. Options may be specified in any order. Supported 
options are: 

li display the executable file header 

r display the relocations of the executable file 

l=<seg> specify the load address of the binary file 


x 


enable extended capabilities of Open Watcom Exe2bin 


is a file specification for a 16-bit DOS executable file used as input. If no file extension is 
specified, a file extension of ".exe" is assumed. Wild card specifiers may not be used. 


bin _file 


is an optional file specification for a binary output file. If no file name is given, the 
extension of the input file is replaced by "bin" and taken as the name for the binary output 
file. 


Description: 

1. If are any relocations in the input file, the -1 option becomes mandatory (and is useless 
otherwise). 

2. If exe2bin is called without the -x option, certain restrictions to the input file apply (apart from 
being a valid DOS executable file): 

• the size of the binary data must be <= 64 KByte 

• no stack must be defined, i.e. ss:sp = 0x0000:0x0000 

• the code segment must be always zero, i.e. cs = 0x0000 

• the initial instruction pointer must be either ip = 0x0000 or ip = 0x0100 
None of the above restrictions apply if the -x option is supplied. 

3. If cs:ip = 0x0000:0x0100 and the -x option is not specified, no relocations are allowed in the 
input file. Furthermore, exe2bin skips another 0x100 bytes following the header (in addition to 
the latter). 

This behaviour allows the creation of DOS ".COM" executables and is implemented for 
backward compatibility. It is however strongly suggested to use the Open Watcom Linker 
instead (together with directive " format dos com"). 

The examples below illustrate the use of Open Watcom Exe2bin. 
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Example: 

exe2bin prog.exe 

Strips off the executable header from prog. exe and writes the binary part to prog. bin . If there are 
any relocations in prog. exe or if the input file violates any of the restrictions listed above, the execution 
of exe2bin fails. 

Example: 

exe2bin -x prog.exe 

Same as above but the "-x" option relaxes certain restrictions. 


Note: Even if exe2bin is sucessfully invoked with identical input files as in the preceding examples (i.e. 
with vs. without -x) the output files may differ. This happens when cs:ip = 0x0000:0x0100 causes 
exe2bin to skip additional 0x100 bytes from the input file, if the user did not specify -x. 


Example: 

exe2bin -h prog.exe test.bin 

Displays the header of prog. exe , strips it off and copies the binary part to test. bin . 

Example: 

exe2bin -h -r -x -l=0xE000 bios.exe bios.rom 

Displays the header and the relocations (if any) of bios . exe strips the header and applies any fixups to 
(i.e. relocates) bios . exe as if it were to be loaded at OxEOOO:0x0000. The result will be written to 
bios.rom 

The above command line may serve as an example of creating a 128 KByte BIOS image for the PC-AT 
architecture. 


7.2 Exe2bin Messages 

This is a list of the diagnostic messages exe2bin may display, accompanied by more verbose descriptions 
and some possible causes. 

Error opening %s for reading. 

The input executable file could not be opened for reading. 

Check that the input file exists and exe2bin has read permissions. 

Error opening %s for writing. 

The output binary file could not be opened for writing. 

Make sure the media is not write protected, has enough free space to hold the output file, 
and exe2bin has write permissions. 

Error allocating file HO buffer. 

There is not enough free memory to allocate a file buffer. 


Exe2bin Messages 69 







Object File Utilities 


Error reading while copying data. 

An error occured while reading the binary part of the input file. 

This is most likely due to a corrupted executable header. Run exe2bin with the -h option 
and check the size reported. The size of the input file must be at least ("Number of pages" - 
1) * 512 + "Size mod 512". Omit decrementing the number of pages if "Size mod 512" 
happens to equal zero. 

Error writing while copying data. 

The output binary file can not be written to. 

Make sure the media has enough free space to hold the output file and is not removed while 
writing to it. 

Error. %s has no valid executable header. 

The signature (the first two bytes of the input file) does not match "MZ". 

exe2bin can only use valid DOS executable files as input. 

Error allocating/reading reloc-table. 

There is either not enough free memory to allocate a buffer for the relocations (each 
relocation takes about 4 bytes) or there was an error while reading from the input file. 

Error. Option "-l=<seg>" mandatory (there are relocations). 

The executable file contains relocations. Therefore, exe2bin needs to know the segment the 
binary output file is supposed to reside at. 

Either provide a segment as an argument to the -1 option or rewrite your executable file to 
not contain any relocations. 

Error: Binary part exceeds 64 KBytes. 

The binary part of the input file is larger than 64 KBytes. 

The restriction applies because the -x option was not specified. Check if the extended 
behaviour is suitable or rewrite the program to shorten the binary part. 

Error: Stack segment defined. 

The header defines an initial stack, i.e. ss:sp != 0x0000:0x0000. 

The restriction applies because the -x option was not specified. Check if the extended 
behaviour is suitable or rewrite the program to not have a segment of class "stack". 

Error: CS.IP neither 0x0000:0x0000 nor 0x0000:0x0100. 

The header defines an initial cs:ip not matching any of the two values. 

The restriction applies because the -x option was not specified. Check if the extended 
behaviour is suitable or rewrite the program to have a different entry point (cf. Open 
WatcomLinker "option start" ). 

Error: corn-file must not have relocations. 

Although the binary part is <= 64 KByte in length, there is no stack defined and the cs:ip is 
0x0000:0x0100, i.e. exe2bin assumes you try to generate a ".COM" executable, there are 
relocations in the input file. 
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".COM" files are not allowed to contain relocations. Either produce an ".EXE" file instead 
or rewrite the program to avoid the need for relocations. In order to do the latter, look for 
statements that refer to segments or groups such as mov ax, _ TEXT ormov ax, 
DGROUP. 
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8 The Open Watcom Patch Utility 

8.1 Introduction 


The Open Watcom Patch Utility is a utility program which may be used to apply patches or bug fixes to 
Open Watcom’s compilers and its associated tools. As problems are reported and fixed, patches are created 
and made available on Open Watcom’s BBS, Open Watcom’s FTP site, or CompuServe for users to 
download and apply to their copy of the tools. 

8.2 Applying a Patch 

The format of the BPATCH command line is: 


BP A TCH [options ] patch _Jile 


The square brackets [ ] denote items which are optional. 
where description: 

options is a list of valid Open Watcom Patch Utility options, each preceded by a dash 

Options may be specified in any order. The possible options are: 

-p Do not prompt for confirmation 

-b Do not create a .BAK file 

-q Print current patch level of file 

patch_Jile is the file specification for a patch file provided by Open Watcom. 

Suppose a patch file called "wlink.a" is supplied by Open Watcom to fix a bug in the file "WLINK.EXE". 
The patch may be applied by typing the command: 

bpatch wlink.a 

The Open Watcom Patch Utility locates the file C : \WATCOM\BINW\WLINK. EXE using the PATH 
environment variable. The actual name of the executable file is extracted from the file wlink . a . It then 
verifies that the file to be patched is the correct one by comparing the size of the file to be patched to the 
expected size. If the file sizes match, the program responds with: 

Ok to modify 'C:\WATCOM\BINW\WLINK.EXE'? [y|n] 

If you respond with "yes", BPATCH will modify the indicated file. If you respond with "no", BPATCH 
aborts. Once the patch has been applied the resulting file is verified. First the file size is checked to make 


Applying a Patch 75 







Executable Image Utilities 


sure it matches the expected file size. If the file size matches, a check-sum is computed and compared to 
the expected check-sum. 

Notes: 

1. If an error message is issued during the patch process, the file that you specified to be patched 
will remain unchanged. 

2. If a sequence of patch files exist, such as "wlink.a", "wlink.b" and "wlink.c", the patches must be 
applied in order. That is, "wlink.a" must be applied first followed by "wlink.b" and finally 
"wlink.c". 


8.3 Diagnostic Messages 

If the patch cannot be successfully applied, one of the following error messages will be displayed. 

Usage: BPATCH j-pj j-q} {-b} <file> 

-p = Do not prompt for confirmation 
-b = Do not create a .BAKfile 
-q = Print current patch level of file 
The command line was entered with no arguments. 

not been patched 

This message is issued when the "-q" option is used and the file has not been patched. 
been patched to level ’%.v ’ 

This message is issued when the "-q" option is used and the file has been patched to the 
indicated level. 

already been patched to level ’%s ’ - skipping 
This message is issued when the file has already been patched to the same level or higher. 

Command line may only contain one file name 

More than one file name is specified on the command line. Make sure that"/" is not used 
as an option delimiter. 

Command line must specify a file name 

No file name has been specified on the command line. 

’%s’ is not a Open Watcom patch file 

The patch file is not of the required format. The required header information is not present. 
’%s’ is not a valid Open Watcom patch file 

The patch file is not of the required format. The required header information is present but 
the remaining contents of the file have been corrupted. 

’%.v ’ is the wrong size (%lul). Should be (%lu2) 

The size of the file to be patched (%lul) is not the same as the expected size (%lu2). 

Cannot find ’%.v ’ 

Cannot find the executable to be patched. 


File ’%s ’ has 

File ’%s ’ has 

File ’%s ’ has 
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Cannot open ’%.v ’ 

An error occurred while trying to open the patch file, the file to be patched or the resulting 
file. 

Cannot read ’%s’ 

An input error occurred while reading the old version of the file being patched. 

Cannot rename ’%s’ to ’%s ’ 

The file to be patched could not be renamed to the backup file name or the resulting file 
could not be renamed to the name of the file that was patched. 

Cannot write to ’%s’ 

An output error occurred while writing to the new version of the file to be patched. 

I/O error processing file ’%s ’ 

An error occurred while seeking in the specified file. 

No memory for %s 

An attempt to allocate memory dynamically failed. 

Patch program aborted! 

This message is issued if you answered no to the "OK to modify" prompt. 

Resulting file has wrong checksum (%lu) - Should be (%lu2) 

The check-sum of the resulting file (%lu) does not match the expected check-sum (%lu2). 
This message is issued if you have patched the wrong version. 

Resulting file has wrong size (%lul) - Should be (%lu2) 

The size of the resulting file (%lul) does not match the expected size (%lu2). This 
message is issued if you have patched the wrong version. 
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9 The Open Watcom Strip Utility 

9.1 Introduction 


The Open Watcom Strip Utility may be used to manipulate information that is appended to the end of an 
executable file. The information can be either one of two things: 

1. Symbolic debugging information 

2. Resource information 

This information can be added or removed from the executable file. Symbolic debugging information is 
placed at the end of an executable file by the Open Watcom Linker or the Open Watcom Strip Utility. 
Resource information is placed at the end of an executable by a resource compiler or the Open Watcom 
Strip Utility. 

Once a program has been debugged, the Open Watcom Strip Utility allows you to remove the debugging 
information from the executable file so that you do not have to remove the debugging directives from the 
linker directive file and link your program again. Removal of the debugging information reduces the size 
of the executable image. 

All executable files generated by the Open Watcom Linker can be specified as input to the Open Watcom 
Strip Utility. Note that for executable files created for Novell’s NetWare operating system, debugging 
information created using the "NOVELL" option in the "DEBUG" directive cannot be removed from the 
executable file. You must remove the "DEBUG" directive from the directive file and re-link your 
application. 

The Open Watcom Strip Utility currently runs under the following operating systems. 

•DOS 

•OS/2 

• QNX 

• Windows NT/2000/XP 

• Windows 95/98/Me 


9.2 The Open Watcom Strip Utility Command Line 

The Open Watcom Strip Utility command line syntax is: 
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WSTRIP [options] input Jile [output_file] [info_file] 


where: 


[] The square brackets denote items which are optional. 

options 

-n (noerrors) Do not issue any diagnostic message. 

-q (quiet) Do not print any informational messages. 

-r (resources) Process resource information rather than debugging 

information. 

-a (add) Add information rather than remove information. 


input_file 


is a file specification for the name of an executable file. If no file extension is specified, 
the Open Watcom Strip Utility will assume one of the following extensions: "exe", "dll", 
"exp", "rex", "nlm", "dsk", "lan", "nam", "msl", "cdm", "ham",''qnx" or no file extension. 
Note that the order specified in the list of file extensions is the order in which the Open 
Watcom Strip Utility will select file extensions. 


output_file is an optional file specification for the output file. If no file extension is specified, the file 

extension specified in the input file name will be used for the output file name. Ifis 
specified, the input file name will be used. 


info_file is an optional file specification for the file in which the debugging or resource information 

is to be stored (when removing information) or read (when adding information). If no file 
extension is specified, a file extension of "sym" is assumed for debugging information and 
"res" for resource information. To specify the name of the information file but not the 
name of an output file, a "." may be specified in place of output Jile. 


Description: 

1. If the "r" (resource) option is not specified then the default action is to add/remove symbolic 
debugging information. 

2. If the "a" (add) option is not specified then the default action is to remove information. 

3. If output_file is not specified, the debugging or resource information is added to or removed 
from input_file. 

4. If output_file is specified, input Jile is copied to output_file and the debugging or resource 
information is added to or removed from output Jile. input Jile remains unchanged. 

5. If info Jile is specified then the debugging or resource information that is added to or removed 
from the executable file is read from or written to this file. The debugging or resource 
information may be appended to the executable by specifying the "a" (add) option. Also, the 
debugging information may be appended to the executable by concatenating the debugging 
information file to the end of the executable file (the files must be treated as binary files). 
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6. During processing, the Open Watcom Strip Utility will create a temporary file, ensuring that a 
file by the chosen name does not already exist. 

9.3 Strip Utility Messages 

The following messages may be issued by the Open Watcom Strip Utility. 

Usage: WSTRIP [options] inputJile [outputJile] [info_file] 
options: (-option is also accepted) 

In don’t print warning messages 
/q don’t print informational messages 

lr process resource information rather than debugging information 
/a add information rather than delete information 
input_file: executable file 
output Jile: optional output executable or ’ 
info Jile: optional output debugging or resource information file 
or input debugging or resource informational file 
The command line was entered with no arguments. 

Too low on memory 

There is not enough free memory to allocate file buffers. 

Unable to find ’%s ’ 

The specified file could not be located. 

Cannot create temporary file 

All the temporary file names are in use. 

Unable to open ’%s ’ to read 

The input executable file cannot be opened for reading. 

’%s’ is not a valid executable file 

The input file has invalid executable file header information. 

’%s’ does not contain debugging information 

There is nothing to strip from the specified executable file. 

Seek error on ’%s ’ 

An error occurred during a seek operation on the specified file. 

Unable to create output file ’%s ’ 

The output file could not be created. Check that the output disk is not write-protected or 
that the specified output file is not marked "read-only". 

Unable to create symbol file ’%s’ 

The symbol file could not be created. 

Error reading ’%s ’ 

An error occurred while reading the input executable file. 

Error writing to ’%s ’ 

An error occurred while writing the output executable file or the symbol file. Check the 
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amount of free space on the output disk. If the input and output files reside on the same 
disk, there might not be enough room for a second copy of the executable file during 
processing. 

Cannot erase file ’%s ’ 

The input executable file is probably marked "read-only" and therefore could not be erased 
(the input file is erased whenever the output file has the same name). 

Cannot rename file ’%s’ 

The output executable file could not be renamed. Ordinarily, this should never occur. 
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10 The Open Watcom Make Utility 

10.1 Introduction 


The Open Watcom Make utility is useful in the development of programs and text processing but is general 
enough to be used in many different applications. Make uses the fact that each file has a time-stamp 
associated with it that indicates the last time the file was updated. Make uses this time-stamp to decide 
which files are out of date with respect to each other. For instance, if we have an input data file and an 
output report file we would like the output report file to accurately reflect the contents of the input data file. 
In terms of time-stamps, we would like the output report to have a more recent time-stamp than the input 
data file (we will say that the output report file should be "younger" than the input data file). If the input 
file had been modified then we would know from the younger time-stamp (in comparison to the report file ) 
that the report file was out of date and should be updated. Make may be used in this and many other 
situations to ensure that files are kept up to date. 

Some readers will be quite familiar with the concepts of the Make file maintenance tool. Open Watcom 
Make is patterned after the Make utility found on UNIX systems. The next major section is simply 
intended to summarize, for reference purposes only, the syntax and options of Make’s command line and 
special macros. Subsequent sections go into the philosophy and capabilities of Open Watcom Make. If 
you are not familiar with the capabilities of the Make utility, we recommend that you skip to the next major 
section entitled "Dependency Declarations" and read on. 


10.2 Open Watcom Make Reference 

The following sub-sections serve as a reference guide to the Open Watcom Make utility. 

10.2.1 Open Watcom Make Command Line Format 

The formal Open Watcom Make command line syntax is shown below. 


WMAKE [options] [macro _defs] [targets] 


As indicated by the square brackets [ ], all items are optional. 

options is a list of valid Open Watcom Make options, each preceded by a slash ("/") or a dash ("—"). 

Options may be specified in any order. 

macro_defs is a list of valid Open Watcom Make macro definitions. Macro definitions are of the form: 

A=B 


and are readily identified by the presence of the "=" (the "#" character may be used instead 
of the "=" character if necessary). Surround the definition with quotes (") if it contains 
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blanks (e.g., "debug_opt=debug all"). The macro definitions specified on the command 
line supersede any macro definitions defined in makefiles. Macro names are 
case-insensitive unless the "ms" option is used to select Microsoft NMAKE mode. 

targets is one or more targets described in the makefile. 

10.2.2 Open Watcom Make Options Summary 

In this section, we present a terse summary of the Open Watcom Make options. This summary is displayed 
on the screen by simply entering "WMAKE ?" on the command line. 

Example: 

C>wmake ? 

-a make all targets by ignoring time-stamps 

-b block/ignore all implicit rules 

-c do not verify the existence of files made 

-d debug mode - echo all work as it progresses 

-e always erase target after error/interrupt (disables prompting) 

-/ the next parameter is a name of dependency description file 

-h do not print out Make identification lines (no header) 

-i ignore return status of all commands executed 

-k on error/interrupt: continue on next target 

-/ the next parameter is the name of a output log file 

-m do not search for MAKEINIT file 

-ms Microsoft NMAKE mode 

-n no execute mode - print commands without executing 

-o use circular implicit rule path 

-p print the dependency tree as understood from the file 

-q query mode - check targets without updating them 

-r do not use default definitions 

-s silent mode - do not print commands before execution 

-sn noisy mode - always print commands before execution 

-t touch files instead of executing commands 

-u UNIX compatibility mode 

-v verbose listing of inline files 

-y show why a target will be updated 

-z do not erase target after error/interrupt (disables prompting) 

10.2.3 Command Line Options 

Command line options, available with Open Watcom Make, allow you to control the processing of the 
makefile. 


a 

make all targets by ignoring time-stamps 

The "a" option is a safe way to update every target. For program maintenance, it is the preferred method 
over deleting object files or touching source files. 
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b 

block/ignore all implicit rules 

The "b" option will indicate to Make that you do not want any implicit rule checking done. The "b" option 
is useful in makefiles containing double colon explicit rules because an implicit rule search is 
conducted after a double colon target is updated. Including the directive . BLOCK in a makefile also 
will disable implicit rule checking. 

c 

do not verify the existence of files made 

Make will check to ensure that a target exists after the associated command list is executed. The target 
existence checking may be disabled with the "c" option. The "c" option is useful in processing makefiles 
that were developed with other Make utilities. The . NOCHECK directive is used to disable target existence 
checks in a makefile. 

d 

debug mode - echo all work as it progresses 

The "d" option will print out information about the time-stamp of files and indicate how the makefile 
processing is proceeding. 

e 

always erase target after error/interrupt (disables prompting) 

The "e" option will indicate to Make that, if an error or interrupt occurs during makefile processing, the 
current target being made may be deleted without prompting. The . ERASE directive may be used as an 
equivalent option in a makefile. 

f 

the next parameter is a name of dependency description file 

The "f" option specifies that the next parameter on the command line is the name of a makefile which must 
be processed. If the "f" option is specified then the search for the default makefile named "MAKEFILE" is 
not done. Any number of makefiles may be processed with the "f" option. 

Example: 

wmake /f myfile 

wmake /f myfilel /f myfile2 

h 

do not print out Make identification lines (no header) 

The "h" option is useful for less verbose output. Combined with the "q" option, this allows a batch file to 
silently query if an application is up to date. Combined with the "n" option, a batch file could be produced 
containing the commands necessary to update the application. 

/ 

ignore return status of all commands executed 
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The "i" option is equivalent to the . IGNORE directive. 


k 

on error/interrupt: continue on next target 

Make will stop updating targets when a non-zero status is returned by a command. The "k" option will 
continue processing targets that do not depend on the target that caused the error. The . CONTINUE 
directive in a makefile will enable this error handling capability. 

/ 

the next parameter is the name of a output log file 

Make will output an error message when a non-zero status is returned by a command. The "1" option 
specifies a file that will record all error messages output by Make during the processing of the makefile. 

m 

do not search for the MAKEINIT file 

The default action for Make is to search for an initialization file called "MAKEINIT" or "TOOLS.INI" if 
the "ms" option is set. The "m" option will indicate to Make that processing of the MAKEINIT file is not 
desired. 

ms 

Microsoft NMAKE mode 

The default action for Make is to process makefiles using Open Watcom syntax rules. The "ms" option will 
indicate to Make that it should process makefiles using Microsoft syntax rules. For example, the line 
continuation in NMAKE is a backslash ("\") at the end of the line. 

n 

no execute mode - print commands without executing 

The "n" option will print out what commands should be executed to update the application without actually 
executing them. Combined with the "h" option, a batch file could be produced which would contain the 
commands necessary to update the application. 

Example: 

wmake /h /n >update.bat 
update 

This is useful for applications which require all available resources (memory and devices) for executing the 
updating commands. 

0 

use circular implicit rule path 

When this option is specified. Make will use a circular path specification search which may save on disk 
activity for large makefiles. The "o" option is equivalent to the . OPTIMIZE directive. 
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P 

print out makefile information 

The "p" option will cause Make to print out information about all the explicit rules, implicit rules, and 
macro definitions. 


query mode - check targets without updating them 

The "q" option will cause Make to return a status of 1 if the application requires updating; it will return a 
status of 0 otherwise. Here is a example batch file using the "q" option: 

Example: 

wmake /q 

if errorstatus 0 goto noupdate 
wmake /q /h /n >\tmp\update.bat 
call \tmp\update.bat 
: noupdate 


do not use default definitions 
The default definitions are: 

_ MAKEOPTS_ = <options passed to WMAKE> 

_MAKEFILES_ = <list of makefiles> 

_ VERSION_ = <version number> 

_ LOADDLL_ = defined if DLL loading supported 

_MSDOS_ = defined if MS/DOS version 

_NT_ = defined if Windows NT version 

_NT386_ = defined if x86 Windows NT version 

_ OS2 = defined if OS/2 version 

_ QNX = defined if QNX version 

_ LINUX_ = defined if Linux version 

_LINUX386_ = defined if x86 Linux version 

_ UNIX_ = defined if QNX or Linux version 

MAKE = <name of file containing WMAKE> 

#endif 

# clear .EXTENSIONS list 
.EXTENSIONS: 

# In general, 

# set .EXTENSIONS list as follows 
.EXTENSIONS: .exe .nlm .dsk .lan .exp & 

.lib .obj & 

. i & 

.asm .c .cpp .cxx .cc .for .pas .cob & 

.h .hpp .hxx .hh . fi .mif .inc 

For Microsoft NMAKE compatibility (when you use the "ms" option), the following default definitions are 
established. 
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# For Microsoft NMAKE compatibility switch, 

# set .EXTENSIONS list as follows 
.EXTENSIONS: .exe .obj .asm ,c .cpp .cxx & 

.bas .cbl .for .f ,f90 .pas .res 


%MAKEFLAGS = $(%MAKEFLAGS) $ (_MAKEOPTS_) 

MAKE=<name of file containing WMAKE> 

AS=ml 


BC=bc 

CC=cl 

COBOL=cobol 

CPP=cl 

CXX=cl 

FOR=f1 

PASCAL=pl 

RC=rc 

.asm.exe: 

$(AS) $(AFLAGS) 
.asm.obj: 

$(AS) $(AFLAGS) 
.c.exe: 

$(CC) $(CFLAGS) 
. c . ob j : 

$(CC) $(CFLAGS) 


$* . asm 
/c $*.asm 
$* . c 
/c $* . c 


.cpp.exe: 

$(CPP) $(CPPFLAGS) $ *.cpp 
. cpp.obj: 

$(CPP) $(CPPFLAGS) /c $ *.cpp 


.cxx.exe: 


$(CXX) $(CXXFLAGS) $*.cxx 
. cxx.obj: 

$(CXX) $(CXXFLAGS) $*.cxx 
. bas.obj: 

$ (BC) $(BFLAGS) $*.bas 


. cbl.exe: 

$(COBOL) $(COBFLAGS) $*.cbl, $*.exe; 
. cbl.obj: 

$(COBOL) $(COBFLAGS) $*.cbl; 

.f.exe: 

$(FOR) $(FFLAGS) $*.f 
. f . ob j : 

$(FOR) /c $ (FFLAGS) $*.f 
.f90.exe: 

$(FOR) $(FFLAGS) $*.f90 
.f90.obj: 

$(FOR) /c $(FFLAGS) $*.f90 
.for.exe: 

$(FOR) $(FFLAGS) $*.for 
. for.obj: 

$(FOR) /c $(FFLAGS) $*.for 
.pas.exe: 

$(PASCAL) $(PFLAGS) $*.pas 
.pas.obj: 

$(PASCAL) /c $(PFLAGS) $*.pas 
.rc.res: 

$(RC) $(RFLAGS) /r $* 


. rc 
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For OS/2, the_ MSDOS _macro will be replaced by_ OS2 _and for Windows NT, the_ MSDOS. 

macro will be replaced by_ NT_. 

For UNIX make compatibility (when you use the "u" option), the following default definition is 
established. 

.EXTENSIONS: .exe ,obj .c ,y .1 .f 

%MAKEFLAGS = $(%MAKEFLAGS) $ (_MAKEOPTS_) 

MAKE=<name of file containing WMAKE> 

YACC=yacc 

YFLAGS= 

LEX=lex 

LFLAGS= 

LDFLAGS= 

CC=cl 
FC=f 1 


. asm.exe: 


$ (AS) 

$(AFLAGS) 

$*.asm 



c .exe: 





$ (CC) 

$ (CFLAGS) 

$(LDFLAGS) 

-o $@ 

$< 

f.exe: 





$ (FC) 

$ (FFLAGS) 

$(LDFLAGS) 

-o $@ 

$< 

c . ob j : 





$ (CC) 

$ (CFLAGS) 

1 

o 

<r> 

A 



f . ob j : 





$ (FC) 

$ (FFLAGS) 

-c $< 




.y.obj : 

$(YACC) $(YFLAGS) $< 

$(CC) $(CFLAGS) -c y.tab.c 

del y.tab.c 

move y.tab.obj $@ 

. 1. ob j : 

$(LEX) $(LFLAGS) $< 

$(CC) $(CFLAGS) -c lex.yy.c 

del lex.yy.c 

move lex.yy.obj $@ 

.y.c: 

$(YACC) $(YFLAGS) $< 
move y.tab.c $@ 

. 1. c : 

$(LEX) $(LFLAGS) $< 
move lex.yy.c $@ 


The "r" option will disable these definitions before processing any makefiles. 


silent mode - do not print commands before execution 
The "s" option is equivalent to the . SILENT directive. 


noisy mode - always print commands before execution 

The "sn" option overrules all silencing controls. It can be used to assist in debugging a makefile. 
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t 

touch files instead of executing commands 

Sometimes there are changes which are purely cosmetic (adding a comment to a source file) that will cause 
targets to be updated needlessly thus wasting computer resources. The "t" option will make files appear 
younger without altering their contents. The "t" option is useful but should be used with caution. 

U 

UNIX compatibility mode 

The "u" option will indicate to Make that the line continuation character should be a backslash "\" rather 
than an ampersand "&". 

V 

The "v" option enables a verbose listing of inline temporary files. 

y 

The "y" option enables the display of a progress line denoting which dependent file has caused a target to 
be updated. This is a useful option for helping to debug makefiles. 

Z 

do not erase target after error/interrupt (disables prompting) 

The "z" option will indicate to Make that if an error or interrupt occurs during makefile processing then the 
current target being made should not be deleted. The . HOLD directive in a makefile has the same effect as 
the "z" option. 

10.2.4 Special Macros 

Open Watcom Make has many different special macros. Here are some of the simpler ones. 


Macro 

Expansion 

$$ 

represents the character "$" 

$# 

represents the character "#" 

$@ 

full file name of the target 

$* 

target with the extension removed 

$< 

list of all dependents 

$? 

list of dependents that are younger than the target 


The following macros are for more sophisticated makefiles. 

Macro Expansion 

_MSDOS _ This macro is defined in the MS/DOS environment. 

_NT_ This macro is defined in the Windows NT environment. 

_OS2 _ This macro is defined in the OS/2 environment. 
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_LINUX_ 

_QNX_ 

_UNIX_ 

_MAKEOPTS_ 

_MAKEFILES. 

MAKE 

VERSION 


This macro is defined in the Linux environment. 

This macro is defined in the QNX environment. 

This macro is defined in the Linux or QNX environment. 

contains all of the command line options that WMAKE was invoked with except 
for any use of the "f" or "n" options. 

contains the names of all of the makefiles processed at the time of expansion 
(includes the file currently being processed) 

contains the full name of the file that contains WMAKE 

contains the wmake version. 


The next three tables contain macros that are valid during execution of command lists for explicit rules, 
implicit mles, and the . ERROR directive. The expansion is presented for the following example: 

Example: 

a:\dir\target.ext : b:\dirl\depl.exl c:\dir2\dep2.ex2 


Macro 

Expansion 

$ A @ 

a:\dir\target.ext 

$ A * 

a:\dir\target 

$ A & 

target 

$ A . 

target.ext 

$ A : 

a:\dir\ 

Macro 

Expansion 

$[@ 

b:\dirl\depl.exl 

$[* 

b:\dirl\depl 

$[& 

depl 

$[. 

depl.exl 

$[: 

b:\dir 1\ 

Macro 

Expansion 

$]@ 

c:\dir2\dep2.ex2 

$]* 

c:\dir2\dep2 

$]& 

dep2 

$]. 

dep2.ex2 

$]: 

c:\dir2\ 
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10.3 Dependency Declarations 

In order for Open Watcom Make to be effective, a list of file dependencies must be declared. The 
declarations may be entered into a text file of any name but Make will read a file called "MAKEFILE" by 
default if it is invoked as follows: 

Example: 

C>wmake 

If you want to use a file that is not called "MAKEFILE" then the command line option "f" will cause Make 
to read the specified file instead of the default "MAKEFILE". 

Example: 

C>wmake /f myfile 

We will now go through an example to illustrate how Make may be used for a simple application. Suppose 
we have an input file, a report file, and a report generator program then we may declare a dependency as 
follows: 

# 

# (a comment in a makefile starts with a "#") 

# simple dependency declaration 

# 

balance.1st : ledger.dat 
doreport 

Note that the dependency declaration starts at the beginning of a line while commands always have at least 
one blank or tab before them. This form of a dependency declaration is called an explicit rule. The file 
"BALANCE.LST" is called the target of the rule. The dependent of the rule is the file "LEDGER.DAT" 
while "DOREPORT" forms one line of the rule command list. The dependent is separated from the target 
by a colon. 


Hint: A good habit to develop is to always put spaces around the colon so that it will not be confused 
with drive specifications (e.g., a:). 


The explicit rule declaration indicates to Make that the program "DOREPORT" should be executed if 
"LEDGER.DAT" is younger than "BALANCE.LST" or if "BALANCE.LST" does not yet exist. In 
general, if the dependent file has a more recent modification date and time than the target file then Open 
Watcom Make will execute the specified command. 


Note: The terminology employed here is used by S.I.Feldman of Bell Laboratories in Make - A 
Program for Maintaining Computer Programs. 

http://www.softlab.ntua.gr/facilities/documentation/unix/docs/make.txt has a copy of this seminal 
article. Confusion often arises from the use of the word "dependent". In this context, it means "a 
subordinate part". In the example, "LEDGER.DAT" is a subordinate part of the report 
"BALANCE.LST". 
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10.4 Multiple Dependents 

Suppose that our report "BALANCE.LST" becomes out-of-date if any of the files "LEDGER.DAT", 
"SALES.DAT" or "PURCHASE.DAT" are modified. We may modify the dependency rule as follows: 

# 

# multiple dependents rule 

# 

balance.1st : ledger.dat sales.dat purchase.dat 
doreport 

This is an example of a rule with multiple dependents. In this situation, the program "DOREPORT" should 
be executed if any of "LEDGER.DAT", "SALES.DAT" or "PURCHASE.DAT" are younger than 
"BALANCE.LST" or if "BALANCE.LST" does not yet exist. In cases where there are multiple 
dependents, if any of the dependent files has a more recent modification date and time than the target file 
then Open Watcom Make will execute the specified command. 


10.5 Multiple Targets 

Suppose that the "DOREPORT" program produces two reports. If both of these reports require updating as 
a result of modification to the dependent files, we could change the rule as follows: 

# 

# multiple targets and multiple dependents rule 

# 

balance.1st summary.1st : ledger.dat sales.dat purchase.dat 
doreport 

Suppose that you entered the command: 
wmake 

which causes Make to start processing the rules described in "MAKEFILE". In the case where multiple 
targets are listed in the makefile. Make will, by default, process only the first target it encounters. In the 
example. Make will check the date and time of "BALANCE.LST" against its dependents since this is the 
first target listed. 

To indicate that some other target should be processed, the target is specified as an argument to the Make 
command. 

Example: 

wmake summary.1st 

There are a number of interesting points to consider: 

1. By default. Make will only check that the target file exists after the command ( "DOREPORT" in 
this example) is executed. It does not check that the target’s time-stamp shows it to be younger. 
If the target file does not exist after the command has been executed, an error is reported. 

2. There is no guarantee that the command you have specified does update the target file. In other 
words, simply because you have stated a dependency does not mean that one exists. 
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3. Furthermore, it is not implied that other targets in our list will not be updated. In the case of our 
example, you can assume that we have designed the "doreport" command to update both targets. 


10.6 Multiple Rules 

A makefile may consist of any number of rules. Note that the following: 

targetl target2 : dependentl dependents dependents 
command list 

is equivalent to: 

targetl : dependentl dependent2 dependents 
command list 

target2 : dependentl dependent2 dependents 
command list 

Also, the rules may depend on the targets of other rules. 

# 

# rule 1: this rule uses rule 2 

# 

balance.1st summary.1st : ledger.dat sales.dat purchase.dat 
doreport 

# 

# rule 2: used by rules 1 and 3 

# 

sales.dat : canada.dat england.dat usa.dat 
dosales 


# 

# rule 3: this rule uses rule 2 

# 

year.1st : ledger.dat sales.dat purchase.dat 
doyearly 

The dependents are checked to see if they are the targets of any other rules in the makefile in which case 
they are updated. This process of updating dependents that are targets in other rules continues until a rule is 
reached that has only simple dependents that are not targets of rules. At this point, if the target does not 
exist or if any of the dependents is younger than the target then the command list associated with the rule is 
executed. 


Hint: The term "updating", in this context, refers to the process of checking the time-stamps of 
dependents and running the specified command list whenever they are out-of-date. Whenever a 
dependent is the target of some other rule, the dependent must be brought up-to-date first. Stated 
another way, if "A" depends on "B" and "B" depends on "C" and "C" is younger than "B" then we must 
update "B" before we update "A". 


Make will check to ensure that the target exists after its associated command list is executed. The target 
existence checking may be disabled in two ways: 
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1. use the command line option "c" 

2. use the . NOCHECK directive. 

The rule checking returns to the previous rule that had the target as a dependent. Upon returning to the 
rule, the command list is executed if the target does not exist or if any of the updated dependents are now 
younger than the target. If you were to type: 

wmake 

here are the steps that would occur with the previous makefile: 
update(balance.1st) (rule 1) 


update(ledger.dat) 

(not 

a 

target 

update(sales.dat) 

(found 

rule 2 

update(Canada.dat) 

(not 

a 

target 

update(england.dat) 

(not 

a 

target 

update(usa.dat) 

(not 

a 

target 


IF sales.dat does not exist OR 

any of (Canada.dat,england.dat, usa.dat) 
is younger than sales.dat 
THEN execute "dosales" 

update(purchase.dat) (not a target) 

IF balance.1st does not exist OR 

any of (ledger.dat,sales.dat,purchase.dat) 
is younger than (balance.1st) 

THEN execute "doreport" 

The third rule in the makefile will not be included in this update sequence of steps. Recall that the default 
target that is "updated" is the first target in the first rule encountered in the makefile. This is the default 
action taken by Make when no target is specified on the command line. If you were to type: 

wmake year.1st 

then the file "YEAR.LST" would be updated. As Make reads the rules in "MAKEFILE", it discovers that 
updating "YEAR.LST" involves updating "SALES.DAT". The update sequence is similar to the previous 
example. 


10.7 Command Lists 

A command list is a sequence of one or more commands. Each command is preceded by one or more 
spaces or tabs. Command lists may also be used to construct inline files "on the fly". Macros substitute in 
command lists and in inline files. An inline file is introduced by "«" in a command in a command list. 
Data to insert into that file is placed (left-justified) in the command list. The data is terminated by "«" in 
the first column. It is not possible to place a line which starts "«" in an inline file. More than one inline 
file may be created in a command. Data for each is placed in order of reference in the command. 

In building the Open Watcom system, it is sometimes necessary to do some text substitution with a program 
called vi. This needs a file of instructions. The following simplifies an example used to build Open 
Watcom so that inline files may be shown. Without inline files, this is done as: 
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$(dllname).imp : $(dllname).lbc ../../trimlbc.vi 
cp $(dllname).lbc $(dllname).imp 
$(vi) -s ../../trimlbc.vi $(dllname).imp 

where trimlbc.vi consists of 
set magic 

set magicstring = () 
atomic 

%s/\.dll'/'/ 

% s / A (\ + \ +') (.*) ('\.' ) \. [0-9]+$/\l\2\3..'\2' / 

x 

A doubled "$" to produce a single dollar is notable when an inline file is used: 

$(dllname).imp : $(dllname).lbc 

cp $(dllname).lbc $(dllname).imp 
$(vi) -s << $(dllname).imp 
set magic 

set magicstring = () 
atomic 

%s/\.dll'/'/ 

% s / A (\ + \ + ') (.*) ('\.' )\. [0-9]+$$/\l\2\3..'\2'/ 

x 

<< 

A filename may follow a "«" on a command line to cause a file with that name to be created. (Otherwise, 
'WMAKE’ chooses a name.) "keep" or "nokeep" may follow a terminating "«" to show what to do with 
the file after usage. The default is "nokeep" which zaps it. 

10.8 Final Commands (.AFTER) 

The . AFTER directive specifies commands for Make to run after it has done all other commands. See the 
section entitled "Command List Directives" on page 137 for a full description of its use. 

10.9 Ignoring Dependent Timestamps (.ALWAYS) 

The . ALWAYS directive indicates to Make that the target should always be updated regardless of the 
timestamps of its dependents. 

# 

# .always directive 

# 

foo : bar .always 
wtouch $@ 

foo is updated each time Make is run. 
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10.10 Automatic Dependency Detection (.AUTODEPEND) 

Explicit listing of dependencies in a makefile can often be tedious in the development and maintenance 
phases of a project. The Open Watcom C/C++ compiler will insert dependency information into the object 
file as it processes source files so that a complete snapshot of the files necessary to build the object file are 
recorded. Since all files do not have dependency information contained within them in a standard form, it 
is necessary to indicate to Make when dependencies are present. 

To illustrate the use of the . AUTODEPEND directive, we will show its use in an implicit rule and in an 
explicit rule. 

# 

# .AUTODEPEND example 

# 

.c.obj: .AUTODEPEND 

wcc386 $[* $(compile_ options) 

test.exe : a.obj b.obj c.obj test.res 
wlink FILE a.obj, b.obj, c.obj 
wrc /q /bt=windows test.res test.exe 

test.res : test.rc test.ico .AUTODEPEND 

wrc /ad /q /bt=windows /r $[@ $~@ 

In the above example. Make will use the contents of the object file to determine whether the object file has 
to be built during processing. The Open Watcom Resource Compiler can also insert dependency 
information into a resource file that can be used by Make. 

10.11 Initial Commands (.BEFORE) 

The . BEFORE directive specifies commands for Make to run before it does any other command. See the 
section entitled "Command List Directives" on page 137 for a full description of its use. 

10.12 Disable Implicit Rules (.BLOCK) 

The . BLOCK directive and the "b" command line option are alternative controls to cause implicit rules to 
be ignored. See the section entitled "Command Line Options" on page 86 for a full description of its use. 

10.13 Ignoring Errors (.CONTINUE) 

The . CONTINUE directive and the "b" command line option are alternative controls to cause failing 
commands to be ignored. See the section entitled "Command Line Options" on page 86 for a full 
description of its use. 
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# 

# .continue example 

# 

.continue 

all: bad good 
@%null 


bad: 

false 

good: 

touch $@ 

Although the command list for bad fails, that for good is done. Without the directive, good is not built. 


10.14 Default Command List (.DEFAULT) 

The . DEFAULT directive provides a default command list for those targets which lack one. See the section 
entitled "Command List Directives" on page 137 for a full description of its use. 

# 

# .default example 

# 

.default 

Secho Using default rule to update target "$@" 

Secho because of dependent(s) "$<" 

wtouch $@ 

all: foo 

f oo: 

wtouch foo 

"all" has no command list. The one supplied to the default directive is executed instead. 


10.15 Erasing Targets After Error (.ERASE) 

Most operating system utilities and programs have special return codes that indicate error conditions. Open 
Watcom Make will check the return code for every command executed. If the return code is non-zero. 
Make will stop processing the current rule and optionally delete the current target being updated. By 
default. Make will prompt for deletion of the current target. The . ERASE directive indicates to Make that 
the target should be deleted if an error occurs during the execution of the associated command list. No 
prompt is issued in this case. Here is an example of the . ERASE directive: 

# 

# .ERASE example 

# 

.ERASE 

balance.1st : ledger.dat sales.dat purchase.dat 
doreport 
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If the program "DOREPORT" executes and its return code is non-zero then Make will attempt to delete 
"BALANCE.LST". 


10.16 Error Action (.ERROR) 

The . ERROR directive supplies a command list for error conditions. See the section entitled "Command 
List Directives" on page 137 for a full description of its use. 

# 

# .error example 

# 

.error: 

@echo it is good that "$@" is known 

all : .symbolic 
false 


10.17Ignoring Target Timestamp (.EXISTSONLY) 

The . EXISTSONLY directive indicates to Make that the target should not be updated if it already exists, 
regardless of its timestamp. 

# 

# .existsonly directive 

# 

foo: .existsonly 
wtouch $@ 

If absent, this file creates foo; if present, this file does nothing. 


10.18 Specifying Explicitly Updated Targets (.EXPLICIT) 

The . EXPLICIT directive may me used to specify a target that needs to be explicitly updated. Normally, 
the first target in a makefule will be implicitly updated if no target is specified on Make command line. 
The . EXPLICIT directive prevents this, and is useful for instance when creating files designed to be 
included for other make files. 

# 

# .EXPLICIT example 

# 

target : .symbolic .explicit 

@echo updating first target 

next : .symbolic 

@echo updating next target 

In the above example. Make will not automatically update "target", despite the fact that it is the first one 
listed. 
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10.19 Defining Recognized File Extensions (.EXTENSIONS) 

The . EXTENSIONS directive and its synonym, the . SUFFIXES directive declare which extensions are 
allowed to be used in implicit rules and how these extensions are ordered. . EXTENSIONS is the 
traditional Watcom name; . SUFFIXES is the corresponding POSIX name. The default .EXTENSIONS 
declaration is: 

.EXTENSIONS: 

.EXTENSIONS: .exe .nlm .dsk .lan .exp .lib .obj & 

.i .asm .c .cpp .cxx .cc .for .pas .cob & 

.h .hpp .hxx .hh .fi .mif .inc 

A .EXTENSIONS directive with an empty list will clear the . EXTENSIONS list and any previously 
defined implicit rules. Any subsequent . EXTENSIONS directives will add extensions to the end of the list. 


Hint: The default . EXTENSIONS declaration could have been coded as: 

.EXTENSIONS 


.EXTENSIONS 

.exe 

.EXTENSIONS 

.nlm .dsk .lan .exp 

.EXTENSIONS 

.lib 

.EXTENSIONS 

•obj 

.EXTENSIONS 

.i .asm .c .cpp .cxx .cc 

.EXTENSIONS 

.for .pas .cob 

.EXTENSIONS 

.h .hpp .hxx .hh .fi .mif .inc 

.EXTENSIONS 

.inc 

with identical results. 


Make will not allow any implicit rule declarations that use extensions that are not in the current 
.EXTENSIONS list. 

# 

# .extensions and .suffixes directives 

# 

.suffixes : # Clear list 
.extensions : .foo .bar 

.bar.foo: 

copy $< $@ 

fubar.foo: 

fubar.bar: .existsonly 
wtouch $@ 

The first time this example runs. Make creates fubar.foo. This example always ensures that fubar.foo is a 
copy of fubar.bar. Note the implicit connection beween the two files. 


102 Defining Recognized File Extensions (.EXTENSIONS) 






The Open Watcom Make Utility 


10.20 Approximate Timestamp Matching (.FUZZY) 

The . FUZZY directive allows . AUTODEPEND times to be out by a minute without considering a target out 
of date. It is only useful in conjunction with the . JUST_ ENOUGH directive when Make is calculating the 
timestamp to set the target to. 

10.21 Preserving Targets After Error (.HOLD) 

Most operating system utilities and programs have special return codes that indicate error conditions. Open 
Watcom Make will check the return code for every command executed. If the return code is non-zero. 
Make will stop processing the current rule and optionally delete the current target being updated. By 
default. Make will prompt for deletion of the current target. The . HOLD directive indicates to Make that 
the target should not be deleted if an error occurs during the execution of the associated command list. No 
prompt is issued in this case. The . HOLD directive is similar to . PRECIOUS but applies to all targets 
listed in the makefile. Here is an example of the . HOLD directive: 

# 

# .HOLD example 

# 

.HOLD 

balance.1st : ledger.dat sales.dat purchase.dat 
doreport 

If the program "DOREPORT" executes and its return code is non-zero then Make will not delete 
"BALANCE.LST". 


10.22 Ignoring Return Codes (.IGNORE) 

Some programs do not have meaningful return codes so for these programs we want to ignore the return 
code completely. There are different ways to ignore return codes namely, 

1. use the command line option "i" 

2. put a " in front of specific commands, or 

3. use the . IGNORE directive. 

In the following example, the rule: 

# 

# ignore return code example 

# 

balance.1st : ledger.dat sales.dat purchase.dat 
-doreport 

will ignore the return status from the program "DOREPORT". Using the dash in front of the command is 
the preferred method for ignoring return codes because it allows Make to check all the other return codes. 

The . IGNORE directive is used as follows: 
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# 

# .IGNORE example 

# 

.IGNORE 

balance.1st : ledger.dat sales.dat purchase.dat 
doreport 

Using the . IGNORE directive will cause Make to ignore the return code for every command. The "i" 
command line option and the . IGNORE directive prohibit Make from performing any error checking on the 
commands executed and, as such, should be used with caution. 

Another way to handle non-zero return codes is to continue processing targets which do not depend on the 
target that had a non-zero return code during execution of its associated command list. There are two ways 
of indicating to Make that processing should continue after a non-zero return code: 

1. use the command line option "k" 

2. use the . CONTINUE directive. 


10.23 Minimising Target Timestamp (.JUST_ENOUGH) 

The . JUST_ ENOUGH directive is equivalent to the "j" command line option. The timestamps of created 
targets are set to be the same as those of their youngest dependendents. 

# 

# .JUST_ ENOUGH example 

# 

.just_ enough 
.c.exe: 

wcl386 -zq $< 
hello.exe: 

hello.exe is given the same timestamp as hello.c, and not the usual timestamp corresponding to when 
hello.exe was built. 


10.24 Updating Targets Multiple Times (.MULTIPLE) 

The . MULTIPLE directive is used to update a target multiple times. Normally, Make will only update 
each target once while processing a makefile. The . MULTIPLE directive is useful if a target needs to be 
updated more than once, for instance in case the target is desUoyed during processing of other targets. 
Consider the following example: 
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# 

# example not using .multiple 

# 

all: targl targ2 

target: 

wtouch target 

targl: target 

rm target 
wtouch targl 

targ2: target 

rm target 
wtouch targ2 

This makefile will fail because "target" is destroyed when updating "targl", and later is implicitly expected 
to exist when updating "targ2". Using the . MULTIPLE directive will work around this problem: 

# 

# .MULTIPLE example 

# 

all : targl targ2 

target : .multiple 

wtouch target 

targl : target 

rm target 
wtouch targl 

targ2 : target 

rm target 
wtouch targ2 

Now Make will attempt to update "target" again when updating "targ2", discover that "target" doesn't exist, 
and recreate it. 


10.25 Ignoring Target Timestamp (.NOCHECK) 

The . NOCHECK directive is used to disable target existence checks in a makefile. See the section entitled 
"Command Line Options" on page 86 for a full description of its use. 

10.26 Cache Search Path (.OPTIMIZE) 

The . OPTIMIZE directive and the equivalent "o" command line option cause Make to use a circular path 
search. If a file is found in a particular directory, that directory will be the first searched for the next file. 
See the section entitled "Command Line Options" on page 86 for a full description of its use. 
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10.27 Preserving Targets (.PRECIOUS) 

Most operating system utilities and programs have special return codes that indicate error conditions. Open 
Watcom Make will check the return code for every command executed. If the return code is non-zero. 
Make will stop processing the current rule and optionally delete the current target being updated. If a file is 
precious enough that this treatment of return codes is not wanted then the .PRECIOUS directive may be 
used. The . PRECIOUS directive indicates to Make that the target should not be deleted if an error occurs 
during the execution of the associated command list. Here is an example of the .PRECIOUS directive: 

# 

# .PRECIOUS example 

# 

balance summary : sales.dat purchase.dat .PRECIOUS 
doreport 


If the program "DOREPORT" executes and its return code is non-zero then Make will not attempt to delete 
"BALANCE" or "SUMMARY". If only one of the files is precious then the makefile could be coded as 
follows: 

# 

# .PRECIOUS example 

# 

balance : .PRECIOUS 

balance summary : sales.dat purchase.dat 
doreport 

The file "BALANCE.LST" will not be deleted if an error occurs while the program "DOREPORT" is 
executing. 

10.28 Name Command Sequence (.PROCEDURE) 

The . PROCEDURE directive may be used to construct "procedures" in a makefile. 

# 

# .procedure example 

# 

all: .symbolic 
@%make proc 

proc: .procedure 

@echo Executing procedure "proc" 

10.29 Re-Checking Target Timestamp (.RECHECK) 

Make will re-check the target’s timestamp, rather than assuming it was updated by its command list. This 
is useful if the target is built by another make- style tool, as in the following example: 
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# 

# .RECHECK example 

# 

foo.gz : foo 

gzip foo 

foo : .ALWAYS .RECHECK 

nant -buildfile:foo.build 

foo’s command list will always be run, but foo will only be compressed if the timestamp is actually 
changed. 

10.30 Suppressing Terminal Output (.SILENT) 

As commands are executed. Open Watcom Make will print out the current command before it is executed. 
It is possible to execute the makefile without having the commands printed. There are three ways to inhibit 
the printing of the commands before they are executed, namely: 

1. use the command line option "s" 

2. put an in front of specific commands, or 

3. use the . SILENT directive. 

In the following example, the rule: 

# 

# silent command example 

# 

balance summary : ledger.dat sales.dat purchase.dat 
Sdoreport 

will prevent the string "doreport" from being printed on the screen before the command is executed. 

The . SILENT directive is used as follows: 

# 

# .SILENT example 

# 

.SILENT 

balance summary : ledger.dat sales.dat purchase.dat 
doreport 

Using the . SILENT directive or the "s" command line option will inhibit the printing of all commands 
before they are executed. The "sn" command line option can be used to veto any silencing control. 

At this point, most of the capability of Make may be realized. Methods for making makefiles more 
succinct will be discussed. 
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10.31 Defining Recognized File Extensions (.SUFFIXES) 

The . SUFFIXES directive declares which extensions are allowed to be used in implicit rules and how 
these extensions are ordered. It is a synonym for the . EXTENSIONS directive. See the section entitled 
"Defining Recognized File Extensions (.EXTENSIONS)" on page 102 for a full description of both 
directives. 


10.32 Targets Without Any Dependents (.SYMBOLIC) 

There must always be at least one target in a rule but it is not necessary to have any dependents. If a target 
does not have any dependents, the command list associated with the rule will always be executed if the 
target is updated. 

You might ask, "What may a rule with no dependents be used for?". A rule with no dependents may be 
used to describe actions that are useful for the group of files being maintained. Possible uses include 
backing up files, cleaning up files, or printing files. 

To illustrate the use of the . SYMBOLIC directive, we will add two new rules to the previous example. 
First, we will omit the . SYMBOLIC directive and observe what will happen when it is not present. 

# 

# rule 4: backup the data files 

# 

backup : 

echo "insert backup disk" 
pause 

copy *.dat a: 

echo "backup complete" 

# 

# rule 5: cleanup temporary files 

# 

cleanup : 

del *.tmp 
del \tmp\*.* 

and then execute the command: 

wmake backup 

Make will execute the command list associated with the "backup" target and issue an error message 
indicating that the file "BACKUP" does not exist after the command list was executed. The same thing 
would happen if we typed: 

wmake cleanup 

In this makefile we are using "backup" and "cleanup" to represent actions we want performed. The names 
are not real files but rather they are symbolic names. This special type of target may be declared with the 
. SYMBOLIC directive. This time, we show rules 4 and 5 with the appropriate addition of . SYMBOLIC 
directives. 
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# 

# rule 4: backup the data files 

# 

backup : .SYMBOLIC 

echo "insert backup disk" 
pause 

copy *.dat a: 

echo "backup complete" 

# 

# rule 5: cleanup temporary files 

# 

cleanup : .SYMBOLIC 
del *.tmp 
del \tmp\*.* 


The use of the . SYMBOLIC directive indicates to Make that the target should always be updated internally 
after the command list associated with the rule has been executed. A short form for the common idiom of 
singular . SYMBOLIC targets like: 

target : .SYMBOLIC 
commands 


is: 


target 

commands 

This kind of target definition is useful for many types of management tasks that can be described in a 
makefile. 


10.33 Macros 


Open Watcom Make has a simple macro facility that may be used to improve makefiles by making them 
easier to read and maintain. A macro identifier may be composed from a string of alphabetic characters and 
numeric characters. The underscore character is also allowed in a macro identifier. If the macro identifier 
starts with a "%" character, the macro identifier represents an environment variable. For instance, the 
macro identifier "%path" represents the environment variable "path". 


Macro identifiers Valid? 

2morrow yes 

stitch_in_9 yes 

invalided no 

2b_or_not_2b yes 

%path yes 

reports yes 

!@#*% no 


We will use a programming example to show how macros are used. The programming example involves 
four C/C++ source files and two header files. Here is the initial makefile (before macros): 
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# 

# programming example 

# (before macros) 

# 

plot.exe : main.obj input.obj calc.obj output.obj 
wlink @plot 

main.obj : main.c defs.h globals.h 
wcc386 main /mf /dl /w3 

calc.obj : calc.c defs.h globals.h 
wcc386 calc /mf /dl /w3 

input.obj : input.c defs.h globals.h 
wcc386 input /mf /dl /w3 

output.obj : output.c defs.h globals.h 
wcc386 output /mf /dl /w3 

Macros become useful when changes must be made to makefiles. If the programmer wanted to change the 
compiler options for the different compiles, the programmer would have to make a global change to the 
makefile. With this simple example, it is quite easy to make the change but try to imagine a more complex 
example with different programs having similar options. The global change made by the editor could cause 
problems by changing the options for other programs. A good habit to develop is to define macros for any 
programs that have command line options. In our example, we would change the makefile to be: 

# 

# programming example 

# (after macros) 

# 

link_ options = 

compiler = wcc386 

compile_ options = /mf /dl /w3 

plot.exe : main.obj input.obj calc.obj output.obj 
wlink $ (link_ options) Splot 

main.obj : main.c defs.h globals.h 

$(compiler) main $(compile_ options) 

calc.obj : calc.c defs.h globals.h 

$(compiler) calc $(compile_ options) 

input.obj : input.c defs.h globals.h 

$(compiler) input $(compile_ options) 

output.obj : output.c defs.h globals.h 

$(compiler) output $(compile_ options) 

A macro definition consists of a macro identifier starting on the beginning of the line followed by an "=" 
which in turn is followed by the text to be replaced. A macro may be redefined, with the latest declaration 
being used for subsequent expansions (no warning is given upon redefinition of a macro). The replacement 
text may contain macro references. 
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A macro reference may occur in two forms. The previous example illustrates one way to reference macros 
whereby the macro identifier is delimited by "$(" and ")". The parentheses are optional so the macros 
"compiler" and "compile_options" could be referenced by: 

main.obj : main.c defs.h globals.h 

$compiler main $compile_ options 

Certain ambiguities may arise with this form of macro reference. For instance, examine this makefile 
fragment: 

Example: 

temporary_ dir = \tmp\ 

temporary_ file = $temporary_ dirtmpOOO.tmp 

The intention of the declarations is to have a macro that will expand into a file specification for a temporary 
file. Make will collect the largest identifier possible before macro expansion occurs. The macro reference 
is followed by text that looks like part of the macro identifier ("tmpOOO") so the macro identifier that will 
be referenced will be "temporary_dirtmpOOO". The incorrect macro identifier will not be defined so an 
error message will be issued. 

If the makefile fragment was: 

temporary_ dir = \tmp\ 

temporary_ file = $(temporary_ dir)tmpOOO.tmp 

there would be no ambiguity. The preferred way to reference macros is to enclose the macro identifier by 
"$(" and ")". 

Macro references are expanded immediately on dependency lines (and thus may not contain references to 
macros that have not been defined) but other macro references have their expansion deferred until they are 
used in a command. In the previous example, the macros "link_options", "compiler", and 
"compile_options" will not be expanded until the commands that reference them are executed. 

Another use for macros is to replace large amounts of text with a much smaller macro reference. In our 
example, we only have two header files but suppose we had very many header files. Each explicit rule 
would be very large and difficult to read and maintain. We will use the previous example makefile to 
illustrate this use of macros. 

# 

# programming example 

# (with more macros) 

# 

link_ options = 

compiler = wcc386 

compile_ options = /mf /dl /w3 

header_ files = defs.h globals.h 
object_ files = main.obj input.obj calc.obj & 
output.obj 

plot.exe : $(object_ files) 

wlink $ (link_ options) Splot 

main.obj : main.c $(header_ files) 

$(compiler) main $(compile_ options) 
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calc.obj : calc.c $(header_ files) 

$(compiler) calc $(compile_ options) 

input.obj : input.c $(header_ files) 

$(compiler) input $(compile_ options) 

output.obj : output.c $(header_ files) 

$(compiler) output $(compile_ options) 

Notice the ampersand ("&") at the end of the macro definition for "object_files". The ampersand indicates 
that the macro definition continues on the next line. In general, if you want to continue a line in a makefile, 
use an ampersand ("&") at the end of the line. 

There are special macros provided by Make to access environment variable names. To access the PATH 
environment variable in a makefile, we use the macro identifier "%path". For example, if we have the 
following line in a command list: 

Example: 

echo $(%path) 

it will print out the current value of the PATH environment variable when it is executed. 

There are two other special environment macros that are predefined by Make. The macro identifier 
"%cdrive" will expand into one letter representing the current drive. Note that it is operating system 
dependent whether the cd command changes the current drive. The macro identifier "%cwd" will expand 
into the current working directory. These macro identifiers are not very useful unless we can specify that 
they be expanded immediately. The complementary macros "$+" and respectively turn on and turn 
off immediate expansion of macros. The scope of the "$+" macro is the current line after which the default 
macro expansion behaviour is resumed. A possible use of these macros is illustrated by the following 
example makefile. 

# 

# $(%cdrive), $(%cwd), $+, and $- example 

# 

dirl = $(%cdrive):$(%cwd) 
dir2 = $+ $(dirl) $- 
example : .SYMBOLIC 

cd . . 

echo $(dirl) 
echo $(dir2) 

Which would produce the following output if the current working directory is 
C:\WATCOM\SOURCE\EXAMPLE: 

Example: 

(command output only) 

C:\WATCOM\SOURCE 
C:\WATCOM\SOURCE\EXAMPLE 

The macro definition for "dir2" forces immediate expansion of the "%cdrive" and "%cwd" macros thus 
defining "dir2" to be the current directory that Make was invoked in. The macro "dirl" is not expanded 
until execution time when the current directory has changed from the initial directory. 

Combining the $+ and $- special macros with the special macro identifiers "%cdrive" and "%cwd" is a 
useful makefile technique. The $+ and $- special macros are general enough to be used in many different 
ways. 
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Constructing other macros is another use for the $+ and $- special macros. Make allows macros to be 
redefined and combining this with the $+ and $- special macros, similar looking macros may be 
constructed. 

# 

# macro construction with $+ and $- 

# 

template = filel.$(ext) file2.$(ext) file3.$(ext) file4.$(ext) 
ext = dat 

data_ files = $+ $(template) $- 
ext = 1st 

listing_ files = $+ $ (template) $- 

example : .SYMBOLIC 

echo $(data_ files) 
echo $(listing_ files) 

This makefile would produce the following output: 

Example: 

filel.dat file2.dat file3.dat file4.dat 
filel.lst file2.1st file3.1st file4.1st 

Adding more text to a macro can also be done with the $+ and $- special macros. 

# 

# macro addition with $+ and $- 

# 

objs = filel.obj file2.obj file3.obj 
objs = $+$(objs)$- file4.obj 
objs = $+$(objs)$- file5.obj 

example : .SYMBOLIC 
echo $(objs) 

This makefile would produce the following output: 

Example: 

filel.obj file2.obj file3.obj file4.obj file5.obj 

Make provides a shorthand notation for this type of macro operation. Text can be added to a macro by 
using the "+=" macro assignment. The previous makefile can be written as: 


# 

# macro addition with += 

# 

objs = filel.obj file2.obj file3.obj 
objs += file4.obj 
objs += file5.obj 

example : .SYMBOLIC 
echo $ (objs) 

and still produce the same results. The shorthand notation "+=" supported by Make provides a quick way 
to add more text to macros. 

Make provides the "linject" preprocessor directive to append a "word" (one or more graphic characters) to 
one or more macros. The previous makefile is adapted to show the usage: 
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# 

# macro construction with !inject 

# 

linject filel.obj objs objsl2 objsl3 
linject file2.obj objs objsl2 objsl3 
linject file3.obj objs objsl3 

linject file4.obj objs 
linject file5.obj objs 

example : .SYMBOLIC 
echo $ (objs) 
echo $ (objsl2) 
echo $ (objsl3) 
echo $ (objsl4) 
echo $(objsl5) 

This makefile would produce the following output: 

Example: 

filel.obj file2.obj file3.obj file4.obj file5.obj 
filel.obj file2.obj 
filel.obj file2.obj file3.obj 
filel.obj file2.obj file3.obj file4.obj 
filel.obj file2.obj file3.obj file4.obj file5.obj 

The "linject" preprocessor directive supported by Make provides a way to append a word to several macros. 

There are instances when it is useful to have macro identifiers that have macro references contained in 
them. If you wanted to print out an informative message before linking the executable that was different 
between the debugging and production version, we would express it as follows: 

# 

# programming example 

# (macro selection) 

# 

version = debugging # debugging version 

msg_ production = linking production version ... 
msg_ debugging = linking debug version ... 

link_ options_ production = 

link_ options_ debugging = debug all 

link_ options = $ (link_ options_ $ (version) ) 

compiler = wcc386 

compile_ options_ production = /mf /w3 
compile_ options_ debugging = /mf /dl /w3 
compile_ options = $(compile_ options_ $(version) ) 


objsl4 objsl5 
objsl4 objsl5 
objsl4 objsl5 
objsl4 objsl5 
objsl5 
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header_ files = defs.h globals.h 
object_ files = main.obj input.obj calc.obj & 
output.obj 

plot.exe : $(object_ files) 

echo $(msg_ $(version)) 
wlink $(link_ options) Splot 

main.obj : main.c $(header_ files) 

$(compiler) main $(compile_ options) 

calc.obj : calc.c $(header_ files) 

$(compiler) calc $(compile_ options) 

input.obj : input.c $(header_ files) 

$(compiler) input $(compile_ options) 

output.obj : output.c $(header_ files) 

$(compiler) output $(compile_ options) 

Take notice of the macro references that are of the form: 

$ (<partial_ macro_ identifier>$ (version) ) 

The expansion of a macro reference begins by expanding any macros seen until a matching right 
parenthesis is found. The macro identifier that is present after the matching parenthesis is found will be 
expanded. The other form of macro reference namely: 

$<macro_ identifier> 

may be used in a similar fashion. The previous example would be of the form: 

$<partial_ macro_ identifier>$version 

Macro expansion occurs until a character that cannot be in a macro identifier is found (on the same line as 
the "$") after which the resultant macro identifier is expanded. If you want two macros to be concatenated 
then the line would have to be coded: 

$(macrol)$(macro2) 

The use of parentheses is the preferred method for macro references because it completely specifies the 
order of expansion. 

In the previous example, we can see that the four command lines that invoke the compiler are very similar 
in form. We may make use of these similarities by denoting the command by a macro reference. We need 
to be able to define a macro that will expand into the correct command when processed. Fortunately, Make 
can reference the first member of the dependent list, the last member of the dependent list, and the current 
target being updated with the use of some special macros. These special macros have the form: 

$<file_ specifier><form_ qualifier> 

where <file_specifier> is one of: 
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" A " represents the current target being updated 

"[" represents the first member of the dependent list 

"]" represents the last member of the dependent list 

and <form_qualifier> is one of: 

full file name 

file name with extension removed 
"&" file name with path and extension removed 

file name with path removed 
path of file name 

If the file "D:\DIR1\DIR2\NAME.EXT" is the current target being updated then the following example will 
show how the form qualifiers are used. 


Macro 

Expansion for D:\DIR1\DIR2\NAME.EXT 

$ A @ 

D:\DIR1\DIR2\NAME.EXT 

$ A * 

D:\DIR1\DIR2\NAME 

$ A & 

NAME 

$ A . 

NAME.EXT 

$ A : 

D:\DIR1\DIR2\ 


These special macros provide the capability to reference targets and dependents in a variety of ways. 
# 

# programming example 

# (more macros) 

# 

version = debugging # debugging version 

msg_ production = linking production version ... 
msg_ debugging = linking debug version ... 

link_ options_ production = 

link_ options_ debugging = debug all 

link_ options = $ (link_ options_ $ (version) ) 
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compile_ options_ production = /mf /w3 
compile_ options_ debugging = /mf /dl /w3 
compile_ options = $ (compile_ options_ $ (version) ) 

compiler_ command = wcc386 $[* $ (compile_ options) 

header_ files = defs.h globals.h 
object_ files = main.obj input.obj calc.obj & 
output.obj 

plot.exe : $(object_ files) 

echo $(msg_ $(version)) 
wlink $ (link_ options) @$ A * 

main.obj : main.c $(header_ files) 

$(compiler_ command) 

calc.obj : calc.c $(header_ files) 

$ (compiler_ command) 

input.obj : input.c $(header_ files) 

$ (compiler_ command) 

output.obj : output.c $(header_ files) 

$ (compiler_ command) 

This example illustrates the use of the special dependency macros. Notice the use of "$ A *" in the linker 
command. The macro expands into the string "plot" since "plot.exe" is the target when the command is 
processed. The use of the special dependency macros is recommended because they make use of 
information that is already contained in the dependency rule. 

At this point, we know that macro references begin with a "$" and that comments begin with a "#". What 
happens if we want to use these characters without their special meaning? Make has two special macros 
that provide these characters to you. The special macro "$$" will result in a "$" when expanded and "$#" 
will expand into a "#". These special macros are provided so that you are not forced to work around the 
special meanings of the "$" and "#" characters. 

There is also a simple macro text substitution facility. We have previously seen that a macro call can be 
made with $(macroname). The construct $(macroname:stringl=string2) substitutes macroname with each 
occurrence of stringl replaced by string2. We have already seen that it can be useful for a macro to be a set 
of object file names separated by spaces. The file directive in wlink can accept a set of names separated by 
commas. 

# 

# programming example 

# (macro substitution) 

# 

. c . ob j : 

wcc386 -zq $*.c 

object_ files = main.obj input.obj calc.obj output.obj 

plot.exe : $(object_ files) 

wlink name $@ file $(object_ files: =,) 
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Note that macro substitution cannot be used with special macros. 

It is also worth noting that although the above example shows a valid approach, the same problem, that is, 
providing a list of object files to wlink, can be solved without macro subsitutions. The solution is using the 
{} syntax of wlink, as shown in the following example. Refer to the Open Watcom Linker Guide for 
details. 

# 

# programming example 

# (not using macro substitution) 

# 


.c.obj: 

wcc386 -zq $*.c 

object_ files = main.obj input.obj calc.obj output.obj 

plot.exe : $(object_ files) 

wlink name $@ file { $ (object_ files) } 


10.34 Implicit Rules 

Open Watcom Make is capable of accepting declarations of commonly used dependencies. These 
declarations are called "implicit rules" as opposed to "explicit rules" which were discussed previously. 
Implicit rules may be applied only in instances where you are able to describe a dependency in terms of file 
extensions. 


Hint: Recall that a file extension is the portion of the file name which follows the period. In the file 
specification: 

c:\dos\ansi.sys 

the file extension is "SYS". 


An implicit rule provides a command list for a dependency between files with certain extensions. The form 
of an implicit rule is as follows: 

. <dependent_ extension> . <target_ extension>: 

<command_ list> 

Implicit rules are used if a file has not been declared as a target in any explicit rule or the file has been 
declared as a target in an explicit rule with no command list. For a given target file, a search is conducted 
to see if there are any implicit rules defined for the target file’s extension in which case Make will then 
check if the file with the dependent extension in the implicit rule exists. If the file with the dependent 
extension exists then the command list associated with the implicit rule is executed and processing of the 
makefile continues. 

Other implicit rules for the target extension are searched in a similar fashion. The order in which the 
dependent extensions are checked becomes impoitant if there is more than one implicit rule declaration for 
a target extension. If we have the following makefile fragment: 
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Example: 

.pas.obj: 

(command list) 

. c . ob j : 

(command list) 

an ambiguity arises. If we have a target file "TEST.OBJ" then which do we check for first, "TEST.PAS" or 
"TEST.C"? Make handles this with the previously described . EXTENSIONS directive. Returning to our 
makefile fragment: 

.pas.obj: 

(command list) 

. c . ob j : 

(command list) 

and our target file "TEST.OBJ", we know that the . EXTENSIONS list determines in what order the 
dependents "TEST.PAS" and "TEST.C" will be tried. If the .EXTENSIONS declaration is: 

Example: 

.EXTENSIONS: 

.EXTENSIONS: .exe .obj .asm .pas .c .cpp .for .cob 

we can see that the dependent file "TEST.PAS" will be tried first as a possible dependent with "TEST.C" 
being tried next. 

One apparent problem with implicit rules and their associated command lists is that they are used for many 
different targets and dependents during the processing of a makefile. The same problem occurs with 
commands constructed from macros. Recall that there is a set of special macros that start with "$ A ", "$[", 
or "$]" that reference the target, first dependent, or last dependent of an explicit dependency rule. In an 
implicit rule there may be only one dependent or many dependents depending on whether the rule is being 
executed for a target with a single colon ":" or double colon dependency. If the target has a single 
colon or double colon dependency, the "$ A ", "$[", and "$]" special macros will reflect the values in the rule 
that caused the implicit rule to be invoked. Otherwise, if the target does not have a dependency rule then 
the "$[" and "$]" special macros will be set to the same value, namely, the file found in the implicit rule 
search. 

We will use the last programming example to illustrate a possible use of implicit mles. 

# 

# programming example 

# (implicit rules) 

# 

version = debugging # debugging version 

msg_ production = linking production version ... 
msg_ debugging = linking debug version ... 

link_ options_ production = 

link_ options_ debugging = debug all 

link_ options = $ (link_ options_ $ (version) ) 
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compiler = wcc386 

compile_ options_ production = /mf /w3 
compile_ options_ debugging = /mf /dl /w3 
compile_ options = $(compile_ options_ $(version)) 

header_ files = defs.h globals.h 
object_ files = main.obj input.obj calc.obj & 
output.obj 

plot.exe : $(object_ files) 

echo $(msg_ $(version)) 
wlink $ (link_ options) @$ /v * 


. c . ob j : 

$(compiler) $[* $(compile_ options) 

main.obj : main.c $(header_ files) 

calc.obj : calc.c $(header_ files) 

input.obj : input.c $(header_ files) 

output.obj : output.c $(header_ files) 

As this makefile is processed, any time an object file is found to be older than its associated source file or 
header files then Make will attempt to execute the command list associated with the explicit rule. Since 
there are no command lists associated with the four object file targets, an implicit rule search is conducted. 
Suppose "CALC.OBJ" was older than "CALC.C". The lack of a command list in the explicit rule with 
"CALC.OBJ" as a target causes the ".c.obj" implicit rule to be invoked for "CALC.OBJ". The file 
"CALC.C" is found to exist so the commands 

wcc386 calc /mf /dl /w3 

echo linking debug version ... 

wlink debug all @plot 

are executed. The last two commands are a result of the compilation of "CALC.C" producing a 
"CALC.OBJ" file that is younger than the "PLOT.EXE" file that in turn must be generated again. 

The use of implicit rules is straightforward when all the files that the makefile deals with are in the current 
directory. Larger applications may have files that are in many different directories. Suppose we moved the 
programming example files to three sub-directories. 


Files 

Sub-directory 

*.H 

\EXAMPLE\H 

*.C 

\EXAMPLE\C 

rest 

\EXAMPLE\0 


Now the previous makefile (located in the \EXAMPLE\O sub-directory) would look like this: 
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# 

# programming example 

# (implicit rules) 

# 

h_ dir = \example\h\ #sub-directory containing header files 

c_ dir = \example\c\ #sub-directory containing C/C++ files 

version = debugging # debugging version 

msg_ production = linking production version ... 
msg_ debugging = linking debug version ... 

link_ options_ production = 

link_ options_ debugging = debug all 

link_ options = $ (link_ options_ $ (version) ) 

compiler = wcc386 

compile_ options_ production = /mf /w3 
compile_ options_ debugging = /mf /dl /w3 
compile_ options = $ (compile_ options_ $ (version) ) 

header_ files = $ (h_ dir) defs . h $ (h_ dir) globals . h 
object_ files = main.obj input.obj calc.obj & 
output.obj 

plot.exe : $(object_ files) 

echo $ (msg_ $ (version) ) 
wlink $(link_ options) 


. c. ob j : 

$ (compiler) $[* $ (compile_ options) 
main.obj : $ (c_ dir) main. c $ (header_ files) 
calc.obj : $ (c_ dir) calc. c $ (header_ files) 
input, obj : $ (c_ dir) input. c $ (header_ files) 
output, obj : $ (c_ dir) output. c $ (header_ files) 

Suppose "\EXAMPLE\0\CALC.OBJ" was older than "\EXAMPLE\C\CALC.C". The lack of a command 
list in the explicit rule with "CALC.OBJ" as a target causes the ".c.obj" implicit rule to be invoked for 
"CALC.OBJ". At this time, the file "\EXAMPLE\O\CALC.C" is not found so an error is reported 
indicating that "CALC.OBJ" could not be updated. How may implicit rules be useful in larger applications 
if they will only search the current directory for the dependent file? We must specify more information 
about the dependent extension (in this case ".C"). We do this by associating a path with the dependent 
extension as follows: 

. <dependent_ extension> : <path_ specif ication> 

This allows the implicit rule search to find the files with the dependent extension. 


Hint: A valid path specification is made up of directory specifications separated by semicolons 
Here are some path specifications: 

D :;C:\DOS;C:\UTILS;C:\WC 
C:\SYS 
A:\BIN;D: 

Notice that these path specifications are identical to the form required by the operating system shell's 
"PATH" command. 
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Our makefile will be correct now if we add the new declaration as follows: 

# 

# programming example 

# (implicit rules) 

# 

h_ dir = \example\h\ #sub-directory containing header files 

c_ dir = \example\c\ #sub-directory containing C/C++ files 

version = debugging # debugging version 

msg_ production = linking production version ... 
msg_ debugging = linking debug version ... 

link_ options_ production = 

link_ options_ debugging = debug all 

link_ options = $ (link_ options_ $ (version) ) 

compiler = wcc386 

compile_ options_ production = /mf /w3 
compile_ options_ debugging = /mf /dl /w3 
compile_ options = $ (compile_ options_ $ (version) ) 

header_ files = $ (h_ dir) defs . h $ (h_ dir) globals . h 
object_ files = main.obj input.obj calc.obj & 
output.obj 

plot.exe : $(object_ files) 

echo $ (msg_ $(version)) 
wlink $ (link_ options) @$ A * 

. c: $ (c_ dir) 

.c.obj: 

$ (compiler) $[* $ (compile_ options) 
main.obj : $ (c_ dir) main. c $ (header_ files) 
calc.obj : $ (c_ dir) calc. c $ (header_ files) 
input, obj : $ (c_ dir) input. c $ (header_ files) 
output, obj : $ (c_ dir) output. c $ (header_ files) 

Suppose "\EXAMPLE\O\CALC.OBJ" is older than "\EXAMPLE\C\CALC.C”. The lack of a command list 
in the explicit rule with "CALC.OBJ" as a target will cause the ".c.obj" implicit rule to be invoked for 
"CALC.OBJ". The dependent extension ".C" has a path associated with it so the file 
"\EXAMPLE\C\CALC.C" is found to exist. The commands 

wcc386 \EXAMPLE\C\CALC /mf /dl /w3 
echo linking debug version ... 
wlink debug all @plot 

are executed to update the necessary files. 

If the application requires many source files in different directories Make will search for the files using 
their associated path specifications. For instance, if the current example files were setup as follows: 

Sub-directory Contents 

\EXAMPLE\H 

DEFS.H, GLOBALS.H 

\EXAMPLE\C\PROGRAM 

MAIN.C, CALC.C 
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\EXAMPLE\C\SCREEN 

INPUT.C, OUTPUT.C 


\EXAMPLE\O 

PLOT.EXE, MAKEFILE, MAIN.OBJ, CALC.OBJ, INPUT.OBJ, OUTPUT.OBJ 

the makefile would be changed to: 

# 

# programming example 

# (implicit rules) 

# 

h_ dir = ..\h\ # sub-directory with header files 

# sub-directories with C/C++ source files 
program_ dir = . .\c\program\ # - MAIN.C, CALC.C 
screen, dir = ..\c\screen\ # - INPUT. C, OUTPUT. C 

version = debugging # debugging version 

msg_ production = linking production version ... 
msg_ debugging = linking debug version ... 

link_ options_ production = 

link_ options_ debugging = debug all 

link_ options = $ (link_ options_ $ (version) ) 

compiler = wcc386 

compile_ options_ production = /mf /w3 
compile_ options_ debugging = /mf /dl /w3 
compile_ options = $ (compile_ options_ $ (version) ) 

header_ files = $ (h_ dir) defs . h $ (h_ dir) globals . h 
object_ files = main.obj input.obj calc.obj & 
output.obj 

plot.exe : $(object_ files) 

echo $ (msg_ $(version)) 
wlink $ (link_ options) @$ A * 

.c: $ (program_ dir) ; $ (screen, dir) 

.c.obj: 

$ (compiler) $[* $ (compile_ options) 
main.obj : $ (program_ dir) main. c $ (header_ files) 
calc.obj : $ (program_ dir) calc. c $ (header_ files) 
input.obj : $(screen, dir)input.c $(header_ files) 
output, obj : $ (screen, dir) output. c $ (header_ files) 


Suppose that there is a change in the "DEFS.H" file which causes all the source files to be recompiled. The 
implicit rule ".c.obj" is invoked for every object file so the corresponding ".C" file must be found for each 
".OBJ" file. We will show where Make searches for the C/C++ source files. 


update main.obj 

test ..\c\program\main.c 
execute wcc386 ..\c\program\main /mf 


(it does 
/dl /w3 


exist) 


update calc.obj 

test ..\c\program\calc.c 

execute wcc386 ..\c\program\calc /mf 


(it does 
/dl /w3 


exist) 
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update 

test 

test 

execute 


input.obj 

. . \c\program\input.c 
..\c\screen\input.c 
wcc386 ..\c\screen\input 


(it does not exist) 
(it does exist) 
/mf /dl /w3 


update 

test 

test 

execute 


output.obj 

..\c\program\output. c 
..\c\screen\output.c 
wcc386 ..\c\screen\output 


(it does not exist) 
(it does exist) 
/mf /dl /w3 


etc. 


Notice that Make checked the sub-directory ”..\C\PROGRAM" for the files "INPUT.C" and "OUTPUT.C”. 
Make optionally may use a circular path specification search which may save on disk activity for large 
makefiles. The circular path searching may be used in two different ways: 

1. use the command line option "o" 

2. use the . OPTIMIZE directive. 


Make will retain (for each suffix) what sub-directory yielded the last successful search for a file. The 
search for a file is resumed at this directory in the hope that wasted disk activity will be minimized. If the 
file cannot be found in the sub-directory then Make will search the next sub-directory in the path 
specification (cycling to the first sub-directory in the path specification after an unsuccessful search in the 
last sub-directory). 

Changing the previous example to include this feature, results in the following: 

# 

# programming example 

# (optimized path searching) 

# 

.OPTIMIZE 

h_ dir = ..\h\ # sub-directory with header files 

# sub-directories with C/C++ source files 
program_ dir = ..\c\program\ # - MAIN.C, CALC.C 
screen, dir = ..\c\screen\ # - INPUT. C, OUTPUT.C 

version = debugging # debugging version 

msg_ production = linking production version ... 
msg_ debugging = linking debug version ... 

link_ options_ production = 

link_ options_ debugging = debug all 

link_ options = $ (link_ options_ $ (version) ) 

compiler = wcc386 

compile_ options_ production = /mf /w3 
compile_ options_ debugging = /mf /dl /w3 
compile_ options = $ (compile_ options_ $ (version) ) 

header_ files = $ (h_ dir) defs . h $ (h_ dir) globals . h 
object_ files = main.obj input.obj calc.obj & 
output.obj 

plot.exe : $(object_ files) 

echo $ (msg_ $(version)) 
wlink $ (link_ options) @$ A * 

.c: $ (program_ dir) ; $ (screen, dir) 

. c. ob j : 

$ (compiler) $[* $ (compile_ options) 
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main.obj : $ (program_ dir) main. c $ (header_ files) 
calc.obj : $ (program_ dir) calc. c $ (header_ files) 
input, obj : $ (screen, dir) input. c $ (header_ files) 
output, obj : $ (screen_ dir) output. c $ (header_ files) 


Suppose again that there is a change in the "DEFS.H" file which causes all the source files to be 
recompiled. We will show where Make searches for the C/C++ source files using the optimized path 
specification searching. 


update 

test 

execute 

update 

test 

execute 

update 

test 

test 

execute 

update 

test 

execute 

etc. 


main.obj 

..\c\program\main.c (it does exist) 

wcc386 ..\c\program\main /mf /dl /w3 

calc.obj 

..\c\program\calc.c (it does exist) 

wcc386 ..\c\program\calc /mf /dl /w3 

input.obj 

..\c\program\input.c (it does not exist) 

..\c\screen\input.c (it does exist) 

wcc386 ..\c\screen\input /mf /dl /w3 

output.obj 

..\c\screen\output.c (it does exist) 

wcc386 ..\c\screen\output /mf /dl /w3 


Make did not check the sub-directory "..\C\PROGRAM" for the file "OUTPUT.C" because the last 
successful attempt to find a ".C" file occurred in the "..\C\SCREEN" sub-directory. In this small example, 
the amount of disk activity saved by Make is not substantial but the savings become much more 
pronounced in larger makefiles. 


Hint: The simple heuristic method that Make uses for optimizing path specification searches namely, 
keeping track of the last successful sub-directory, is very effective in reducing the amount of disk 
activity during the processing of a makefile. A pitfall to avoid is having two files with the same name 
in the path. The version of the file that is used to update the target depends on the previous searches. 
Care should be taken when using files that have the same name with path specifications. 


Large makefiles for projects written in C/C++ may become difficult to maintain with all the header file 
dependencies. Ignoring header file dependencies and using implicit rules may reduce the size of the 
makefile while keeping most of the functionality intact. The previous example may be made smaller by 
using this idea. 
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# 

# programming example 

# (no header dependencies) 

# 

.OPTIMIZE 

h_ dir = ..\h\ # sub-directory with header files 

# sub-directories with C/C++ source files 
program_ dir = ..\c\program\ # - MAIN.C, CALC.C 
screen, dir = ..\c\screen\ # - INPUT.C, OUTPUT.C 

version = debugging # debugging version 

msg_ production = linking production version ... 
msg_ debugging = linking debug version ... 

link_ options_ production = 

link_ options_ debugging = debug all 

link_ options = $ (link_ options_ $ (version) ) 

compiler = wcc386 

compile_ options_ production = /mf /w3 
compile_ options_ debugging = /mf /dl /w3 
compile_ options = $ (compile_ options_ $ (version) ) 

object_ files = main.obj input.obj calc.obj & 
output.obj 

plot.exe : $(object_ files) 

echo $ (msg_ $(version)) 
wlink $ (link_ options) 

.c: $ (program_ dir) ; $ (screen, dir) 

. c. ob j : 

$ (compiler) $[* $ (compile_ options) 

Implicit rules are very useful in this regard providing you are aware that you have to make up for the 
information that is missing from the makefile. In the case of C/C++ programs, you must ensure that you 
force Make to compile any programs affected by changes in header files. Forcing Make to compile 
programs may be done by touching source files (not recommended), deleting object files, or using the "a" 
option and targets on the command line. Here is how the files "INPUT.OBJ" and "MAIN.OBJ" may be 
recompiled if a change in some header file affects both files. 

Example: 

del input.obj 
del main.obj 
wmake 

or using the "a" option 
Example: 

wmake /a input.obj main.obj 

The possibility of introducing bugs into programs is present when using this makefile technique because it 
does not protect the programmer completely from object modules becoming out-of-date. The use of 
implicit rules without header file dependencies is a viable makefile technique but it is not without its 
pitfalls. 
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10.35 Double Colon Explicit Rules 

Single colon explicit rules are useful in many makefile applications. However, the single colon rule has 
certain restrictions that make it difficult to express more complex dependency relationships. The 
restrictions imposed on single colon explicit rules are: 

1. only one command list is allowed for each target 

2. after the command list is executed, the target is considered up to date 

The first restriction becomes evident when you want to update a target in different ways (i.e., when the 
target is out of date with respect to different dependents). The double colon explicit rule removes this 
restriction. 

# 

# multiple command lists 

# 

targetl :: dependentl dependent2 
commandl 

targetl :: dependents dependent4 
command2 

Notice that if "targetl" is out of date with respect to either "dependentl" or "dependent2" then "commandl" 
will be executed. The double colon explicit rule does not consider the target (in this case "targetl") up 
to date after the command list is executed. Make will continue to attempt to update "targetl". Afterwards 
"command2" will be executed if "targetl" is out of date with respect to either "dependent3" or 
"dependent4". It is possible that both "commandl" and "command2" will be executed. As a result of the 
target not being considered up to date, an implicit rule search will be conducted on "targetl" also. Make 
will process the double colon explicit rules in the order that they are encountered in the makefile. A 
useful application of the double colon explicit rule involves maintaining and using prototype 
information generated by a compiler. 

# 

# double colon "::" example 

# 

compiler = wcc386 
options = /w3 

# generate macros for the .OBJ and ,DEF files 
template = modulel.$(ext) module2.$(ext) module3.$(ext) 
ext = obj 

objs = $+ $(template) $- 
ext = def 

defs = $+ $(template) $- 

# add .DEF to the extensions list 
.EXTENSIONS: 

.EXTENSIONS: .exe .obj .def .c 
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# implicit rules for the .OBJ and .DEF files 
. c.obj: 

$(compiler) $[* $ (options) 

# generate the prototype file (only do a syntax check) 

.c.def: 

$(compiler) $[* $ (options) /v/zs 

program.exe :: $(defs) 
erase *.err 

program.exe :: $(objs) 
wlink @$ A * 

The ".OBJ" files are updated to complete the update of the file "PROGRAM.EXE". It is important to keep 
in mind that Make does not consider the file "PROGRAM.EXE" up to date until it has conducted a final 
implicit rule search. The double colon explicit rule is useful when describing complex update actions. 

10.36 Preprocessing Directives 

One of the primary objectives in using a make utility is to improve the development and maintenance of 
projects. A programming project consisting of many makefiles in different sub-directories may become 
unwieldy to maintain. The maintenance problem stems from the amount of duplicated information 
scattered throughout the project makefiles. Make provides a method to reduce the amount of duplicated 
information present in makefiles. Preprocessing directives provide the capability for different makefiles to 
make use of common information. 

10.36.1 File Inclusion 

A common solution to the "duplicated information" problem involves referencing text contained in one file 
from many different files. Make supports file inclusion with the ! include preprocessing directive. The 
development of object libraries, using 16-bit Open Watcom C/C++, for the different 80x86 16-bit memory 
models provides an ideal example to illustrate the use of the ! include preprocessing directive. 

Sub-directory Contents 

\ WINDOW WINDOW. CMD, WINDOW.MIF 

\WINDOW\H PROTO. H, GLOBAL S . H, BIOS_DEF.H 
\WINDOW\C WINDOW. C, KEYBOARD. C, MOUSE. C, BIOS.C 

\WINDOW\SCSD 

small model object files, MAKEFILE, WINDOW_ S . LIB 

\WINDOW\SCBD 

compact model object files, MAKEFILE, WINDOW_ C . LIB 

\WINDOW\BCSD 

medium model object files, MAKEFILE, WINDOW_ M. LIB 
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\WINDOW\BCBD 

large model object files, MAKEFILE, WINDOW_ L . LIB 

\WINDOW\BCHD 

huge model object files, MAKEFILE, WINDOW_ L . LIB 

The WLIB command file "WINDOW.CMD" contains the list of library operations required to build the 
libraries. The contents of "WINDOW.CMD" are: 

-iwindow 
-+bios 
-ikeyboard 
—hmouse 

The library manager command indicates to WLIB that the object file should be replaced in the library. 

The file "WINDOW.MIF" contains the makefile declarations that are common to every memory model. 

The ".MIF" extension will be used for all the Make Include Files discussed in this manual. This extension 
is also in the default extension list so it is a recommended extension for Make include files. The contents of 
the "WINDOW.MIF" file is as follows: 

# 

# example of a Make Include File 

# 

common = /dl /w3 # common options 

objs = window.obj bios.obj keyboard.obj mouse.obj 

.c : . . \c 

. c . ob j : 

wcc $[* $(common) $(local) /m$(model) 

window_ $(model).lib : $(objs) 

wlib window_ $(model) @..\window 

The macros "model" and "local" are defined by the file "MAKEFILE" in each object directory. An 
example of the file "MAKEFILE" in the medium memory model object directory is: 

# 

# !include example 

# 

model = m # memory model required 

local = # memory model specific options 

[include ..\window.mif 

Notice that changes that affect all the memory models may be made in one file, namely "WINDOW.MIF". 
Any changes that are specific to a memory model may be made to the "MAKEFILE" in the object 
directory. To update the medium memory model library, the following commands may be executed: 
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Example: 

C>cd \window\bcsd 
C>wmake 

A DOS ".BAT" or OS/2 ".CMD" file may be used to update all the different memory models. If the 
following DOS "MAKEALL.BAT" (OS/2 "MAKEALL.CMD") file is located somewhere in the "PATH", 
we may update all the libraries. 


cd \window\scsd 
wmake %1 %2 %3 %4 

%5 

% 6 

%7 

o \° 

00 

%9 

cd \window\scbd 
wmake %1 %2 %3 %4 

%5 

% 6 

%7 

%8 

%9 

cd \window\bcsd 
wmake %1 %2 %3 %4 

%5 

% 6 

%7 

%8 

%9 

cd \window\bcbd 
wmake %1 %2 %3 %4 

%5 

% 6 

%7 

%8 

%9 

cd \window\bchd 
wmake %1 %2 %3 %4 

%5 

% 6 

%7 

%8 

%9 


The batch file parameters are useful if you want to specify options to Make. For instance, a global 
recompile may be done by executing: 


Example: 

Omakeall /a 


The ! include preprocessing directive is a good way to partition common information so that it may be 
maintained easily. 


Another use of the ! include involves program generated makefile information. For instance, if we have 
a program called "WMKMK" that will search through source files and generate a file called 
"WMKMK.MIF" that contains: 

# 

# program generated makefile information 

# 

C_ to_ OBJ = $(compiler) $[* $(compile_ options) 

OBJECTS = WINDOW.OBJ BIOS.OBJ KEYBOARD.OBJ MOUSE.OBJ 

WINDOW.OBJ : ..\C\WINDOW.C ..\H\PROTO.H ..\H\GLOBALS.H 

$ (C_ tO_ OBJ) 

BIOS.OBJ : . . \C\BIOS . C . . \H\BIOS_ DEF . H . . \H\GLOBALS . H 

$ (C_ tO_ OBJ) 

KEYBOARD.OBJ : ..\C\KEYBOARD.C ..\H\PROTO.H ..\H\GLOBALS.H 

$ (C_ tO_ OBJ) 

MOUSE.OBJ : ..\C\MOUSE.C ..\H\PROTO.H ..\H\GLOBALS.H 
$ (C_ tO_ OBJ) 


In order to use this program generated makefile information, we use a "MAKEFILE" containing: 
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# 

# makefile that makes use of generated makefile information 

# 

compile_ options = /mf /dl /w3 

first_ target : window.lib .SYMBOLIC 
echo done 

!include wmkmk.mif 

window.lib : $(OBJECTS) 

wlib window $(OBJECTS) 

make : .SYMBOLIC 

wmkmk /r ..\c\*.c+..\c\*.cpp+..\h 

Notice that there is a symbolic target "first_target" that is used as a "place holder". The default behaviour 
for Make is to "make" the first target encountered in the makefile. The symbolic target "first_target" 
ensures that we have control over what file will be updated first (in this case "WINDOW.LIB"). The use of 
the ! include preprocessing directive simplifies the use of program generated makefile information 
because any changes are localized to the file "MAKEFILE". As program development continues, the file 
"WMKMK.MIF" may be regenerated so that subsequent invocations of WMAKE benefit from the new 
makefile information. The file "MAKEFILE" even contains the command to regenerate the file 
"WMKMK.MIF". The symbolic target "make" has an associated command list that will regenerate the file 
"WMKMK.MIF". The command list can be executed by typing the following command: 

Example: 

C>wmake make 

The use of the ! include preprocessing directive is a simple way to reduce maintenance of related 
makefiles. 


Hint: Macros are expanded on ! include preprocessor control lines. This allows many benefits like: 
!include $(%env_var) 

so that the files that Make will process can be controlled through many different avenues like internal 
macros, command line macros, and environment variables. 

Another way to access files is through the suffix path feature of Make. A definition like 
. mif: c:\mymifs;d:\some\more\mifs 

will cause Make to search different paths for any make include files. 


10.36.2 Conditional Processing 

Open Watcom Make has conditional preprocessing directives available that allow different declarations to 
be processed. The conditional preprocessing directives allow the makefile to 

1. check whether a macro is defined, and 

2. check whether a macro has a certain value. 

The macros that can be checked include 
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1. normal macros "$(<macro_identifier>)" 

2. environment macros "$(%<environment_var>)" 

The conditional preprocessing directives allow a makefile to adapt to different external conditions based on 
the values of macros or environment variables. We can define macros on the WMAKE command line as 
shown in the following example. 

Example: 

C>wmake "macro=some text with spaces in it" 

Alternatively, we can include a makefile that defines the macros if all the macros cannot fit on the 
command line. This is shown in the following example: 

Example: 

C>wmake /f macdef.mif /f makefile 

Also, environment variables can be set before WMAKE is invoked. This is shown in the following 
example: 

Example: 

C>set macro=some text with spaces in it 
C>wmake 

Now that we know how to convey information to Make through either macros or environment variables, we 
will look at how this information can be used to influence makefile processing. 

Make has conditional preprocessing directives that are similar to the C preprocessor directives. Make 
supports these preprocessor directives: 

! ifeq 
! ifneq 
!ifeqi 
! ifneqi 
! ifdef 
! ifndef 

along with 

! else 
! endif 

Together these preprocessor directives allow selection of makefile declarations to be based on either the 
value or the existence of a macro. 

Environment variables can be checked by using an environment variable name prefixed with a A 
common use of a conditional preprocessing directive involves setting environment variables. 

# 

# setting an environment variable 

# 

!ifndef %lib 
.BEFORE 

set lib=c:\watcom\lib386;c:\watcom\lib386\dos 

!endif 
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If you are writing portable applications, you might want to have: 

# 

# checking a macro 

# 

[include version.mif 

!ifdef 0S2 
machine = /2 
! else 

machine = /0 
!endif 

The ! if def ("if defined") and ! ifndef ("if not defined") conditional preprocessing directives are useful 
for checking boolean conditions. In other words, the ! ifdef and ! ifndef are useful for "yes-no" 
conditions. There are instances where it would be useful to check a macro against a value. In order to use 
the value checking preprocessor directives, we must know the exact value of a macro. A macro definition 
is of the form: 

<macro_ identifier> = <text> <comment> 

Make will first strip any comment off the line. The macro definition will then be the text following the 
equal "=" sign with leading and trailing blanks removed. Initially this might not seem like a sensible way 
to define a macro but it does lend itself well to defining macros that are common in makefiles. For 
instance, it allows definitions like: 

# 

# sample macro definitions 

# 

link_ options = debug line # line number debugging 

compile_ options = /dl /s # line numbers, no stack checking 

These definitions are both readable and useful. A makefile can handle differences between compilers with 
the lifeq, lifneq, lifeqiand ! ifneqi conditional preprocessing directives. The first two 
perform case sensitive comparisons while the last two perform case insensitive comparisons. One way of 
setting up adaptive makefiles is: 

# 

# options made simple 

# 

compiler = wcc386 

stack_ overflow = No # yes -> check for stack overflow 

line_ info = Yes # yes -> generate line numbers 


!ifeq compiler wcc386 
lifneqi stack_ overflow yes 
stack_ option = /s 

!endif 

lifeqi line_ info yes 

line_ option = /dl 

!endif 
!endif 


# compile for 286 

# default: 8086 
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!ifeq compiler tcc 
lifeqi stack_ overflow yes 

stack_ option = -N 

!endif 

lifeqi line_ info yes 

line_ option = -y 

!endif 
!endif 
# 


# make sure the macros are defined 

# 

lifndef stack_ option 
stack_ option = 

! endif 

lifndef line_ option 
line_ option = 

! endif 

example : .SYMBOLIC 

echo $ (compiler) $ (stack_ option) $(line_ option) 

The conditional preprocessing directives can be very useful to hide differences, exploit similarities, and 
organize declarations for applications that use many different programs. 

Another directive is the ! define directive. This directive is equivalent to the normal type of macro 
definition (i.e., macro = text) but will make C programmers feel more at home. One important distinction 
is that the ! define preprocessor directive may be used to reflect the logical structure of macro definitions 
in conditional processing. For instance, the previous makefile could have been written in this style: 

lifndef stack_ option 
1 define stack_ option 
1endif 

lifndef line_ option 
1 define line_ option 
1endif 

The "1" character must be in the first column but the directive keyword can be indented. This freedom 
applies to all of the preprocessing directives. The 1 else preprocessing directive benefits from this type of 
style because 1 else can also check conditions like: 

lelse ifeq 
lelse ifneq 
lelse ifeqi 
lelse ifneqi 
lelse ifdef 
lelse ifndef 

so that logical structures like: 
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lifdef %version 
! ifeq %version debugging 
! define option debug all 

! else ifeq %version beta 
! define option debug line 

! else ifeq %version production 
! define option debug 

! else 

! error invalid value in VERSION 

! endif 
!endif 

can be used. The above example checks the environment variable "VERSION" for three possible values 
and acts accordingly. 

Another derivative from the C language preprocessor is the ! error directive which has the form of 
!error <text> 

in Make. This directive will print out the text and terminate processing of the makefile. It is very useful in 
preventing errors from macros that are not defined properly. Here is an example of the ! error 
preprocessing directive. 

Iifndef stack_ option 

! error stack_ option is not defined 
!endif 

Iifndef line_ option 

! error line_ option is not defined 
! endif 

There is one more directive that can be used in a makefile. The ! undef preprocessing directive will clear 
a macro definition. The ! undef preprocessing directive has the form: 

!undef <macro_ identifier> 

The macro identifier can represent a normal macro or an environment variable. A macro can be cleared 
after it is no longer needed. Clearing a macro will reduce the memory requirements for a makefile. If the 
macro identifier represents an environment variable (i.e., the identifier has a prefix) then the 
environment variable will be deleted from the current environment. The ! undef preprocessing directive 
is useful for deleting environment variables and reducing the amount of internal memory required during 
makefile processing. 

10.36.3 Loading Dynamic Link Libraries 

Open Watcom Make supports loading of Dynamic Link Library (DLL) versions of Open Watcom software 
through the use of the ! loaddll preprocessing directive. This support is available on Win32 and 32-bit 
OS/2 platforms. Performance is greatly improved by avoiding a reload of the software for each file to be 
processed. The syntax of the ! loaddll preprocessing directive is: 

!loaddll $(exename) $(dllname) 

where $ (exename) is the command name used in the makefile and $ (dllname) is the name of the 
DLL to be loaded and executed in its place. Lor example, consider the following makefile which contains a 
list of commands and their corresponding DLL versions. 
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# Default compilation macros for sample programs 

# 

# Compile switches that are enabled 


CFLAGS = -dl 

CC = wpp386 $(CFLAGS) 

LFLAGS = DEBUG ALL 

LINK = wlink $(LFLAGS) 


ifdef_LOADDLL 


loaddll 

wcc 

weed 

loaddll 

wccaxp 

weedaxp 

loaddll 

wcc38 6 

wccd38 6 

loaddll 

wpp 

wppdi8 6 

loaddll 

wppaxp 

wppdaxp 

loaddll 

wpp38 6 

wppd38 6 

loaddll 

wlink 

wlinkd 

loaddll 

wlib 

wlibd 


endif 


. c . ob j : 

$(CC) $*.c 


The_ LOADDLL _symbol is defined for versions of Open Watcom Make that support th&oaddll 

preprocessing directive. The ! ifdef_LOADDLL _construct ensures that the makefile can be 

processed by an older version of Open Watcom Make. 

Make will look up the wpp3 8 6 command in its DLL load table and find a match. It will then attempt to 
load the corresponding DLL (i.e., wppd3 8 6.dll) and pass it the command line for processing. The 
lookup is case insensitive but must match in all other respects. For example, if a path is included with the 
command name then the same path must be specified in the ! loaddll preprocessing directive. This 
problem can be avoided through the use of macros as illustrated below. 
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# Default 

# 

# Compile 

# 

cc286 = 

cc286d = 
cc386 = 

cc386d = 
linker = 
linkerd = 


compilation macros for sample programs 

switches that are enabled 

wpp 

wppdi8 6 
wpp38 6 
wppd38 6 
wlink 
wlinkd 


CFLAGS = -dl 

CC = $ (cc386) $(CFLAGS) 


DEBUG ALL 
wlink $(LFLAGS) 


LFLAGS 

LINK 

!ifdef _ 
!loaddll 
!loaddll 
!loaddll 
!endif 


_ LOADDLL, 
$(cc286) 

$(cc386) 

$(linker) 


$ (cc286d) 

$ (cc386d) 

$(linkerd) 


. c . ob j : 

$(CC) $*.c 


A path and/or extension may be specified with the DLL name if desired. 


10.37 Command List Directives 


Open Watcom Make supports special directives that provide command lists for different purposes. If a 
command list cannot be found while updating a target then the directive . DEFAULT may be used to 
provide one. A simple . DEFAULT command list which makes the target appear to be updated is: 

.DEFAULT 

wtouch $ A @ 

The Open Watcom Touch utility sets the time-stamp on the file to the current time. The effect of the above 
rule will be to "update" the file without altering its contents. 

In some applications it is necessary to execute some commands before any other commands are executed 
and likewise it is useful to be able to execute some commands after all other commands are executed. 

Make supports this capability by checking to see if the . BEFORE and . AFTER directives have been used. 

If the . BEFORE directive has been used, the . BEFORE command list is executed before any commands are 
executed. Similarly the . AFTER command list is executed after processing is finished. It is important to 
note that if all the files are up to date and no commands must be executed, the . BEFORE and . AFTER 
command lists are never executed. If some commands are executed to update targets and errors are 
detected (non-zero return status, macro expansion errors), the . AFTER command list is not executed (the 
. ERROR directive supplies a command list for error conditions and is discussed in this section). These two 
directives may be used for maintenance as illustrated in the following example: 
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# 

# .BEFORE and .AFTER example 

# 

.BEFORE 

echo .BEFORE command list executed 

.AFTER 

echo .AFTER command list executed 

# 

# rest of makefile follows 

# 


If all the targets in the makefile are up to date then neither the . BEFORE nor the . AFTER command lists 
will be executed. If any of the targets are not up to date then before any commands to update the target are 
executed, the . BEFORE command list will be executed. The . AFTER command list will be executed only 
if there were no errors detected during the updating of the targets. The .BEFORE, .DEFAULT, and 
.AFTER command list directives provide the capability to execute commands before, during, and after the 
makefile processing. 


Make also supports the . ERROR directive. The . ERROR directive supplies a command list to be executed 
if an error occurs during the updating of a target. 


# 

# .ERROR example 

# 

.ERROR 


beep 

# 

# rest of makefile 

# 


follows 


The above makefile will audibly signal you that an error has occurred during the makefile processing. If 
any errors occur during the . ERROR command list execution, makefile processing is terminated. 


10.38 MAKEINIT File 


As you become proficient at using Open Watcom Make, you will probably want to isolate common 
makefile declarations so that there is less duplication among different makefiles. Make will search for a 
file called "MAKEINIT" (or "TOOLS.INI" when the "ms" option is set) and process it before any other 
makefiles. The search for the "MAKEINIT" file will occur along the current "PATH". If the file 
"MAKEINIT" is not found, processing continues without any errors. By default. Make defines a set of data 
described at the "r" option. The use of a "MAKEINIT" file will allow you to reuse common declarations 
and will result in simpler, more maintainable makefiles. 
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10.39 Command List Execution 


Open Watcom Make is a program which must execute other programs and operating system shell 
commands. There are three basic types of executable files in DOS. 

1. .COM files 

2. . EXE files 

3. .BAT files 

There are two basic types of executable files in Windows NT. 

1. .EXE files 

2. . BAT files 

There are two basic types of executable files in OS/2. 

1. .EXE files 

2. . CMD files 

The . COM and . EXE files may be loaded into memory and executed. The . BAT files must be executed by 
the DOS command processor or shell, "COMMAND.COM". The . CMD files must be executed by the 
OS/2 command processor or shell, "CMD.EXE" Make will search along the "PATH" for the command and 
depending on the file extension the file will be executed in the proper manner. 

If Make detects any input or output redirection characters (these are ">", "<", and "I") in the command, it 
will be executed by the shell. 

Under DOS, an asterisk prefix (*) will cause Make to examine the length of the command argument. If it is 
too long (> 126 characters), it will take the command argument and stuff it into a temporary environment 
variable and then execute the command with "@env_var" as its argument. Suppose the following sample 
makefile fragment contained a very long command line argument. 

# 

# Asterisk example 

# 

*foo myfile /a /b /c ... /x /y /z 

Make will perform something logically similar to the following steps. 

set TEMPVAR001=myfile /a /b /c ... /x /y /z 
too @TEMPVAR0 01 

The command must, of course, support the "@env_var" syntax. Typically, DOS commands do not support 
this syntax but many of the Open Watcom tools do. 

The exclamation mark prefix (!) will force a command to be executed by the shell. Also, the command will 
be executed by the shell if the command is an internal shell command from the following list: 


break 

(check for Ctrl+Break) 

call 

(nest batch files) 

chdir 

(change current directory) 

cd 

(change current directory) 
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els 

(clear the screen) 

cmd 

(start NT or OS/2 command processor) 

command 

(start DOS command processor) 

copy 

(copy or combine files) 

ctty 

(DOS redirect input/output to COM port) 

d: 

(change drive where "d" represents a drive specifier) 

date 

(set system date) 

del 

(erase files) 

dir 

(display contents in a directory) 

echo 

(display commands as they are processed) 

erase 

(erase files) 

for 

(repetitively process commands, intercepted by WMAKE) 

if 

(allow conditional processing of commands) 

md 

(make directory) 

mkdir 

(make directory) 

path 

(set search path) 

pause 

(suspend batch operations) 

prompt 

(change command prompt) 

ren 

(rename files) 

rename 

(rename files) 

rmdir 

(remove directory) 

rd 

(remove directory) 

rm 

(erase files or directories, intercepted by WMAKE) 

set 

(set environment variables, intercepted by WMAKE) 

time 

(set system time) 

type 

(display contents of a file) 

ver 

(display the operating system version number) 

verify 

(set data verification) 

vol 

(display disk volume label) 


The operating system shell "SET" command is intercepted by Make. The "SET" command may be used to 
set environment variables to values required during makefile processing. The environment variable 
changes are only valid during makefile processing and do not affect the values that were in effect before 
Make was invoked. The "SET" command may be used to initialize environment variables necessary for the 
makefile commands to execute properly. The setting of environment variables in makefiles reduces the 
number of "SET" commands required in the system initialization file. Here is an example with the Open 
Watcom C/C++ compiler. 

# 

# SET example 

# 

.BEFORE 

set include=c:\special\h;$(%include) 

set lib=c:\watcom\lib386;c:\watcom\lib386\dos 

# 

# rest of makefile follows 

# 


The first "SET" command will set up the INCLUDE environment variable so that the Open Watcom 
C/C++ compiler may find header files. Notice that the old value of the INCLUDE environment variable is 
used in setting the new value. 
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The second "SET" command indicates to the Open Watcom Linker that libraries may be found in the 
indicated directories. 

Environment variables may be used also as dynamic variables that may communicate information between 
different parts of the makefile. An example of communication within a makefile is illustrated in the 
following example. 

# 

# internal makefile communication 

# 

.BEFORE 

set message=message text 1 
echo *$(%message)* 
set message= 
echo *$(%message)* 

.example : another_ target .SYMBOLIC 
echo *$(%message)* 

another_ target : .SYMBOLIC 

set message=message text 2 

The output of the previous makefile would be: 

(command output only) 

‘message text 1* 

★ ★ 

‘message text 2* 

Make handles the "SET" command so that it appears to work in an intuitive manner similar to the operating 
system shell's "SET" command. The "SET" command also may be used to allow commands to relay 
information to commands that are executed afterwards. 

The DOS "FOR" command is intercepted by Make. The reason for this is that DOS has a fixed limit for the 
size of a command thus making it unusable for large makefile applications. One such application that can 
be done easily with Make is the construction of a WLINK command file from a makefile. The idea behind 
the next example is to have one file that contains the list of object files. Anytime this file is changed, say, 
after a new module has been added, a new linker command file will be generated which in turn, will cause 
the linker to relink the executable. First we need the makefile to define the list of object files, this file is 
"OBJDEF.MIF" and it declares a macro "objs" which has as its value the list of object files in the 
application. The content of the "OBJDEF.MIF" file is: 

# 

# list of object files 

# 

objs = & 

window.obj & 
bios.obj & 
keyboard.obj & 
mouse.obj 

The main makefile ("MAKEFILE") is: 
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# 

# FOR command example 

# 

[include objdef.mif 

plot.exe : $ (objs) plot.Ink 
wlink @plot 

plot.Ink : objdef.mif 

echo NAME $ A & >$ A @ 
echo DEBUG all »$ A @ 

for %i in ($(objs)) do echo FILE %i >>$ A @ 

This makefile would produce a file "PLOT.LNK" automatically whenever the list of object files is changed 
(anytime "OBJDEF.MIF" is changed). For the above example, the file "PFOT.FNK" would contain: 

NAME plot 
DEBUG all 
FILE window.obj 
FILE bios.obj 
FILE keyboard.obj 
FILE mouse.obj 

The "rm" command is intercepted by Make. The reason for this is the need of being available on all 
supported platforms. The "rm" internal command is simplified implementation of the POSIX rm command. 
It supports following options. 

-f force deletion of read-only files, no diagnostics messages about missing items 

-r deletion of directories 

-v verbose operation 

Make supports nine internal commands: 


1. %abort 

2. %append 

3. %create 

4. %erase 

5. %make 

6. %null 

7. %quit 

8. %stop 

9. %write 


The %abort and %quit internal commands terminate execution of Make and return to the operating 
system shell: %abort sets a non-zero exit code; %quit sets a zero exit code. 

# 

# %abort and %quit example 

# 

done_ enough : 

%quit 

suicide : 

%abort 
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The %append, %create, %erase, and %write internal commands allow WMAKE to generate files 
under makefile control. This is useful for files that have contents that depend on makefile contents. 
Through the use of macros and the "for" command. Make becomes a very powerful tool in maintaining lists 
of files for other programs. 

The %append internal command appends a text line to the end of a file (which is created if absent) while 
the %write internal command creates or truncates a file and writes one line of text into it. Both 
commands have the same form, namely: 

%append <file> <text> 

%write <file> <text> 

where <f ile> is a file specification and <text> is arbitrary text. 

The %create internal command will create or truncate a file so that the file does not contain any text 
while the %erase internal command will delete a file. Both commands have the same form, namely: 

%create <file> 

%erase <file> 


where <file>isa file specification. 


Full macro processing is performed on these internal commands so the full power of WMAKE can be used. 
The following example illustrates a common use of these internal commands. 

# 

# %append, %create, %erase, and %write example 

# 

[include objdef.mif 

plot.exe : $ (objs) plot.Ink 
wlink @plot 


plot.Ink : objdef.mif 
%create $ A @ 

%append $ A @ NAME $ A & 

# Next line equivalent to previous 
%create $ A @ NAME $ A & 

%append $ A @ DEBUG all 

for %i in ($ (objs)) do %append $ A @ 


two lines. 


FILE %i 


clean : .SYMBOLIC 

%erase plot.Ink 


The above code demonstrates a valuable technique that can generate directive files for WLINK, WLIB, and 
other utilities. 


The %make internal command permits the updating of a specific target and has the form: 
%make <target> 

where <target> is a target in the makefile. 
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# 

# %make example 

# 

[include objdef.mif 

plot.exe : $ (objs) 

%make plot.Ink 
wlink @plot 

plot.Ink : objdef.mif 
%create $~@ 

%append $~@ NAME $''& 

%append $^@ DEBUG all 

for %i in ($(objs)) do %append $^@ FILE %i 

There seem to be other ways of doing the same thing. Among them is putting plot.lnk into the list of 
dependencies: 

# 

# %make counter-example 

# 

[include objdef.mif 

plot.exe : $ (objs) plot.lnk 
wlink @plot 

plot.lnk : objdef.mif 
%create $ A @ 

%append $ A @ NAME $ A & 

%append $^@ DEBUG all 

for %i in ($(objs)) do %append $ A @ FILE %i 
and using a make variable: 

# 

# %make counter-example 

# 

[include objdef.mif 
plot.exe : $(objs) 

wlink NAME $^& DEBUG all FILE { $(objs) } 

The %null internal command does absolutely nothing. It is useful because Make demands that a 
command list be present whenever a target is updated. 
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# 

# %null example 

# 

all : application! application2 .SYMBOLIC 
%null 

application! : appll.exe .SYMBOLIC 
%null 

application2 : appl2.exe .SYMBOLIC 
%null 

appll.exe : (dependents ...) 

(commands) 

appl2.exe : (dependents ...) 

(commands) 

Through the use of the %null internal command, multiple application makefiles may be produced that are 
quite readable and maintainable. 

The %stop internal command will temporarily suspend makefile processing and print out a message 
asking whether Makefile processing should continue. Make will wait for either the "y" key (indicating that 
the Makefile processing should continue) or the "n" key. If the "n" key is pressed, makefile processing will 
stop. The %stop internal command is very useful for debugging makefiles but it may be used also to 
develop interactive makefiles. 

# 

# %stop example 

# 

all : appll.exe .SYMBOLIC 
%null 

appll.exe : (dependents ...) 

@echo Are you feeling lucky? Punk! 

@%stop 
(commands) 

10.40 Compatibility Between Open Watcom Make and UNIX 
Make 


Open Watcom Make was originally based on the UNIX Make utility. The PC’s operating environment 
presents a base of users which may or may not be familiar with the UNIX operating system. Make is 
designed to be a PC product with some UNIX compatibility. The line continuation in UNIX Make is a 
backslash ( "\") at the end of the line. The backslash ( "\") is used by the operating system for directory 
specifications and as such will be confused with line continuation. For example, you could type: 

cd \ 

along with other commands ... and get unexpected results. However, if your makefile does not contain 
path separator characters ("\") and you wish to use "\" as a line continuation indicator then you can use the 
Make "u" (UNIX compatibility mode) option. 
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Also, in the UNIX operating system there is no concept of file extensions, only the concept of a file suffix. 
Make will accept the UNIX Make directive . SUFFIXES for compatibility with UNIX makefiles. The 
UNIX compatible special macros supported are: 

Macro Expansion 

$@ full name of the target 

$* target with the extension removed 

$< list of all dependents 

$? list of dependents that are younger than the target 

The extra checking of makefiles done by Make will require modifications to UNIX makefiles. The UNIX 
Make utility does not check for the existence of targets after the associated command list is executed so the 
"c" or the . NOCHECK directive should be used to disable this checking. The lack of a command list to 
update a target is ignored by the UNIX Make utility but Open Watcom Make requires the special internal 
command %null to specify a null command list. In summary. Make supports many of the features of the 
UNIX Make utility but is not 100% compatible. 

10.41 Open Watcom Make Diagnostic Messages 

This section lists the various warning and error messages that may be issued by the Open Watcom Make. 

In the messages below, %? character sequences indicate places in the message that are replaced with some 
other string. 

1 Out of memory 

2 Make execution terminated 

3 Option %c%c invalid 

4 %c%c must be followed by a filename 

5 No targets specified 

6 Ignoring first target in MAKEINIT 

7 Expecting a %M 

8 Invalid macro name %E 

9 Ignoring out of place %M 

10 Macros nested too deep 

11 Unknown internal command 

12 Program name is too long 

13 No control characters allowed in options 

14 Cannot execute %E: %Z 
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15 Syntax error in %s command 

16 Nested %s loops not allowed 

17 Token too long, maximum size is %d chars 

18 Unrecognized or out of place character ’%C’ 

19 Target %E already declared %M 

20 Command list does not belong to any target 

21 Extension(s) %E not defined 

22 No existing file matches %E 

23 Extensions reversed in implicit rule 

24 More than one command list found for %E 

25 Extension %E declared more than once 

26 Unknown preprocessor directive: %s 

27 Macro %E is undefined 

28 !If statements nested too deep 

29 !%s has no matching !if 

30 Skipping !%1 block after !%2 

31 %1 not allowed after !%2 

32 Opening file %E: %Z 

34 !%s pending at end of file 

35 Trying to !%s an undefined macro 

36 Illegal attempt to update special target %E 

37 Target %E is defined recursively 

38 %E does not exist and cannot be made from existing files 

39 Target %E not mentioned in any makefile 

40 Could not touch %E 

41 No %s commands for making %E 

42 Last command making (%L) returned a bad status 
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43 Deleting %E: %Z 

44 %s command returned a bad status 

45 Maximum string length exceeded 

46 Illegal character value %xH in file 

47 Assuming target(s) are . %s 

48 Maximum %%make depth exceeded 

49 Opening (%s) for write: %Z 

50 Unable to write: %Z 

51 CD ’ing to %E: %Z 

52 Changing to drive %C: 

53 DOS memory inconsistency detected! System may halt ... 

53 OS corruption detected 

54 While reading (%s): %Z 

59 !IF Parse Error 

60 TMP Path/File Too Long 

61 Unexpected End of File 

62 Only NO(KEEP) allowed here 

63 Non-matching " 

64 Invalid String Macro Substitution 

65 File Name Length Exceeded 

66 Redefinition of .DEFAULT Command List 

67 Non-matching {In Implicit Rule 

68 Invalid Implicit Rule Definition 

69 Path Too Long 

70 Cannot Load/Unload DLL %E 

71 Initialization of DLL %E returned a bad status 

72 DLL %E returned a bad status 
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73 Illegal Character %C in macro name 

74 in closing file %E 

75 in opening file %E 

76 in writing file %E 

77 User Break Encountered 

78 Error in Memory Tracking Encountered 

79 Makefile may be Microsoft try /ms switch 
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11.1 Introduction 


This chapter describes the Open Watcom Touch utility. Open Watcom Touch will set the time-stamp (i.e., 
the modification date and time) of one or more files. The new modification date and time may be the 
current date and time, the modification date and time of another file, or a date and time specified on the 
command line. This utility is normally used in conjunction with the Open Watcom Make utility. The 
rationale for bringing a file up-to-date without altering its contents is best understood by reading the 
chapter which describes the Make utility. 

The Open Watcom Touch command line syntax is: 


WTOUCH [options] file_spec [file_spec...] 


The square brackets [ ] denote items which are optional. 

options is a list of valid options, each preceded by a slash ("/") or a dash Options may be 

specified in any order. 

file_spec is the file specification for the file to be touched. Any number of file specifications may be 

listed. The wild card characters "*" and "?" may be used. 

The following is a description of the options available. 


c 

d <date> 

f<file> 

i 

q 

r 

t <time> 
u 


do not create an empty file if the specified file does not exist 

specify the date for the file time-stamp in "mm-dd-yy" format 

use the time-stamp from the specified file 

increment time-stamp before touching the file 

suppress informational messages 

touch file even if it is marked read-only 

specify the time for the file time-stamp in "hh:mm:ss" format 

use USA date/time format regardless of country 

display help screen 


11.2 WTOUCH Operation 

WTOUCH is used to set the time-stamp (i.e., the modification date and time) of a file. The contents of the 
file are not affected by this operation. If the specified file does not exist, it will be created as an empty file. 
This behaviour may be altered with the "c" option so that if the file is not present, a new empty file will not 
be created. 
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Example: 

(will not create myfile.dat) 

Owtouch /c myfile.dat 

If a wild card file specification is used and no files match the pattern, no files will have their time-stamps 
altered. The date and time that all the specified files are set to is determined as follows: 

1. The current date and time is used as a default value. 

2. A time-stamp from an "age file" may replace the current date and time. The "f" option is used to 
specify the file that will supply the time-stamp. 

Example: 

(use the date and time from file "last.tim") 

Owtouch /f last.tim file*.dat 

3. The date and/or time may be specified from the command line to override a part of the 
time-stamp that will be used. The "d" and "t" options are used to override the date and time 
respectively. 

Example: 

(use current date but use different time) 

Owtouch /t 2:00p file*.dat 
(completely specify date and time) 

Owtouch /d 10-31-90 /t 8:00:00 file*.dat 
(use date from file "last.tim" but set time) 

Owtouch /f last.tim /t 12:00 file*.dat 

The format of the date and time on the command line depends on the country information 
provided by the host operating system. Open Watcom Touch should accept dates and times in a 
similar format to any operating system utilities (i.e., the DATE and TIME utilities provided by 
DOS). The "a" and "p" suffix is an extension to the time syntax for specifying whether the time 
is A.M. or P.M., but this is only available if the operating system is not configured for military 
or 24-hour time. 
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12 The IDE2MAKE Utility 

12.1 Introduction 


This chapter describes the IDE2MAKE utility. 1DE2MAKE loads an IDE project file and, using the 
associated .tgt files, generates make files that can be invoked with WMAKE. If the .wpj file does not exist, 
a default project is used. If any tgtfile(s) are specified, they are used as the targets in creating the make 
files. 

The IDE2MAKE command line syntax is: 


ide2make [options] [tgtfile] 


The square brackets [ ] denote items which are optional. At least one item must be specified, otherwise the 
program usage is shown. 

options is a list of valid options, each preceded by a slash ("/") or a dash Options may be 

specified in any order. 

tgtfile is the file specification for the targetfile to be used. Any number of file specifications may 

be listed. 


The following is a description of the options available. 


P <wpjfile> 
c <cfgfile> 
i 


d 

l 


r 

li <number> 


loads wpjfile.wpj (project.wpj by default) 

loads cfgfile instead of ide.cfg 

directory to search configuration files 

generate makefiles using development switch set 

generate makefiles with long lines (no length limit) 

generate makefiles using release switch set 

generate makefiles for selected host OS (default is current host) 

0 - Windows 3.x 

1 - OS/2 PM 

2 - Windows NT 

3 - Win-OS/2 

4 - Windows 95 

5 - Japanese Windows 3.x on an IBM 

6 - Japanese Windows 3.x on a Nec98 

7 - Dec Alpha (Windows NT) 

8 - DOS 

9 - Linux 
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12.2 IDE2MAKE Operation 

IDE2MAKE is used to create makefiles from IDE project and targetfiles. If no targetfile is specified, 
makefiles for all targets are generated. 
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Preface 


The Open Watcom Vi Editor is a programmer’s editor. It is loosely based on UNIX Vi, but is much more 
powerful. This manual may be used by someone without any knowledge of Vi, or by experienced Vi users. 
People familiar with Vi will find Open Watcom Vi Editor is very similar in its basic behaviour, but with 
many additional features. 
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Chapter 7 
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Chapter 9 
Chapter 10 


Introduction provides an overview of Vi. 

Basic Usage is for the novice Vi user. This section provides an overview of the basic 
features of Vi through some simple exercises. 

Intermediate Usage provides some more exercises which introduce additional useful 
features of Vi. 

Advanced Usage This chapter discusses the advanced features of Vi. 

Command Mode Keys This chapter describes the keystrokes that initiate the many different 
features of command mode. 

Editor Command Line This chapter describes all the different commands that may be issued 
in Vi. 

Editor Settings This chapter shows all the different settings that are used for configuring Vi. 

Windowing, Menus and the Mouse This chapter provides a guide for using and configuring 
the user interface of Vi to suit your needs. 

Editor Script Reference This chapter describes Vi’s script language. 

Regular Expressions This chapter describes how to use regular expressions in Vi when 
executing search, search and replace, and global commands. 
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11ntroduction to the Open Watcom Vi Editor 


Open Watcom Vi Editor (Vi) is a programmer’s editor. It is loosely based on UNIX Vi, but is much more 
powerful. This manual may be used by someone without any knowledge of Vi, or by an experienced Vi 
user. People familiar with Vi will find the Open Watcom Vi Editor is very similar in its basic behaviour. 

An editor is very personal thing. Every person uses an editor in a different way, or wants things to look 
slightly different. Vi was designed with this in mind. Most features in Vi are configurable. 

Vi has many powerful features. Some of the more significant are: 

• fully configurable 

• The size of every window can be set by the user 

• The color of every window can be set by the user 

• A window’s border can be set by the user 

• The menu bar may be enabled/disabled 

• The menu items in each menu can be set by the user 

• Keys can be changed and augmented to suit any configuration 

• unlimited undo and redo capability 

• unlimited file size 

• unlimited number of lines in a file 

• edit up to 250 files at the same time 

• multiple views on the same file 

• full mouse support 

• powerful script language 

• local and global variables 

• structured constructs (loop, while, if/elseif/else ) 

• arbitrary conditional expressions 

• file I/O 

• batch edit processing 

• regular expression search and replacement 

• text marks 

• keystroke macros 

• block delete, copy, change, case toggle, and shift operations 
Open Watcom Vi Editor is available for the following environments: 

• DOS (real mode) (286 or higher) 

• DOS (protected mode, 386 or higher processors) 

•OS/2 1.x 

• OS/2 2.x 

• Windows NT 

• QNX 

• Windows 3.x GUI 

• Windows NT GUI 

• Linux (multiple CPU architectures) 
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1.1 Terms and Notation 

1.1.1 The Mouse 

If you have a mouse, you may use it with Vi. When you move your mouse, you will see a large block 
move around on your screen. This is called the mouse cursor. 

These terms are used when referring to things that may be done with the mouse. 

click Pressing a mouse button once. 

double click Pressing a mouse button twice in rapid succession. 

dragging Holding down a mouse button and then moving the mouse. 

1.1.2 The Screen 


When you start up Vi, you will see something like the following: 



Figure 1 . Vi after start-up 

The Vi screen has several windows. 


• The top line of the screen is the menu bar which contains all of the menu choices, the current mode, 
and the current time. 

• The large window below the menu bar is the edit window. Since Vi is a multiple file editor, you 
may have more than one edit window. Other edit windows are usually covered by the current edit 
window, unless you change the size and position of the edit windows. 

• The lower left corner of the screen contains the status window. This window typically shows the 
current row and column. 

• The majority of the bottom of the screen contains the message window. This window displays all 
errors and informational messages. 
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In the edit window will be a flashing line. This flashing line is the cursor, and it indicates which line you 
are on and the position within the line. 

On the border of the edit window are a number of special symbols. These special symbols are referred to as 

gadgets 

• In the top left corner of the edit window is the gadget (”) that opens up the menu for the window. 

• In the lower right corner of the edit window is the resize gadget (”). When you click on this gadget 
with your mouse and then drag the mouse, you can resize the edit window. 

• On the right hand side of the edit window is the scroll bar. The scroll bar has several components: 

• The scroll up (”) gadget. When you click on this with your mouse, the edit window scrolls up one 
line. 

• The scroll down (”) gadget. When you click on this with your mouse, the edit window scrolls 
down one line. 

• The scroll thumb (”). The scroll thumb indicates the relative position of the current line in the file. 
When you click on the scroll thumb with your mouse and drag it, you can move to a new position in 
the file. If you click with your mouse on the scroll bar above the scroll thumb, you move one page 
up in the file. If you click on the scroll bar below the scroll thumb, you move one page down in the 
file. 
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6 Terms and Notation 




2 Basic Usage 


Using any editor as powerful as Vi takes some practice. This chapter will lead you through the basics or 
using Vi 

2.1 Starting the Open Watcom Vi Editor 

Vi is invoked by typing the command 
vi 

at the command prompt. Try typing this. You will see something similar to the following: 



Figure 2. The Vi screen 

If you are running DOS on a 386 (or higher) machine, then you can also use the protected mode version of 
Vi. This version of Vi runs as a native 386 application, which means that it has access to more memory and 
will do its processing more quickly. You can start this version by typing 

vip 

at the command prompt. 

Vi also accepts one or more files as an optional parameter. Each file that you specify will be edited by Vi. 
For example, typing 

vi test.c 

will edit the file test. c. Typing 
vi test.c other.c 

will edit the files test. c and other . c. Typing 
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vi * . c 

will edit all files that have the extension . c. 

To exit Vi, use your mouse to select the File menu, and pick the Exit item. If you do not have a mouse, 
press ALT_F (hold down the ALT key and press the letter F) and use the down arrow key to highlight the 
Exit item. Pressing the ENTER key selects the Exit item. 


2.2 What is a Modal Editor? 


A modal editor is one where keystrokes have different meaning, depending on what mode you are in. Vi 
has two main modes, command mode and text insertion mode. 

While in command mode, pressing a key on your keyboard can cause something different to happen. For 
example, pressing the letter D (capital ’d') deletes all characters from the current cursor position to the end 
of the line. If the same letter ’D’ (is pressed while in text insertion mode, the letter 'D’ appears in your text 
(much as you would expect). 

It is easy to tell what mode you are in while using Vi. When you are in command mode, the cursor is a thin 
line. When you are in text insertion mode, the cursor is much thicker: if you are inserting text, the cursor 
is one half of a full block, and if you are overstriking text, the cursor is a full block. 

The mode indicator on the menu bar at the top of your screen shows the current mode. While in command 
mode, you will see the following: 

Mode: command 

While in text insertion mode, you will see either: 

Mode: insert 


or 


Mode: overstrike 

depending on whether you are inserting or overstriking text. 

Vi is in command mode by default. There are numerous ways to enter text insertion mode, the easiest of 
which is to press the Insert key on your keyboard. 

The ESC key is one of the more important keys in Vi. Pressing ESC once will stop whatever you are 
doing and return you to command mode. If you have started a command mode sequence, pressing ESC 
will cancel the command and return you to command mode. 

Exercises 

Start up Vi by typing 
vi 

at your command prompt. 
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Basic Usage 


You will see a screen that looks like the following: 



Figure 3. The Vi screen 


Press the insert ( INS ) key. The cursor will get larger and you will see the mode indicator change from 


Mode: command 


to 


Mode: insert 

Try typing some characters. Notice that they appear in the edit window as you type. When you are done, 
press the ESC key. The cursor will get smaller and you will see the mode indicator change from 

Mode: insert 


to 


Mode: command 

To exit Vi, use your mouse to select the File menu, and pick the Exit item. If you do not have a mouse, 
press ALT_F (hold down the ALT key and press the letter F) and use the down arrow key to highlight the 
Exit item. Pressing the ENTER key selects the Exit item. 

Once you exit, you will be prompted with a message as follows: 
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Figure 4. The Really Exit prompt 

there are still files that have been modified but not saved. Press ’n’ then the ENTER key to exit without 
saving your current file. 


2.3 Some Basic Commands 


To begin editing with Vi, there are only a few basic commands that you need to learn. Once you master 
these few commands, you will be able to accomplish all basic editing tasks. In later chapters, more 
sophisticated commands will be introduced which allow advanced tasks to be completed more quickly. 

2.3.1 Moving Around 

When you are in command mode, you may move around in your text using various cursor keys. The basic 
keys that you use to move around are: 

UP (up arrow key) 

Cursor up through the text. 

DOWN (down arrow key) 

Cursor down through the text. 

LEFT (left arrow key) 

Cursor left through the text. 

RIGHT (right arrow key) 

Cursor right through the text. 

HOME Move to the start of the current line. 

END Move to the end of the current line. 

PAGEUP Move up one page in the text. 

PAGEDOWN Move down one page in the text. 
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Basic Usage 


CTRL_PAGEUP (Ctrl key + Page Up key) 

Move to the first character on the first line in the file. 

CTRL_PAGEDOWN (Ctrl key + Page Down key) 

Move to the last character on the last line in the file. 

These same cursor keys may also be used when entering text in text insertion mode. 


2.3.2 Saving and Exiting a File 

Once you have modified a file, may want to save it and either edit other files or exit the editor. When you 
exit a modified file, you may want to either discard your changes or keep them. 

You can discard ALL of your files by selecting the Exit item in the File menu. Alternatively, you can 
discard or save the changes on an individual file basis. 

If you wish to save the current file you are editing and leave that particular edit session, the fastest way to 
do it is to use the command ’ZZ\ Press ESC to make sure that you are in command mode, and then type 
two capital z’s (’ZZ’) in a row. This saves the file, then exits the edit buffer for the file. If you are editing 
any other files, the next one in the list will become the current one. If you are not editing any other files, 
then Vi will exit. 


You may use certain menu items to save or discard changes to your file. The main menu option File (by 
clicking on it with the mouse or by pressing ALT_F) has options for saving the current file. As well, each 
edit window has a menu associated with it that you can access by pressing ALT_G. You can also access 
this menu by clicking on the gadget (”) in the top left hand corner of an edit window. This menu has a 
number of choices for dealing with the file. 


If you activate the File menu item, either with the mouse or by pressing ALT_F, a menu will be displayed 
as follows: 



Figure 5. The File Menu 


If you select the Save current file item, Vi will save the current file you are editing. You will remain 
editing the current file. 
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If you select the Save current file and close item, Vi will save the current file you are editing, and close 
the edit window. If you are editing any other files, the next one in the list will become the current one. If 
you are not editing any other files, then Vi will exit. 

If you activate the individual file menu either by clicking on the gadget at the top-left corner of the edit 
window with the mouse or by pressing ALT_G, then a menu will pop up as follows: 



Figure 6. The Individual Edit Window menu 

If you select the Save current file item, Vi will save the current file you are editing. You will remain 
editing the current file. 

If you select the Save & close item, Vi will save the current file you are editing, and exit that edit buffer. If 
you are editing any other files, the next one in the list will become the current one. If you are not editing 
any other files, then Vi will exit. 

If you select the Close no save item, Vi will discard the current file without saving your modifications. If 
you are editing any other files, the next one in the list will become the current one. If you are not editing 
any other files, then Vi will exit. 

If you select the Close item, Vi will try to discard the current file. However, if the file has been modified, 
then the option will fail. 

2.3.3 Inputting Text 

You have already learned that pressing the INS key while in command mode puts Vi into insert mode. 

Once you are in insert mode, you may enter whatever text you like. You may cursor around and modify 
your text in whatever way you choose. Once you are done, you may press the ESC key to return to 
command mode. 

While you are in text insertion mode, the basic keys that allow you to move through the text are: 

UP (up arrow key) 

Cursor up through the text. 

DOWN (down arrow key) 

Cursor down through the text. 
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LEFT (left arrow key) 

Cursor left through the text. 

RIGHT (right arrow key) 

Cursor right through the text. 

HOME Move to the start of the current line. 

END Move to the end of the current line. 

PAGEUP Move up one page in the text. 

PAGEDOWN Move down one page in the text. 

CTRL_PAGEUP (Ctrl key + Page Up key) 

Move to the first character on the first line in the file. 

CTRL_PAGEDOWN (Ctrl key + Page Down key) 

Move to the last character on the last line in the file. 

These keys allow you to manipulate the text while in text insertion mode: 

CTRL_DEL (Control-Delete) 

Deletes the current line. 

BS (Backspace key) 

Deletes the character before the cursor, moving the cursor and the rest of the line to the left 
one character. 

DEL (Delete key) 

Delete the character under the cursor. If you are at the end of the line, DEL has the same 
effect as pressing BS. 

ENTER Start a new line. 

INS Toggles between inserting and overstriking text. 

Along with the INS key, there are a number of other keys that you can press in command mode that will 
place you in text insertion mode, where you can edit text. The difference between all of these commands is 
where the cursor moves to before you start inputting text. The basic set of keys is: 

a Starts appending (inserting) text after the current character. 

A Starts appending (inserting) text after the last character on the current line. 

i Starts inserting text at the current cursor position. This is the same as pressing the INS key. 

I Starts inserting text before the first non-white space character on the current line. 

o Adds a blank line after the current line, and starts you inserting text on the new line. 

O Adds a blank line before the current line, and starts you inserting text on the new line. 

R Starts overstriking text at the current cursor position. 

INS Start inserting text at the current cursor position. 

Remember, while in text insertion mode, the following mode indicator will appear on the menu bar: 

Mode: insert 
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or 


Mode: overstrike 

depending on whether you are inserting or overstriking text. As well, the cursor will change to a larger 
block cursor to help you remember that you are are inputting text. 

To exit text insertion mode at any time, press the ESC key. Your mode indicator will switch to 
Mode: command 

Exercises 

1. Edit a new file (called "test", for example) as follows: 
vi test 

You will see the following screen: 



Figure 7. Editing the New File "test" 


Note the message window (the bottom two lines of the screen) contains the message 

"test" [new file] line 1 of 1 — 100% — 

This message indicates that you are editing a new file called test, that you are on line 1 of a 1 line 
file, and that line 1 is 100% of the way into the file. 

You may see that message any time by pressing CTRL_G (hold down the Ctrl key and press the 
g key). 

Enter text insertion mode by pressing the INS key, and type the following lines: 

This is a test line. 

This is another test line. 

When you are done typing these lines, remember to press the ESC key to return to command 
mode. 
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Press CTRL_G (hold down Ctrl and press the g key). The message window (the bottom two 
lines of the screen) will show the message: 

"test" [modified] line 2 of 2 — 100% — 

Now, press two capital z’s in a row (’ZZ’). This will save the file and return to the operating 
system command prompt. 

2. Edit the file you created in the previous example, by typing 
vi test 

You will see the following screen: 



Note the message window (the bottom two lines of the screen) contains the message 

"test" line 1 of 2 — 50% — 

This message is different than when you edited "test" for the first time. The "[new file]" 
indicator is gone, since you have edited an existing file. This message indicates to you that you 
are now editing a file called test, that you are on line 1 of a 2 line file, and that line 1 is 50% of 
the way into the file. 

Now try to experiment with the different ways of entering insert mode. 

1. Try pressing the ’A’(capital ’a’) key. This will move your cursor to the end of the 
line, and will put you into insert mode. Try adding some text to this line, and press 
the ESC key when you are done. 

2. Try pressing the T key. This will move your cursor to the start of the line, and will 
put you into insert mode. Try adding some text to this line, and press the ESC key 
when you are done. 

3. Try pressing the ’R’ key. This will start you in overstrike mode. Note that the you 
have a very large cursor and that the mode indicator says: 

Mode: overstrike 
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Try typing some characters. As you type, what was there already is replaced by what 
you type. Press the ESC key when you are done. 

4. Try pressing the T key. This is the same as pressing the INS key. Now type some 
text, then press the INS key. Note that your cursor turned to full height from half 
height, and the mode indicator changed from: 

Mode: insert 

to 

Mode: overstrike 

Now, when you type, you will replace the existing characters. Try pressing the INS 
key again. This time, your cursor will turn from full height to half height, and the 
mode indicator will change from: 

Mode: overstrike 

to 

Mode: insert 

Remember to press the ESC key when you are done. 

5. Try pressing the ’a’ key. This will move the cursor over one character, and put you in 
insert mode. Try cursoring around inside your text using the arrow keys. Use the 
END key to move to the end of a line, and the HOME key to move to the start of a 
line. Press the ESC key when you are done. 

You have now made a number of significant modifications to your file. To discard the file 
without saving your changes, activate the individual file menu (at the top-left corner of the edit 
window) either by clicking on the gadget with the mouse or by pressing ALT_G. When the 
menu is up, try selecting the Close item. You will get the message: 

File modified - use :q! to force 

The command ":q!" being referred to will be discussed later. The file can be exited without 
saving by using the Close no save menu item. Activate the individual file menu again, and 
select this item. This will discard your changes to the file, and since you are not editing any 
other files, you are returned to the operating system command prompt. 

2.4 Cutting and Pasting Text 

So far, you have learned how to edit a file, input some text, and save or cancel your changes. Now you will 
learn some simple ways of deleting text and moving it elsewhere. 
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2.4.1 Lines 

The section "Inputting Text" on page 12 noted that pressing CTRL_DEL (control-delete) deleted a line 
when inputting text. This same command can be used while in command mode. 

If you want to delete more than one line at once, you may precede this delete command with a repeat 
count. You enter a repeat count simply by typing numbers before you press CTRL_DEL. As you type a 
number in command mode, it will appear in a special window, as follows: 



Figure 9. Repeat Count Display 


The number that you are typing is displayed in the repeat count window. As with all command mode 
commands, if you decide that you have made a mistake, just press the ESC key and the count you have 
been typing will be cancelled. 

So, if you type a repeat count of 5 and then press CTRL_DEL, five lines will be deleted. If you do not 
type a repeat count, then one line will be deleted. 

You can also delete a line by pressing the'd' key twice in a row (’dd’). This has the exact same effect as 
pressing the CTRL_DEL key. You may precede this command by a repeat count as well. For example, 
typing 

12dd 

deletes the next 12 lines in your file. 

Once you have deleted some lines, you might want to paste them back in. If you press SHIFTINS (shift 
insert), the line(s) you deleted will be pasted in after the current line. If you press CTRL INS (control 
insert), the line(s) you deleted will be pasted in before the current line (which reverses the action of 

CTRL_DEL). 

There are two other keys for pasting, the letters ’p’ and ’P’ (small p and capital p). Small ’p’ pastes the 
line(s) you deleted after the current line, just like SHIFT INS. Capital p (’P’) pastes the line(s) you 
deleted before the current line, just like CTRLJNS. 

If you do not wish to delete some lines, but you do wish to copy them so you can paste them somewhere 
else, then you may use the "yank" command. If you press the letter ’Y’, or type the letters ’yy’, you will 
"yank" (make a copy of) the current line. Just like ’dd' or CTRL_DEL, you can precede these commands 
with a repeat count. For example, typing 
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6Y 


or 


6yy 

will copy 6 lines in your file. 

Once you have yanked the lines, you may paste them in, as discussed above. 

2.4.2 Characters 

To delete characters while in command mode, you can press the DEL key or the ’x’ key. The current 
character under the cursor will be deleted. You may type a repeat count before you type DEL or ’x’, and 
that will delete a number of characters. For example, typing 3x when the cursor is on ’T’ in the line 

Delete Test. 

will leave you with 

Delete t. 

and the cursor will be on the’t’ just before the period. 

If you wish to delete the character before the cursor, you may press the letter ’X’ (capital x). This will 
delete the character before the cursor, and move the cursor back one (i.e. the cursor stays on the character 
that it was on before you pressed the ’X’). You may use a repeat count with this command. For example, 
typing 3X when the cursor is on ’T’ in the line 

Delete Test. 

will leave you with 

DeleTest. 

and the cursor will still be on the 'T'. 

Once you have deleted some characters, you might want to paste them back in. The keys involved are the 
exact same keys for pasting lines. The difference is that when you paste characters, the characters are 
pasted into the current line, whereas when you paste lines, the lines are pasted above or below the current 
line. 

If you press SHIFT_INS (shift insert), the character(s) you deleted will be pasted in after the current cursor 
position on the current line. If you press CTRL INS (control insert), the character(s) you deleted will be 
pasted in before the current cursor position on the current line. 

There are two other keys for pasting, the letters p and P (small p and capital p). Small p pastes the 
character(s) you deleted after the current cursor position on the current line, just like SHIFT INS. Capital 
p CP’) pastes the character(s) you deleted before the cursor position on the current line, just like 

CTRL_INS. 

Exercises 
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Edit the file "test" created in the previous examples by typing: 
vi test 

You should see the lines: 

This is a test line. 

This is another test line. 

The following examples are meant to be tried in sequence. Each example builds on the previous one. 

1. Copy the first line by pressing the ’Y’ (capital ’y’) while the cursor is on the first line. 

2. Now press the ’p’ key to paste the line after the current line. You should see the lines: 

This is a test line. 

This is a test line. 

This is another test line. 

3. Now, go to the second line and yank 2 lines, by pressing the number ’2’ followed by the letters 

’yy’- 

4. Cursor up to the top line, and press the capital p CP’) key to paste the lines above the current 
line. You will see: 

This is a test line. 

This is another test line. 

This is a test line. 

This is a test line. 

This is another test line. 

5. Now, move to the top line in the file and delete the first 3 lines by press the number ’3’ followed 
by the letters ’dd’. You will now have the following lines: 

This is a test line. 

This is another test line. 

6. Delete the first line by pressing CTRL_DEL or by typing ’dd’. You will be left with a single 
line: 

This is another test line. 

7. Paste the line you deleted back in. If you press the letter ’p’ or SHIFT INS, the line you deleted 
will appear after the first line: 

This is another test line. 

This is a test line. 

8. Paste the line above the current line by pressing capital p CP') or CTRL INS. 

This is a test line. 

This is another test line. 

This is a test line. 

9. Delete all 3 lines of text. Make sure your cursor is on the first line in the file, and type 3dd. 

This will delete all three lines, and you will have an empty edit buffer. 
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10. Paste the lines back in by typing ’p’. The three lines will be pasted in: 


This 

is 

a test 

line. 

This 

is 

another 

test line 

This 

is 

a test 

line. 


11. Go to the first line in the file, and to the first column (try pressing CTRL_PAGEUP ). Then 
press the ’x’ key. The first line should become: 

his is a test line. 

Your cursor should be on the letter 'h’ in column 1. 

12. Type the letter 'p\ The ’T’ that you deleted will appear after the ’h' in column 1: 

hTis is a test line. 

13. Type capital p f P'). The ’T’ that you deleted will appear before the T and after the ’T’ you just 
pasted in. 

hTTis is a test line. 

14. Cursor to the first column and type 6x. This will delete the first word and the space: 

is a test line. 

15. Move the cursor over to the’t’ in ’test’. Press capital x (’X’), and you will see: 

is atest line. 

The cursor will remain on the ’t’. 

16. Type 3X. You will now see 

itest line. 

and the cursor will still be on the ’t’. 

You have now made a number of significant modifications to your file. To discard the file without saving 
your changes, activate the individual file menu (at the top-left corner of the edit window) either by clicking 
on the gadget with the mouse or by pressing ALT_G. When the menu is up, try selecting the Close item. 
You will get the message: 

File modified - use :q! to force 

The command ":q!" being referred to will be discussed later. The file can be exited without saving by using 
the Close no save menu item. Activate the individual file menu again, and select this item. This will 
discard your changes to the file, and since you are not editing any other files, you are returned to the 
operating system command prompt. 
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2.5 Using the Menus 

Vi comes with a default set of menus that have the following items 

File Edit Position Window Options Help 

The first letter of each word is highlighted, indicating that that key is the hot key to activate the menu. 

To use a hot key, hold down the ALT key and press the highlighted key. This will display the menu. 

There is also a menu associated with each edit window. You can activate this window by pressing ALT_G 
or by clicking on the gadget in the upper left hand corner of the edit window. 

You may activate a menu on the menu bar by pressing the appropriate hot key or by clicking on the word 
with the mouse. When you press down with the left mouse button, the menu is activated. If you keep the 
button down and move the mouse from right to left across the menu bar, the other menus will activate as 
the mouse cursor sweeps across the word. 

Once a menu is activated, a selection list appears. An item in the selection list may be chosen by doing one 
of the following: 

1. Cursoring up or down to the item and pressing the ENTER key. 

2. Typing the hot key for the menu item. 

3. Clicking on an item with the mouse. 

4. Dragging the mouse and releasing the mouse button on an item. 

Once a menu is activated, it may be cancelled by pressing the ESC key, or by clicking the mouse 
somewhere outside the menu. If you press the cursor right key, the menu to the right of the menu currently 
selected will activate. If you press the cursor left key, the menu to the left of the menu currently selected 
will activate. 

The following sections describe each of the menus, and how each menu item is used. 

2.5.1 Edit Window Menu 

This menu is selected by pressing ALT_G or by clicking on the gadget in the upper left hand comer of an 
edit window with the mouse. Once you have done one of these, the following menu appears: 
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Figure 10. The Individual Edit Window menu 


Maximize Causes the window to become as large as possible. 

Minimize Causes the window to become as small as possible. 


Open another view 

Creates a separate window that is editing the same copy of the current file. This is useful if 
you wish to be able to look at one part of a file while editing another part 

Save Saves the current file. You remain editing the current file. 

Save and close Saves the current file and closes the window. 

Close no save Closes the window, discarding the current file and any changes you may have made. 

Close Closes the window. If the file has been modified, then the close will fail. 


2.5.2 Window Menu 

This menu is selected by pressing ALT_W or by clicking on word Window on the menu bar with the 
mouse. Once you have done one of these, the following menu appears: 


22 


Using the Menus 






Basic Usage 


File Edit Position Window Options Hel 

=--ane 

Tile windows 

~ Cascade windows 

~ Reset windows 



1 "no_nane" [new file] line 1 of 1 — 1 QQx — 


Figure 11. The Window menu 


Tile windows Tile all edit windows in a grid pattern, so that each window is displayed without 
overlapping any other. 

Cascade windows 

Causes all edit windows to cascade (overlap each other with the top border of each visible). 

Reset windows Resets all edit buffer windows to be full size (the same as maximizing each window 
individually). 


2.5.3 Options Menu 


This menu is selected by pressing ALT_0 or by clicking on word Options on the menu bar with the 
mouse. Once you have done one of these, the following menu appears: 



Settings 


This brings up a list of all settings for Vi. For more information on settings, see the chapter 
"Editor Settings" on page 147. 
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2.5.4 File Menu 

This menu is selected by pressing ALT_F or by clicking on the word File in the menu bar with the mouse. 
Once you have done one of these, the following menu appears: 



Figure 13. The File menu 


Open new file Displays a list of all files and directories in the current directory, along with all drives that 
are available. If you pick a file, you will edit that file. If you pick a directory, Vi will 
display all the files in that directory. If you pick a drive, Vi will display all files in the 
current directory on that drive. 

Next file Flip to the next file in the list of files that you are editing. 

Read file Displays a list of all files and directories in the current directory, along with all drives that 

are available. If you pick a file, that file will be read into the current edit buffer, after the 
current line. If you pick a directory, Vi will display all the files in that directory. If you 
pick a drive, Vi will display all files in the current directory on that drive. 

File list When selected, a list of all files that you are editing is displayed. Any modified files have 

an asterisk (’*’) before their name. By picking a file from this list, you move to that file. 


Save current file 

Vi will save the current file you are editing. You will remain editing the current file. 

Save current file and close 

Vi will save the current file you are editing, and close the edit window. If you are editing 
any other files, the next one in the list will become the current one. If you are not editing 
any other files, then Vi will exit. 


Enter command 

Allows you to enter a command line command. The command line is discussed in the next 
chapter, "Intermediate Usage" on page 29. 

System Starts an operating system command shell. You exit the command shell by typing ’exit’. 

Exit Exits all edit sessions, as long as no files have been modified. 


24 


Using the Menus 






Basic Usage 


2.5.5 Edit Menu 


This menu is selected by pressing ALT_E or by clicking on word Edit on the menu bar with the mouse. 
Once you have done one of these, the following menu appears: 



Figure 14. The Edit menu 

Delete region Deletes the selected (highlighted) region. 


Copy (yank) region 

Makes a copy of the selected (highlighted) region. 

Paste (put) Pastes the last deleted or copied text into the current edit buffer. The text is pasted after the 
current position in the file. 

Insert text Causes Vi to enter insert mode at the current cursor position. 

Overstrike text Causes Vi to enter overstrike mode at the current cursor position. 

Undo Undoes the last change that you made to the current edit buffer. If you keep selecting this 

item, you will undo more and more of your changes. If you select this item enough times, 
your file will be restored to the state when it was first opened or created. 

Redo Redoes the last undo that you did in the current edit buffer. If you keep selecting this item, 

you will redo more and more of your undos. If you select this item enough times, your file 
will return to the state when you made your last change. 


2.5.6 Position Menu 

This menu is selected by pressing ALT_P or by clicking on word Position on the menu bar with the 
mouse. Once you have done one of these, the following menu appears: 


Using the Menus 25 







The Open Watcom Vi Editor User’s Guide 



Figure 15. The Position menu 


Start of file 
End of file 
Line number 
Start of line 
End of line 


Moves to the start of the current edit buffer. 

Moves to the end of the current edit buffer. 

Prompts for a specific line number. Once you enter the number, you are placed at that line. 
Moves to the start of the current line. 

Moves to the end of the current line. 


Search forwards 

Prompts for some search text. Once you type some text and press ENTER, Vi searches 
forwards through the current edit buffer for the text. If the text is found, it is highlighted 
and the cursor is placed on the first character of the text. 

Search backwards 

Prompts for some search text. Once you type some text and press ENTER, Vi searches 
backwards through the current edit buffer for the text. If the text is found, it is highlighted 
and the cursor is placed on the first character of the text. 

Last search Repeats the last search that you typed, in the same direction as the initial search request. 

Reverse last search 

Repeats the last search that you typed, but the searches occurs in the opposite direction of 
the initial search request. 


2.5.7 Help Menu 

This menu is selected by pressing ALT_H or by clicking on word Help on the menu bar with the mouse. 
Once you have done one of these, the following menu appears: 
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Figure 16. The Help menu 


Command line Gives help on all command line commands. 

Keystrokes Gives help on command mode and text insertion mode 
Regular expressions 

Gives help on the search and replace abilities of Vi’s regular expressions. 
Scripts Gives help on Vi’s script language. 

Starting up Gives help on the various command line parameters for Vi. 
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3 Intermediate Usage 


This chapter discusses a number of the commonly used features of the Open Watcom Vi Editor. The 
knowledge of the information in the chapter "Basic Usage" is assumed. 


3.1 The Command Line 


The Open Watcom Vi Editor has a powerful set of commands that are entered in a special command 
window. These commands are referred to as command line commands. You can activate the command 
window in two ways: 

1. Select the Enter command item under the File menu. 

2. Press the colon key when in command mode. Remember to press the ESC key to ensure 
that you are in command mode before pressing 


Once you have done one of the previous things, the following window will appear on your screen: 



Figure 1 7. The Command Entry window 


You may enter a command in this window (for example: quit). If you wish to cancel the command that 
you are typing, just press the ESC key and the window will disappear. 


You may cursor back and forth in the command window, and use the backspace and delete keys to change 
mistakes. Once you press ENTER, the command will be processed. 


If you cursor up, you will go through a list of commands that you have entered at the command window 
(newest to oldest). This is your command history. Cursoring down will take you through the history from 
oldest to newest. This is very useful if you have typed a complicated command and did not get it quite 
right or if you just wish to execute the command again. 


The chapter "Editor Commands" on page 101 describes the command line in more detail. 
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3.1.1 Line Numbers 

Some command line commands accept a line address or a line range as a parameter. For example, when 
specifying the write command, you may specify 

:write 

or you may specify 
:1,10 write 

A line address is a number or a sum of numbers. As well, some special symbols may be used: 

. (dot) Represents the current line number. 

$ (dollar) Represents the last line number. 

’a (front quote) Indicates the line with the mark ’a’ set; marks ’a’ through ’z’ may be used. Marks are 
discussed later in this chapter. 

A line range is two line addresses separated by a comma. 

Some examples of line addresses and line ranges are: 

.+5 - five lines past the current line. 

'a - the line with mark a. 

$ - the last line 

1,5 - lines 1 to 5 

. ,$ - current line in file to end line of file 

.-3,100 - the line 3 before the current to line 100 

Line addresses are discussed in greater detail in the section "Line Addresses" on page 103. 

If you just enter a line address on its own on the command line, then you will go directly to that line. 

Exercises 

1. Start up Vi, and try selecting the File menu, and then selecting the Enter command item. 
Notice how the window pops up. Try typing and cursoring around. When you are done, press 
the ESC key to cancel the command. 

2. Make sure that you are in command mode, then press the colon (’:’) key. Once again, the 
command window pops up. Try typing and cursoring around. When you are done, press the 
ESC key to cancel the command. 

3. Add 10 lines to your file. Then press the colon (’:’) key and enter the number 5. You will go to 
line 5. Try entering different numbers and see what happens. If you enter a line number that 
does not exist, you will see the message: 
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No such line 

4. Now that you have a number of commands entered, try cursoring up and down in the command 
window. You will see all the commands that you have typed. 

3.2 Getting a File for Editing 

In the chapter "Basic Usage", you saw that you could edit a file by either specifying the name on the 
command line when invoking Vi, or by selecting the File menu and picking the Edit new file option. 

The general way to edit a new file is to use the command line command edit. To enter this command, 
make sure that you are in command mode and press the colon key. Once the command prompt is 
displayed, then simply type edit (optionally followed by a file name or a list of files), and then press 

ENTER. 

If you do not specify a file, then a directory listing is displayed. From this listing, you may pick a file, 
another directory, or another drive (the available drives are at the end of the listing). A directory is 
indicated by the leading backslash (’V). If a directory is chosen in this window, then the list of files in that 
directory is displayed. This list also contains all the drives available (which are enclosed in square 
brackets, e.g. [c:]). If you select a drive, the list of files in the current directory on that drive is displayed. 

For files and directories, each line indicates the file name, the various attributes of the file ([directory, 
[a]rchive, [h]idden, [s]ystem, [r]eadable, [w]riteable, e[x]ecutable), the file size in bytes, the date and time 
of the last file update. Some sample lines are: 


test. c 

-a—rw- 

25586 

08/16/92 

08:14 

bar. c 

-a—r— 

639 

02/27/92 

13:25 

\tmpdir 
[c: ] 

d-rw- 

0 

08/16/92 

19:05 


You may also specify one or more files after the edit command. If a file you specify is the same as one 
already being edited, then control is simply transferred to the window with that file. 

Exercises 

1. Start up Vi without any files specified. Then try entering the command line command edit 
without any parameters (remember to press the colon (’:’) key first). You will see a screen 
similar to the following: 
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Figure 18. File Selection display 


Try changing to other directories or drives with this list. When you are done, press the ESC key 
to cancel the selection list. 

2. Try entering the following command line 

:e afile 

This will cause Vi to start editing a new file called "afile". 

3. Try entering the command 

:e bfile cfile 

This will cause Vi to edit two new files, one named "bfile" and one named "cfile". 

4. Enter the command 

:e afile 

This returns you to the first file ("afile") that you were already editing. 

5. Press CTRL_C, and Vi will quit all the files that you have started editing. 


3.3 Moving Between Files 

There are a number of ways to move between files that you are editing. As you have seen in the previous 
section, you can move to a file that you are already editing by using the command line command edit and 
specifying the name of the file you wish to move to. 


You may press the FI key while in command mode or text insertion mode. This function key moves you to 
the next file in the list of files that you are editing. 

You may press the F2 key while in command mode or text insertion mode. This function key moves you to 
the previous file in the list of files that you are editing. 
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The previous two function keys that you may use also have command line equivalents. The command line 
command next moves you to the next file in the list of files that you are editing. 

The command line command prev moves you to the previous file in the list of files that you are editing. 

It is also possible to display a list of all files that you are currently editing. You may press the F7 key in 
either command mode or text insertion mode, or enter the command line command files. Doing any one of 
these things will cause a list of all files currently being edited to appear. An asterisk (’*’) will precede files 
that have been modified. From this list, you may go to one of the files, quit one of the files, or save one of 
the files then quit it. 

Exercises 

1. Start up Vi in the following way: 
vi a b c 

This will cause you to edit three new files. Now, press the F7 key. The following will appear: 



Figure 19. Current File List 


Select the file b. That file will become the current file being edited. 

2. Type the command line 

:files 

You will see the same result as you saw in the previous example. Press the ESC key to cancel 
this display. 

3. Press the FI key several times. You will rotate through the three files that you are editing. 

4. Press the F2 key several times. You will rotate through the three files that you are editing, but in 
the opposite order than when you were pressing the FI key. 

5. Use the command line commands next and prev to move through the files. These commands 
behave the same as pressing FI and F2. 
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3.4 Moving Around in a File 

You have already learned to use the cursor keys to move around through a file. When you are in command 
mode, there are a number of keys that also cause movement through the file. Many of these keys may be 
preceded with a repeat count. You enter the repeat count by typing a number (which will be echoed in a 
special window on the screen). 

Once you have entered the repeat count, you may cancel it by pressing the ESC key, or you may follow it 
with a movement command. For example, if you type: 

3<Down Arrow Key> 

you will move down three lines instead of one. 

The basic command mode movement commands are: 

UP (up arrow key) 

Cursor up through the text. 

DOWN (down arrow key) 

Cursor down through the text. 

LEFT (left arrow key) 

Cursor left through the text. 

RIGHT (right arrow key) 

Cursor right through the text. 

HOME Move to the start of the current line. 

END Move to the end of the current line. 

PAGEUP Move up one page in the text. 

PAGEDOWN Move down one page in the text. 

CTRL_PAGEUP (Ctrl key + Page Up key) 

Move to the first character on the first line in the file. 

CTRL_PAGEDOWN (Ctrl key + Page Down key) 

Move to the last character on the last line in the file. 

There are additional commands that move you around the file which do not require your fingers to move 
off the home row of your keyboard. For a touch typist, this is a great advantage. For a list of all of the 
movement commands, see the section "Movement" on page 72 in the chapter "Modes". The following list 
of movement commands move you around on the current line: 

$ (dollar sign) Move to the end of the current line. 

0 (zero) Move to the start of the current line. 

b Move backwards to the previous word on the current line. If preceded with a repeat count, 

you move back that many words. 
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h Move right through the text. If preceded with a repeat count, then you move right that 

many characters. 

I Move left through the text. If preceded with a repeat count, then you move left that many 

characters. 

w Move forward to the next word on the current line. If preceded with a repeat count, you 

move forward that many words. 

B Move backwards to the previous whitespace delimited word on the current line. If 

preceded with a repeat count, you move back that many words. 

W Move forward to the next whitespace delimited word on the current line. If preceded with 

a repeat count, you move forward that many words. 

The following list of movement commands move you to other lines: 

CTRL_B Move back one page in the text. If preceded with a repeat count, you will move back that 

many pages. 

CTRL_D Move down one half page in the text. If preceded with a repeat count, then you move 

forward that many lines. As well, any future CTRL_D or CTRL_U commands issued will 
move that many lines, instead of a half page. 

CTRL_F Move forward one page in the text. If preceded with a repeat count, you will move forward 

that many pages. 

CTRLJU Move up one half page in the text. If preceded with a repeat count, then you move 

backwards that many lines. As well, any future CTRL_U or CTRL_D commands issued 
will move that many lines, instead of a half page. 

j Move down through the text. If preceded with a repeat count, then you move down that 

many lines. 

k Move up through the text. If preceded with a repeat count, then you move up that many 

lines. 

G Moves to the last line in the file. If preceded with a repeat count, then you move to that 

line in the file. 

H Move to the top of the current edit window. If preceded with a repeat count, you move that 

many lines from the top of the edit window. 

L Move to the bottom of the current edit window. If preceded with a repeat count, you move 

that many lines from the bottom of the edit window. 

M Move to the middle of the current edit window. 

Exercises 

1. Edit a new file, "atest". Once you have edited this file, add the line: 

This is a test line. 
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Once you have done this, copy this line by pressing ’Y’. Press ’p’ to paste in the copy. Press ’p’ 
28 more times, so that you create a file with 30 lines in it (all just like the first line). 


2. So that we can more easily see the results, type the following command line: 

:%s/V\# / 


This is a substitution command. It will replace the start of each of your lines with the line 
number. We will learn about the substitution command in the next chapter. When you are done, 
you should see a screen similar to the following: 



Figure 20. "ATEST" File Contents 


3. Press the ’G’ key. You will move to the last line of the file. 

4. Type the following: 

15G 

This will move you to line 15. 

5. Try using CTRL_F and CTRL_B. Notice that they behave just like PAGEUP and 
PAGEDOWN. 

6. Try using ’w’ and ’b’ to move forward and backwards through words in the file. 

7. Try using ’j’ and ’k’ to cursor up and down in the file. 

8. Try using T and ’h’ to cursor left and right in the file. 

9. Press the ’H’ key. The cursor will move to the top line in the edit window. 

10. Press the ’L’ key. The cursor will move to the bottom line in the edit window. 

11. Try typing some numbers before pressing the ’H’ and ’L’ keys. For example, typing 

3H 

will move your cursor to the 3rd line from the top of the edit window. 
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12. Press the ’M’ key. The cursor will move to the middle of edit window. 

13. Press the ’$’ key. The cursor will move to the end of the current line. 

14. Press the 'O’ (zero) key. The cursor will move to the start of the current line. 

15. Press CTRL_D. You will move down half a page 

16. Type the number '2' and then press CTRL_D. Notice that you only move down 2 lines. 

17. Press CTRL_D. You will move down 2 lines. 

18. Press CTRL_U. You will move up 2 lines. 

19. Press 'ZZ' to save the file. This file will be used in later exercises. 

3.5 Saving and Exiting a File Revisited 

We have already seen in the section "Saving and Exiting a File" on page 11a number of ways to save and 
exit your files. These methods included typing 'ZZ' and using the menus. 

There are a number of different command line commands that can be used for saving and/or quitting your 
files. 

1. quit ("!") or q ("!") 

2 . quitall 

3. write ("!") or w("!") 

4. wq 

5. xit 

The quit command is used to exit a file without saving it. If the file has been modified, the command will 
fail and the message: 

File modified - use :q! to force 
will be displayed. To quit a modified file, the exclamation point (’!’) is used: 

:quit! 
or 

: q! 

This discards the contents of the current edit buffer. 

To quit every file that you are editing, the quitall command is used. If no files have been modified, then 
you will immediately exit Vi. If files have been modified, you will be asked to verify whether or not you 
really want to exit the editor. 
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The write command is used to write the current file. If you specify a file name, the edit buffer will be 
written to a file with that name. 

:write new.txt 

writes out a new file with the name new. txt. 

If the file name you specify already exists, you will see the message: 

File exists - use w! to force 
To overwrite an existing file, use the exclamation point (’!’): 
write! new.txt 

or 

w! new.txt 

If you are specifying a new file name, you may also specify a line range to write to that new file. Some 
examples are: 

: 1,100 write new.txt - write the first 100 lines to "new.txt". 

:50 write a.txt - write line 50 to "a.txt" 

The wq ( write and quit) and the xit (exit) commands both do the same thing. They write out the current file 
if it has been modified, and then exit the file. This is the exact same as typing ’ZZ’ in command mode. 

Exercises 

1. Edit a file as follows: 

vi abc 

Add the lines: 

Line 1. 

Line 2 . 

Line 3. 

2. Enter the command line command quit (remember to press the colon (’:’) key to bring up the 
command window). You will see the message: 

File modified - use :q! to force 

Press CTRL_G. The message window will indicate the following: 

"abc" [modified] line 3 of 3 — 100% — 

As you can see, the file has been modified, so you are not allowed to quit. 

3. Enter the command line command write. You will see the message: 

"abc" 3 lines, 27 bytes 
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This indicates that the file has been written. Now press CTRL_G, and you will see: 

"abc" line 3 of 3 — 100% — 

Notice that the file no longer is marked as modified once it is written. 

4. Try the command line command quit again. This time, you will be able to quit the file, since the 
file has been written, and is no longer marked as modified. 

5. Re-edit the file "abc". Enter command: 

:1,2 w def 

This will write out a new file called "def". Now quit Vi. 

6. Edit the file "def". Notice that it contains the lines 

Line 1. 

Line 2. 

These are the first two lines of "abc", that you wrote to this file. Try entering the command: 

:write abc 

You will see the message 

File exists - use w! to force 

Since "abc" already exists, you are not allowed to overwrite it, unless you specify the 
exclamation point, as follows: 

:write! abc 

7. Re-edit the file "abc". Delete the last line. Press CTRL_G, and you will see that the file is 
modified. Now, enter the command line command (remembering to press 

:q! 

You will exit the file, even though it has been modified. 

8. Re-edit the file "abc", and delete the last line. Enter the command line command xit. This will 
save the file and exit it, and because you are not editing any other files, you will exit Vi. You 
could also use the command wq to do the same thing. Both of these commands do the same 
thing as pressing 'ZZ’ while in command mode. 

9. Start up Vi as follows: 

vi abc def 

This will edit two files, "abc" and "def". Enter the command line command quitall and you will 
exit Vi. 

10. Repeat the previous example, but add a line to one of the two files. Now enter the command line 
command quitall. In this case, you will be prompted with 
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Files are modified, really exit? 

Reply with a ’y\ and you will exit Vi, even though files are modified. 

3.6 Using the Mouse 

You may use the mouse for many things. You may select text, relocate the cursor, resize a window, move a 
window, use the scroll bar, or use the menus. 

Text selection will be discussed in the next section. Using menus with the mouse was discussed in the 
previous chapter, in the section "Using the Menus" on page 21. 

By simply moving your mouse cursor to a location in an edit window and clicking the left mouse button, 
the cursor will move to that position. 

By moving your mouse to the top border of an edit window and pressing down the left mouse button, you 
can move the window around by moving your mouse. When you release the button, the window will move 
to the new position. 

By moving your mouse to the bottom right hand corner of an edit window (to the vertical two-headed 
arrow) and pressing down the left mouse button, you can resize the window by moving your mouse. When 
you release the left button, the window will be redrawn in its new size. 

Edit windows have scroll bars which indicate the position in the file and allow you to position to different 
portions of the file. The scroll thumb (the solid block on the scroll bar) indicates the relative location of 
your current cursor position in the file. If the scroll thumb is at the top, then you are on the top line of the 
file. If it is at the bottom, then you at the end of the file. 

By left-clicking on the single arrows at the top or the bottom of the scroll bar, the edit window will scroll 
up or down a single line. If you hold the left mouse button down, then the window will scroll continuously. 

If you click the left mouse button in the scrollbar region between the thumb and the top arrow, you will 
move up a page in the file you are editing. If you click the left mouse button below the scroll thumb, you 
will move down a page in the file you are editing. If you hold the left mouse button down, then you will 
page continuously. 

By pressing and holding down the left mouse button on the scroll thumb, you can set the edit position 
yourself. As you drag the scroll thumb up and down, the edit window will be redrawn to show you the 
corresponding portion of your file. 

3.7 Selecting Text 

Vi has the ability to highlight (select) text, either on an individual line or a group of lines, and then do 
various actions on the highlighted (selected) text. 

You may select text with either the keyboard or the mouse. The keyboard interface is as follows: 

SHIFT_UP (shifted cursor up key) 

Starts or continues selection and moves up to the previous line. The new line is selected. 
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SHIFT_DOWN (shifted cursor down key) 

Starts or continues selection and moves down to the next line. The new line is selected. 
SHIFT_LEFT (shifted cursor left key) 

Starts or continues selection and moves left to the next character. The new character is 
selected. 

SHIFT_RIGHT (shifted cursor right key) 

Starts or continues selection and moves right to the previous character. The new character 
is selected. 

CTRL_R Starts text selection, if no text is selected. The current character is highlighted. If a region 

is already selected, then this cancels the selected region. 

ESC Cancels the current selection. 

Once text selection has been started, then any movement command may be used to expand or shrink the 
selected region. Multiple line selections always select complete lines. A portion of a single line can be 
selected (i.e. a word) by growing the selection left or right. A portion of a line is called a column region 
and a multiple line selection is called a line region. 

You can select text with the mouse by holding down the right or left mouse button, and moving the mouse 
up and down or left and right. When using the right button, a selection menu will appear after the mouse 
button is released , from which you choose what you wish to do with the selected text. 

If you highlight a region by holding down the left button and moving the mouse, then releasing the button 
has no effect (the region simply remains highlighted). This region may then be operated on from the 
command line, using different command mode commands, or by right-clicking the mouse in the selected 
region. 

If you click the right mouse button (right-click) while the mouse cursor is in a highlighted (selected) set of 
lines, then a selection menu for the lines appears. If you right-click in a selected group of characters on a 
single line (a column region) then a selection menu for that column region appears. The two menus are 
different. You may also bring up these menus by pressing the underscore (’_’) key. 

If you click the right mouse button (right-click) in an unselected region, the current word will be 
highlighted and the selection menu will appear. This can also be accomplished by pressing the underscore 
(’_’) key. 

If you double click the left mouse button, the current word will be highlighted and the selection menu will 
appear. However, the word selected here is slightly different than the word selected by clicking the right 
mouse button. This word is defined to include the characters and ’V, so that double clicking the left 

mouse button on a file name will select the entire path. 

Exercises 

1. Edit the file "atest" created in the Exercises section of "Moving Around in a File" on page 34. 
Click the left mouse button when the mouse cursor is on the top line, and drag your mouse down 
until the first 10 lines are selected. If you do not have a mouse, then press the shift key and 
cursor down until the first 10 lines are selected. 
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Now, click the right mouse button somewhere inside the selected region. If you do not have a 
mouse, press the underscore key. A menu will appear. The selected region and the menu 
will appear as follows: 
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Figure 21. Selected Lines menu 


From this menu, you can either delete or yank (copy) the lines. You may cancel the menu by 
pressing ESC (the region remains highlighted). You can cancel the selected region by pressing 
ESC again. 


If you click your left mouse button somewhere outside the selected region, both the menu and 
the selected region will be cancelled. 


2. Make sure the selected region is cancelled (press ESC until it is gone). Now press the right 
mouse button on the word "This" in the first line of the file. If you do not have a mouse, then 
position the cursor somewhere in the word "This" and press the underscore (’_’) key. You will 
see the following menu appear: 



Figure 22. Selected Columns menu 

You may do a number of things from the popup menu: 
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Open Open (edit) the file indicated by the highlighted (selected) text. The selected text 

is treated like a file name, and an edit session for that file is started. The file will 
be given the name of the highlighted text. 

Change Change the selected word. 

Delete Delete the selected word. 

Yank Yank (copy) the selected word. 

Fgrep Search the current directory for any files containing the selected word. See the 

command line command fgrep in the chapter "Editor Commands" on page 101 
for more information. 

Tag Search your tags file for the selected word. See the command line command tag 

in the chapter "Editor Commands" on page 101 for more information. 


3. Make sure the selected region is cancelled. Then add the following line to the start of the file 
(use the command mode key capital o (’O’) to open a line above the first line): 

♦include <c:\h\test.h> 

Now, try right mouse clicking on parts of the file name. Notice how only individual pieces of 
the file name are selected. Now, try double clicking the left mouse button somewhere on the file 
name. The menu from the previous example will appear, selecting the entire file name as shown 
below: 
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Figure 23. Double Click Selection 


4. Try using CTRL_R to start a selection and then move around in your file. Use the ESC key to 
cancel your selection. 

5. Try using the shifted cursor keys to select lines. Use the ESC key to cancel your selection. 
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3.8 Joining Text 

Vi has the ability to join two lines together. If you press the letter ’J’ (capital ’j’) while in command mode, 
then the next line will join to the end of the current line. All white space except for a single space will be 
removed. For example, typing ’J’ while on the first line in these two lines: 

This is a line. 

This is another line. 

produces the line: 

This is a line. This is another line. 

If you precede ' J' with a repeat count, then that many lines after the current line will be joined to the 
current line. For example, typing 

4 J 

while on the first line of: 

Line 1. 

Line 2. 

Line 3. 

Line 4. 

Line 5. 

Line 6. 

will produce the result: 

Line 1. Line 2. Line 3. Line 4. Line 5. 

Line 6. 

There is also a command line command called join that is used to join lines of text together. This 
command is used as follows: 

<linerange> join 

The lines in the specified range <linerange> are joined together. If a single line number is specified, then 
the line after that line is joined to the specified line. If no line number is specified, then the line after the 
current line is joined to the current line. For example, the command: 

:1/5 join 

will cause the lines 1 through 5 of the file to be joined into a single line. 

3.9 Using Marks 

Text marks are used to memorize a position in the edit buffer that you may want to return to later. Each file 
may have up to 26 marks in it (identified via the letters ’a’ through 'z’). Marks may also be set with the 
command line command mark. 
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A mark is useful in that you do not have to remember a specific line number, you just need to remember the 
letter that you picked for the mark name. You can then return to the line or even the exact position on the 
line easily. 

You may set a mark by pressing the letter’m’ (in command mode) and pressing one of the letters from ’a’ 
to ’z\ For example, if you type 

ma 

you will set the mark ’a’ at the current position in the file, and you will see the following message appear: 
Mark 'a' set 

You can set a mark with the command line command mark. The syntax of the command is 
<line> mark <letter> 

You specify which line the mark is to be set on with <line>. If no line is specified, the current line is 
assumed. You specify the mark id f a’-’z’) with <letter>. 

For example, the following command line commands may be used to set marks: 

mark a - sets the mark 'a' on the current line. 

5 mark b - sets the mark 'b' on line 5. 

Once you have set a mark, you may return to the mark by pressing either the front quote (apostrophy) (’) or 
the back quote (‘), followed by the letter of the mark you wish to return to. Using the back quote causes 
you to return to the row and column position of the mark. Using the front quote (apostrophy) causes you to 
return to the line with the mark (the cursor moves to the first column on the line). 

For example, after setting the mark ’a’, you can return to it by typing: 

'a - return to the line with the mark 'a' . 

'a - return to the exact position with the mark 'a'. 

Marks are useful when you need to go searching a file for something, but you want to be able to return to a 
specific position. They are also useful when deleting and copying text (see the section "Deleting, Copying, 
and Pasting Text" on page 48 later on in this chapter). 

For more information on marks, see the section "Marks" on page 79 in the chapter "Modes". 

Exercises 

1. Edit the file "atest" created in the Exercises section of "Moving Around in a File" on page 34. 
Cursor to the letter T in the word ’is’ on the first line, and type 

ma 

This will set the mark ’a’ at that position. 

2. Page down twice. Now, type 

'a 

You will be moved to the ’i’ in the word ’is’ on the first line. 
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3. Page down twice. Now, type 

'a 

You will be moved to the first column of the first line. 

4. Go to the bottom of the file. Now, enter the command line command mark as follows 
(remember to press colon to bring up the command window) 

:mark z 

5. Go to the top of the file (using CTRL_PAGEUP), and enter the command line 

: ' z 

This will return you to the last line of the file 

6. Now, type the following command line 

: 'a 

This will take you back to line 1, where you set the mark ’a’. 

3.10 Searching for Text 

You can search a file for a string in either a forwards or backwards direction. By using the command mode 
key 7’, you are prompted for a string to search for in the forwards direction. By using the command mode 
key ’?’, you are prompted for a string to search for in the backwards direction. 

When the string is found, your cursor is moved to the first character of the string, and the string is 
highlighted. 

If the string (for example, "abc") is not found, you will see the message: 

String 'abc' not found 

When you press 7’ (forward search), the following window will appear: 
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Figure 24. Search String Entry Window 

This window behaves just like the command window: you may cursor back and forth in the command 
window, and use the backspace and delete keys to change mistakes. Once you press ENTER, the 
command will be processed. If you press ESC, the search in cancelled. 

If you press ’ ?’ (backwards search), you will be able to enter a backwards search string. 

If you press ’n\ Vi will take you to the next occurrence of the last search string, searching in the same 
direction as the last search command. 

If you press ’N’, Vi will take you to the next occurrence of the last search string, only it will search in the 
opposite direction as the last search command. 

You can use complex search strings known as regular expressions. Certain characters have special 
meaning in a regular expression, they are: 

A $.[()|? + *\ @ 

If you wish to search for any of these special characters, you must place a backslash (’V) before the 
character. For example, to search for: 

ab. c$ 

you have to enter: 
ab\.c\$ 

For information on regular expressions, see "Regular Expressions" on page 167. 

The section "Searching" on page 82 in the chapter "Modes" describes the searching in more detail. 

Exercises 

1. Edit the file "atest" created in the Exercises section of "Moving Around in a File" on page 34. 
Press the forward slash (’/’) key, and enter the string "this". The word "This" on the first line 
will be highlighted, and your cursor will be on the ’T’. (notice that the search is case 
insensitive). 
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2. Now press, the ’n’ key. You will move to the word "This" on the second line. 

3. Press ’n’ two more times. You will now be on the word "This" on the fourth line. 

4. Press ’N\ You will move to the word "This" on the third line. 

5. Press the question mark (’?’) key, and enter the string "1". You will move to the ’ 1’ on the first 

line. 

6. Press ’n’. The search will wrap around to the end of the file, and search backwards until the ’1’ 
on line 21 is encountered. 

7. Press ’n’. You will move to the ’ 1’ on line 19. 

8. Press ’N’. You will move back to the ’1’ on line 21. 


3.11 Deleting, Copying, and Pasting Text 

There are two useful commands in Vi for deleting and copying text. In command mode, you press the’d’ 
key to start the delete sub-mode. You press the ’y’ key to start the yank (copy) sub-mode. Each of these 
sub-modes is indicated on the mode indicator on the menu bar: 

Mode: delete 


or 


Mode: yank 

Once you have entered the sub-mode, you can then specify one of the following operations: 

1. A movement command. See the section "Movement" on page 72 for a full description of all 
movement commands. If a movement command is specified, then the range that the command 
will act on is from the current position to the position that would be achieved by using the 
movement command. 

2. A search command: 

• / (forward slash) 

• ? (question mark) 

• n 

•N 

See the section "Searching" on page 82 for a full description of the searching commands. If a 
search command is specified, then the range that the command will act on is from the current 
position to the position that would be achieved by using the search command. 

3. The current selected (highlighted) region. In this case, <oper> is the r key. 

4. The same character as the command character. This causes the command to operate on the 
current line. 

Some examples are: 
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dw - delete a word 

yr - yank (copy) highlighted region 

d/text - delete up to the word "text". 

These commands can be preceded by an optional repeat count. This repeat count specifies the number of 
times that the command will be executed. If the repeat count is not specified, the command is executed 
once. For example: 

3dw - delete 3 words 
2yy - copy 2 lines 

A copy buffer can be specified between the repeat count and the command. The buffer is identified by 
preceding it with double quotes ("). For example: 

3"ayy - copy 3 lines into buffer 'a'. 

"zdd - delete 3 lines into buffer 'z'. 

The optional copy buffer is a place where deleted or yanked text resides. If you do not specify a buffer, 
then the active copy buffer is assumed. There are 9 numbered buffers (1-9) that may be selected as the 
active buffer (buffer 1 is the default active buffer). When text enters the active copy buffer, the old 
contents of the active buffer spills into the next buffer. The contents of each buffer spills into the next, with 
the end buffer (9) losing its contents. 

The active copy buffer may be selected by pressing CTRL_F1 through CTRL_F9 in command mode. 
When you do this, a message appears showing you which buffer has been selected, how many 
lines/characters are in the buffer, and the first line of the buffer. 

There are also 26 named buffers, ’a’ through ’z\ The contents of these buffers is constant over the life of 
your editing session. They retain their contents until you update them. 

For more information on copy buffers, see the section "Copy Buffers" on page 81 in the chapter "Modes". 

There is also a delete command line command and a yank command line command for deleting and 
yanking text. These commands only operate on line ranges. Their syntax is: 

<range> delete <"?> 

<range> yank <"?> 

The <"?> indicates a copy buffer, and <range> indicates a line range. If no line range is specified, then 
the current line is assumed. Some examples are: 

:1,5 delete - delete lines 1 to 5 

:1,$ yank "a - copy all lines into buffer 'a' 

:d - deletes the current line 

In the section "Cutting and Pasting Text" on page 16 in the previous chapter, you learned about the small 
’p’ and the capital ’p’ CP’ ) command mode commands to put (paste) copied or deleted text into the edit 
buffer. Remember, small ’p’ is used to paste after the current cursor position, and capital ’p’ CP’) is use to 
paste before the current cursor position. 

If what you deleted or yanked was a sequence of characters on a single line, then these characters are 
inserted into the current line when you paste. If you deleted or yanked whole lines, then those lines are 
inserted around the current line when you paste. 
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The put (paste) command line commands accept a copy buffer as the buffer to paste out of. The default is 
the active copy buffer, but any buffer can be specified. Once again, <"?> indicates a copy buffer: 

<"?>p 

<"?>P 

As well, there is a command line command for pasting text: the put command. The syntax is: 

<line> put <!> <"?> 

If the line <line> is specified, then the buffer is pasted around the specified line instead of the current line. 

If the exclamation mark is specified, then contents of the copy buffer are pasted before the specified line. 
Otherwise, the contents of the copy buffer are pasted after the specified line. 

The <"?> is an optional copy buffer. If it is not specified, then the active copy buffer is used. The double 
quotes (") must be specified. 

Deleting text is discussed in more detail in the section "Deleting Text" on page 86 in the chapter "Modes". 
Copying text is discussed in more detail in the section "Copying Text" on page 88 in the chapter "Modes". 

Exercises 

1. Edit the file "atest" created in the Exercises section of "Moving Around in a File" on page 34. 
Press ’dd’. This will delete the first line of the file. 

2. Press ’dw\ This will delete the first word of the line. 

3. Press ’d$\ This will delete to the end of the line. 

4. Press ’dj\ This will delete the current line and the next line. 

5. Press '2dw\ This will delete the first two words of the current line: 

04 This is a test line, 
leaving you with 

is a test line. 

6. Press ’2w’. This will move you to the letter ’t' in "test". Press capital p CP’). The 2 words you 
deleted will be inserted before the ’t’: 

is a 04 This test line. 

7. Type the following command mode keys: 

"add 

You will see the message: 

1 lines deleted into buffer a 

8. Press ’p’. Note that you inserted the two words you deleted before into the current line. 


50 Deleting, Copying, and Pasting Text 




Intermediate Usage 


9. Type: 

"ap 

This will insert the contents of buffer 'a’ (line line you deleted) after the current line. 

10. Type the following: 

2 "byy 

This will copy the next two lines into buffer "b". You will see the message 
2 lines yanked into buffer b 


11. Type: 


"bP 

This will insert the two lines you yanked before the current line. 

12. Type 


3 " zyw 

This will yank three words into copy buffer V. 

13. Make sure you are in command mode and enter the command line 

:q! 

to exit without saving your changes. 

3.12 Altering Text 

You could change text by deleting the text and then entering insert mode. However, Vi provides a special 
method for doing both of these things at once. By pressing the V key in command mode, you enter the 
change sub-mode. You will see the mode line indicate: 

Mode: change 

If you are changing characters on a line, the characters will be highlighted. If you press the ESC key, the 
change will be cancelled. Once you type a character, the characters will be deleted and you will enter text 
insertion mode. 

If you are changing whole lines, the lines are deleted and you enter text insertion mode. 

Once you have entered the change sub-mode, you can then specify one of the following operations: 

1. A movement command. See the section "Movement" on page 72 for a full description of all 
movement commands. If a movement command is specified, then the range that the command 
will act on is from the current position to the position that would be achieved by using the 
movement command. 
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2. A search command: 

• / (forward slash) 

• ? (question mark) 

• n 
•N 

See the section "Searching" on page 82 for a full description of the searching commands. If a 
search command is specified, then the range that the command will act on is from the current 
position to the position that would be achieved by using the search command. 

3. The current selected (highlighted) region. In this case, <oper> is the r key. 

4. The same character as the command character. This causes the command to operate on the 
current line. 

Some examples are: 

cw - change current word 

c$ - change to the end of the current line 

You can also specify an optional repeat count before the change command. This will cause the change 
command to be repeated that many times. For example: 

2cw - change two words 
3cc - change three lines 

The changing of text is discussed in greater detail in the section "Changing Text" on page 89 of the chapter 
"Modes". 

Exercises 

1. Edit the file "atest" created in the Exercises section of "Moving Around in a File" on page 34. 
Type’cw’. This first word "01" will be highlighted. Press ESC. The word will return to 
normal, and nothing will happen. 

2. Type ’cw’ again. This time, type the following: 

This is new text. 

and press the ESC key to exit text insertion mode. Your original line: 

01 This is a test line, 
will now be: 

This is new text. This is a test line. 

3. Type ’2cc\ The first two lines will be deleted, and you will enter text insertion mode. Type the 
following: 

This is more new text. 

4. Return to command mode by pressing the ESC key. Cursor to the letter T in the word "is" and 
type ’c$\ This will highlight from the letter T to the end of line. Enter the text: 
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This is more new text. 

5. Make sure you are in command mode and enter the command line 

:q! 

to exit without saving your changes. 

3.13 Undo and Redo 


Vi has an unlimited undo capacity (constrained only by memory and disk space). Every change that you 
make to a file is remembered, and can be undone in the reverse order that you made the changes. 

A change can be undone by pressing the letter ’u’ while in command mode. You can undo further changes 
by pressing ’u’ repeatedly. 

If you undo a change you wanted to keep, you can redo it by pressing capital ’u’ (’U’). Each time you 
press ’U\ an undo is re-done. Once you undo changes, you cannot redo them after you modify the file. 

The command line command for undoing changes has the following syntax: 

undo 

If you specify an exclamation point (’!’) after the undo keyword, then you will do a redo instead of an 
undo: 


undo! 

See the section "Undoing Changes" on page 79 in the chapter "Modes" for more information. 

Exercises 

1. Edit the file "atest" created in the Exercises section of "Moving Around in a File" on page 34. 
Delete the first line, delete the second line, then delete the third line (one at a time). Then, press 
’u’ in command mode. The third line will come back. 

2. Press ’u’ again. The second line will come back. 

3. Enter the command line command: 

: undo 

The first line will come back. 

4. Enter the command line command 

: undo 

again. This undo command cannot do anything, since you have already undo all the changes to 
your file. You will see the message 

No more undos 
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appear. 

5. Press the capital u (’IT) key in command mode. The first line will now disappear, as you are 
undoing your undo. 

6. Press ’U’ again. The second line will disappear. 

7. Enter the command line command (remember to press 

undo! 

The third line will disappear. 

8. Enter the command line command: 

undo! 

You will see the message: 

No more undos 


3.14 Repeating Edit Operations 

When you enter a command mode command to modify your file you can re-execute the sequence by 
pressing the dot (’.’) key. 

For example, suppose you entered the command mode command: 

3dd 

to delete 3 lines. If you press after this, you will delete another 3 lines. 

There are two useful extension to this as well. Vi has concepts known as memorize mode and alternate 
memorize mode. You enter memorize mode by pressing the letter’m’ (also used to set a mark) followed 
by a dot (’.’). You will then see the message 

Memorize Mode started 

From this point forward, every key that you type is memorized. When you are done memorizing, you can 
then press the dot (’.’) key while in command mode, and this ends memorize mode. You will see the 
message: 

Memorize Mode ended 

Once you have memorized a key sequence, you can re-execute it by pressing dot (’.’). This will cause Vi to 
behave as if all the keys you memorized were being typed by you again. 

The memorized sequence will be lost the next time you change the text other than with To memorize a 
sequence that will always be remembered, you can use alternate memorize mode. This mode is used the 
same way as memorize mode, only you use an equals sign (’=’) instead of a dot (’.’). 

Exercises 
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1. Edit the file "atest" from the Exercises section of "Moving Around in a File" on page 34. Delete 
the first two lines by typing the command mode command: 

2dd 

Now press the dot key. Two more lines will be deleted. 

2. Move to the first column of the first line. Type the command mode command: 

m. 

This will start you in memorize mode. Now, type: 
dwjdwj. 

This deletes the word on the first line, goes down to the next line, deletes another word on the 
next line, and goes down one more line. The final dot (’.’) terminates memorize mode. 

3. Now, press dot This will delete the first word of the next two lines. 

4. Make sure you are in command mode and enter the command line 

:q! 

to exit without saving your changes. 
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4 Advanced Usage 


This chapter discusses a number of the less commonly used features of the Open Watcom Vi Editor. The 
knowledge of the information in the chapter "Basic Usage" and "Intermediate Usage" is assumed. 


4.1 The Substitute Command 


The command line command substitute is a powerful mechanism for changing text in your file. For every 
match of a string, the string can be replaced with something else. 

You can use complex search strings known as regular expressions. Certain characters have special 
meaning in a regular expression, they are: 

A $.[()|? + *\ @ 

If you wish to search for any of these special characters, you must place a backslash (’V) before the 
character. For example, to search for: 

ab. c$ 

you have to enter: 
ab\.c\$ 

For information on regular expressions, see "Regular Expressions" on page 167. 

The syntax of the substitute command is: 

<linerange> substitute /<string>/<subs>/"g""i" 

The line range <linerange> specifies the lines that the substitute command is to work on. If no line range 
is specified, then the current line is assumed. 

The first occurrence of the search string <string> on each line is replaced with the string <subs>. 

If the letter 'g’ is specified at the end, then every occurrence of the search string <string> on each line is 
replaced with the string <subs>. 

If the letter T is specified at the end, then the substitution is interactive. You will be prompted before each 
replacement to verify that you want it to be done. 

Exercises 

1. Edit the file "atest" created in the Exercises section of "Moving Around in a File" on page 34 in 
the previous chapter "Intermediate Usage". Enter the command line command (remember to 
press colon (’:’) to bring up the command window): 
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: 1,$s/This/This This/ 

All lines will have the word "This" replaced with "This This". 

2. Enter the command line command: 

: 1,$s/This/Change/ 

Notice that only the first occurrence of the word "This" was replaced. 

3. Type the letter ’u’ in command mode to undo the change you just made. Then enter the 
command line command: 

: 1,$s/This/Change/g 

Now all of the occurrences of "This" were replaced. 

4. Make sure you are in command mode and enter the command line 

:q! 

to exit without saving your changes. 


4.2 The Global Command 

The command line command global is a method of executing a command on every line that has (or does 
not have) a specific string. 

You can use complex search strings known as regular expressions. Certain characters have special 
meaning in a regular expression, they are: 

A $.[()|? + *\ @ 

If you wish to search for any of these special characters, you must place a backslash CV) before the 
character. For example, to search for: 

ab. c$ 

you have to enter: 
ab\.c\$ 

For information on regular expressions, see "Regular Expressions" on page 167. 

The syntax of the global command is: 

<linerange> global "!" /<string>/ <cmd> 

The line range <linerange> specifies the lines that the global command is to work on. If no line range is 
specified, then all the lines in the file is assumed. 

The command line command <cmd> will be executed on every line that has the string <string>. 
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If the exclamation mark (’!’) is used, then the command line command <cmd> will be executed on every 
line that does not have the string <string>. 

Exercises 

1. Edit the file "atest" created in the Exercises section of "Moving Around in a File" on page 34 in 
the previous chapter "Intermediate Usage". Enter the command line command (remember to 
press colon to bring up the command window): 

:g/This/delete 

Each line that contains the word "This" on it will have the delete command executed on it. 

2. Press the ’u’ key to undo the previous global command, then enter the command line command: 

:g/l/delete 

All lines with the character ' 1’ in them will be deleted. 

3. Press the ’u’ key to undo the previous global command, then enter the command line command: 

:g!/1/delete 

All lines without the character ’ 1 ’ in them will be deleted. 

4. Make sure you are in command mode and enter the command line 

:q! 

to exit without saving your changes. 

4.3 Searching Files For Text 

There are command line commands provided to search through all files for some text. These commands 
differ from the search commands outlined in the section "Searching for Text" on page 46 in the previous 
chapter in that they search files in directories rather than files that are being edited. These file search 
commands are fgrep and egrep. 

The fgrep command is a fast search for a specified string. The syntax of this command is: 

fgrep "-c" "-i" <string> <files>. 

The file list <files> is searched for the string <string>. 

If you wish to have spaces in your string, then you can enclose the string in either double quotes or 
forward slashes (’/’). 

If -c is specified, then the search is made case sensitive. If -i is specified, then the search is made case 
insensitive. If neither of these options is specified, then case sensitivity is determined by the current 
caseignore setting (for more information about caseignore.see the section "Boolean Settings" on page 148 
in the chapter "Editor Settings"). 
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The egrep command searches for regular expressions, and is slower than the fgrep command. The syntax 
of this command is: 


egrep <regexp> <files>. 

The file list <files> is searched for the regular expression <regexp>. 

If you wish to have spaces in your regular expression, then you can enclose the string in either double 
quotes or forward slashes (’/’). 

For example, entering the following command: 

:fgrep window *.c 

searches all files in the current directory ending in the extension .c for the string window. While searching 
for the item. Open Watcom Vi Editor displays a window that shows all files being searched. 


When all matches are found, a selection window is presented with all the files that contained the search 
string. 


The selection window appears as follows: 


File Edit Position 
HSpecial Key 
<F1> Go To 
<F2> Edit 
<F3> Get All 


Window 


guiclrst.c 

guicreat-c 

guidlg.c 

guidraw.c 

guiextra.c 

guigcolr.c 

guignval.c 

guihfIt-c 

guihint.c 

guihook.c 

guihtool.c 

guiimdi.c 

guiimmdi.c 

guimdi.c 

guindime.c 


-|no_name | 


command 


20:00 


-|Files With Matches I 


-l/22-i^ 


"bool GUIClearStatusText< gui window * wnd >” A| 

’’ * GUICreateUindow — Create a window with gi‘ 

” gui_window «wnd; M 

’’extern u o id GU I Dr a wT ext ( gui_window *wnd, char 
’’void GUISetExtra< gui_window *• wnd, void *■ ext 
’’static void PickColourC gui_window «wnd, int 1 
’’static bool GetNewFunction< gui_window *gui, g 
’’extern bool GUICreateFloatingPopup< gui_window 
”bool GUIHasHintType< gui_window *wnd, hint_typ 
’’static void <*fXChangeTitle>< gui_window * 

’’extern bool GUICreateFloat Too lBar< gui_window 
’’void InitMDI< gui_window *wnd, gui_create_info 
’’bool XFakelnitMDI< gui_window *wnd >;” 

’’extern void GUIAddMDIActions< bool has_items, 
’’extern gui_window *Root;” 1 


L = 


1 C: 


1 ”no_name” [new file] line 1 of 1 — 100X — 


Figure 25. FGrep result display 


4.4 Mapping Keys 

A powerful feature in Open Watcom Vi Editor is the ability to change the meaning of any key in command 
mode or text insertion mode. Using this feature, you can configure the editor any way which suits your 
needs. 


The command line commands map and mapbase are used to remap the definition of a key. The syntax of 
these commands is as follows: 

map "!" <key> <string> 
mapbase <key> <string> 

Both commands remap the specified key <key> to execute the characters in <string>. Whenever the 
specified key is pressed while in command mode, it is equivalent to typing the characters in <string>. 
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In the map command, specifying the exclamation point (’!’) causes the map to be for text insertion mode, 
rather than command mode. 

It is possible for <string> to contain keys that are mapped themselves. If you want to do a key mapping 
that is in terms of the base definitions of the keys, then you should use the mapbase command. 

To remove the mapping of a key, the command line command unmap is used. The syntax of this 
command is: 

unmap <key> 

If you need to specify a special key (e.g. ENTER, FI, etc) for <key> you specify a symbolic name for it. 
There are a number of pre-defined key symbols that are recognized when specifying which key is being 
mapped or unmapped. These are described in the Appendix "Symbolic Keystrokes" on page 221. 

If you need to use one or more special keys (e.g. ENTER, FI, etc) in <string> then you may enter: 

\<"key"> Any special key may be inserted for "key". The angle brackets are required. There are a 
number of pre-defined keys symbols that are recognized. These are described in the 
Appendix "Symbolic Keystrokes" on page 221. 

\e Short form for the escape key (rather than \<ESC>). 

\n Short form for the enter key (rather than \<ENTER>). 

V; If a command line command is used in the sequence, and it follows the colon (’:’). the 

command is not added to the history. For example: 

:\hdate\n 

will display the current date and time, but the command will not enter the command 
history. 

\x If a command line command is used in the sequence, then this stops the command window 

from opening. This prevents the "flashing" of the command window as it is opened then 
closed. For example: 

\x:date\n 

will display the current date and time, but the command window will not be displayed. 


Exercises 

1. Edit the file "atest" created in the Exercises section of "Moving Around in a File" on page 34 in 
the previous chapter "Intermediate Usage". Enter the following command line command: 

:map F5 dd 

Now, whenever you press F5, a line will be deleted. Try pressing F5 a few times to verify this. 

2. Enter the command line command 

:unmap F5 
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and try pressing F5 again. It will no longer delete lines. 

3. Enter the command line command 

:map F6 :date\n 

Press F6. The time and date will be displayed in the message window. You will notice that the 
command window flashes as you push F6. 

4. 

:map F6 \x:date\n 

Press F6. The time and date will be displayed in the message window. You will notice that the 
command window no longer flashes. 

5. Bring up the command window ( press and press cursor up. You will notice that the date 
commands are in your history. Now, enter the command line command: 

:map F6 \x:\hdate\n 

Press F6 a few times. Bring up the command window again and cursor up. You will see that the 
date commands did not get added to the history. 

6. Enter the command line command: 

:map! F6 \edwi 

Whenever you press F6 in text insertion mode, you will exit insert mode (the \e is like pressing 
the ESC key), delete the current word, and then re-enter insert mode. Try entering text insertion 
mode and pressing F6. 

7. Exit text insertion mode and press F6. You will notice that the date is still displayed, since the 
text insertion mode and command mode mappings for F6 are different. 

8. Make sure you are in command mode and enter the command line 

: q! 

to exit without saving your changes. 
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5 The Open Watcom Vi Editor Environment 


Along with the Open Watcom Vi Editor executable, there are a number of files that are needed: 
ed.cfg The configuration script (contains editor setup) 

keys.dal Symbolic key names used by the command line commands map, mapbase, unmap, 

execute and keyadd. 

errmsg.dat The text strings for Vi’s various error messages. 

error.dat Symbolic names for errors that can occur. These are used for testing return codes in editor 
scripts. 

The editor searches for its special files as follows: 

1. The editor executable itself (if the files are bound). 

2. The current directory. 

3. Directories in the EDPATH environment variable. 

4. Directories in the PATH environment variable. 

The environment variable EDPATH is used so that the support files for Vi do not have to be in your 
PATH. Only Vi itself has to be in your PATH. 

5.1 Using Edbind 

Edbind is a utility designed to place any specified files onto the end of the editor executable. The file 
edbind. dat contains the list of all files to bind. This would normally include ed.cfg and all the .dat 
files. This eliminates the need to have these files in your path, and allows Vi to locate the files faster. 

Note that your configuration file must be the FIRST FILE in the edbind. dat file. The first file is 
designated to be the file containing the configuration script, the name is irrelevant. 

The contents of edbind. dat might be as follows: 
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edvi 
rdmevi 
wrmevi 
resvi 
qallvi 
procvi 
errvi 
chkoutvi 
forceoutvi 
unlockvi 
mcselvi 
mlselvi 
lnum._ vi 
keys.dat 
errmsg.dat 
error.dat 

In this example, edbind. dat contains the special files ed. cf g, all the .dat files, and a number of 
compiled editor scripts (the files with the ,_vi extension). 

Usage is as follows: 

edbind <editor exe name> (-s) 

Options -s: strip info from executable 
The files in edbind. dat files are searched for in the following order: 

1. The current directory. 

2. The directories in the environment variable EDPATH. 

3. The directories in the environment variable PATH 


5.2 Invoking the Open Watcom Vi Editor 

Vi is invoked from the command prompt with the following possible set of parameters: 

vi [-?-dinqrvz] +<n> -k "keys" [-s <scr> [-p "parm"]] [-t <tag>] 

[-c <cfg>] files 

The files specified may contain regular expressions. 

The parameters cause the following: 

-? Displays the possible options, and what they do. 

Starts Vi in stdio mode. In this mode, Vi reads from standard in to get the file to edit. 
When the file is written, the lines are written to standard out. This is useful for including 
Vi in a pipe. 

-d Use default configuration. Vi will not invoke ed. cfg when it starts up. 
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-q 

-r 

-v 

-z 

+<n> 

-k "keys" 

-s <scr> 

-p "parms" 

-t <tag> 

-c <cfg> 


Ignore lost files. Vi will not let you start if there are files to be recovered. This option will 
cause Vi to get rid of its checkpoint fde, so that it will no longer complain about fdes that 
have not been recovered. 

This option will cause Vi to read a file as it needs the data, instead of reading the file all at 
once. It is useful if you wish to look at the first lines of a huge file. This option overrides 
any setting of readentirefile in your configuration. 

Causes Vi to run in quiet mode (no screen usage). This is useful for using Vi as a batch 
script processor. 

Recover lost files, if there are any. If this option is specified, files specified on the 
command line are ignored. 

Causes file edited to be a "view only" file. 

Causes Vi not to terminate a file read when finding a ctrl-z in a file. This option is the 
same as the ignorectrlz setting. 

Cause Vi set the edit buffer to line <n> in the file edited. 

Execute the string keys as if they were typed from the keyboard. These keystrokes are 
processed once Vi is initialized and all files have been read in. 

Runs the startup script <scr> once Vi is initialized and all files have been read in. Up to 10 
startup scripts may be specified. 

Specify the parameters parms for each startup script. Multiple parms may be specified as 
long as they are in double quotes. The parameters are associated with the most recently 
specified startup script. 

Edits the file containing the tag <tag>. 

Runs the configuration script <cfg>, instead of the default ed. cf g. 


5.3 Lost File Recovery 

Vi has an autosave feature that periodically makes a backup copy of the current edit buffer. This backup is 
kept in the directory specified by the tmpdir setting. 

The autosaveinterval setting is used to specify the number of seconds between backups of the current edit 
buffer. If autosaveinterval is set to 0, then the autosave feature is disabled. 

Vi keeps a lock file called alock_?.fil in its tmpdir. The question mark (’?’) will be a letter. There may be 
more than one lock file, if more than one copy of Vi is running on the current machine. 

Vi keeps a checkpoint file called asave_?.fil. The question mark (’?’) will be a letter. Once a file is 
autosaved, its name is added to this checkpoint file. When the file is discarded, its name is removed from 
this checkpoint file. So, if for any reason, you lose your editing session, this checkpoint file will contain 
information about what files were being edited at the time. Assuming tmpdir has been set to D:\TMP, then 
a example of what asave_?.fil could contain is: 
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d:\tmp\aaaaa23j.tmp e:\c\test.c 
d:\tmp\baaaa23j.tmp e:\h\test.h 
d:\tmp\caaaa23j.tmp c:\autoexec.bat 

The file e:\c\test.c was being edited, and its backup is stored in d:\tmp\aaaaa23j.tmp. 

The file e:\h\test.c was being edited, and its backup is stored in d:\tmp\baaaa23j.tmp. 

The file c:\autoexec.bat was being edited, and its backup is stored in d:\tmp\caaaa23j.tmp. 

You do not need use this information in order to recover lost files, however, this is useful to know if you 
wish to look at the files before recovering them. 

If a checkpoint file exists when Vi is started, then the following message will appear: 

Files have been lost since your last session, use -r to recover or 
-i to ignore 

Vi cannot be invoked until either -i or -r is specified. 

If -i is specified, then the checkpoint files are erased and Vi starts up normally. The .tmp files that contain 
the lost files still remain in the backup directory, however. 

If -r is specified, then Vi recovers the lost files. Note that the recovered files must be saved in order to 
overwrite the original copy. 
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6 Modes 


The Open Watcom Vi Editor is a modal editor. When you are in command mode (the default mode), there 
are a number of valid keys that may be pressed. To ensure that you are in command mode, press the ESC 
key until the mode indicator on the menu bar displays: 

Mode: command 

When in text insertion mode, text may be entered. There are two aspects to text insertion mode: insert and 
overstrike. Text insertion mode is entered via a number of different commands from command mode, 
and is indicated by a larger cursor, along with a mode line indication. The types of cursor are controlled 
with the commandcursortype, insertcursortype, and overstrikecursortype settings. 

When Vi is in a text insertion mode, the mode indicator on the menu bar displays one of: 

Mode: insert 


or 


Mode: overstrike 


6.1 Text Insertion Mode 


When in text insertion mode (either inserting or overstriking ), you may enter text and freely cursor about 
through the file. When you are finished adding text, the ESC key returns you to command mode. 

It should be remembered that an undo applies to changes caused by commands; so all changes made while 
in text insertion mode are part of a single undo record. For more information on undos, see the section 
"Undoing Changes" on page 79 later on in this chapter. 

The following keys, when pressed in command mode, place you into text insertion mode: 

a Starts appending (inserting) text after the current character in the edit buffer. 

A Starts appending (inserting) text after the last character on the current line in the edit buffer. 

C Changes text from the current position to the end of the current line. Deletes the text, and 

enters text insertion mode. 

<n>c<oper> Change command. Deletes the text in the range specified by <oper>, and enters text 
insertion mode. 

g Starts inserting or overstriking text at the current cursor position, depending on how you 

were adding text the last time you were in text insertion mode. 

i Starts inserting text at the current cursor position. 

I Starts inserting text before the first non-white space character on the current line. 
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o Opens a line after the current line, and enters text insertion mode. 

O Opens a line before the current line, and enters text insertion mode. 

R Starts overstriking text at the current character in the edit buffer. 

<n>s Substitute <n> characters. The first <n> characters from the current cursor position are 

deleted, and text insertion mode is entered. 

<n>S Substitute lines of text. <n> lines from the current line forward are deleted, and text 

insertion mode is entered. 

INS Start inserting text at the current cursor position. 

6.1.1 Special Keys 

While in text insertion mode, certain keys do special things. These keys are: 

Arrow Keys 


Up 

Cursor up through the text. 

DOWN 

Cursor down through the text. 

LEFT 

Cursor left through the text. 

RIGHT 

Cursor right through the text. 


Text Selection Keys 


SHIFT_UP (shifted cursor up key) 

Starts or continues selection and moves up to the previous line. The new 
line is selected. 

SHIFT_DOWN (shifted cursor down key) 

Starts or continues selection and moves down to the next line. The new 
line is selected. 

SHIFT_LEFT (shifted cursor left key) 

Starts or continues selection and moves left to the next character. The new 
character is selected. 

SHIFT_RIGHT (shifted cursor right key) 

Starts or continues selection and moves right to the previous character. The 
new character is selected. 

CTRL_R Starts text selection, if no text is selected. The current character is 

highlighted. If a region is already selected, then this cancels the selected 
region. 

ESC Cancels the current selection. 
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CTRL_PAGEUP 

Moves to the first non-white space character on the first line of the current edit buffer. 
CTRL_PAGEDOWN 

Moves to the last character on the last line of the current edit buffer. 

SHIFT_DEL Deletes the currently selected region into the active copy buffer. 

SHIFT_INS Pastes the active copy buffer into the text after the current position. 

SHIFT_TAB Move back to the previous tab stop, deleting the characters before the cursor. 

CTRL_DEL (ctrl-delete) 

Delete the current line into the active copy buffer. 

CTRL_INS (ctrl-insert) 

Pastes the active copy buffer into the text before the current position. 

CTRL_D Move backwards shiftwidth spaces, deleting the characters before the cursor. A 
shiftwidth is a number that you may set, its default value is 4. 

CTRLJT Insert shiftwidth spaces. If realtabs is set, then once tabamount spaces are inserted, the 

spaces are replaced with a tab character. 

CTRL_V The next key typed is inserted directly, without any interpretation. 

CTRL_Q The next key typed is inserted directly, without any interpretation. 

BS Backspace one on the current line, deleting the character before the cursor. 

DEL Delete the character under the cursor. If you are at the end of the line, DEL has the same 

effect as pressing BS. 

ENTER Start a new line. 

END Move to the end of the current line. 

HOME Move to the start of the current line. 

INS Toggles between insert and overstrike mode. 

PAGEUP Move up one page in the text. 

PAGEDOWN Move up down one page in the text. 

TAB Move forward to the next tab stop. If realtabs is set, a tab character is inserted into the file. 

Otherwise, spaces are inserted. 
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6.2 Command Mode 

The following command mode command descriptions show items within angle brackets (<>). The angle 
brackets are there to indicate items that you may supply. You are not required to type the brackets. For 
example, <n> simply means that in the corresponding place in the command you can enter a number. 

Many commands may be preceded with a repeat count, which is indicated by a <n> before a command. 

The number is not required; if it is not supplied, it is usually assumed that a 1 was entered for the repeat 
count. As long as the setting repeatinfo is enabled, the number that is typed appears in a special window 
called the countwindow. 

Other commands may be preceded with a copy buffer name, which is indicated with a <"?>. If you do not 
want the result of the operation to be copied into the active buffer, then an alternate buffer may be 
specified. The double quotes (") are required (this indicates that an alternate buffer is being specified), and 
then a buffer ’ l’-’9’ or ’a’-’z’ is specified. See the section "Copy Buffers" on page 81 for more 
information. 

6.2.1 Movement 

The following are command mode commands that cause movement in the current edit buffer. 

<«>l (or bar) 

Move to the column number specified by <n>. 

Example(s): 

Move to column 1 of the current line. 

15 I 

Move to column 15 of the current line. 

‘< ?> (back quote) 

Moves to the mark position (line and column) specified by <?> See the section "Marks" on 
page 79 for more information. 

Also see the command line command mark. 

Example(s): 

'a 

Move to the line and column with mark a. 

’< ?> (front quote) 

Move to the start of line with the mark <?>. See the section "Marks" on page 79 for more 
information. 

Also see the command line command mark. 

Example(s): 

' z 

Move to the start of the line with mark z. 
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% (percent) 


$ (dollar) 

A (caret) 

; (semi-colon) 

, (comma) 


Moves to matching brace or other defined match string. Defaults are and 

For example, by pressing % while on the first opening brace (’(’) on the line: 

if( ( i=foo( x ) ) ) return; 

moves the cursor to the last closing brace (’)’) on the line. It is possible to set arbitrary 
pairs of match strings using the command line command match. 

Moves the cursor to the last character on the current line. 

Moves the cursor to the first non-whitespace character on the current line. 


Repeats the last f, F, t or T movement commands. 

Repeats the last f, F, t or T movement commands, but the search is done in the opposite 
direction. 

If the last movement command was an F then an f movement command is executed. If the 
last movement command was a t then a T movement command is executed. 


Similarly, if the last movement command was an f then an F movement command is 
executed. If the last movement command was a t then a T movement command is 
executed. 


<n>- (dash) 

Moves the cursor to the start of the previous line. If a repeat count <n> is specified, then 
you are moved up <n> lines. 

<n>+ (plus) 

Moves the cursor to the start of the next line. If a repeat count <n> is specified, then you 
are moved down <n> lines. 


0 


Moves the cursor the first character of the current line. 


CTRL_PAGEUP 

Moves to the first non-white space character on the first line of the current edit buffer. 
CTRL_PA GED O WN 

Moves to the last character on the last line of the current edit buffer. 

<n>DOWN 

Move the cursor down one line. <n> is specified, the cursor moves down <n> lines. 
END Moves the cursor to the last character on the current line. 

<n>ENTER 

Moves the cursor to the start of the next line. If a repeat count <n> is specified, then the 
cursor is moved down <n> lines. 

HOME Moves the cursor the first character of the current line. 

<n>LEFT Move the cursor left one character. If <n> is specified, the cursor moves left <n> 
characters. 
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<n> PAGEDOWN 

Moves forwards one page. If a repeat count <n> is specified, then you are moved ahead 
<n> pages. The number of lines of context maintained is controlled by the 
pagelinesexposed setting. 


<n>PAGEUP 

Moves backwards one page. If a repeat count <n> is specified, then you are moved back 
<n> pages. The number of lines of context maintained is controlled by the 
pagelinesexposed setting. 

<n>RIGHT 

Move the cursor right one character. If <n> is specified, the cursor moves right <n> 
characters. 

<n>SHIFT_TAB 

Moves the cursor left by tabamount characters. A repeat count <n> multiplies this. 
<n>TAB Moves the cursor right by tabamount characters. A repeat count <n> multiplies this. 

<n>UP Move the cursor up one line. <n> is specified, the cursor moves up <n> lines. 

<n>CTRL_B 

Moves backwards one page. If a repeat count <n> is specified, then you are moved back 
<n> pages. The number of lines of context maintained is controlled by the 
pagelinesexposed setting. 

<n>CTRL_D 

Move down a certain number of lines. The default is to move down half a page. If the 
repeat count <n> is specified, then that becomes the number of lines moved from then on. 
Also see the CTRL_U key. 

<n>CTRL_E 

Expose the line below the last line in the current edit window, leaving the cursor on the 
same line if possible. If a repeat count <n> is specified, then that many lines are exposed. 

<n>CTRL_F 

Moves forwards one page. If a repeat count <n> is specified, then you are moved ahead 
<n> pages. The number of lines of context maintained is controlled by the 
pagelinesexposed setting. 

<n>CTRL_N 

Move the cursor to the next line. If a repeat count <n> is specified, then you are moved 
down <n> lines. 

<n>CTRL_P 

Move the cursor to the previous line. If a repeat count <n> is specified, then you are 
moved up <n> lines. 

<n>CTRL_U 

Move up a certain number of lines. The default is to move up half a page. If the repeat 
count <n> is specified, then that becomes the number of lines moved from then on. Also 
see the CTRL_D key. 
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<n>CTRL_Y 


<n>B 


<n>b 


<n>E 


Expose the line above the first line in the current edit window, leaving the cursor on the 
same line if possible. If a repeat count <n> is specified, then that many lines are exposed. 

Moves the cursor backwards to the start of previous space delimited word on the current 
line. 

Example(s): 

B 

If the cursor was on the right parenthesis (’)’) of 
x = foo(abc) + 3; 
then the cursor moves to the f in foo. 

2B 

If the cursor was on the right parenthesis (’)’) of 
x = foo(abc) + 3; 
then the cursor moves to the = sign. 

Moves the cursor backwards to the start of the previous word on the current line. A word is 
defined using the word setting. The default is that any characters in the set (_, a-z, A-Z, 
0-9 ) are considered part of a word, and all other characters (except for whitespace) are 
delimiters. Groups of delimiters are considered to be a word as well. 

Example(s): 

b 

If the cursor was on the right parenthesis (’)’) of 
x = foo(abc) + 3; 

then the cursor moves to the letter a in abc. 

2b 

If the cursor was on the right parenthesis (’)’) of 
x = foo(abc) + 3; 

then the cursor moves to left parenthesis (. 

Moves the cursor to the end of the next space delimited word on the current line. 

Example(s): 

E 

If the cursor was on the letter f in 
x = foo(abc) + 3; 

then the cursor moves to the right parenthesis ). 

2E 

If the cursor was on the letter f in 
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x = foo(abc) + 3; 
then the cursor moves to the + sign. 

<n>e Moves the cursor to the end of the next word on the current line. A word is defined using 

the word setting. The default is that any characters in the set ( a-z, A-Z, 0-9 ) are 
considered part of a word, and all other characters (except for whitespace) are delimiters. 
Groups of delimiters are considered to be a word as well. 

Example(s): 

e 

If the cursor was on the letter f in 
x = foo(abc) + 3; 

then the cursor moves to the second letter o in foo. 

2e 

If the cursor was on the letter f in 
x = foo(abc) + 3; 
then the cursor moves to the left parenthesis (. 

<n>F< ?> Moves the cursor backwards from its current position to the character <?> on the current 
line. If a repeat count <n> is specified, then the nth occurrence of the character <?> is 
moved to. 

Example(s): 

F + 

If the cursor is on the semi-colon in 
x = foo(abc) + 3; 

The the cursor is moved to the + sign. 

2Fo 

If the cursor is on the semi-colon in 
x = foo(abc) + 3; 

The the cursor is moved to the first o in foo. 

<«>/<?> Moves the cursor forwards from its current position to the character <?> on the current 
line. If a repeat count <n> is specified, then the nth occurrence of the character <?> is 
moved to. 

Example(s): 

f+ 

If the cursor is on the character x in 
x = foo(abc) + 3; 

The the cursor is moved to the + sign. 
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<n>G 

<n>h 

<n>H 

<n>j 

<n>k 

<n>L 

<n>l 

M 

<n>T<?> 


2fo 

If the cursor is on the character x in 

x = foo(abc) + 3; 

The the cursor is moved to the second o in foo. 

Goes to the line specified by the repeat count <n>. If no repeat count is specified, you 
move the the last line in the current edit buffer. 

Example(s): 

100G 

Moves to line 100 in the current edit buffer. 


G 

Moves to the last line in the current edit buffer. 

Move the cursor left one character. If <n> is specified, the cursor moves left <n> 
characters. 

Moves to the line at the top of the current file window. If a repeat count is specified, then 
you are moved to that line relative to the top of the current file window. 

Example(s): 

2H 

Moves to the second line from the top of the current file window. 

H 

Moves to the line at the top of the current file window. 

Move the cursor down one line. <n> is specified, the cursor moves down <n> lines. 

Move the cursor up one line. <n> is specified, the cursor moves up <n> lines. 

Moves to the line at the bottom of the current file window. If a repeat count is specified, 
then you are moved to that line relative from the bottom of the current file window. 

Example(s): 

2L 

Moves to the second line from the bottom of the current file window. 

L 

Moves to the line at the bottom of the current file window. 

Move the cursor right one character. If <n> is specified, the cursor moves right <n> 
characters. 

Moves the cursor to the line in the middle of the current file window. 

Moves the cursor backwards from its current position to the character after the character 
<?> on the current line. If a repeat count <n> is specified, then the the character after the 
nth occurrence of the character <?> is moved to. 

Example(s): 

T + 
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If the cursor is on the semi-colon in 
x = foo(abc) + 3; 

The the cursor is moved to the space after the + sign. 

2To 

If the cursor is on the semi-colon in 
x = foo(abc) + 3; 

The the cursor is moved to the second o in foo. 

<n>t< ?> Moves the cursor forwards from its current position to the character before the character 

<?> on the current line. If a repeat count <n> is specified, then the the character before the 
nth occurrence of the character <?> is moved to. 

Example(s): 

t + 

If the cursor is on the character x in 
x = foo(abc) + 3; 

The the cursor is moved to the space before + sign. 

2to 

If the cursor is on the character x in 
x = foo(abc) + 3; 

The the cursor is moved to the first o in foo. 

<n>W Moves the cursor forward to the start of the next space delimited word on the current line. 

Example(s): 

w 

If the cursor was on the letter f in 
x = foo(abc) + 3; 
then the cursor moves to the + sign. 


2W 

If the cursor was on the letter f in 
x = foo(abc) + 3; 
then the cursor moves to the number 3. 

<n>w Moves the cursor forward to the start of the next word on the current line. A word is 

defined using the word setting. The default is that any characters in the set ( a-z, A-Z, 
0-9) are considered part of a word, and all other characters (except for whitespace) are 
delimiters. Groups of delimiters are considered to be a word as well. 

Example(s): 


78 


Command Mode 




Modes 


w 

If the cursor was on the letter f in 
x = foo(abc) + 3; 
then the cursor moves to the left parenthesis (. 
2w 

If the cursor was on the letter f in 
x = foo(abc) + 3; 
then the cursor moves to the letter a in abc. 


6.2.2 Undoing Changes 

Vi keeps an undo history of all changes made to an edit buffer. There is no limit on the number of undos, 
as long as there is enough memory to save the undo information. If there is not enough memory to save 
undo information for the current action, then the oldest undo information is removed until enough memory 
has been released. 

There is also an undo-undo (redo) history: as you issue undo commands, the information to redo the undo 
is kept. However, once you modify the file other than by doing an undo, the redo history is lost. 

As you issue undo commands, a message indicating how many undos are remaining. The message could 
look like: 

16 items left on undo stack 

This lets you know how many undos it would take to restore the edit buffer to its original condition. Once 
there are no more undos, you will see the message: 

undo stack is empty 

Once you undo all changes, then the file changes state from modified to unmodified. However, if some 
undo changes have had to be discarded because of low memory, the file will still be in a modified state. 

The keystrokes for doing undo and redo are: 


u 

Undo last change 

U 

Redo last undo. 


Also see the command line command undo (command). 

6.2.3 Marks 

Text marks are used to memorize a position in the edit buffer that you may want to return to later. Each file 
may have up to 26 marks in it (identified via the letters ’a’ through ’z’). Marks may also be set with the 
command line command mark. 

Mark commands are: 
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m<?> Allows the setting of mark <?>. 

If <?> is an exclamation mark (’!’) instead of a letter, it clears all marks on the current line. 

If <?> is a dot instead of a letter, it puts Vi in memorize mode. All characters typed 
are memorized until another dot (’.’) is pressed. The memorized keystrokes may be 
repeated by pressing a dot See the dot (’.’) command mode command later in this 
chapter. 

If <?> is an equals sign (’=’) instead of a letter, it puts Vi in alternate memorize mode. All 
characters typed are memorized until another equals sign (’=’) is pressed. The memorized 
keystrokes may be repeated by pressing an equals sign (’=’). See the equals sign (’=’) 
command mode command later in this chapter. 

Also see the command line command mark. 

Example(s): 

ma 

Sets the mark a at the current cursor position 


m. 

Enter memorize mode 
m! 

Clear any marks set on the current line. 

’<?> (front quote) 

Move to the start of the line with the mark <?>. 

Example(s): 

'a 

Moves to the first column of the line with mark a. 


Moves to the first column of line of the last position before the last 
non-linear movement command was issued. 


'<?> (back quote) 

Move to the position in the edit buffer with the mark <?>. 


Example(s): 

'a 

Moves to the column and line with mark a. 


Moves to the last position before the last non-linear movement command was 
issued. 

Pressing “ and ” take you to the last position you were at before you used a non-linear movement 
command (’, ‘, ?, /, G, n, and N commands). So, if you are at line 5 column 10 and type /foo, pressing “ 
will first move you back to line 5 column 10. Pressing “ again will move you to the occurrence of foo, 
since the previous “ command was a non-linear movement command. 
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6.2.4 Copy Buffers 

A copy buffer is a buffer where copied or deleted data is kept. There are a number of these buffers 
available. There are 9 default buffers that text is placed into when it is deleted/yanked (see the command 
line commands delete and yank, along with the sections "Deleting Text" on page 86 and "Copying Text" 
on page 88 later in this chapter). These buffers are numbered 1 through 9, and any of these buffers may be 
the active copy buffer. 

The active copy buffer may be selected using function keys. CTRL_F1 through CTRL_F9 select buffers 1 
through 9 respectively. When a buffer is selected, information about its contents is displayed in the 
message window. This buffer becomes the active copy buffer. All yanked/deleted text is copied into this 
buffer. 

When text is yanked/deleted into the active copy buffer, the contents of the the buffers are cascaded 
forward from the active buffer into the next one, with the last numbered copy buffer losing its contents. 

Any buffers that are before the active copy buffer have their contents preserved. For example, if buffer 3 is 
the active buffer, then a deletion will cascade buffer 3 to buffer 4, buffer 4 to buffer 5, and so on, with the 
contents of buffer 9 being lost. Buffers 1 and 2 remain untouched, and buffer 3 gets a copy of the deleted 
text. 

There are several command mode commands that add text to buffers; they are 

< "?><n>d<oper> 

Deletes text in various ways. 

<n>DEL Deletes the character at the current cursor position. 

D Deletes text from the current cursor position to the end of the current line. 

<n>x Deletes the character at the current cursor position. 

<n>X Deletes the character before the current cursor position. 

< "?><n>y<oper> 

Yanks (copies) text in various ways. 

<n>Y Yanks (copies) the current line. 

There is more information on these command mode commands later in this chapter. 

Text may be yanked/deleted into a specific copy buffer by typing "[1-9] before the appropriate command. 
As well, there are 26 named buffers that may be used, ’a’-’z’. When text is yanked or deleted into a named 
buffer, it remains there for the life of the editing session (or until replaced). 

To retrieve the contents of a buffer, use: 

< "?> SHIFT_INS 

Puts (pastes) the contents of the active copy buffer after the cursor position in the current 
edit buffer. 

Also see the command line command put. 

Example(s): 
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"aSHIFT_ INS 

Copy the data in the named buffer a after the current position in the file. 
SHIFT_ INS 

Copy the data in the active buffer after the current position in the file. 

< "?>p Puts (pastes) the contents of the active copy buffer after the cursor position in the current 

edit buffer. 

Also see the command line command put. 

Example(s): 

P 

Copies the data in the active buffer after the current position in the file. 

" 5p 

Copies the data in the numbered buffer 5 after the current position in the file. 

< "?>P Puts (pastes) the contents of the active copy buffer before the cursor position in the current 

edit buffer. 

Also see the command line command put. 

Example(s): 

"aP 

Copy the data in the named buffer a before the current position in the file. 


P 

Copy the data in the active buffer before the current position in the file. 
Without a "? prefix, these commands retrieve the contents of the active buffer. 

The contents of a copy buffer may be executed, as if the contents were typed from the keyboard. See the @ 
command mode command later in this chapter. 

6.2.5 Searching 

The following command mode commands are used for searching for text: 

/ (forward slash) 

Enter a regular expression to search for from current position forwards. 

? (question mark) 

Enter a regular expression to search for from current position backwards. 
n Repeat last search command, in the direction of the last search. 

N Repeat last search command, in the opposite direction of the last search. 

For more information on regular expressions, see "Regular Expressions" on page 167. 

Once you press the / or the ? keys, a search string entry window will appear: 
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command 17:51 


File Edit Position Window Options Help command 17:51 

-|no_name I- 

~ / 

ij_1 C:_1 "no_name M [new file] line 1 of 1 — 1 Q&x —_ 


Figure 26. Search String Entry Window 

This position and size of the search string entry window are controlled using the commandwindow 
windowing command. Search strings may be up to 512 bytes in length; the search string window scrolls. 

The search string window has a history associated with it; the size of this search string history is controlled 
using the maxfindhistory setting. As well, the search string history is preserved across sessions of Vi if 
the historyfile parameter is set. 

If the first letter of a search string is a CTRL_A (entered by typing a CTRL_V followed by a CTRL_A) 
then that search string will not be added to the search string history. 

6.2.5.1 Special Keys In The Search String Window 

Once in the search string window, a number of keys have special meaning: 


CTRLJV 

Insert next keystroke directly; do not process as a special character. 

CTRL_Q 

Insert next keystroke directly; do not process as a special character. 

CTRL_0 

Insert the current input string after current line in the edit buffer. 

ALT_0 

Insert the current input string before current line in the edit buffer. 

ALT_L 

Adds the current line in the current edit buffer, from the current column to the end of the 
line, to the input string. 

CTRL_E 

Adds the current space delimited word in the current edit buffer to the input string. 

CTRL_L 

Adds the current line in the current edit buffer to the input string. 

CTRL_R 

Adds the currently selected column range in the current edit buffer to the input string. 

CTRLJW 

Adds the current word in the current edit buffer to the input string. 

CTRLJNS 

Restores last thing typed in the input window (one level undo). 

UP 

Scroll backwards through the history. 
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DOWN 

ALT_TAB 

RIGHT 

LEFT 

CTRL_END 

END 

HOME 

INSERT 

BS 

DELETE 

ENTER 

ESC 

TAB 


Scroll forwards through the history. 

Command completion. Looks backwards through the history for first item starting with 
what is already entered. Subsequent presses of ALT_TAB get the 2nd last matching item, 
and so on. 

Move cursor right through input string. 

Move cursor left through input string. 

Delete to end of the input string. 

Move to end of the input string. 

Move to start of the input string. 

Toggle between insertion and overstrike of text. 

Backspace in the input string, deleting the previous character. 

Delete current character. 

Do the search. 

Cancel the search request. 

Try to complete the file name based on the current string. 

The first match is completed, and a window with possible choices is displayed. Subsequent 
presses of TAB will scroll forward through the list of possible matches, and pressing 
SHIFT_TAB will scroll backwards through the list of possible matches. Cursor keys may 
also be used, and so may the mouse. 


File Fdit Position Window Options Help 


abandon.c 
bnddata.c 
clset-c 
dat -c 
dosdir.c 
editmv-c 
expandfn.c 
fcbdmp.c 


Hno_nane | 


-|File Completion List \ 

addstr.c alias.c 

change.c cledit.c 

clsubs.c cmdline.c 

dc.c delete.c 

dotmode.c editdc.c 


error.c 


expr.c 
fcbdup.c 


ex.c 
f cb.c 
fcbems.c 


autosave .c 
clglob.c 

cstatus.c 
dir-c 
edit ins.c 
exappend.c 
fcbblock.c 
fcbmem.c 


command 


18:59 


bind.c 
dread, c 
cut .c 
dirdisp.c 
editmain.c 
exdata.c 
fcbdisk.c 
fcbmerge.c 


/clglob.c 


fc = 


1 C: 


1 "no_name M [new file] line 1 of 1 — 100/ — 


Figure 27. File Name Completion Window 


84 


Command Mode 







Modes 


6.2.6 Inserting Text 

The following commands cause Vi to go from command mode directly into text insertion mode: 

INS Starts inserting text before the current character in the edit buffer. 

a Starts appending (inserting) text after the current character in the edit buffer. 

A Starts appending (inserting) text after the last character on the current line in the edit buffer. 

g Enters text insertion mode at the current cursor position. This sets you up in overstrike or 

insert mode, depending on the mode you were in last time you were in text insertion 
mode. 

This key is useful to keyadd in a script, to return to the exact same type of text insertion 
mode the user was in before leaving text insertion mode. 

i Starts inserting text before the current character in the edit buffer. 

I Starts inserting text before the first non-white space character in the edit buffer. 

o Opens a line after the current line, and enters text insertion mode. 

O Opens a line before the current line, and enters text insertion mode. 

Once you are in text insertion mode, you can toggle back and forth between insert and overstrike using the 
INS key. You exit text insertion mode by pressing the ESC key. See the previous section, "Text Insertion 
Mode" on page 69, for more information on manipulating text in text insertion mode. 

6.2.7 Replacing Text 

The following commands are used to replace text: 

g Enters text insertion mode at the current cursor position. This sets you up in overstrike or 

insert mode, depending on the mode you were in last time you were in text insertion 
mode. 

This key is useful to keyadd in a script, to return to the exact same type of text insertion 
mode the user was in before leaving text insertion mode. 

R Starts overstriking text at the current character in the edit buffer. Once you are overstriking 

text, you can toggle back and forth between overstrike and insert using the INS key. You 
exit text insertion mode by pressing the ESC key. See the previous section, "Text Insertion 
Mode" on page 69, for more information on manipulating text in text insertion mode. 

<n>r<?> Replaces the current character with the next character typed, <?>. If a repeat count is 
specified, then the next <n> characters are replaced with the character <?>. 

Example(s): 

ra 

Replaces the current character with the letter a. 
lOrZ 
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Replaces the next 10 characters with the letter Z. 


6.2.8 Deleting Text 

The commands in this section are for deleting text in an edit buffer. All deleted text is copied into a copy 
buffer for later use, see the section "Copy Buffers" on page 81. 

< "?>D Deletes the characters from the current position to the end of line. 

Example(s): 

"aD 

Deletes characters from current position to the end of line into the named 
buffer a. 


<nx"?>X 

Delete the character before the current cursor position. 

Example(s): 

X 

Delete the previous character. 

10X 

Delete the 10 previous characters. 

"z5X 

Delete the 5 previous characters into the named buffer z. 

<n>< "?>x Delete the character at the current cursor position. 

Example(s): 

x 

Delete the current character. 

3x 

Delete the next 3 characters. 

" 217 x 

Delete the next 17 characters into the numbered buffer 2. 

<nx"?>DEL 

Delete the character at the current cursor position. This behaves the same as the command 
mode command x. 

Example(s): 

DEL 

Delete the current character. 

12DEL 

Delete the next 12 characters. 

"a5DEL 

Delete the next 5 characters into the named buffer a. 
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The <oper> notation in the following command indicates some sort of operator that the command will act 
on. <oper> may be one of: 

1. A movement command. See the section "Movement" on page 72 for a full description of all 
movement commands. If a movement command is specified, then the range that the command 
will act on is from the current position to the position that would be achieved by using the 
movement command. 

2. A search command: 

• / (forward slash) 

• ? (question mark) 

• n 
•N 

See the section "Searching" on page 82 for a full description of the searching commands. If a 
search command is specified, then the range that the command will act on is from the current 
position to the position that would be achieved by using the search command. 

3. The current selected (highlighted) region. In this case, <oper> is the r key. 

4. The same character as the command character. This causes the command to operate on the 
current line. 

<nx"?>d<oper> 

Delete text from the current position in the file to the position specified by <oper>. A copy 
of the text is placed into the specified copy buffer <"?>. If no buffer is specified, then the 
text is placed into the active buffer. A repeat count <n> may precede the command, this 
causes <n> units of the <oper> command to be deleted. 

<oper> may be specified as d, which causes a single line to be deleted. 

Also see the command line command delete. 

Example(s): 

dr 

Deletes the current selected (highlighted) region in the edit buffer. A copy is 
placed into the active copy buffer. 

" zdd 

Deletes the current line. A copy is placed into the named copy buffer z. 
95dd 

Deletes 95 lines, starting at the current. A copy of the lines is placed into the 
active buffer. 

"cdf a 

Deletes the characters from the current column up to and including the first a 
on the current line. A copy of the text is placed in the named buffer c. 

" 5d' a 

Deletes the lines from the current line to the line with mark m into the 
numbered buffer 5. 
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dG 

Deletes all lines from the current line to the end of the current edit buffer. 


6.2.9 Copying Text 

This section describes commands that are for yanking (copying) text. This text is placed into a copy buffer, 
see the section "Copy Buffers" on page 81 for more information. 

<n>Y Yank (copy) the current line. If a repeat count <n> is specified, then <n> lines are copied. 

This command is the same as typing yy. 

The <oper> notation in the following command indicates some sort of operator that the command will act 
on. <oper> may be one of: 

1. A movement command. See the section "Movement" on page 72 for a full description of all 
movement commands. If a movement command is specified, then the range that the command 
will act on is from the current position to the position that would be achieved by using the 
movement command. 

2. A search command: 

• / (forward slash) 

• ? (question mark) 

• n 
•N 

See the section "Searching" on page 82 for a full description of the searching commands. If a 
search command is specified, then the range that the command will act on is from the current 
position to the position that would be achieved by using the search command. 

3. The current selected (highlighted) region. In this case, <oper> is the r key. 

4. The same character as the command character. This causes the command to operate on the 
current line. 

<nx"?>y<oper> 

Yanks (copies) text from the current position in the file to the position specified by <oper>. 
Text is placed into the specified copy buffer <"?>. If no buffer is specified, then the text is 
placed into the active buffer. A repeat count <n> may precede the command, this causes 
<n> units of the <oper> command to be copied. 

<oper> may be specified as y, which causes a single line to be yanked. 

Also see the command line command delete. 

Example(s): 

yy 

Yanks (copies) the current line into the active copy buffer. 
lOyy 

Copies 10 lines, starting at the current, into the active buffer. 
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y$ 

Copies the characters from the current column to the end of the current line 
into the active buffer. 

"ay'm 

Yanks the lines from the current line to the line with mark m into the named 
buffer a. 

y/foo 

Copies: 

• the part of the current line from the current position to the end of the 
line 

• all lines between the current line and the first line containing the string 

foo 

• the part of the line containing foo from the start of the line to the first 
letter in the string foo 


6.2.10 Changing Text 

The following commands are for changing text. If a range of lines is being changed, the lines are deleted 
and Vi enters text insertion mode. 

If the change is taking place on the single line, the range of characters being changed is highlighted, and the 
last character in the range is indicated with a dollar sign (’$’). If the ESC key is pressed, and changelikevi 
is not set, then the change command is cancelled. If changelikevi is set, then the highlighted area is 
deleted. If anything other than the ESC key is pressed, the highlighted area is deleted and Vi enters text 
insertion mode. 

C This command changes the characters on the current line from the current character to the 

end of the line. The character range is highlighted, and once a character is typed, the 
highlighted text is deleted, and text insertion mode is entered. 

This command is the same as typing c$. 

<n>S This command substitutes the current line with text. The text on the current line is deleted, 

and text insertion mode is entered. If a repeat count <n> is specified, then <n> lines are 
deleted. 

This command is the same as typing cc. 

<n>s This command substitutes the current character with text. If <n> is specified, then <n> 

characters are substituted. 

This command is the same as typing cl, cRIGHT, or cSPACE. 

The <oper> notation in the following command indicates some sort of operator that the command will act 
on. <oper> may be one of: 

1. A movement command. See the section "Movement" on page 72 for a full description of all 
movement commands. If a movement command is specified, then the range that the command 
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will act on is from the current position to the position that would be achieved by using the 
movement command. 

2. A search command: 

• / (forward slash) 

• ? (question mark) 

• n 
•N 

See the section "Searching" on page 82 for a full description of the searching commands. If a 
search command is specified, then the range that the command will act on is from the current 
position to the position that would be achieved by using the search command. 

3. The current selected (highlighted) region. In this case, <oper> is the r key. 

4. The same character as the command character. This causes the command to operate on the 
current line. 

<n>c<oper> 

Change text from the current position in the file to the position specified by <oper>. A 
repeat count <n> may precede the command, this causes <n> units of the <oper> 
command to be changed. 

<oper> may be specified as c, which causes a single line to be changed. 

Example(s): 

cr 

Changes the current selected (highlighted) region in the edit buffer. 


cc 

Change the current line. The current line is deleted, and text insertion mode 
is entered. 

95cc 

Changes 95 lines, starting at the current. The lines are deleted, and text 
insertion mode is entered. 


cw 

Change the current word. The current word is highlighted, and once a 
character other than ESC is typed, the word is deleted and text insertion 
mode is entered. 


c$ 

Changes from the current column to the end of the current line. The column 
range is highlighted, and once a character other than ESC is typed, the 
column range is deleted and text insertion mode is entered. 

2cf a 

Changes from the current column to the second letter a on the current line. 
The column range is highlighted, and once a character other than ESC is 
typed, the column range is deleted and text insertion mode is entered. 
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6.2.11 Shifting Text 

The following commands are used to shift lines to the right or left, inserting or deleting leading whitespace. 
The <oper> notation in the following commands indicates some sort of operator that the command will act 
on. <oper> may be one of: 

1. A movement command. See the section "Movement" on page 72 for a full description of all 
movement commands. If a movement command is specified, then the range that the command 
will act on is from the current position to the position that would be achieved by using the 
movement command. 

2. A search command: 

• / (forward slash) 

• ? (question mark) 

• n 
•N 

See the section "Searching" on page 82 for a full description of the searching commands. If a 
search command is specified, then the range that the command will act on is from the current 
position to the position that would be achieved by using the search command. 

3. The current selected (highlighted) region. In this case, <oper> is the r key. 

4. The same character as the command character. This causes the command to operate on the 
current line. 

<n»<oper> (right angle bracket) 

This is the shift right command. It shifts the specified lines to the right shiftwidth spaces, 
inserting necessary leading tabs if realtabs is specified. 

A repeat count <n> may precede the command, this causes <n> units of the <oper> 
command to be shifted to the right. 

<oper> may be specified as >, which causes a single line to be shifted to the right. 

Also see the command line command >. 

Example(s): 

10 » 

Shifts the current line and the next 9 lines to the right shiftwidth spaces. 

>' a 

Shifts all lines from the current line to the line with mark a to the right 
shiftwidth spaces. 


Shifts all lines in the selected (highlighted) region to the right shiftwidth 
spaces. 

<n>«oper> (left angle bracket) 

This is the shift left command. It shifts the specified lines to the left shiftwidth spaces. 
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A repeat count <n> may precede the command, this causes <n> units of the <oper> 
command to be shifted to the left shiftwidth spaces. 

<oper> may be specified as <, which causes a single line to be shifted to the left shiftwidth 
spaces. 

Also see the command line command <. 

Example(s): 

<< 

Shifts the current line to the left shiftwidth spaces. 


<G 

Shifts all lines from the current line to the last line in the edit buffer to the 
left shiftwidth spaces. 

10<j 

Shifts the current line and the next 10 lines to the left shiftwidth spaces. 


6.2.12 Case Toggling 

The case toggle command mode command switches upper case letters to lower case, and lower case letters 
to upper case. An example of its behaviour is changing the line 

This Is A Line Of Text. 


to 


tHIS iS a 1INE oF tEXT. 

The <oper> notation in the following command indicates some sort of operator that the command will act 
on. <oper> may be one of: 

1. A movement command. See the section "Movement" on page 72 for a full description of all 
movement commands. If a movement command is specified, then the range that the command 
will act on is from the current position to the position that would be achieved by using the 
movement command. 

2. A search command: 

• / (forward slash) 

• ? (question mark) 

• n 

•N 

See the section "Searching" on page 82 for a full description of the searching commands. If a 
search command is specified, then the range that the command will act on is from the current 
position to the position that would be achieved by using the search command. 

3. The current selected (highlighted) region. In this case, <oper> is the r key. 

4. The same character as the command character. This causes the command to operate on the 
current line. 
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<n>~<oper> (tilde) 

This is the case toggle command. This command only works if the togglecaselikevi setting 
is not turned on. If togglecaselikevi is set, then pressing ~ only changes the case of the 
current character, and advances the cursor to the next character. 

However, if togglecaselikevi is not set, then this command toggles the case of the 
characters over the range specified by <oper> 

A repeat count <n> may precede the command, this causes <n> units of the <oper> 
command to be case toggled. 

<oper> may be specified as ~, which causes a single line to be have its case toggled. 

Example(s): 

~r 

Toggles the case of the currently selected (highlighted) range. 


Toggles the case of all characters from the current column of the current line 
to the last character of the current line. 


~w 

Toggles the case of the current word. 

10 ~~ 

Toggles the case of the current line and the 9 lines following. 


6.2.13 Filters 

The command mode filter command has the same functionality as the command line command filter. The 
<oper> notation in the following command indicates some sort of operator that the command will act on. 
<oper> may be one of: 

1. A movement command. See the section "Movement" on page 72 for a full description of all 
movement commands. If a movement command is specified, then the range that the command 
will act on is from the current position to the position that would be achieved by using the 
movement command. 

2. A search command: 

• / (forward slash) 

• ? (question mark) 

• n 

•N 

See the section "Searching" on page 82 for a full description of the searching commands. If a 
search command is specified, then the range that the command will act on is from the current 
position to the position that would be achieved by using the search command. 

3. The current selected (highlighted) region. In this case, <oper> is the r key. 

4. The same character as the command character. This causes the command to operate on the 
current line. 
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<n>!<oper> (exclamation mark) 

Filter text. The line range specified by <oper> are run through a specified filter. A repeat 
count <n> may precede the command, this causes <n> units of the <oper> command to be 
run through the filter. 

<oper> may be specified as !, which causes a single line to be run through the filter. 


The lines specified are run through a specified system command (filter). Once the filter 
range has been specified, a window is displayed, prompting for a system command: 


File Edit Position Window Options Help 

\ C:\Data\programsNow test\helloc.c |- 


connand 


19:27 


ttinclude <stdio.h> 


int main<int argc, char *-*argu> 

< 

int count; 

printf <"He llo world?\nArguments were :\n”>; 
for (count = 0; count < argc; count++> 
printf < M xs\n M , argv[count]); 
return 0; 

> 


Command: 


fc = 


1 C: 


1 ''C:\Data\programsNow testNhelloc.c" line 1 of 10 


Figure 28. Filter System Command Prompt 


The system command must take input from standard in and put its output to standard out. 
The lines specified are replaced with the output of the the command. 

There is a filter command history in the filter command prompt, the size of which is 
controlled with the maxfilterhistory setting. 

Also see the command line command !. 


Example(s): 

! r 

Runs the current selected (highlighted) region in the edit buffer through a 
specified filter. 


I | 

Runs the current line through a specified filter 


Runs all lines from the current line to the end of the edit buffer through a 
specified filter. 


6.2.14 Text Selection 

Text may be selected with the mouse. However, if you do not wish to use the mouse, there is a keyboard 
interface to allow you to accomplish the same thing. 
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Once text selection has been started, any movement command adds to the selected region. The selected 
region may be cleared, and text selection ended, by pressing the ESC key. 


A selected region is highlighted by exchanging the foreground and background the colors of the line. A 
selected region could look as follows: 


File Hdit Position Window Options Help 

HC:\Data\programs\ow test\helloc.c |- 


command 


19:27 


I ttinclude <stdio.h> 


int main<int argc, char **argv> 

l< 

int count; 

printf ("Hello world?NnArguments were:\n">; 

for (count = 0; count ( argc; count++> 
printf ("xs\n", argu [count ]> ; 



8 C: 


44 No such column 


Figure 29. Selected Text Region 


The following are the command mode commands for selecting text and manipulating selected text. 
CTRL_R Starts text selection, if no text is selected. The current character is highlighted. 


If region is already selected, then cancel the selected region. 


<n>SHIFT_UP 

Starts selection (if not already started) and moves up to the previous line. The previous line 
and the current line are selected. If a repeat count <n> is specified, then the cursor moves 
up <n> lines, and all the lines between the starting and ending position are selected. 

<n>SHIFT_DOWN 

Starts selection (if not already started) and moves down to the next line. The next line and 
the current line are selected. If a repeat count <n> is specified, then the cursor moves down 
<n> lines, and all the lines between the starting and ending position are selected. 

<n>SHIFT_LEFT 

Starts selection (if not already started) and move left to the previous character. The current 
character and the previous character are selected. If a repeat count <n> is specified, then 
the cursor moves left <n> characters, and all the characters between the starting and ending 
position are selected. 

<n> SHIFT_RIGFIT 

Starts selection (if not already started) and move right to the next character. The current 
character and the next character are selected. If a repeat count <n> is specified, then the 
cursor moves right <n> characters, and all the characters between the starting and ending 
position are selected. 

<"?>SHIFT_DEL 

Deletes the currently selected region. If the copy buffer <"?> is specified, the region is 
copied into that buffer, otherwise the data is copied into the active buffer. 
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_ (underscore) 

Simulates the right mouse being clicked at the current cursor position. If a region is not 
selected, then the current word will be selected. The word is defined using the command 
line command word. 

6.2.15 Miscellaneous Keys 

CTRLjC Exits the editor if no files have been modified. If files have been modified, a prompt is 

displayed asking you to verify that you really want to discard the modified file(s). If you 
do not respond with a ’y’, then the command is cancelled. 

Also see the command line command quitall. 

CTRLjG Display information about the current file in the edit window. The information includes: 

• the file name. 

• a special indicator if the file is read-only. 

• a special indicator if the file is view-only. 

• a special indicator if the file has been modified. 

• the current line number, and the last line number. 

• The percentage of the way through the file. 

Some sample results are: 

"test.c" [modified] line 5 of 100 — 5% — 

"..\c\file.c" [read only] line 100 of 100 - 100% - 
"\autoexec.bat" line 1 of 100 — 1% — 

CTRL_L Redraws the current screen. 

CTRL_V Displays the current version of Vi in the message window. 

Also see the command line command version. 

CTRL_X Displays the hex value (and the decimal value) of the current character. A sample of the 

output in the message window is: 

Char 'e': 0x65 (101) 

CTRL_] (control right square bracket) 

Go to the tag given by the current word. The word is defined using the command line 
command word. 

Also see the command line command tag. 

See the appendix "CTAGS" on page 219 for more information. 

ALT_W Activates the current edit window’s menu. This menu is defined using the 

windowgadgetmenu menu. See the chapter "Windows and Menus" on page 135 for more 
information on setting this menu. 
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ALT_X Insert a character, at the current cursor position. When ALT_X is pressed, a prompt is 

displayed: 



Figure 30. Character Insertion Prompt 


Enter either a decimal or a hex number. That character will be inserted directly into the 
edit buffer. 


: (colon) Allows entry of a command line. See the chapter "Editor Commands" on page 101 for full 

details on command line commands. 


@<?> (at sign) 

This command executes the copy buffer <?>. Vi behaves as if the contents of the buffer 
were being typed at the keyboard. 

<n>J loins the next line to the current line. If a repeat count <n> is specified, the next <n> lines 

are joined to the current line, (lines are concatenated one after another). 

Also see the command line command join. 

Example(s): 

J 

Joins the next line to the current line. 

3 J 

Joins the next 3 lines to the current line. 

Q Enters EX mode. EX mode is a line-oriented mode of Vi. To exit EX mode, use the 

visual command. 

Z<Z> Used when you are finished with the current edit buffer. If the current edit buffer has been 

modified, it is saved. 

Example(s): 

zz 

Finished with current edit buffer. 

<n>z<?> Reorients the current screen position. The current line moves as follows, depending on the 
value of <?>: 
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FI 


F2 


Fll 


F12 


. (dot) 


= (equals sign) 


ENTER Moves the current line to the top of the screen. 

. (dot) Moves the current line to the center of the screen. 

- (dash) Moves the current line to the bottom of the screen. 

If a repeat count <n> is specified, then <n> is made the current line. 

Example(s): 

z— 

Move the current line to the bottom of the screen. 

IOOzENTER 

Makes line 100 the current line, and puts line 100 at the top of the screen. 
25z . 

Makes line 25 the current line, and puts line 25 at the center of the screen. 
Move forward through the file list to the next file. 

Also see the command line command next. 

Move backwards through the file list to the previous file. 

Also see the command line command prev. 

Push the current file and position. If you press F12, you will be restored to this position. 
These positions are stacked up, up to a maximum of maxpush. 

Also see the command line command push. 

Restore the last pushed file and position. 

Also see the command line command pop. 

Repeat the last command mode command that changed text in the edit buffer. It is also 
possible to memorize more than just one command for by using memorize mode: 

1. Type " m.". (Vi enters memorize mode). 

2. Enter keystrokes. 

3. Type " 

Now, whenever you press dot all the entered keystrokes will be executed. 

Performs the last alternate memorized command sequence. The alternate memorize mode 
is used as follows: 

1. Type " m=". (Vi enters alternate memorize mode). 

2. Enter keystrokes. 
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3. Type " =" 

Now, whenever you press the equals sign (’=’), all the entered keystrokes will be executed 
as if you typed them again from the keyboard. 

This memorized keystroke sequence will last until you memorize another, unlike using " m. 

it 

ALT_M Display current memory state. Shows the total amount of memory, the amount of memory 

for use by Vi, and how much extended memory and/or disk space is available. 
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7 Editor Commands 


This chapter describes the various editor commands that may be entered. A command is entered by 
pressing the colon key while in command mode, or by selecting the Enter command option in the File 
menu. 


To ensure that you are in command mode, press ESC until the mode indicator says 


Mode: command 


Once you press the key, the command entry window will appear: 



Figure 31. Command Entry Window 


This position and size of the command entry window are controlled using the commandwindow 
windowing command (character mode versions of the editor only). Commands may be up to 512 bytes in 
length; the command window scrolls. 


There are a special set of commands that may be entered at the command line for controlling the various 
windows and menus of Vi. These commands are discussed in the next chapter, "Windows and Menus" on 
page 135. 


The command line has a command history associated with it; the size of this command history is controlled 
using the maxclhistory setting. As well, the command history is preserved across sessions of Vi if the 
historyfile parameter is set. 

If a command is being executed through a mapped key (see the map and mapbase commands later in this 
chapter), then it can be useful to keep the command from being added to the history. By having a "\h" as 
the first characters after the character, the command will not be added to the command history. 
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7.1 Special Keys In The Command Window 

Once in the command window, a number of keys have special meaning: 

CTRL_V Insert next keystroke directly; do not process as a special character. 

CTRL_Q Insert next keystroke directly; do not process as a special character. 

CTRL_0 Insert the current input string after current line in the edit buffer. 

ALT_0 Insert the current input string before current line in the edit buffer. 

ALT_L Adds the current line in the current edit buffer, from the current column to the end of the 

line, to the input string. 

CTRL_E Adds the current space delimited word in the current edit buffer to the input string. 

CTRL_L Adds the current line in the current edit buffer to the input string. 

CTRL_R Adds the currently selected column range in the current edit buffer to the input string. 

CTRL_W Adds the current word in the current edit buffer to the input string. 

CTRL_INS Restores last thing typed in the input window (one level undo). 

UP Scroll backwards through the history. 

DOWN Scroll forwards through the history. 

ALTJTAB Command completion. Looks backwards through the history for first item starting with 
what is already entered. Subsequent presses of ALT_TAB get the 2nd last matching item, 
and so on. 

RIGHT Move cursor right through input string. 

LEFT Move cursor left through input string. 

CTRL_END Delete to end of the input string. 

END Move to end of the input string. 

HOME Move to start of the input string. 

INSERT Toggle between insertion and overstrike of text. 

BS Backspace in the input string, deleting the previous character. 

DELETE Delete current character. 

ENTER Process the command. 

ESC Cancel the command. 
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TAB Try to complete the file name based on the current string. 


The first match is completed, and a window with possible choices is displayed. Subsequent 
presses of TAB will scroll forward through the list of possible matches, and pressing 
SHIFT_TAB will scroll backwards through the list of possible matches. Cursor keys may 
also be used, and so may the mouse. 



Figure 32. File Name Completion Window 


7.2 Line Addresses 


Some commands take a line address range and/or a line address. A line address is composed of a line 
number or a special symbol. As well, ’+’ and may be used to add or subtract from the current address; 
e.g.: 


5+7 

100-5 

99-11+6 


Indicates line 13 
indicates line 95 
indicates line 94 


Special symbols are: 

. (dot) Represents the current line number. 

5 (dollar) Represents the last line number. 

% (percent) Represents the address range 1,$ (the entire file) 

# (pound) Represents the current selected region 

’a (front quote) Indicates the line with the mark ’a’ set; marks ’a’ through ’z’ may be used. 
/regexp/ 


?regexp? 


Indicates the first line following the current line that has the regular expression regexp. If 
regexp is not specified, then the last regular expression search is used. 

Indicates the first line previous to the current line that has the regular expression regexp. If 
regexp is not specified, then the last regular expression search is used. 
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For more information on regular expressions, see the chapter "Regular Expressions" on page 167. 

If a line address is not specified, then the current line is assumed. If + or - are the first character, then they 
are assumed to operate on the current line number; e.g. specifying +1 takes you forward one line in the file. 

A line address range is two line addresses separated by a comma; these indicate the start and end of the line 
address range. 

7.2.1 Line Address Examples 

.-5 5 lines before the current line 

1,5 lines 1 to 5. 

.-10,.+10 10 lines before the current line to 10 lines past the current line 

$-5 5 lines before the last line in the file 

% all lines 

# all lines in the currently selected region 

’a,. line with mark ’a’ to current line. 

/foo/ the first line after the current line containing ’foo’ 

’z+5,$-10 5 lines past line with mark ’z’ to 10 lines before the end of the file. 

/foo/+5,/bar/-l 5 lines past line next line containing 'foo’ to 1 line before the line containing 'bar'. 

7.3 Commands 

The following command descriptions show items within angle brackets (<>). The angle brackets are there 
to indicate items that you may supply. You are not required to type the brackets. For example, <filename> 
simply means that in the corresponding place in the command you should enter the name of a file. For 
example, <filename> may be replaced with 

test.c 

and the brackets are not entered. 

The command descriptions also show items inside double quotes ("). The double quotes are used to 
indicate a literal option that you may supply. You are not required to type the quotes. For example, "-c" 
indicates that in the corresponding place in the command you may enter -c. 

In the syntax model for each command, the upper-case characters represent the minimal truncation of the 
command. For example, in its syntax model, the edit command is specified as "Edit", indicating that the 
"e", "ed", "edi", and "edit" are acceptable abbreviations (and that "e" is the shortest of them). 


104 Commands 




Editor Commands 


Some commands are noted as "EX mode only". This means that the command is not available front the 
normal command line; it may only be used from an editor script or from EX mode (which is entered by 
pressing ’Q’ in command mode). 


7.3.1 > 

Syntax: <line_range> > 

Description: This command shifts the specified line range <line_range> to the right shiftwidth spaces, 

inserting necessary leading tabs if realtabs is specified. 

Example(s): 

1, • > 

Shifts from first line to current line to the right shiftwidth spaces. 

See Also: < 

7.3.2 < 

Syntax: <line_range> < 

Description: This command shifts the specified line range <line_range> to the left shiftwidth spaces. 

Example(s): 

Shifts entire file shiftwidth spaces to the left. 

See Also: > 

7.3.3! 

Syntax: <line_range> ! <cmd> 

Description: If <line_range> is specified, then the lines are run through the specified system command 

<cmd> (the command must get its input from standard in and write its output to standard 
out) and replaces the lines with the output of the command. 

If no range is specified, then the system command <cmd> is run. If <cmd> is not 
specified, then an operating system shell is started. 

The global variable %(Sysrc) contains the return code from the last system command, and 
%(Syserr) contains the errno value. 

Example(s): 

1,$ ! sort 

Takes all lines in the current edit buffer and runs them through the sort command. The lines 
are then replaced with the output of the sort command. 

! dir 

Executes the system dir command. After dir is finished executing, you are prompted to 
press a key before returning to the editor. 
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Temporarily leaves Vi and enters an operating system command shell. 

See Also: shell 

7.3.4 ABBREV 

Syntax: ABbrev <short> <long> 

Description: Create an abbreviation of <short> for <long>. Whenever <short> is typed as a word 

during text insertion mode, it is expanded to <long>. unabbrev is used to remove the 
abbreviation. 

Example(s): 

abbrev wh while( 

Whenever wh is entered as a word, the word while( is substituted. 

See Also: unabbrev 

7.3.5 ALIAS 

Syntax: ALias <alias> <data> 

Description: Creates an command line alias of <alias> for <data>. Whenever <alias> is typed on the 

command line, the full command <data> is substituted, unalias is used to remove the 
abbreviation. 

Example(s): 

alias ai set autoindent 

Whenever ai is entered on the command line, the command set autoindent is executed. 

See Also: unalias 

7.3.6 APPEND 

Syntax: <line_num> Append 

Description: Appends source lines after line <line_num>. Append is terminated when a line with 

nothing but a dot (’.’) is entered. 

Notes: Only valid in EX mode. 

See Also: change, insert 

7.3.7 CASCADE 

Syntax: CASCADE 

Description: Causes all edit buffer windows to cascade (overlap each other with top border of each 

visible). 
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See Also: maximize, minimize, movewin, resize, size, tile 

7.3.8 CD 

Syntax: CD <dir> 

Description: Changes current working directory to <dir>. If <dir> is not specified, then the current 

directory is displayed in the message window. <dir> may be specified with drive and path. 

Example(s): 

cd c:\tmp 

Changes to the \tmp directory of the c drive 
cd 

Display the current working directory 

7.3.9 CHANGE 

Syntax: <line_range> Change 

Description: Deletes the line range , and replaces the range with inputted source lines. The input of text 

is terminated when a line with nothing on it but a dot (’.’) is entered. 

Notes: Only valid in EX mode. 

See Also: append, insert 

7.3.10 COMPILE 

Syntax: COMPile "-a" "-A" <script> <result> 

Description: Compiles the editor script <script>. 

If -a is specified, all local variables are translated at compile time (rather than at run time) - 
this is useful for the configuration script. 

If -A is specified, all variables (both local and global) are translated at compile time. 

The file will be compiled into a file with the same name as the script and the extension 
._vi., unless <result> is specified. 

For information on editor scripts, see the chapter "Editor Script Language" on page 177. 

Example(s): 

comp -a ed.cfg 

Compiles the default configuration script ed.cfg and expands all local variables to any 
values assigned to them in the script. The compiled script file edvi is generated. 

If any errors occur while compiling, a file with the the same name as the script and the 
extension .err is created. 
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comp test.vi test.out 

Compiles the script test. vi and generates the compiled script file test. out. 

See Also: load, source 

7.3.11 COMPRESS 

Syntax: COMpress 

Description: Replaces spaces in the current edit buffer with tabs. Single spaces are not replaced with a 

tab, and spaces inside a quoted string are not replaced with a tab. 

7.3.12 COPY 

Syntax: <line_range> COpy <line_number> 

Description: Copies the specified range of lines <line_range> after the line <line_number>. 

Example(s): 

% copy $ 

Copies the entire file and places the lines after the last line in the file. 

1,. copy . 

Copies all lines from the beginning of the file to the current line and places the lines after the 
current line. 

7.3.13 DATE 

Syntax: DAte 

Description: Display the current time and date in the message window. 

7.3.14 DELETE 

Syntax: <line_range> Delete <buffer> 

Description: Deletes the specified line range <line_range>. 

If <buffer> is not specified, the text is deleted into the active copy buffer. 

If <buffer> (’l’-’9\ or ’a’-’z’) is specified, the text is deleted into that copy buffer. 

The put command may be used to place contents of a copy buffer into the file. 

Example(s): 

% d 

Deletes all lines into the active copy buffer. 

1,10 da 

Deletes lines 1 to 10 into the named copy buffer a. 
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See Also: move, put, yank 

7.3.15 ECHO 

Syntax: ECHO <line> <msg> 

Description: Echos the message <msg> on line <line> of the message window. 

If <line> is specified as off, then nothing is echoed into the message window from then on. 

If <line> is specified as on, messages will start to appear in the message window again. 

<msg> may be surrounded by double quotes (") or a forward slash (/) if it contains any 
spaces. 

Example(s): 

echo 1 "hello world" 

The words hello world will appear on line 1 of the message window, 
echo off 

Disables output to the message window, 
echo on 

Enables output to the message window, 
echo 2 /Line 2 message/ 

The words Line 2 message will appear on line 2 of the message window. 

7.3.16 EDIT 

Syntax: Edit"!" <files> 

Description: Edits the specified files <files>. <files> may be a single file or a list of files. 

Each file name may contain file regular expressions, see the section "File Matching Regular 
Expressions" on page 169 in the chapter "Regular Expressions" for more information. 

If "!" is specified, then the current file is discarded before editing the new file(s). 

If a file is already being edited, then control is simply transferred to the window with that 
file. If the file is already being edited and you specified a different path, then a new copy 
of the file is read from the disk and is edited, unless samefilecheck is set. If samefilecheck 
is set, then control is transferred to the window with the original copy of the file. 

If you wish to have have multiple views on the same file, the open command is available. 

If <files> is not specified, then a window containing a list of files in the current directory is 
opened. From this listing, you may pick a file, another directory, or another drive (the 
available drives are at the end of the listing). A directory is indicated by the leading 
backslash (’V). If a directory is chosen in this window, then the list of files in that directory 
is displayed. This list also contains all the drives available (which are enclosed in square 
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brackets, e.g. [c:]). If you select a drive, the list of files in the current directory on that 
drive is displayed. 


For files and directories, each line indicates the file name, the various attributes of the file 
([directory, [a]rchive, [h]idden, [s]ystem, [r]eadable, [w]riteable, executable), the file 
size in bytes, the date and time of the last file update. Some sample lines are: 


test.c 

-a—rw- 

25586 

08/16/92 

08:14 

bar. c 

-a—r— 

639 

02/27/92 

13:25 

\tmpdir 

d-rw- 

0 

08/16/92 

19:05 


[c: ] 

Example(s): 

edit test.c 

Edits the file test.c. 

edit! test2.c 

Discards the current file, and edits test2.c. 


edit test.(c|h) 

Edits the file test.c if it exists, and the file test.h if it exists, 
edit ([a-c])*.c 

Edits all files in the current directory that start with the letters a, b or c and have the extension 
.c. 

edit * 

Edits all files in the current directory, 
edit 

Gives a file selection display: 


File Edit Position Window Options Help command 14:34 

-|no_name |- 1 





H C: \Dat a\Pro grams\o w\bld\oi\c 1- 

- 1/151! 

A 



. 

d-rw- 

0 07/07/2005 

15:28 A 

| 



abandon.c 

— a — r — 

2037 

07/07/2005 

15:28 




addstr.c 

-a—r— 

2246 

07/07/2005 

15:28 




alias.c 

-a—r— 

5812 

07/07/2005 

15:28 




autosave. 

c -a—r— 

14558 

07/07/2005 

15:28 




bind.c 

-a — r — 

49434 

07/07/2005 

15:28 




bnddata.c 

-a — r — 

7174 

07/07/2005 

15:28 




change.c 

-a — r — 

2320 

07/07/2005 

15:28 




cledit -c 

-a — r — 

14618 

07/07/2005 

15:28 




clglob.c 

-a — r — 

8514 

07/07/2005 

15:28 




clread.c 

-a — r — 

4135 

07/07/2005 

15:28 




clset.c 

-a — r — 

36043 

07/07/2005 

15:28 




cIsubs.c 

-a — r — 

13137 

07/07/2005 

15:28 




cmdline-c 

-a — r — 

38355 

07/07/2005 

15:28 




cstatus.c 

-a — r — 

3431 

07/07/2005 

15:28 V 

_ i 













▼ 



1 C: 

1 'no_name 

[new file] 

line 1 of 

1 — 100/ - 

- 



Figure 33. File Selection Display 


See Also: open, read, view, visual 
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7.3.17 EGREP 

Syntax: EGRep <regexp> <files> 

Description: Searches the file list <files> for the regular expression <regexp>. 

<regexp> may be surrounded by double quotes (") or a forward slash (V) if it contains any 
spaces. 

<files> may be a single file, a directory, or a list of files. <files> may contain file regular 
expressions, see the section "File Matching Regular Expressions" on page 169 in the 
chapter "Regular Expressions" for more information. 

If <files> is not specified, it defaults to the setting of grepdefault. If a directory is 
specified for <files>, then the files in that directory are searched, based on the setting of 

grepdefault. 

When all matches are found, a selection window is presented with all the files that 
contained <regexp>. 

If you are not using regular expressions, the fgrep command is much faster. For more 
information on regular expressions, see the chapter "Regular Expressions" on page 167. 

Example(s): 

egrep ((if)|(while)) *.c 

Searches all files in the current directory ending in the extension .c for the regular expression 

((if)l(while)). 

egrep [a-z]a+ 

Searches all files specified by grepdefault for the regular expression [a-z]a+. 
egrep [a-z]a+ ..\c 

Searches all files in the directory .Ac specified by grepdefault for the regular expression 

[a-z]a+. 

See Also: fgrep 

7.3.18 EVAL 

Syntax: EVAL <expr> 

Description: Evalutes a given mathematical expression, and displays the result on line 1 of the message 

window. For a full explanation of the rules for formulating the expression <expr>, see the 
chapter "Editor Script Language" on page 177. 

Example(s): 

eval 5+7*3 

Evaluates 5+7*3 and displays the result (26) in the message window, 
eval (5+7)*3 

Evaluates (5+7)*3 and displays the result (36) in the message window, 
eval ( (12 + 3)*100)/50-3 
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Evaluates ((12+3)*100)/50-3 and displays the result (27) in the message window. 


7.3.19 EXECUTE 


Syntax: EXECUTE <str> 

Description: Execute the string <str>. This causes the editor to behave as if the string <str> was typed 

at the keyboard. 

Special keys in the string are indicated as follows: 

\<"key"> Any special key may be inserted for "key". The angle brackets are 
required. There are a number of pre-defmed keys symbols that are 
recognized. These are described in the Appendix "Symbolic Keystrokes" 
on page 221. 

\e Short form for the escape key (rather than \<ESC>). 

V; Short form for the enter key (rather than \<ENTER>). 

Vi If a command line command is used in the sequence, and it follows the 

colon (’:’), the command is not added to the history. For example: 

: \hdate\n 

will display the current date and time, but the command will not enter the 
command history. 

Vr If a command line command is used in the sequence, then this stops the 

command window from opening. This prevents the "flashing" of the 
command window as it is opened then closed. For example: 

\x:date\n 

will display the current date and time, but the command window will not be 
displayed. 


Example(s): 

execute dd 

Acts as if dd were typed, and the current line gets deleted. 


execute :eval 5*3\n 

Acts as if :eval 5*3<ENTER> was typed, and the number 15 gets displayed in the message 
window. 

See Also: keyadd, map, mapbase 
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7.3.20 EXITALL 

Syntax: EXITALL 

Description: Exits all files. Lor each file that has been modified, you are prompted as to whether you 

want to save the file or not. 

See Also: quitall 

7.3.21 EXPAND 

Syntax: EXPAND 

Description: Replaces all tabs in the current edit buffer with spaces. 


7.3.22 FGREP 

Syntax: LGRep "-c" "-u" <string> <files> 

Description: Searches the file list <files> for the string <string>. 

The search is by default case insensitive, unless -c is specified, which forces the search to 
be case sensitive. Specifying -u causes the setting of caseignore to determine whether or 
not to be case sensitive in the search. 

<string> may be surrounded by double quotes (") or a forward slash (/) if it contains any 
spaces. 

<files> may be a single file or a list of files. Each file name may contain file regular 
expressions, see the section "File Matching Regular Expressions" on page 169 in the 
chapter "Regular Expressions" for more information. 

If <files> is not specified, it defaults to the setting of grepdefault. 

While searching for the item, Vi displays a window that shows all files being searched. 
When all matches are found, a selection window is presented with all the files that 
contained <files>. 


Example(s): 

fgrep window *.c 

Searches all files in the current directory ending in the extension .c for the string window. 
This will produce out similar to the following: 
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7.3.23 FILES 


Syntax: Files 

Description: Opens a window with the a list of all files current being edited. Files that have been 

modified will have a beside them. A file may be selected from this list either with the 
keyboard or with the mouse. 


Example(s): 

files 

Displays following screen 
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7.3.24 FLOATMENU 

Syntax: FLOATMENU <id> <slen> <xl> <yl> 

Description: Activates the floating (popup) menu <id> ( <id> may be 0, 1, 2 or 3). 

The floating menus are defined using the command line command menu (See the section 
"Menu Commands" on page 142 ). 

<xl>, <yl> specify the coordinates of the upper left hand corner of the floating menu. 

(0,0) specifies the upper left hand corner of the screen. 

<slen> defines the length of a string that the menu is around the floating menu will try to 
appear around the string ( <id> may be 0). This is useful if you wish to pop up a menu 
around some selected characters on a line, for example. 

If <slen> is non-zero, then the coordinates is assumed to be the lower right-hand side of the 
string that the menu is popping up around. 

Example(s): 

float 0 0 10 10 

Bring up floating menu 0 at location (10,10) on the screen. There is no string, so the menu 
position will simply cycle around (10,10) in an attempt to position itself. 

float 0 6 50 20 

Bring up floating menu 0 at location (50,20) on the screen. This is assumed to be on the 
lower right hand side of a string of length 5 (i.e., it is assumed that the string is on line 19 and 
starts at column 45). If the menu cannot fit by opening at (50,20), it will try to open at all 
other corners of the string. 

See Also: menu, input, get 

7.3.25 GENCONFIG 

Syntax: GENCONFIG <filename> 

Description: Writes the current editor configuration out to the file <filename>. If <filename> is not 

specified, then the file name "ed.cfg" is assumed. 

7.3.26 GLOBAL 

Syntax: <line_range> Global /<regexp>/ <cmd> 

Description: For each line in the range <line_range> that matches the regular expression <regexp>, the 

editor command <cmd> is executed. <cmd> may contain replacement expressions, see the 
chapter "Regular Expressions" on page 167 for more information. 

If "!" is specified, then the command <cmd> is executed on every line that does NOT 
match the regular expression <regexp>. 

If <line_range> is not specified, then the global command operates on the entire line range 
of the current edit buffer. 
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Example(s): 

g/printf/d 

Deletes all lines in the current edit buffer that have the word printf. 
g!/[a-c]123/ d 

Deletes all lines in the current edit buffer that DO not match the regular expression [a-c]123. 
g/ (abc)*/ execute Iabc\e 

For every line that matches the regular expression (abc)*, execute the keystrokes 
Iabc<ESC> (this will insert the characters abc at the start of the line). 

See Also: substitute 

7.3.27 HELP 

Syntax: HELP <topic> 

Description: Starts a view-only edit buffer on help for a specified topic. Possible topics are: 

COMmandline All command line commands. 

KEYS What different keystrokes do in command mode. 

REGularexpressions 

How to use regular expressions. 

SETtings Everything that can be modified with the set command line command. 

SCRipts Vi script guide. 

STARTing How to start the editor: switches, required files. 

Example(s): 

help com 

Gives help on command line commands, 
help 

Gives list of help topics. 

7.3.28 INSERT 

Syntax: <line_number> Insert 

Description: Inserts text after a the specified line number <line_number>. Insert is terminated when a 

line with nothing but a is entered. 

Notes: Only valid in EX mode. 

See Also: append, change 
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7.3.29 JOIN 

Syntax: 

Description: 

Example(s): 

• r 

7.3.30 KEY ADD 

Syntax: 

Description: 


<line_range> Join 

Joins the lines in the specified range <line_range> into a single line (lines are concatenated 
one after another). 


.+2 join 

Joins the current line and the next 2 lines into a single line. 


KEY Add <string> 

Adds a set of keystrokes <string> to the key buffer just as if they were typed by the user. 
The processing of these keystrokes is deferred until Vi finishes its current processing, and 
is ready to process keystrokes again. This is different than the execute command, which 
processes the keystrokes immediately. 

Keyadd is useful in a script, because it allows keystrokes to be executed after the script is 
exited. This prevents re-entrance of a script that is being executed by a mapped key in 
input mode, for example. 

Keys are processed in FIFO order. Multiple keyadd commands cause more keys to queue 
up for processing. 

If you need to use one or more special keys (e.g. ENTER, FI, etc) in <string>, they may 
specified as follows: 

\<"key"> Any special key may be inserted for "key". The angle brackets are 
required. There are a number of pre-defined keys symbols that are 
recognized. These are described in the Appendix "Symbolic Keystrokes" 
on page 221. 

\e Short form for the escape key (rather than \<ESC>). 

\n Short form for the enter key (rather than \<ENTER>). 

V; If a command line command is used in the sequence, and it follows the 

colon (’:’), the command is not added to the history. For example: 

:\hdate\n 

will display the current date and time, but the command will not enter the 
command history. 

\x If a command line command is used in the sequence, then this stops the 

command window from opening. This prevents the "flashing" of the 
command window as it is opened then closed. For example: 

\x:date\n 
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will display the current date and time, but the command window will not be 
displayed. 

Example(s): 

keyadd dd 

Acts as if dd were typed, and the current line gets deleted, 
keyadd :eval 5*3\n 

Acts as if :eval 5*3<ENTER> was typed, and the number 15 gets displayed in the message 
window. 

See Also: execute, map, mapbase 

7.3.31 LIST 

Syntax: <line_range> List 

Description: Lists lines in the specified line range. 

Notes: Only valid in EX mode. 

7.3.32 LOAD 

Syntax: LOAD <script> 

Description: Loads a script into memory for the life of the edit session. This allows for much faster 

access to the script, since the data structures for the script do not have to be built every time 
the script is invoked. This is especially important for a hook script. 

For information on editor scripts, see the chapter "Editor Script Language" on page 177. 

Example(s): 

load rdme._vi 

Loads the script rdme vi and makes it resident. 

See Also: compile, source 

7.3.33 MAP 

Syntax: MAP "!" <key> <string> 

Description: Tells the editor to run the string of keys <string> whenver the key <key> is pressed in 

command mode. 

If "!" is specified, then the string of keys <string> is executed whenever <key> is pressed 
in text insertion mode. 

When a mapped key is pressed, it acts is if the characters in <string> are being typed at the 
keyboard. Recursion does not occur; if a key that is mapped is executed after it has been 
executed as a mapped key, then the default behaviour for that key is used, e.g.: 
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map a Oa 

will cause the editor to move to column 1, and then start appending after the character in 
column 1. 

If you need to specify a special key (e.g. ENTER, FI, etc) in <key>, you specify a 
symbolic name for that key. There are a number of pre-defined keys symbols that are 
recognized when specifying which key is being mapped/unmapped. These are described in 
the Appendix "Symbolic Keystrokes" on page 221. 

If you need to use one or more special keys (e.g. ENTER, FI, etc) in <string>, then you 
may enter: 

\<"key"> Any special key may be inserted for "key". The angle brackets are 
required. There are a number of pre-defined keys symbols that are 
recognized. These are described in the Appendix "Symbolic Keystrokes" 
on page 221. 

\e Short form for the escape key (rather than \<ESC>). 

\n Short form for the enter key (rather than \<ENTER>). 

\h If a command line command is used in the sequence, and it follows the 

colon (’:’), the command is not added to the history. For example: 

:\hdate\n 

will display the current date and time, but the command will not enter the 
command history. 

Vr If a command line command is used in the sequence, then this stops the 

command window from opening. This prevents the "flashing" of the 
command window as it is opened then closed. For example: 

\x:date\n 

will display the current date and time, but the command window will not be 
displayed. 

To remove a mapping, use the unmap command. 


Example(s): 

map K \x:next\n 

Whenever K is pressed in command mode, the next command is executed. The command 
window will not be displayed, because of the \x. 

map CTRL_ T \x:\hda\n 

Whenever CTRL_T is pressed in command mode, the current date is displayed. The 
command window will not be displayed, because of the \x. The command will not be added 
to the command history, because of the \h. 

map CTRL_ W \x:fgrep \<CTRL_ W>\n 
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Whenever CTRL_W is pressed in command mode, an fgrep command, searching for the 
current word, is executed. The \x keeps the command window from opening. \<CTRL_W> 
simulates CTRL_W being pressed, so the current word is inserted into the command line. 

map! CTRL_ W \edwi 

Whenever CTRL_W is pressed in text insertion mode, text insertion mode is exited (\e 
simulates the ESC key being pressed), the current word is deleted, and text insertion mode is 
re-entered. This has the effect of deleting the current word in text insertion mode and 
appearing to remain in text insertion mode. 

See Also: execute, keyadd. unmap 

7.3.34 MAPBASE 

Syntax: MAPBASE <key> <string> 

Description: Tells the editor to run the string of keys whenver the key <string> is pressed in command 

mode. 

This works the same as the map command, only all characters in <string> work as their 
base meaning that is, all key mappings are ignored and the keys have their default 
behaviour. 

See Also: execute, keyadd. map, unmap 

7.3.35 MARK 

Syntax: <line_number> MArk <markname> 

Description: Sets the text mark <markname> on the line <line_number>. The mark name is a single 

letter from a to z. This mark may then be referred to on the command line or in command 
mode by using a front quote (’) before the mark name, e.g.: 

'a 

Example(s): 

mark a 

Sets the mark a on the current line. Typing the command ’a will return you to that mark. 

100 mark z 

Sets the mark z on line 100. 

7.3.36 MATCH 

Syntax: match/<rxl>/<rx2>/ 

Description: Set what is matched by the ’%’ command mode command. Defaults are and 

For example, by pressing the percent key (’%’) when the cursor is on the first open bracket 
(’(’) in the line: 

if ( ( i=foo( x ) ) ) return; 
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moves the cursor to the last ’)’ in the line. 

This command allows you to extend what is matched to general regular expressions. <rxl> 
is the regular expression that opens a match, <rx2> is the regular expression that closes a 
match. 

Note that in the matching regular expressions, magic is set (special characters 
automatically have their meaning, and do not need to be escaped). 

For more information on regular expressions, see the chapter "Regular Expressions" on 
page 167. 


Example(s): 

match /# *if/# *endif/ 

This adds the matching of all #if and #endif commands (an arbitrary number of spaces is 
allowed to occur between the '#' sign and the if or endif words. Ifis pressed while over 
a #if statement, the cursor is moved to the corresponding #endif statement. 


7.3.37 MAXIMIZE 

Syntax: MAXimize 

Description: Maximizes the current edit buffer window. 

See Also: cascade, minimize, movewin, resize, size, tile 


7.3.38 MINIMIZE 

Syntax: MINimize 

Description: Minimizes the current edit buffer window. 

See Also: cascade, maximize, movewin, resize, size, tile 


7.3.39 MOVE 

Syntax: <line_range> Move <line_number> 

Description: Deletes the specified range of lines <line_range> and places them after the line 

<line_number>. 


Example(s): 

1,10 move $ 

Moves the first 10 lines of the file after the last line in the file. 


1,. move .+1 

Deletes all lines from the beginning of the file to the current line and places the lines one line 
after the current line. 


See Also: delete 
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7.3.40 MOVEWIN 


Syntax: MOVEWin 

Description: Enter window movement mode. The cursor keys are then used to move the current edit 

buffer window. 

See Also: cascade, maximize, minimize, resize, size, tile 


7.3.41 NEXT 

Syntax: Next 

Description: Moves to the next file in the list of files being edited. 

See Also: prev 

7.3.42 OPEN 

Syntax: Open <file> 

Description: Opens a new window on the specified file. If no file is specified, then a new window is 

opened on the current edit buffer. These new windows are different views on the same edit 
buffer. 

Once multiple views on an edit buffer are opened, the window border contains a number 
indicating which view of the edit buffer is associated with that file: 


File Edit Position Window Options 
i tags -c [13 1- 


Help 


command 


23:07 


FindTag - locate a given tag 
V 

int FindTag< char *tag > 

< 

extern char _NEAR METRE]; 
int rc,omag; 

char *oldms; 


omag = EditFlags-Magic; 
EditFlags-Magic = FALSE; 
oldms = Majick; 

Majick = &META[3]; 


rc = ColorFind< tag, 0 >; 


Majick = oldms; 
EditFlags.Magic = omag; 
return< rc >; 


> FindTag 


A /* 

*■ TagHunt — hunt for a specified tag 






int TagHunt< char *str > 


1 


char 

int 


buff [MAX_STR], file [FI® 
nun,rc =ERR_NO_ERR; 


I 


I 


rc = LocateTag< str, file, buff >; 
if< ?rc > < 


I 


s 


PushFileStackO; 
rc = EditFile< file, FALSE >; 
if < rc == ERR_NO_ERR > < 
if< buff[01 != ’/’ > < 
nun = atoi< buff >; 
rc = GoToLineNoRelCurS 
> else < 

rc = FindTagC buff >; 
if< rc < 0 > < 

strcpy< buff, str| 


L: 101 C: 


1 "tags.c" [read only] line 1 of 333 — 0x — 


Figure 36. Two views of the same file 


See Also: edit, view, visual 
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7.3.43 POP 

Syntax: POP 

Description: Restores the last pushed file position. 

The setting maxpush controls the maximum number of push commands that will be 
remembered. 

See Also: push, tag 

7.3.44 PREV 

Syntax: Prev 

Description: Moves to the previous file in the list of files being edited. 

See Also: next 

7.3.45 PUSH 

Syntax: PUSH 

Description: Saves the current file position. The next pop command will cause a return to this position. 

The setting maxpush controls the maximum number of push commands that will be 
remembered. 

The tag command does an implicit push. 

See Also: pop, tag 

7.3.46 PUT 

Syntax: <line_number> PUt <buffer> 

Description: Puts (pastes) the copy buffer <buffer> (’l’-’9\ or ’a’-’z’) after the line <line_number>. 

If <buffer> is not specified, the active copy buffer is assumed. 

If "!" is specified, then the lines are put before the line <line_number>. 

Example(s): 

put 

Pastes the active copy buffer after the current line. 

1 put! 

Pastes the active copy buffer before the first line in the edit buffer. 

$ put a 

Pastes named copy buffer a after the last line in the file. 


Commands 123 




The Open Watcom Vi Editor Reference 


put! 4 

Pastes numbered copy buffer before the current line. 

See Also: delete, yank 

7.3.47 QUIT 

Syntax: Quit”!" 

Description: Quits the current file. Quit will not quit a modified file, unless "!" is specified, in which 

case all changes are discarded and the file is exited. 

Example(s): 

q! 

Quits the current file, discarding all modifications since the last write. 

See Also: write, wq, xit 


7.3.48 QUITALL 

Syntax: 

Description: 


QUIT All 

Exits the editor if no files have been modified. If files have been modified, a prompt is 
displayed asking to you verify that you really want to discard the modified file(s). If you 
do not respond with a ’y’, then the command is cancelled. 


Example(s): 

quitall 

If files have been modified, the following prompt is displayed: 


File Edit Position Uindow Options Help 

-|no_pame | 

this is test text 


command 19:03 




"no_name" has been modified — save changes (yes!no Scancel)? 


1 C: 17 "nojiame" [modified] line 1 of 1 — 100X — 


Figure 37. Really Exit prompt 
See Also: exitall 
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7.3.49 READ 

Syntax: <line_number> Read <file_name> 

Description: Reads the text front file <file_name> into the current edit buffer. The lines are placed after 

line specified by <line_number>. If <line_number> is not specified, the current line is 
assumed. 

Line 0 may be specified as <line_number> in order to read a file in before the first line of 
the current edit buffer. 

Each file name <file_name> may contain file regular expressions, see the section "File 
Matching Regular Expressions" on page 169 in the chapter "Regular Expressions" for more 
information. 

If <file_name> is not specified, then a window containing a list of files in the current 
directory is opened, from which a file may be selected. 

If the first character of <file_name> is a dollar sign (’$’), then this indicates that a directory 
is to be read in. If nothing follows, then the current directory is read. Otherwise, all 
characters that follow the dollar sign are treated as a file regular expression, which is used 
to read in the directory. 

Example(s): 

0 read test.c 

Reads the file test.c into the current edit buffer and places the text before the first line of the 


r test.c 

Reads the file test.c into the current edit buffer and places the text after the current line, 
r $ 

Reads the current directory and places the data after the current line. 

r $* . c 

Reads the current directory, matching only files with .c extensions, and places the data after 
the current line. 

r $..\c\*.* 

Reads the .Ac directory, and places the data after the current line, 
read 

Gives a file selection display: 
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Figure 38. File Selection display 

7.3.50 RESIZE 

Syntax: RESize 

Description: Allows resizing of the current edit window with the keyboard. The cursor keys are used as 

follows: 

UP move top border up 

DOWN move top border down 

LEFT move right border left 

RIGHT move right border right 

SHIFTJUP move bottom border up 
SHIFT_DOWN move bottom border down 
SHIFT_LEFT move left border left 
SHIFT_RIGHT move left border right 
See Also: cascade, maximize, minimize, movewin, size, tile 


7.3.51 SET 

Syntax: SEt <variable> <value> 

Description: Certain variables within Vi may be changed after Vi is executing. <value> is assigned to 

<variable>. 


If <variable> and <value> are not specified, the a window containing a list of all boolean 
values is displayed. 
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If <variable> is specified as a 2, then a window containing all other values is displayed. 

From the selection window, a variable may be selected (with ENTER or double clicking the 
mouse), and a new value entered. If the variable was boolean, then pressing ENTER or 
double clicking toggles the value. 

If a variable is a boolean variable, then it is be set via 

set var - set var to TRUE 

set novar - set var to FALSE 

Variables other than boolean variables are set via 

set var = test - set var to 'test' 
set var test - set var to 'test' 

Note that the ’=’ operator is optional. 

For information on all the different settable options, see the chapter "Editor Settings" on 
page 147. 


7.3.52 SETCOLOR 


Syntax: SETCOLOR <c> <r> <g> <b> 

Description: Set the color number <c> to have the RGB value <r>, <g>, <b>. <c> may have a value of 

0 to 15. <c>, <r>, and <g> may have values from 0 to 63. 

This command only has an affect under operating systems where it is possible to remap the 
colors in some way (DOS). 


Example(s): 

setcolor 1 63 0 38 

This remaps color number 1 to a pink color. 

setcolor 15 25 40 38 

This remaps color number 15 to a pale green color. 


7.3.53 SHELL 

Syntax: SHell 

Description: Escapes to an operating system shell. 

See Also: ! 

7.3.54 SIZE 

Syntax: SIZE <xl> <yl> <x2> <y2> 

Description: Resizes the current edit buffer window to have upper left-hand corner at ( <xl>, <yl>) and 

lower right-hand corner at ( <x2>, <y2>). 
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Example(s): 

SIZE 0 0 10 10 

Changes the size of the current edit buffer window to have upper left-hand corner at (0,0) and 
lower right-hand corner at (10,10). 

See Also: cascade, maximize, minimize, movewin, resize, tile 

7.3.55 SOURCE 

Syntax: SOurce <script> <pl> <p2> ... <pn> 

Description: Execute Vi source script file <script>. Optional parameters <pl> to <pn> may be 

specified, these are passed to the specified script. 

If is specified as the script name, the current file being edited is run as a script. 

For information on editor scripts, see the chapter "Editor Script Language" on page 177. 

Example(s): 

source foo.vi abc 

Executes the script foo.vi, passing it the parm abc. 
source . 

Executes the current edit buffer as a script. 

See Also: compile, load 

7.3.56 SUBSTITUTE 

Syntax: <line_range> Substitute /<regexp>/<replexp>/<gxi> 

Description: Over the line range <line_range>, replace each occurrence of regular expression <regexp> 

with the replacement expression <replexp>. 

Only the first occurrence on each line is replaced, unless <g> is specified, in which case all 
occurrences on a line are replaced. 

If <i> is specified, each replacement is verified before it is performed. 

See the chapter "Regular Expressions" on page 167 for more information on regular 
expression matching and substitution. 

Example(s): 

%s/foo/bar/ 

Changes the first occurrence of foo to bar on each line of the entire file. 

1, .s/(([a-z]be)*)/Abc\2/g 

Changes all occurrences of the regular expression (([a-z]bc)*) to the substitution expression 
Abc\2. The changes are only applied on lines 1 to the current line of the current edit buffer. 

'a,'b/ A abc//i 
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Any line that starts with abc has the abc changed to the null string. The user is prompted 
before each change. The changes are only applied from the line containing mark a to the line 
containing mark b. 

See Also: global 

7.3.57 TAG 

Syntax: TAG <tagname> 

Description: Searches for the tag <tagname>. Tags are kept in a special file, which must be located 

somewhere in your path. This file is controlled with the tagfilename setting; the default 
for this setting is tags. The tags file contains a collection of procedure names and typedefs, 
along with the file in which they are located and a search command/line number with which 
to exactly locate the tag. 

See the appendix "CTAGS" on page 219 for more information. 

Example(s): 

tag MyFunc 

Locates the tag MyFunc in the tags file, edits the source file that contains the function 
MyFunc, and moves the cursor to the definition of the function in the source file. 

7.3.58 TILE 

Syntax: TILE "h" I "v" I <x> <y> 

Description: Tile all current file windows. The tiling layout is specified as an <x> by <y> grid. The or 

bars (T) in the command syntax indicate that only one of the options may be used. 

If no parameters are specified, maxwindowtilex and maxwindowtiley are used (this is the 
default tile grid). 

If "h" is specified, then files are tiled horizontally (as many as will fit). 

If "v" is specified, then files are tiled vertically (as many as will fit). 

Specifying <x> <y> overrides the default tile grid. As a special case, specifying <x> <y> 
as 1 1 causes all windows to be restored. 

Example(s): 

tile 3 5 

Tile windows 3 across and 5 high. 

tile 1 1 

Untile windows. 

tile h 

Tile windows horizontally, 
tile 

Tile windows according to default tile grid. 
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See Also: cascade, maximize, minimize, resize, size, movewin 

7.3.59 UNABBREV 

Syntax: UNABbrev <abbrev> 

Description: Removes the abbreviation <abbrev>. See the abbrev command for how to set an 

abbreviation. 

Example(s): 

unabbrev wh 

Remove the abbreviation wh. 

See Also: abbrev 

7.3.60 UNALIAS 

Syntax: UNALias <alias> 

Description: Removes the command line alias <alias>. See the alias command for how to set a 

command line alias. 

Example(s): 

unalias ai 

Remove the command line alias ai. 

See Also: alias 

7.3.61 UNDO (command) 

Syntax: Undo "!" 

Description: Undo the last change. There is no limit on the number of undo’s that can be saved, except 

for memory. Continuing to issue undo commands walks you backwards through your edit 
history. 

Specifying "!" undoes the last undo (redo). Again, there are no restrictions on this. 
However, once you modify the file, you can longer undo the last undo. 

7.3.62 UNMAP 

Syntax: UNMAP "!" <key> 

Description: Removes the mapping of the key <key> for command mode. If "!" is specified, then the 

key mapping is removed for text insertion mode. See the map command for details on 
mapping keys. 

There are a number of pre-defined symbols that are recognized for "!". These are 
described in the Appendix "Symbolic Keystrokes" on page 221. 
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Example(s): 

unmap CTRL_ W 

Removes the mapping of CTRL_W for command mode. Pressing CTRL_W in command 
mode will now do the default action. 

unmap! FI 

Removes the mapping of FI for text insertion mode. Typing FI in text insertion mode will 
now do the default action. 

See Also: map, mapbase 

7.3.63 VERSION 

Syntax: VERsion 

Description: Displays the current version of Vi in the message window. 


7.3.64 VIEW 

Syntax: VIEw "!" <file_name> 

Description: Functions the same as the edit command, except that it causes the file edited to be a "view 

only" file (no modification commands work). 

Example(s): 

view test.c 

Edits the file test.c in view-only mode. 

See Also: edit, open, visual 


7.3.65 VISUAL 

Syntax: Visual <file_name> 

Description: Causes Vi to re-enter visual mode (full screen editing mode) if Vi is in EX mode. If the 

filename <file_name> is specified, this functions just like the edit command. 

Example(s): 

vi test.c 

Return to full screen editing mode (if in EX mode) and edit the file test.c 
vi 

Return to full screen editing mode (if in EX mode). 

See Also: edit, open, view 
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7.3.66 WRITE 

Syntax: <line_range> Write <file_name> 

Description: Writes the specified range of lines <line_range> to the file <file_name>. 

If no line range is specified, then all lines are written. 

If <file_name> is not specified, then the current file is written. If <file_name> exists, and 
is not the name of the file that you are writing, then the write will fail. 

Specifying "!" forces an overwrite of an existing file. 

Example(s): 

1,10 w! test.c 

Write the first 10 lines of the current file to the file test.c, and overwrite test.c if it already 
exists. 

w 

Write out the current file. 

See Also: quit, wq, xit 

7.3.67 WQ 

Syntax: WQ 

Description: Writes current file, and exits. 

See Also: quit, write, xit 

7.3.68 YANK 

Syntax: <line_range> Yank <buffer> 

Description: Y ank (make a copy of) the specified line range <line_range>. 

If <buffer> is not specified, the text is yanked (copied) into the active copy buffer. 

If <buffer> (’l’-’9\ or ’a’-’z’) is specified, the text is yanked into that copy buffer. 

The put command may be used to place the contents of a copy buffer into the file. 

Example(s): 

% y 

Yanks (copies) all lines into the active copy buffer. 

., $ y z 

Yanks the lines from the current line to the last line in the file into the copy buffer z. 

See Also: delete, put 
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7.3.69 XIT 

Syntax: Xit 

Description: Exits the current file, saving it if it has been modified. 

See Also: quit, write, wq 
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8 Windows and Menus 


This chapter describes the command line commands devoted to configuring the Open Watcom Vi Editor’s 
windows and menus. All windows are fully configurable: dimension, colors, existence of borders. The 
menus are fully configurable: all menu topics and menu items are user settable. 

A window is configured first by specifying a window. Once the a window is specified, a number of 
properties may be set. These properties are described in the following section. 

8.1 Window Properties 

Some of the following command line commands accept colors as parameters. These colors may be 
numbers in the range 0 through 15. As well, Vi has symbolic names for these colors, they are: 

• black 

• blue 

• green 

• cyan 

• red 

• magenta 

• brown 

• white 

• dark_gray 

• light_blue 

• light_green 

• light_cyan 

• light_red 

• light_magenta 

• yellow 

• bright_white 


8.1.1 BORDER 

Syntax: BORDER <hasbord> <fg_clr> <bg_clr> 

Description: This command specifies the type of border and its colors. 

<hasbord> describes the type of border: if <hasbord> is set to -1, there is no border, if 
<hasbord> is set to 1, there is a border. 

<fg_clr> is used to specify the foreground color of the border (0-15). It is ignored for 
<hasbord> of -1. 

<bg_clr> is used to specify the background color of the border (0-15). It is ignored for 
<hasbord> of -1. 
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Example(s): 

border -1 

The currently selected window has no border, 
border 1 yellow black 

The currently selected window has a yellow border with a black background. 

8.1.2 DIMENSION 

Syntax: DIMENSION <xl> <yl> <x2> <y2> 

Description: ( <xl>, <yl>) specifies the coordinates of the upper left-hand corner of the window, and ( 

<x2>, <y2>) specifies the coordinates of the lower right-hand corner of the window. 

Open Watcom Vi Editor editor automatically senses the number of lines and columns 
available. The global variables %(SW) (screen width) and %(SH) (screen height) are 
always set. These are useful for coding dimensions that are relative to the size of the 
screen. All parameters may be coded as expressions. 

All coordinates are 0-based. The top left corner of the screen is (0,0). The bottom right 
corner of the screen is (%(SW)-1,%(SH)-1). 

Example(s): 

dimension 0 1 %(SW)-1 % (SH)—3 

Makes the currently selected window the full width of the screen. Its y dimensions are from 
the second line of the screen and to the third last line of the screen. 

dimension %(SW)-10 5 %(SW)-1 10 

Makes the currently selected window’s x dimension start at the tenth column from the right 
of the screen and end at the rightmost column of the screen. Its y dimensions range from the 
fifth line to the tenth line of the screen. 

8.1.3 ENDWINDOW 

Syntax: ENDWindow 

Description: Ends entry of properties for the currently selected window. The currently selected window 

is then redrawn with the new properties, if it was previously visible. 

8.1.4 HILIGHT 

Syntax: HILIGHT <fg_clr> <bg_clr> 

Description: <fg_clr> sets the foreground color and <bg_clr> sets the background color of highlighted 

text in the currently selected window. 

Example(s): 

hilight bright_ white black 

Sets the highlighted color of the currently selected window to be bright white text with a 
black background. 
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8.1.5 TEXT 


Syntax: TEXT <fg_clr> <bg_clr> 

Description: <bg_clr> sets the foreground color and sets the background color of text in the currently 

selected window. 

Example(s): 

text white black 

Sets the text color of the currently selected window to be white text with a black background. 

8.2 Window Types 

This section describes all possible windows that may be selected. These command line commands select 
the window to start setting properties. See the previous section for properties that may be set. 


8.2.1 COMMAND WINDO W 

Syntax: COMMANDWindow 

Description: This is the window that is displayed whenever Open Watcom Vi Editor is prompting for a 

command line, a search string, a filter command or any other command or data. 


8.2.2 COUNTWINDOW 


Syntax: COUNTWindow 

Description: Window that opens when repeat counts are entered. This window is disabled if repeatinfo 

is not set. 


8.2.3 DEFAULTWINDOW 

Syntax: DEFAULTWindow 

Description: When the defaultwindow is selected, all windows get the properties that are set. Note that 

this is best defined first to provide the default behaviour, and all other windows that you 
want to be different from the default can be specified after. 


8.2.4 D IRWIN DOW 


Syntax: DIRWindow 

Description: This is the window that you select a file from whenever no file is specified from the 

command line commands edit or read. 
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8.2.5 EDITWINDOW 


Syntax: EDITWindow 

Description: This is the window that files are edited from. 


8.2.6 EXTRAINFOWINDOW 

Syntax: EXTRAINFOWindow 

Description: This window contains extra information about possible things that may be done. It is 

displayed when selecting results from the command line commands fgrep, egrep, and files. 


8.2.7 FILEWINDOW 


Syntax: FILEWindow 

Description: The window in which list of files currently being edited is displayed. This is displayed 

when the command line command files is executed. 


8.2.8 FILECWINDOW 


Syntax: FILECWindow 

Description: This window contains list of possible file choices when file completion cannot match one 

specific file. It is displayed whenever the TAB key is pressed in a command window. 


8.2.9 LINENUMBER WIN DO W 

Syntax: LINENUMBERWindow 

Description: This is the window that line numbers are displayed in. The dimension of this window is 

ignored, the absolute position of the window is decided by the position of the edit window 
that it is associated with. 

This window is disabled if linenumbers is not set. 


8.2.10 MENUWINDOW 


Syntax: MENUWindow 

Description: This sets the properties of the windows that open whenever a menu is activated. Any 

dimension given with this window is ignored; the position of each menu is variable. 
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8.2.11 MENUBARWINDOW 

Syntax: MENUBARWindow 

Description: This window is the menu bar. This is where all menus set up with the command line menu 

are displayed. 


8.2.12 MESSAGEWINDOW 

Syntax: MESSAGEWindow 

Description: The window in which all all editor feedback is reported. The hilight color is the color that 

errors are reported in. 

This window needs to have two lines in order to view Open Watcom Vi Editor feedback; 
however, very few messages use two lines, so you can get by with a message window that 
is only one line high. 


8.2.13 SETWINDOW 


Syntax: SETWindow 

Description: The window in which Open Watcom Vi Editor settings are displayed. This window is 

displayed when the command line set command is entered without parameters or with 2 as 
its only parameter. 


8.2.14 SETVALWINDOW 

Syntax: SETVALWindow 

Description: The window in which the new value of an editor setting is entered. This window is 

displayed if a value change is requested after entering the command line set with 2 as the 
parameter. 


8.2.15 STATUSWINDOW 

Syntax: STATUSWindow 

Description: This is the window where the current line and column are reported. The current line 

number is displayed in the first line of the window, and the current column is displayed in 
the second line of the window. This window is disabled if statusinfo is not set. 
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8.3 Sample Window Settings 

The following examples are sample settings of the different types of windows. These commands may be 

issued from the command line one at at time, or may be executed from a Open Watcom Vi Editor script. 

Typically, these commands will be found in the Open Watcom Vi Editor configuration script. 

Commandwindow: 

commandwindow 

dimension 2 %(SH)-7 %(SW)-3 %(SH)-5 
text %(white) %(blud) 0 
border 171 

hilight %(highwhite) %(cyan) 1 
endwindow 

Countwindow: 

countwindow 

dimension 28 %(SH)-5 43 %(SH)-3 
border 171 
text %(white) %(blue) 0 
hilight %(highwhite) %(cyan) 1 
endwindow 

Dirwindow: 

dirwindow 

dimension 15 2 %(SW)-12 %(SH)-7 
border 171 
text %(white) %(blue) 0 
hilight %(highwhite) %(cyan) 1 
endwindow 

Editwindow: 

editwindow 

dimension 0 1 %(SW)-1 %(SH)-2 
border 1 %(white) %(black) 
text %(white) %(black) 0 
hilight %(yellow) %(blue) 0 
whitespace %(white) %(black) 0 
selection %(yellow) %(blue) 0 
eoftext %(white) %(black) 0 
keyword %(highwhite) %(black) 0 
octal %(cyan) %(black) 0 
hex %(cyan) %(black) 0 
integer %(cyan) %(black) 0 
char %(cyan) %(black) 0 
preprocessor %(yellow) %(black) 0 
symbol %(white) %(black) 0 
invalidtext %(yellow) %(black) 0 
identifier %(white) %(black) 0 
jumplabel %(cyan) %(black) 0 
comment %(lightcyan) %(black) 0 
float %(cyan) %(black) 0 
string %(cyan) %(black) 0 
endwindow 
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Extrainfowindow: 

extrainfowindow 

dimension 0 1 %(SW)-1 %(SH)-3 
border 171 
text %(white) %(blue) 0 
hilight %(purple) %(cyan) 1 
endwindow 

Filecwindow: 

filecwindow 

dimension 4 7 %(SW)-5 %(SH)-9 
border 171 
text %(white) %(blue) 0 
hilight %(highwhite) %(cyan) 1 
endwindow 

File window: 

filewindow 

dimension 26 2 %(SW)-2 %(SH)-7 
border 171 
text %(white) %(blue) 0 
hilight %(highwhite) %(cyan) 1 
endwindow 

Messagewindow: 

messagewindow 

dimension 18 %(SH)-1 %(SW)-1 %(SH)-1 
border -1 

text %(white) %(blue) 0 
hilight %(yellow) %(blue) 1 
endwindow 

Menuwindow: 

menuwindow 

dimension 0 1 %(SW)-1 %(SH)-3 
border 1 14 1 

text %(highwhite) %(blue) 0 
hilight %(yellow) %(blue) 1 
endwindow 

Menubarwindow: 

menubarwindow 

dimension 0 0 %(SW)-1 0 
border -1 

text %(highwhite) %(blue) 0 
hilight %(yellow) %(blue) 1 
endwindow 

Setvalwindow: 
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setvalwindow 

dimension 46 6 %(SW)-7 9 
border 171 
text %(white) %(blue) 0 
hilight %(highwhite) %(cyan) 1 
endwindow 

Set window: 

setwindow 

dimension 12 2 43 %(SH)-4 
border 171 
text %(white) %(blue) 0 
hilight %(highwhite) %(cyan) 1 
endwindow 

Status window: 

statuswindow 

dimension 0 %(SH)-1 17 %(SH)-1 
border -1 

text %(white) %(blue) 0 
hilight %(yellow) %(blue) 1 
endwindow 


8.4 Menu Commands 


Vi menus are set dynamically. Any menu will automatically be added to the menu bar when created, and 
removed when destroyed. There are some reserved menus: 

windowgadget This menu is the one that appears when the upper left hand corner of an edit window is 
clicked. 

float<0-3> These are floating (popup) menus. They are made to appear when the script command 
floatmenu is used. There are 4 floating menus, floatO through float3. 

Menus will attempt to open up where they are told to; however, if the menu cannot fit, then it will try to 
open above the position that it was told to, to the left of the position that it was told to, and above and to the 
left of the position that it was told to. 

The following sections describe each of the command line commands for controlling menus. 


8.4.1 ADDMENUITEM 


Syntax: ADDMENUItem <menuname> <itemname> <cmd> 

Description: Adds a new item to a previously created menu <menuname>. The item <itemname> is 

added to the menu. 

This command is similar to the command line command menuitem, only the menuitem 
command is used when first defining a menu. 
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<menuname> may be a quoted string, if the parameter contains spaces. If <menuname> 
is specified as then a solid bar is displayed in the menu. 

A character in <itemname> preceded with an ’&’ will be the hot key for activating the 
menu, e.g. &Control would have ’C’ as the hot key. 

The command <cmd> may be any Open Watcom Vi Editor command line command, and 
is run whenever the item is selected. 

See Also: menuitem 

8.4.2 DELETEMENU 

Syntax: DELETEMENU <menuname> 

Description: Destroys menu with name <menuname>. 

8.4.3 DELETEMENUITEM 

Syntax: DELETEMENUItem <menuname> <index> 

Description: Deletes item number <index> from menu <menuname>. The item number <index> is 0 

based. 

If <index> is specified as -1, then the last item is removed from the menu. 

8.4.4 ENDMENU 

Syntax: ENDMENU 

Description: Finishes the creation of a new menu. 

See Also: menu 

8.4.5 MENU 

Syntax: MENU <menuname> 

Description: Starts the creation of a new menu <menuname>. If a menu exists with the name already, it 

is destroyed and re-created. A character preceded with an ampersand (’&’) will be the hot 
key for activating the menu, e.g. &Control would have ’C’ as the hot key. 

<menuname> may be a reserved name: windowgadget, floatO, float 1, float2, or float3 

See Also: endmenu, menuitem 
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8.4.6 MENUITEM 


Syntax: MENUITEM <itemname> <cmd> 

Description: Adds the item <itemname> to the last menu started with the menu command. Menu items 

may be added until the command line command endmenu has been issued. 

<itemname> may be a quoted string, if the parameter contains spaces. If <itemname> is 
specified as then a solid bar is displayed in the menu. 

A character in <itemname> preceded with an ampersand (’&’) will be the hot key for 
activating the menu item, e.g. &Exit would have ’E’ as the hot key. 

The command <cmd> may be any Open Watcom Vi Editor command line command, and 
is run whenever the item is selected. 


See Also: addmenuitem, endmenu, menu 


8.5 Sample Menus 

The following examples are sample menu setups. These commands may be issued from the command line 
one at at time, or may be contained in a script and executed in the script. Typically, these commands will 
be found in the Open Watcom Vi Editor configuration script. 

This configures the menu that is popped up whenever the top left-hand corner of an edit window is clicked 
with the mouse. 

menu windowgadget 

menuitem "&Maximize" maximize 
menuitem "M&inimize" minimize 
menuitem "" 

menuitem "&Open another view" open 
menuitem "" 

menuitem "SSave" write 
menuitem "&Save & close" keyadd ZZ 
menuitem "Close &no save" quit! 
menuitem "&Close" quit 
endmenu 

This configures one of the floating (popup) menus. This menu could be displayed whenever a word is 
selected with the mouse. 

menu floatO 


menuitem 

"&Open" 

edit %1 

menuitem 

1! II 


menuitem 

"SChange 

" keyadd cr 

menuitem 

"SDelete 

" keyadd dr 

menuitem 

"&Yank" 

keyadd yr 

menuitem 

II II 


menuitem 

"&Fgrep" 

fgrep "%1" 

menuitem 

"&Tag" tag %1 


endmenu 

This configures a menu bar menu item called File. 
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menu &File 

menuitem "&Open new file ..." edit 
menuitem "&Next file" next 
menuitem "&Read file ..." read 
menuitem "&File list ..." file 
menuitem "" 

menuitem "&Save current file" write 
menuitem "Save Scurrent file & close" wq 
menuitem "" 

menuitem "EnSter command ..." keyadd \<CTRL_ K> 
menuitem "S&ystem" shell 
menuitem "" 

menuitem "E&xit" exitall 
endmenu 

This configures a menu bar menu item called Edit, 
menu &Edit 

menuitem "SDelete region" keyadd \<SHIFT_ DEL> 
menuitem "&Copy (yank) region" keyadd yr 
menuitem "SPaste (put)" put 
menuitem "" 

menuitem "Slnsert Text" keyadd i 
menuitem "&Overstrike Text" keyadd R 
menuitem "" 
menuitem "&Undo" undo 
menuitem "&Redo" undo! 
endmenu 

This configures a menu bar menu item called Position. 

menu SPosition 

menuitem "&Start of file" 1 
menuitem "&End of file" $ 
menuitem "Line Snumber" so lnum._vi 
menuitem "" 

menuitem "S&tart of line" keyadd 0 
menuitem "En&d of line" keyadd $ 
menuitem "" 

menuitem "Search Sforwards" keyadd / 
menuitem "Search Sbackwards" keyadd ? 
menuitem "&Last search" keyadd n 
menuitem "SReverse last search" keyadd N 
endmenu 

This configures a menu bar menu item called Window, 
menu &Window 

menuitem "&Tile windows" tile 
menuitem "SCascade windows" cascade 
menuitem "SReset windows" tile 1 1 
menuwindowlist 
endmenu 

This configures a menu bar menu item called Options. 
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menu SOptions 

menuitem "SSettings ..." set 
endmenu 


This configures a menu bar menu item called Help. 


menu &Help 

menuitem "SCommand Line" help com 
menuitem "&Key Strokes" help keys 
menuitem "SRegular Expressions" help 
menuitem "SScripts" help scr 
menuitem "S&ettings" help set 
menuitem "Starting &Up" help start 
endmenu 


reg 
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This chapter describes the various options that may be controlled using the Open Watcom Vi Editor’s set 
command. Options are typically set in the configuration script however, options are settable at execution 
time as well. 

If you know the option you wish to set, you may just issue the set command directly at the command 
prompt, e.g.: 

set nocaseignore 

set autosaveinterval=10 

A boolean option is set in the following way: 

set autoindent - turns on autoindent 
set noautoindent - turns off autoindent 

Short forms may also be used; for example: 

set ai - turns on autoindent 
set noai - turns off autoindent 

A non-boolean option may be set in the following way: 

set filename=test.c - sets current filename to 'test.c' 
set filename test2.c - sets current filename to 'test2.c' 

Note that the assignment operator ’=’ is optional. 

If you do not know the boolean option you wish to set, you may issue the set command with no option at 
the command prompt, e.g.: 


This will cause a menu of all possible settings to appear. These values may be changed by either cursoring 
to the desired one and pressing enter, or by double clicking on the desired one with the mouse. Boolean 
settings will toggle between TRUE and FALSE. Selecting any other setting will cause a window to pop up, 
displaying the old value and prompting you for the new value. This window may be cancelled by pressing 
the ESC key. 
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Figure 39. Vi Settings Selection list 


When you are finished with the settings menus, you may close the window by pressing the ESC key. 


9.1 Boolean Settings 

The section contains descriptions of the boolean settings. 


9.1.1 autoindent 

Syntax: autoindent [ai] 

Description: In text insertion mode, autoindent causes the cursor to move to start of previous line when a 

new line is started. In command mode, autoindent causes the cursor to go to the first non 
white-space when ENTER is pressed. 


9.1.2 automessageclear 

Syntax: automessageclear [ac] 

Description: Automatically erases the message window when a key is typed in command mode. 


9.1.3 beepflag 

Syntax: beepflag [bf] 

Description: Vi normally beeps when an error is encountered. Setting nobeepflag disables the beeping. 
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9.1.4 caseignore 

Syntax: caseignore [ci] 

Description: Causes all searches to be case insensitive if set. 

9.1.5 changelikevi 

Syntax: changelikevi [cv] 

Description: If set, then the change command behaves like UNIX Vi, i.e. if ESC is pressed when no 

change has been made, the text is deleted. Normally, pressing ESC cancels the change 
without deleting the text. 

9.1.6 cmode 

Syntax: cmode [cm] 

Description: When cmode is set, certain things will happen when you are entering text: 

• After entering a line ending in ’ {’, the next line will be indented a shiftwidth further 
than the current one. 

• After entering a line ending in ’}’, the current line is shifted to match the indentation 
of the line with the matching ’ {’. The cursor will flash for a brief instant on the 
matching ’ {’ if showmatch is set. 

• All lines entered will have trailing white space trimmed off. 

• "case" and "default" statements are shifted to be aligned with switch statements. 

Each file has its own cmode setting; so setting cmode in one file and not in another (during 
the same editing session) will work. 

One thing that is useful is to add the following lines to your read hook script: 

if %E == .c 
set cmode 

else 

set nocmode 
endif 

This will cause cmode to be set if the file has a .c extension, and not to be set for any other 
type of file. 

9.1.7 columninfilestatus 

Syntax: columninfilestatus [cs] 

Description: Causes the current column to be added to file status display (obtained when typing 

CTRL_G). 
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9.1.8 currentstatus 

Syntax: currentstatus [ct] 

Description: Enables the display of the current status on the menu bar. The position on the menu bar is 

controlled with currentstatuscolumn. 

9.1.9 drawtildes 

Syntax: drawtildes [dt] 

Description: If drawtildes is true, then the all lines displayed that do not have any data associated with 

them will have a tilde displayed on the line. If drawtildes is false, then no tidies will 
be displayed and the string fileendstring will be displayed after the last line with data. 

9.1.10 eightbits 

Syntax: eightbits [eb] 

Description: If eightbits is set, then all characters are displayed as normal. If noeightbits is set then 

non-printable ASCII will be displayed as control characters. 

9.1.11 escapemessage 

Syntax: escapemessage [em] 

Description: Display the current file status whenever the ESC key is pressed in command mode. 

9.1.12 extendedmemory 

Syntax: extendedmemory [xm] 

Description: If extendedmemory is set, extended memory is used if it is present (standard extended, 

EMS, XMS). This option applies to the real-mode DOS version of Vi only. 

9.1.13 ignorectrlz 

Syntax: ignorectrlz [iz] 

Description: Normally, a CTRL_Z in a file acts as an end-of-file indicator. Setting ignorectrlz causes Vi 

to treat CTRL_Z as just another character in the file. This option may also be selected 
using the ’-z’ option when invoking Vi. 
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9.1.14 ignoretagcase 

Syntax: ignoretagcase [it] 

Description: When using the "-t" command line option of Vi, the tag that is matched is normally case 

sensitive. Setting ignoretagcase causes the tag matching to be case insensitive. 

9.1.15 magic 

Syntax: magic [ma] 

Description: If magic is set, then all special characters in a regular expression are treated as "magic", and 

must be escaped to be used in an ordinary fashion. If nomagic is set, then any special 
characters in magicstring are NOT treated as magic characters by the regular expression 
handler, and must be escaped to have special meaning. 

Magic characters are: A $.[()|?+*\@ 

9.1.16 pauseonspawnerr 

Syntax: pauseonspawnerr [ps] 

Description: This option, if set, causes Vi to pause after spawning (running a system command) if there 

was an error, even if the system command was spawned from a script. Normally, a 
command spawned from a script does not pause when control returns to the editor. 

9.1.17 quiet 

Syntax: quiet [qu] 

Description: When running in quiet mode, Vi does not update the screen. This is useful when running a 

complex script, so that the activity of the editor is hidden. This option may be selected 
when invoking Vi by using the ’-q’ switch, causing Vi to run in a ’batch mode’. 

9.1.18 quitmovesforward 

Syntax: quitmovesforward [qf] 

Description: If this option is set, then when a file is quit, the next file in the list of files is moved to. 

Otherwise, the previous file in the list of files is moved to. 

9.1.19 readentirefHe 

Syntax: readentirefile [rf] 

Description: If readentirefile is set, then the entire file is read into memory when it is edited. This is the 

default setting. However, if noreadentirefile is set, then the file is only read into memory as 
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it is needed. This option is useful when you only want to look at the first few pages of a 
large file. This option may be selected when invoking Vi by using the ’-n’ switch. 

9.1.20 readonlycheck 

Syntax: readonlycheck [re] 

Description: This option causes Vi to complain about modifications to read-only files every time the file 

is modified. 

9.1.21 realtabs 

Syntax: realtabs [rt] 

Description: If norealtabs is set, then tabs are expanded to spaces when the file is read. 

9.1.22 regsubmagic 

Syntax: regsubmagic [rm] 

Description: If noregsubmagic is set, then escaped characters have no meaning in regular expression 

substitution expressions. 

9.1.23 samefilecheck 

Syntax: samefilecheck [sc] 

Description: Normally, Vi just warns you if you edit a file twice (with a different path). If 

samefilecheck is set, then if you edit a file that is the same as a file already being edited 
(only you specified a different path), then that file will be brought up, rather than a new 
copy being read in. 

9.1.24 saveconfig 

Syntax: saveconfig [sn] 

Description: If this option is set, then the editor’s configuration (fonts, colors, settings, etc) is saved 

when the editor is exited. 

This option is only valid with the GUI versions of the editor. 

9.1.25 saveposition 

Syntax: saveposition [so] 

Description: If this option is set, then the editor’s position and size is saved when the editor is exited, 

and restored the next time the editor is started. 
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This option is only valid with the GUI versions of the editor. 

9.1.26 searchwrap 

Syntax: searchwrap [sw] 

Description: When searching a file, Vi normally wraps around the top or bottom of the file. If 

nosearchwrap is set, then Vi terminates its searches once it reaches the top or bottom of the 

file. 

9.1.27 showmatch 

Syntax: showmatch [sm] 

Description: If showmatch is set, the Vi briefly moves the cursor to a matching ’(’ whenever a ’)’ is 

typed while entering text. Also, the matching ’ {’ is shown if a ’} ’ is typed if cmode is set. 

9.1.28 tagprompt 

Syntax: tagprompt ftp] 

Description: If a more than one instance of a tag is found in the tags file, a list of choices is displayed if 

tagprompt is set. 

9.1.29 undo 

Syntax: undo [un] 

Description: Setting noundo disables Vi’s undo ability. 

9.1.30 verbose 

Syntax: verbose [ve] 

Description: If enabled, this option causes Vi to display extra messages while doing involved 

processing. 

9.1.31 wordwrap 

Syntax: wordwrap [ww] 

Description: If enabled, word movement commands (’wYW’,’b’,’B’) will wrap to the next or previous 

line. 
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9.1.32 wrapbackspace 

Syntax: wrapbackspace [ws] 

Description: If this option is set, pressing backspace while on column one of a line will cause Vi to wrap 

to the end of the previous line (while in text insertion mode ). 

9.1.33 writecrlf 

Syntax: writecrlf [wl] 

Description: Normally, lines are written with carriage return and line feeds at the end of each line. If 

nowritecrlf is set, the lines are written with only a line feed at the end. 

9.1.34 Mouse Control Booleans 

The section contains descriptions of the boolean settings affecting the mouse. 

9.1.34.1 lefthandmouse 

Syntax: lefthandmouse [lm] 

Description: When lefthandmouse is set, the right and left mouse buttons are inverted. 

9.1.34.2 usemouse 

Syntax: usemouse [um] 

Description: This option enables/disables the use of the mouse in Vi. 

9.1.35 Window Control Booleans 

The section contains descriptions of the boolean settings affecting windows. 

9.1.35.1 clock 

Syntax: clock [cl] 

Description: This enables/disables the clock display. The position of the clock is controlled by the 

clockx and clocky set commands. 

9.1.35.2 linenumbers 

Syntax: linenumbers [In] 

Description: This option turns on the line number window. This window is displayed on the left-hand 

side of the edit window by default, unless linenumsonright is set. 
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9.1.35.3 linenumsonright 

Syntax: linenumsonright [lr] 

Description: Setting linenumsonright causes the line number window to appear on the right-hand side of 

the edit window. 

9.1.35.4 marklonglines 

Syntax: marklonglines [ml] 

Description: If this option is set, then any line that exceeds the with of the screen has the last character 

highlighted. If endoflinechar is a non-zero ASCII value, then the last character is 
displayed as that ASCII value. 

9.1.35.5 menus 

Syntax: menus [me] 

Description: This option enables/disables the menu bar. 

9.1.35.6 repeatinfo 

Syntax: repeatinfo [ri] 

Description: Normally, Vi echos the repeat count in the countwindow as it is typed. Setting 

norepeatinfo disables this feature. 

9.1.35.7 spinning 

Syntax: spinning [sp] 

Description: If set, this option enables the busy-spinner. Whenever the editor is busy, a spinner will 

appear. The position of the spinner is controlled using the spinx and the spiny set 
commands. 

9.1.35.8 statusinfo 

Syntax: statusinfo [si] 

Description: If set, this option enables the status info window. This window contains the current line 

and column, and is controlled using the statuswindow window command. 

9.1.35.9 toolbar 

Syntax: toolbar [tb] 

Description: This option enables/disables the toolbar. 

This option is only valid with the GUI versions of the editor. 
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9.1.35.10 windowgadgets 

Syntax: windowgadgets [wg] 

Description: This option enables/disables gadgets on edit session windows. 

9.2 Non-Boolean Settings 

The section contains descriptions of the non-boolean settings. 

9.2.1 autosaveinterval 

Syntax: autosaveinterval <seconds> 

Description: Sets the number of seconds between autosaves of the current file to the backup directory. 

Autosave is disabled if <seconds> is 0. The backup directory is defined using the tmpdir 
parameter. 

9.2.2 commandcursortype 

Syntax: commandcursortype <size> 

Description: Sets the size of the cursor when in command mode. Values for <size> are 0 to 100 (0=full 

size, 100=thin). 

9.2.3 endoflinechar 

Syntax: endoflinechar <ascii_val> 

Description: If marklonglines is set, and <ascii_val> is non-zero, then the character in the last column 

of a line wider than the screen is displayed as the ASCII value <ascii_val>. 

9.2.4 exitattr 

Syntax: exitattr <attr> 

Description: Defines the attribute to be assigned to the screen when Vi is exited. The attribute is 

composed of a foreground and a background color, (16 * background + foreground gives 
<attr>). The default is 7 (white text, black background). 

This option is only valid with the character mode versions of the editor. 
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9.2.5 fileendstring 

Syntax: fileendstring <string> 

Description: If drawtildes is false, then the character string <string> will be displayed after the last line 

with data. 


9.2.6 grepdefault 

Syntax: grepdefault <rexexp> 

Description: Default files to search when using the fgrep or egrep commands. <rexexp> is a file 

matching regular expression, the default is *.(clh) For more information, see the section 
"File Matching Regular Expressions" on page 169. 


9.2.7 hardtab 

Syntax: hardtab <dist> 

Description: This controls the distance between tabs when a file is displayed. The default is 8 (4 on 

QNX). 


9.2.8 history file 

Syntax: historyfile <fname> 

Description: If the history file is defined, your command and search history is saved across editing 

sessions in the file <fname>. 


9.2.9 insertcursortype 

Syntax: insertcursortype <size> 

Description: Sets the size of the cursor when inserting text in text insertion mode. Values for <size> are 

0 to 100 (0=full size, 100=thin). 


9.2.10 magicstring 

Syntax: magicstring <str> 

Description: If magic is not set, then the characters specified in <str> are NOT treated as magic 

characters by the regular expression handler, and must be escaped to have special meaning. 

Magic characters are: ' s $.[()|? + *\@ 
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9.2.11 maxclhistory 

Syntax: maxclhistory <numcmds> 

Description: Vi keeps a history of commands entered at the command line. <numcmds> sets the number 

of commands kept in the history. 

9.2.12 maxemsk 

Syntax: maxemsk <kbytes> 

Description: Sets the maximum number of kilobytes of EMS memory to be used by Vi (DOS real-mode 

version only). 

This option can only be set during editor initialization. 

9.2.13 maxfilterhistory 

Syntax: maxfilterhistory <numfiltercmds> 

Description: Vi keeps a history of the filter commands entered. <numfiltercmds> sets the number of 

filter commands kept in the history. 

9.2.14 maxfindhistory 

Syntax: maxfindhistory <numsearchcmds> 

Description: Vi keeps a history of search commands entered. <numsearchcmds> sets the number of 

search commands kept in the history. 

9.2.15 maxlinelen 

Syntax: maxlinelen <maxlne> 

Description: This parameter controls the maximum line length allowed by Vi. The default value is 512 

bytes. Any lines longer than <maxlne> are broken up into multiple lines. 

9.2.16 maxpush 

Syntax: maxpush <num> 

Description: Controls the number of pushed file positions that will be remembered. Once more than 

<num> push or tag commands have been issued, the first pushed positions are lost. 
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9.2.17 maxswapk 

Syntax: maxswapk <n> 

Description: Sets the maximum number of kilobytes of disk space to be used for temporary storage by 

Vi. 

This option can only be set during editor initialization. 

9.2.18 maxxmsk 

Syntax: maxxmsk <kbytes> 

Description: Sets the maximum number of kilobytes of XMS memory to be used by Vi (DOS real-mode 

version only). 

This option can only be set during editor initialization. 

9.2.19 pagelinesexposed 

Syntax: pagelinesexposed <lines> 

Description: Sets the number of lines of context left exposed when a page up/down is done. For 

example, if <lines> is set to 1, then when a page down key is pressed, the bottom line of the 
file will be visible at the top of the new page. 

9.2.20 overstrikecursortype 

Syntax: overstrikecursortype <size> 

Description: Sets the size of the cursor when in overstriking text in text insertion mode. Values for 

<size> are 0 to 100 (0=full size, 100=thin). 

9.2.21 radix 

Syntax: radix <rdx> 

Description: Sets the radix (base) of the results of using the command line command eval. The default 

is base 10. 

9.2.22 shiftwidth 

Syntax: shiftwidth <nsp> 

Description: Sets the number of spaces inserted/deleted by the shift operators (’>’ and ’<’), CTRL_D 

and CTRL_T in text insertion mode, and by autoindent and cmode when they are 
indenting. 
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9.2.23 stackk 

Syntax: stackk <kbytes> 

Description: Sets the size (in kilobytes) of the stack used by Vi. The minimum is 10. This can be set 

higher if you plan on using nested scripts that go deeper than 4 or 5 levels. 

This option can only be set during editor initialization. 

9.2.24 statussections 

Syntax: statussections <sects> 

Description: The controls the appearance of the bars in the status window. A list of distances (in pixels) 

is given. This distance is measured from the start of the status window. Each section may 
have something put in it via the statusstring 

This option is only valid with the GUI versions of the editor. 

9.2.25 statusstring 

Syntax: statusstring <str> 

Description: This controls what is displayed in the status window. Any characters may be in this string. 

Additionally, the dollar sign (’$’) is a special character. It is used in combination with 
other characters to represent special values: 

• $<n>C current column number. If <n> is specified (a number), then the column 
number will be padded with spaces so that the it occupies <n> characters. 

• $D current date 

• $H current hint text from menus or toolbar (GUI editors only) 

• $<n>L current line number. If <n> is specified (a number), then the line number 
will be padded with spaces so that the it occupies <n> characters. 

• $M current mode the editor is in 

• $T current time 

• $n skip to next line in status window (character mode editors only) 

• $$ replaced with a ’$’ 

• $c replaced with a comma 

• $[ skip to next block in the status window (GUI editors only) 

• $1 text will be centered (within current block for GUI editors) 
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• $> text will be right-justified (within current block for GUI editors) 

• $< text will be left-justified (within current block for GUI editors) 

A number may precede the L or the C, to indicate the amount of space that the string should 
occupy; for example, $6L will cause the line number to always occupy at least 6 spaces. 

The string may be surrounded by quotes if spaces are being used. The default status string 
setting for character mode editors is; 

set statusstring="L:$6L$nC:$6C" 

For GUI editors, the default status string setting is: 

set statusstring = "Ln:$5L$[Col:$3C$[Mode: $M$[$|$T$[$H" 

9.2.26 shellprompt 

Syntax: shellprompt <string> 

Description: This setting controls what the prompt at the command line will be after using the shell 

command. 

9.2.27 tabamount 

Syntax: tabamount <nsp> 

Description: Sets the number of spaces inserted when the tab key is pressed in a text insertion mode. If 

realtabs is set, these spaces will be changed into tabs, based on the setting of hardtab. 

9.2.28 tagfilename 

Syntax: tagfilename <fname> 

Description: This defines the file name that Vi is to use to locate tags in. The default is the name tags. 

9.2.29 tmpdir 

Syntax: tmpdir <dir> 

Description: This is used to specify the directory where all temporary editor files are to be created. 

This option can only be set during editor initialization. 
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9.2.30 word 

Syntax: word <str> 

Description: This defines the word used by Vi. <str> is a group of character pairs. Each pair defines a 

range; e.g. 09az defines the characters 0 through 9 and a thorough z. Any character in the 
ranges defined by <str> is considered part of a word. 

The default for word is "_09AZaz". 

The word will be delimited by white space (spaces or tabs) and all characters not in the 
ranges defined by <str>. 


9.2.31 wrapmargin 

Syntax: wrapmargin <margin> 

Description: If wrapmargin is set to a non-zero value, then word wrapping is enabled. As text is entered, 

the position of the cursor is monitored. Once the cursor gets within <margin> characters of 
the right margin, the current word is moved to a new line. 

9.2.32 Mouse Control Values 

The section contains descriptions of the non-boolean settings affecting the mouse. 

9.2.32.1 mousedclickspeed 

Syntax: mousedclickspeed <ticks> 

Description: Sets the number of ticks between the first mouse button depress and the second mouse 

button depress for the action to count as a double-click. A tick is approximately 1/18 of a 
second. 

This option is only valid with the character mode versions of the editor. 

9.2.32.2 mouserepeatdelay 

Syntax: mouserepeatdelay <ticks> 

Description: Sets the number of ticks between when a mouse button is depressed and when the button 

starts to "repeat". A tick is approximately 1/18 of a second. 

This option is only valid with the character mode versions of the editor. 

9.2.32.3 mousespeed 

Syntax: mousespeed <speed> 
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Description: Sets the speed of the mouse. <speed> may be in the range 0-31 (0 is the fastest, 31 is the 

slowest). 

This option is only valid with the character mode versions of the editor. 

9.2.32.4 wordalt 

Syntax: wordalt <str> 

Description: This defines the alternate word used when double clicking the mouse. <str> is defined in 

the same fashion as for the word setting. 

The default for wordalt is _09AZaz". 

9.2.33 Window Control Values 

The section contains descriptions of the non-boolean settings affecting windows. 

9.2.33.1 buttonheight 

Syntax: buttonheight <height> 

Description: Sets the height (in pixels) of the tools on the toolbar. 

This option is only valid with the GUI versions of the editor. 

9.2.33.2 buttonwidth 

Syntax: buttonwidth <width> 

Description: Sets the width (in pixels) of the tools on the toolbar. 

This option is only valid with the GUI versions of the editor. 

9.2.33.3 clockx 

Syntax: clockx <x> 

Description: Sets the x-coordinate of where the clock is to be displayed, if clock is enabled. 

This option is only valid with the character mode versions of the editor. 

9.2.33.4 clocky 

Syntax: clocky <y> 

Description: Sets the y-coordinate of where the clock is to be displayed, if clock is enabled. 

This option is only valid with the character mode versions of the editor. 
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9.2.33.5 currentstatuscolumn 

Syntax: currentstatuscolumn <col> 

Description: Controls which column current status information is displayed in on the the menu bar, if 

currentstatus is enabled. 

This option is only valid with the character mode versions of the editor. 


9.2.33.6 cursorblinkrate 

Syntax: cursorblinkrate <ticks> 

Description: Controls the speed at which the cursor blinks at. 

This option is only valid with the GUI versions of the editor. 


9.2.33.7 gadgetstring 

Syntax: gadgetstring <str> 

Description: This string controls the characters that are used to draw the gadgets on the border. The 

characters in the string are used as follows: 

1. top left corner of edit window 

2. top right corner of edit window 

3. bottom left corner of edit window 

4. bottom right corner of edit window 

5. left side of edit window 

6. top and bottom of edit window 

7. left side of file name on top of border of edit window 

8. right side of file name on top of border of edit window 

9. cursor up gadget on scroll bar 

10. cursor down gadget on scroll bar 

11. right side of edit window (scroll bar area) 

12. scroll thumb 

This option is only valid with the character mode versions of the editor. 


9.2.33.8 inactivewindowcolor 

Syntax: inactivewindowcolor <clr> 

Description: Sets the foreground color of an edit window border when it is inactive (not the current edit 

window). <clr> may be 0-15, or one of the previously defined color keywords. 

This option is only valid with the character mode versions of the editor. 
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9.2.33.9 maxtilecolors 

Syntax: maxtilecolors <n> 

Description: Controls the number of tile colors for tiled windows (when using the tile command). 

This option is only valid with the character mode versions of the editor. 


9.2.33.10 maxwindowtilex 

Syntax: maxwindowtilex <x> 

Description: Defines the maximum number of windows that may be tiled together in the x direction 

when using the tile command. 

This option is only valid with the character mode versions of the editor. 


9.2.33.11 maxwindowtiley 

Syntax: maxwindowtiley <y> 

Description: Defines the maximum number of windows that may be tiled together in the y direction 

when using the tile command. 

This option is only valid with the character mode versions of the editor. 


9.2.33.12 movecolor 

Syntax: movecolor <attr> 

Description: Controls the color attributes of an edit window border when the window is being moved 

(either by using the mouse or by using the movewin command). The attribute is composed 
of a foreground and a background color, (16 * background + foreground gives <attr>). 

This option is only valid with the character mode versions of the editor. 


9.2.33.13 resizecolor 

Syntax: resizecolor <attr> 

Description: Controls the color attributes of an edit window border when the window is being resized 

(either by using the mouse or by using the resize command). The attribute is composed of 
a foreground and a background color, (16 * background + foreground gives <attr>). 

This option is only valid with the character mode versions of the editor. 

9.2.33.14 spinx 

Syntax: spinx <x> 
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Description: Sets the x-coordinate of where the busy spinner is displayed, if spinning is enabled. 

This option is only valid with the character mode versions of the editor. 

9.2.33.15 spiny 

Syntax: spiny <y> 

Description: Sets the y-coordinate of where the busy spinner is displayed, if spinning is enabled. 

This option is only valid with the character mode versions of the editor. 


9.2.33.16 tilecolor 

Syntax: tilecolor <n fg bg> 

Description: Sets tile area <n> to have the foreground color <fg> and the background color <bg>. 

The tile area <n> must be in the range 1 to maxtilecolors. 

The colors may be in the range 0-15, or one of the previously defined color keywords. 
This option is only valid with the character mode versions of the editor. 
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Regular expressions are a powerful method of matching strings in your text. Commands that use regular 
expressions are: 

• forward slash (’/’) command mode key (search forwards) 

• question mark (’?’) command mode key (search backwards) 

• forward slash (’/’) command line address (search forwards) 

• question mark (’?’) command line address (search backwards) 

• substitute command line command 

• global command line command 

• egrep command line command 

• match command line command 

Different characters in a regular expression match different things. A list of all special (or "magical") 
characters is: 

• A backslash (’V) followed by a single character other than new line matches that character. 

• The caret (’ A ’) matches the beginning of a line. 

• The dollar sign (’$’) matches the end of a line. 

• The dot (’.’) matches any character. 

• A single character that does not have any other special meaning matches that character. 

• A string enclosed in brackets [] matches any single character from the string. Ranges of ASCII 
character codes may be abbreviated as in "a-zO-9". A ’]’ may occur only as the first character of the 
string. A literal must be placed where it cannot be mistaken as a range indicator. If a caret (’ A ’) 
occurs as the first character inside the brackets, then any characters NOT in the string are matched. 

• A regular expression followed by an asterisk (’*’) matches a sequence of 0 or more matches of the 
regular expression. 

• A regular expression followed by a plus sign (’+') matches one or more matches of the regular 
expression. 

• A regular expression followed by a question mark (’?’) matches zero or one matches of the regular 
expression. 

• Two regular expressions concatenated match a match of the first followed by a match of the second. 
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• Two regular expressions separated by an or bar (T) match either a match for the first or a match for 
the second. 

• A regular expression enclosed in parentheses matches a match for the regular expression. 

• The order of precedence of operators at the same parenthesis level is the following: [], then *+?, 
then concatenation, then I. 

• All regular expressions following an at sign (’ @’) are to be treated as case sensitive, regardless of 
the setting of caseignore. 

• All regular expressions following a tilde (’-’) are to be treated as case insensitive, regardless of the 
setting of caseignore. 

• If an exclamation point (’!’) occurs as the first character in a regular expression, it causes the 
ignoring of the magic setting; that is, all magic characters are treated as magical. An exclamation 
point (’!’) is treated as a regular character if it occurs anywhere but at the very start of the regular 
expression. 

If a regular expression could match two different parts of the line, it will match the one which begins 
earliest. If both begin in the same place but match different lengths, or match the same length in different 
ways, then the rules are more complicated. 

In general, the possibilities in a list of branches are considered in left-to-right order, the possibilities for **’, 
‘+’, and ‘?’ are considered longest-first, nested constructs are considered from the outermost in, and 
concatenated constructs are considered leftmost-first. The match that will be chosen is the one that uses the 
earliest possibility in the first choice that has to be made. If there is more than one choice, the next will be 
made in the same manner (earliest possibility) subject to the decision on the first choice. And so forth. 

For example, ‘(abla)b*c’ could match ‘abc’ in one of two ways. The first choice is between ‘ab’ and ‘a’; 
since ‘ab’ is earlier, and does lead to a successful overall match, it is chosen. Since the ‘b’ is already 
spoken for, the ‘b*’ must match its last possibility the empty string since it must respect the earlier choice. 

In the particular case where no Ts are present and there is only one ‘+’, or ‘?’, the net effect is that the 
longest possible match will be chosen. So ‘ab*’, presented with ‘xabbbby’, will match ‘abbbb’. Note that 
if ‘ab*’ is tried against ‘xabyabbbz’, it will match ‘ab’ just after ‘x’, due to the begins-earliest rule. 

10.1.1 Regular Expression BNF 

A pseudo-BNF for regular expressions is: 
reg-exp {branch}l{branch}l... 

branch {piece} {piece}... 

piece {atom{* or + or ?}} {atom{* or + or ?}}... * - match 0 or more of the atom + - match 1 or 

more of the atom ? - match a match of the atom, or the null string 

atom (reg-exp ) or range or ~ or @ or A or $ or \char or char 

range [ { A } char and/or charlo-charhi ] 

’ A ’ causes negation of range. 
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Match any character. 

A Match start of line. 

$ Match end of line. 

@ What follows is to be searched with case sensitivity. 

What follows is to be searched without case sensitivity. 

/ If it occurs as the first character in a regular expression, it causes the ignoring of the magic 

setting; that is, all magic characters are treated as magical. ! is treated as a regular 
character if it occurs anywhere but at the very start of the regular expression. 

char Any character. 

\char Forces \char to be accepted as char (no special meaning) except \t matches a tab character if 

realtabs is set. 


10.2 File Matching Regular Expressions 

When specifying a file name in Vi, it is possible to use a file matching regular expression. This expression 
is similar to a regular expression, but has a couple of differences; 

1. A dot (’.’) specifies an actual dot in the file name. 

2. An asterisk (’*’) is equivalent to (matches 0 or more characters). 

3. A question mark (’?’) is equivalent to a regular expression dot (’.’); i.e., a question mark matches 
exactly one character. 

4. Caret (’ A ’) has no meaning. 

5. Dollar sign (’$’) has no meaning. 

6. Backslash (’V) has no meaning (it is used as a directory separator). 

Imagine the list of files: 

a. c 
abc. c 
abc 
bed. c 
bad 
xyz. c 

The following examples show how what files from the above list would be matched by various file name 
regular expressions: 
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a*.c - all files that start with 'a' and end in ' .c' . 

matches: "a.c" and "abc.c" 

(alb)*.c - all files that start with an ’a’ or a ’b’ and end in \c’ 
matches: "a.c" "abc.c" and "bcd.c" 

*d.c - all files that end in’d.c’. 
matches: "bcd.c" 

* - all files. 

*.* - all files that have a dot in them, 

matches: a.c abc.c bcd.c xyz.c 

10.3 Replacement Strings 

If you are dealing with regular expression search and replace, then there are some special character 
sequences in the replacement string. 

& Each instance of “&' in the replacement string is replaced by the entire string of matched 

characters. 

\\ Used to enter a ’V in the replacement string. 

V; Replaced with a new line. 

V Replaced with a tab (if realtabs is set). 

\<n> Each instance of <n>, where <n> is a digit from 0 to 9, is replaced by the n’th 

sub-expression in the regular expression. 

\u The next item in replacement string is changed to upper case. 

V The next item in replacement string is changed to lower case. 

\U All items following \U in the replacement string are changed to upper case, until a \E or \e 

is encountered. 

\L All items following \L in the replacement string are changed to lower case, until a \E or \e 

is encountered 

\e Terminate a \U or \L 

\E Terminate a \U or \L. 

\l<«> Substitutes spaces up to column <n>, so that the item that follows occurs at column <n>. 

\# Substitutes current line number that the match occurred on. 
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10.4 Controlling Magic Characters 

By default, all special characters in a regular expression are "magical"; that is, if a special character is used 
it has a special meaning. To use a special character, like (, it must be escaped: \(. 

However, it is possible to change this using the magic setting and the magicstring setting. If magic is set, 
then all special characters are magical. If magic is NOT set, then any special characters listed in 
magicstring lose their special meaning, and are treated as regular characters. For example, the following 
command line commands 

set nomagic 

set magicstring= () 

set up Vi so that the brackets () lose their special meaning. To use the characters in their "magical" way, 
they must be escaped with a Y 

Replacement strings special character sequences can be disabled by turning off the regsubmagic setting. 

10.5 Regular Expression Examples 

The following sections contain examples of regular expression usage for text matching and text 
replacement. 

10.5.1 Matching Examples 

This section gives examples of different types of regular expressions. Each example shows the regular 
expression, the initial string, and the result. In the result, the part of the string that is matched is underlined. 

a+ 

1 . 


String: 

defabc 

Matches: 

defabc 

String: 

aaabca 

Matches: 

aaabca 

String: 

zzzaaayyy 

Matches: 

zzzaaayyy 

String: 

defabc 
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Matches: 

2 . 

String: 

Matches: 

3 . 

String: 

Matches: 

ab* 

1 . 

String: 

Matches: 

2 . 

String: 

Matches: 

3 . 

String: 

Matches: 

ab*$ 

1 . 

String: 

Matches: 

2 . 

String: 

Matches: 

3 . 

String: 

Matches: 

4 . 

String: 

Matches: 

ab? 


defabc 

aaabca 

flflabca 

zzzaaayyy 

zzzaaayyy 


xabc 

xabc 

abbbbbcabc 

abbbbbcabc 

dddacab 

dddacab 


xabc 

abc 

abbbbbcabc 

abbbbbcabc 

dddacab 

dddacafc 

defabbbbb 
def abbbbb 
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i. 



String: 

abc 

2. 

Matches: 

abc 


String: 

abbbbbcabc 

3. 

Matches: 

a/jbbbbcabc 


String: 

acab 


Matches: 

acab 

[abc] 



1 . 

String: 

abc 

2. 

Matches: 

abc 


String: 

defb 

3. 

Matches: 

deft 


String: 

defcghi 


Matches: 

defcghi 

a | b 



1 . 

String: 

abc 

2. 

Matches: 

abc 


String: 

bac 

3. 

Matches: 

bac 


String: defabc 

Matches: defabc 


[a-z]+ 
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1. 

2 . 

3. 

( [ A 

1 . 

(abc) | 

1 . 

2 . 

A (abc) 

1 . 

2 . 

3. 


String: 

abcdef 

Matches: 

abcdef 

String: 

abcOdef 

Matches: 

aftcOdef 

String: 

Oabcdef 

Matches: 

0 abcdef 


String: 

abc def 

Matches: 

abc def 

(def) 


String: 

abcdef 

Matches: 

abc def 

String: 

zzzdefabc 

Matches: 

zzzdefabc 

1 (def) 



String: 

abcdef 

Matches: 

abc def 

String: 

zzzdefabc 

Matches: 

zzzdefabc 

String: 

zzzabcdef 

Matches: 

zzzabc def 


174 Regular Expression Examples 




Regular Expressions 


( (abc) + | (def))ghi 

1 . 


String: 

defabcghi 

Matches: 

defabcghi 

String: 

abcabcghi 

Matches: 

abcabcghi 

String: 

abcdefghi 

Matches: 

abcdefghi 

String: 

abcdef 

Matches: 

abcdef 


10.5.2 Replacement Examples 

Regular expressions and replacement expressions. Each example shows the regular expression and the 
replacement expression, the initial string, the match, and the resulting string after the replacement. 

The regular expression and the replacement are separated by forward slashes (’/’). For example, in the 
string 

/([a-z]+)((a|b))/Test:\l\2/ 

(ta-z]+)((alb)) is the regular expression and Test:\l\2 is the replacement expression. 
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11 Editor Script Language 


The Open Watcom Vi Editor supports a powerful command language. In a script, you may use any 
command line command, along with a number of special commands explicitly for the script environment. 

White space is ignored in a script file, unless a line starts with a right angle bracket (’>’). Comments may 
be imbedded in a script file by starting the line with pound sign (’#’). 

A script is invoked using the command line command source. Examples are: 

source test2.vi 

source test.vi parml parm2 parm3 parm4 

A script may be invoked with a set of optional parameters. These optional parameters are accessed in the 
script by using %n. Every occurrence of %n in the script is replaced by the corresponding parameter. To 
access parameter above 9, brackets must surround the number. This is because: 


%10 


cannot be distinguished from the variable %1 followed by a 0, and the variable %10. To remove the 
ambiguity, brackets are used: 

% ( 10 ) 

All parameters can be accessed by using %*. 

To allow multiple words in a single parameter, delimit the sequence by forward slashes (’/’) or double 
quotes For example, the line 

source test.vi "a b c" d e 

would cause the script test.vi to have the following variables defined: 

%* = a b c d e 
%1 = a b c 
%2 = d 
%3 = e 

General variables, both local and global, are also supported in the editor script language. Any line in a 
script that is not one of the script commands has all the variables on it expanded before the line is 
processed. Script commands can manipulate the variables. For more information, see the section "Script 
Variables" on page 178 of this chapter. 

There are several useful command line commands dealing with Vi scripts, they are: 

compile Used to compile a script. This allows much faster execution of the script by Vi. 

load Used to make a script resident in Vi. This allows much faster invocation of the script, since 

Vi does not have to search for it or parse it. 


Editor Script Language 177 




The Open Watcom Vi Editor Reference 


If a system command is spawned from a script (using the exclamation point (’!’) command), then Vi does 
not pause after the system command is finished running. However, if you set pauseonspawnerr, then Vi 
will pause after a system command is executed from a script if the system command returned an error. 

11.1 Script Variables 

General variables are supported in a Vi script. Variables are preceded by a percent symbol (’%’). 
Variables with more than one letter must be enclosed by brackets, for example: 

%a - references variable named a. 

%(abc) - references variable named abc. 

The brackets are required to disambiguate single letter variables followed by text from multiple letter 
variables. 

Both local and global variables are supported. They are distinguished by the case of the first letter: local 
variables must begin with a lower case letter, and global variables begin with an upper case variable. 
Example variables: 


%A 
% Si 

%(AbC) 
%(abC) 


global variable named A. 
local variable named a. 
global variable named AbC. 
local variable named abC. 


Global variables are valid for the life of the editing session. 

Local variables are only valid for the life of the script that they are used in. 


11.1.1 Pre-defined Global Variables 

There are a number of global variables that take on values as the editor runs, they are: 

%C Contains the current column number in the current edit buffer. 

%D Drive of current file, based on the actual path. 

%(D1) Drive of current file, as typed by the user. This could have no value. 

%E File name extension of current file. 

%F Current file name (including name and extension). 

%H Home directory of a file. This is the directory where the edit command was issued. 

%N Name of the current file, extension removed. 

%M Modified status of the current file - set to 1 if the file has been modified, and a 0 otherwise. 

%(OS) What operating system the editor is hosted on. Possible values are: 

• dos (protect and real mode). 

• unix (QNX, Linux or other Unix-based systems) 


178 Script Variables 




Editor Script Language 


• os2 

• os2v2 

• nt 

%(OS386) This variable is set to 1 is the host operating system is 386 (or higher) based. The possible 
386 environments are: 

• dos (protect mode). 

• os2v2 

• nt 

• unix (when running on a 386) 

Path of current file (no extension, name, or 

Path of current file (no extension, name, or 
This could have no value. 

Contains the current row (line number) in the current edit buffer. 

Height of entire screen in characters. 

Width of entire screen in characters. 

%(Sysrc) Return code from last system command. 

11.2 Hook Scripts 

Vi has several hook points where a script, if defined by the user, is invoked. This allows you to intercept 
the editor at key points to change its behaviour. A script that is invoked at a hook point is referred to as a 

hook script. 

Each hook script is identified by a particular global variable. Whenever Vi reaches a hook point, it checks 
if the global variable is defined, and if it is, the global variables contents are treated like a script name, and 
that script is invoked. 

The hook points are: 

• after a new file has been read. 

• before a modified file is saved and exited. 

• after return is pressed on the command line. 

• whenever an unmodified file is modified. 

• whenever a selected (highlighted) column range is chosen (via mouse click or keyboard). 

• whenever a selected (highlighted) line range is chosen (via mouse click or keyboard). 

Read Hook The hook script is called just after a new file has been read into the editor. 

The script invoked is the file specified by the global variable %(Rdhook). 


drive) based on the actual full path to the file, 
drive) based on the name typed by the user. 


%P 

%(P1) 

%R 

%(SH) 

%(SW) 
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Write Hook The hook script is called just before a modified file is to be saved and exited. 

The script invoked is the file specified by the global variable %(Wrhook). 

Command Hook 

The hook script is called after the return is pressed from the command line. The global 
variable %(Com) contains the current command string, and may be modified. Whatever it 
is modified to is what will be processed by the command line processor. 

The script invoked is the file specified by the global variable %(Cmdhook). 

Modified Hook The hook script is called whenever a command is about to modify an unmodified file. If 
the file is modified, the hook is not called. 

The script invoked is the file specified by the global variable %(Modhook). 

Mouse Columns Sel Hook 

The hook script is called whenever a selected column range has been picked. Picking a 
selected region is done by right-clicking the region with the mouse, or by double clicking 
the region with the mouse, or by using the underscore command mode keystroke. 

The script is invoked with the following parameters: 

%1 The selected string. 

%2 Line on screen of selected string. 

%3 Column on screen of start of selected string. 

%4 Column on screen of end of selected string. 

The script invoked is the file is specified by the global variable %(MCselhook). 

Mouse Lines Sel Hook 

The hook script is called whenever a selected line range has been picked. Picking a 
selected region is done by right-clicking the region with the mouse, or by double clicking 
the region with the mouse, or by using the underscore command mode keystroke. 

%1 Line on screen where selection request occurred. 

%2 Column on screen where selection request occurred. 

%3 First line of selected region. 

%4 Last line of selected region. 

The script invoked is the file specified by the global variable %(MLselhook). 
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11.3 Script Expressions 

Vi allows the use of constant expressions in its script language. Long integers and strings may be used in 
an expression. Some sample expressions are: 

5*3+12 

(7*7) +10*((3 + 5)*8 + 9) 

5 >= %(var) 

("%(str)" == "foo") || ("%(str)" == "bar") 

(5+%i*3 == 15) 
rdonly == 1 

An expression is composed of operators and tokens. Operators act on the tokens to give a final result. 

A token in an expression may be a special keyword, a boolean setting value, an integer, or a string. 


A string is indicated by surrounding the string with double quotes ("). A token is an integer if it starts with 
a numeric digit (0 to 9). 


If a token starts with a dot then the remainder of the token is assumed to be a setting token. This token 
evaluates to be 1 or 0 for a boolean setting, or to the actual value of the setting for all others. 


.autoindent 
. ai 

.autosave 
. tmpdir 


1 if autoindent is true, 0 otherwise 
1 if autoindent is true, 0 otherwise 
current value of autosave 
current tmpdir string 


If a token is not surrounded by double quotes, and is not a keyword and is not an integer, then that token is 
assumed to be a string. 

If an expression contains conditional operators, then the result of the expression is a boolean value (1 or 0). 
The following script language control flow commands expect boolean results: 

•if 

• elseif 

• quif 

• while 

• until 

The following are conditional operators in an expression: 

• — (equal to) 

• != (not equal to) 

• > (greater than) 

• >= (greater than or equal to) 

• < (less than) 

• <= (less than or equal to) 

• && (boolean AND) 

• II (boolean OR) 


An expression may also operate on its token using various mathematical operators, these operators are 

• + (plus) 

• - (minus) 
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• * (multiply) 

• / (divide) 

• ** (exponentiation) 

• A (bitwise NOT) 

• I (bitwise OR) 

• & (bitwise AND) 

• » (bit shift down) 

• « (bit shift up) 

Special keyword tokens are: 

ERR_??? These are symbolic representations of all possible errors while executing in Vi. These 

values are found in error. dat. These values are described in the appendix "Error Code 
Tokens" on page 227. 

lastrc This keyword evaluates to the return code issued by the last command run in the script. 

Possible values to compare against are found in error . dat. These values may are 
described in the appendix "Error Code Tokens" on page 227. 

rdonly This keyword evaluates to 1 if the current file is read only, and 0 if it is not read only. 

config This keyword evalutes to a number representing the current mode the screen is configured 

to. Possible values are: 

100 Screen is in color mode. 

10 Screen is in black and white mode. 

1 Screen is in monochrome mode. 

This may be used to have different configurations built into your configuration script 
ed. cf g. 

black This keyword evalutes to the integer representing the color black (0). 

blue This keyword evalutes to the integer representing the color blue (1). 

green This keyword evalutes to the integer representing the color green (2). 

cyan This keyword evalutes to the integer representing the color cyan (3). 

red This keyword evalutes to the integer representing the color red (4). 

magenta This keyword evalutes to the integer representing the color magenta (5). 

brown This keyword evalutes to the integer representing the color brown (6). 

white This keyword evalutes to the integer representing the color white (7). 

dark_gray This keyword evalutes to the integer representing the color dark_gray (8). 

lightJblue This keyword evalutes to the integer representing the color light_blire (9). 

light_green This keyword evalutes to the integer representing the color light_green (10). 
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light_cyan This keyword evalutes to the integer representing the color light_cyan (11). 

light_red This keyword evalutes to the integer representing the color light_red (12). 

light_magenta This keyword evalutes to the integer representing the color light_magenta (13). 
yellow This keyword evalutes to the integer representing the color yellow (14). 

bright_white This keyword evalutes to the integer representing the color bright_white (15). 

11.3.1 Script Expression BNF 

This section describes a BNF for the construction of constant expressions. 

expression : conditional-exp 

conditional-exp 

: log-or-exp 

I log-or-exp ? expression : conditional-exp 

log-or-exp : log-and-exp 

I log-or-exp II log-and-exp 

log-and-exp : bit-or-exp 

I log-and-exp && bit-or-exp 

bit-or-exp : bit-xor-exp 

I bit-or-exp I bit-xor-exp 

bit-xor-exp : bit-and-exp 

I bit-xor-exp A bit-and-exp 

bit-and-exp : equality-exp 

I bit-and-exp & equality-exp 

equality-exp : relational-exp 

I equality-exp == relational-exp I equality-exp != relational-exp 

relational-exp : shift-exp 

I relational-exp > shift-exp 
I relational-exp < shift-exp 
I relational-exp >= shift-exp 
I relational-exp <= shift-exp 

shift-exp : additive-exp 

I shift-exp « additive-exp 
I shift-exp » additive-exp 

additive-exp : multiplicative-exp 

I additive-exp + multiplicative-exp 
I additive-exp - multiplicative-exp 
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multiplicative-exp 

: exponent-exp 

I multiplicative-exp * exponent-exp 
I multiplicative-exp / exponent-exp 
I multiplicative-exp % exponent-exp 

exponent-exp : unary-exp 

I exponent-exp ** unary-exp 


unary-exp 


primary-exp 


token 


primary-exp 
- unary-exp 
~ unary-exp 
! unary-exp 

token 

I ( expression) 

: INTEGER 
I STRING 
I KEYWORD 


11.4 Control Flow Commands 


This section gives a brief overview of the control flow commands of the Vi script language. For a full 
description of all script commands, see the next section "Script Commands" on page 185. 


11.4.1 The LOOP Block 


The loop block is similar to the do-while construct in C. The flow of the loop may be modified using the 
break, continue or quif script commands. 

The loop may be set to run until a termination condition is met by using the loop - until commands. 

The loop may be set to run without any termination condition by using the loop - endloop commands. 

An overview of a loop block is: 
loop 

break 
continue 
quif <expr> 
until <expr> 

loop 

break 
continue 
quif <expr> 
endloop 
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11.4.2 The WHILE Block 


The while block is similar to the while loop construct in C. The flow of the while loop may be modified 
using the break, continue or quif script commands. 

The while loop is set up using the while - endwhile commands. 

An overview of the while block is: 

while <expr> 
break 
continue 
quif <expr> 
endwhile 


11.4.3 The IF Block 


The if block is similar to the if-else construct in C. 

An overview of the if block is: 

if <expr> 
elseif <expr> 
elseif <expr> 
else 
endif 


11.5 Script Commands 

The following command descriptions show items within angle brackets (<>). The angle brackets are there 
to indicate items that you may supply. You are not required to type the brackets. For example, <filename> 
simply means that in the corresponding place in the command you should enter the name of a file. For 
example, <filename> may be replaced with 

test.c 

and the brackets are not entered. 

The command descriptions also show items inside double quotes ("). The double quotes are used to 
indicate a literal option that you may supply. You are not required to type the quotes. For example, "-c" 
indicates that in the corresponding place in the command you may enter -c. 

In the syntax model for each command, the upper-case characters represent the minimal truncation of the 
command. For example, in its syntax model, the ASSIGN command is specified as "ASSIGN", indicating 
that all the letters are required (there are no abbreviations, only "assign" is accepted as the command). 

The term <expr> is used to indicate an expression in the following commands. Expressions are discussed 
in full detail in the section "Script Expressions" on page 181 of this chapter. 

Script variables are used by some of the following commands. Variables are discussed in full detail in the 
section "Script Variables" on page 178 of this chapter. 
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When a script command terminates, lastrc is sometimes set to a value. This value may be tested in an 
expression. Script commands that set this have a Returns section. 


11.5.1 ATOMIC 


Syntax: ATOMIC 

Description: This command causes all editing actions done by the script to all be part of one undo 

record. This way, the action of the entire script can be eliminated with a single undo 
(command) i.e., it is an atomic action. 

11.5.2 ASSIGN 

Syntax: ASSIGN <vl> = /<val>/"r$@xl" 

Description: This command is used to assign the value <val> to the variable <vl>. 

The forward slashes (’/’) around <val> are only need if there are spaces in <val>, or if one 
of the special flags r, x, 1 , $ or @ is required at the end. 

The special flags have the following meaning: 

r When this flag is used, <val> may contain regular expression replacement 

strings (using the last regular expression searched for). For more 
information on regular expressions, see the chapter "Regular Expressions" 
on page 167. 

I When this flag is used, <val> is assumed to be an expression that indicates 

a line number. The expression is evaluated, and the data on the 
corresponding line number is assigned to <vl>. 

x When this flag is used, <val> is assumed to be an expression, and is 

evaluated. The result is assigned to <vl>. For another way of assigning 
expression results to a variable, see the expr script command. 

$ (dollar sign) When this flag is used, <val> is assumed to be the name of an operating 

system environment variable, and the contents of that environment variable 
is what is assigned to <vl>. 

@ When this flag is used, <val> may be the name of one of the set command 

parameters. <vl> will be given the current value of that parameter. 

<val> may be coded as a special operator. If <val> is coded this way, the forward slashes 
(’/’) must NOT be used. The special operators are: 

strlen <v> Computes the length of the variable <v>. This value is assigned to <vl>. 
strchr <v> <c> 

Computes the offset of the character <c> in the variable <v>. The offset is 
assigned to <vl>. Note that the character <c> may be a variable, the value 
of which will be expanded before offset is computed.. 
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substr <v> <nl > <n2> 

Computes a substring of the string contained in the variable <v>. The 
substring is composed of characters from offset <nl> to offset <n2>. The 
substring is assigned to <vl>. Note that the parameters <nl> and <n2> 
may be variables, the values of which will be expanded before the substring 
is computed. 


Example(s): 

assign %a = foobar 

The variable %ci gets the string foobar assigned to it. 

assign %(Path) = /path/$ 

The global variable %(Path) gets the data stored in the path environment variable assigned 
to it. 

assign %b = strlen %a 

Assigns the length of the contents of the local variable %a to the local variable %b. 
Assuming the local variable %a has the string abcdefg assigned to it, then %b gets 7 
assigned to it. 

assign %b = strchr %a b 

Assigns the offset of the letter b in the string contained in the local variable %a to the local 
variable %b. Assuming the local variable %a has the string abcdefg assigned to it, then %b 
gets 2 assigned to it. 

assign %(Substr) = substr %a 2 4 

Assigns the characters from offset 2 to offset 4 in the string contained in the local variable 
%a to the global variable %(Substr). Assuming the local variable %a has the string abcdefg 
assigned to it, then %b gets bed assigned to it. 

assign %(res) = /abc % (str) def/ 

Assuming %(str) has been assigned the value xyz, then the string abc xyz def is assigned to 
the local variable %(res) 

assign %(Result) = /100*30+(50-17)*10/x 
The value 3330 is assigned to the global variable %(Result). 

See Also: expr 


11.5.3 BREAK 

Syntax: BREAK 

Description: Unconditionally exits the current looping block. This breaks out of loop - endloop, loop - 

until and while - endwhile blocks. 

See Also: continue, endloop, endwhile, loop, quif, until, while 
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11.5.4 CONTINUE 

Syntax: 

Description: 

See Also: 

11.5.5 ENDIF 

Syntax: 
Description: 
See Also: 

11.5.6 ENDLOOP 

Syntax: 
Description: 
See Also: 

11.5.7 ENDWHILE 

Syntax: 
Description: 
See Also: 

11.5.8 ELSEIF 

Syntax: 

Description: 


See Also: 


CONTINUE 

Restarts the current looping block. This causes a jump to the top of loop - endloop, loop - 
until and while - endwhile blocks. 

break, endloop, endwhile, loop, quif, until, while 


ENDIF 

Terminates an if - elseif - else block, 
if, elseif, else 


ENDLOOP 

Terminates a loop block. Control goes to the top of the current loop. 

break, continue, endwhile, loop, quif, until, while 


ENDWHILE 

Terminates a while block. Control goes to the top of the current while loop. 

break, continue, endloop, loop, quif, until, while 


ELSEIF <expr> 

An alternate case in an if block. If the opening if script command and none of the elseif 
script commands prior to this one were executed, then this elseif is executed. 

Any variables contained in <expr> are expanded before the expression is evaluated. 

If <expr> is true, then the code following the elseif is executed. If <expr> is false, control 
goes to the next elseif, else or endif command. 

if, else, endif 
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11.5.9 ELSE 

Syntax: ELSE 

Description: This is the alternate case in an if block. If none of the preceding if or elseif statements are 

true, the code following the else command is executed. 

See Also: if, elseif, endif 

11.5.10 EXPR 

Syntax: EXPR <vl> = <expr> 

Description: Assigns the expression <expr> to the variable <vl>. 

Any variables contained in <expr> are expanded before the expression is evaluated. 

Example(s): 

expr %(Num) = 100*30+50 

Assigns the value 3050 to the global variable %(Num). 

expr %a = %(SW)-10 

Assuming a screen width of 80, then this assigns the value 70 to the local variable %a. 

See Also: assign, eval 

11.5.11 FCLOSE 

Syntax: FCLOSE <n> 

Description: Closes file previously opened with a fopen script command. 

Example(s): 

fclose 1 
Closes file 1. 

See Also: fopen, fread, fwrite 

11.5.12 FOPEN 

Syntax: FOPEN <name> <n> <how> 

Description: This command opens file <name>, assigning it file handle <n>. 

<n> may be a value from 1 to 9. This number is used to identify the file for future fread, 
fwrite or fclose script commands. 

<how> specifies the method that the file is opened. Methods are: 
a Opens file for append. 
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r 

w 

x 


Returns: 


Opens file for read. 

Opens file for write. 

Checks if the file exists. This does not actually open the file, so no fclose is 
required. 


ERR_NO_ERR. 

The setting of lastrc if the open/existence check is a success. 
ERR_FILE_NO T_FO UND 

The setting of lastrc if the open/existence check is a fails. 


Example(s): 

fopen test.dat 1 r 

Opens file test.dat for read, and uses file handle 1. 

fopen test.dat 2 w 

Opens file test.dat for write, and uses file handle 2. 

fopen test.dat 1 x 

Tests if the file test.dat exists. 

fopen test.dat 9 a 

Opens file test.dat for append, and uses file handle 9. 

See Also: fclose, fread, fwrite 

11.5.13 FREAD 

Syntax: FREAD <n> <vl> 

Description: Reads a line from the file identified by handle <n>. The line is stored in the variable <vl>. 

Returns: 

ERR_NO_ERR The setting of lastrc if the read was successful. 

END_OF_FILE 

The setting of lastrc if end of file was encountered. 
ERR_FILE_NOT_OPEN 

The setting of lastrc if the file being read was not opened with fopen. 

Example(s): 

fread 1 %(line) 

Reads the next line from file handle 1 into the variable %(line). 

See Also: fclose, fopen, fwrite 
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11.5.14 FWRITE 


Syntax: FWRITE <n> <vl> 

Description: Writes the contents of the variable <vl> to the file identified by handle <n>. 

Returns: 


ERR_NO_ERR The setting of lastrc if the write was successful. 

ERR_FILE_NO T_OPEN 

The setting of lastrc if the file being written was not opened with fopen. 


Example(s): 

fwrite 3 %(line) 

Writes the contents of the variable %(line) to file handle 3. 

See Also: fclose, fopen, fread 

11.5.15 GET 

Syntax: GET <vl> 

Description: Waits for the user to type a single keystroke, and then assigns the keystroke into variable 

<vl>. 

Example(s): 

get %(ch) 

Waits for a key to be pressed, and then assigns the key to the local variable %(ch). 

tloatmcnu. input 

GOTO <label> 

Transfers control to point in script with label <label> defined, 
label 

IF <expr> 

Starts an if block. 

Any variables contained in <expr> are expanded before the expression is evaluated. 

If <expr> is true, then the code following the if is executed. If <expr> is false, control 
goes to the next elseif, else or endif command. 


See Also: 

11.5.16 GOTO 

Syntax: 
Description: 
See Also: 

11.5.17 IF 

Syntax: 

Description: 


Script Commands 191 




The Open Watcom Vi Editor Reference 


See Also: elseif, else, endif 

11.5.18 INPUT 

Syntax: INPUT <vl> 

Description: Open a window (the commandwindow) and get a string from the user. The string is 

assigned to the variable <vl>. 

If <vl> was assigned a value before the input script command was executed, then that 
value is used as a prompt string in the input window. 

Returns: 

ERR_NO_ERR. 

The setting of lastrc if a string was entered. 

NO_VALUE_ENTERED 

The setting of lastrc if the user pressed ESC to cancel the input string. 


Example(s): 

input %(str) 

Get a string from the user, placing the result in the local variable %(str). If %(str) had no 
previous value, then the user would be prompted with: 

Enter Value: 

However, if %(str) had the value Type in a filename:, then the user would be prompted 
with: 


Type in a filename: 

See Also: floatmenu, get 

11.5.19 LABEL 

Syntax: LABEL <name> 

Description: Defines the a label with the name <name> at the current line in the script. 

See Also: goto 

11.5.20 LOOP 

Syntax: LOOP 

Description: Start a loop block. This is the top of the block, after a continue, endloop or until control 

returns to the instruction after the loop command. 

See Also: break, continue, endloop, endwhile, loop, quif, until, while 
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11.5.21 NEXTWORD 


Syntax: NEXTWORD <srcvar> <resvar> 

Description: Remove the next space-delimited word from the variable <srcvar>. The word is placed in 

the variable specified by <srcvar>. Both <srcvar> and <resvar> must be variables only. 


Example(s): 

nextword %a %b 

If %a has'this is a test' assigned to it, then after this command is processed, %a 
will have 'is a test' assigned to it, and %b will have ' this' assigned to it. 


11.5.22 QUIF 

Syntax: QUIF <expr> 

Description: Conditionally quit current loop or while loop block. 

Any variables contained in <expr> are expanded before the expression is evaluated. 

If <expr> is true, the current looping block is exited and execution resumes at the line after 
the end of the current block. 

If <expr> is false, execution continues at the next line. 

See Also: break, continue, endloop, endwhile, loop, until, while 


11.5.23 RETURN 

Syntax: RETURN <rc> 

Description: Exit the script, returning <rc>. 

If the script was invoked by another script, then this value becomes lastrc. 

If the script was invoked at the command line, then this return code is reported as the 
appropriate error, if <rc> is not ERR_NO_ERR. 

There are symbolic values for various error codes. These values are described in the 
appendix "Error Code Tokens" on page 227. 


11.5.24 UNTIL 

Syntax: UNTIL <expr> 

Description: Closes a loop block. 

Any variables contained in <expr> are expanded before the expression is evaluated. 
If <expr> is true, the first line after the loop block is executed. 
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If <expr> is false, then control is returned to the top of the loop block, and the loop 
executes again. 

See Also: break, continue, endloop, endwhile, loop, quif, while 


11.5.25 WHILE 

Syntax: WHILE <expr> 

Description: Start a loop block. If <expr> is true, the body of the loop is executed. If <expr> is false, 

execution transfers to the instruction after the endwhile command. 

Any variables contained in <expr> are expanded before the expression is evaluated. 

This is the top of the block, after a continue or endwhile control returns to the while 
command. 

See Also: break, continue, endloop, endwhile, loop, quif, until 


11.6 Script Examples 

The following section describes a number of the scripts that are provided with Vi. Each script is discussed 
in detail. 

11.6.1 Example - err.vi 

This is a simple script that edits a file that has the exact same name as the current file, only has the 
extension .err. 

1) edit %D%P%N.err 


Line 1 

> edit %D%P%N.err 

The global variable %D contains the drive of the current file. The global variable %P contains the full 
path to the current file. The global variable %N contains the name of the current file (extension 
removed). These are combined with the .err extension to create a full path to an error file. This file is 
edited. 

11.6.2 Example - Inum.vi 

This script prompts the user for a line number, and if a line number is entered, goes to that line. 
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1) 

assign %a 

= /Enter Line Number:/ 

2) 

input %a 


3) 

if lastrc 

! = NO_ VALUE_ ENTERED 

4) 

%a 


5) 

endif 


Lines 1 -2 



> assign %a = 

/Enter Line Number:/ 


> input %a 

These lines assigns the string Enter Line Number: to the local variable %a. This value will be used by 
the input command on line 2 to prompt the user. 

Lines 3-5 

> if lastrc != NO_ VALUE_ ENTERED 

> %a 

> endif 

As long as the input was not cancelled by the user (by pressing the ESC key), the line the user typed is 
executed directly. This assumes that the user will type a number. 

11.6.3 Example - qall.vi 

This script tries to quit each file being edited. If the file has been modified, the user is prompted if he 
wishes to save the file. If he replies ’y’, the file is saved. If he replies ’n’, the file is discarded. If he 
presses the ESC key and cancels the input, the script is exited. 
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1) 

loop 


2) 



3) 

quit 


4) 

if lastrc == ERR_ FILE. 

_ MODIFIED 

5) 

assign %a = /Save 

"%F" (y\/n)?/ 

6) 

input %a 


7) 

quif lastrc == NO_ 

. VALUE_ ENTERED 

8) 

if "%a" == y 


9) 

write 


10) 

quit 


11) 

else 


12) 

quit! 


13) 

endif 


14) 

endif 


15) 

quif lastrc != ERR_ NO. 

_ ERR 

16) 



17) 

endloop 



Line 1 

> loop 
Starts the loop. 

Lines 3-4 

> quit 

> if lastrc == ERR_ FILE_ MODIFIED 

Tries to to quit the file. If the quit command fails, and the return code is ERR_FILE_MODIFIED (the 
quit command will fail if the file being abandoned is modified), then the code from lines 5-14 is 
executed. 

Lines 5-6 

> assign %a = /Save "%F" (y\/n)?/ 

> input %a 
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Assigns the string Save "<filename>" (y/n)? to the local variable %a. This value will be used by the 
input command on line 6 to prompt the user. 

Line 7 

> quif lastrc == NO_ VALUE_ ENTERED 

This exits the main loop if the user cancels the input prompt by pressing the ESC key. 

Lines 8-13 

> if "% a" == y 

> write 

> quit 

> else 

> quit! 

> endif 

If the user typed the letter y, then the edit buffer is saved and exited, otherwise the contents of the edit 
buffer are discarded. 

Line 15 

> quif lastrc != ERR_ NO_ ERR 

This exits the main loop if any of the previous commands did not return the "everything is OK" return 
code, ERR_NO_ERR. 

Line 17 

> endloop 

Ends the loop. Control is returned to line 3. 

11.6.4 Example - wrme.vi 

This example is the default write hook script. This is called just before a edit buffer is saved and exited. If 
the file has a null name, then the user is prompted for a name. If he cancels the prompt, then the save is 
aborted. Otherwise, the new name is set and the save continues. 
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1) if "%F" != "" 

2) return ERR_ N0_ ERR 

3) endif 

4) assign %a = /Enter file name:/ 

5) input %a 

6) if lastrc == N0_ VALUE_ ENTERED 

7) return D0_ NOT_ CLEAR_ MESSAGE_ WINDOW 

8) endif 

9) echo off 

10) set filename = %a 

11) echo on 

12) return ERR_ NO_ ERR 
Lines 1 -3 

> if "%F" != "" 

> return ERR_ NO_ ERR 

> endif 

Checks if the current file name is the empty string. If it is not, then there is a filename and the script 
returns ERR_NO_ERR to indicate that processing is to continue. 

Lines 4-8 

> assign %a = /Enter file name:/ 

> input %a 

> if lastrc == NO_ VALUE_ ENTERED 

> return DO_ NOT_ CLEAR_ MESSAGE_ WINDOW 

> endif 

The user is prompted with Enter a file name:. If he cancels the input command by pressing the ESC 
key, then the script returns DO_NOT_CLEAR_MESSAGE_WINDOW, which is not an error condition 
but causes the save process to abort (remember, a hook point stops what it is doing if an non-zero return 
code is returned from the hook script). 

Line 9 

> echo off 
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Echo is disabled so that the setting of the filename will not cause the normal message to appear in the 
message window. 

Line 10 

> set filename = %a 

The filename is set to whatever the user typed in. 

Line 11 

> echo on 
Echo is enabled. 

Line 12 

> return ERR_ N0_ ERR 

The script returns ERR_NO_ERR to indicate that processing is to continue. 

11.6.5 Example - proc.vi 

This example prompts the user for a procedure name. If the user types one, then a procedure skeleton is 
added: 

/* 

* ProcName 
*/ 

void ProcName( ) 

{ 

} /* ProcName */ 

and the user is left in input mode on the space before the closing bracket (’)’). 
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1) assign %a = /Procedure Name:/ 

2) input %a 

3) if lastrc == NO_ VALUE_ ENTERED 

4) return 

5) endif 

6) atomic 

7) echo off 

8) assign %x = /autoindent/@ 

9) set noautoindent 

10) execute \e0o/*\n * %a\n */\n\e0ivoid %a( @ )\n{\n\n} /* %a 
*/\n\e 

11) if %x == 1 

12) set autoindent 

13) endif 

14) -4 

15) execute \e0f@x 

16) echo on 

17) echo 1 Procedure %a added 

18) echo 2 " " 

19) keyadd i 
Lines 1 -5 

> assign %a = /Procedure Name:/ 

> input %a 

> if lastrc == NO_ VALUE_ ENTERED 

> return 

> endif 

The user is prompted with Procedure Name:. If he cancels the input command by pressing the ESC 
key, then the script exits. 

Line 6 
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> atomic 

The script is an atomic one; so all modifications to the edit buffer can be undone with a single undo 
(command). 

Line 7 

> echo off 

Disables any output to the message window. 

Line 8 

> assign %x = /autoindent/@ 

This line gets the current state of the autoindent setting, and saves it the the local variable %x. 

Line 9 

> set noautoindent 

Turns off autoindent, so that the text to be inserted will line up properly. 

Line 10 

> execute \eOo/*\n * %a\n */\n\eOivoid %a( @ )\n{\n\n) /* %a */\n\e 

This line simulates the typing of a number of keystrokes at the keyboard. The effect of these keys is to 
generate the following: 

/* 

* ProcName 
*/ 

void ProcName( @ ) 

{ 

} /* ProcName */ 

Lines 11-13 

> if %x == 1 

> set autoindent 

> endif 

The local variable %x is set to the previous value of autoindent. If autoindent was on before, then this 
turns it back on. 

Line 14 

> -4 

This backs the cursor up to the line 
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void ProcName( @ ) 

Line 15 

> execute \eOf@x 

This line simulates the typing of a number of keystrokes at the keyboard. The effect of these keystrokes 
is to move forward to the ’ @’ character and delete it. This leaves the cursor in the position necessary to 
enter procedure parameters. 

Line 16 

> echo on 

Enables output to the message window. 

Lines 17-18 

> echo 1 Procedure %a added 

> echo 2 " " 

Displays a message. 

Line 19 

> keyadd i 

Adds the key T to the keyboard buffer. Once the script exits, Vi will process this key as if the user had 
typed it. Thus, once the script is done, the user is left inserting text. 
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A. Command Mode Key Summary 


The following is a list of all possible keys that may be pressed in command mode, and their default 
behaviour. 

Commands preceded with a <n> take a repeat count. 

Commands preceded with a <"?> accept a copy buffer name. 

Commands that accept mark letter (’a’-’z’) have a <?> in their definition. 

The <oper> notation in the following commands indicates some sort of operator that the command will act 
on. <oper> may be one of: 

1. A movement command. See the section "Movement" on page 72 for a full description of all 
movement commands. If a movement command is specified, then the range that the command 
will act on is from the current position to the position that would be achieved by using the 
movement command. 

2. A search command: 

• / (forward slash) 

• ? (question mark) 

• n 

•N 

See the section "Searching" on page 82 for a full description of the searching commands. If a 
search command is specified, then the range that the command will act on is from the current 
position to the position that would be achieved by using the search command. 

3. The current selected (highlighted) region. In this case, <oper> is the r key. 

4. The same character as the command character. This causes the command to operate on the 
current line. 


<n>CTRL_B 

Move up one page. 

<n>CTRL_D 

Move down a half page. 

<n>CTRL_E 

Expose the line below the bottom line on the screen. 

<n>CTRL_F 

Move down one page. 

CTRL_G 

Display current file status. 

CTRL_L 

Redraw the screen. 
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<n>CTRL_N 
<n>CTRL_P 
CTRL_R 
<n>CTRL_U 
CTRL_V 
CTRL_X 
<n>CTRL_Y 
CTRLJ 
<n> SPACE 
<n>!<oper> 
$ 

% 

'<?> 

<n> + 

<n>- 

/ 

0 

<n>«oper> 

<n»<oper> 

? 

@ 

A 

<n>B 


Move to next line. 

Move to previous line. 

Start text selection. 

Move up a half page. 

Display current version. 

Display hex value of character under cursor. 

Expose the line before the top line on the screen. 

Go to the tag indicated by the current word. 

Move the cursor right one character. 

Run lines through a filter. 

Move to the end of the current line. 

Find the matching brace or other defined match item. 

Go to the mark ?. 

Go to the start of the next line. 

Perform the last f,t,F or T command, in the opposite direction. 

Go to the start of the previous line. 

Repeat last command mode sequence that changed the edit buffer. 
Search forward for a string. 

Move to the first character on the current line. 

Enter a command line command. 

Perform the last f,t,F or T command. 

Shift lines to the left. 

Shift lines to the right. 

Search backwards for a string 

Execute a copy buffer as if it were typed at the keyboard. 

Start inserting text at the end of the current line. 

Move back to the start of the previous space delimited word. 
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c 

D 

<n>E 

F<n><?> 

<n>G 

<n>H 

I 

<n>J 

<n>L 

M 

N 

O 

< "?>P 

Q 

R 

<n>S 

T<?> 

U 

<n>W 

<n>X 

<n>Y 

Z 


‘<?> 

a 

<n>b 


Change characters from the current column to the end of the current line. 

Delete characters from the current column to the end of the current line. 

Move forwards to the end of the next space delimited word. 

Move backwards to a specified character. 

Go to a specified line number. 

Go to the top of the current edit window. 

Start inserting text at the first non-whitespace character on the current line. 

Join the next line to the current line. 

Go to the bottom of the current edit window. 

Go to the middle of the current edit window. 

Repeat the last find command, only search in the opposite direction. 

Open a blank line above the current line, and enter text insertion mode. 

Insert a copy buffer before the current position. 

Enter EX mode. 

Enter text overstrike mode. 

Substitute lines with other text. 

Move backwards to the character after a specified character. 

Re-do (undoes the last undo). 

Move forward to the start of the next space delimited word. 

Delete the character before the current character. 

Yank (copy) lines. 

If followed by another Z, saves the current file (if it has been modified) and quits the file. 
Move to the first non-whitespace character on the line. 

Simulate right-mouse button press. 

Go to the line and column with the mark <?>. 

Start inserting text at the character after the current cursor position. 

Move backwards to the start of the previous word. 
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<n>c<oper> Change text. 

< "?><n>d<oper> 

Delete text. 

<n>e Move to the end of the current word. 

<n>f<?> Move forward to the character <?> on the current line. 

<n>h Move left. 

i Start inserting text at the current cursor position. 

<n>j Move down one line. 

<n>k Move up one line. 

<n>l Move right. 

m< ?> Set the mark <?>. 

n Repeat the last find command. 

o Open a new line after the current line, and start inserting text. 

< "?>p Insert a copy buffer at the current position in the edit buffer. 

<n>r Replace the current character. 

<n>s Substitute the current character with text. 

<n>t<?> Move up to the character before the character <?> on the current line. 

it Undo the last change. 

<n>w Move to the start of the next word. 

<n>x Delete the character at the cursor. 

<nx"?>y<oper> 

Yank (copy) text. 

<n>z<?> Reposition the current line. 

<n> I Move to the specified column. 

<n>~<oper> Toggle the case of text. 

FI Move to the next file in the list of files being edited. 

F2 Move back to the previous file in the list of files being edited. 

<n>UP Move up one line. 
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<n>DOWN 

Move down one line. 

<n>LEFT 

Move left to the previous character. 

<n>RIGHT 

Move right to the next character. 

<n>PAGEUP 

Move up one page. 

<n> PAGEDOWN 

Move down one page. 

INS 

Start inserting text at the current cursor position. 

< "?><n>DEL Delete the character at the current cursor position. 

<n>BS 

Move left to the previous character. 

<n> SHIFT_TAB 

Move left by a tab amount. 

<n>ENTER 

Move to the start of the next line. 

<n>TAB 

Move right by a tab amount. 

HOME 

Move to the start of the current line. 

END 

Move to the end of the current line. 

CTRL_F1 

Make copy buffer 1 active. 

CTRL_F2 

Make copy buffer 2 active. 

CTRL_F3 

Make copy buffer 3 active. 

CTRL_F4 

Make copy buffer 4 active. 

CTRL_F5 

Make copy buffer 5 active. 

CTRL_F6 

Make copy buffer 6 active. 

CTRL_F7 

Make copy buffer 7 active. 

CTRL_F8 

Make copy buffer 8 active. 

CTRL_F9 

Make copy buffer 9 active. 

ALT_M 

Display current memory state. 

ALT_W 

Activate the current edit window menu. 

ALT_X 

Insert a keystroke by entering the ASCII value. 

CTRL_PAGEUP 

Move to the first character in the current edit buffer. 
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CTRL_PAGEDOWN 

Move to the last character in the current edit buffer. 

<n>SHIFT_UP 

Start selection, and move up. 

<n>SHIFT_DOWN 

Start selection, and move down. 

<n> SHIFT_LEFT 

Start selection, and move left. 

<n> SHIFT_RIGHT 

Start selection, and move right. 

< "?> SHIFT_DEL 

Delete selected region. 

< "?> SHIFT_INS 

Insert a copy buffer at the current position in the edit buffer. 
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B. The Open Watcom Vi Editor Error Messages 


This appendix lists all of the various errors that Vi reports during its operation. 

In the following error message text, there are certain special characters that you will not see when the 
message is displayed; instead, something is filled in when you see it. These special characters are: 

%s An appropriate string is filled in by Vi. 

%c An appropriate character is filled in by Vi. 

%d An appropriate number is filled in by Vi. 

*+ operand could be empty 

A regular expression error, issued if you use * or + after an empty sub-expression. 

?+*follows nothing 

A regular expression error, issued if you use a ?, + or * without using some sub-expression 
for them to operate on. 

Already in dot mode 

You pressed dot and the string that was executed tried to do another dot from 
command mode. 

Already two marks on this line 

Only two marks are allowed on any line. This error is issued if you try to place a third 
mark on the line. 

Cannot delete character 

You tried to delete a character that is not there. 

Cannot insert the character value 0. 

You typed the number 0 at the prompt from the ALT_X command mode keystroke. 
Cannot open line number window 

Vi could not open the line number window, probably due to an invalid position of the 
command window. 

Case toggle has nothing following 

A regular expression error, issued if you use a case toggle operator (@ or ~) and do not 
place an expression after it. 

Character ’%c’ not found 

You used a ’f, ’T’, T, ’F\ or command mode keystroke, and the letter that you 
specified is not on the line. 
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Directory operation failed 

You tried to ’cd’ to a directory that does not exist. 

Empty copy buffer 

You tried to paste a copy buffer that has no contents. 

End of file reached 

"nosearchwrap" is set and a search command got to the end of the edit buffer without 
finding a string. 

Expecting : You coded an expression with the ’?’ operator and did not specify a 

File close error 

The "fclose" script command failed - this probably indicates a problem with your hard disk. 
File exists - use w! to force 

You attempted to write a file out with a new name that already exists. 

File has no name 

You attempted to write a file that has not been given a name. 

File is a tty The file names "con", "lptN", "nul", and "pin" are special TTY files. You attempted to read 
or edit a file like this. 

File is read only 

You attempted to modify a read-only file. 

File is view only 

You attempted to modify a view-only file. 

File modified - use :q! to force 

You attempted to quit a modified file. 

File not FOPEN 

In a script, you attempted to "fread" or "fwrite" a file that you did not open with "fopen". 
File not found Issued whenever Vi is looking for a file and it cannot be found. 

File open error Vi will issue this error whenever a file cannot be opened. Typically, this happens when 
you try to edit a directory as a file. 

File read error This error occurs when Vi is trying to read a file. This could indicate that there is a 
problem with your hard disk. 

File seek error This error occurs when Vi is trying to seek to a position in a file. This could indicate a 
problem with your hard disk. 


File write error 

This error occurs when Vi is trying to write a file. This could indicate that your hard disk is 
full, or that there is a problem with your hard disk. 

File "error.dat" not found 

When a script is being processed, and an error token is needed, the file "error.dat" is 
loaded. If it cannot be found, then this error is issued. 
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Input key map already running 

If another input key mapping is run while an input key map is running, this error is issued. 
Insufficient stack for allocation 

Vi tried to do an operation and did not have enough stack space. Try increasing your 
stackk setting and trying the operation again. 

Internal err: Invalid undo record found - undo stacks purged 

Vi has encountered an internal error. Please note the circumstances of this error and, if 
possible, construct a small test case that demonstrates the problem. You can then either file 
a bug report using OpenWatcom’s Bugzilla (http://bugzilla.openwatcom.org), or you can 
discuss the problem on one of the OpenWatcom newsgroups 
(news://news.openwatcom.org). 

Internal err: Null pointer found 

Vi has encountered an internal error. Please note the circumstances of this error and, if 
possible, construct a small test case that demonstrates the problem. You can then either file 
a bug report using OpenWatcom’s Bugzilla (http://bugzilla.openwatcom.org), or you can 
discuss the problem on one of the OpenWatcom newsgroups 
(news://news.openwatcom.org). 

Internal err: Open undo 

Vi has encountered an internal error. Please note the circumstances of this error and, if 
possible, construct a small test case that demonstrates the problem. You can then either file 
a bug report using OpenWatcom’s Bugzilla (http://bugzilla.openwatcom.org), or you can 
discuss the problem on one of the OpenWatcom newsgroups 
(news://news.openwatcom.org). 

Internal err: Regexp corrupted pointer 

Vi has encountered an internal error. Please note the circumstances of this error and, if 
possible, construct a small test case that demonstrates the problem. You can then either file 
a bug report using OpenWatcom’s Bugzilla (http://bugzilla.openwatcom.org), or you can 
discuss the problem on one of the OpenWatcom newsgroups 
(news://news.openwatcom.org). 

Internal err: Regexp foulup 

Vi has encountered an internal error. Please note the circumstances of this error and, if 
possible, construct a small test case that demonstrates the problem. You can then either file 
a bug report using OpenWatcom’s Bugzilla (http://bugzilla.openwatcom.org), or you can 
discuss the problem on one of the OpenWatcom newsgroups 
(news://news.openwatcom.org). 

Internal err: Regexp memory corruption 

Vi has encountered an internal error. Please note the circumstances of this error and, if 
possible, construct a small test case that demonstrates the problem. You can then either file 
a bug report using OpenWatcom’s Bugzilla (http://bugzilla.openwatcom.org), or you can 
discuss the problem on one of the OpenWatcom newsgroups 
(news://news.openwatcom.org). 

Internal error: Regular expression NULL argument 

Vi has encountered an internal error. Please note the circumstances of this error and, if 
possible, construct a small test case that demonstrates the problem. You can then either file 
a bug report using OpenWatcom’s Bugzilla (http://bugzilla.openwatcom.org), or you can 
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discuss the problem on one of the OpenWatcom newsgroups 
(news://news.openwatcom.org). 

Invalid abbreviation 

You did not enter an "abbrev" command correctly. 

Invalid alias command 

You did not enter an "alias" command correctly. 


Invalid ASSIGN 

You did not enter script "assign" command correctly. 

Invalid case command 

You did not enter a valid operation after starting the case toggle command mode 
command. 

Invalid change command 

You did not enter a valid operation after starting the change (’c’) command mode 
command. 

Invalid command 

You entered an invalid command line command. 

Invalid conditional expression 

You did not code a script "if', "elseif", "quif', "until" or "while" statement correctly. 
Invalid data in file ’%s’ at line %d 

This error is issued if one of the .dat files (error.dat, errmsg.dat, keys.dat) contains invalid 
data. 

Invalid delete command 

You did not enter a valid operation after starting the delete fd’) command mode command. 
Invalid EXPR You coded an invalid "expr" script command. 

Invalid FCLOSE 

You coded an invalid "fclose" script command. 

Invalid find command 

You issued an invalid search command. 


Invalid FOPEN 

You coded an invalid "fopen" script command. 

Invalid FREAD 

You coded an invalid "fread" script command. 

Invalid FWRITE 

You coded an invalid "fwrite" script command. 

Invalid global command 

You issued an invalid "global" command line command. 
Invalid GOTO You coded an invalid "goto" script command. 


214 The Open Watcom Vi Editor Error Messages 




The Open Watcom Vi Editor Error Messages 


Invalid INPUT You coded an invalid "input" script command. 

Invalid key ’%c’ 

You press a key that has no mapping in command mode. 

Invalid LABEL You coded an invalid "label" script command. 

Invalid line address 

You used a "copy" or "move" EX mode command, and specified an invalid destination line. 
Invalid line range 

You used an invalid line range for a "global", "substitute" or shift (">" or "<") command 
line command. This occurs if you use line number past the end of the file. 

Invalid map command 

You issued an invalid "map" or "mapbase" command. 

Invalid mark - use ’a’-’z’ 

You attempted to set a mark that was not in the range ’a’ to ’z\ 

Invalid match command 

You issued an invalid "match" command line command. 

Invalid menu You issued an invalid "menu" command line command. 

Invalid redraw You did not specify a valid key after starting the ’z’ command mode command - valid keys 
are dash ENTER, and dot 

Invalid copy buffer ’%c’ - use or ’a’-’z’ 

You tried to access an invalid copy buffer. 

Invalid set command 

You tried to set a variable that does not exist. 

Invalid setcolor command 

You issued an invalid "setcolor" command line command. 

Invalid shift command 

You did not enter a valid operation after starting a shift (’<’ or ’>’) command mode 
command. 

Invalid substitute command 

You issued an improper "substitute" command line command. 

Invalid tag found 

Your tags file contained an invalid tag entry. 


Invalid window 

You attempted an operation on an undefined window, or the window that you attempted to 
define was invalid. 

Invalid window data 

The parameters to "border", "text", "hilight", or "dimension" were invalid. 
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Invalid yank command 

You did not enter a valid operation after starting the yank (’y’) command mode command. 


invalid [] range 

A regular expression error, issued when you specified an invalid range inside the square 
brackets. 


Label not found 

In a script, you attempted to "goto" a label that was not defined. 

Mark ’%c’ no longer valid 

You tried to access a mark that has become invalid ( the line or column that had the mark no 
longer exists). 

Mark ’%c’ not set 

You tried to access an undefined mark. 

Matching ’%s ’ not found 

You used the command mode key ’%’ to look for a matching string to the string under the 
cursor, only the match could not be found. 

nested *?+ A regular expression error, issued if you have two or more of the ’?’ or ’+’ characters 
in a row. 

No character to replace 

You used the command mode key ’r’ to replace a character on an empty line. 

No file specified 

You issued a "compile", "load" or "source" command, and did not specify a file. Another 
source of this error is using the "write" command with a line range and not specifying a file 
name. 

No more undos You issued an undo command, and there are no more undos to perform. 

No more windows 

You exceeded the limit of 250 windows that can be open at the same time. 

No previous search string 

You pressed ’n’ or ’N’ in command mode, but have not yet issued a search command. 

No selection You used the ’r’ operator with’d’, ’c’, ’!’ in command mode, but there is no 

selected region. Another source of this error is specifying the pound sign (’#') as a line 
range on the command line, and having no selected region. 

No string specified 

You indicated that you are starting a string on the command line by using a double quote 
or forward slash (’/’), but you did not specify any characters at all for the string. 

No such abbreviation 

You attempted to use the command line command "unabbrev" for an abbreviation that does 
not exist. 

No such alias You attempted to use the command line command "unalias" for an alias that does not exist. 
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No such drive You used the "cd" command line command to attempt to switch to a disk drive that does 
not exist. 

No such line You specified a line number that does not exist in the current edit buffer. 

Not enough room in line 

You attempted to add characters to a line, and the resulting line would be longer than the 
setting of "maxlinelen". 

Not that many words 

You attempted a command mode command that tried to access more words than were on 
the current line. 

Not valid while in ex mode 

You attempted to use a command from EX mode that was not allowed: an "edit" command 
line command with no parameter, or a "read" command line command with no parameter. 

Nothing to match 

You used the command mode percent (’%’) keystroke, but there was nothing on the current 
line that could be matched. 

Only valid in ex mode 

You attempted to use an EX mode only command from the command line: "append", 
"change", "insert", or "list". 

Out of memory The editor ran out of memory. Try removing some TSR’s (terminate and stay resident 
programs) or increasing swap space (maxswapk). 

Repeat string too long 

You entered a repeat count with too many digits, only 9 digits are allowed. 

Copy buffer too big 

You attempted to execute a copy buffer that is larger than 1024 bytes. 

Script already loaded 

You attempted to load a script that was previously loaded. 

String ’%s’ not found 

A search string cannot be found in the file. 

Swap file full Vi ran out of space in the swap file, but needed more space. Increase the maxswapk 
setting. 

Swap file open error 

Vi could not open a swap file. This could indicate that there are too many open files, or 
that the directory is full (if the swap file is on the root directory), or a problem with your 
hard disk. 

Swap file read error 

An error was encountered while attempting to read the swap file. This could indicate 
problems with your hard disk. 
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Swap file write error 

An error was encountered while attempting to read the swap file. This could indicate 
problems with your hard disk, or that the disk is full. 

Tag ’%s’ not found 

If the tag you have requested cannot be found in the tags file, this error is issued. 

Too many () A regular expression error. There is a limit of 21 nested parenthesis in a regular 
expression. 

Too many match items 

When using the match command to add another match string. There is a limit of 9 different 
match pairs. 

Top of file reached 

Issued if you have nosearchwrap set and a search command gets to the top of the edit buffer 
without finding a string. 

Trailing \ A regular expression error, issued if a backslash (’V) is the last character on a line. Since a 
backslash is an escape character, it must always have a character following it. 

Unmatched () A regular expression error. You have an unequal number of open and closed round 
brackets. 

Unmatched [] A regular expression error. You have specified one square bracket, without using the 
matching one. 

Warning: file is read only 

This warning is issued if "readonlycheck" is set. The message is issued every time you 
modify a read only file. 
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C. CTAGS 


The Open Watcom Vi Editor can utilize something known as tags to help you locate declarations of various 
objects in your C, C++, and FORTRAN code. 

In C or C++ files, tags will help you locate functions, typedefs, structs, enums and unions. In a C++ file, 
you will also be able to locate classes. 

Tags will help you find all function and subroutines in FORTRAN files. 

Once you select a tag that you wish to locate (by either using the command mode key CTRL_] (control 
close square bracket) or the command line command tag). Open Watcom Vi Editor searchs a special tag 
file for the specified tag. The name of the tag file is determined by the setting of tagfilename, the default is 
tags. 

If the tag is located in the tag file, then Open Watcom Vi Editor edits the file that contains the tag that you 
specified and goes to the line with the definition on it, highlighting the line. If the tag is not found, you will 
get an error message. 

The tag file must be located somewhere in the directories specified in your PATH or EDPATH 
environment variable. 

There is a special program provided for the creation of tag files. This program is called ctags. It is used as 
follows: 

Usage: ctags [-?admstqvx] [-f<fname>] [files] [Soptfile] 

[files] : source files (may be C, C++, or FORTRAN) 

file names may contain wild cards (* and ?) 
[Soptfile] : specifies an option file 
Option File Directives: 

option <opts>: any command line options (no dashes). 

an option line resets the d,m,s and t 

they must be specified on option line to 
remain in effect 

file <flist> : a list of files, separated by commas 
-? : print this list 

-a : append output to existing tags file 

-c : add classes (C++ files) 

-d : add all #defines (C,C++ files) 

-f<fname> : specify alternate tag file (default is 

-m : add #defines (macros only) (C,C++ files) 

-s : add structs, enums and unions (C,C++ files) 

-t : add typedefs (C,C++ files) 

-q : quiet operation 

-v : verbose operation 

-x : add all possible tags (same as -cdst) 

Options may be specified in a CTAGS environment variable 


options. 


Options: 


"tags") 
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D. Symbolic Keystrokes 


When mapping keys using the map command, and unmapping keys using the unmap command, it is useful 
to be able to specify the key that you are mapping symbolically, especially if it is a function key, a cursor 
key or other special key. There are a number of pre-defined keys symbols that are recognized when 
specifying which key is being mapped/unmapped. 

The next section describes the symbol used to represent the key, and what the key actually is. These 
symbols are also used throughout this guide to represent a special key. 

D.1 Symbols and Meaning 


ALT_A 

Alt key and A key. 

ALT_B 

Alt key and B key. 

ALT_C 

Alt key and C key. 

ALT_D 

Alt key and D key. 

ALT_DEL 

Alt key and delete key. 

ALT_DOWN 

Alt key and cursor down key. 

ALT_E 

Alt key and E key. 

ALT_END 

Alt key and end key. 

ALT_F 

Alt key and F key. 

ALT_F1 

Alt key and FI key. 

ALT_F2 

Alt key and F2 key. 

ALT_F3 

Alt key and F3 key. 

ALT_F4 

Alt key and F4 key. 

ALT_F5 

Alt key and F5 key. 

ALT_F6 

Alt key and F6 key. 

ALT_F7 

Alt key and F7 key. 

ALT_F8 

Alt key and F8 key. 
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ALT_F9 

Alt key and F9 key. 

ALT_F10 

Alt key and F10 key. 

ALT_F11 

Alt key and FI 1 key. 

ALT_F12 

Alt key and F12 key. 

ALTjG 

Alt key and G key. 

ALT_H 

Alt key and FI key. 

ALT_HOME 

Alt key and home key. 

ALT_I 

Alt key and I key. 

ALTJNS 

Alt key and insert key. 

ALTJ 

Alt key and J key. 

ALT_K 

Alt key and K key. 

ALT_L 

Alt key and L key. 

ALT_LEFT 

Alt key and cursor left key. 

ALT_M 

Alt key and M key. 

ALT_N 

Alt key and N key. 

ALTJ) 

Alt key and O key. 

ALTJ 

Alt key and P key. 

ALTJAGEDOWN 

Alt key and page down key. 

ALTJAGEUP Alt key and page up key. 

alt_q 

Alt key and Q key. 

ALTJ 

Alt key and R key. 

ALTJIGHT 

Alt key and cursor right key. 

ALTJ 

Alt key and S key. 

ALTJ 

Alt key and T key. 

ALT JAB 

Alt key and tab key. 

ALTJ 

Alt key and U key. 

ALTJP 

Alt key and cursor up key. 
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ALT_V 

Alt key and V key. 

ALT_W 

Alt key and W key. 

ALT_X 

Alt key and X key. 

ALT_Y 

Alt key and Y key. 

ALT_Z 

Alt key and Z key. 

BS 

Backspace key. 

CTRL_A 

Control key and A key. 

CTRL_B 

Control key and B key. 

CTRL_C 

Control key and C key. 

CTRL_D 

Control key and D key. 

CTRL_DEL 

Control key and delete key. 

CTRL_DOWN 

Control key and cursor down key. 

CTRL_E 

Control key and E key. 

CTRL_END 

Control key and end key. 

CTRL_F 

Control key and F key. 

CTRL_F1 

Control key and FI key. 

CTRL_F2 

Control key and F2 key. 

CTRL_F3 

Control key and F3 key. 

CTRL_F4 

Control key and F4 key. 

CTRL_F5 

Control key and F5 key. 

CTRL_F6 

Control key and F6 key. 

CTRL_F7 

Control key and F7 key. 

CTRL_F8 

Control key and F8 key. 

CTRL_F9 

Control key and F9 key. 

CTRL_F10 

Control key and F10 key. 

CTRL_F11 

Control key and Fll key. 

CTRL_F12 

Control key and F12 key. 
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CTRLjG 

Control key and G key. 

CTRL_H 

Control key and H key. 

CTRL_HOME 

Control key and home key. 

CTRLJ 

Control key and I key. 

CTRLJNS 

Control key and insert key. 

CTRLJ 

Control key and J key. 

CTRL_K 

Control key and K key. 

CTRLJ 

Control key and L key. 

CTRLJEFT 

Control key and cursor left key. 

CTRLJ/l 

Control key and M key. 

CTRL_N 

Control key and N key. 

CTRLJ) 

Control key and O key. 

CTRLJ 

Control key and P key. 

CTRLJAGEDOWN 


Control key and page down key. 


CTRLJAGEUP 

Control key and page up key. 

CTRLJ 

Control key and Q key. 

CTRLJ 

Control key and R key. 

CTRLJIGHT 

Control key and cursor right key. 

CTRLJ 

Control key and S key. 

CTRLJ 

Control key and T key. 

CTRLJAB 

Control key and tab key. 

CTRLJ 

Control key and U key. 

CTRLJP 

Control key and cursor up key. 

CTRLJV 

Control key and V key. 

CTRLJ/ 

Control key and W key. 

CTRLJ 

Control key and X key. 


224 Symbols and Meaning 




Symbolic Keystrokes 


CTRL_Y Control key and Y key. 
CTRLJZ Control key and Z key. 

DEL Delete key. 

DOWN Cursor down key. 

END End key. 

ENTER Enter key. 

ESC Escape key. 

FI FI key. 

F2 F2 key. 

F3 F3 key. 

F4 F4 key. 

F5 F5 key. 

F6 F6 key. 

F7 F7 key. 

F8 F8 key. 

F9 F9 key. 

F10 F10 key. 

Fll FI 1 key. 

F12 F12 key. 

HOME Home key. 

INS Insert key. 

LEFT Cursor left key. 

PAGEDOWN Page down key. 

PAGEUP Page up key. 

RIGHT Cursor right key. 

SHIFT_DEL Shift key and delete key. 
SHIFT_DOWN Shift key and cursor down key. 
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SHIFT_F1 

Shift key and FI key. 

SHIFT_F2 

Shift key and F2 key. 

SHIFT_F3 

Shift key and F3 key. 

SHIFT_F4 

Shift key and F4 key. 

SHIFT_F5 

Shift key and F5 key. 

SHIFT_F6 

Shift key and F6 key. 

SHIFT_F7 

Shift key and F7 key. 

SHIFT_F8 

Shift key and F8 key. 

SHIFT_F9 

Shift key and F9 key. 

SHIFT_F10 

Shift key and F10 key. 

SHIFT_F11 

Shift key and FI 1 key. 

SHIFT_F12 

Shift key and F12 key. 

SHIFTJNS 

Shift key and insert key. 

SHIFT_LEFT 

Shift key and cursor left key. 

SHIFT_RIGHT Shift key and cursor right key. 

SHIFT_TAB 

Shift key and tab key. 

SHIFTJJP 

Shift key and cursor up key. 

TAB 

Tab key. 

UP 

Cursor up key. 
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E. Error Code Tokens 


These are the tokens defined in the file error. dat that you can use to identify different errors in an 
editor script. A typical usage would be: 

if lastrc != ERR_ NO_ ERR 
... handle error . . . 

else 

... no error ... 
endif 

END_OF_FILE 

Returned if a fread command is done at the end of file. 

ERR_DIRE CTORY_OP_FAILED 

Returned if the last cd command was to a non-existent directory. 

ERR_FILE_EXISTS 

Returned if the last write command tried to overwrite an existing file. 

ERR_FILE_MODIFIED 

Returned if you attempt to quit a modified file. 

ERR_FILE_NO T_FO UND 

Returned by the read command or the fopen command if the file could not be found. 

ERR_FILE_VIEW_ONLY 

Returned if you attempt to modify a view only file. 

ERR_FIND_END_OF_FILE 

Returned if nosearchwrap is set, and the last search command encountered the end of the 
edit buffer. 

ERR_FIND_NO T_FOUND 

Returned if the last search command didn’t find the string. 

ERR_FIND_TOP_OF_FILE 

Returned if nosearchwrap is set, and the last search command encountered the top of the 
edit buffer. 

ERR_INVALID_COMMAND 

Returned if the last command was invalid. 

ERR_INVALID_SET_COMMAND 

Returned if the last set command was an invalid one. 

ERR_NO_ERR Returned if the last operation was a success. 
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ERR_NO_FILE_NAME 

Returned if you attempt to write a file with no file name. 
ERR_NO_MORE_ UNDOS 

Returned if the last undo command didn’t undo anything. 
ERR_NO_SUCH_DRIVE 

Returned if the last cd command was to a non-existent drive. 
ERR_NO_SUCH_LINE 

Returned if the last movement command went to an invalid line. 

ERR_READ_ONLY_FILE 

Returned if you attempt to modify a read only file. 

NEW_FILE Value of lastrc in a read hook script, if the file just edited was a new file. 

NO_VALUE_ENTERED 

Returned if an input command was cancelled by the user. 
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1 Overview 


1.1 Introduction 


The Open Watcom Debugger is a powerful debugging tool that helps you analyse your programs and find 
out why they are not behaving as you expect. It allows you to single step through your code, set break 
points based on complex conditions, modify variables and memory, expand structures and classes and much 
more. With the debugger you can debug programs that run on the following platforms: 

•DOS 

• CauseWay DOS Extender 

• Tenberry Software DOS/4G Extender 

• Phar Lap DOS Extender 

• Windows 3.x 

• Windows NT/2000/XP 

• Windows 9x 

• 16 and 32-bit OS/2 

• GNU/Linux 

• QNX4 

• QNX 6 (Neutrino) 

• Novell NetWare 


1.2 New Features 

The latest version of the debugger contains many new features that you should know about. 

1.2.1 User Interface 

The debugger’s user interface has been redesigned. There are GUI versions of the debugger that run under 
Windows 3.x, Windows NT/2000/XP, Windows 9x, and 32-bit OS/2. There are also character mode 
versions that run under DOS, Windows 3.x, OS/2, Linux and QNX 4. All versions share a common user 
interface incorporating powerful features like context sensitive menus, eliminating the need for command 
oriented debugging. 

1.2.2 Reverse Execution 

The debugger keeps a history of your interactions that modify the state of the program you are debugging. 
This includes the effects of statements in your program that you trace. The size of this history is limited 
only by available memory. Undo and Redo allow you to step backward and forward through this history. 
This allows you to reverse the effects of tracing over simple statements in your program. You can also 
reverse any accidental interactions that affect your program’s state. See "The Undo Menu" on page 54. 
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1.2.3 Replay 

The debugger keeps a history of all interactions that affect the execution of your program such as setting 
break points and tracing. Replay allows you to restart the application and run the application back to a 
previous point. This is particularly useful when you accidentally trace over a call. This replay information 
may be saved to a file in order to resume a debugging session at a later date. See "The Replay Window" on 
page 56. 

1.2.4 Stack Unwinding 

You can navigate up and down the program’s call stack to see where the currently executing routine was 
called from. As you do this, all other windows in the debugger update automatically. Local variables in 
the calling routines will be displayed along with their correct values. See "The Undo Menu" on page 54. 

1.2.5 Simplified Breakpoints 

The debugger allows you to set breakpoints when code is executed or data is modified. These breakpoints 
may be conditional based on an expression or a countdown. Simple breakpoints are created with a 
keystroke or single mouse click. More complex breakpoints are entered using a dialog. See "The 
Breakpoint Dialog" on page 75. 

1.2.6 Context Sensitive Menus 

Context sensitive menus are present in each debugger window. To use them, you select an item from the 
the screen using the right mouse button. A menu containing a list of actions appropriate for that item is 
displayed. You can use this capability to perform actions such as displaying the value of an expression 
which you have selected from the source window. 

1.2.7 Buttons 

The debugger contains small buttons that appear on the left side of some windows. These buttons are 
shortcuts for the most common operations. For example, you can set and clear a breakpoint by clicking on 
the button to the left of a source line. 


1.3 Common Menu Items 


The debugger’s context sensitive menus contain many useful menu items. Each of these items behave 
differently depending upon the selected item. A description of some of the commonly found menu items 
follows: 

Inspect Inspect displays the selected item. The debugger determines how to best display the 

selected item based on its type. If you inspect a variable or an expression, the debugger 
opens a new window showing its value. If you inspect a function, the debugger positions 
the source code window at the function definition. If you inspect a hexadecimal address 
from the assembly window, a window showing memory at that address is opened, and so 
on. Experimenting with inspect will help you learn to use the debugger effectively. 


4 Common Menu Items 




Overview 


Modify 

New 

Delete 

Source 

Assembly 

Functions 

Watch 

Break 

Globals 

Show 

Type 


Modify lets you change the selected item. You will normally be prompted for a new value. 
For example, select the name of a variable from any window and choose Modify to change 
its value. 

New adds another item to a list of items displayed in a window. For example, choosing 
New in the Break Point window lets you create a new breakpoint. 

Delete removes the selected item from the window. For example, you can use Delete to 
remove a variable from the Watches window. 

Source displays the source code associated with the selected item. The debugger will 
reposition the source code window at the appropriate line. Selecting a module name and 
choosing Source will display the module’s source code. 

Assembly positions the assembly code window at the code associated with the selected 
item. 

Functions shows a list of all functions associated with the selected item or window. For 
example, choose Functions in the source window to see a list of all functions defined in that 
module. 

Watch adds the selected variable or expression to the Watches window. This allows you to 
watch its value change as the program runs. Note that this is not a watchpoint. Execution 
will not stop when the variable changes. See the chapter entitled "Breakpoints" on page 
71 for information about setting watchpoints. 

Break sets a breakpoint based on the selected item. If a variable is selected, the program 
will stop when the variable is modified. If a function is selected, the program will stop 
when the function executes. 

Globals shows a list of global variables associated with the selected item. 

Show will present a cascaded menu that let’s you show things related to the selected item. 
For example, you can use Line from the Show menu in the source code window to see the 
line number of the selected line. 

Type will present a cascaded menu that allows you to change the display type of the 
window or selected item. 
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2 Preparing a Program to be Debugged 


Before you can debug a program, you must put debugging information into the code. 

There are three different formats of debugging information that can be put into the code — "Watcom", 
"DWARF" or "CodeView". Starting with version 11.0 (and continuing in the Open Watcom 1.0 and later 
compilers), the default format is "DWARF". In earlier releases, the default was "Watcom". Although the 
debugger supports all three formats, it is best if you allow the default format to be generated. 

To produce an executable that has debugging information, you need to: 

1. specify the correct compiler options when you compile, and 

2. specify the correct linker options when you link. 

During development, use the c/2 option of the compiler and use the debug all directive at the beginning of 
your linker command line or at the beginning of your linker directive file. This will ensure that maximum 
debugging information is available during your debugging session. Change to the dl option when you need 
to create a distribution version of your product. This is necessary since the c/2 option disables most 
compiler optimizations, whereas dl will not affect the quality of generated code. During production, you 
can use the linker’s symfile option to put the dl debugging information into a separate file. This lets you 
distribute a production quality executable yet still have the luxury of source line debugging when bugs are 
repotted. 

2.1 Compiler Debugging Options 

d0 The dO option will generate no debugging information. This is the default option. 

dl The dl option will generate debugging information for global symbols and line numbers. 

dl+ The dl+ option will generate debugging information for global symbols and line numbers, 

and typing information for local structs and arrays. 

d2 The d2 option will generate the most debugging information that is normally needed, 

including global information, line numbers, types, and local variables. 

d2i The c/2/ option is identical to c/2 but does not permit inlining of functions. This option can 

result in larger object and/or executable files (we are discussing both "code" and "file" size 
here). 

d2t The d2t option is identical to c/2 but does not include type name debugging information. 

This option can result in smaller object and/or executable files (we are discussing "file" size 
here). 

d3 The dl option will generate all debugging information generated by c/2. In addition, it will 

generate information about all types defined in a compilation unit, regardless of whether 
they are used in that compilation unit. This option will create very large objects and 
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executable files. Do not use it unless you want to have access to types that have no 
variables associated with them. 


2.2 Linker Debugging Options 

The linker is the tool that puts together a complete program and sets up the debugging information for all 
the modules in the executable file. There is a linker directive that tells the linker when it should include 
debugging information from the modules. 

The directive you should use in the general case is: 

DEBUG ALL 

This directive will include all debugging information in the default format. You should always use this 
directive except in the rare cases when you need debugging information in a format other than the default. 

For "DWARF" format debugging information, the directive is: 

DEBUG DWARE 

For "Watcom" format debugging information, there are two levels of debugging information that you 
should collect during the link. They are: 

DEBUG WATCOM LINES global names, source line numbers 

DEBUG WATCOM ALL global names, source line numbers, local variables, typing information 

Linker DEBUG directives are position dependent so you must make sure that the directive precedes the 
object files and libraries that require debugging information. 

For instance, if the file "mylink.lnk" contained: 

# 

# invoke with: wlink @mylink 

# 

file main 

debug watcom lines 
file input, output 
debug watcom all 
file process 

then the files input and output will have global names and source line information available during 
debugging. All debugging information in the file process is available during debugging. No information is 
available for main except global names. 

If you use a DEBUG directive anywhere, all files, including main, will have global name information. 
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2.3 Debugger Settings 

You may encounter problems if the debugger does not know where to find the source code associated with 
your executable. The name of the source file included in the debugging information is the path and the 
original name from the compiler’s command line. If the original filename is no longer valid (i.e., you have 
moved the source to another directory), you must tell the debugger where to find the source files by 
choosing Source Path from the File menu. 
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3 Starting Up the Debugger 


The following topics are discussed: 

• "Open Watcom Debugger Command Line" 

• "Common Switches" on page 16 

• "DOS and Windows Options" on page 18 

• "DOS Specific Options" on page 19 

• "Windows Specific Options" on page 20 

• "Linux Options" on page 20 

• "QNX Options" on page 21 

• "Environment Variables" on page 21 

3.1 Open Watcom Debugger Command Line 

There are several versions of the debugger. 
binw\wd.exe This is the DOS character-mode debugger. 
binw\wdc.exe This is the Windows 3.x character-mode debugger. 
binw\wdw.exe This is the Windows 3.x windowed (GUI) debugger. 
binnt\wd.exe This is the Windows NT/9x character-mode debugger. 
binnt\wdw.exe This is the Windows NT/9x windowed (GUI) debugger. 
binp\wd.exe This is the OS/2 character-mode debugger. 
binp\wdw.exe This is the OS/2 windowed (GUI) debugger. 
wd This is the name of the debugger used on UNIX platforms. 

See the sections entitled "Operating System Specifics" on page 109 and "Remote Debugging" on page 89 
for information on which version to select for your situation. 

On the debugger command line, you can specify options that you want to use during your debugging 
session. Acceptable option short forms are indicated in capital letters. For example, the /TRap option may 
be shortened to /tr. 
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3.2 Common Switches 

The following switches are applicable to all operating systems. 

/TRap=trap _Jile[;trap _parm] 

specifies an executable helper program that the debugger uses to control the application 
being debugged, or to communicate across a remote link. It is called a "trap file" since the 
interrupts used for debugging are sometimes called "traps". The trap option selects the 
appropriate trap file to use. This option must be specified when remote debugging, 
debugging DOS extender applications or debugging OS/2 exception handlers. 

The remote trap files themselves have startup parameters. This is specified following the 
semi-colon. See "Remote Debugging" on page 89. Normally you do not have to specify a 
trap file. If you do not specify the trap option, the default trap file that supports local 
debugging is loaded. There are several exceptions. 

1. To debug a CauseWay 32-bit application, you must use /TRAP=CW. 

2. To debug a Tenberry Software 32-bit DOS/4G(W) application, you must use 
/TRAP=RSI. 

3. To debug a Phar Lap 32-bit application, you must use /TRAP=PLS. 

4. To debug an OS/2 exception handler, you must use /TRAP=STD 2 which tells 
the debugger to catch exceptions only on the second chance (normally it would 
be the debugger that traps the exception). 

5. To debug an OS/2 16-bit application under Phar Lap's RUN286 DOS extender, 
you must use /TRAP=STD16. 

/LInes=n controls the number of lines used by a character mode debugger. The number of lines 

available depends on the operating system and your video card. The values 25, 43 and 50 
are often supported. 

/COlumns=n controls the number of columns used by a character mode debugger. The number of 

columns available depends on the operating system and your video card. If your system 
does not support the requested number of columns, this option is ignored 

/Invoke=file may be used to specify an alternate name for the debugger configuration file which is to be 
used at start-up time. The default file name is "WD.DBG". Debugger configuration files 
are found in the current directory or one of the directories in your PATH. 

/NOInvoke specifies that the default debugger configuration file is not to be invoked. 

/NOMouse requests that the debugger ignore any attached mouse. This may be necessary if you are 

trying to debug mouse events received by your application. This option ensures that the 
debugger will not interfere with the mouse. 

/DYnamic=number 

specifies the amount of dynamic storage that the debugger is to set aside for its own use on 
startup. The default amount that is set aside is 500K bytes. The larger the amount, the less 
memory will be available for the application to be debugged. You only need to use this 
option if the debugger runs out of memory, or is causing your application to run out of 
memory. If you are using the remote debugging feature, the debugger will use as much 
available memory as available. 
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/NOExports specifies that no exports (system symbols) should be loaded. It helps to speed up load time 
when debugging remotely and marginally so when debugging locally. 

/LOcalinfo=local_Jile 

is used primarily, but not exclusively, in conjunction with the remote debugging 
capabilities of the debugger. It causes the debugger to use one or more local files as 
sources of debugging information if the right conditions are met. When the debugger 
observes that an executable file or Dynamic Link Library (DLL) is being loaded with the 
same name (i.e., the path and extension have been stripped) as one of the /localinfo files, 
then the named local file is used as a source of debugging information. The named file can 
be an executable file, a DLL file (.dll), a symbolic information file (.sym), or any other file 
with debugging information attached. 

Example: 

wd /local=c:\dlls\mydll.sym /local=c:\exes\myexe.exe /tr=par myexe 


In the above example, the debugger would obtain debugging information for any 
executable or DLL called myexe or mydll from c : \exes\myexe . exe or 
c : \dlls\mydll. sym respectively. Note that no path searching is done for local files. 
The debugger tries to open the file exactly as specified in the localinfo option. 

See the section entitled "Remote Debugging" on page 89 for an explanation of remote 
debugging. 

/DOwnload specifies that executable file to be debugged is to be downloaded to the task machine from 
the debugger machine. The debugger searches for the executable file in the local path, and 
downloads it to the debug server’s current working directory on the remote machine before 
starting to debug. Debugging information is not downloaded, but is obtained locally, as in 
the localinfo option. Note: Only the executable is downloaded; any required DLLs must 
be present on the remote machine. Downloading is relatively fast if you are using one of 
the TCP/IP (TCP) or Netware (NOV) remote links. Be sure to specify the file extension if 
it is not ".exe". 

Example: 

wd /tr=nov;john /download sample.exe 
wd /tr=nov;john /download sample.nlm 

The debugger does not erase the file when the debugging session ends. So if you debug the 
application again, it will check the timestamp, and if the file is up-to-date, it doesn’t bother 
re-downloading it. 

See the section entitled "Remote Debugging" on page 89 for an explanation of remote 
debugging. 

/REMotefiles is used in conjunction with the remote debugging capabilities of the debugger. It causes the 
debugger to look for all source files and debugger files on the remote machine. When 
remotefiles is specified, all debugger files (except "trap" files) and application source files 
are opened on the task machine rather than the debugger machine. The trap file must be 
located on the debugger machine. 

The PATH environment variable on the task machine is always used in locating executable 
image files. When remotefiles is specified, the debugger also uses the task machine’s 
PATH environment variable to locate debugger command files. See the section entitled 
"Remote Debugging" on page 89 for an explanation of remote debugging. See the section 
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entitled "Specifying Files on Remote and Local Machines" on page 100 for an explanation 
of remote and local file names. 

/NOFpu requests that the debugger ignore the presence of a math coprocessor. 

/NOSYmbols requests that the debugger omit all debugging information when loading an executable 
image. This option is useful if the debugger detects and tries to load debugging 
information which is not valid. 

/DIp=dipname used to load a non-default Debug Information Processor (DIP). This option is generally not 
needed since the debugger loads all DIPs that it finds by default. See "The Images 
Window" on page 49. 

3.3 DOS and Windows Options 

The following switches apply to the DOS (binwYwd) and Windows 3.x character-mode (binwYwdc) 

debuggers. Refer to the sections called "DOS Specific Options" on page 19 and "Windows Specific 

Options" on page 20 for more switches relating to these environments. 

/Monochrome When two display devices are present in the system, this option indicates that the 

Monochrome display is to be used as the debugger’s output device, leaving the Color 
display for the application to use. Use this option in conjunction with the Two option 
described below. 

/Color, /Colour 

When two display devices are present in the system, this option indicates that the Colour 
display is to be used as the debugger’s output device. This option is used in conjunction 
with the Two option described below. 

/Ega43 When an Enhanced Graphics Adapter (EGA) is present, 43 lines of output are displayed by 

a character mode debugger. 

/VgaSO When a Video Graphics Array (VGA) is present, 50 lines of output are displayed by a 

character mode debugger. 

/Overwrite specifies that the debugger’s output can overwrite program output. In this mode, the 
application and the debugger are forced to share the same display area. 

Do not use this option if you wish to debug a DOS graphics-mode application. 

/Two specifies that a second monitor is connected to the system. If the monitor type 

(Monochrome, Color, Colour, Ega43, Vga50) is not specified then the monitor that is not 
currently being used is selected for the debugger’s screen. If the monitor type is specified 
then the monitor corresponding to that type is used for the debugger’s screen. This option 
may be used when debugging a DOS graphics-mode application on the same machine 
and a second monitor is available. 
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3.4 DOS Specific Options 

Use the following switches for the DOS debuggers. For more DOS options, refer to the section called 
"DOS and Windows Options" on page 18. 

specifies that page 0 of screen memory is to be used for the application’s screen and that 
page 1 of screen memory should be used for the debugger’s screen. This option may be 
selected when using a graphics adapter such as the CGA, EGA or VGA. Using the Page 
option results in faster switching between the application and debugger screens and makes 
use of the extra screen memory available with the adapter. This is the default display 
option. Do not me this option if you wish to debug a DOS graphics-mode application. 

specifies that the application’s screen memory and the debugger’s screen memory are to be 
swapped back and forth using a single page. The debugger allocates an area in its own data 
space for the inactive screen. This reduces the amount of memory available to the 
application. It also takes more time to switch between the application and debugger 
screens. This option MUST be used when debugging a DOS graphics-mode application 
and a second monitor is not available. 

The default display options are: 

1. If you have a two display system, the debugger uses both displays with the 
program output appearing on the active monitor and the debugger output 
appearing on the alternate monitor. In other words, the Two option is selected by 
default. 

2. If you have one of the CGA, EGA or VGA graphics adapters installed in your 
system then the debugger selects the Page option by default. 

3. Under all other circumstances, the debugger selects the Swap option by default. 

ICHecksize-n umber 

specifies the minimum amount of storage, in kilobytes, that the debugger is to provide to 
DOS for the purpose of spawning a program while the debugger is active. This option is 
useful when the application that is being debugged uses up most or all of available 
storage, leaving insufficient memory to spawn secondary programs. In order to provide 
the requested amount of free memory to DOS, the debugger will checkpoint as much of the 
application as required. 

Checkpointing involves temporarily storing a portion of the memory-resident application 
on disk and then reusing the part of memory that it occupied for the spawned program. 
When the spawned program terminates, the checkpointed part of the application is restored 
to memory. 

The default amount is OK bytes. In this case, the spawned program may or may not be run 
depending on how much free storage is available to DOS to run the program. 

Warning: If the application being debugged installs one or more interrupt handlers, 

the use of this option could hang your system. Your system could lock up 
if the debugger checkpoints a portion of the application's code that contains 
an interrupt handler. 


/Page 


/Swap 


/NOCHarremap 

turns off the character re-mapping that the DOS debugger uses for displaying dialogs and 
window frames. Use this option when trying to debug in an environment where 
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character remapping is not available. Windowed DOS boxes under OS/2 do not support 
character re-mapping. 

/NOGraphicsmou.se 

Turn off the graphics mouse emulation code that makes the mouse cursor look like an 
arrow instead of a block. Use this option if the mouse cursor appears as 4 line drawing 
characters instead of an arrow. 

3.5 Windows Specific Options 

Use the following switches for the Windows character-mode debugger. Refer to the section called "DOS 
and Windows Options" on page 18 for more Windows options. 

/Fastswap specifies that Windows 3.x screen memory and the debugger’s screen memory are to be 
swapped back and forth using a technique that is faster than the default method of screen 
swapping but not guaranteed to work for all video adapters. This option applies to 
Windows 3.x only. By default, the Windows 3.x version of the debugger uses a more 
conservative (and slower) method that works with all video adapters. 

3.6 Linux Options 

You can use the following switch for the Linux debugger. 

-Console=console_spec 

specifies the virtual console to use for debugger windows. This may be a console number 
as in the following example. 

Example: 

-console=2 

You may also use a full device name. 

Example: 

-console=/dev/tty 

In this case, the debugger will use that device for its input and output. The 
debugger/application screen flipping features will be disabled. 

You can also optionally follow the device name with a colon and a terminal type. 

Example: 

-con=/dev/tty:vt240 

This will let the debugger know what kind of terminal it’s talking to so it can initialize the 
user interface appropriately. 

-COlumns=n specifies the number of columns of the screen/window that the debugger should attempt to 
establish. 
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-XConfig=string 

specifies a set of X Windows configuration options to pass to xterm. The following 
example sets the xterm font size to 12 point. 

Example: 

-xc=-fs -xc=12 


3.7 QNX Options 

You can use the following switch for the QNX debugger. 

-Console=console_spec 

specifies the virtual console to use for debugger windows. This may be a console number 
as in the following example. 

Example: 

-console=2 

You may also use a full device name. 

Example: 

-console=//23/dev/serl 

In this case, the debugger will use that device for its input and output. The 
debugger/application screen flipping features will be disabled. 

You can also optionally follow the device name with a colon and a terminal type. 

Example: 

-con=/dev/ttypl:vt240 

This will let the debugger know what kind of terminal it’s talking to so it can initialize the 
user interface appropriately. 

-COlumns-n specifies the number of columns of the screen/window that the debugger should attempt to 
establish. 

-XConfig=string 

specifies a set of X Windows configuration options to pass to xqsh. 


3.8 Environment Variables 


You can use the WD environment variable to specify default options to be used by the debugger. Once you 
have defined the environment variable, those options are used each time you start the debugger. 


Environment Variables 
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3.8.1 WD Environment Variable 

If the specification of an option involves the use of an "=" character, use the "#" character in its place. This 
is required by the syntax of the "SET" command. Options found in the environment variable are processed 
before options specified on the command line. The following example illustrates how to define default 
options for the debugger: 

Example: 

C>set wd=/swap/lines#50 

3.8.2 WD Environment Variable in Linux 

The following example illustrates how to define default options for the debugger under Linux: 

Example: 

$ export WD="-lines=50 -columns=100" 

Under Linux, care must be taken to specify the environment variable name entirely in uppercase letters. 

3.8.3 WD Environment Variable in QNX 

The following example illustrates how to define default options for the debugger under QNX: 

Example: 

$ export "WD=-nofpu -console=3" 

Under QNX, care must be taken to specify the environment variable name entirely in uppercase letters. 
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4 The Open Watcom Debugger Environment 


This chapter describes the interactions you need in order to use the debugger. 

4.1 Debugger Windows 

The debugger displays its information in windows. Both the character and the GUI-based debuggers use 

similar conventions for window manipulation. 

4.1.1 Window Controls 

Each window has the following controls 

Minimize, Maximize, Restore 

You can control the size of each window using the Minimize, Maximize, and Restore 
buttons. The buttons appear on the top right corner of the window. The Minimize button is 
the down arrow. When you click on the down arrow, the window becomes an icon at the 
bottom of the screen. The Maximize button is the up arrow. When you click on the up 
arrow, the window fills the whole screen. The Restore button appears only when the 
window is maximized. It is an up and down arrow. Click on the Restore button to put the 
window back to its original size. 

Close Each window has a Close button in the top left corner. Double-click on this button to close 

the window. 

System Menu The System Menu contains menu items that operate on the window. It contains: 

• Restore 

• Move 

• Size 

• Minimize 

• Maximize 

You can activate the System Menu of the main window by clicking once on the System 
Menu button (top, left-hand corner) or by typing ALT-Space. For Microsoft Windows, you 
can type ALT-Hyphen to activate a child window’s System Menu. 

Windows that contain information that cannot fit in the window have scroll bars. Use the 
scroll bars to reposition the window so the information you want to see is visible. The 
small box in the scroll bar indicates the current scroll position in the window. 

Each window is titled so that you know what information it contains. The title appears in 
the bar at the top of the window. 

Many windows have small buttons on the left hand side. These buttons are short forms for 
performing the most common operations. 


Scroll Bars 

Title 

Buttons 
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4.1.2 The Current Window 

The current window is the one whose title bar is coloured. Press CTRL-TAB to move from window to 
window. 

4.1.3 Controlling the Size and Location of Windows 

The following window operations are possible. 

• "Moving Windows" 

• "Resizing Windows" 

• "Zooming Windows" 

• "Context Sensitive Pop-up Menus" 

• "Text Selection" on page 27 

4.1.3.1 Moving Windows 

To move a window, click in the Title bar and drag it to a new location. You can also choose Move from the 
System Menu and use the cursor keys to reposition the window, pressing ENTER when the window is in 
the right spot. 

4.1.3.2 Resizing Windows 

In the GUI-based version of the debugger, you can resize a window’s width, height, or both. Refer to the 
system documentation for details. 

In the character-based version of the debugger, you can only resize a window from the corners. Move the 
cursor to any corner of the window. Click and drag the mouse to resize the window. 

You can also choose Size from the System Menu to change the size of a window. Use the cursor keys to 
resize the window, press ENTER when the window is the right size. 

4.1.3.3 Zooming Windows 

Choose Zoom from the Window menu to toggle a window between its maximized and normal sizes. 

4.1.3.4 Context Sensitive Pop-up Menus 

The debugger has context sensitive pop-up menus for each window in the application. You can access the 
menu either by pressing the right mouse button in the window or by typing the period (.) key. You can 
then choose a menu item by typing the highlighted character or by clicking the mouse on it. 

If you have memorized the highlighted menu character, you can bypass the menu and activate the menu 
item directly by pressing the CTRL key in conjunction with that character. The items that appear in the 
menu depend on the current window. These menus are described in detail throughout this document. 
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Note The Action item in the main menu is identical to the the context sensitive pop-up menu for 

the current window and may be used instead of pop-up menus. 

For more information on the choices presented in the pop-up menus, see the section entitled "Variable and 
Watch Windows" on page 61. 


4.1.3.5 Text Selection 

Some windows, such as the Source and Assembly windows, allow you to select text. For example, you 
might want to select a variable name or expression. Menu items will act on the selected item. 

You can select text with either the left or right mouse button. If you use the right button, the pop-up menu 
appears when you release the button. With the keyboard, hold SHIFT while using the cursor keys. You 
can select a single character and the debugger will automatically extend the selection to include the entire 
surrounding word. 


4.2 Menus 

At the top of the debugger window are a number of menu items. You can select a menu item with the 
mouse or by pressing ALT and the highlighted character from the menu title. 

Many menu items have accelerators or keyboard equivalents. They appear to the right of the menu item. 

As you learn the debugger, take time to learn the accelerators. They will help you to use the debugger more 
effectively. 

4.3 The Toolbar 



Figure 1. The Debugger Window 


The Toolbar 
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The Toolbar appears under the menu in the GUI-based debugger. The buttons in the Toolbar are equivalent 
to menu selections. There are eight buttons in the toolbar. Listed from left to right, they are: 

• Go from the Run menu 

• Step Over from the Run menu 

• Trace Into from the Run menu 

• Until Return from the Run menu 

• Undo from the Undo menu 

• Redo from the Undo menu 

• Unwind Stack from the Undo menu 

• Rewind Stack from the Undo menu 

• Home from the Undo menu 

See the sections entitled "The Run Menu" on page 53 and "The Undo Menu" on page 54 for details. 


4.4 Dialogs 



Figure 2. A Typical Dialog 

Dialogs appear when you choose a menu item that does not perform an immediate action. They allow you 
to make choices and set options. The dialogs contain the following: 

Edit fields These are fields in which you can type information. 

Buttons You can click on buttons to perform actions. 

Default button The default button in a dialog is highlighted. You can select this button by pressing 
ENTER. 
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Cancel All dialogs contain a cancel button. Choose the Cancel button or press ESC to leave a 

dialog without saving or implementing changes you have made to the dialog. 

Check Boxes Check boxes are used to control settings in the debugger. Click on the field, or TAB to it 
and press SPACE to toggle the option between on and off. 

Radio Buttons Radio buttons present a set of mutually exclusive choices. Click on a radio button to turn it 
on or press TAB to move to the group of radio buttons and use the cursor keys to select a 
radio button. If this does not work, use the accelerator key to turn on the desired radio 
button. Only one radio button is on at all times. When you select a different radio button, 
the currently selected one is turned off. 

List boxes A list box contains a list of applicable items. 

Drop-down List boxes 

A drop down list box is a list that does not appear on the screen until you click on the down 
arrow on the right of the box. You may then select from a list of options. 


4.5 Accelerators 

Accelerators are keys that you can press in place of selecting a menu item or typing commands. The 
debugger comes with a standard set of accelerators that you can view by choosing Accelerators from the 
Window menu. 

If you are used to the CodeView debugger, you should be comfortable with the Open Watcom Debugger’s 
default set of accelerators. If you are used to using Turbo Debugger, you can select accelerators which are 
similar to its accelerator definitions. To select Turbo accelerators, choos & Accelerator from the Window 
menu then select TD Keys from the Action menu. 


4.5.1 Default Accelerators 

The default accelerators are: 


/ 

ALT-/ 

CTRLA 

9 

FI 

F2 

F3 

F4 

F5 

F6 

F7 

F8 

F9 

F10 

SHIFT-F9 

CTRL-F4 


Search/Find... 

Search/Next 

Search/Next 

add a new expression to the Watch window 

invoke help facility 

Data/Registers 

toggle between source level and assembly level debugging 

Window/Application 

Run/Go 

Window/Next 

Run/Run to Cursor 

Run/Trace Into 

Break/Toggle 

Run/Step Over 

add a new item to the Watch window 
close the current window 
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CTRL-F5 

CTRL-F6 

CTRL-F9 

CTRL-F10 

ALT-F10 

CTRL-TAB 

CTRL-LEFT 

CTRL-RIGHT 

CTRL-UP 

CTRL-DOWN 

CTRL-BACKSPACE 

ALT-1 

ALT-2 

ALT-3 

ALT-4 

ALTS 

ALTS 

ALTS 

ALTS 

ALTS 

CTRL-z 

SPACE 


n 

N 

u 

U 

b 

e 

g 

h 


restore the current window to its normal size 
rotate the current window 
minimize the current window 
maximize the current window 

display the floating pop-up menu for the current window 

rotate the current window 

Undo/Undo 

Undo/Redo 

Undo/Unwind Stack 

Undo/Rewind Stack 

Undo/Home 

Data/Locals 

Data/Watches 

Code/Source 

File/View... 

Data/Memory at... 

Data/Memory at... 

Data/Registers 
Data/80x87 FPU 
File/Command... 

Window/Zoom 
Run/Step Over 

display the floating pop-up menu for the current window 
File/Command... 

Search/Match 

Search/Next 

Search/Previous 

Undo/Undo 

Undo/Redo 

Break/At Cursor 

Data/Memory at... 

Run/Execute to... 
move cursor left one 


i 

j 

k 

l 

t 

x 


Run/Trace Into 
move cursor down one 
move cursor up one 
move cursor right one 
Break/Toggle 
Run/Next Sequential 


4.5.2 Turbo Emulation Accelerators 

The Turbo emulation accelerators are: 


F2 

Break/Toggle 

F3 

Code/Modules 

F4 

Run/Run to Cursor 

F5 

Window/Zoom 

F6 

Window/Next 

F7 

Run/Trace Into 

F8 

Run/Step Over 
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ALT-F2 

ALT-F3 

ALT-F4 

ALT-F5 

ALT-F7 

ALT-F8 

ALT-F9 

ALT-F10 

CTRL-F2 

CTRL-F4 

CTRL-F7 


4.6 The File Menu 

The File menu contains items that allow you to perform file operations, such as: 

Open Start debugging a new program, or to restart the current program with new arguments. 

View Display a file in a window. 

Command Enter a debugger command. For a description of debugger commands, refer to the section 
entitled "Debugger Commands" on page 145. 

Options Set the global debugging options. For a full description of these options, refer to the 

section entitled "The Options Dialog" on page 32. 

Window Options 

Set the options for the debugger’s various windows. For a full description of these options, 
refer to the section entitled "The Window Options Dialog" on page 33. 

Save Setup Save the debugger’s current configuration. This saves the positions and sizes of all 

windows as well as all options and settings. By default, this information is saved into the 
file setup . dbg, however, you can save this information into another file to create 
alternate debugger configurations. 

Load Setup Foad a configuration previously saved using Save Setup. 

Source Path Modify the list of directories which will be searched when the debugger is searching for 
source files. 

System The menu item appears only in the character-based version of the debugger. It spawns a 

new operating system shell. 

Exit Close the debugger. 


Run/Go 

Break/New... 

close the current window 

Undo/Undo 

Window/Application 

trace one assembly instruction 

Run/Until Return 

Run/Execute to... 

activate the pop-up menu for the current window 
Run/Restart 

open a new Watch window 

add a new item to the Watch window 
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4.6.1 The Options Dialog 



Figure 3. The Options Dialog 

The Options dialog allows you to change the following settings: 

Auto configuration save When this option is on, the debugger automatically saves its configuration upon 
exit. 

Warning Bell When this option is on, the debugger will beep when a warning or error is issued. 

Implicit Invoke If this option is on, the debugger will treat an unknown command as the name of a 

command file and automatically try to invoke it. If this option is off, you must use the 
invoke command to invoke a command file. 

Under UNIX, a conflict is possible when Invoke is on. A path specified for a command file 
name is confused with the short form of the DO command (/). A similar problem occurs 
under DOS, OS/2, Windows 3.x, Windows NT, or Windows 95 when a drive specifier 
forms part of the file name. 

Recursion Check Use this option to control the way tracing over recursive function calls is handled. When 
this option is on, and you trace over a function call, the debugger will not stop if the 
function executes recursively. 

Break on write (not change) Use this option (if available with the selected trap) to enable true 

break-on-write breakpoints. This will break on any write access; not just when a watch 
point has changed. 

Screen flip on execution Use this option to control whether the debugger automatically flips the display to 
the application’s screen upon execution. Leave this option on if you are using the 
character mode debugger to debug a Windows 3.x application. 

Ignore case This option controls whether or not case is ignored or respected when the debugger is 
searching for a string. 
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Do not expand hex numbers This option controls whether or not hexadecimal values are displayed in their 
natural size (zero preceded) or displayed in their most compact form. The default is to 
display the value in its full natural size. 

Default Radix Use this option to define the default radix used by the debugger. The debugger associates a 
radix with each action automatically. For example, if you are asked to enter an address, the 
debugger assumes base 16. If you double click on a decimal value, you will be prompted 
for a decimal replacement value but there are occasions when the debugger must use the 
default radix. If you add an arbitrary expression to the Watches window, the default radix 
is used when interpreting that expression. You can specify any radix between 2 and 36. 

Double click mS This option sets the amount of time in milliseconds allowed between two clicks for the 
debugger to accept it as a double click. Enter a larger value if you are having trouble with 
double clicks. 

4.6.2 The Window Options Dialog 



Figure 4. The Window Options Dialog 

Use the Window Options dialog to define options related to the debugger’s various windows. All of these 
options appear in a dialog when you choose Window Options from the File menu. 

The Window Options dialog allows you to set options for the following windows: 

• Source 

• Modules 

• Functions 

• Assembly 

• Watches 

• Locals 

• File Variables 

• Globals 
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• Variable 


4.6.2.1 The Assembly Options 

The Assembly options allow you to define how your assembly code appears. You can set the following 
options: 

Show Source Turn on this option if you want source code intermixed with assembly code. 

Hexadecimal Turn on this option if you want immediate operands and values to be displayed in 
hexadecimal. 

4.6.2.2 The Variables Options 

Use the Variable options to set display options and to specify which members of a class you want displayed 
when a structure or class is expanded. You can set: 

Protected Display protected members in expanded classes. 

Private Display private members in expanded classes. 

Whole Expression 

Turn this option on to show the whole expression used to access fields and array elements 
instead of just the element number or field name itself. 

Display C++ member functions in expanded classes. 

Display inherited members in expanded classes. 

Display the compiler-generated members. You will usually not want this option turned on. 

Display members of the 'this' pointer as if they were local variables declared within the 
member function. 

Display static members. 


Functions 

Inherited 

Compiler 

Members 

Static 


4.6.2.3 The File Options 

You can set the display width of a tab in the File options section. This value defaults to 8 spaces. 


4.6.2.4 The Functions and Globals Options 

For both Functions and Global Variables windows, you can turn on the Typed Symbols option. This 
restricts the list of symbols to those that are defined in modules compiled with full debugging information 
(d2 option). 


4.6.2.5 The Modules Options 

You can turn on Show All to allow the Modules window to display all modules in your program, not just 
those which have been compiled with the d2 option. 
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4.7 The Code Menu 

The Code menu allows you to display windows that show different information related to your code. It 

contains the following items: 

Source Open the Source window. It shows source code at the currently executing location. See 

"The Source Window" on page 44. 

Modules Display a sorted list of modules contained in the current program. See "The Modules 

Window" on page 46. 

Functions Open a sorted list of all functions in the program. See "The Functions Window" on page 
48. 

Calls Open the Call History window. This window displays the program’s call stack. See "The 

Calls Window" on page 57. 

Assembly Open the Assembly window. It shows assembly code at the currently executing location. 
See "The Assembly Window" on page 82. 

Threads Open a list of all threads in your program and their current state. See "The Thread 

Window" on page 57. 

Images Open a list of the executable images which are related to the program being debugged. 

This includes a list of all loaded DLLs. See "The Images Window" on page 49. 

Replay Open the program execution Replay window. This window allows you to restart your 

application and replay your debugging session to any point. See "The Replay Window" on 
page 56. 


4.8 The Data Menu 

The Data menu contains a number of windows that you can open to view the state of your program’s data. 

It contains the following items: 

Watches Open a Watches window. You can add and delete variables from the Watches window and 

use it to evaluate complex expressions and perform typecasting. See "Variable and Watch 
Windows" on page 61. 

Locals Open a Locals window. It displays the local variables of the currently executing function. 

See "Variable and Watch Windows" on page 61. 

File Variables Open a File Variables window. It contains a list of variables defined at file scope in the 
current module. See "Variable and Watch Windows" on page 61. 

Globals Open a sorted sorted list of all global variables in your program. Values are not displayed 

since it would make this window very expensive to update, but you can select variables 
from this window and add them to a Watches window. See "The Globals Window" on 
page 47. 
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Registers Displays the CPU registers and their values. See "The CPU Register Window" on page 81. 

FPU Registers Displays the FPU registers and their values. See "The FPU Registers Window" on page 84. 

MMX Registers 

Displays the MMX (multi-media extension) registers and their values. See "The MMX 
Registers Window" on page 84. 

XMM Registers 

Displays the XMM (SSE) registers and their values. See "The XMM Registers Window" 
on page 85. 

Stack Displays memory at the stack pointer. See "The Memory and Stack Windows" on page 65. 

I/O Ports Open a window that lets you manipulate the I/O address space of the machine. See "The 

I/O Ports Window" on page 83. 

Memory at... Display memory at a given address. See "The Memory and Stack Windows" on page 65. 

Log Displays debugger messages and the output from debugger commands. See "The Log 

Window" on page 37. 

4.9 The Window Menu 

The Window menu allows you to control and arrange the windows on your screen. 

The Window menu contains the following items: 

Application Switch to the output screen of the application. Press any key to return to the debugger. 

To Log Save the current window’s contents to the log window. Open the Log window to see the 

contents. 

To File Save the contents of the current window to a file. You must enter a file name and choose 

the drive and directory to which you want to save the information. This is useful for 
comparing program state between debugging sessions. 

Zoom Change the size of the current window. Zoom toggles the current window between its 

normal and maximum sizes. 

Next Rotate through the windows, choosing a new current window. 

Accelerator Open the Accelerator window. This window allows you to inspect and modify the 
debugger’s keyboard shortcut keys. 
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4.10 The Action Menu 

Most windows in the debugger have a context sensitive pop-up menu. The Action menu will contain the 
same menu items as the current window’s pop-up menu. It may be used as an alternative to the pop-up 
menus. As an alternative to selecting text with the right mouse button and using the pop-up menu, you can 
select text with the left mouse button or keyboard and use the Action menu. For more information on the 
choices presented in the pop-up menus, see the section entitled "Variable and Watch Windows" on page 61. 

4.11 The Help Menu 

The Help menu contains items that let you use the on-line help facility. They are: 

Contents Show the main table of contents of the on-line help information. This is equivalent to 

pressing FI. 

On Help Display help about how to use the on-line help facility. This menu item is not available in 

character-mode versions of the debugger. 

Search Search the on-line help for a topic. This menu item is not available in character-mode 

versions of the debugger. 

About Display the "about box". It contains the copyright and version information of the debugger. 

4.12 The Status Window 

The Status window appears at the bottom of the debugger screen. As you drag the mouse over a menu 
item, descriptive text about that menu item appears in the toolbar. Messages about the current status of the 
program and debugger warning messages also appear in the Status window. 

4.13 The Log Window 


■ Log 


A DLL has been loaded: 'ntdll.dll' 

A DLL has been loaded: 'USER32 dll' 

A DLL has been loaded: 'KERNEL32.dll' 

A DLL has been loaded: 'GDI32 dll' 

A new task has been loaded 
Break on execute: main(cintmain@49) 

Break on execute: cmemmqr@lnitPermArea+0x0000000E(cmemmqr@72) 

gam — s eh 


Figure 5. The Log Window 


The Log Window 
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Choose Log from the Data menu to see the Log window. The Log window displays several different types 
of messages, including: 

• status messages such as break point notification 

• warning and error messages 

• output from debugger commands 

You can send the contents of any window to the Log window by selecting To Log from the Window menu. 
This allows you to save a window’s contents and review it later. 


4.14 The Accelerator Window 



Figure 6. The Accelerator Window 

The Accelerator window allows you to control the accelerators or keyboard equivalents used by the 
debugger. Choose Accelerator from the Window menu to open this window. The window displays 4 items 
relating to each accelerator definition. They are the key name, the window to which the accelerator applies, 
the type of action that the accelerator defines, and the specifics of that action. 

Accelerators may either apply to all windows or to a specific window. You could define F2 to perform a 
different action depending upon which window is current. Accelerators which apply to all windows will 
have a window type of all. 

An accelerator can define one of three action types. They are: 
pop-up Activate a pop-up menu item in the current window. 

menu Activate an item from the main menu. 

command Perform an arbitrary debugger command. 
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You can modify an element of an accelerator definition by double-clicking on it, or by cursoring to it and 

pressing ENTER. Press the right mouse button to access the following menu items: 

Modify Change the currently selected element of an accelerator assignment. If the key name is 

selected, the you will be prompted to type a new key. If the window name is selected, you 
will be presented with a list of possible window classes. If the action type or details are 
selected, you will be presented with a menu in order to pick the menu item which will be 
attached to the accelerator. 

New Add a new accelerator assignment. You will be prompted for all details. 

Delete Delete the selected accelerator. 

TD Keys Use an approximation of Borland Turbo Debugger’s accelerators. 

WD Keys Use the default set of accelerators. If you are familiar with CodeView, you will be 
comfortable with these key assignments. 
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5 Navigating Through a Program 


This section describes how to use the debugger to browse through your program. 


5.1 The Search Menu 


The Search menu allows you to search a window for a given string. It contains the following items: 


Find 

Next 
Previous 
All Modules 


Search the current window for the first appearance of a given string. You will be prompted 
for the string. See "Entering Search Strings". 

Find a subsequent occurrence of a search string. 

Find a previous occurrence of a search string. 

This will search through the source code of all the modules contained in your program for a 
given string. See "Entering Search Strings". 


Match Find a string in a sorted window by incremental matching. Once you select match, the text 

you type appears in the status window, and the window you are searching repositions itself 
as you type each character. Press ESC to leave this mode. 


5.1.1 Entering Search Strings 



Figure 7. Entering a search string 

When you choose Find from the Search menu or All Modules from the Search menu, you must enter the 
search string that you are looking for and set the parameters for the search. The Search screen consists of 
the following items: 
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Enter Search String 

Enter the string to be found in this edit box. The larger list below shows other strings that 
you have searched for during this debugging session. You can select these by clicking on 
them or by using the up and down arrow keys. The most recent search string appears at the 
top of the list. 

Regular Expression 

Check this box if the string is to be interpreted as a regular expression. You can click on 
the Edit button to edit the set of regular expression characters that will be used. For a 
description of regular expressions, see the Editor manual. 

Ignore Case Check this box if you want the debugger to match the search string regardless of case. 


5.2 The Source Window 


< Source: csym.c 


void SymsPurgeO 

{ 

LABELPTR label; 

^ label = LabelHead; 

O while( label != NULL) { 

LabelHead = label->next_label; 
© CMemFree( label); 

O label = L^jelHead; 

° } 

// EnumlnitO; 

// PurgeTags( TagHead ); 

O TagHead = NULL; 

// PurgeTags( DeadTags ); 


Figure 8. The Source Window 

The Source window displays your program’s source code. As you trace through your program, it 
repositions itself at the currently execution location. If you have an Assembly window open, the Source 
and Assembly windows will always be positioned at the same code. If you scroll in one, the other follows. 

Source lines that have code associated with them have a button at the left of the screen. You can click on 
this button to set, disable and clear break points. 

You can Inspect any item displayed in the source window by double-clicking on it, or by cursoring to it and 
pressing ENTER. Press the right mouse button to access the following pop-up menu items: 

Inspect Inspect the selected item in an appropriate window. You can select function names, 

variable names, or any valid expression. 

Run to Cursor Resume program execution until the selected line is executed. 

Break Add a breakpoint based on the selected text. If a variable is selected, the program will stop 

when its value changes. If a function name is selected the program will stop when that 
function is executed. This does not set a break at the current line. Use Toggle from the 
Break menu or At Cursor from the Break menu to set a breakpoint at the current line. 


^jnjxj 

d 


J 

d 
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Enter Function 

Resume program execution until the selected function is entered. 

Watch Add the selected item to the Watches window for further inspection or modification. 

Find Search for other occurrences of the selected string in the Source window. 

Home Reposition the window to show the currently executing location. The cursor will move to 

the next line of the program to be executed. 

Show/Assembly 

Show the assembly code associated with the selected line. 

Show/Functions 

Show the list of all functions contained in the source file. 

Show/Address Reposition the window at a new address. You will be prompted for an expression. 

Normally you would type a function name but you can type any expression that resolves to 
a code address. For example, you might type the name of a variable that contains a pointer 
to a function. See "Open Watcom Debugger Expression Handling" on page 119. 

Show/Module Show the code for a different module. You will be prompted for its name in a dialog. As a 
shortcut, you can type the beginning of a module name and click the Module... button. 

This will display a list of all modules that start with the text you typed. 

Show/Fine Move to a different source line. You can also find out what line you are looking at. The 
edit field will be initialized with the current line number. 


5.3 The File Window 

A File window is Similar to a source window except that it displays a file which is not part of the program 
being debugged. Menu items related to execution such as Break from the pop-up menu are not available. 
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5.4 The Modules Window 



Figure 9. The Modules Window 

The Modules window displays a list of the modules that make up the current program. To open the 
Modules window, choose Modules from the Code menu. 


Three items are displayed for each module. At the left, there is a button. You can click the mouse on it to 
see the source or assembly associated with the module. This can also be accomplished by double-clicking 
on the module name or cursoring to it and pressing ENTER. Next is the module name. Third, if the 
module is contained in an executable image other than the one being debugged, is the name of that image. 

Since this window is sorted Match from the Search menu can be used to find a module. Choose Match 
from the Search menu (or press =) and begin typing the name of the module. 


Press the right mouse button to access the following pop-up menu items: 


Source Show the source code associated with the selected module. 

Assembly Show the assembly code associated with the selected module. 
Functions Show the list of all functions contained in this module. 


Break All Set a breakpoint at each function in this module. 

Clear All Delete all breakpoints which are set at addresses with this module. This does not affect 

break-on-write break points. 

Show All Toggle between showing all modules and just modules which were compiled with full 
debugging information (d2). This menu item sets options on a per-window basis, 
overriding the global settings. When you use the menu item to change these settings, they 
will not be saved between debugging sessions. To change an option permanently, see "The 
Window Options Dialog" on page 33. 
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5.5 The Globals Window 


Globals 

-JnJ *J 

tzset@_tzFIaq 

±1 

_tzname 


_UnhandledExceptionFilter(sM 
_VirtualAlloc@16 

J 

_VirtualFree@12 
_VirtualQuery@12 
WideCharToMultiByte@32 
_WriteFile@20 
dosret@_xlat 

386rgtbl@ABCDRegs 

generate@abortCG 

zJ 


Figure 10. The Globals Window 


You can open the Globals window by choosing Globals from the Data menu. This window displays the 
names of all global variables defined in the program. You can add a variable to the Watches window by 
double-clicking on it, or cursoring to it and pressing ENTER. 

Press the right mouse button to access the following pop-up menu items: 

Watch Add the selected variable to the Watches window. 

Raw Memory Display the memory associated with the selected variable. 

Typed Symbols 

Toggle between showing all symbols and just those defined in modules compiled with the 
d2 option. Variables from the C/C++ library and assembly code are suppressed. This 
menu item sets options on a per-window basis, overriding the global settings. When you 
use the menu item to change these settings, they will not be saved between debugging 
sessions. To change an option permanently, see "The Window Options Dialog" on page 
33. 


The Functions Window 
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5.6 The Functions Window 


f Functions 


♦ cfold2@ArithmeticType 
O BoolConstExpr 

O CastConstValue 

♦ CastFloatValue 
cfold2@ConstantLeaf 

O DoConstFold 

♦ DoFloatOp 
O DoOp32 

O DoOp64 
O DoSignedOp 
Q DoSignedOp64 

♦ DoUnSignedOp 


1 


d 


Figure 11. The Functions Window 


The Functions window can display a list of all functions contained in a module, executable image or 
program. To the left of each function name is a button. You can click on these buttons to set and clear 
breakpoints at the various functions. This can also be accomplished by double-clicking on the function 
name or cursoring to a function and pressing ENTER. 

Press the right mouse button to access the following pop-up menu items: 

Break Set a breakpoint at the selected function. A dialog will appear so that you can fill in 

detailed breakpoint information. For more information, refer to the section entitled "The 
Breakpoint Dialog" on page 75. 

Source Show the source code for the selected function. 

Assembly Show the assembly code associated with the selected function. 

Typed Symbols 

Toggle between showing all symbols and just those defined in modules compiled with the 
d2 option. Variables from the C/C++ library and assembly code are suppressed. This 
menu item sets options on a per-window basis, overriding the global settings. When you 
use the menu item to change these settings, they will not be saved between debugging 
sessions. To change an option permanently, see "The Window Options Dialog" on page 
33. 
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5.7 The Images Window 


< Images 


Jnjxj 

Executable File 

Debug Information 

Debug Information Type 

wcc386d.exe 

wcc386d.sym 

DWARF 

ntdll.dll 

ntdll.dll 

EXPORTS 

USER32.dll 

USER32.dll 

EXPORTS 

KERNEL32.dll 

KERNEL32.dll 

EXPORTS 

GDI32.dll 

GDI32.dll 

EXPORTS 

jlU 


Jj 


Figure 12. The Images Window 


Choose Images from the Code menu to open the Images window. It displays a list of executable images 
associated with the program that you are currently debugging. Executable images include the program 
executable, DLLs (Windows, OS/2 and Windows NT), and NLMs (NetWare). This window displays the 
name of the executable image, the name of the symbolic debugging information file (if available), and the 
debugging information type. 

Different debugging information types are generated by different compilers. 

Valid information types are: 


DWARF This information is generated by the Open Watcom compilers. 

Watcom This information is optionally generated by the Open Watcom compilers. 

CodeView In addition to Open Watcom compilers, several other products, including Microsoft’s, can 

generate CodeView style information. 


MAPSYM This information is generated by Microsoft’s or IBM’s MAPSYM utility. MAPSYM 
processes linker map file and outputs a .sym file. Symbol files in MAPSYM format are 
often available for OS/2 system DLLs. MAPSYM files only contain information about 
global symbols, but usually provide much more detail than just exports information. 


EXPORTS This information is contained in the executable file itself, and is used by the operating 

system. Under OS/2, Windows and Windows NT, DLLs have export tables which define 
the names and addresses of entry points. Exports information lets you see the names of 
system entry points and APIs. Novell NLMs also have entry point tables. In addition, they 
may have Novell style debugging information, created with Novell’s linker (NLMLINK) or 
using the Open Watcom Linker’s "debug novell" option. This information is made 
available to the debugger. 


You can add new debugging information to an image by double-clicking on the image name or cursoring to 
it and pressing ENTER. 

Press the right mouse button to access the following pop-up menu items: 
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New Symbols 

Delete Symbols 

Modules 

Functions 

Globals 


Add symbolic debugging information for the selected image. This is useful if you know 
that a separate debug information file contains the appropriate debugging information that 
was not found by the debugger. 

Delete any symbolic debugging information associated with the selected image. 

Show a list of modules contained in the selected image. 

Show a list of functions contained in the selected image. 

Show a list of all global variables contained in the selected image. 
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6 Controlling Program Execution 


This section describes how you can control the execution of your program as you debug it. 

6.1 The Run Menu 

The Run menu controls how your program executes. It contains the following items. 

Go Start or resume program execution. Execution resumes at the current location and will not 

stop until a breakpoint is encountered, an error occurs, or your program terminates. 

Run to Cursor Resume program execution until it executes the location of the cursor in the Source or 
Assembly window. Execution will stop before the cursor position if a breakpoint is 
encountered or an error occurs. 

Execute to Resume program execution until it executes a specified address. You will be prompted to 
enter an address. It can be the name of a function or an expression that resolves to a code 
address. See "Open Watcom Debugger Expression Handling" on page 119. In the dialog, 
you can click the Symbols... button as a shortcut. You can type a partial symbol name like 
f oo and the Symbol button will show you a list of symbols that start with f oo. You can 
then choose one of these symbols by clicking on it or hitting ENTER. Note that the first 
time you use the Symbols... in a debugging session, it will take a while as the debugger 
sorts the symbol table for the program. 

If your program encounters a breakpoint or an error occurs before the specified address is 
executed, your request to stop at the given address is ignored. 

Step Over Trace a single source or assembly line depending on whether the source or assembly 
window is current. Step Over will not step into any function calls. 

Trace Into This is similar to Step Over except that it will step into any function calls. 

Next Sequential 

Run until the program executes the next sequential source line or assembly instruction. 

This is useful if the program is executing the last statement in a loop and you wish to 
execute until the loop terminates. When using this command, be sure that the execution 
path will eventually execute the next statement or instruction. If execution fails to reach 
this point then the program may continue to execute until completion. This situation is like 
setting a breakpoint at a statement or assembly instruction which will never be executed 
and then issuing a GO command. In this situation, the application would execute until an 
error occurred or another breakpoint was encountered. 

Until Return Resume program execution until the currently executing function returns. Execution 
terminates prior to this if an error occurs or a breakpoint is encountered. 

Skip to Cursor Reposition the instruction pointer at the cursor position, "skipping" all instructions in 

between. When you continue execution, the program continues from this point. This is 
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useful if you want to skip an offending line or re-execute something. Use this menu item 
with caution. If you skip to an instruction which is not in the current function or skip to 
code that expects a different program state, your program could crash. 

Restart Restart your program from the beginning. All breakpoints in your program will be 

preserved. Breakpoints in DLLs will not be preserved. 

Debug Startup Restart your program from the beginning but stop before system initialization. Normally 
the debugger puts you at the main (fmain, winmain, etc.) entry point in your application. 
This option will allow you to break much earlier in the initialization process. This feature 
is useful for debugging run-time startup code, initializers, and constructors for static C++ 
objects. 

For DOS, Windows 3.x and Netware, the debugger will put you at the assembly entry point 
of your application (i.e., it doesn’t run the "progstart" hook). 

Windows 3.x runs each DLL’s startup code as it loads it, and the static DLLs are really 
loaded by the run-time startup code, so, to debug the startup code for a statically linked 
Windows 3.x DLL, you need to do the following. 

1. Select Debug Startup from the Run menu. 

2. Select On Image Load from the Break menu. Type the name of the DLL in 
which you are interested. 

3. Select Go from the Run menu 

For OS/2 and Windows NT, the debugger will put you at a point after all DLLs have been 
loaded, but before any DLL initialization routines are called. This enables you to set 
breakpoints in your statically referenced DLL’s startup code. 

If you have hard-coded int3 instructions in your DLL startup, the debugger will skip them, 
unless you use Debug Startup from the Run menu. 

All breakpoints in your program will be preserved. Breakpoints in DLLs will not be 
preserved. 

Save Save the current debugging session to a file. The file contains commands that will allow 

the debugger to play your debugging session back to its current point in a later session. See 
"The Replay Window" on page 56. 

Restore Restore a saved debugging session. If you run the program with different input or if the 

program is a multi-threaded application, this option may not work properly since external 
factors may have affected program execution. See "The Replay Window" on page 56. 


6.2 The Undo Menu 


The debugger keeps an execution history as you debug your program. This history is accessible using the 
Undo menu. The effect of program statements as you single step through your program are recorded. All 
interactions that allow you to modify the state of your program including modifying variable values, 
changing memory and registers are also recorded. Undo and Redo let you browse backward and forward 
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through this execution history. As you use these menu items, all recorded effects are undone or redone, and 
each of the debugger’s windows are updated accordingly. 

You can resume program execution at any previous point in the history. The program history has no size 
restrictions aside from the amount of memory available to the debugger, so theoretically you could single 
step through your entire program and then execute it in reverse. There are several practical problems that 
get in the way of this. When you single step over a call or interrupt instruction, or let the program run 
normally, the debugger has no way of knowing what kind of side effects occurred. No attempt is made to 
discover and record these side effects, but the fact that you did step over a call is recorded. If you try to 
resume program execution from a point prior to a side effect, the debugger will give you a the option to 
continue or back out of the operation. Use caution if you choose to continue. If an important side effect is 
duplicated, you program could crash. Of course reversing execution over functions with no side effects is 
harmless, and can be a useful debugging technique. If you have accidentally stepped over a call that does 
have a side effect, you can use Replay to restore your program state. 

Unwind and Rewind move the debugger’s state up and down the call stack. Like Undo, all windows are 
updated as you browse up and down the stack, and you can resume execution from a point up the call stack. 
A warning will be issued if you try resuming from a point up the call stack since the debugger cannot 
completely undo the effects of the call. 

Unwind is particularly useful when your program crashes in a routine that does not contain debugging 
information. strcpy() is a good example of this. You can use Unwind to find the call site and inspect the 
parameters that caused the problem. 

The runtime library detects certain classes of errors and diagnoses them as fatal runtime errors. If this 
occurs when you are debugging, the debugger will be activated and the error message will be displayed. 

For example, throwing an exception in C++ without having a catch in place is a fatal runtime error. In C, 
the abort() and assert() functions are fatal errors. When this happens, you will be positioned in an internal 
C library call. You can use Unwind to find the point in your source code that initiated the error condition. 

When Unwind and Undo are used in conjunction. Undo is the primary operation and Unwind is secondary. 
You can Undo to a previous point in the history and then Unwind the stack. If you Unwind the stack first 
and then use Undo, the Unwind has no effect. 


If you modify the machine state in any way when you are browsing backward through the execution 
history, all forward information from that point is discarded. If you have browsed backward over a side 
effect the debugger will give you the option of canceling any such operation. 

The Undo menu contains the following items. 

Undo Browse backwards through the program execution history. 

Redo Browse forward through the program execution history. 

Unwind Stack Move up the call stack one level. 

Rewind Stack Move down the call stack one level. 


Home Return to the currently executing location, reversing the effects of all Undo and Unwind 

operations. 
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6.3 The Replay Window 


< Replay 


DbgBieakPoint+OxOOOOOOOl: 

main: 

main+OxOOOOOOOE: 
main+OxOOOOOOl 5: 
main+OxOOOOOOl 5: 
cqen2@DelineLabels+0x0000001 C: 


|cgen2@DefineLabels+0x00000069: 


let 

ini main() 

FrontEndlniK FALSE ); 
atexit( ResetHandlers ): 
atexit( ResetHandleis ); 
if( Labellndex != 0 ) { 

} 


^iSJx] 

new/piogram wcc386d.exe \tmp\ci 

trace/source/over 

tiace/source/over 

bieak/set /index 1. /unmapped /sy 

go 

Irace/source/over 

tiace/souice/into 
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Figure 13. The Replay Window 


Choose Replay from the Code menu to open the Replay window. This window displays each of the steps 
that you have performed during this debugging session that might have affected program flow. There are 
three items displayed in the replay window. First is the address the program was executing when you took 
some action that could affect the program. These actions include setting break points, tracing and 
modifying memory. Second is the source or assembly code found at that address. Third is a command in 
the debugger’s command language that will duplicate the action you took. The most common use for 
Replay is when you accidentally step over a function call, or the program unexpectedly runs to completion. 
If this happens, you can open the replay window, and replay you debugging session up to any point prior to 
the last action you took. 


There are special cases where replay will not perform as expected. Since replay is essentially the same as 
playing your keystrokes and mouse interactions back to the debugger, your program must behave 
identically on a subsequent run. Any keyboard or mouse interaction that your program expects must be 
entered the same way. If your program expects an input file, you must run it on the same data set. Your 
program should not behave randomly or handle asynchronous events. Finally, your program should not be 
multi-threaded. If you have just been tracing one thread, your program will replay correctly, but multiple 
threads may not be scheduled the same way on a subsequent run. 

You can replay program execution to any point by double clicking on that line or by cursoring to it and 
pressing ENTER. Select any line and press the right mouse button to see the following pop-up menu items: 


Goto Replay the program until it returns to the selected level in the replay history. 

Source Position the source window at the selected line. 

Assembly Show the assembly code for the selected line. 
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6.4 The Calls Window 


^aaixi 


_NTMain: call near ptr_CMain 
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Figure 14. The Calls Window 


Choose Calls from the Code menu menu to display the Calls window. This window displays the program’s 
call stack. Each line contains the name of the function that was executing, and the source or assembly code 
at the call site. You can use Unwind and Rewind to obtain this information, but the calls windows will 
show you the entire call stack. 

You can Unwind to any point in the call stack by double-clicking on a line, or by cursoring to it and 
pressing ENTER. Select a line and press the right mouse button to access the following pop-up menu 
items: 

Unwind Unwind the stack to the level of the selected code. This is equivalent to using Unwind 

from the Undo menu or Rewind from the Undo menu. 

Break Set a breakpoint at the return from the selected call. 

Goto Execute until the program returns from the selected call. 


6.5 The Thread Window 


« Threads 
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Figure 15. The Thread Window 


The Thread Window 
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Choose Thread from the Code menu to display Thread window. This window displays the system ID of 
each thread, the state of the thread, and under some operating systems, system specific information about 
the thread including its name and scheduling priority. The state of each thread can be: 

current This is the thread that was running when the debugger was entered. It is the thread that hit 

a break point or error. When you trace through the application, only the current thread is 
allowed to run. 

runnable This thread will be allowed to run whenever you let your program run, but will not run 
when you trace the program. 

frozen This thread will not be allowed to run when you resume your program. 

dead Under some operating systems, threads that have been terminated still show up in the list of 

threads. A dead thread will never execute again. 

You can make any thread current by double clicking on it or cursoring to it and pressing ENTER. All other 
debugger windows update accordingly. Press the right mouse button to access the following pop-up menu 
items: 

Switch to Make the selected thread current. 

Freeze Change the state of the selected thread to be frozen. You cannot freeze the current thread. 

Thaw Change the state of the selected thread to be runnable.. The current thread is always 

runnable. 
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7 Examining and Modifying the Program State 


The following topics are discussed: 

• "Variable and Watch Windows" 

• "The Memory and Stack Windows" on page 65 


7.1 Variable and Watch Windows 
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Figure 16. The Watch and Variable Window 

Windows that display variables come in several different varieties. They are: 

• Locals 

• File Variables 

• Watches 

• Variable 

They are collectively called variable windows. You use the same interactions in all variable windows to 
display, modify and browse your variables and data structures. The only difference between these windows 
are the variables that they display. The values in each window are updated as you trace through your 
program. The windows display the following information: 

Locals Contains the list of variables which are local to the current routine. Choose Locals from 

the Data menu to open this window. 

File Variables Contains a list of all variables which are defined at file scope in the current module. This 
includes external and static symbols. Choose File Variables from the Data menu to open 
this window. 

Watches The Watches windows allows you to add and delete variables and expressions. In other 

windows you can choose Watch from the pop-up menu. This will open the watches 
window add the text which is selected in another window to the watches window. You can 
use New from the pop-up menu to add any expression to the Watches window. Once 
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entered, you can choose Edit from the pop-up menu to edit the expressions or typecast the 
variables. 

Variable This is another instance of a Watches window. A variable window is created when you 

select a variable or expression in a window and use Inspect from the pop-up menu. 

Each line of a variable window has three elements. On the left is a button. The button changes depending 
on the type of the variable or expression, it changes based on the type of the item: 

structs (classes) (unions) Structures may be opened and closed by clicking on the button at the left. When 
you open a structure or class, one line is added to the window for each field of the structure. 
These new lines are indented. If you click on the button again, the structure is closed and 
the window is returned to its original state. 

arrays Like structs, arrays may be opened and closed. When you open an array, one line is added 

to the window for each element of the array. The debugger will display at most 1000 
elements of an array. If it contains more you can use Type/Array... to open different 
ranges. Multi dimensional arrays are treated like an array of arrays. When you open the 
first dimension, the lines that are added will also be arrays which you can open. 

pointers When the variable is a pointer, you can click on the button and the debugger will follow the 

pointer and change the line to represent the item which is the result of the pointer reference. 
For example, if you have a pointer to an integer and click on the button, the integer value 
will be displayed. The button then changes to indicate so that you can undo the operation 
by clicking on it again. 

In the case of pointers to pointers, clicking on the button will follow the pointers one level 
each time you click on the button until a non-pointer value is reached. Clicking on the 
button at this point will undo take you back to the original state. When the pointer points to 
a struct, the structure will automatically be opened when you click on the button. If a 
pointer is really an array, you can use Type/Array... from the pop-up menu to open it as an 
array. 

Next comes the name of the variable, field or array element being displayed. Finally, the value is 
displayed. If the item being displayed is not a scalar item, the value displayed is an indication that it is a 
complex data type. If the value changes when you run your program, it will be highlighted. If a variable 
goes out of scope, or a pointer value becomes invalid, the value will be displayed as question marks. 

You can modify a variable’s value by double clicking on the value field, or by cursoring to it and pressing 
enter. Double clicking or pressing enter on the name field is equivalent to clicking on the button. Press the 
right mouse button to access the following pop-up menu items: 

Modify... Modify the value of the selected item. 

Break Set a breakpoint so that execution stops when the selected item’s value changes. This is the 

same as setting a breakpoint on the object. See "Breakpoints" on page 71. 


Inspect Open a new Variable window containing the selected item. If the item is a compound 

object (array, class, or structure), it will be opened automatically. 

Watch Add the selected item to the Watch window. 
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Show/Raw Memory 

Display raw memory at the address of this variable. This lets you examine the actual 
binary representation of a variable. 

Show/Pointer Memory 

Display the memory that the item points to. This is useful when you have a pointer to a 
block of memory that does not have a type associated with it. 

Show/Pointer Code 

Display the code that the variable points to. If the item being displayed is a pointer to 
function, you can use this menu item to see the definition of that function. 

Show/Type Display the type of the variable in an information message box. Select "OK" to dismiss the 
information box and resume debugging. 


Edit Open a dialog box in which you can edit an expression in the Watch window. This is 

useful for typecasting variables or evaluating expressions. See "Open Watcom Debugger 
Expression Handling" on page 119. 

New Add a new variable or expression to the window. You will be prompted for the expression 

to add. 

Delete Delete the selected item from the window. 


FieldOnTop Display the value of this member at the top of the structure/class. You can selectively add 
or remove items from the list that is displayed "on top". For example, say you have a 
struct Point displayed as: 

[-] point 
x 10 

y 30 

other "asdf" 

If you toggle FieldOnTop for both x and y then point would be displayed like this: 

[-] point { 10, 30 } 

x 10 

y 30 

other "asdf" 

Furthermore, if you closed the struct (or pointer to struct) then you would see: 

[+] point { 10, 30 } 

This carries to structs containing structs (and so on) as shown in the following struct 
containing two Point structures. 

[-] rect { { 10, 10 }, { 30, 30 } } 
top_ left { 10, 10 } 
bot_ right { 30, 30 } 
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If you close it, then you will see: 

[+] rect { { 10, 10 }, { 30, 30 } } 

Class/Show Functions 

Display function members of this object. If this option is not selected, no functions are 
displayed. This option works in conjunction with other Class selections to display 
"Inherited", "Generated", "Private" and "Protected" functions. 

Class/Show Inherited 

Display inherited members of this object. To see inherited functions, you must also select 
Class/Show Functions. 

Class/Show Generated 

Display compiled-generated members of this object. To see generated functions, you must 
also select Class/Show Functions. 

Class/Show Private 

Display private members of this object. To see private functions, you must also select 
Class/Show Functions. 

Class/Show Protected 

Display protected members of this object. To see protected functions, you must also select 
Class/Show Functions. 

Class/Show Static 

Display static members of this object. 

Type/All Hex This item is only available when the display item is an array or a fake array (a pointer 
changed to display as if it were an array using Type/Array ). Change the value of all 
sibling array entries to be displayed in hexadecimal. 

Type/Hex Change the value to be displayed in hexadecimal. 

Type/All Decimal 

This item is only available when the display item is an array or a fake array (a pointer 
changed to display as if it were an array using Type/Array ). Change the value of all 
sibling array entries to be displayed in decimal. 

Type/Decimal Change the value to be displayed in decimal. 

Type/Character 

Change the value to be displayed as a single character constant. This useful when you have 
a one byte variable that really contains a character. The debugger will often display it as an 
integer by default. 

Type/String The debugger automatically detects pointers to strings in the variable windows and displays 
the string rather than the raw pointer value. In the string is not null terminated, contains 
non-printable characters, or is not typed as a pointer to ’char’, this mechanism will not 
work. Type/String overrides the automatic string detecting and displays the pointer as a 
string regardless of its type. 

Type/Pointer This will undo the effects of Type/String or Type/Array. It will also let you see the raw 
pointer value when the debugger has automatically displayed a pointer to char as a string. 
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Type/Array... Use this menu item to display a pointer as if it were an array, or to display ranges of an 
array’s elements. You will be prompted for the first and last element to display. 

Options/Whole Expression 

Select this option to show the whole expression used to access fields and array elements 
instead of just the element number or field name itself. 

Options/Expand ’this’ 

Do not display members of the ’this’ pointer as if they were local variables declared within 
the member function. 


7.2 The Memory and Stack Windows 
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Figure 1 7. The Memory Window 


Use the Memory window or the Stack window to examine memory in raw form. To open a Memory 
window, choose Memory At from the Data menu. The Enter Memory Address dialog appears. Enter the 
memory address and press Return to see the Memory window. You can also use one of the Show/Pointer 
Memory or Show/Raw Memory items in a variable window to display the memory associated with a 
variable. 


The Stack Window always shows the memory at the stack pointer. It is moved as your program executes to 
track the top of the stack. The stack pointer location will be at the top of the window. The location of the 
BP or EBP register will also be indicated. Choose Stack from the Data menu to open the Stack window. 

You can modify memory by double-clicking on a value in the Memory or Stack window, or by cursoring to 
it and pressing enter. You will be prompted for a new value. 

Memory windows allow you to follow data structures in the absence of debugging information. The 
Follow menu items will reposition the memory window to the address that is found under the cursor. The 
Repeat and Previous items will let you repeat a follow action. This makes it simple to follow linked lists. 
Press the right mouse button to access the following pop-up menu items: 
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Modify Modify the value at the selected address. You will be prompted for a new value. You 

should enter the value in the same radix as the window is currently displaying. You are not 
limited to typing constants values. You can enter an arbitrary expression to be used for the 
new value. 

Break on Write 

Set a breakpoint to stop execution when the selected value changes. See "Breakpoints" on 
page 71. 


Near Follow Displays the memory that the selected memory points to, treating it as a near pointer. The 
new offset to be displayed will be xxxx where xxxx is the word under the cursor. 

DGROUP will be used as the segment if it can be located. The program’s initial stack 
segment will be used otherwise. When you are debugging a 16-bit or 32-bit application, 
the appropriate word size is used. 

Far Follow Displays the memory that the selected memory points to, treating it as a far pointer. The 

new address to be displayed will be the the segment and offset found at the cursor location. 
Note that pointers are stored in memory with the offset value first and the segment value 
second. 

Segment Follow 

Display the segment that the selected memory points to, treating it as a segment selector. 
The new address to be displayed will be xxxx:0 where xxxx is the two byte word under the 
cursor. 

Cursor Follow Make the selected position the new starting address in the window. This means that the 

first byte in the memory window will become the byte that the cursor was pointing to. This 
is useful for navigating through an array when no debugging information is available. 

Repeat Repeat the previous Follow operation. The new address that will be used is at the same 

offset relative to the beginning of the window as it was in the original Follow operation. 
Repeating a pointer or segment follow is a linked list traversal. Repeating a Cursor Follow 
operation advances to the next element in an array. 

Previous Back out of a Follow or Repeat operation. This will display the memory window you were 

previously viewing. Essentially, this undoes a Follow operation. You can back all the way 
out to the first memory location you were examining. 

Home Undo all Follow and Repeat operations. This will take you back to the very first location 

window you were examining. It is equivalent to using Previous repeatedly. 


Left Scroll the window backward through memory by the size of the displayed memory items. 

Right Scroll the window forward through memory by the size of the displayed memory items. 


Address Position the window at a new address. You will be prompted to type in a new address. 

You can type an arbitrary expression. See "Open Watcom Debugger Expression Handling" 
on page 119. If you type the name of a variable, the address of that variable is used. If the 
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expression you type does not contain a segment value DGROUP will be used as the 
segment if it can be located. The program’s initial stack segment will be used otherwise. 

Assembly 

Position the assembly window to the address of the memory under the cursor. This is 
useful if you have incorrectly displayed a pointer as data and wish to look at the code 
instead. 

Type/Byte 

Display as hexadecimal bytes. 

Type/Word 

Display as hexadecimal 16-bit words. 

Type/Dword 

Display as hexadecimal 32-bit words. 

Type/Qword 

Display as hexadecimal 64-bit words. 

Type/Char 

Display as signed 8-bit integers. 

Type/Short 

Display as signed 16-bit integers. 

Type/Long 

Display as signed 32-bit integers. 

Type/ _ int64 

Display as signed 64-bit integers. 

Type/Unsigned Char 

Display as unsigned 8-bit integers. 


Type/Unsigned Short 

Display as unsigned 16-bit integers. 


Type/Unsigned Long 

Display as unsigned 32-bit integers. 

Type/Unsigned _ int64 

Display as unsigned 64-bit integers. 

Type/0:16 Pointer 

Display as 16-bit near pointers (16-bit offset). 

Type/16:16 Pointer 

Display as 32-bit far pointers (16-bit segment, 16-bit offset). 
Type/0:32 Pointer 

Display as 32-bit near pointers (32-bit offset). 

Type/16:32 Pointer 

Display as 48-bit far pointers (16-bit segment, 32-bit offset). 

Type/Float Display as 32-bit floating-point values. 

Type/Double Display as 64-bit floating-point values. 

Type/Extended Float 

Display as 80-bit floating-point values. 
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7.2.1 Following Linked Lists 

Use the memory window to display the memory address of the first node of your linked list. Move to the 
"next" field of your structure and use the Near (or Far) Follow command. The next node of your linked list 
will be displayed. Now by using the Repeat command you can traverse the linked list. 

7.2.2 Traversing Arrays 

Display the memory address of your array. Select the first byte of the second element of your array then 
use the Cursor Follow command to move the second element of your array to the beginning of the memory 
window. By using the Repeat command you can traverse your array. 
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8 Breakpoints 


The Open Watcom Debugger uses the single term breakpoint to refer to the group of functions that other 
debuggers often call breakpoints, watchpoints, and tracepoints. 

A breakpoint is traditionally defined as a place in your program where you want execution to stop so that 
you can examine program variables and data structures. A watchpoint causes your program to be executed 
one instruction or source line at a time, watching for the value of an expression to become true. Do not 
confuse a watchpoint with the watch window. A tracepoint causes your program to be executed one 
instruction or source line at a time, watching for the value of certain program variables or 
memory-referencing expressions to change. 

In the Open Watcom Debugger: 

• Break-on-execute refers to the traditional breakpoint 

• Break-on-write refers to the traditional tracepoint 

• A traditional watchpoint is a break-on-execute or break-on-write that is coupled with a condition 
The Open Watcom Debugger unifies these three concepts by defining three parts to a breakpoint: 

• the location in the program where the breakpoint occurs 

• the condition under which the breakpoint is triggered 

• the action that takes place when the breakpoint triggers 

You can specify a countdown, which means that a condition must be true a designated number of times 
before the breakpoint is triggered. 

When a breakpoint is triggered, several things can happen: 

• program execution is stopped (a breakpoint) 

• an expression is executed (code splice) 

• a group of breakpoints is enabled or disabled 

In this chapter, you will learn about the breakpoint including how to set simple breakpoints, conditional 
breakpoints, and how to set breakpoints that watch for the exact moment when a program variable, 
expression, or data object changes value. 

8.1 How to Use Breakpoints during a Debugging Session 

The following topics are discussed: 

• "Setting Simple Breakpoints" on page 72 

• "Clearing, Disabling, and Enabling Breakpoints" on page 72 
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8.1.1 Setting Simple Breakpoints 

When debugging, you will often want to set a few simple breakpoints to make your program pause 
execution when it executes certain code. You can set or clear a breakpoint at any location in your program 
by placing the cursor on the source code line and selecting Toggle from the Break menu or by clicking on 
the button to the left of the source line. You can set breakpoints in the assembly window in a similar 
fashion. Setting a break-on-write breakpoint is equally simple. Select the variable with the right mouse 
button and choose Break from the pop-up menu. 

Break points have three states. They are: 

• enabled 

• disabled 

• cleared (non-existent) 

The button for an enabled break point is a stop sign or [!]. The button for a disabled break point is a grey 
stop sign or [.]. A green diamond or [ ] appears when no breakpoint exists at the given line. The same 
buttons also appear in the Assembly window and the Break window to indicate the status of a break point. 

Note: Some lines in your program do not contain any machine code to execute and therefore, you 

cannot set a breakpoint on them. The compiler does not generate machine code for 
comments and some C constructs. All lines of code in your program that can have a 
breakpoint on them have a button to the left of the source line. You can click on them to 
change their current status. 

8.1.2 Clearing, Disabling, and Enabling Breakpoints 

Choosing Toggle from the Break menu (F9) toggles between the three different breakpoint states: 

• enabled 

• disabled 

• cleared (non-existent) 


8.2 The Break Menu 


You can use the Break menu to control your breakpoints. Operations including creating new breakpoints, 
changing a breakpoint’s status, and viewing a list of all break points. 

Toggle Change the status of the breakpoint at the current line in the source or assembly window. 

The status alternates between enabled, disabled and cleared. The button on the source or 
assembly line will be updated to reflect the status of the breakpoint. 

Note: Disabled and cleared breakpoints are not the same. If you disable a 

breakpoint, you can re-enable it and retain the information about the 
breakpoint (i.e., conditions, countdown, and actions). When you clear a 
breakpoint, you lose all information about the breakpoint. If you disable a 
breakpoint, and press F9 twice to enable, you will lose the information 
about the breakpoint because you cleared it before you re-enabled it. To 
enable a disabled breakpoint without losing the breakpoint information, use 
the Breakpoint Option dialog or the Breakpoint window. 
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At Cursor Set a breakpoint at the current line in the source or assembly window. If the current line 
does not contain any executable code, the breakpoint is set on the closest preceding line of 
code that does contain executable code. When you choose At Cursor, the Breakpoint 
dialog appears. 

New This allows you to create any type of breakpoint using a dialog. You must specify the 

address in the dialog. 

On Image Load... 

Cause program execution to stop when an executable image (DLL) is dynamically loaded. 
The menu item is only available when debugging an Win32 or OS/2 executable. A 
dialogue will appear allowing you to add and delete image names from the list. You only 
need to type a substring of the actual image name. You can identify the file 
"C:\PATH\IMAGE.DLL" with any substring, for example "IMAGE", "IMAGE.DLL" or 
"ATH\IMAGE.DLL". Case is ignored in the image names. 

On Debug Message 

When checked, cause program execution to stop whenever Windows 3.1, Windows NT, or 
Windows 95 prints a debug string. A debug string is printed whenever the application or 
debug Kernel calls the OutputDebugString function. This option is toggled each time it is 
selected from the Break menu. 

Open the breakpoint window. This window will show a list of all breakpoints. You can 
use the window to create, delete and modify breakpoints. 

Clear all breakpoints. 

Disable all breakpoints, but do not delete them. 

Enable all breakpoints that are disabled. 

Save all breakpoint information to a file. This is useful when you are creating complicated 
breakpoints. You can save and restore them in a later debugging session. 

Restore a set of breakpoints that were saved by using Save from the Break menu. 


View All 

Clear All 
Disable All 
Enable All 
Save 

Restore 
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8.3 The Break Window 
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Figure 18. The Break Window 


The Break window displays each breakpoint and its status. It appears when you select the View All from 
the Break menu A breakpoint button appears at the left of each line. You can click on this button to enable 
and disable a breakpoint. Unlike the source and assembly windows, the button will not clear the 
breakpoint. Next appears the address of the breakpoint. Finally, for break-on-execute breakpoints, the 
source or assembly code at the break point location is displayed. For break-on-write breakpoints, the 
current value of the location is displayed in hex. 

You can modify any break point by double clicking on it, or by cursoring to it and pressing enter. The 
Breakpoint Options dialog will appear to allow you to modify the break point. Press the right mouse button 
to access the following pop-up menu items: 


Modify Change the definition of the selected breakpoint. The Breakpoint dialog will appear. 

New Add a new breakpoint. An empty Breakpoint dialog will appear. You must specify the 

address of the new Breakpoint. Refer to the section entitled "The Breakpoint Dialog" on 
page 75 for a description of the items in the which appear in the dialog. 

Delete Delete the selected breakpoint. 

Enable Enable the selected breakpoint. 

Disable Disable the selected breakpoint. 

Source Display the source code associated with the break point. This operation only makes sense 

for break-on-execute breakpoints. 

Assembly Display the assembly code associated with the selected line. This operation only makes 
sense for break-on-execute breakpoints. 
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8.4 The Breakpoint Dialog 



Figure 19. The Breakpoint Dialog 


The breakpoint dialog appears when you select At Cursor from the Break menu or New from the Break 
menu and whenever you attempt to modify a break point. It allows you to define the breakpoint and set all 
of its conditions. A description of the items in the dialog follows. 

Address This edit field displays the address tag associated with the selected breakpoint. 

When you choose At Cursor this field already contains an address that describes the line of 
code that the cursor is on. The format of the address tag is symbol+of f set where 
symbol is the name of the nearest function and offset is distance in bytes past that 
symbol where the break point is defined. It is normally best NOT to edit this field. To 
change the line of source code, leave the dialog, move the cursor to where you want the 
breakpoint, and use the At Cursor command again. 

When you choose New, this field is empty. You can type any valid address expression in 
this field. It can be the name of a function, global variable. Refer to the section entitled 
"Open Watcom Debugger Expression Handling" on page 119 for more information about 
address expressions. In the dialog, you can click the Symbols... button as a shortcut. You 
can type a partial symbol name like f oo and the Symbol button will show you a list of 
symbols that start with f oo. You can then choose one of these symbols by clicking on it 
or hitting ENTER. Note that the first time you use the Symbols... in a debugging session, 
it will take a while as the debugger sorts the symbol table for the program. 
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Note: Be careful when using local (stack) variables for a break-on-write 

breakpoint. As soon as execution leaves the scope of the variable, the 
memory will change at random since the variable does not really exist any 
more and the memory will be used for other variables. Also, if execution 
enters that variable’s scope again, the variable may not have the same 
memory address. 

Condition Use this field to enter a conditions that must be met before a breakpoint will trigger. The 
condition can be an arbitrary debugger expression. These include statements in the 
language you are debugging. A valid example for the C language is i == 1. 

Break on Execute 

Check this field to create a break-on-execute breakpoints. If you choose Execute, be sure 
that the address field contains a code address (function name or code line number) and not 
a variable address. Variable are never executed. If the address field names a variable, the 
breakpoint will never trigger. 

Break on 1 Byte/2 Bytes/4 Bytes/8 Bytes... 

Check one of these fields to create break-on-write breakpoints. If you choose one of these 
options, be sure that the Address field contains a variable address and not a code address. 

A code address will never be written to, so the breakpoint will never trigger. The size of 
the memory location is defined by the checkbox you use as follows: 

1 Byte The breakpoint will trigger only when the first byte of the memory address 

is written to. 

2 Bytes The breakpoint will trigger when either of the first two bytes at the memory 

address are written to. 

4 Bytes The breakpoint will trigger if any of the first four bytes of the memory 

address are written to. 

8 Bytes The breakpoint will trigger if any of the first eight bytes of the memory 

address are written to. This option is only supported by certain trap files 
and will be grayed out if the selected trap file does not support it. 

Note: In older versions of the debugger and traps, the break on write feature is 

really a break on change: the debugger will only stop execution if the 
breakpoint is hit and the value of the watched data has been changed. For 
the current version of the debugger this is the still the default behaviour but 
can be modified. Refer to "The Options Dialog" on page 32 to change the 
breakpoint behaviour to true break-on-write. 

Countdown Use this field to enter the number of times an address must be hit before the breakpoint 
triggers. Every time the breakpoint conditions are met, the countdown decreases by one. 
The breakpoint will trigger only after the countdown is at zero. Once the countdown 
reaches zero, the breakpoint will trigger each time the conditions are met. If you have also 
set a condition, the countdown will only decrease by one when the condition is true. 

Total Hits This field displays the total number of times an address has been hit. This includes the 

times the breakpoint does not trigger because a condition failed or the countdown has not 
yet hit zero. 

Reset Click on this button to reset the Total Hits field to zero. 

Execute when Hit 

Use this field to enter a debugger command. When the breakpoint is triggered, the 
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Resume 


Enabled 


Value 


Clear 


debugger will execute this command. You can use this field to execute arbitrary C 
statements, change a variable or register, or even set other breakpoints. For a more detailed 
description of commands that can be entered in this field, refer to the section called 
"Debugger Commands" on page 145. If you want to use this field to execute a statement in 
the language you are debugging, you need to use a DO command in front of the statement. 
For example, you could enter DO i = 10 to have the value of 10 assigned to i each time 
the breakpoint triggered. 

Check this field if you want the program to resume execution after the Execute when Hit 
command has been completed. This capability can be used to patch your code. 

This field displays the current status of the breakpoint. If it is checked, the breakpoint is 
enabled. If it is unchecked, the breakpoint is disabled. 

For Break-on-Execute breakpoints this field displays the source line or the assembly line at 
which the break point is defined. For Break-on-Write breakpoints, this field displays the 
memory contents. 

Click on the clear button to clear the breakpoint and close the dialog. 
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9 Assembly Level Debugging 


This chapter addresses the following assembly language level debugging features: 

• "The CPU Register Window" 

• "The Assembly Window" on page 82 

• "The I/O Ports Window" on page 83 

• "The FPU Registers Window" on page 84 

• "The MMX Registers Window" on page 84 

• "The XMM Registers Window" on page 85 


9.1 The CPU Register Window 



Figure 20. The CPU Register Window 

You can open the CPU Register window by choosing Register from the Data menu. The register names 
and values are displayed in this window. As you execute your program, registers that have changed since 
the last trace or breakpoint will be highlighted. 

You can modify a register value by double clicking on the value, or by cursoring to it and pressing ENTER. 
Press the right mouse button to access the following pop-up menu items: 


Modify 

Inspect 


Hex 


Change the value of the selected register. 

Open a Memory window displaying the memory contents of the address specified by the 
register. If a segment register is selected, memory at offset 0 in the segment will be 
displayed. 

Toggles the register window display format between hexadecimal and decimal. 


Extended Displays the Extended 386 register set. This menu item sets options on a per-window 

basis, overriding the global settings. When you use the menu item to change these settings, 
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they will not be saved between debugging sessions. To change an option permanently, see 
"The Window Options Dialog" on page 33. 


9.2 The Assembly Window 



Figure 21. The Assembly Window 


You can open the Assembly window by choosing Assembly from the Code menu. You can Inspect an item 
in by double-clicking on it, or by cursoring to it and pressing ENTER. Press the right mouse button to 
access the following pop-up menu items: 

Inspect When you selecting a memory address, register or operand and use Inspect, the debugger 

opens a Memory Window displaying the selected memory address. 

Break If a code address is selected this command will set a break-on-execute breakpoint at the 

selected code address. If a variable address is selected, this command will set a 
break-on-write breakpoint on the selected address, this does not set a break at the current 
line. Use Toggle from the Break menu or At Cursor from the Break menu to set a 
breakpoint at the current line. 


Enter Function 

Resume program execution until the selected function is executed. 

Show/Source Display the source code associated with the selected assembly line. 

Show/Functions 

Show the list of all functions defined in the current module. 

Show/Address Reposition the window at a new address. You will be prompted for an expression. 

Normally you would type a function name but you can type any expression that resolves to 
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a code address. For example, you might type the name of a variable that contains a pointer 
to a function. See "Open Watcom Debugger Expression Handling" on page 119. 


Show/Module... 

Show a different module. You will be prompted for its name in a dialog. As a shortcut, 
you can type the beginning of a module name and click the Module... button. This will 
display a list of all modules that start with the text you typed. 

Home Reposition the window to the currently executing location. The cursor will move to the 

next line of the program to be executed. 

No source Toggle the Assembly window display between only assembly code and assembly code 
intermixed with source lines. This menu item sets options on a per-window basis, 
overriding the global settings. When you use the menu item to change these settings, they 
will not be saved between debugging sessions. To change an option permanently, see "The 
Window Options Dialog" on page 33. 

Hex Toggle the Assembly window display between hexadecimal and decimal. This menu item 

sets options on a per-window basis, overriding the global settings. When you use the menu 
item to change these settings, they will not be saved between debugging sessions. To 
change an option permanently, see "The Window Options Dialog" on page 33. 


9.3 The I/O Ports Window 



Figure 22. The I/O Window 


Use the I/O window to manipulate I/O ports. This is only supported when the operating system allows 
application software to use IN and OUT instructions. I/O ports can be added to the window, and typed as a 
byte, word (2 bytes) or dword (4 bytes). Use New from the pop-up menu to add a new port to the window. 
Once you have done this, four items will appear on the line. First appears the read button which appears as 
an open book, or [r]. Second appears the write button. It is a pencil or [w]. Third appears the port address, 
and finally the value. When you first enter a port address the value appears as question marks. The 
debugger does not automatically read or write the value since this can have side effects. In order to read 
the displayed value from the port, click on the read button. To write the displayed value back, click on the 
write button. You can change the value by double clicking on it, or by cursoring to it and pressing ENTER. 
Press the right mouse button to access the following pop-up menu items: 


Modify Change the selected item. You can change either the value field or the address field. This 

does not write the value back to the port. You must choose Write to write to the port. 

New Add a new line to the window. You can have several I/O ports displayed at once. 
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Delete Delete the selected line from the window. 

Read Read the displayed value from the port. 

Write Write the displayed value to the port. 

Type Change the display type of the value. The size of this type determines how much is read 

from or written to the I/O port. 

9.4 The FPU Registers Window 


FPU registers (Pentium 4/Xeon) 


ST(0): +2.340000000000000000E+0001 
ST(1): ???????????????????????????? 
ST(2): ???????????????????????????? 
ST(3): ???????????????????????????? 
ST(4): ???????????????????????????? 
ST(5): ???????????????????????????? 
SI (B) ???????????????????????????? 
ST(7): ???????????????????????????? 


-JD|.X| 


TAG(O) 
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Empty 

de: 0 
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ze: 0 

cl: 0 

zm: 1 

pc: 

double 

TAG (3) 

Empty 

oe: 0 

c2: 0 

om: 1 
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Empty 

pe: 1 


pm: 1 

iptr: 

0x001 B:0x00401455 

TAG(6) 

Empty 

sf: 0 


iem: 0 

optr: 

0x0023:0x0006FD98 

TAG(7) 

Empty 



es: 0 




Figure 23. The FPU Registers Window 


Choose FPU Registers from the Data menu to open the FPU window. This window displays the current 
value and status of all the FPU registers. If you are debugging a program that uses Intel 8087 emulation, 
this window display the contents of the emulator’s data area. You can change a value by double-clicking 
on, it or by cursoring to it and pressing ENTER. Press the right mouse button to access the following 
pop-up menu items: 

Modify Change the value of the selected register, or bit. You will be prompted for a new value, 

unless you are modifying a bit. A bit will toggle between 0 and 1. 

Flex Toggle the FPU window display between hexadecimal and floating-point display. This 

menu item sets options on a per-window basis, overriding the global settings. When you 
use the menu item to change these settings, they will not be saved between debugging 
sessions. To change an option permanently, see "The Window Options Dialog" on page 
33. 


9.5 The MMX Registers Window 


< MMX Registers 
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Figure 24. The MMX Registers Window 
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Choose MMX Registers from the Data menu to open the MMX window. This window displays the current 

values of all the MMX registers. You can change a value by double-clicking on, it or by cursoring to it and 

pressing ENTER. Press the right mouse button to access the following pop-up menu items: 

Modify Change the value of the selected register component. You will be prompted for a new 

value. The same action can be performed by pressing ENTER or double-clicking as 
described above. 

Inspect This item has no function in the MMX register window. 

Hex Toggle the MMX register window display between hexadecimal and floating-point display. 

This menu item sets options on a per-window basis, overriding the global settings. When 
you use the menu item to change these settings, they will not be saved between debugging 
sessions. To change an option permanently, see "The Window Options Dialog" on page 
33. 

Signed Toggle the display of the contents of the MMX registers as signed or unsigned quantities. 

When "signed" is enabled, each byte, word, doubleword or quadword is displayed as a 
signed quantity. When "signed" is disabled, each byte, word, doubleword or quadword is 
displayed as an unsigned quantity. 

Byte Display the contents of the MMX registers as a series of 8 bytes. 

Word Display the contents of the MMX registers as a series of 4 words. 

DWord Display the contents of the MMX registers as a series of 2 doublewords. 

QWord Display the contents of the MMX registers as single quadwords. 

Float Display the contents of the MMX registers as a series of 2 IEEE single-precision 

floating-point values. 

9.6 The XMM Registers Window 


XMM Registers 
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Figure 25. The XMM Registers Window 


Choose XMM Registers from the Data menu to open the XMM window. This window displays the current 
values of all the XMM registers, as well as the contents of XMM status registers. You can change a value 
by double-clicking on, it or by cursoring to it and pressing ENTER. Press the right mouse button to access 
the following pop-up menu items: 
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Modify 

Inspect 

Hex 

Signed 

Byte 

Word 

DWord 

QWord 

Float 

Double 


Change the value of the selected register component. You will be prompted for a new 
value. The same action can be performed by pressing ENTER or double-clicking as 
described above. 

This item has no function in the XMM register window. 

Toggle the XMM register window display between hexadecimal and floating-point display. 
This menu item sets options on a per-window basis, overriding the global settings. When 
you use the menu item to change these settings, they will not be saved between debugging 
sessions. To change an option permanently, see "The Window Options Dialog" on page 
33. 

Toggle the display of the contents of the XMM registers as signed or unsigned quantities. 
When "signed" is enabled, each byte, word, doubleword or quadword is displayed as a 
signed quantity. When "signed" is disabled, each byte, word, doubleword or quadword is 
displayed as an unsigned quantity. 

Display the contents of the XMM registers as a series of 16 bytes. 

Display the contents of the XMM registers as a series of 8 words. 

Display the contents of the XMM registers as a series of 4 doublewords. 

Display the contents of the XMM registers as a series of 2 quadwords. 

Display the contents of the XMM registers as a series of 4 single-precision floating-point 
values. 

Display the contents of the XMM registers as a series of 2 double-precision floating-point 
values. 
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10 Remote Debugging 


10.1 Overview 


Remote debugging allows you to run the debugger on one side of a communication link and the application 
being debugged on the other. Remote debugging is required when there is not enough memory to run both 
the debugger and the application on the same machine. Remote debugging may also be required for 
debugging graphical applications. 

The DOS debugger runs in protected mode (above the 1M mark), with a small memory footprint in the first 
640k. Newer operating systems such as OS/2 and Windows NT/9x have eliminated the 640k barrier, so 
there is little need for remote debugging due to memory limitations alone. However, remote debugging is 
often helpful when debugging graphical or interactive application where the debugger interferes with the 
user application. Remote debugging is also required to debug Novell NetWare applications, or specialized 
embedded systems that cannot run the entire debugger. 

There are many different communication links supported. Some communicate between two machines. In 
this case an external communication medium is used. Some links communicate between two operating 
systems shells on the same machine. In either case, the concepts are the same. 

While remote debugging, you may want to reference a file that is found on one machine or the other. See 
the section entitled "Specifying Files on Remote and Local Machines" on page 100 for details about remote 
and local file names. 

The debugger is broken down into 4 parts. 

The Debugger This is the portion of the debugger that contains the user interface. It is the largest part of 
the debugger. Its name is either WD.EXE, WDW.EXE or WDC.EXE 

The Debug Kernel The debugger interprets your requests and sends low level requests to the debug kernel. 

It is a small executable that is dynamically loaded by the debugger or a remote debug 
server and used to control your application. It can be called STD.TRP, STD.DLL, 

RSI.TRP or PLS.TRP 

Remote Trap Files — These are versions of the debug kernel file that take requests and send them across a 
communications link to a remote debug server. You choose a trap file using the debugger’s 
"trap" option. See "Common Switches" on page 16. Trap files have a 3 letter file name 
that represents the name of the communications layer being used. The file extension is 
TRP or DLL. 

Remote Debug Servers — These executable files receive requests from a communications link and pass 
them to a debug kernel. Remote debug server names all start with ???SERV. The first 3 
letters represent the communication layer being used and correspond to the trap file that is 
used on the other side of the link. 

In the following examples, 
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A>cmdl 

B>cmd2 

indicates that cmdl is to be run on one machine and cmd2 is to be run on the other. 


A normal non-remote debugging session just uses the user interface and the debug kernel. All components 
run on the same machine. This simple debugging session would be started with the command: 

A>wd app 

+-+ +-+ +-+ 


WD.EXE 

STD.TRP 


APP.EXE 

/ 

/ 



\ 

\ 




Debugging a Tenberry Software DOS/4GW (32-bit extended DOS) application is the same except you must 
use a different trap file to control the application. 

A>wd /trap=rsi app 


WD.EXE 

RSI.TRP 


APP.EXE 

/ 

/ 



\ 

\ 




A remote debugging session adds a remote debug server and a remote trap file as well. For example, using 
the parallel port to debug between two machines would be accomplished using the following components: 

A>parserv 
B>wd /tr=par app 



H-parallel-t- 

i cable 


PARSERV 


STD.TRP 


APP.EXE 

.EXE 

/ 

/ 




\ 

\ 




In order to start the above remote debugging session, you must follow these steps. 


1. Connect the two machines with a parallel cable. See "Wiring For Remote Debugging" on page 
173. 
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2. Start the remote debug server (PARSERV) on one machine. 

3. Start the debugger with the option "/trap=PAR" on the other machine. This causes the debugger 
to load the remote trap file (PAR). This will communicate across the remote link to 
PARSERV.EXE, which will in turn communicate with the debug kernel (STD) in order to debug 
the application. 

The rest of the debugger command line is identical to the command you would type if you were debugging 
the application locally. 

You must start the remote debug server first. If you do not, the remote trap file will not be able to establish 
a communication link and the debugger will refuse to start. 

It is important to realize that the application to be debugged must reside on the debug server machine. It 
must be possible for the debug server to locate the application to be debugged. It can be in the current 
working directory of the debugger server machine, or in the PATH, or a path to locate the application on 
the debug server machine can be specified on the debugger command line. Alternatively, you can ask the 
debugger to download the application to the debug server machine if the application resides on the 
debugger machine. 

A>parserv 

B>wd /down /tr=par app 

See the description of the "download" option in the section entitled "Common Switches" on page 16. 

If you are remote debugging a 32-bit application, you must use the correct trap file on the remote debug 
server side of the link. The trap file specification must come first before any other arguments on the 
command line. 

A>serserv /tr=rsi 
B>wd /tr=ser app 

+-+ +-+ 

WD.EXE | | SER.TRP 

/ / 

\ \ 

+-+ +-+ 

H-serial-t- 

cable 

+-+ +-+ + + 


SERSERV 


| RSI.TRP 


APP.EXE 

.EXE 

/ 

/ 




\ 

\ 




+-+ +-+ +-+ 


Following is an example of an internal remote link. This example shows you how to use the OS/2 version 
of the debugger to debug a DOS application. 
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+-+ +-+ 

WD.EXE | | NMP.DLL 

/ / 

\ \ 

+-+ +-+ 

+— OS/2 NP API —+ 

+-+ +-+ + + 


NMPSERV 


| STD.DLL 


APP.EXE 

.EXE 

/ 

/ 




\ 

\ 




+-+ +-+ +-+ 


The communication medium employed in this case is OS/2 Named Pipes. 

The debugger provides the following remote link capabilities: 

NOV This link uses Novell's SPX layer for communication. Supported under DOS, OS/2, 

Windows 3.x, Windows NT/2000/XP and NetWare. 

NET This link uses NetBIOS to communicate. If your network software supports NetBIOS, you 

can use this link. Supported under DOS, OS/2, Windows 3.x, and NetWare. 

PAR This link supports communication using the parallel or printer port. Several different cable 

configurations are supported. See "Wiring For Remote Debugging" on page 173. 

Supported under DOS, OS/2, Windows 3.x, Windows 9x, Windows NT/2000/XP, 

NetWare, Linux and QNX 4. 

SER This link uses a serial port to communicate. Rates of up to 115K BAUD are supported. 

See "Wiring For Remote Debugging" on page 173. Supported under DOS, OS/2, Windows 
9x, Windows NT/2000/XP and QNX 4. 

WIN This link will communicate between two Windows DOS boxes. Supported under Windows 

3.x and Windows 9x (for DOS applications only). 

NMP This link will use Named Pipes to communicate internally between OS/2 sessions. OS/2, 

DOS and Win-OS/2 sessions are supported. If your network supports Named Pipes, and 
you have at least one OS/2 machine on the network, you can communicate between OS/2, 
DOS and Windows 3.x machines on the network. Supported under OS/2 (DOS, OS/2 and 
Windows 3.x applications). 

VDM This link is a subset of the NMP link. It is supported under OS/2 and Windows NT. The 

application being debugged must be a DOS or seamless Win-OS/2 application. Supported 
under OS/2 and Windows NT (DOS, OS/2 and Windows 3.x applications). 

TCP This link will use TCP/IP to communicate internally or over a network between sessions. 

Supported under DOS, OS/2, Windows 9x, Windows NT/2000/XP, Linux and QNX. 

Communication parameters may be passed to the remote trap file and the remote server. They are passed to 

the remote trap file by following the name of the trap file with a semi-colon and the parameter. For 

example: 
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A>serserv 2.4800 

passes the parameter 2.4800 to the remote debug server. To pass the same parameter to the remote trap file, 
use: 


B>wd /tr=ser;2.4800 app 

These link parameters are specific to each remote link and are described in the following section. 

Each of the debug servers can accept an optional "Once" parameter. The "Once" parameter is used by the 
Open Watcom Integrated Development Environment. Usually, a server stays running until terminated by 
the user. If the "Once" option is specified, the remote server will terminate itself as soon as the debugger 
disconnects from it. 


10.2 Link Descriptions 

The following communication links are described: 

• "NOV (Novell SPX)" 

• "NET (NetBIOS)" on page 94 

• "PAR (Parallel)" on page 94 

• "SER (Serial)" on page 95 

• "WIN (Windows 3.x/9x Virtual DOS Machine)" on page 96 

• "NMP (Named Pipes)" on page 97 

• "VDM (Virtual DOS Machine)" on page 98 

• "TCP/IP (Internet Packets)" on page 99 

10.2.1 NOV (Novell SPX) 

This link communicates over a Novell Network. In order to use this link, you must have a NetWare 
requester installed on both machines. Be sure that it is configured to include the SPX option. Consult your 
NetWare documentation for details. 

The parameter to this link is an arbitrary name to be used for the connection. This allows multiple network 
users users to remote debug simultaneously. The default name is NovLink. If the remote server will not 
start, try specifying a different name for the link. The following example shows how to use the default link 
parameters: 

A>novserv 
B>wd /tr=nov app 

The following example shows how to name "john" as a link parameter: 
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A>novserv john 

B>wd /tr=nov;john app 

10.2.2 NET (NetBIOS) 

This link communicates over NetBIOS. In order to use this link, you must have NetBIOS installed on both 
machines. Consult your network documentation for details. 

The parameter to this link is an arbitrary name to be used for the connection. This allows multiple network 
users users to remote debug simultaneously. The default name is NetLink. The following example shows 
how to use the default link parameters. 

A>netserv 
B>wd /tr=net app 

The following example shows how to use the name "tammy" as a link parameter. 

A>netserv tammy 

B>wd /tr=net;tammy app 

10.2.3 PAR (Parallel) 

This link communicates over the parallel port. Three different cable types may be used. They are called 
the LapLink, Flying Dutchman, and Watcom cables. Although the Watcom cable will communicate 
considerably faster than the other two, we have found it to be unreliable on some printer cards. See 
"Wiring For Remote Debugging" on page 173. 

The parameter to this link is a number from 1 to 3 or the letter "p" followed by a hexadecimal printer I/O 
port address. This tells the software which parallel port the cable is connected to (LPT1, LPT2, LPT3). 

The default is 1. The parameter used on each side of the link depends on which printer port the cable is 
plugged into on that machine. It need not be the same on both sides. The following example shows how to 
debug across a parallel cable plugged into printer port 3 on one machine and port 2 on the other. 

A>parserv 3 

B>wd /tr=par;2 app 

As an alternative, you can specify a port address to use. It is less convenient than specifying a port number 
but will work on systems like OS/2 where the actual I/O port address cannot be obtained from the system. 
The following example shows how to debug across a parallel cable plugged into I/O port 0x378 on one 
machine and port 2 on the other. 

A>parserv p378 
B>wd /tr=par;2 app 

Windows NT Note: Under Windows NT/2000/XP you must have the dbgport.sys device driver installed 
and loaded on your machine before the host debugger will be able to access the parallel port. To install this 
file manually, first copy it from %WATCOM%\binnt\dbgpoit.sys to %WINDOWS%\system32\drivers. 
Once the file has been copied, run the %WATCOM%\binnt\dbginst.exe program to install the device driver 
and activate it. You will need to have system administrator permissions in order to be able to run the 
dbginst.exe program. Once these two steps are done, the parallel port debugger can work. Note also that if 
you wish to do parallel port debuging on a target machine running Windows NT/2000/XP, you will need to 
follow the same set of steps on the target machine as well. 
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If you are going to debug a DOS extender application, then you must also specify a trap file to the server 
program. The trap file must be specified before the port number. The following example shows how to 
debug a 32-bit DOS/4GW application across a parallel cable plugged into printer port 2 on one machine 
and port 3 on the other. 

A>parserv /tr=rsi 2 
B>wd /tr=par;3 app 

The "RSI" trap file is specified for DOS/4G1W) applications. You can specify other trap files for the other 
DOS extenders (e.g., "CW" for CauseWay). Do not forget to include other required files in the path. 

CW Both "CWSTUB.EXE" and the loader help file "CWHELP.EXE" must also be located in 

one of the directories listed in the DOS PATH environment variable. See the section 
entitled "Debugging CauseWay 32-bit DOS Extender Applications" on page 110 for more 
information on debugging applications that use the CauseWay DOS extender. 

RSI Both "DOS4GW.EXE" and the loader help file "RSIHELP.EXP" must also be located in 

one of the directories listed in the DOS PATH environment variable. See the section 
entitled "Debugging DOS/4G1W) 32-bit DOS Extender Applications" on page 110 for 
more information on debugging applications that use the DOS/4GW DOS extender. 

PLS One or more of "RUN386.EXE" (or "TNT.EXE"), "DBGLIB.REX", "PLSHELP.EXP", 

and "PEDHELP.EXP" must be located in one of the directories listed in the DOS PATH 
environment variable. See the section entitled "Debugging Phar Lap 32-bit DOS Extender 
Applications" on page 110 for more information on debugging applications that use the 
Phar Lap DOS extender. 

10.2.4 SER (Serial) 

This link communicates over the serial port. See the appendix entitled "Wiring For Remote Debugging" on 
page 173 for wiring details. The debugger and server will automatically synchronize on a communications 
speed. They may communicate at rates as high as 115kB. The DOS and OS/2 "mode" command or the 
QNX "stty" commands need not be used. 

The parameter to this link takes the form 

port_ number.baud_ rate 

port_ number is a number from 1 to 3 indicating which serial port the cable is connected to. The default 
is 1. 

baud_ rate is the maximum BAUD rate at which to communicate. If you already know the maximum 
BAUD rate at which the two machines will communicate, this parameter will speed up the connection time 
by eliminating some of the synchronization protocol. 

baud_ rate may be any of 115200, 57600, 38400, 19200, 9600, 4800, 2400, or 1200. It may be 
shortened to the first 2 digits. 

A special BAUD rate of 0 is also allowed. This should be used if the serial port has been pre-assigned 
using the "mode" or "stty" commands. The pre-assigned BAUD rate is used and the BAUD rate 
negotiation is avoided. This will allow you to debug over a modem. 

The following example shows how to debug across a serial cable using default settings: 
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A>serserv 
B>wd /tr=ser app 

The following example shows how to debug across a serial cable using serial port 2 on each machine 
setting the maximum BAUD rate to 9600: 

A>serserv 2.9600 

B>wd /tr=ser;2.9600 app 

QNX 4 Note: Under QNX 4, a node id may be specified followed by a comma if the serial port is not 
located on the current node. The command "serserv 3,1.9600" would use the device 
//3/dev/serl at a BAUD rate of 9600. Alternatively, you can specify a device such as 
/dev/foobar. To specify the maximum line speed, you can specify something like 
/dev/foobar.56. Of course, you can also include a node id such as //5/dev/foobar. 

A>serserv //3/dev/ser2.9600 

B>wd /tr=ser;//5/dev/ser2.9600 app 

If you are going to debug a DOS extender application, then you must also specify a trap file to the server 
program. The trap file must be specified before the port number and BAUD rate. The following example 
shows how to debug a 32-bit DOS/4GW application across a serial cable using serial port 1 on one machine 
and serial port 2 on the other machine setting the maximum BAUD rate to 9600 for each: 

A>serserv /tr=rsi 1.9600 
B>wd /tr=ser;2.9600 app 

The "RSI" trap file is specified for DOS/4GIW) applications. You can specify other trap files for the other 
DOS extenders (e.g., "CW" for CauseWay). Do not forget to include other required files in the path. 

CW Both "CWSTUB.EXE" and the loader help file "CWHELP.EXE" must also be located in 

one of the directories listed in the DOS PATH environment variable. See the section 
entitled "Debugging CauseWay 32-bit DOS Extender Applications" on page 110 for more 
information on debugging applications that use the CauseWay DOS extender. 

RSI Both "DOS4GW.EXE" and the loader help file "RSIHELP.EXP" must also be located in 

one of the directories listed in the DOS PATH environment variable. See the section 
entitled "Debugging DOS/4GIW) 32-bit DOS Extender Applications" on page 110 for 
more information on debugging applications that use the DOS/4GW DOS extender. 

PLS One or more of "RUN386.EXE" (or "TNT.EXE"), "DBGLIB.REX", "PLSHELP.EXP", 

and "PEDHELP.EXP" must be located in one of the directories listed in the DOS PATH 
environment variable. See the section entitled "Debugging Phar Lap 32-bit DOS Extender 
Applications" on page 110 for more information on debugging applications that use the 
Phar Lap DOS extender. 

10.2.5 WIN (Windows 3.x/9x Virtual DOS Machine) 

This link communicates between 2 Windows DOS boxes. In order to use this link, you must have 
Windows 3.x or Windows 95 installed on your machine. You must run Windows 3.x in enhanced mode. 
You must also include the "device" specification listed below in the [386Enh] section of your 
"SYSTEM.INI" file (this line is usually added during the Open Watcom software installation process). 

DEVICE=C:\WATCOM\BINW\WDEBUG.386 
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In order for this link to work properly, you must ensure that this link runs in a DOS box that has 
background execution enabled. 

The parameter to this link is an arbitrary name to be used for the connection. This allows you to have 
multiple remote debug sessions active simultaneously. The default name is WinLink. The following 
examples show how to use the default name or specify a link name using the Windows 3.x/95 VDM link. 

A>winserv 

B>wd /tr=win app 

A>winserv whats_ in_ a_ name 

B>wd /tr=win; whats_ in_ a_ name app 

The following examples show how to debug a 32-bit extended DOS application using the Windows 3.x/95 
VDM link. 

A>winserv /tr=rsi 

B>wd /tr=win app 

A>winserv /tr=rsi whats_ in_ a_ name 

B>wd /tr=win; whats_ in_ a_ name app 

The "RSI" trap file is specified for DOS/4GIW) applications. You can specify other trap files for the other 
DOS extenders (e.g., "CW" for CauseWay). Do not forget to include other required files in the path. 

CW Both "CWSTUB.EXE" and the loader help file "CWHELP.EXE" must also be located in 

one of the directories listed in the DOS PATH environment variable. See the section 
entitled "Debugging CauseWay 32-bit DOS Extender Applications" on page 110 for more 
information on debugging applications that use the CauseWay DOS extender. 

RSI Both "DOS4GW.EXE" and the loader help file "RSIHELP.EXP" must also be located in 

one of the directories listed in the DOS PATH environment variable. See the section 
entitled "Debugging DOS/4GIW) 32-bit DOS Extender Applications" on page 110 for 
more information on debugging applications that use the DOS/4GW DOS extender. 

PLS One or more of "RUN386.EXE" (or "TNT.EXE"), "DBGLIB.REX", "PLSHELP.EXP", 

and "PEDHELP.EXP" must be located in one of the directories listed in the DOS PATH 
environment variable. See the section entitled "Debugging Phar Lap 32-bit DOS Extender 
Applications" on page 110 for more information on debugging applications that use the 
Phar Lap DOS extender. 

10.2.6 NMP (Named Pipes) 

The named pipes link allows you to communicate between any two sessions on an OS/2 machine. You can 
also debug remotely between DOS, Windows 3.x and OS/2 machines if you have installed remote named 
pipe support on these machines. See your network documentation for details on remote named pipes. 

In order to use named pipes, you must first run the NMPBIND program. This may run any OS/2 machine 
on the network. It can be run detached, by putting the following line into your OS/2 CONFIG.SYS. 

RUN=C:\WATCOM\BINP\NMPBIND.EXE 
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If you run NMPSERVW under Win-OS/2, it must be run as a seamless Windows session. This is due to 
the fact that full screen Win-OS/2 sessions may not get any processor time when they are not in the 
foreground. 

The parameter to this link can take the following forms: 
name 

name@machine 

name is an arbitrary name to be used for the connection. This allows you to have multiple remote debug 
sessions active simultaneously. The default name is NMPLink. 

machine is the name of the machine on which the NMPBIND program is running. This allows you to use 
remote named pipes. 

The following example shows you how to use the named pipe link between two sessions on the same OS/2 
machine. 

A>nmpserv 
B>wd /tr=nmp app 

The following example assumes that there is a machine named HAL with a remote named pipe server on 
the network which is running NMPBIND. 

A>nmpserv mylink@hal 

B>wd /tr=nmp;mylink@hal app 

10.2.7 VDM (Virtual DOS Machine) 

VDM is actually a limited version of named pipes that does not require the NMPBIND program to be 
running. It has several restrictions however. 

1. It does not support network debugging. 

2. Under OS/2, the debugger (user interface) must run in an OS/2 (not a DOS) session. The 
debugger may also be started under Windows NT but not Windows 95 since it does not support 
named pipes. 

3. Under OS/2, the remote debug server must run in a seamless Win-OS/2 or a DOS session. 

4. Under Windows NT, the remote debug server will be run in a Windows NT Virtual DOS 
Machine. 

5. Under Windows 95, the remote debug server can be started but since Windows 95 does not 
support named pipes it will not work properly. See the section entitled "WIN (Windows 3.x/9x 
Virtual DOS Machine)" on page 96 for an alternative. 

6. If you are running VDMSERVW under Win-OS/2, it must be run as a seamless Windows 
session. This is due to the fact that full screen Win-OS/2 sessions may not get any processor 
time when they are not in the foreground. 

The parameter to this link is an arbitrary name to be used for the connection. This allows you to have 
multiple VDM debug sessions active simultaneously. The default name is VDMLink. The following 
example shows how to use the VDM link: 

A>vdmserv 
B>wd /tr=vdm app 

The following example shows how to use the VDM link specifying "brian" as the link name. 
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A>vdmserv brian 

B>wd /tr=vdm;brian app 

10.2.8 TCP/IP (Internet Packets) 

The TCP/IP link allows you to communicate between any two sessions using TCP/IP if you have installed 
TCP/IP support. You can also debug remotely between OS/2 and Windows NT/95 machines if you have 
installed TCP/IP support on these machines. See your network documentation for details on installing 
TCP/IP support. To use TCP/IP support under DOS, you need to configure the WATTCP client and install 
a packet driver for your network card. 

In order to use TCP/IP to remotely debug a program, you must start the TCPSERV server program first. 

Example: 

A>tcpserv 

Socket port number: 3563 

Open Watcom TCP/IP Debug Server Version 2.0 
Scpyrit 1988 
Press 'q' to exit 

The server program displays an available socket port number on the screen. 

You may specify a TCP/IP "service" as an argument on the command line. TCPSERV will check the 
TCP/IP services list to find a matching service. If no argument is specified on the command line, 
TCPSERV uses "tcplink" as the service name. If no matching service name is found, TCPSERV attempts 
to convert the argument to a numeric port number and use that. If the argument can not be converted to a 
number, port number 3563 is used. 

The TCP/IP services list is stored in different places depending on the operating system. 

OS/2 d: \TCP IP \ETC\ SERVICES depending on the drive where TCP/IP is installed 

Linux and QNX /etc/services 

Windows 9x d : \windows\SERVICES depending on the drive and directory where Windows 95 is 
installed 

Windows NT d : \WINNT\SYSTEM32\DRIVERS\ETC\SERVICES depending on the drive where 
Windows NT is installed 

You will also need to know the Internet Protocol (IP) address of the machine running the TCPSERV 
program. This can be in alphanumeric or numeric form (e.g., jdoe.watcom.on.ca or 172.31.0.99). With the 
alphanumeric form, it is not necessary to specify the domain name portion if the two machines are in the 
same domain. 

To use the remote TCP/IP server, you must specify the TCP/IP trap file name to the debugger along with an 
argument consisting of your IP address, optionally followed by a and the service name or socket port 
number used by TCPSERV. You must also include the name of the application you wish to run and debug 
on the remote machine. 
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Example 1: 

A>tcpserv 

B>wd /tr=tcp;jdoe app 
or 

B>wd /tr=tcp;172.31.0.99 app 

Example2: 

A>tcpserv 1024 
B>wd /tr=tcp;jdoe:1024 app 
or 

B>wd /tr=tcp;jdoe.watcom.on.ca:1024 app 
or 

B>wd /tr=tcp;172.31.0.99:1024 app 
Example3: 

A>tcpserv dbgservice 
B>wd /tr=tcp;jdoe:dbgservice app 
or 

B>wd /tr=tcp;jdoe.watcom.on.ca:dbgservice app 
or 

B>wd /tr=tcp;172.31.0.99:dbgservice app 

The TCP/IP remote debug service permits debugging of applications anywhere on the Internet. However, 
response will vary with the distances involved. 

10.3 Specifying Files on Remote and Local Machines 

In order to identify files on either the local or remote machine, two special prefixes are supported. 

@L The "@L" prefix is used to indicate that the file resides on the local machine (the one on 

which the debugger is running). 

@L[d:][path]filename[.ext] 

When "[path]" is not specified, the current directory of the specified drive of the local 
machine is assumed. When "[d:]" is not specified, the current drive of the local machine is 
assumed. 

Example: 

0LOUTPUT.LOG 
@LD:\CMDS 

@LD:\CMDS\DATA.TMP 

@R The "@R" prefix is used to indicate that the file resides on the remote machine. 

@R[d:][path]filename[.ext] 

When "[path]" is not specified, the current directory of the specified drive of the remote 
machine is assumed. When "|d:[" is not specified, the current drive of the remote machine 
is assumed. 
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Example: 

0RMYAPPL.DAT 

@RD:\PROGRAMS\EXE\MYAPPL.LNK 
@R\PROGRAMS\SRC 
@R\PROGRAMS\SRC\UILIB.C 

Thus a file may be identified in three different ways. 

[d:][path]filename[.ext] 

@L[d:][path]filename[.ext] 

@R[d:][path]filename[.ext] 

A file of the first form resides on either the local or remote machine depending on whether the current drive 
is a local or remote drive. A file of the second form always resides on the local machine. A file of the third 
form always resides on the remote machine. 

Notes: 

1. In the each form, the omission of "[d:]" indicates the current drive. 

[path]filename[.ext] 

@L[path]filename[.ext] 

@R[path]filename[.ext] 

2. In the each form, the omission of "[path]" indicates the current path of the specified drive. 

[d:]filename[.ext] 

@L[d:]filename[.ext] 

@R[d:]filename[.ext] 

Observe that if "[d:]" is omitted also then the following forms are obtained: 

filename[.ext] 

@Lfilename[.ext] 

@Rfilename[.ext] 

3. The special drive prefixes "@L" and "@R" cannot be used in your own application to reference 
files on two different machines. These prefixes are recognized by the Open Watcom Debugger 
only. Should the situation arise where one of your filenames begins with the same prefix ("@L", 
"@1", "@R" or "@r") then "@@" can be used. For example, if your wish to refer to the file on 
disk called "@link@" then you could specify "@@link@". Note that "A@link@" would also 
suffice. 
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111nterrupting a Running Program 


11.1 Overview 

It is not unusual for your code to contain an endless loop that results in the program getting stuck in one 
spot. You then want to interrupt the program so that you can see where it’s getting stuck. The process to 
give control back to the debugger is different for each operating system. 

11.2 DOS 

Press the Print Screen key. This will work if the program is stuck in a loop. If it has misbehaved in some 
other way. Print Screen may have no effect since a misbehaved application may overwrite code, data, the 
debugger, or operating system code. 

When debugging with the CauseWay DOS extender, by default the running program can be interrupted by 
pressing CTRL-ALT. The key combination is configurable in the CWHELP.CFG file (located in "BINW" 
directory). 

11.3 Windows 3.x 

Press CTRL-ALT-F. Windows must be running in enhanced mode and the device WDEBUG.386 must be 
installed the [386Enh] section of SYSTEM.INI for this to work. You cannot interrupt a running program 
under Win-OS/2. 


11.4 Windows NT, Windows 95 

If you are using the non-GUI version of the debugger, switch focus to the debugger screen and press 
CTRF-BREAK. 

If you are using the GUI-based version of the debugger or one of the remote debug servers, switch focus to 
the debugger or debug server screen and click anywhere. When you switch to the debugger screen, you 
will see a pop-up stating that: 

The debugger cannot be used while the application is 
running. Do you want to interrupt the application? 

If you select "Yes", the debugger will attempt to interrupt the application. If you select "No", the debugger 
will resume waiting for the application to hit a breakpoint or terminate. 

If you select "Yes" and the debugger cannot interrupt the application, you can click on the debugger again 
and it will display a pop-up asking: 
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The debugger could not sucessfully interrupt your 
application. Do you want to terminate the application? 

If you select "Yes", the debugger will terminate your application. If you select "No", the debugger will 
resume waiting for the program to hit a breakpoint or terminate. 

Note: Under Windows 95, it is very difficult to interrupt a program that is in an infinite loop or 

spending most of its time in system API's. Under Windows 95, you can only interrupt a 
program that is responding to messages (or looping in its own thread code). If your 
program is an infinite loop, interrupting the program will likely fail. The only option in this 
case is to terminate the program. 

This is not an issue under Windows NT which has a superior debug API. 

If you press CTRL-BREAK when the application has focus, you will terminate the application being 
debugged rather than interrupting it. 


11.5 OS/2 


Use the program manager to switch focus to the debugger screen then press CTRL-BREAK. If you press 
CTRL-BREAK when the application has focus, you will terminate the application being debugged rather 
than interrupting it. 


11.6 NetWare 


On the NetWare file server console, press ALT-ESCAPE while holding down both SHIFT keys. In some 
instances, this may cause the system debugger to become active instead of the Open Watcom Debugger. 


11.7 Linux 


Switch focus to the debugger console and press CTRL-C. Alternatively, you may send any unhandled 
signal to the application being debugged. Consult your Linux documentation for details. 


11.8 QNX 


Switch focus to the debugger console and press CTRL-BREAK. Alternatively, you may send any 
unhandled signal to the application being debugged. Consult your QNX system documentation for details. 
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12 Operating System Specifics 


This section discusses the following topics: 

DOS Extender debugging 

See the section entitled "Debugging 32-bit DOS Extender Applications". 

NLM debugging 

See the section entitled "Debugging a Novell NLM" on page 111. 

Graphics programs 

See the section entitled "Debugging Graphics Applications" on page 111. 
Windows 3.x debugging 

See the section entitled "Debugging Windows 3.x Applications" on page 112. 

DLL debugging 

See the section entitled "Debugging Dynamic Link Libraries" on page 112. 
Disabling 386/486 debug registers 

See the section entitled "Disabling Use of 386/486 Debug Registers" on page 113. 
Linux debugging 

See the section entitled "Debugging Under Linux" on page 113. 

QNX debugging 

See the section entitled "Debugging Under QNX" on page 114. 


12.1 Debugging 32-bit DOS Extender Applications 

The Open Watcom Debugger supports debugging of 32-bit applications developed with Open Watcom 
C/C++(32), Open Watcom FORTRAN 77/32, and assembly language. A DOS extender must be used to 
run the application. The following DOS extenders are suppoited. 

CauseWay DOS Extender 

a public domain DOS extender included in the Open Watcom C/C++(32) and Open 
Watcom FORTRAN 77/32 packages. Note that this DOS extender is largely compatible 
with DOS/4GW and can often be used interchangeably. 

DOS/4GW a DOS extender from Tenberry Software, Inc. DOS/4GW is a subset of Tenberry 
Software’s DOS/4G product. DOS/4GW is customized for use with Open Watcom 
C/C+-H32) and Open Watcom FORTRAN 77/32 and is included in these packages. 

386\DOS-Extender 

(version 2.2d or later) a DOS extender from Phar Lap Software, Inc. 
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12.1.1 Debugging CauseWay 32-bit DOS Extender Applications 

When using the CauseWay DOS extender, the "CWSTUB.EXE" file must be located in one of the 
directories listed in the DOS PATH environment variable. The "CWSTUB.EXE" file will usually be 
stored in the "BINW" directory of the Open Watcom compiler package. You must also use the TRap=CW 
option. The "CW.TRP" file will usually be stored in the "BINW" directory of the Open Watcom compiler 
package. You should ensure that this "BINW" directory is included in the DOS PATH environment 
variable. Otherwise, you must specify the full path name for the trap file. 

The help file "CWHELP.EXE" must also be located in one of the directories listed in the DOS PATH 
environment variable. It will usually be stored in the "BINW" directory of the Open Watcom compiler 
package. 

Example: 

C>wd /trap=cw hello 
or 

C>set wd=/trap#cw 
C>wd hello 

12.1.2 Debugging D0S/4G(W) 32-bit DOS Extender Applications 

When using the Tenberry Software DOS extender, the "DOS4GW.EXE" or "DOS4G.EXE" file must be 
located in one of the directories listed in the DOS PATH environment variable. The "DOS4GW.EXE" file 
will usually be stored in the "BINW" directory of the Open Watcom compiler package. You must also use 
the TRap=RSI option. The "RSI.TRP" file will usually be stored in the "BINW" directory of the Open 
Watcom compiler package. You should ensure that this "BINW" directory is included in the DOS PATH 
environment variable. Otherwise, you must specify the full path name for the trap file. 

The help file "RSIHELP.EXP" must also be located in one of the directories listed in the DOS PATH 
environment variable. It will usually be stored in the "BINW" directory of the Open Watcom compiler 
package. 

Example: 

C>wd /trap=rsi hello 
or 

C>set wd=/trap#rsi 
C>wd hello 

12.1.3 Debugging Phar Lap 32-bit DOS Extender Applications 

When using the Phar Lap Software, Inc. DOS extender, the "RUN386.EXE" (or "TNT.EXE"), 
"DBGLIB.REX", "PLSHELP.EXP", and "PEDHELP.EXP" files must be located in one of the directories 
listed in the DOS PATH environment variable. You must also use the TRap=PLS option. The 
"PLS.TRP", "PLSHELP.EXP" and "PEDHELP.EXP" files will usually be stored in the "BINW" directory 
of the Open Watcom compiler package. You should ensure that this "BINW" directory is included in the 
DOS PATH environment variable. Otherwise, you must specify the full path name for the trap file. 

Parameters are passed to the "RUN386" or "TNT" DOS extender using the TRap option. The entire 
parameter must be placed within braces. The following example illustrates how to debug a Phar Lap 
application passing the -maxreal switch to RUN386.EXE or TNT.EXE. 
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Example: 

C>wd /trap=pls;{-maxreal 512} hello 
or 

C>set wd=/trap#pls;{-maxreal 512} 
C>wd hello 


12.2 Debugging a Novell NLM 

Novell NLM’s may only be debugged remotely. You must use either the serial, parallel, or Novell SPX 
link. There are 5 NLM’s distributed in the Open Watcom package. The following table describes their use: 

NetWare 3.11/3.12 NetWare 4.01 

Serial serserv4.nlm 

Parallel parserv3.nlm parserv4.nlm 

SPX novserv3.nlm novserv4.nlm 

To start remote debugging, you load one of the above NLMs at the NetWare file server console. The 
debugger is then invoked as in any remote debugging session. See the chapter entitled "Remote 
Debugging" on page 89 for parameter details. See the appendix entitled "Wiring For Remote Debugging" 
on page 173 for parallel/serial cable details. 

For example, on a NetWare 4.01 server type: load novserv4 

On a workstation, type: WD /tr=nov mynlm 

Debugging information for every running NLM is available. You can debug any NLM in the system as if it 
were part of your application, as long as you created it with debug information. If the NLM does not have 
Watcom style debugging information, the debugger will attempt to use any debugging information created 
by Novell’s linker (NLMLINK). 

12.3 Debugging Graphics Applications 

When debugging a graphics application, there are a number of Open Watcom Debugger command line 
options that could be specified depending on your situation. 

1. If you only have one monitor attached to your system, use the Swap option. The Swap option 
specifies that the application’s screen memory and the debugger’s screen memory are to be 
swapped back and forth using a single page. 

2. If you have two monitors attached to your system then the Two and Monochrome options should 
be used. The Two option specifies that a second monitor is connected to the system. Note that if 
the monitor type ( Monochrome, Color, Colour, Ega43, Vga50) is not specified then the monitor 
that is not currently being used is selected for the debugger’s screen. If you specify 
Monochrome then the monochrome monitor will be used for the debugger’s screen. 

3. If you are debugging the graphics application using a second personal computer and the remote 
debugging feature of the Open Watcom Debugger then the choice of display and operation mode 
for the Open Watcom Debugger is irrelevant. If one system is equipped with a graphics display 
and the other with a monochrome display then you will undoubtedly use the system equipped 
with the monochrome display to run the Open Watcom Debugger. 
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12.4 Debugging Windows 3.x Applications 

Both a character mode and a GUI debugger are supplied that run in the Windows environment. You must 
choose which of these debuggers you are going to use. They both have advantages and disadvantages. 
When your application is suspended, the GUI and character mode debuggers behave differently. The GUI 
debugger allows other applications to continue running. The character mode debugger does not. Although 
the GUI debugger has a much nicer looking user interface, you should not use it under some circumstances. 
You can always use the character mode debugger. You should be aware of the following restrictions: 

1. If you are trying to debug an applications that uses DDE you should not use the GUI debugger. 

2. Do not try to use the GUI debugger to debug system modal dialogs. 

3. If you hit a break-point in a dialog callback procedure or in your window procedure when it is 
receiving certain events (e.g., WM_MENUSELECT), the GUI debugger will lock input to itself. 
When this happens, you will not be able to switch away from the debugger, and no other 
application will repaint themselves. When this happens, pop-up menus will not draw correctly 
and you will have to use the Action menu instead. You should not try to quit the debugger when 
it is in this state. 

4. Do not try to use either of the Windows debuggers in a seamless Win-OS/2 session. 

If you find that the Windows debugger starts too slowly, try using the DIp=DWARF option. This prevents 
the debugger from searching each DLL in the system for debugging information. It will start up faster, but 
you will not be able to see the name of the Windows API calls. 

To start the Open Watcom Debugger, select the program group in which you have installed the Open 
Watcom Debugger. One of the icons presented is used to start the debugger. Double-click on the Open 
Watcom Debugger icon. 

You can make special versions of the Open Watcom Debugger icon using Properties from the File menu of 
the Windows "Program Manager". For example, you can add any options you wish to the "Command 
Line" field of the "Properties" window. When you click on the newly created icon, the options specified in 
the "Command Line" field are the defaults. As long as no executable file name was specified in the 
"Command Line" field, the Open Watcom Debugger will present its prompt window. In the prompt 
window, you can specify an executable file name and arguments. 

If you are debugging the same program over and over again, you might wish to create an icon that includes 
the name of the file you wish to debug in the "Command Line" field. Each time you click on that icon, the 
Open Watcom Debugger is started and it automatically loads the program you wish to debug. 

12.5 Debugging Dynamic Link Libraries 

The debugger automatically detects all DLLs that your application references when it loads the application. 
When your program loads a DLL dynamically, the debugger detects this as well. If you have created your 
DLL with debugging information, you can debug it just as if it were part of your application. Even if it 
does not have debugging information, the debugger will process system information to make the DLL entry 
point names visible. There are a few limitations: 

1. You cannot debug your DLL initialization code. This is the first routine that the operating 
system runs when it loads the DLL. This is not normally a problem, since most DLLs do not do 
much in the way of initialization. 

2. When a DLL is loaded dynamically, its debugging information may not be available 
immediately. Try tracing a few instructions and it will appear. 
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3. If you restart an application, you will lose any break points that you had set in dynamically 
loaded DLLs. You need to trace back over the call to LoadModule or DOSLoadModule and 
re-set these break points. 

12.6 Disabling Use of 386/486 Debug Registers 

It may be necessary to prevent the Open Watcom Debugger from using the 386/486 Debug Registers (a 
hardware feature used to assist debugging). This situation arises with certain DOS control programs that do 
not properly manage Debug Registers. If the Open Watcom Debugger fails upon startup on a 386/486 
system, it is a good indication that use of the Debug Registers must be disabled. With "STD.TRP", the trap 
file parameter "d" may be specified to disable the use of Debug Registers. The following example 
illustrates the specification of the "d" trap file parameter. 

Example: 

C>wd /trap=std;d calendar 

12.7 Debugging Under Linux 

When the debugger starts up, it will attempt to open the initialization file . wdrc provided that you have 
not specified the Invoke command line option. It looks for this file in all the usual places ( CWD, 
WD_PATH, /opt/watcom/wd). This file normally contains your customization commands. If it is 
found, it is processed as the default configuration file. You would normally place this file in your home 
directory. 

If the file does not exist, the debugger then looks for the wd. dbg file. 

If you do not want the debugger to use the . wdrc file then you can do one of two things — make sure that 
it cannot be located (e.g., delete it) or use the Invoke command line option (you could specify the wd. dbg 
file as the target). 

The supplied version of the wd. dbg file contains an "invoke" command referencing the file 
setup. dbg . This file, in turn, contains a "configfile" command and "invoke" commands referencing 
other command files. The "configfile" command marks setup. dbg as the default file name to use when 
the debugger writes out the current configuration. 

The following section entitled "Search Order for Open Watcom Debugger Support Files under Linux" 
describes the search order for debugger files under Linux. 

12.7.1 Search Order for Open Watcom Debugger Support Files under Linux 

There are several supporting files provided with the Open Watcom Debugger. These files fall into five 
categories. 

1. Open Watcom Debugger command files (files with the ".dbg" suffix). 

2. Open Watcom Debugger trap files (files with the ".tip" suffix). 

3. Open Watcom Debugger parser files (files with the ".prs" suffix). 

4. Open Watcom Debugger help files (files with the ".hip" suffix). 


Debugging Under Linux 113 




Operating System specifics 


5. Open Watcom Debugger symbolic debugging information files (files with the ".sym" suffix). 

The search order for Open Watcom Debugger support files is as follows: 

1. the current directory, 

2. the paths listed in the WD_PATH environment variable, 

3. the path listed in the HOME environment variable 

4. the directory where Open Watcom Debugger was started from 

5. "../wd" directory relative to the directory where Open Watcom Debugger was started from, and, 
finally, 

6. the "/opt/watcom/wd" directory. 

You should note the following when using the remote debugging feature of the Open Watcom Debugger. 
When the REMotefiles option is specified, the debugger also attempts to locate the Open Watcom 
Debugger’s support files (command files, trap files, etc.) on the task machine. 

12.8 Debugging Under QNX 

When the debugger starts up, it will attempt to open the initialization file . wdrc provided that you have 
not specified the Invoke command line option. It looks for this file in all the usual places ( CWD, 
WD_PATH, / usr/watcom/<ver>/wd, /usr/watcom/wd). This file normally contains your 
customization commands. If it is found, it is processed as the default configuration file. You would 
normally place this file in your home directory. 

If the file does not exist, the debugger then looks for the wd. dbg file. 

If you do not want the debugger to use the . wdrc file then you can do one of two things — make sure that 
it cannot be located (e.g., delete it) or use the Invoke command line option (you could specify the wd. dbg 
file as the target). 

The supplied version of the wd. dbg file contains an "invoke" command referencing the file 
setup. dbg. This file, in turn, contains a "configfile" command and "invoke" commands referencing 
other command files. The "configfile" command marks setup. dbg as the default file name to use when 
the debugger writes out the current configuration. 

The following section entitled "Debugging Under QNX Using the Postmortem Dump Facility" describes 
the use of the debugger with the Postmortem dump facility. The following section entitled "Search Order 
for Open Watcom Debugger Support Files under QNX" on page 116 describes the search order for 
debugger files under QNX. 

12.8.1 Debugging Under QNX Using the Postmortem Dump Facility 

A limited form of debugging of an application that has terminated and produced a postmortem dump can be 
done under QNX. In order to use this feature, you must start the QNX "dumper" program. 


dumper [-d path] [-p pid] & 
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dumper is the program name for the QNX postmortem dump program. 

-d path The name of the directory in which postmortem dumps are written. If not specified, the 

default is the user’s home directory. 

-p pid Save a dump file for this process if it terminates for any reason. Do not save a dump file 

for any other process. 

& must be specified so that the shell is rejoined. 

Example: 

$ dumper & 

$ dumper -d /usr/fred/dump_ area & 

Whenever a program terminates abnormally, a dump of the current state of the program in memory is 
written to disk. The dump file name is the same as the program name with a .dmp extension. For example, 
if the program name is a.out then the dump will be written to the /home/userid/a.out.dmp file. 

You can use the -d option of the dumper program to force all dumps into a single directory rather than into 
the invoking user’s home directory. 

The -p option lets you monitor a particular process. You can run multiple copies of the dumper program, 
each monitoring a different process. 

If the Open Watcom Debugger was being used to debug the program at the time that it abnormally 
terminated then the dump is written to the user’s home directory provided that the -d option was not used. 

To examine the contents of the postmortem dump, the Open Watcom Debugger may be used. The interface 
between the Open Watcom Debugger and the postmortem dump is contained in a special "trap" file. The 
trap file is specified to the Open Watcom Debugger using the TRap option. 

wd -TRap=pmd[;i] [:sym_file]file_spec 

wd is the program name for the Open Watcom Debugger. 

-TRap=pmd[ i] must be specified when debugging an application that has terminated and produced a 

postmortem dump. The optional ";i" is specified when the modification date of the original 
program file does not match the information contained in the dumper file. It indicates that 
the symbolic debugging information in the program file may be out-of-date. It instructs the 
Open Watcom Debugger to ignore the date mismatch. Depending on the shell that you are 
using, it may be necessary to place the option specification in quotation marks if you 
include the optional ";i". 

Example: 

$ wd "-trap=pmd;i" myapp 

sym Jile is an optional symbolic information file specification. The specification must be preceded 

by a colon When specifying a symbol file name, a path such as "//5/etc/" may be 
included. For QNX, the default file suffix of the symbol file is ".sym". 

file_spec is the file name of the dumper file to be loaded into memory. When specifying a file name, 

a path such as "//5/etc/" may be included. If a path is omitted, the Open Watcom Debugger 
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will first attempt to locate the file in the current directory and, if not successful, attempt to 
locate the file in the default dumper directory: /usr/dumps. 

Basically, the Open Watcom Debugger is fully functional when a postmortem dump is examined. 
However, there are some operations which are not allowed. Among these are: 

1. Task execution cannot be restarted using Go from the Run menu. 

2. A register can be modified for the purposes of expression evaluation. You can choose Go from 
the Run menu to restore the register contents to their original postmortem state. 

3. Memory cannot be modified. 

4. Memory outside of regions owned by the program cannot always be examined. 

5. I/O ports cannot be examined. 


12.8.2 Search Order for Open Watcom Debugger Support Files under QNX 

There are several supporting files provided with the Open Watcom Debugger. These files fall into five 
categories. 

1. Open Watcom Debugger command files (files with the ".dbg" suffix). 

2. Open Watcom Debugger trap files (files with the ".tip" suffix). 

3. Open Watcom Debugger parser files (files with the ".prs" suffix). 

4. Open Watcom Debugger help files (files with the ".hip" suffix). 

5. Open Watcom Debugger symbolic debugging information files (files with the ".sym" suffix). 
The search order for Open Watcom Debugger support files is as follows: 

1. the current directory, 

2. the paths listed in the WD_PATH environment variable, 

3. the path listed in the HOME environment variable, and, finally, 

4. the "/usr/watcom/wd" directory. 

You should note the following when using the remote debugging feature of the Open Watcom Debugger. 
When the REMotefiles option is specified, the debugger also attempts to locate the Open Watcom 
Debugger’s support files (command files, trap files, etc.) on the task machine. 
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13 Open Watcom Debugger Expression Handling 


13.1 Introduction 


The Open Watcom Debugger is capable of handling a wide variety of expressions. An expression is a 
combination of operators and operands selected from application variables and names, debugger variables, 
and constants. Expressions can be used in a large number of debugger commands and dialogs. For 
example, the evaluated result of an expression may be displayed by choosing New from the pop-up menu in 
the Watches window or by using the print command. 

The appropriate syntax of an expression, i.e., the valid sequence of operators and operands, depends on the 
grammar of the language that is currently established. The Open Watcom Debugger supports the grammars 
of the C, C++, and FORTRAN 77 languages. A grammar is selected automatically by the debugger when 
tracing the execution of modules in an application. For example, part of an application may be written in 
C, another part in C++, and another part in FORTRAN 77. The modules must have been compiled by one 
of the Open Watcom C, C++ or FORTRAN 77 compilers. When tracing into a module written in one of 
these languages, the debugger will automatically select the appropriate grammar. In addition to this 
automatic selection, a particular grammar may be selected using the debugger Set LAnguage command. 

The language currently selected can be determined using the SHow Set LAnguage command. 

13.2 General Rules of Expression Handling 

The debugger handles two types of expressions. The difference between the two types of expressions is 
quite subtle. One is called an "expression" and things operate as you would normally expect. This type of 
expression is used for all "higher" level operations such as adding items to the Watches window. The other 
type is called an "address expression". It is used whenever the debugger prompts for an address and in 
lower level commands such Examine and Modify. If the notation for a particular command argument is 
<address>, it is an address expression. If it ends in just "expr" then it is a normal expression. The 
difference between the two forms lies in how they treat symbol names. In a normal expression the value of 
a symbol is its n’alue, or contents. In an address expression, the value of a symbol is (sometimes) its 
lvalue, or address. 

Consider the following case. You have a symbol sam at offset 100 and the word at that location contains 
the value 15. If you enter sam into the watches window you expect the value 15 to be printed and since the 
Watches window takes a normal expression that is what you get. Now let us try it with the Breakpoint 
dialog. Enter sam in the address field. The Breakpoint dialog uses the result of its expression as the 
address at which to set a breakpoint. The Breakpoint dialog takes an address expression, and an implicit 
unary "&" operator is placed in front of symbols. The debugger has a set of heuristics that it applies to 
determine whether it should use the rvalue or lvalue of a symbol. 
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13.3 Language Independent Variables and Constants 

The following sections describe conventions used in the debugger for identifying modules, variables, line 
numbers, registers, etc. 

13.3.1 Symbol Names 

Regardless of the programming language that was used to code the modules of an application, the names of 
variables and routines will be available to the debugger (provided that the appropriate symbolic debugging 
information has been included with the application’s execution module). The debugger does not restrict the 
way in which names are used in expressions. A name could represent a variable but it could also represent 
the entry point into a routine. 

The syntax of a symbol name reference is quite complicated. 

[[[image] @][module] @][routine _name.]symbol_name 

Generally, an application will consist of many modules which were compiled separately. The current 
image is the one containing the module which is currently executing. The current module is the one 
containing the source lines currently under examination in the Source or Assembly window. By default, 
the Source window’s title line contains the current module name. The current routine is the one containing 
the source line at which execution is currently paused. 

The following are examples of references to symbol names. 

Example: 

symbol_ name 

main 

WinMain 

FMAIN 

printf 

LIB$G_ OPEN 

stdin 

If the symbol does not exist in the current scope then it must be qualified with its routine name. Generally, 
these are variables that are local to a particular routine. 

Example: 

routine_ name . symbol_ name 

main.curr_ time 

main.tyme 

SUB1.X 

SUB2 . X 

If the symbol is not externally defined and it does not exist in the current module then it may be qualified 
with its module name. In the C and C++ programming languages, we can define a variable that is global to 
a module but known only to that module ("static" storage class). 

Example: 

static char *NarrowTitle = { "Su Mo Tu We Th Fr Sa" }; 

In the above example, "NarrowTitle" is global to the module "calendar". If the current module is not 
"calendar" then the module name can be used to qualify the symbol as shown in the following example. 
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Example: 

calendar@NarrowTitle 

If the symbol is local to a routine that is not in the current module then it must be qualified with its module 
name and routine name. 

Example: 

module_ name@routine_ name . symbol_ name 
calendar@main.curr_ time 
calendar@main.tyme 
subsSSUBl.X 
subs@SUB2.X 

If the symbol is local to an image that is not in the current executable then it must be fully qualified with 
the image name. 

Example: 

prog_ name@@routine_ name 

prog_ name@module_ name@routine_ name 

prog_ name@module_ name@routine_ name.symbol_ name 

dll_ name@calendar@main . curr_ time 

dll_ name@calendar@main.tyme 

program@subs@SUBl.X 

program@subs@SUB2.X 

There is a special case for the primary executable image. This is the name of the program you specified 
when you started the debugger. You can reference it by omitting the image name. The following examples 
all refer to symbols in the primary executable image: 

Example: 

@@WinMain 
@module@WinMain 
@@routine.symbol 

In the FORTRAN 77 programming language, all variables (arguments, local variables, COMMON block 
variables) are available to the subprogram in which they are defined or referenced. The same symbol name 
can be used in more than one subprogram. If it is a local variable, it represents a different variable in each 
subprogram. If it is an argument, it may represent a different variable in each subprogram. If it is a 
variable in a COMMON block, it represents the same variable in each subprogram where the COMMON 
block is defined. 
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Example: 

SUBROUTINE SUB1( X ) 
REAL Y 

COMMON /BLK/ Z 


END 

SUBROUTINE SUB2( X ) 
REAL Y 

COMMON /BLK/ Z 


END 

In the above example, "X" is an argument and need not refer to the same variable in the calling 
subprogram. 

Example: 

CALL SUB1( A ) 

CALL SUB2( B ) 

The variable "Y" is a different variable in each of "SUB1" and "SUB2". The COMMON block variable 
"Z" refers to the same variable in each of "SUB1" and "SUB2" (different names for "Z" could have been 
used). To refer to "X", "Y", or "Z" in the subprogram "SUB2", you would specify "SUB2.X", "SUB2.Y", 
or "SUB2.Z". If "SUB2" was in the module "MOD" and it is not the current module, you would specify 
"MOD@SUB2.X", "MOD@SUB2.Y", or "MOD@SUB2.Z". 

Note: Global and local symbol name debugging information is included in an executable image if 

you request it of the linker. However, local symbol information must be present in your 
object files. The Open Watcom C, C++ and FORTRAN 77 compilers can include local 
symbol debugging information in object files by specifying the appropriate compiler 
option. See "Preparing a Program to be Debugged" on page 9. 

13.3.2 Line Numbers 

Regardless of the programming language that was used to code the modules of an application, line number 
information identifying the start of executable statements will be available to the debugger (provided that 
the appropriate symbolic debugging information has been included with the application’s execution 
module). The debugger does not restrict the way in which line number references are used in expressions. 
A line number represents the code address of an executable statement in a routine. Not all line numbers 
represent executable statements; thus some line numbers may not be valid in an expression. For example, 
source lines consisting of comments do not represent executable statements. 

The general format for a line number reference is: 

[ [image]@ ] [module_name] @ decimal_digits 

The following are examples of references to executable statements. 


122 Language Independent Variables and Constants 




Open Watcom Debugger Expression Handling 


Example: 

@36 

@@45 

@51 

@125 

hello@ 9 

@hello@ 9 

prog@hello@ 9 

otherprg@goodbye@ 9 

puzzle@50 

calendar@20 

SUB103O 

If the line number does not exist in the current module, it must be qualified with its module name. If it does 
not exist in the current image, it must be qualified with the image name. Line numbers are not necessarily 
unique. For example, an executable statement could occur at line number 20 in several modules. The 
module name can always be used to uniquely identify the line 20 in which we are interested. In the above 
examples, we explicitly refer to line 20 in the module "calendar". When the module name is omitted, the 
current module is assumed. 

Note: Line number debugging information is included in an executable image if you request it of 

the linker. However, line number information must be present in your object files. The 
Open Watcom C, C++ and FORTRAN 77 compilers can include line number debugging 
information in object files by specifying the appropriate compiler option. See "Preparing a 
Program to be Debugged" on page 9. You can request line number debugging information 
when assembling assembly language source files using Open Watcom Assembler The "dl" 
option must be specified on the command line. 


13.3.3 Constants 

A constant can be arithmetic or character. Each constant has a data type associated with it. Arithmetic 
constants consist of those constants whose data type is one of integer, real, or complex (FORTRAN only). 

C treats character constants like arithmetic constants so they can be used in arithmetic expressions. 
FORTRAN treats character constants as constants of type CHARACTER so they cannot be used in 
arithmetic expressions. 

13.3.3.11nteger Constants 

An integer constant is formed by a non-empty string of digits preceded by an optional radix specifier. The 
digits are taken from the set of digits valid for the current radix. If the current radix is 10 then the digits are 
’0’ through '9’. If the current radix is 16 then the digits are ’O' through ’9’ and 'A' through ’F’ or ’a’ 
through 'f. See "The Options Dialog" on page 32. 

The following are examples of integer constants. 


Example: 

123 

57DE 

1423 

345 

34565788 
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Radix specifiers may be defined by the user, but two are predefined by the debugger. Ox may be defined to 
be a radix specifier for hexadecimal (base 16) numbers. On may be defined to be a radix specifier for 
decimal (base 10) numbers 


Example: 

0x1234 

0nl234 

255 

Oxff 

OxlADB 

0n200 

0xl2fc0 


hexadecimal 

decimal 

decimal 

hexadecimal 

hexadecimal 

decimal 

hexadecimal 


13.3.3.2 Real Constants 

We first define a simple real constant as follows: an optional sign followed by an integer part followed by 
a decimal point followed by a fractional part. The integer and fractional parts are non-empty strings of 
digits. The fractional part can be omitted. 

A real constant has one of the following forms. 

(1) A simple real constant. 

(2) A simple real constant followed by an E or e followed by an optionally signed integer 
constant. 


The optionally signed integer constant that follows the E is called the exponent. The value of a real 
constant that contains an exponent is the value of the constant preceding the E multiplied by the power of 
ten determined by the exponent. 


The following are examples of real constants. 

123.764 
0.4352344 
1423.34E12 
+345.E-4 
-0.4565788E3 
2 . E6 
1234 . 


Note: The accepted forms of floating-point constants are a subset of that supported by the 

FORTRAN 77 programming language. The debugger does not support floating-point 
constants that begin with a decimal point (e.g., .4352344) or have no decimal point (e.g., 
2E6). However, both forms would be acceptable to a FORTRAN compiler. Also, the 
debugger does not support double precision floating-point constants where "D" is used 
instead of "E" for the exponent part (e.g., 2D6, 2.4352344D6). All floating-point constants 
are stored internally by the debugger in double precision format. 

13.3.3.3 Complex Constant (FORTRAN Only) 

A complex constant consists of a left parenthesis, followed by a real or integer constant representing the 
real part of the complex constant, followed by a comma, followed by a real or integer constant representing 
the imaginary part of the complex constant, followed by a right parenthesis. 
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The following are examples of complex constants. 

( 1423.34E12, 3 ) 

( +345, 4 ) 

Complex constants will be accepted when the debugger’s currently established language is FORTRAN. 

The language currently selected can be determined using the SHow Set LAnguage command. 

13.3.3.4 Character Constant (C Only) 

In the C and C++ programming languages, a character constant consists of an apostrophe followed by a 
single character followed by an apostrophe. The apostrophes are not part of the datum. An apostrophe in a 
character datum represents one character, namely the apostrophe. A character constant must have length 1. 

The following are examples of character constants. 

'A' 

' e' 

III 


The C/C++ form of a character constant will be accepted when the debugger’s currently established 
language is C or C++. The language currently selected can be determined using the SHow Set LAnguage 
command. 

13.3.3.5 Character String Constant (FORTRAN Only) 

In the FORTRAN 77 programming language, a character constant consists of an apostrophe followed by 
any string of characters followed by an apostrophe. The apostrophes are not part of the datum. If an 
apostrophe is to appear as part of the datum it must be followed immediately by another apostrophe. Note 
that blanks are significant. The length of the character constant is the number of characters appearing 
between the delimiting apostrophes. Consecutive apostrophes in a character datum represent one character, 
namely the apostrophe. A character constant must not have length 0. 

The following are examples of character constants. 

'ABCDEFG1234567' 

'There''s always tomorrow' 

The FORTRAN form of a character constant will be accepted when the debugger’s currently established 
language is FORTRAN. 

13.3.4 Memory References 

In addition to referring to memory locations by symbolic name or line number, you can also refer to them 
using a combination of constants, register names, and symbol names. In the Intel 80x86 architecture, a 
memory reference requires a segment and offset specification. When symbol names are used, these are 
implicit. The general form of a memory reference is: 

[segment:]offset 

When an offset is specified alone, the default segment value is taken from the CS, DS or SS register 
depending on the circumstances. 
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13.3.5 Predefined Debugger Variables 

The debugger defines a number of symbols which have special meaning. These symbols are used to refer 
to the computer’s registers and other special variables. 

General Purpose Registers 

eax, ax, al, ah, ebx, bx, bl, bh, ecx, cx, cl, ch, edx, dx, dl, dh 


Index Registers 

esi, si, edi, di 

Base Registers esp, sp, ebp, bp 

Instruction Pointer 

eip, ip 

Segmentation Registers 

cs, ds, es,fs, gs, ss 


Flags Registers 

fl, fl.o, fl.d, fl.i, fl.s, fl.z, fl.a, fl.p, fl.c, efl, efl.o, efl.d, efl.i, efl.s, efl.z, efl.a, efl.p, efl.c 
8087 Registers stO, stl, st2, st3, st4, st5, st6, st7 

8087 Control Word 

cw, cw.ic, cw.rc, cw.pc, cw.iem, cw.pm, cw.um, cw.om, cw.zm, cw.dm, cw.im 

8087 Status Word 

sw, sw.b, sw.c3, sw.st, sw.c2, sw.cl, sw.cO, sw.es, sw.sf, sw.pe, sw.ue, sw.oe, sw.ze, sw.de, 
sw. ie 

Miscellaneous Variables 

dbg$32, dbg$bottom, dbg$bp, dbg$code, dbg$cpu, dbg$ctid, dbg$data, dbg$etid, dbg$fpu, 
dbg$ip, dbg$left, dbg$monitor, dbg$ntid, dbg$os, dbg$pid, dbg$psp, dbg$radix, 
dbg$remote, dbg$right, dbg$sp, dbg$top, dbg$nil, dbg$src, dbg$loaded 

The debugger permits the manipulation of register contents and special debugger variables (e.g., dbg$32) 
using any of the operators described in this chapter. By default, these predefined names are accessed just 
like any other variables defined by the user or the application. Should the situation ever arise where the 
application defines a variable whose name conflicts with that of one of these debugger variables, the 
module specifier _ dbg may be used to resolve the ambiguity. For example, if the application defines a 
variable called cs then _ dbg@cs can be specified to resolve the ambiguity. The "_dbg@" prefix indicates 
that we are referring to a debugger defined symbol rather than an application defined symbol. See 
"Predefined Symbols" on page 167. 

13.3.6 Register Aggregates 

There are times when a value may be stored in more than one register. For example, a 32-bit "long" integer 
value may be stored in the register pair DX:AX. We require a mechanism for grouping registers to 
represent a single quantity for use in expressions. 
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We define the term "register aggregate" as any grouping of registers to form a single unit. An aggregate is 
specified by placing register names in brackets in order from most significant to least significant. Any 
aggregate may be specified as long as it forms an 8, 16, 32 or 64-bit quantity. The following are examples 
of some of the many aggregates that can be formed. 


Example: 

8-bit 

16-bit 

16-bit 

16-bit 

32-bit 

32-bit 

32-bit 

32-bit 

64-bit 

64-bit 


[al] 



[ah 

al] 


[bl 

ah] 


[ax] 



[dx 

ax] 


[dh 

dl 

ax 

[dh 

dl 

ah 

[ds 

di] 


[ax 

bx 

cx 

[edx eax] 


al] 

dx] 


(386/486/Pentium only) 


In some cases, the specified aggregate may be equivalent to a register. For example, the aggregates "[ah 
al]" and "[ax]" are equivalent to "ax". 


The default type for 8-bit, 16-bit, and 32-bit aggregates is integer. The default type for 64-bit aggregates is 
double-precision floating-point. To force the debugger into treating a 32-bit aggregate as single-precision 
floating-point, the type coercion operator "[float]" may be used. 


13.4 Operators for the C Grammar 

The debugger supports most C operators and includes an additional set of operators for convenience. The 
Open Watcom C Language Reference manual describes many of these operators. 

The syntax for debugger expressions is similar to that of the C programming language. Operators are 
presented in order of precedence, from lowest to highest. Operators on the same line have the same 
priority. 
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Lowest Priority 

Assignment Operators 

= += -= *= /= %= &= |= A = <<= »= 

Logical Operators 

&& 

Bit Operators 

A 

& 

Relational Operators 

<<=<>= 

Shift Operators 
<< » 

Arithmetic Operators 
+ 

* / % 

Unary Operators 

+ — ~ ! ++ — & * % 
sizeof unary_ expr 
sizeof (type_ name) 

(type_ name) unary_ expr 
[type_ name] unary_ expr 
? 

Binary Address Operator 


Highest Priority 


Parentheses can be used to order the evaluation of an expression. 

In addition to the operators listed above, a number of primary expression operators are supported. These 

operators are used in identifying the object to be operated upon. 

[] subscripting, substringing 

() function call 

field selection 

-> field selection using a pointer 

The following sections describe the operators presented above. 

13.4.1 Assignment Operators for the C Grammar 

= Assignment: The value on the right is assigned to the object on the left. 

+= Additive assignment: The value of the object on the left is augmented by the value on the 

right. 

-= Subtractive assignment: The value of the object on the left is reduced by the value on the 

right. 
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*= Multiplicative assignment: The value of the object on the left is multiplied by the value on 

the right. 

/= Division assignment: The value of the object on the left is divided by the value on the 

right. 

%= Modulus assignment: The object on the left is updated with MOD(left,right). The result is 

the remainder when the value of the object on the left is divided by the value on the right. 

&= Bit-wise AND: The bits in the object on the left are ANDed with the bits of the value on 

the right. 

1= Bit-wise inclusive OR: The bits in the object on the left are ORed with the bits of the value 

on the right. 

A = Bit-wise exclusive OR: The bits in the object on the left are exclusively ORed with the bits 

of the value on the right. 

«= Left shift: The bits in the object on the left are shifted to the left by the amount of the value 

on the right. 

»= Right shift: The bits in the object on the left are shifted to the right by the amount of the 

value on the right. If the object on the left is described as unsigned, the vacated high-order 
bits are zeroed. If the object on the left is described as signed, the sign bit is propagated 
through the vacated high-order bits. The debugger treats registers as unsigned items. 

13.4.2 Logical Operators for the C Grammar 

&& Logical conjunction: The logical AND of the value on the left and the value on the right is 

produced. If either of the values on the left or right is equal to 0 then the result is 0; 
otherwise the result is 1. 

II Logical inclusive disjunction: The logical OR of the value on the left and the value on the 

right is produced. If either of the values on the left or right is not equal to 0 then the result 
is 1; otherwise the result is 0. If the value on the left is not equal to 0 then the expression 
on the right is not evaluated (this is known as short-circuit expression evaluation). 

13.4.3 Bit Operators for the C Grammar 

& Bit-wise AND: The bits of the value on the left and the value on the right are ANDed. 

I Bit-wise OR: The bits of the value on the left and the value on the right are ORed. 

A Bit-wise exclusive OR: The bits of the value on the left and the value on the right are 

exclusively ORed. 
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13.4.4 Relational Operators for the C Grammar 

== Equal: If the value on the left is equal to the value on the right then the result is 1; 

otherwise the result is 0. 

!= Not equal: If the value on the left is not equal to the value on the right then the result is 1; 

otherwise the result is 0. 

< Less than: If the value on the left is less than the value on the right then the result is 1; 

otherwise the result is 0. 

<= Less than or equal: If the value on the left is less than or equal to the value on the right 

then the result is 1; otherwise the result is 0. 

> Greater than: If the value on the left is greater than the value on the right then the result is 

1; otherwise the result is 0. 

>= Greater than or equal: If the value on the left is greater than or equal to the value on the 

right then the result is 1; otherwise the result is 0. 

13.4.5 Arithmetic/Logical Shift Operators for the C Grammar 

« Left shift: The bits of the value on the left are shifted to the left by the amount described 

by the value on the right. 

» Right shift: The bits of the value on the left are shifted to the right by the amount described 

by the value on the right. If the object on the left is described as unsigned, the vacated 
high-order bits are zeroed. If the object on the left is described as signed, the sign bit is 
propagated through the vacated high-order bits. The debugger treats registers as unsigned 
items. 

13.4.6 Binary Arithmetic Operators for the C Grammar 

+ Addition: The value on the right is added to the value on the left. 

_ Subtraction: The value on the right is subtracted from the value on the left. 

* Multiplication: The value on the left is multiplied by the value on the right. 

/ Division: The value on the left is divided by the value on the right. 

% Modulus: The modulus of the value on the left with respect to the value on the right is 

produced. The result is the remainder when the value on the left is divided by the value on 
the right. 
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13.4.7 Unary Arithmetic Operators for the C Grammar 

+ Plus: The result is the value on the right. 

_ Minus: The result is the negation of the value on the right. 

~ Bit-wise complement: The result is the bit-wise complement of the value on the right. 

/ Logical complement: If the value on the right is equal to 0 then the result is 1; otherwise it 

is 0. 

++ Increment: Both prefix and postfix operators are supported. If the object is on the right, it 

is pre-incremented by 1 (e.g., ++x). If the object is on the left, it is post-incremented by 1 
(e.g., x++). 

_ Decrement: Both prefix and postfix operators are supported. If the object is on the right, it 

is pre-decremented by 1 (e.g., —x). If the object is on the left, it is post-decremented by 1 
(e.g., x ). 

& Address of: The result is the address (segment:offset) of the object on the right (e.g., 

&main). 

* Points: The result is the value stored at the location addressed by the value on the right 

(e.g., *(ds:100), *string.loc). In the absence of typing information, a near pointer is 
produced. If the operand does not have a segment specified, the default data segment 
(DGROUP) is assumed. 

(SS:00FE) = FFFF 
var: (SS:0100) = 0152 

(SS:0102) = 1240 
(SS:0104) = EEEE 

% Value at address: The result is the value stored at the location addressed by the value on 

the right (e.g., %(ds: 100), %string.loc). In the absence of typing information, a far pointer 
is produced. If the operand does not have a segment specified, the default data segment 
(DGROUP) is assumed. 

(SS:00FE) = FFFF 
var: (SS:0100) = 0152 

(SS:0102) = 1240 
(SS:0104) = EEEE 


Note that this operator is not found in the C or C++ programming languages. 


13.4.8 Special Unary Operators for the C Grammar 

sizeof unary _expression 

Example: 

sizeof tyme 
sizeof (*tyme) 


sizeof(type_name ) 
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Example: 

sizeof( struct tm ) 

(type_ttame) unary jexpression The type conversion operator (type_name) is used to convert an item from 
one type to another. The following describes the syntax of "type_name". 

type_name ::= type_spec {[ "near” I "far" I "huge"] 
type_spec ::= typedef_name 

I "struct" structure Jag 
I "union" union Jag 
I "enum" enumjag 
I scalar Jype { scalar Jype } 
scalarJype ::= "char" I "int" I "float" I "double" 

I "short" I "long" I "signed" I "unsigned" 

Example: 

(float) 4 
(int) 3.1415926 

[type jiame] unary jexpression You can force the debugger to treat a memory reference as a particular type 
of value by using a type coercion operator. A type specification is placed inside brackets as 
shown above. The basic types are char (character, 8 bits), short (short integer, 16 bits), 
long (long integer, 32 bits), float (single-precision floating-point, 32 bits), and double 
(double-precision floating-point, 64 bits). Unless qualified by the short or long keyword, 
the int type will be 16 bits in 16-bit applications and 32 bits in 32-bit applications (386, 486 
and Pentium systems). The character, short integer and long integer types may be treated 
as signed or unsigned items. The default for the character type is unsigned. The default 
for the integer types is signed. 

Example: 


[char] 

(default 

unsigned) 

[signed char] 




[unsigned char] 




[int] 

(default 

is 

signed) 

[short] 

(default 

is 

signed) 

[short int] 

(default 

is 

signed) 

[signed short int] 




[long] 

(default 

is 

signed) 

[long int] 

(default 

is 

signed) 


[signed long] 

[unsigned long int] 

[float] 

[double] 

Note that it is unnecessary to specify the int keyword when short or long are specified. 

Existence test: The "?" unary operator may be used to test for the existence of a symbol. 

Example: 

?id 


The result of this expression is 1 if "id" is a symbol known to the debugger and 0 otherwise. 
If the symbol does not exist in the current scope then it must be qualified with its module 
name. Automatic symbols exist only in the current function. 
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13.4.9 Binary Address Operator for the C Grammar 

: Memory locations can be referenced by using the binary operator and a combination of 

constants, register names, and symbol names. In the Intel 80x86 architecture, a memory 
reference requires a segment and offset specification. A memory reference using the 
operator takes the following form: 

segmenUoffset 

The elements segment and offset can be expressions. 

Example: 

(ES) : (DI + 100) 

(SS) : (SP-20) 

13.4.10 Primary Expression Operators for the C Grammar 

[] Elements of an array can be identified using subscript expressions. Consider the following 

3-dimensional array defined in the "C" language. 

Example: 

char *ProcessorType[2][4][2] = 

{ { { "Intel 8086", "Intel 8088" }, 

{ "Intel 80186", "Intel 80188" }, 

{ "Intel 80286", "unknown" }, 

{ "Intel 80386", "unknown" } }, 

{ { "NEC V30", "NEC V20" }, 

{ "unknown", "unknown" }, 

{ "unknown", "unknown" }, 

{ "unknown", "unknown" } } }; 

This array can be viewed as two layers of rectangular matrices of 4 rows by 2 columns. 
The array elements are all pointers to string values. 

By using a subscript expression, specific slices of an array can be displayed. To see only 
the values of the first layer, the following expression can be issued. 

Example: 

processortype[0] 

To see only the first row of the first layer, the following expression can be issued. 
Example: 

processortype[0][0] 

To see the second row of the first layer, the following command can be issued. 

Example: 

processortype[0][1] 

To see the value of a specific entry in a matrix, all the indices can be specified. 
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o 


-> 


Example: 

processortype[0][0][0] 
processortype[0][0][1] 
processortype[0] [1] [0] 

The function call operators appear to the right of a symbol name and identify a function call 
in an expression. The parentheses can contain arguments. 

Example: 

ClearScreen() 

PosCursor( 10, 20 ) 

Line( 15, 1, 30, ) 

The "." operator indicates field selection in a structure. In the following example, tyme2 
is a structure and tm_ year is a field in the structure. 

Example: 

tyme2 ,tm_ year 

The operator indicates field selection when using a pointer to a structure. In the 
following example, tyme is the pointer and tm_ year is a field in the structure to which it 
points. 

Example: 

tyme->tm_ year 


13.5 Operators for the C++ Grammar 

Debugger support for the C++ grammar includes all of the C operators described in the previous section 
entitled "Operators for the C Grammar" on page 127. In addition to this, the debugger supports a variety of 
C++ operators which are described in the C+ + Programming Language manual. 

Perhaps the best way to illustrate the additional capabilities of the debugger’s support for the C++ grammar 
is by way of an example. The following C++ program encompasses the features of C++ that we will use in 
our debugging example. 

Example: 

// DBG_EXAM.C: C++ debugging example program 

struct BASE { 
int a; 

BASE() : a(0) {} 

-BASE(){} 

BASE & operator =( BASE const &s ) 

{ 

a = s . a; 
return *this; 

} 

virtual void foo() 

{ 

a = 1; 

} 

} ; 
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struct DERIVED : BASE { 
int b; 

DERIVED() : b(0) {} 

-DERIVED() {} 

DERIVED & operator =( DERIVED const &s ) 

{ 

a = s . a; 
b = s.b; 
return *this; 

} 

virtual void foo() 

{ 

a = 2; 
b = 3; 

} 

virtual void foo( int ) 

{ 

} 

} ; 

void use( BASE *p ) 

{ 

p->foo(); 

} 

void main() 

{ 

DERIVED x; 

DERIVED y; 

use ( &x ); 
y = x; 

} 

Compile and link this program so that the most comprehensive debugging information is included in the 
executable file. 

13.5.1 Ambiguity Resolution in the C++ Grammar 

Continuing with the example of the previous section, we can step into the call to use and up to the 
p->foo () function call. Try to set a breakpoint at foo. 

You will be presented with a window containing a list of "foo" functions to choose from since the reference 
to foo at this point is ambiguous. Select the one in which you are interested. 

You may also have observed that, in this instance, p is really a pointer to the variable x which is a 
DERIVED type. To display all the fields of x, you can type cast it as follows. 

Example: 

* (DERIVED *)p 
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13.5.2 The "this" Operator for the C++ Grammar 

Continuing with the example of the previous sections, we can step into the call to f->foo () and up to the 
b=3 statement. You can use the "this" operator as illustrated in the following example. 

Example: 

this->a 

*this 

13.5.3 "operator" Functions in the C++ Grammar 

Continuing with the example of the previous sections, we can set breakpoints at C++ operators using 
expressions similar to the following: 

Example: 

operator = 

DERIVED & operator =( DERIVED const &s ) 

{ 

a = s . a; 
b = s.b; 
return *this; 

} 

13.5.4 Scope Operatorfor the C++ Grammar 

We can use the scope operator to identify what it is that we wish to examine. Continuing with the 
example of the previous sections, we can enter an address like: 

base::foo 

In some cases, this also helps to resolve any ambiguity. The example above permits us to set a breakpoint 
at the source code for the function f oo in the class BASE . 

virtual void foo() 

{ 

a = 1; 

} 

Here are some more interesting examples: 

derived::foo 
derived::operator = 

The first of these two examples contains an ambiguous reference so a prompt window is displayed to 
resolve the ambiguity. 
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13.5.5 Constructor/Destructor Functions in the C++ Grammar 

We can also examine the constructor/destructor functions of an object or class. Continuing with the 
example of the previous sections, we can enter expressions like: 

Example: 

base::base 
base::-base 

The examples above permit us to reference the source code for the constructor and destructor functions in 
the class BASE. 


13.6 Operators for the FORTRAN Grammar 

The debugger supports most FORTRAN 77 operators and includes an additional set of operators for 
convenience. The additional operators are patterned after those available in the C programming language. 

The grammar that the debugger supports is close to that of the FORTRAN 77 language but there are a few 
instances where space characters must be used to clear up any ambiguities. For example, the expression 

1. eq. x 

will result in an error since the debugger will form a floating-point constant from the "1." leaving the string 
"eq.x". If we introduce a space character after the "1" then we clear up the ambiguity. 

1 .eq.x 

Unlike FORTRAN, the parser in the debugger treats spaces as significant characters. Thus spaces must not 
be introduced in the middle of symbol names, constants, multi-character operators like .EQ. or //, etc. 

Operators are presented in order of precedence, from lowest to highest. Operators on the same line have 
the same priority. 
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Lowest Priority 

Assignment Operators 

= += -= *= /= %= &= |= A = <<= »= 

Logical Operators 
.EQV. .NEQV. 

.OR. 

.AND. 

.NOT. 

Bit Operators 

A 

& 

Relational Operators 

.EQ. .NE. .LT. .LE. .GT. .GE. 

Shift and Concatenation Operators 

« » // 

Arithmetic Operators 
+ 

* / % 

** (unsupported) 

Unary Operators 
+ 

~ ++ — & * % 

[type_ name] unary_ expr 
? 

Binary Address Operator 


Highest Priority 


Parentheses can be used to order the evaluation of an expression. 

In addition to the operators listed above, a number of primary expression operators are supported. These 
operators are used in identifying the object to be operated upon. 

() subscripting, substringing, or function call 

field selection 

-> field selection using a pointer 


The following built-in functions may be used to convert the specified argument to a particular type. 


INT ( ) 
REAL( ) 
DBLE ( ) 
CMPLX( ) 
DCMPLX( ) 


conversion to integer 
conversion to real 
conversion to double-precision 
conversion to complex 

conversion to double-precision complex 


The following sections describe the operators presented above. 
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13.6.1 Assignment Operators for the FORTRAN Grammar 

= Assignment: The value on the right is assigned to the object on the left. 

+= Additive assignment: The object on the left is augmented by the value on the right. 

-= Subtractive assignment: The object on the left is reduced by the value on the right. 

*= Multiplicative assignment: The object on the left is multiplied by the value on the right. 

/= Division assignment: The object on the left is divided by the value on the right. 

%= Modulus assignment: The object on the left is updated with MOD(left,right). The result is 

the remainder when the value of the object on the left is divided by the value on the right. 

&= Bit-wise AND: The bits in the object on the left are ANDed with the bits of the value on 

the right. 

1= Bit-wise inclusive OR: The bits in the object on the left are ORed with the bits of the value 

on the right. 

A = Bit-wise exclusive OR: The bits in the object on the left are exclusively ORed with the bits 

of the value on the right. 

«= Left shift: The bits in the object on the left are shifted to the left by the amount of the value 

on the right. 

»= Right shift: The bits in the object on the left are shifted to the right by the amount of the 

value on the right. If the object on the left is described as unsigned, the vacated high-order 
bits are zeroed. If the object on the left is described as signed, the sign bit is propagated 
through the vacated high-order bits. The debugger treats registers as unsigned items. 

13.6.2 Logical Operators for the FORTRAN Grammar 

.EQV. Logical equivalence: The logical equivalence of the value on the left and the value on the 

right is produced. 

.NEQV. Logical non-equivalence: The logical non-equivalence of the value on the left and the 

value on the right is produced. 

.OR. Logical inclusive disjunction: The logical OR of the value on the left and the value on the 

right is produced. 

.AND. Logical conjunction: The logical AND of the value on the left and the value on the right is 

produced. 

.NOT. Logical negation: The logical complement of the value on the right is produced. 
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13.6.3 Bit Operators for the FORTRAN Grammar 

I Bit-wise OR: The bits of the value on the left and the value on the right are ORed. 

A Bit-wise exclusive OR: The bits of the value on the left and the value on the right are 

exclusively ORed. 

& Bit-wise AND: The bits of the value on the left and the value on the right are ANDed. 

13.6.4 Relational Operators for the FORTRAN Grammar 

.EQ. Equal: If the value on the left is equal to the value on the right then the result is 1; 

otherwise the result is 0. 

.NE. Not equal: If the value on the left is not equal to the value on the right then the result is 1; 

otherwise the result is 0. 

.LT. Less than: If the value on the left is less than the value on the right then the result is 1; 

otherwise the result is 0. 

.LE. Less than or equal: If the value on the left is less than or equal to the value on the right 

then the result is 1; otherwise the result is 0. 

.GT. Greater than: If the value on the left is greater than the value on the right then the result is 

1; otherwise the result is 0. 

. GE. Greater than or equal: If the value on the left is greater than or equal to the value on the 

right then the result is 1; otherwise the result is 0. 

13.6.5 Arithmetic/Logical Shift Operators for the FORTRAN Grammar 

« Left shift: The bits of the value on the left are shifted to the left by the amount described 

by the value on the right. 

» Right shift: The bits of the value on the left are shifted to the right by the amount described 

by the value on the right. If the object on the left is described as unsigned, the vacated 
high-order bits are zeroed. If the object on the left is described as signed, the sign bit is 
propagated through the vacated high-order bits. The debugger treats registers as unsigned 
items. 

13.6.6 Concatenation Operator for the FORTRAN Grammar 

// String concatenation: The concatenation of the character string value on the left and right 

is formed. 
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13.6.7 Binary Arithmetic Operators for the FORTRAN Grammar 

+ Addition: The value on the right is added to the value on the left. 

_ Subtraction: The value on the right is subtracted from the value on the left. 

* Multiplication: The value on the left is multiplied by the value on the right. 

/ Division: The value on the left is divided by the value on the right. 

% Modulus: The modulus of the value on the left with respect to the value on the right is 

produced. The result is the remainder when the value on the left is divided by the value on 
the right. 

** Exponentiation: This operation is not supported by the debugger. 


13.6.8 Unary Arithmetic Operators for the FORTRAN Grammar 

+ Plus: The result is the value on the right. 

_ Minus: The result is the negation of the value on the right. 

~ Bit-wise complement: The result is the bit-wise complement of the value on the right. 

++ Increment: Both prefix and postfix operators are supported. If the object is on the right, it 

is pre-incremented by 1 (e.g., ++x). If the object is on the left, it is post-incremented by 1 
(e.g., x++). 

_ Decrement: Both prefix and postfix operators are supported. If the object is on the right, it 

is pre-decremented by 1 (e.g., —x). If the object is on the left, it is post-decremented by 1 
(e.g., x—), 

& Address of: The result is the address (segment:offset) of the object on the right (e.g., 

&main). 

* Points: The result is the value stored at the location addressed by the value on the right 

(e.g., *(ds:100), *string.loc). In the absence of typing information, the value on the right is 
treated as a pointer into the default data segment (DGROUP) and a near pointer is 
produced. 

(SS:OOFE) = FFFF 
var: (SS:0100) = 0152 

(SS:0102) = 1240 
(SS:0104) = EEEE 

% Value at address: The result is the value stored at the location addressed by the value on 

the right (e.g., %(ds:100), %string.loc). In the absence of typing information, the value on 
the right is treated as a pointer into the default data segment (DGROUP) and a far pointer is 


produced. 




(SS:OOFE) 

= FFFF 

var: 

(SS:0100) 

= 0152 


(SS:0102) 

= 1240 


(SS:0104) 

= EEEE 
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Note that this operator is not found in the FORTRAN 77 programming language. 

13.6.9 Special Unary Operators for the FORTRAN Grammar 

? Existence test: The "?" unary operator may be used to test for the existence of a symbol. 


?id 


The result of this expression is 1 if "id" is a symbol known to the debugger and 0 otherwise. 
If the symbol does not exist in the current scope then it must be qualified with its module 
name. Automatic symbols exist only in the current subprogram. 

13.6.10 Binary Address Operator for the FORTRAN Grammar 

: Memory locations can be referenced by using the binary operator and a combination of 

constants, register names, and symbol names. In the Intel 80x86 architecture, a memory 
reference requires a segment and offset specification. A memory reference using the 
operator takes the following form: 

segmenUoffset 

The elements segment and offset can be expressions. 

Example: 

(ES) : (DI + 100) 

(SS) : (SP-20) 

13.6.11 Primary Expression Operators for the FORTRAN Grammar 

() Elements of an array can be identified using subscript expressions. 

The "." operator indicates field selection in a structure. This operator is useful in mixed 
language applications where part of the application is written in the C or C++ programming 
language. In the following example, tyme2 is a structure and tm_ year is a field in the 
structure. 

tyme2 ,tm_ year 

-> The operator indicates field selection when using a pointer to a structure. This 

operator is useful in mixed language applications where part of the application is written in 
the C or C++ programming language. In the following example, tyme is the pointer and 
tm_ year is a field in the structure to which it points. 

tyme->tm_ year 
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A. Debugger Commands 


This section describes the syntax of debugger commands as well as a description of each of the debugger 
commands. 


A.1 Syntax Definitions 

A debugger command may contain any of the following syntax elements: 

• A word in angle brackets, like <anything> is a defined term. Its definition will appear after the 
syntax description of the command. 

• [x] indicates that "x" is an optional item. It may or may not be included in the command. 

• [xlylz] indicates that on of x, y or z should be included in the command. 

• [x [x [...]]] indicates that x may be repeated zero or more times in the command. 

• CApital indicates that ca,cap,capi,... are accepted short forms for the command "capital". 

• (GUI only) indicates that this command is only available in a GUI debugger. 

• (character-based) indicates that this command is only available in a character mode debugger. 

• <expr> indicates an expression. These may include any of the variables, etc in the program being 
debugged, and are evaluated in the current program context. See "Open Watcom Debugger 
Expression Handling" on page 119. 

• <integer> is an integer constant 

• <intexpr> is an an expression which evaluates to an integral value. See "Open Watcom Debugger 
Expression Handling" on page 119. 

• <command> is any debugger command or group of debugger commands. 

You can group debugger commands with braces and separate them with semi-colons. The resulting 
compound command may be considered as an atomic command. 

{<command>;<command>;<command>} 


• <address> is any expression which evaluates to an address. See "Open Watcom Debugger 
Expression Handling" on page 119. 

• <string> is a string of text, optionally enclosed in braces. For example, 

this_ is_ a_ string 
{so is this} 
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• <wndname> is the name of a window. Valid window names (with acceptable short forms indicated 
in capitals) are: 

• ASsembly 

• AL1 

• BReak 

• Calls 

• W atch 
•File 

• FPu 

• Functions 

• FILES cope 

• LOCals 
•LOG 

• MEmory 

• MOdules 

• Register 

• SOurce 

• STack 

• Thread 
•IO 

• Globals 

• Variable 

• Binary 

• IMage 

• GLobalfunctions 

• Accelerators 

• TMPFile 

• REPlay 

• CUrrent 

• <file> represents any valid operating system file name. For example, 

c: \autoexec.bat 

• <path> represents any valid operating system directory path. For example, 

c:\dirl\dir2 


A.2 Command Summary 

A summary of each command follows. 

A.2.1 Accelerate 

This command behaves as if a menu item from the main menu was selected: 

Accelerate main <menu> {<menu_ string>} 

This command behaves as if the named menu item in the floating pop-up menu for the current window was 
selected: 

Accelerate {<menu_ string>} 
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<menu> the string appearing on the main menu bar (File, Run, Break, Code, etc) 

<menu_string> 

is enough of the text appearing in a menu to uniquely identify it. 

For example: 

accelerate main run {until return} 

behaves as if "Until return" is selected from the run menu 

accelerate {Home} 

behaves as if "home" were picked from the floating pop-up menu of the current window. 

A.2.2 Break 

This command prints a list of all breakpoints into the log window: 

Break 

This command sets a break point. See the section entitled "Breakpoints" on page 71 for details about 
breakpoint operation. 

Break [|/Set|/Byte|/Word|/DWord|/Modify] 

<address> [ {<do_ command>} [ { <condition> } [ <countdown> ]]] 

This command deactivates a breakpoint: 

Break/Deactivate <brkid> 

This command enables a breakpoint: 

Break/Activate <brkid> 

This command clears a breakpoint: 

Break/Clear <brkid> 

This command toggles a breakpoint through the active/inactive/deleted states: 

Break/Toggle <brkid> 

This command turns on the resume option in the breakpoint: 

Break/Resume <brkid> 

This command turns off the resume option in the breakpoint: 

Break/UnResume <brkid> 

This command turns on/off the breakpoint for appropriate image!DLL) load: 

Break/Image [/Clear] <image(DLL) name> 

The Break options are: 
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/Set (default) 

/Byte 

/Word 

/DWord 

/Modify 

<condition> 

<countdown> 


the breakpoint triggers when <address> is executed 

the breakpoint triggers when the byte at <address> is modified 

the breakpoint triggers when the word at <address> is modified 

the breakpoint triggers when the double word at <address> is modified 

the breakpoint triggers when integer at <address> is modified 

an expression that must be true (non-zero value) before the breakpoint stops program 
execution 

an integer. The breakpoint will not stop program execution until <countdown> is 
decremented to zero. 


Note: If you specify both <condition> and <countdown>, <countdown> 

decrements only when <condition> evaluates to true. 


<do_command> 

a command that is executed each time the breakpoint stops program execution 
<brkid> option can be three possible values: 


<address> Perform the operation on breakpoint with the given address. 

* Perform the operation on all breakpoints. 

#<integer> Names a breakpoint by its index. This index can be discovered on the title 
line of the Breakpoint dialog. 


Some examples of the break command and a description follow: 


This command sets a breakpoint at "foo" the 20th time that i equals 10. When this occurs ’do j7’ is 
executed: 

Break /Set foo {do j7] {i10} 20 


This command clears the breakpoint at foo: 

Break /Clear foo 


This command activates breakpoint #1: 

Break /Activate #1 


This command deactivates all breakpoints: 

Break /Deactivate * 


A.2.3 Call 

Use the Call command to call a routine. The Call command options are: 

Call [/Far|/Interrupt|/Near] 

<address> 

[([<parm>[,<parm>[...]]])] [/|<printlist>] 

This command calls the routine at <address> with parameters. 
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/Far 

Use a far call instruction. 

/Near 

Use a near call instruction. 

/Interrupt 

Call the routine as if it were an interrupt handler. 

<parm> 

is [/<location>] <expr> 

<location> 

is [/l<regset>] 


/ means to put the parm on the stack. 

/<regset> means to put the parm into the named registers. 

<regset> is a register aggregate. See "Open Watcom Debugger Expression Handling" on 
page 119. 

<printlist> See the print command for details. 

Some examples of the Call command follow: This command calls the function foo: 
call foo 

This command calls the function bar passing the parameters 1, 2, and 3: 
call bar( 1,2,3 ) 

This command calls foo putting 1 on the stack, 2 in AX and 3 in CX:BX printing out the value of AX and 
DX in decimal and hexadecimal respectively on return: 

call /near foo( // 1, /ax 2, /[cx bx] 3 ) {%d %x} ax,dx 

The Call command only uses very basic symbolic information - it’s designed that way so that it can work 
even when no symbolic information is available. This has a number of implications. The first is that the 
debugger pays no attention to any information on where parameters are stored. For example, in 32-bit 
applications, unless explictly instructed otherwise, the first parm is placed in EAX, the second in EDX, and 
so on (as defined by the "set call" command). That means that you have to do something like: 

call foo( // &a, // 3 ) 

to get things on to the stack. This leads to a second, very important consideration. 

The debugger has no idea of the memory model that the program is compiled in (recall that the 32-bit 
compiler does support large memory models and far pointers, even if we don't supply versions of the 
libraries for it). That means that the debugger has no idea on whether the address of a symbol should be far 
or near. It always assumes far, since that never loses information. A far pointer would be truncated to a 
near pointer when moved into a 32-bit register like EAX but not so when pushed onto the stack. In this 
case, / / &a and / / 3 cause 48-bit far pointers to be pushed onto the stack (they are actually pushed as 64 
bits for alignment reasons). Thus the pointer to b is in the wrong place for the routine to access it 
(assuming it is expecting near pointers) and this will likely cause a task exception. To avoid this problem 
and properly pass arguments to the routine, you need to do the following: 

call foo( // (void near *)&a, // (void near *)3 ) 

This forces the debugger to push near pointers onto the stack. 
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Similar considerations apply for the 16-bit case. 

A.2.4 CAPture 

Use the Capture command to execute a command and put the resulting program output into a window. The 
format of the command follows: 

CAPture <command> 


For example, this command calls a routine, foo, and puts its output into a debugger window. 

capture call foo 


A.2.5 COnfigfile 

COnfigfile 


Used by the debugger to save and restore the configuration. When "configfile" appears in a command file, 
it identifies that file as the default configuration file. The debugger will overwrite the command file when 
autosaving the current configuration. Also, the name of this file is displayed in the filename field when the 
"Save Setup" dialog initially appears. 

If more than one file is encountered containing the "configfile" command, the last one seen is used to 
establish the configuration file name. 

A.2.6 Display 

The display command allows you to open any window. The general Display command is: 

Display <wndname> [/Open|/Close|/New|/Minimize|/MAximize|/Restore] 

[<ord>,<ord>,<ord>,<ord>] 


This command causes the debugger screen to repaint: 

Display 

This command displays the toolbar as either fixed (default) or floating: 

Display Toolbar [/Open] [/FLoating/Fixed] [<ord>] 

This command closes the toolbar: 

Display Toolbar [/Close] 

This command opens the status line: 

Display Status [/Open] 

This command closes the status line: 

Display Status /Close 

This command brings a window to the front: 

Display <wndname> 
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The options for the Display command follow: 

<ord> The height to be used for toolbar buttons. 

<ord>, <ord>, <ord>, <ord> 

These are the x and y coordinates of the top left corner, and the width and the height of the 
window respectively. 0,0,10000,10000 is a window covering the entire screen. 

/Open Open a new window or resize an existing one. 

/New Open a new window regardless of an existing one. 

/Close Close the window. 

/Minimize Iconize the window. 

/MAximize Make the window full screen size. 

/REstore Restore a window from a minimize or maximize. 

Some examples of the display command follow: This command opens a register window in the top left 
quarter of the screen: 

display register /open 0,0,5000,5000 

This command minimizes the source window if it is open: 

display source /minimize 

A.2.7 DO (or/) 

Use the DO command to evaluate an arbitrary C/C++ or FORTRAN expression. The format of the 
command is: 

DO <expr> 

For example: 

DO i = 10 

A.2.8 ERror 

Use the Error command to display a string as an error message. The format of the command is: 

ERror <string> 

For example: 

error {An error has been detected} 
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A.2.9 Examine 

Use the Examine command to examine memory at a specific address. 

Examine [/<type>] [<address>] [,<follow> [,<len>]] 

where "<type>" is one of 

Byte 

Word 

Dword 

Qword 

Char 

Short 

Long 

_ int64 

Unsigned_ Char 
Unsigned_ Short 
Unsigned_ Long 

Unsigned_int64 

0 :16_ Pointer 
16:16_ Pointer 
0:32_ Pointer 
16:32_ Pointer 
Float 
Double 

Extended_ Float 


To show an assembly window at a specific address: 

Examine /Assembly [<address>] 

To show a source window at a specific address 

Examine /Source [<address>] 

To add an address to the I/O window as a byte, word, or dword: 

Examine [/IOByte|/IOWord|/IODword] [<address>] 

The options for the Examine command follow: 

/<type> where "<type>" is one of Byte, Word, Dword, Qword, Char, Short, Long, 

_int 64 JJnsigned_ Char, Unsigned_ Short, Unsigned_ Long, 

Unsigned_int64Q : 16_ Pointer, 16 :16_ Pointer, 0 : 32_ Pointer, 

16 : 32_ Pointer, Float, Double, or Extended_ Float . Set the initial display 
type of the memory window. 

/IOByte /IOWord /IODword 

Set the initial display type of the line in the I/O window. 

<address> the address to examine. 

<follow> an expression which will be used if the memory window’s Repeat function is chosen. 

<len> an integer expression indicating the length of memory to examine. 

For example, this command opens a memory window positioned at the address of "foo". The initial display 

type will be 2 byte words. If the Repeat menu item is used, it will follow a near pointer 4 bytes past the 

beginning of the window *(.+$). The window will display 16 bytes of data at a time: 
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examine /word foo,*(.+4),16 

A.2.10 Flip 

Use the Flip command to configure screen flipping. See the section entitled "The Options Dialog" on page 
32 for details 

Flip ON 
Flip OFf 

A.2.11 FOnt 

Use the Font command to set the font for the specified window. The command is: 

FOnt <wndname> <fontinfo> 

<wndname> the name of the affected window 
<fontinfo> operating system specific font data. 

A.2.12 Go 

Use the Go command to start or continue program execution. Execution then resumes at the specified 
address or at the location defined by the current contents of the CS:1P or CS:EIP register pair. The format 
of the Go command is: 

Go [/Until] [/Keep] [/Noflip] [[<start>,]<stop>] 

The options are: 

/Until skips breakpoints until the specified stop address is reached. 

/Keep allows you to keep a previous temporary breakpoint. If you keep the previous breakpoint 

you cannot create a new one. 

/Noflip keeps the debugger from flipping to the application’s screen. 

<start> the <address> at which to start execution (optional). 

<stop> the <address> at which to stop execution. 

Some examples of the Go command are: 

This command will resume execution until function "foo" is executed without flipping to the application 
screen: 

go /noflip foo 

This command starts execution at "foo" and runs until "bar" is executed. 

go foo,bar 
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A.2.13 Help 

Bring up the help screen: 

Help 

A.2.14 HOok 

Use the Hook command to execute a command when a defined event occurs. The format of the Hook 
command is: 

HOok <event> <command> 

<event> can be any of the following: 

PROGStart a program is loaded 
PROGEnd a program terminates 
DLLStart a DLL is loaded 

DLLEnd a DLL is unloaded 

EXECStart program execution is beginning 

EXECEnd program execution is stopped 

Sourceinfo the current location being examined has debugging information 
Assemblyinfo the current location being examined has no debugging information 
Modulechange the current location being examined has changed modules 

This example causes the locals and source window to come to the front whenever a region with symbolic 
debugging information is entered: 

hook sourceinfo {display locals; display source} 

A.2.15 IF 

Use the If command to evaluate an expression and then, depending on the results, execute a list of 
commands. The format of the If command is: 

IF <expr> { <command> } 

[ ELSEIF <expr> { <command> } [ ELSEIF <expr> { <command> } [...]]] 

[ELSE { <command> }] 

If the expression results in a non-zero value, the list of debugger commands contained after the IF 
expression are executed. Otherwise, the list of commands that appear after the ELSEIF expression are 
executed. 
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A.2.16 INvoke(or<) 

Use the Invoke command to invoke a file containing a number of debugger commands. The format of the 
Invoke command is: 

INvoke <file> [<string> [<string> [...]]] 

< <file> [<string> [<string> [...]]] 


<file> is the name of the command file to invoke. 

<string> will be passed as a parameter. These parameters may be referenced in the command file as 

<1>, <2>, etc. 

A.2.17 Log (or >) 

Use the Log command to send the Dialog window output to a specified file. The following commands start 
logging to a file: 

Log <file> 

Log /Start <file> 

> <file> 


The following commands start appending log information to a file. 

Log > <file> 

>> <file> 

Log /Append <file> 

The following commands stop logging: 


Log 

> 


A.2.18 MOdify 

Use the Modify command to change memory at an address to the values specified by the list of expressions. 

Modify [/Byte|/Pointer|/Word|/Dword|/IOByte|/IOWord|/IODword] <address>[,<expr>[...]] 

The options for the modify command are: 

/Byte /Pointer /Word /Dword Control the size of memory to be modified. 

/IOByte /IOWord /IODword Control the size of the I/O port to be modified. 

<address> The address to modify. 

<expr> The values to be placed in memory. 

This command changes the 3 bytes at location "foo" to the values 1, 2 and 3: 
modify /byte foo 1,2,3 

This command changes the 4 bytes at location "foo" to the value 12345678 hex: 
modify /dword foo 0x12345678 
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A.2.19NEW 


Use the New command to initialize various items. The format of the New command is: 

NEW [<args>] 

NEW /Program [[:<symfile>] <progfile> [<args>]] 

NEW /Restart [<args>] 

NEW /STDIn <file> 

NEW /STDOut <file> 

NEW /SYmbol <file> [seg [,seg [...]] 


<symfile> 

<progfile> 

<args> 

/Restart 

/STDIn 

/STDOut 

/Symbol 


represents a file containing the symbolic information, 
represents the executable file. 

represent the arguments to be passed to the program. 

Reload the current application and place it into an initial state so that you may begin 
execution again. The application may have already partially or completely executed. 

associate the standard input file handle with a particular file or device. 

associate the standard output file handle with a particular file or device. 

load additional symbolic debugging information and specify the mapping between the 
linker addresses and the actual execution addresses. 


A.2.20 PAint 

Use the Paint command to define window or dialog colours. To define the colour for windows, use the 
following command: 

PAint [Status|<wndname>] <wndattr> <color> ON <color> 

To define the colour for dialogs in the character-based version of the debugger, use the following 
command: 

PAint Dialog <dlgattr> <color> ON <color> 

The paint options are as follows: 

<wndattr> allows you to define the window attributes. You can choose from the following items: 
MEnu Plain menu text (character-based) 

MEnu STandout menu accelerator key (character-based) 

MEnu Disabled grayed menu item (character-based ) 

MEnu Active menu item under the cursor (character-based) 

MEnu Active STandout menu accelerator key under the cursor (character-based) 
MEnu Frame frame of the menu (character-based) 
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MEnu Disabled Active grayed menu item under the cursor (character-based) 

Title Disabled a non active window’s title 

Frame Active the frame of the active window (character-based) 

Frame Disabled the frame an inactive window (character-based) 

ICon an icon 

Plain normal text within a window 

Active window text under the cursor 

SElected window text being selected 

STandout window text the debugger wishes to highlight 
Active STandout window text the debugger wishes to highlight under the cursor 
BUtton the gadgets on the left side of a window (character-based) 

<dlgattr> option allows you to define the dialog attributes. The possible options are: 

Plain normal text 

Frame the dialog frame 

SHadow the shadow of a button 

BUtton Plain normal button text 

BUtton STandout button accelerator key character 

BUtton Active a button which has focus 

BUtton Active STandout button accelerator key character of a button with focus 
<color> You can choose from the following colours: 

• BLAck 

•BLUe 

• GREEn 

• Cyan 

• Red 

• MAgenta 

•BROwn 


Command Summary 157 




Appendices 


• White 
•GREY 

• GRAy 

• BRIght BLUe 

• BRIght GREEn 

• BRIght Cyan 

• BRIght Red 

• BRIght MAgenta 

• Yellow 

• BRIght BROwn 

• BRIght White 

Some examples of the paint command follow: 

paint all plain black on white 

paints plain text black on white in all windows, 
paint dialog button standout bright green on yellow 


A.2.21 Print (or ?) 


Use the Print command to prompt for an expression and then print it to the log window. Use this command 
to examine the values of variables and expressions. The Print command is: 

Print [/Program] [<printlist>] 

Print /Window [<exprlist>] 


/Window 

/Program 

<printlist> 

<exprlist> 

<format> 


opens up a watch window containing the listed expressions, 
print the results to the application's screen, 
is [<format>] [<exprlist>] 
is [<expr> [,<expr> [...]]] 

is a printf like format string. It consists of plain text intermixed with control sequences, 
which will be substituted with values from the expression list. The control sequences are: 

%i The corresponding argument is printed out as a signed decimal integer 

value. 

%d The corresponding argument is printed out as a signed decimal integer 

value. 

%u The corresponding argument is printed out as an unsigned decimal integer 

value. 
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%x The corresponding argument is printed out as an unsigned hexadecimal 

integer value. Letter digits are printed in lower case (a-f). 

%X The corresponding argument is printed out as an unsigned hexadecimal 

integer value. Letter digits are printed in upper case (A-F). 

%o The corresponding argument is printed out as an unsigned octal integer 

value. 

%p The corresponding argument is printed out as a pointer (segment:offset) 

value in hexadecimal notation. 

%c The corresponding argument is printed out as a single character value. 

%s The corresponding argument is printed out as a C/C++ string value. The 

argument must point to a string of characters terminated by a byte whose 
value is zero. 

%% To print out a percentage symbol, the must be doubled up (i.e., %%). 

%/ The corresponding argument is printed out in floating-point representation. 

If the floating-point value has a very large or small magnitude, you should 
use one of "g", "G", "e" or "E" formatting. 

%g The corresponding argument is printed out in floating-point representation. 

Numbers of very large or small magnitude are printed out in scientific "E" 
notation (e.g., 1.54352e+16). The exponent letter is printed in lower case. 

%G The corresponding argument is printed out in floating-point representation. 

Numbers of very large or small magnitude are printed out in scientific "E" 
notation (e.g., 1.54352E+16). The exponent letter is printed in upper case. 

%e The corresponding argument is printed out in scientific "E" notation (e.g., 

1.23456e+02). The exponent letter is printed in lower case. 

%E The corresponding argument is printed out in scientific "E" notation (e.g., 

1.23456E+02). The exponent letter is printed in upper case. 

%r The corresponding argument is printed out in the current default numeric 

radix. 

%a The corresponding argument is printed out as a symbol reference 

(symbol_name+offset) when possible; otherwise it is printed out as a 
pointer (segment:offset) value in hexadecimal notation. 

%l The corresponding argument is printed out as a line number reference 

(module_name@line_number+offset) when possible; otherwise it is printed 
out as a pointer (segment:offset) value in hexadecimal notation. 

Some examples of the print command follow. This command prints the value of "i": 


This command prints "decimal=100 hex=0x64": 
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print {decimal=%d hex=%x} 100,100 

This command opens a watch window and displays the value of argv[0]: 

print/window argv[0] 


A.2.22 Quit 

Use the Quit command to leave the debugger. 

A.2.23 RECord 

Use the Record command to add a command to the replay window. This command is for internal use only. 
The format of the command is: 

REcord<expr> <command> 


A.2.24 Register 

The format of the Register command is: 

Register <intexpr> 


If intexpr is negative, this is equivalent to using the menu item Undo/Undo -<intexpr> times. If intexpr is 
positive, this is equivalent to using the menu item Undo/Redo <intexpr> times. 

A.2.25 REMark (or *) 

Use the Remark command to enter lines of comments. The format of the command is: 

REMark <string> 


A.2.26 Set 

These commands are used internally by the debugger to save and restore the configuration. The syntax is: 
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Set AUtosave [ON|OFf] 

Set Assembly [Lower|Upper] [Outside|Inside] [Source|NOSource] [Hexadecimal|Decimal] 
Set Variable [Entire|Partial] [CODejNOCODe] [INheritINOINherit] [COMpiler|NOCOMpiler] 
[PRIvate|NOPRIvate] [PROtected|NOPROTected] [MembersjNOMembers] 

Set Functions [Typed|All] 

Set GLobals [Typed|All] 

Set REGister [Hexadecimal|Decimal] [Extended|Normal] 

Set Fpu [Hexadecimal|Decimal] 

Set BE11 [ON|OFf] 

Set BReakonwrite [ON|OFf] 

Set Call [/Far|/Interrupt|/Near] [ ( [<location> [,<location> [...]]] ) ] 

Set Dclick <expr> 

Set Implicit [ON|OFf] 

Set INput <wndname> 

Set Radix <expr> 

Set RECursion [ON|OFf] 

Set SEarch [CASEIgnore|CASEREspect] [Rx|NORx] <string> 

Set SOurce [/Add] [<path> [<path>] [...]]] 

Set SYmbol [/Add|/Ignore|/Respect] [<lookspec> [<lookspec> [...]]] 

Set Tab <intexpr> 

Set Level [Assembly|Mixed|Source] 

Set LAnguage [CPP|CjFORTRAN] 

Set SUpportroutine <string> 

Set MAcro <wndname> <key> <command> 

Set DOntexpandhex [ON|OFf] 

<location> see call command. 

<lookspec> [/IgnoreI/Respect] <string> 


A.2.27 SHow 

The Show commands are used internally by the debugger to save and restore its configuration. The syntax 
is: 

SHow Paint 
SHow Display 
SHow Font 
SHow Set 

SHow Set AUtosave 

SHow Set Assembly 

SHow Set Variable 

SHow Set Functions 

SHow Set GLobals 

SHow Set REGister 

SHow Set Fpu 

SHow Set BE11 

SHow Set BReakonwrite 

SHow Set Call 

SHow Set Dclick 

SHow Set Implicit 

SHow Set INput 

SHow Set Radix 

SHow Set RECursion 

SHow Set SEarch 

SHow Set SOurce 

SHow Set SYmbol 

SHow Set Tab 

SHow Set Level 

SHow Set LAnguage 

SHow Set MAcro 

SHow Set SUpportroutine 

SHow Flip 

SHow Hook 

SHOW DOntexpandhex 
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A.2.28 SKip 

Use the Skip command to set CS:EIP to a specific address. The format of the command is: 

SKip <address> 


A.2.28 STackpos <intexpr> 

The Stackpos command is the same as using Undo/Unwind. The <intexpr> allows you to define the 
number of times to undo or unwind. 

A.2.30 SYstem (or!) 

Use the System command to spawn an operating shell to execute a given string. The format of the system 
command is: 

SYstem [/Remote|/Local] <string> 

/Remote the shell is started on the program side of a remote debug link. 

/Local the shell is started on the debugger side of a remote debug link. 

A.2.31 THread (or ~) 

Use the Thread command to manipulate the threads of execution of a multi-threaded application under 
OS/2 or NetWare 386. The format of the Thread command is: 

THread [/Show|/Freeze|/Thaw|/Change] [<threadid>] 

/Show display the status of the current thread. 

/Freeze freeze a thread and make it unrunnable. 

/Thaw make a frozen thread runnable. 

/Change to select a specific thread. 

<threadid> is the identification number of the thread. 

A.2.32 Trace 

Use the Trace command to step through the execution of your program. The Trace command is: 

Trace [/Assembly|/Mixed|/Source] [/Into|/Next|/Over] 

/Assembly trace through your assembly code on instruction at a time. 

/Mixed trace execution of the application one source statement at a time, or one instruction at a 

time when no source text is available. 
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/Source trace execution of the application one source statement at a time. 

/Into continue execution to the next statement or assembly instruction. If the current statement 

or instruction invokes a routine, then the next statement or instruction is the first one called 
in the routing. 

/Next continue execution to the next statement or assembly instruction that immediately follows 

the current statement or instruction in memory. If the current statement or instruction is 
one that branches, be sure that the execution path eventually executed the statement or 
instruction that follows. If the program does not executed this point, the program may 
execute to completion. 

/Over continue execution to the next statement or assembly instruction. If the current statement 

or instruction invokes a routine, then the next statement or instruction is the one that 
follows the invocation of the routine. 

A.2.33 Undo 

The format of the Undo command is: 

Undo <intexpr> 

If intexpr is positive, this is equivalent to using the menu item Undo/Undo <intexpr> times. If intexpr is 
negative, this is equivalent to using the menu item Undo/Redo -<intexpr> times. 

A.2.34 View 

Use the View command to show a file in a window. The format of the command is: 

View [/Binary] [<file>|<module>] 

/Binary show the file contents in binary. 

<file> the file to be shown. 

<module> the module to be shown. The default is the current module. 

A.2.35 While 

Use the While command to permit the execution of a list of commands while the specified expression is 
true. The While command is: 

While <expr> { <command> } 

A.2.33 Window 

This command operates on the current window. It is useful when defining accelerators that perform 
window operations. 
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Window CLose 

close the window 

Window CURSORStart 

move the cursor to start of line 

Window CURSOREnd 

move the cursor to end of line 

Window CURSORDown 

move the cursor down one line 

Window CURSORLeft 

move the cursor left 

Window CURSORRight 

move the cursor right 

Window CURSORUp 

move up one line 

Window Dump 

dump the window to a file 
Window Log dump the window to a log window 
Window FINDNext 

find the next occurrence of the current search string 
Window FINDPrev 

find the previous occurrence of the current search string 
Window Next make another window the current window 

Window PAGEDown 

move the window down one page 

Window PAGEUp 

move the window up one page 

Window POpup 

show the window’s floating pop-up menu 

Window SEarch 

search for a given string 

Window SCROLLDown 

scroll the window down one line 

Window SCROLLUp 

scroll the window up one line 

Window SCROLLTop 

scroll the window to the very top 
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Window SCROLLBottom 

scroll the window to the very bottom 

Window TABLeft 

move to the previous tabstop 

Window TABRight 

move to the next tabstop 

Window MAXimize 

maximize the window 

Window MINimize 

minimize the window 

Window RES tore 

restore the window 

Window Tile tile all windows 

Window CAscade 

cascade all windows 

Window PRevious 

move to the previous window 
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B. Predefined Symbols 


The Open Watcom Debugger defines a number of symbols which have special meaning. Each of the 
registers is designated by a special name. Note that the registers listed here are applicable when the target 
is an x86 platorm. For other platforms, the register set is different. 


eax 

32-bit EAX register (32-bit mode only) 

ax 

16-bit AX register 

al 

8-bit AL register 

ah 

8-bit AH register 

ebx 

32-bit EBX register (32-bit mode only) 

bx 

16-bit BX register 

bl 

8-bit BL register 

bh 

8-bit BH register 

ecx 

32-bit ECX register (32-bit mode only) 

cx 

16-bit CX register 

cl 

8-bit CL register 

ch 

8-bit CH register 

edx 

32-bit EDX register (32-bit mode only) 

dx 

16-bit DX register 

dl 

8-bit DL register 

dh 

8-bit DH register 

eip 

Instruction pointer register (32-bit mode only) 

ip 

Instruction pointer register 

esi 

Source index register (32-bit mode only) 

si 

Source index register 

edi 

Destination index register (32-bit mode only) 

di 

Destination index register 

esp 

Stack pointer register (32-bit mode only) 

sp 

Stack pointer register 

ebp 

Base pointer register (32-bit mode only) 

bp 

Base pointer register 

cs 

Code segment register 

ds 

Data segment register 

es 

Extra segment register 

fs 

Segment register (32-bit mode only) 

gs 

Segment register (32-bit mode only) 

ss 

Stack segment register 

fl 

Flags register 

efl 

Flags register (32-bit mode only) 


flg_bit_name ::= "c" I "p" I "a" I "z" I "s" I "i" I "d" I "o" 
efl. flg bit name Individual bits in Flags register 

flg_bit_name ::= "c" I "p" I "a" I "z" I V' I "i" I "d" I "o" 
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stO - st7 
cw 

cw.cw_bit_ 


sw 


The following table lists the full name for each of the flags register bits: 


fl.o, efl.o 
fl.d, ejl.d 

fl i, efl.i 
fl.s, efl.s 
fl.z, efl.z 
fl.a, efl.a 
fl.p, ejl.p 
fl.c, eflx 


overflow flag 
direction flag 
interrupt flag 
sign flag 
zero flag 

auxiliary carry flag 
parity flag 
carry flag 


Numeric Data Processor registers (math coprocessor registers) 
8087 control word (math coprocessor control word ) 
name Individual bits in the control word 


cw_bit_name ::= "ic" I "rc" I "pc” I "iem" I "pm" I 
"um" I "om" I "zm" I "dm" I "im" 


The following table lists the full name for each of the control word bits: 
cw.ic infinity control 

0 = projective 

I = affine 

cw.rc rounding control (2 bits) 

00 = round to nearest or even 

01 = round down (towards negative infinity) 

10 = round up (towards positive infinity) 

11= chop (truncate toward zero) 

cw.pc precision control (2 bits) 

00 = 24 bits 
01 = reserved 
10 = 53 bits 

II = 64 bits 

cw.iem interrupt enable mask (8087 only) 

0 = interrupts enabled 
1 = interrupts disabled (masked) 

cw.pm precision (inexact result) mask 

cw.um underflow mask 

cw.om overflow mask 

cw.zm zero-divide mask 

cw.dm denormalized operand mask 

cw.im invalid operand mask 

8087 status word (math coprocessor status word) 
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sw.sw_bit_name Individual bits in the status word 

sw_bit_name ::= "b" I ”c3" I "st" I "c2" I "cl" I 
"cO" I "es" I ”s/” I "pc"! "i<e” I 
Wl ”ze”l "<fc"| "fe" 

The following table lists the full name for each of the status word bits: 

sw.b busy 

sw.c3 condition code bit 3 

sw.st stack stop pointer (3 bits) 

000 = register 0 is stack top 
001 = register 1 is stack top 
010 = register 2 is stack top 


111= register 7 is stack top 

sw.c2 condition code bit 2 

sw.cl condition code bit 1 

sw.cO condition code bit 0 

sw.es error summary (287, 387 only ) 

sw.sf stack fault (387 only ) 

sw.pe precision (inexact result) exception 

sw.ue underflow exception 

sw.oe overflow exception 

sw.ze zero-divide exception 

sw.de denormalized operand exception 

sw.ie invalid operation exception 

mmO - mm7 MMX registers 

mmO.bO - mm0.b7 MMX register component bytes 
mmO.wO - mmO.w3 MMX register component words 
mmO.dO - mmO.dl MMX register component doublewords 

xmmO - xmm7 XMM registers (SSE registers) 

xmmO.bO - xmm0.bl5 XMM register component bytes 
xmmO.wO - xmm0.w7 XMM register component words 
xmmO.dO - xmm0.d3 XMM register component doublewords 
xmmO.qO - xmmO.ql XMM register component quadwords 

The debugger permits the manipulation of register contents using any of the operators described in the 
following chapter. By default, these predefined names are accessed just like any other variables defined by 
the user or the application. Should the situation ever arise where the application defines a variable whose 
name conflicts with that of one of these debugger variables, the module specifier _ dbg may be used to 
resolve the ambiguity. For example, if the application defines a variable called cs then _ dbg@cs can be 
specified to resolve the ambiguity. The "_dbg@" prefix indicates that we are referring to a debugger 
defined symbol rather than an application defined symbol. 
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The flags register, the 8087 control word, and the 8087 status word can be accessed as a whole or by its 
component status bits. 

Example: 

/ f 1. c=0 
/cw.um=0 
?sw.oe 

In the above example, the "carry" flag is cleared, the 8087 underflow mask of the control word is cleared, 
and the 8087 overflow exception bit of the status word is printed. 

The low order bit of the expression result is used to set or clear the specified flag. 

Example: 

f1.c=0x03a6 

In the above example, the "carry" flag is cleared since the low order bit of the result is 0. 

Similarly, the MMX and XMM registers can be accessed as a whole or by their component bytes, words, 
doublewords and quadwords (in the case of the 128-bit XMM registers). 

Example: 

/mmO,bl=l 
?mm0.dO 

In the above example, the second byte of the first MMX register is set to 1, then the first doubleword of the 
same register is printed. 

The debugger also defines some other special names. 

dbg$32 This debugger symbol represents the mode in which the processor is running. 

0 16-bit mode 

1 32-bit mode 

dbg$bp This debugger symbol represents the register pair SS:BP (16-bit mode) or SS:EBP (32-bit 

mode). 

Example: 

? dbg$bp 

dbg$code This debugger symbol represents the current code location under examination. The dot 
address "." is either set to dbg$code or dbg$data, depending on whether you were last 
looking at code or data. 

dbg$cpu This debugger symbol represents the type of central processing unit which is in your 

personal computer system. 

0 Intel 8088, 8086 or compatible processor 

1 Intel 80188, 80186 or compatible processor 

2 Intel 80286 or compatible processor 

3 Intel 80386 or compatible processor 
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dbg$ctid 


dbg$data 


dbg$etid 


dbg$fpu 


dbg$ip 


dbg$monitor 


dbg$ntid 


4 Intel 80486 or compatible processor 

5 Intel Pentium processor 

6 Intel Pentium Pro/II/III processor 

15 Intel Pentium 4 processor 

This debugger symbol represents the identification number of the current execution thread. 
Under environments which do not support threading, the current thread ID is always 1. The 
current execution thread can be selected using the Thread window or the Thread command. 

This debugger symbol represents the current data location under examination. The dot 
address is either set to dbg$code or dbg$data, depending on whether you were last 
looking at code or data. 

This debugger symbol represents the identification number of the thread that was executing 
when the debugger was entered. Under environments which do not support threading, the 
executing thread ID is always 1. 

This debugger symbol represents the type of numeric data processor (math coprocessor) 
that is installed in your personal computer system. 

-1 An 80x87 emulator is installed 

0 No coprocessor is installed 

1 An Intel 8087 is installed 

2 An Intel 80287 is installed 

3 An Intel 80387 is installed 

4 An Intel 80486 processor, supporting coprocessor instructions, is installed 

5 An Intel Pentium processor integrated FPU is installed 

6 An Intel Pentium Pro/II/III processor integrated FPU is installed 

15 An Intel Pentium 4 processor integrated FPU is installed 

This debugger symbol represents the register pair CS:IP (16-bit mode) or CS:EIP (32-bit 
mode). 

Example: 

? dbg$ip 

This debugger symbol represents the type of monitor adapter which is in use. 

0 IBM Monochrome Adapter 

1 IBM Colour Graphics Adapter (CGA) 

2 IBM Enhanced Graphics Adapter (EGA) 

3 IBM Video Graphics Array (VGA) 

This debugger symbol represents the identification number of the next execution thread. 

To iterate through all of the threads in a process, you can execute thread dbg$ntid 
repetitively until you are back to the original thread. Under environments which do not 
support threading, the next thread ID is always 1. To show the execution stack for all 
threads (in the Log window), you can execute the following commands: 
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dbg$os 


dbg$pid 

dbg$psp 

dbg$radix 

dbg$remote 

dbg$sp 


dbg$loaded 

dbg$nil 

dbg$src 


Example: 

/orig_ tid = dbg$ctid 
/curr_ tid = dbg$ctid 
while curr_ tid != 0 { 

print {-Next Thread %x-} curr_ tid; 

show calls; 

/curr_ tid = dbg$ntid; 

thread curr_ tid; 

if ( curr_ tid == orig_ tid ) { 

/curr_ tid = 0; 

} ; 

} 

This debugger symbol represents the operating system that is currently running the 
application. 

0 Unknown Operating System 

1 DOS 

2 OS/2 

3 386IDOS-Extender from Phar Lap Software, Inc. 

5 NetWare 386 from Novell, Inc. 

6 QNX from QNX Software Systems. 

7 DOS/4GW from Tenberry Software, Inc., or CauseWay (both included in 
the Open Watcom C/C++(32) and Open Watcom FORTRAN 77/32 
packages) 

8 Windows 3.x from Microsoft Corporation 

10 Windows NT/2000/XP or Windows 9x from Microsoft Corporation 

12 QNX 6.x ’Neutrino’ 

13 GNU/Linux 

14 FreeBSD 

(OS/2, NetWare 386, Linux, QNX, Windows NT, Windows 95 only) This debugger 
symbol contains the process identification value for the program being debugged. 

(DOS only) This debugger symbol contains the segment value for the DOS "program 
segment prefix" of the program being debugged. 

This debugger symbol represents the current default numeric radix. 

This debugger symbol is 1 if the "REMotefiles" option was specified and 0 otherwise. 

This debugger symbol represents the register pair SS:SP (16-bit mode) or SS:ESP (32-bit 
mode). 

Example: 

? dbg$sp 

This debugger symbol is 1 if a program is loaded. Otherwise, it is 0. 

This debugger symbol is the null pointer value. 

This debugger symbol is 1 if you are currently debugging in an area that contains 
debugging information. 
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C. Wiring For Remote Debugging 


This appendix describes both serial and parallel port cable wiring for remote debugging. 

C.1 Serial Port Wiring Considerations 

If you plan to use the serial port Debug Server "SERSERV", a cable must connect the serial ports of the 
two computer systems. The following diagram illustrates the wiring between the two serial ports. If your 
computer systems have more than one serial port, any serial port may be used. 

Task Machine Debugger Machine 

Serial Serial 

Connector Connector 


Pin # 

1 

(PG) <- 

Pin # 
->i 

(PG) 

2 

(TxD)<- 

- >3 

(RxD) 

3 

(RxD)<- 

- >2 

(TxD) 

-4 

(RTS) 

4 

(RTS) 

-—> 5 

(CTS) 

5 

(CTS) 

—> 6 

(DSR) 

6 

(DSR) 

7 

(SG) <- 

- >7 

(SG) 

—> 8 

(DCD) 

8 

(DCD) 

— 20 

(DTR) 

20 

(DTR) 


Figure 26. Serial Port Wiring Scheme 

Note that the wiring is symmetrical (i.e., either end of the cable can be plugged into either PC). This 
particular arrangement of the wiring is sometimes called a "null modem" (since pins 2 and 3 are crossed 
and no modem is involved). 

C.2 Parallel Port Wiring Considerations 

If you plan to use the parallel port Debug Server "PARSERV" or "PARSERVW", a cable must connect the 
parallel ports of the two computer systems. Three cabling methods are supported - the LapLink cable, the 
Flying Dutchman cable, and Watcom’s own design. There are two advantages to using the LapLink or 
Flying Dutchman cable: 

1. They are commercially available (you may already own one). 
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2. They may work with more PC "compatibles" than Watcom’s cable. Watcom’s cabling requires 
8 bi-directional data lines in the parallel port and some PC "compatibles" do not support this. 

The disadvantage with the LapLink and Flying Dutchman cables is that they are slower than Watcom’s 
cable since only 4 bits are transmitted in parallel versus 8 bits for Watcom’s. Thus Watcom’s cable is 
faster but it will have to be custom made. 


The LapLink cable is available from: 

Travelling Software, Inc. 

18702 North Creek Parkway 
Bothell, Washington, 

U.S.A. 98011 

Telephone: (206) 483-8088 
The Flying Dutchman cable is available from: 
Cyco, 

Adm. Banckertweg 2a, 

2315 SR Leiden, 

The Netherlands. 


The following diagram illustrates Watcom’s cable wiring between the two parallel ports. 


Task Machine Debugger Machine 

Parallel Connector Parallel Connector 


Pin Number 

1 <- 

2 <- 

3 <- 

4 <- 

5 <- 

6 <- 

7 <- 

8 <- 

9 <- 

10 <- 

11 <- 

12 <- 

13 <- 

14 <- 

15 <- 

16 <- 

17 <- 

18 <- 


Pin Number 
—> 2 
—> 1 
—> 14 
—> 16 
—> 15 
—> 13 
—> 12 
—> 10 
—> 11 
—> 8 
—> 9 
—> 7 
—> 6 
—> 3 
—> 5 
—> 4 
—> 17 
—> 18 


Figure 27. Watcom Cable Wiring Scheme 

The following diagram illustrates the LapLink cable wiring between the two parallel ports. 
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Task Machine 
Parallel Connector 


Debugger Machine 
Parallel Connector 


Pin Number 

2 - 

3 - 

4 - 

5 - 

6 - 

10 <- 

11 <- 

12 <- 

13 <- 

15 <- 

25 <- 


Pin Number 
—> 15 
—> 13 
—> 12 
—> 10 
—> 11 

5 

6 
4 
3 
2 

—> 25 


Figure 28. LapLink Cable Wiring Scheme 


The following diagram illustrates the Flying Dutchman cable wiring between the two parallel ports. 


Task Machine 
Parallel Connector 


Debugger Machine 
Parallel Connector 


Pin Number Pin Number 

1 -> 11 

2 -> 15 

3 -> 13 

4 -> 12 

5 -> 10 

10 <- 5 

11 <- 1 

12 <- 4 

13 <- 3 

15 <- 2 


Figure 29. Flying Dutchman Cable Wiring Scheme 

For the IBM PC and PS/2, the connectors are standard "male" DB-25 connectors. Note that, in all cases, 
the wiring is symmetrical (i.e., either end of the cable can be plugged into either PC). 


Note: Although the wiring is different for all three cables, the Open Watcom parallel communications 
software can determine which one is in use. 
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D. Remote File Operations (DOS, NT, OS/2 Only) 


Use the Remote File e Xchange program (RFX) to manipulate files on a personal computer which is 
connected to your personal computer using a debugger remote link. You should consult the chapter entitled 
"Remote Debugging" on page 89 to familiarize yourself with the concepts of remote debugging. The types 
of file operations that are supported on both local and remote machines include: 

1. creating, listing and removing directories 

2. setting the current drive and directory 

3. display, renaming, erasing, and copying files (including PC to PC file transfers). 

To run RFX, set up your machines as if you are about to do remote debugging. Start the remote debug 
server, then start RFX using the the following syntax. 


RFX trap_Jile[;trap_parm] [rfx_cmd] 


The name of a trap file must be specified when running RFX. See "Remote Debugging" on page 89. 

See the section entitled "Specifying Files on Remote and Local Machines" on page 100 for an explanation 
of remote and local file names. 

You are now ready to copy files back and forth between machines. 


D.1 RFX Commands 


When RFX is run without specifying a command, the DOS, NT or OS/2 prompt will change as illustrated 
in the following example. 

Example: 

Mon 11-06-1989 15:17:05.84 E:\DOC\UG 
E>rfx par 

[RFX] Mon 11-06-1989 15:17:12.75 @LE:\DOC\UG 
[RFX] E> 

Note that the current drive specifier "E" in "E:\DOC\UG" has changed to "@LE" indicating that the current 
drive is the local "E" drive. 

Any command can be typed in response to the prompt. RFX recognizes a special set of commands and 
passes all others on to DOS, NT or OS/2 for processing. The following sections describe RFX commands. 
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D.2 Set Current Drive - drive: 


drive: 


The current drive and locale can be set using this command. The "@L" or "@R" prefix may be used to 
specify the locale (local or remote). 

Example: 

d: 

Make the "D" disk of the current locale (local or remote) the current drive. Since the locale is not specified, 
it remains unchanged. 

Example: 

@rc: 

Make the "C" disk of the remote machine the current drive. Both locale and disk are specified. 

Example: 

@le: 

Make the "E" disk of the local machine the current drive. Both locale and disk are specified. 


D.3 Change Directory - CHDIR, CD 


chdir dir_spec 
cd dir_spec 


This command may be used to change the current directory of any disk on the local or remote machine. CD 
is a short form for CHDIR. The "@L" or "@R" prefix may be used to specify the locale (local or remote). 


Example: 

cd \tmp 

Make the "TMP" directory of the current drive the current directory. 


Example: 

cd d:\etc 


Make the "ETC" directory of the "D" disk of the current locale (local or remote) the current directory of 
that drive. 
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Example: 

cd @rc:\demo 

Make the "DEMO" directory of the "C" disk of the remote machine the current directory of that drive. 
Both locale and disk are specified. 

Example: 

cd @le:test 

Make the "TEST" subdirectory of the current directory of the "E" disk of the local machine the current 
directory of that drive. Both locale and disk are specified. 

D.4 Copy Files ■ COPY 


copy [/s] src_spec [dst_spec] [/s] 


The COPY command operates in a manner very similar to the DOS "COPY" and "XCOPY" commands. 
Files may be copied from the local machine to the local or remote machine. Similarly files may be copied 
from the remote machine to the local or remote machine. If A is specified then subdirectories are copied as 
well. Directories will be created as required for the destination files. If dst_spec is not specified then the 
default destination will be the current directory of the other locale (i.e., remote, if the file’s locale is local 
or, local, if the file’s locale is remote). 

Example: 

copy *.for @rd:\tmp 

All files of type "FOR" in the current directory are copied to the "TMP" directory of the "D" disk on the 
remote machine. If the current locale is the local machine then files are copied from the local machine to 
the remote machine. If the current locale is the remote machine then files are copied from the remote 
machine to the remote machine. 


Note: If your default drive is set to one of the disks on the local machine then the locale is local (e.g., 
@LC:, @LD:, @LE:, etc.). If your default drive is set to one of the disks on the remote machine then 
the locale is remote (e.g., @RC:, @RD:, @RE:, etc.). If your DOS, NT or OS/2 prompt contains the 
current drive and directory then it will be easy to identify which locale is current. 


Example: 

copy @rd:\tmp\*.for 

All files of type "FOR" in the "TMP" directory of the "D" disk on the remote machine are copied to the 
current directory of the local machine. Whenever a destination is not specified, the current directory of the 
opposite locale is used. If the source locale is the remote machine then files are copied from the remote to 
the local machine. If the source locale is the current machine then files are copied from the local to the 
remote machine. 


Copy Files - COPY 179 







Appendices 


Example: 

copy @rc:\watcom\*.* /s 

All files and subdirectories of the "WATCOM" directory of the "C" disk on the remote machine are copied 
to the current directory of the local machine. Whenever a destination is not specified, the current directory 
of the opposite locale is used. If the source locale is the remote machine then files are copied from the 
remote to the local machine. If the source locale is the current machine then files are copied from the local 
to the remote machine. Subdirectories are created as required. 


Note: The "COPY" command is most effectively used when copying files from one machine to the 
other. Copying of large amounts of files from one place on the remote machine to another place on the 
remote machine could be done more effectively using the remote machine’s DOS, NT or OS/2. This 
would eliminate the transfer of data from the remote machine to the local machine and back to the 
remote machine. 


D.5 List Directory - DIR 


dir [/w] dir_spec [/w] 


This command may be used to list the directories of any disk on the local or remote machine. Any of the 
DOS, NT or OS/2 "wild card" characters ("?" and "*") may be used. If /w is specified then file names are 
displayed across the screen ("wide") and the file creation date and time are omitted. 

Example: 

dir \tmp 

List the names of files in the "TMP" directory of the current drive. 

Example: 

dir d:\etc 

List the names of files in the "ETC" directory of the "D" disk of the current locale (local or remote). 
Example: 

dir @rc:\demo 

List the names of files in the "DEMO" directory of the "C" disk of the remote machine. Both locale and 
disk are specified. 

Example: 

dir @le:test 

List the names of files in the "TEST" subdirectory of the current directory of the "E" disk of the local 
machine. If no "TEST" subdirectory exists then the names of all files named "TEST" will be listed. Both 
locale and disk are specified. 
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Example: 

dir @le:test.* 

List the names of all files named "TEST" in the current directory of the "E" disk of the local machine. Both 
locale and disk are specified. 


D.6 Erase File ■ ERASE, DEL 


erase [/s] file_spec [Is] 
del [Is] file_spec [Is] 


This command may be used to erase files from the directories of any disk on the local or remote machine. 
DEL is a short form for ERASE. Any of the DOS, NT or OS/2 "wild card" characters ("?" and "*") may be 
used. If A is specified then subdirectories are also processed. 

Example: 

erase \tmp\*.* 


Erase all the files in the "TMP" directory of the current drive. 
Example: 

erase d:\etc\*.lst 


Erase all files of type "LST" in the "ETC" directory of the "D" disk of the current locale (local or remote). 
Example: 

erase @rc:\demo\*.obj 

Erase all files of type "OBJ" in the "DEMO" directory of the "C" disk of the remote machine. Both locale 
and disk are specified. 


Example: 

erase @le:trial.* 


Erase all files named "TRIAL" of any type in the current directory of the "E" disk of the local machine. 
Both locale and disk are specified. 


D.7 Exit from RFX ■ EXIT 


exit 


This command may be used to exit from RFX and return to the invoking process. 
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D.8 Make Directory - MKDIR, MD 


mkdir dir_spec 
md dir_spec 


This command may be used to create a directory on any disk on the local or remote machine. MD is a short 
form for MKDIR. The " @L" or " @R" prefix may be used to specify the locale (local or remote). 

Example: 

md \tmp 

Create a "TMP" directory in the root of the current drive. 


Example: 

md d:\etc 


Create an "ETC" directory in the root of the "D" disk of the current locale (local or remote). 

Example: 

md @rc:\demo 


Create a "DEMO" directory in the root of the "C" disk of the remote machine. Both locale and disk are 
specified. 

Example: 

md @le:test 


Create a "TEST" subdirectory in the current directory of the "E" disk of the local machine. Both locale and 
disk are specified. 


D.9 Rename ■ RENAME, REN 


rename file_spec new_name 
ren file_spec new_name 


This command may be used to rename a file in any directory on any disk on the local or remote machine. 
REN is a short form for RENAME. The "@L" or "@R" prefix may be used to specify the locale (local or 
remote). Unlike the DOS "RENAME" command, a file can be moved to a different directory if the 
directory is specified in new_name. 
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Example: 

ren test.tmp testl.tmp 

Rename the file "TEST.TMP" in the current directory of the current drive to "TEST1.TMP". 

Example: 

ren d:\etc\test.tmp testl.tmp 

Rename the file "TEST.TMP" in the "ETC" directory of the "D" disk of the current locale (local or remote) 
to "TEST1.TMP". 

Example: 

ren @rc:\demo\test.tmp testl.tmp 

Rename the file "TEST.TMP" in the "DEMO" directory of the "C" disk of the remote machine to 
"TEST1.TMP". Both locale and disk are specified. 

Example: 

ren @le:trial.dat triall.dat 

Rename the file "TR1AL.DAT" in the current directory of the "E" disk of the local machine to 
"TRIAL1.DAT". Both locale and disk are specified. 

Example: 

ren @le:trial.dat ..\triall.dat 

Rename the file "TRIAL.DAT" in the current directory of the "E" disk of the local machine to 
"TRIAL1.DAT" and move it to the parent directory. Both locale and disk are specified. 


D.10 Remove Directory ■ RMDIR, RD 


rmdir [Is] dir_spec [Is] 
rd [Is] dir_spec [Is] 


This command may be used to remove one or more directories on any disk on the local or remote machine. 
RD is a short form for RMDIR. The "@L" or "@R" prefix may be used to specify the locale (local or 
remote). If A is specified then subdirectories are also removed. Before a directory can be removed, it must 
not contain any files. 

Example: 

rd \tmp 

Remove the "TMP" directory from the root of the current drive. 
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Example: 

rd d:\etc 

Remove the "ETC" directory from the root of the "D" disk of the current locale (local or remote). 

Example: 

rd @rc:\demo 

Remove the "DEMO" directory from the root of the "C" disk of the remote machine. Both locale and disk 
are specified. 

Example: 

rd @le:test 

Remove the "TEST" subdirectory from the current directory of the "E" disk of the local machine. Both 
locale and disk are specified. 

D.11 Display File Contents ■ TYPE 


type dir_spec 


This command may be used to list the contents of a file on any disk on the local or remote machine. The 
"@L" or "@R" prefix may be used to specify the locale (local or remote). Unlike the DOS "TYPE" 
command, DOS, NT or OS/2 "wild card" characters ("?" or "*") may be used. 

Example: 

type \tmp\test.dat 

List the contents of the file "TEST.DAT" in the "TMP" directory of the current drive. 

Example: 

type d:\etc\*.lst 

List the contents of all files of type "LST" in the "ETC" directory of the "D" disk of the current locale (local 
or remote). 

Example: 

type @rc:\demo\test.c 

List the contents of the file "TEST.C" in the "DEMO" directory of the "C" disk of the remote machine. 

Both locale and disk are specified. 

Example: 

type @le:trial.* 

List the contents of all files named "TRIAL" of any type in the current directory of the "E" disk of the local 
machine. Both locale and disk are specified. 
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D.12 RFX Sample Session 

Run serial port server on remote PC specifying a port 1 and a maximum baud rate of 38,400 baud. 

Tue 11-07-1989 15:29:24.19 C:\ 

Oserserv 1.38 


Run RFX on local PC. 

Tue 11-07-1989 15:30:53.18 E:\DOC\UG 
E>rfx ser 

Link at 38400 baud 


List directory of remote machine’s "F" drive. 


9 15:30:59.33 @LE:\DOC\UG 


[RFX] Tue 11-07-198 

[RFX] E>dir @rf: 

CLIB <DIR> 

MATH <DIR> 

PCLINT <DIR> 

3 File(s) 1 


02-01-89 06:43p 

02-01-89 06 : 51p 

03-09-89 04:05p 

6748544 bytes free 


Switch to remote machine’s "F" drive and list files. 

[RFX] Tue 11-07-1989 15:31:11.80 @LE:\DOC\UG 
[RFX] E>@rf: 

[RFX] Tue 11-07-1989 15:31:22.51 @RF:\ 

[RFX] F>dir 

CLIB <DIR> 02-01-89 06:43p 

MATH <DIR> 02-01-89 06:51p 

PCLINT <DIR> 03-09-89 04:05p 

3 File(s) 16748544 bytes free 


Change to subdirectory and list files. 
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[RFX] Tue 11-07-1989 15:31:27.73 @RF:\ 
[RFX] F>cd clib 

[RFX] Tue 11-07-1989 15:31:47.83 @RF:\CLIB 
[RFX] F>dir 


. 


<DIR> 

02-01-89 

06:43p 

. . 


<DIR> 

02-01-89 

06:43p 

MKCLIB 

BAT 

95 

12-20-88 

04:24p 

MKMODEL 

BAT 

128 

02-01-89 

04 :32p 

MDEF 

INC 

1831 

12-08-88 

12 :23p 

STRUCT 

INC 

2487 

12-20-88 

05 : 45p 

CLIB 

MIF 

559 

02-01-89 

04 : 42p 

H 


<DIR> 

02-01-89 

06:44p 

SCSD 


<DIR> 

02-01-89 

06:44p 

BCSD 


<DIR> 

02-01-89 

06:44p 

SCBD 


<DIR> 

02-01-89 

06:44p 

BCBD 


<DIR> 

02-01-89 

06:44p 

BCHD 


<DIR> 

02-01-89 

06:44p 

ANSI 


<DIR> 

02-01-89 

06:44p 

DOS 


<DIR> 

02-01-89 

06:47p 

A 


<DIR> 

02-01-89 

0 6:50p 

C 


<DIR> 

02-01-89 

0 6:50p 

CGSUPP 


<DIR> 

02-01-89 

06: 50p 


18 File(s) 16748544 bytes free 


List directory of local machine. 


[RFX] Tue 11-07-1989 15:31:51.57 @RF:\CLIB 


[RFX] F>dir @1. 

.\tools\ 

*. c 


CALENDAR 

C 

4378 

04-17-89 

08 :17p 

CLRSCRN 

c 

233 

04-17-89 

08 :17p 

ERR 

c 

198 

04-17-89 

08 : 30p 

MAIN 

c 

142 

04-17-89 

09:14p 

SAMPLEI 

c 

83 

04-14-89 

03:56p 

SAMPLE2 

c 

83 

04-14-89 

03:57p 

SAMPLE3 

c 

86 

04-14-89 

03:58p 

SAMPLE4 

c 

132 

04-14-89 

04:05p 

SAMPLE5 

c 

131 

04-14-89 

04:05p 

SUB1 

c 

108 

11-03-89 

05 : lip 

SUB2 

c 

108 

11-03-89 

05 : lip 

TEST 

c 

236 

05-08-89 

07:02p 


12 File(s) 8292352 bytes free 


Copy file from local machine to current directory of remote machine. 

[RFX] Tue 11-07-1989 15:32:21.99 @RF:\CLIB 
[RFX] F>copy @1..\tools\test.c 
E:..\TOOLS\TEST.C 

1 Files copied 0 Directories created 


Confirm presence of file. 

[RFX] Tue 11-07-1989 15:32:41.22 @RF:\CLIB 
[RFX] F>dir *.c 

TEST C 236 05-08-89 07:02p 

1 File(s) 16746496 bytes free 

Leave RFX. 
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[RFX] Tue 11-07-1989 15:32:46.99 @RF:\CLIB 
[RFX] F>exit 

Tue 1989-11-07 15:32:57.20 E:\DOC\UG 
E> 
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3 


32-bit application debugging 109 
32-bit debugging 
trap file 16 

386IDOS-Extender 109, 172 
version 109 
387 

examining 84 
modifying 84 


8 


8087 

examining 84 
modifying 84 
registers 168 


@ 


@ @routine_name 120 
@L 100 
@R 100 

@routine_name 120 


A 


About menu item 37 
Accelerate command 146 
Accelerator 

for menu items 27 
for pop-up menu 26 


window 38 

Accelerator menu item 36 
Accelerator Pop-up menu 
Delete 39 
Modify 39 
New 39 
TD Keys 39 
WD Keys 39 
accelerators 29, 38 
Action menu 27, 37, 112 
Address menu item 66 
All Modules menu item 43 
Application menu item 36 
arguments 
changing 31 
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expand 62 

traversing in memory 68 
view slices 62 
assembly 

debugging 81 
examining 82 
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setting break points 82 
window 82 

Assembly menu item 5, 35, 46, 48, 56, 67, 74 
Assembly options 34 
Assembly Pop-up menu 
Break 82 
Enter Function 82 
Hex 83 
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Inspect 82 
No source 83 
Show/Address 82 
Show/Functions 82 
Show/Module 83 
Show/Source 82 
At Cursor menu item 72 


B 


backward execution 
over call 56 

over simple statement 54 
Bell 32 
Break 

window 74 

Break All menu item 46 
Break command 147 
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Break menu 
At Cursor 72 
Clear All 73 
Disable All 73 
Enable All 73 
New 73 

On Debug Message 73 
On Image Load 73 
Restore 73 
Save 73 
Toggle 72 
View All 73 

Break menu item 5, 44-45, 48, 57, 62, 72, 82 
Break on write 32 
Break on Write menu item 66 
Break Pop-up menu 
Assembly 74 
Delete 74 
Disable 74 
Enable 74 
Modify 74 
New 74 
Source 74 
breakpoint 

at cursor position 73 
changing 74 
clearing 72 
clearing all 73 
condition 71,76 
countdown 71,76 
counting 76 
creating new 74 
defined 71 
deleting 74, 77 
disabling 72, 74 
disabling all 73 
displaying 73 
enabling 72, 74 
enabling all 73 

executing debugger commands 76 

finding assembly code 74 

finding source code 74 

in assembly code 82 

on debug message 73 

on execute 71,76 

on image load 73 

on write 44, 62, 66, 71, 76 

restoring 73 

saving 73 

setting 73 

setting in caller 57 

setting simple 72 

specifying address 75 

state 72 


status 77 
toggling 72 
up call stack 57 
window 74 
breakpoints 4 
buttons 4, 25 
Byte menu item 85-86 



cable 

Flying Dutchman 173 
LapLink 173 
W atcom 

Watcom’sown 173 
Call command 148 
calls 

displaying stack 57 
unwinding stack 4, 28, 30, 55, 57 
window 57 
Calls menu item 35 
Calls Pop-up menu 
Break 57 
Goto 57 
Unwind 57 

CAPture command 150 
case insensitive searching 32 
CauseWay 105, 109-110,172 
changing memory 36 
char 132 

CHecksize option 19 
Class/Show Functions menu item 64 
Class/Show Generated menu item 64 
Class/Show Inherited menu item 64 
Class/Show Private menu item 64 
Class/Show Protected menu item 64 
Class/Show Static menu item 64 
Clear All menu item 46, 73 
code 

skipping 53 
Code menu 35 
Assembly 35 
Calls 35 
Functions 35 
Images 35 
Modules 35 
Replay 35 
Source 35 
Threads 35 

CodeView keyboard emulation 29 
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Color option 18 
Colour option 18 
COlumns option 16,20-21 
command 

Accelerate 146 
Break 147 
Call 148 
CAPture 150 
COnfigfile 150 
Display 150 
DO (or/) 151 
ERror 151 
Examine 152 
Flip 153 
FOnt 153 
Go 153 
Help 154 
HOok 154 
IF 154 

INvoke(or<) 155 
Fog (or >) 155 
MOdify 155 
NEW 156 
PAint 156 
Print (or?) 158 
Quit 160 
RECord 160 
Register 160 
REMark (or *) 160 
Set 160 
SHow 161 
SKip 162 

STackpos <intexpr> 162 
summary 146 
syntax 145 
SYstem (or !) 162 
THread (or ~) 162 
Trace 162 
Undo 163 
View 163 
While 163 
Window 163 
Command menu item 31 
common menu items 4 
COnfigfile command 150 
configuration 

automatic saving of 32 
saving 32 

Console option 20-21 
Contents menu item 37 
context sensitivity 4 
control-key shortcuts 26 
Coprocessor 
examining 84 


modifying 84 
CPU Register 
window 81 

Cursor Follow menu item 66 
CW.TRP 110 

CWD, environment variable 113-114 
CWSTUB.EXE 110 
Cyco 173 


D 


Data menu 35 
File Variables 35 
FPU Registers 36 
Globals 35 
I/O Ports 36 
Focals 35 
Fog 36 
Memory at 36 
MMX Registers 36 
Registers 35 
Stack 36 
Watches 35 
XMM Registers 36 
_dbg@ 169 
_dbg 169 
dbginst.exe 94 
DBGFIB.REX 110 
dbgport.sys 94 
debug compiler options 9 
debug kernel 89 
debug linker options 10 
debug registers 
disabling 113 
using 113 

Debug Startup menu item 54 
debugging 

32-bit DOS applications 109 
at assembly level 81 
DDEs 49 
mouse events 16 
Novell NFM 111 

postmortem dump under QNX 114 
preparing application for 9 
remote 89 

windows applications 112 
debugging an OS/2 exception handler 16 
debugging DFFs 112 
debugging information 49 
debugging under Linux 113 
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debugging under QNX 114 
Delete menu item 5, 39, 63, 74, 83 
Delete Symbols menu item 50 
dialogs 

general description 28 
Dip option 18 
Disable All menu item 73 
Disable menu item 74 
display 

changing columns 16 
changing lines 16,18 
Display command 150 
DLL 

debugging 49, 112 
showing list of 49 
D O (or /) command 151 
DOS extenders 

386IDOS-Extender 109, 172 
CauseWay 109, 172 
debugging 109 
DOS/4GW 109, 172 
trap option 16 
DOS/4GW 109, 172 
version 109 
DOS4G.EXE 110 
DOS4GW.EXE 110 
double 132 
Double menu item 86 
DOwnload option 17 
dumper 114 
dumper command 114 
DWord menu item 85-86 
DYnamic option 16 


E 


Edit menu item 62-63 
EGA lines 18 
Ega43 option 18 
Enable All menu item 73 
Enable menu item 74 
Enter Function menu item 44, 82 
environment variables 
CWD 113-114 
HOME 114, 116 
PATH 16-17,91,95-97,110 
WD 21-22 

WD_PATH 113-114,116 
ERror command 151 
ESP 36 


Examine 119 
Examine command 152 
exception handler 
OS/2 16 

Execute to menu item 53 
Exit menu item 31 
expression 
evaluate 61 
expressions 
aggregate 126 
C operators 127 
C++operators 134 
character constant 125 
coercing types 127,132 
complex constant 124 
control word register 126 
current module 120 
current routine 120 
_dbg module 126 
_dbg@cs 126 
evaluating 45 
flags 126 
flags register 126 
floating point registers 126 
FORTRAN operators 137 
function 120 
handling of 119 

image @ module @routine_name 120 

instruction pointer 126 

integer constant 123 

line numbers 122 

memory references 125 

module 120 

module @routine_name 120 
offset 125 

pre-defined variables 126 
procedure 120 
real constant 124 
referencing memory 125 
register aggregate 126 
registers 126 
routine 120 
rules 119 
segment 125 
segment registers 126 
status word register 126 
symbol name 120 
type enforcement 127,132 
watching 45 
Extended menu item 81 
extensions 
.TRP 16 
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F 


Far Follow menu item 66 
Fasts wap option 20 
features 3 

FieldOnTop menu item 63 
file 

viewing 45 
window 45 
File menu 31 
Command 31 
Exit 31 
Load Setup 31 
Open 31 
Options 31 
Save Setup 31 
Source Path 31 
System 31 
View 31 

Window Options 31 
file operations 
remote 177 
File options 34 
File Variables 
window 61 

File Variables menu item 35 
Find menu item 43, 45 
Flip command 153 
float 132 

Float menu item 85-86 
Flying Dutchman cable 173 
FOnt command 153 
FPU 

window 84 
FPU Pop-up menu 
Hex 84 
Modify 84 

FPU Registers menu item 36 
Freeze menu item 58 
Functions 

inspecting 44 
showing list of 45, 48 
window 48 

Functions menu item 5, 35, 46, 50 
Functions options 34 
Functions Pop-up menu 
Assembly 48 
Break 48 
Source 48 
Typed Symbols 48 


G 


global variables 
displaying 47 
showing list 47 
Globals 

window 47 

Globals menu item 5, 35, 50 
Globals options 34 
Globals Pop-up menu 
Raw Memory 47 
Typed Symbols 47 
Watch 47 
GNU/Linux 172 
Go command 153 
Go menu item 53 
Goto menu item 56-57 
graphics applications 
debugging 111 


H 


Help command 154 
Help menu 37 
About 37 
Contents 37 
On Help 37 
Search 37 

Hex menu item 81, 83-86 
HOME environment variable 114, 116 
Home menu item 45, 55, 66, 83 
HOok command 154 


/ 


I/O 

window 83 
I/O Pop-up menu 
Delete 83 
Modify 83 
New 83 
Read 84 
Type 84 
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Write 84 
I/O ports 
reading 83 
writing 83 

I/O Ports menu item 36 
IF command 154 
Images 

showing list of 49 
window 49 
Images menu item 35 
Images Pop-up menu 
Delete Symbols 50 
Functions 50 
Globals 50 
Modules 50 
New Symbols 50 
infinite loop 

interrupting 105 

Inspect menu item 4, 44, 62, 81-82, 85-86 
instruction pointer 
repositioning 53 
int 132 
Internet 100 
Internet Protocol 

remote debugging 99 
interrupting a running program 105 
INvoke (or <) command 155 
invoke files 32 
Invoke option 16 
IP address 99 


K 


keep 153 

keyboard equivalents 29, 38 
for menu items 27 
for pop-up menu 26 


L 


LapLink cable 173 
Left menu item 66 
Lines option 16 
linked lists 

following in memory 68 
Linux 172 

customization 113 


debugging 113 
Load Setup menu item 31 
local file specifier prefix 
@L 100 

Local variables 35 
LOcalinfo option 17 
Locals 

window 61 
Locals menu item 35 
locating source code 11 
Log 

window 38 

Log (or >) command 155 
Log menu item 36 
long 132 
loops 

running to completion 53 
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Match menu item 43 

memory 

break on write 66 
changing 36 
display 65 
displaying 36 
examine array 66 
examine new address 66 
follow pointers 66 
modify 65-66 
set display type 67 
window 65 

Memory at... menu item 36 

Memory Pop-up menu 
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Assembly 67 
Break on Write 66 
Cursor Follow 66 
Far Follow 66 
Home 66 
Left 66 
Modify 66 
Near Follow 66 
Previous 66 
Repeat 66 
Right 66 

Segment Follow 66 
Type/0:16 Pointer 67 
Type/0:32 Pointer 67 
Type/16:16 Pointer 67 
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Type/16:32 Pointer 67 

Type/_int64 67 

Type/Byte 67 
Type/Char 67 
Type/Double 67 
Type/Dword 67 
Type/Extended Float 67 
Type/Float 67 
Type/Fong 67 
Type/Qword 67 
Type/Short 67 

Type/Unsigned_int64 67 

Type/Unsigned Char 67 
Type/Unsigned Fong 67 
Type/Unsigned Short 67 
Type/Word 67 
menu 

accelerator 26 
accelerators 27 
Action 27 
alt-key shortcuts 27 
Assembly 5 
Break 5 

control-key shortcuts 26 
Delete 5 
Functions 5 
Globals 5 
Inspect 4 

keyboard equivalents 27 
Modify 4 
New 5 

shortcuts 26-27 
Show 5 
Source 5 
Type 5 
Watch 5 
menus 27 

Microsoft Corp 172 
MMX 

examining 85 
modifying 85 
window 85 
MMX Pop-up menu 
Byte 85 
DWord 85 
Float 85 
Hex 85 
Inspect 85 
Modify 85 
QWord 85 
Signed 85 
Word 85 

MMX registers 169 
MMX Registers menu item 36 


Modify 119 

MOdify command 155 

Modify menu item 4, 39, 66, 74, 81, 83-86 

Modify... menu item 62 

modules 

showing list of 46 
window 46 

Modules menu item 35, 50 
Modules options 34 
Modules Pop-up menu 
Assembly 46 
Break All 46 
Clear All 46 
Functions 46 
Show All 46 
Source 46 

Monochrome option 18 
mouse 

sharing 16 
mouse events 
debugging 16 

Multi-media extension registers 
examining 85 
modifying 85 
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name completion 53, 75 
Named Pipes 

remote debugging 97 
Near Follow menu item 66 
NetWare 386 172 
NEW command 156 
new features 3 

New menu item 5, 39, 61, 63, 73-74, 83, 119 

New Symbols menu item 50 

Next menu item 36, 43 

Next Sequential menu item 53 

NFM 

debugging Novell 111 
showing list of 49 
No source menu item 83 
NOCHarremap option 19 
NOExports option 17 
noflip 153 
NOFpu option 18 
NOGraphicsmouse option 20 
NOInvoke option 16 
NOMouse option 16 
NOSYmbols option 18 
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Novell 172 
Novell NLM 
debugging 111 

Novell SPX remote debugging 93 
null modem wiring 173 


0 


On Debug Message menu item 73 
On Help menu item 37 
On Image Load... menu item 73 
on top 63 
Once argument 93 
Open menu item 31 
Open Watcom Debugger 
overview 3 
option 
Bell 32 

Break on write 32 
options 

Assembly window 34 
CHecksize 19 
Color 18 
Colour 18 
COlumns 16,20-21 
Console 20-21 
default 22 
dialog 32 
Dip 18 
DOwnload 17 
DYnamic 16 
Ega43 18 
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Functions window 34 
Globals window 34 
Invoke 16 
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Modules window 34 
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NOCHarremap 19 
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NOInvoke 16 
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NOSYmbols 18 
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REMotefiles 17 
setting 31 
Swap 19 
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Two 18 

Variables window 34 
Vga50 18 

Watches window 34 
XConfig 21 
Options menu item 31 
Options/Whole Expression menu item 65 
OS/2 

remote debugging 98 
OS/2 exception handler 16 
OutputDebugString 73 
overview 3 
Overwrite option 18 
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Page option 19 
PAint command 156 
parallel port 
wiring 173 

parallel port remote debugging 94 
parameters 
changing 31 

PATH environment variable 16-17, 95-97, 110 
PATH, environment variable 91 
PEDHELP.EXP 110 
Phar Lap Software, Inc 109, 172 
RUN386.EXE 110 
TNT.EXE 110 
platforms supported 3 
PLS.TRP 110 
PLSHELP.EXP 110 
pmd.trp 115 
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display as array 65 
display as string 64 
display value 64 
follow 62 

follow in memory 66 
show as array 62 
show code at 63 
show memory at 63 
postmortem dump 
QNX 114 
predefined symbol 
dbg$32 170 
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dbg$bp 170 
dbg$code 170 
dbg$cpu 170 
dbg$ctid 171 
dbg$data 171 
dbg$etid 171 
dbg$fpu 171 
dbg$ip 171 
dbg$loaded 172 
dbg$monitor 171 
dbg$nil 172 
dbg$ntid 171 
dbg$os 172 
dbg$pid 172 
dbg$psp 172 
dbg$radix 172 
dbg$remote 172 
dbg$sp 172 
dbg$src 172 

Previous menu item 43, 66 

Print (or ?) command 158 

program 
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interrupting 105 
preparing for debugging 9 
restarting 31, 54 
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QNX 172 

customization 114 
debugging 114 
QNX Software Systems 172 
Quit command 160 
QWord menu item 85-86 
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default 33 
setting 33 

Raw Memory menu item 47 
Read menu item 84 
RECord command 160 
recording debug session 56 
Recursive functions 


tracing over 32 
Redo menu item 55 
Register command 160 
Register Pop-up menu 
Extended 81 
Hex 81 
Inspect 81 
Modify 81 
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cw 168 

displaying 32-bit 81 
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examining 81 
flags 168 
floating point 168 
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MMX 169 
modifying 81 
stO - st7 168 
status word 168 
sw 168 
XMM 169 
xmmO - xmm7 169 
Registers menu item 35 

53 REMark (or *) command 160 

remote debugging 89 
Novell SPX 93 
Once argument 93 
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parallel port wiring 173 
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with OS/2 98 
with TCP/IP 99 
with Windows 96 
with Windows NT 98 
remote file operations 177 
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11ntroduction 


Documentation for programs in the form of help files can make the user’s life much easier. The Open 
Watcom OS/2 Help Compiler produces such documentation for the OS/2 operating system’s Information 
Presentation Facility (IPF). It consumes text documents containing special IPF tags, commands, and 
(optionally) bit-mapped graphics, and outputs help files in the .inf or .hip formats. 

The IPF tags are similar to other SGML tags, the most familiar of which is likely HTML. The IPF tags 
allow you, the documentation author, to: 

• Specify the source (highlighted text or regions of an image) and destination of hyper-link jumps 

• Set right and left text margins 

• Create lists, footnotes, notes, and various other kinds of notices 

• Create tables 

• Add illustrations in the form of examples, text figures, and bit-mapped graphics 

• Change the size, style, and color of displayed text 

• Change whether text spacing and new lines in the source are significant or not 

• Customize the behavior of windows in the help viewer 

• Create communication links to other applications 

This document provides a basic description of how tags are used ("Using IPF Tags" on page 7) as well as a 
complete reference for each tag ("IPF Tag Reference" on page 13). For more advanced topics, please refer 
to IBM’s "IPF Programming Guide and Reference" (ipfref.inf) which is available on the internet. 
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2 Using the Open Watcom OS/2 Help Compiler 


The Open Watcom OS/2 Help Compiler is a command line utility. It may be invoked as follows: 

wipfc [options] input.ipf 

2.1 Environment Variables 

The Open Watcom OS/2 Help Compiler depends upon several environment variables that must be set 
correctly before wipfc is run. 

WIPFC This must be set to %watcom%\wipfc, which is the location of the files defining the 

local language encoding. 

IPFCARTWORK Must point to your source of bit-mapped graphic images if your source file uses any. 

IPFCIMBED Must point to your source of input files if your main source file includes other source 

files. 

TMP Must point to a directory where temporary files that are generated by Open Watcom 

OS/2 Help Compiler can be stored. 

2.2 Command Line Flags 

The behavior of the Open Watcom OS/2 Help Compiler can be altered using command line options. Each 
flag begins with a delimiter. Either or 7’ can be used. Each flag is given a longer descriptive name 
here, but only the first character after the delimiter is actually significant. Flag names are not 
case-sensitive. 

2.2.1 Switches 

The switches change the state of the Open Watcom OS/2 Help Compiler in a yes/no fashion. 

Name Description 

inf Generate an ’inf’ file. Otherwise a ’hip’ file is created by default. 

quiet Operate quietly, suppressing the usual copyright information display. 

suppress-search Suppress the generation of the full-text search table in the output file. This makes the 
help file smaller, but the user can’t search for individual words. 
xref Generate additional output information, including a cross-reference of identifiers. 

This is saved in a file ’output-name.log’ where ’output-name’ is the base name of the 
help file being created. 
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2.2.2 Options 

The options give additional information to the Open Watcom OS/2 Help Compiler Each option is 
immediately followed by the information to be passed into wipfc. 


2.2.2.1 localization 

Help files can be created for different locales. This is done by using the localization option in the form of 

-1 xx_ YY 

where xx_YY is the name of the locale (for example, en_US). The localization information is store in a 
text file (en_US.nls in this case). You can create your own locales from the sample file xx_YY.nls, but you 
may also need to create a corresponding entity file containing the definitions of "IPF Symbols" on page 43. 

2.2.2.2 output-name 

You can specify the name of the help file that wipfc generates by using the output-name option. For 
example, 

-o MyHelp 

will cause wipfc to generate an output file (either inf or hip depending on the -inf switch) with a base name 
of ’MyHelp’ 

2.2.2.3 warning-level 

The Open Watcom OS/2 Help Compiler generates three different levels of warnings (1, 2, and 3). By 
default, all levels of warnings are displayed. You can suppress the display of warnings higher than level n 
by using the warning-level option. For example, 

-wl 


suppresses all warnings higher than level 1. 
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3 Using IPF Tags 


Source files for the Open Watcom OS/2 Help Compiler consist of text (words, whitespace, punctuation, and 
entity references), markup tags, and commands. Each markup tags is described in detail elsewhere ("IPF 
Tag Reference" on page 13), as are the commands ("Using IPF Commands" on page 11). 

Tags come in four flavors: 

1. Tags that appear in the document header and control how the document behaves. 

2. Tags that establish blocks. These tags can contain other tags as well as text. 

3. Tags that are in-line and contain text or other in-line tags. 

4. Formatting tags that can appear anywhere, but are usually in-line. 


3.1 Text 

Text consists of words, whitespace, punctuation, and entity references (symbols). 

3.1.1 Words 

Words consist of letters and/or numbers (ABC123 is a single word, for example). Which letters are valid 
depends upon the current locale. For the default locale (en_US, code page 850), the upper and lower case 
ASCII letters are allowed (A-Z, a-z). Other letters can be included via entity references. 

3.1.2 Whitespace 

Whitespace consists of spaces, tabs, and new-line characters. Usually, single whitespace characters are not 
significant, but multiple whitespace characters are. Tab characters are not expanded, so count as a single 
whitespace character. New-lines are generally ignored. 

Some tags create blocks where some or all forms of whitespace become significant. In these cases, 
new-line characters will cause line breaks and the text will be shown as you have formatted it. If the block 
is monospaced, spaces as well as new-lines will be significant. 

3.1.3 Punctuation 

Punctuation is not part of a word. ’ABC123’ is a single word, but ’ABC-123’ is actually two words 
(’ABC’ and ’123’) and a punctuation (’-’). 

Some forms of punctuation are used to delimit tags or entity references. When a colon (’:’) or ampersand 
(’&’) begin a word, that word is treated as a tag or entity reference, respectively. Fikewise, a period (’.’) 
ends both tags and entity references. If you need to use such constructs, replace the punctuation character 
with an entity reference (’&colon.\ ’&amp.', and ’&per.’). 
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3.1.4 Entity References (Symbols) 

Entities are symbolic references to single characters. During processing of the source file, valid entity 
references are removed and the matching single character is substituted. This allows you to include special 
characters that are outside the normal character set (for example, characters with diacriticals) in words. 

Unless the entity reference is a punctuation symbol, a string of ...-word-entity-word-... (in any order) is 
considered to be a single word. 

Unrecognized entity references will cause wipfc to generate a warning. Note that all entity references are 
case sensitive: &Alpha. and &alpha. are two different things. 

3.2 Tag Syntax 

All tags begin with a colon (’:’) and end with a period (’.’). In addition, many tags have flags or 
attribute=value pairs that appear inside the tag between the tag name and the end-of-tag delimiter (’.’). If 
you forget the end-of-tag delimiter, the numerous warnings that wipfc generates will be sure to let you 
know. 


3.3 Tag Attributes 

A tag may have one or more attributes. An attribute contains additional information that a tag needs. The 
attribute has a name, and may also have a value or keyword assigned to it. 

For example, heading tags have a ’res’ attribute that specifies a window identifier (a target for hyper-linked 
jumps). 

:hl res=001.How to make Popcorn 


In this case, res is assigned the value 001. 

Notice that attributes are part of the tag, and the end-of-tag delimiter always follows the last attribute. 

Many tags have multiple attributes. If you like, you can place them on different lines or all on a single line. 
If you place them on different lines, however, the attribute and its assigned value must be on the same line. 
Spaces are allowed between the attribute, ’=’, and the value. If spaces are required within the value, the 
value must be enclosed in matching quotation marks (”, or "", but not ’" or "’). 

Optional attributes all have default values and do not need to be specified unless you need to change the 
default. Other attributes are required, and wipfc will issue a warning if they are not specified. 

Attributes may be specified in any order within a tag. 

Some attributes may not have a value, in which case the presence of the attribute simply acts as a boolean 
flag. For those attributes that do have values, values can be numeric, text strings (with spaces, if quoted), 
or keywords. For example, the color tag specifies the foreground and/or background color for text. Only 
certain colors are supported, and each has a keyword: 

default 

blue 

red 
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pink 

green 

cyan 

yellow 

neutral 

brown 

darkgray 

darkblue 

darkled 

darkpink 

darkgreen 

darkcyan 

black 

palegray 

3.4 End Tags 

Some tags require matching end tags to form an enclosing block of code. The end tag has the same name as 
the tag prefixed with the letter ’e\ For example, if "tag" had an end tag, it would be "etag". 

3.5 Nesting Tags 

Most tags can be arbitrarily nested within other tags. However, some tags can only be nested inside other 
tags. For example, the list-item tag (li) can only appear between opening and closing list tags. 

In addition, there are a few tags that restrict the kinds of elements that they can contain. If you try to 
include a tag where it doesn't belong, wipfc will issue a warning, the tag will be ignored, and the result will 
not be what you hoped for! 

3.6 Tags Requiring Text 

Some tags (for example, heading tags ) have text associated with them. This text can appear either 
immediately after the end-of-tag delimiter (’.’) or on the next line. Note, however, that in this case the 
end-of-tag delimiter must be immediately followed by a new-line character. No other form of whitespace is 
allowed. 


3.7 Units of Measure 


Several tags have attributes that are measurements of one sort or another (window origin and extent, for 
example). Dimensional measurements can be one of three types: absolute, relative, or dynamic. 

Absolute measurements consist of a number followed by a letter that indicates the unit of measurement. 
The units are: 
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• c: the average character width of the default system font. 

• x: pixels. 

• p: typographical points (about 1/72 inch). 

Relative measurements consists of a number followed by the percent sign (%). The values is a percentage 
of the parent window width or height. 

Dynamic measurements consist of a keyword. The actual value is computed at run-time based on the 
current size and position of the parent window. The keywords for x-axis values are: 

• left: flush left in the parent window 

• center: centered in the parent window 

• right: flush right in the parent window 

The keywords for y-axis values are: 

• top: at the top of the parent window 

• center: centered in the parent window 

• bottom: at the bottom of the parent window 

Note that the coordinate system for all window measurements has its origin at the lower left corner. 
Increasingly positive values represent movement upward and rightward. 
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4 Using IPF Commands 


In addition to tags, the Open Watcom OS/2 Help Compiler recognizes 5 commands (or control words) that 
invoke special processing procedures. Each command must start with a period in the first column of a 
line, followed by the name of the command. Commands that start anywhere except the first column of a 
line will be treated as regular text. 

The Open Watcom OS/2 Help Compiler recognizes these commands: 


Command Description 


.* 

.br 

.ce 

.im filename 
.nameit 


Begin a comment. 

Add a line break (start a new line). 

Center a single line of text. 

Imbed (include) filename as if it were text in the current file. 
Define a macro for text substitution. 


4.1 Comment 


Comments are always useful. They allow you to document your documentation! Any text on a line 
beginning with the comment command (.*) is passed over without further processing. 

Don't put a comment within a tag, or between a tag and text that must immediately follow it. 


4.2 br 

There are times when you want to interrupt the normal flow of text and begin a new line. The .br command 
does just that. It must be the only thing on the line. 

Any text following a .br command on the same line will be ignored. 


4.3 ce 

The ce command (.ce) centers the line of text that follows it. 

The single line of text may not contain any other tags, but may contain nameit and entity references. 

4.4 imbed 


The Open Watcom OS/2 Help Compiler allows source files to be embedded in other source files. The 
top-most file is the master file. The imbed command (.im) is followed by the name of the file to include. 
This file is then processed as if it were in-line with the document including it. 
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The ability to include other files makes it possible to break large documents into smaller, more manageable 
logical chunks. 

Note: The embedded files cannot contain the userdoc and euserdoc tags (see "userdoc" on page 

35). Only the master document may contain these tags. 

The embedded files must be in the current directory or in a directory listed in the IPFCIMBED environment 
variable (see "Environment Variables" on page 5). Otherwise, a full path name must be used. 


4.5 nameit 


The nameit command creates a text-substitution macro. The nameit command takes two parameters ( 
symbol =name and text =’string’) that can appear in any order. 

The symbol parameter is the name of the macro. Symbol names were limited to 10 characters (0-9A-Za-z) 
for the original OS/2 help compiler, but Open Watcom OS/2 Help Compiler does not have this restriction. 
Note that the ’&’ character is not part of the symbol name, but is used when referencing the symbol. 

The text parameter defines ’string’ as the text to be substituted on each occurrence of &name. in the text. 

A .nameit symbol is used in the same way as an entity reference. 
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5IPF Tag Reference 


This section acts as a reference, describing how wipfc implements each tag. 


5.1 Overview 


Tags are the heart of IPF markup and come in four flavors: 

1. Tags that appear in the document header. These tags control how the document behaves. 

2. Tags that establish blocks. These tags can contain other tags as well as text. List-blocks and 
tables are special cases in that they can only contain other tags and cannot directly contain text. 

3. Tags that are in-line. These tags can contain text or other in-line tags. 

4. Formatting tags that can appear anywhere, but are usually in-line. 

This diagram classifies each tag and shows which tags can contain which other tags. Tags that are marked 
as containing ’in-line’ can also contain formatting and text. 


Overview 
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Tag Name 
userdoc 
title 
docprof 
ctrldef 
pbutton 
Ctrl 

ectrldef 

fn 

block 

in-line 

efn 

hi 

h2 

h3 

h4 


Classification 

(doc header) 
(doc header) 
(doc header) 
(doc header) 
(doc header) 
(doc header) 
(block) 


(block) 


h5 

h6 


acviewport 

(block) 

artlink 

(in-line) 

link 


eartlink 


artwork 

(in-line) 

caution 

(block) 

in-line 


ecaution 


cgraphic 

(block) 

in-line 


ecgraphic 


color 

(format) 

ddf 

(block) 

dl 

(list-block) 

dthd 

(block) 

in-line 


ddhd 

(block) 

in-line 


dt 

(block) 

in-line 


dd 

(block) 

in-line 


block 


list-block 


edl 


fig 

(block) 

in-line 


figcap 

(block) 

text 


ef ig 


font 

(format) 

hdref 

(in-line) 

hide 

(format) 


block 


in-line 

ehide 

hpl - hp9 (format) 

block 
in-line 
ehpl - ehp9 
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il 

text 

(block) 

i2 

text 

(block) 

icmd 

text 

(block) 

isyn 

text 

(block) 

lines 

in-line 

elines 

(block) 

link 

in-line 

elink 

(in-line) 

lm 

(format) 

note 

in-line 

(block) 

nt 

in-line 

block 

ent 

(block) 

ol 

(list-block 

li 

in-line 

(block) 

IP 

in-line 

list-block 

eol 

(block) 

P 

in-line 

(block) 

parml 

(list-block 

Pt 

in-line 

(block) 

pd 

in-line 

list-block 

eparml 

(block) 

rm 

(format) 

si 

(list-block 

li 

in-line 

(block) 

IP 

in-line 

list-block 

esl 

(block) 

table 

(block) 

row 

(block) 

c 

(block) 

lines 

text 

elines 

in-line 

etable 

(block) 

ul 

(list-block 

li 

in-line 

(block) 

IP 

in-line 

list-block 

(block) 
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eul 

warning (block) 

in-line 
ewarning 

xmp (block) 

in-line 
exmp 
euserdoc 


5.2 Reference 


The Open Watcom OS/2 Help Compiler follows the behavior of the IBM OS/2 Help Compiler as 
documented in the "ipfref.inf" help file. This means that the behavior of the two compilers is very similar 
but not identical, since the IBM compiler allows certain things that the documentation says it should not. 
The entry for each tag that follows describes how the Open Watcom OS/2 Help Compiler treats each tag. 

5.2.1 acviewport 

Description: This tag creates a child window within the current window (page). The contents of this 

child window is controlled by an application via a dynamic link library. 

Attributes: 

dll= ’text’ The name of the dynamic link library containing the code that controls the current viewer 
window. 

objectname= ’text’ 

The entry point (function name) in the dll to be called. Case sensitive. 
objectinfo= ’text’ 

Parameters to be passed to the dll function. 
objectid= ’text’ An identifier to associate the window with the object. 
vpx=measurement 

The x origin of the child window. May be absolute, relative, or dynamic. See "Units of 
Measure" on page 9. 

vpy=measurement 

The y origin of the child window. May be absolute, relative, or dynamic. See "Units of 
Measure" on page 9. 

vpcx=measurement 

The width of the child window. May be absolute, relative, or dynamic. See "Units of 
Measure" on page 9. 

vpcy=measurement 

The height of the child window. May be absolute, relative, or dynamic. See "Units of 
Measure" on page 9. 

Classification: Block 
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May contain: None 

See also: "ddf" on page 19 

5.2.2 artlink 

Description: The artlink tag is used in conjunction with the artwork tag to define rectangular regions of a 

bitmap that each act as a hypergraphic link. 

Note The artlink tag must immediately follow the artwork tag that declares the bit-mapped 

image, or be included in a file referenced from the artwork tag. 

Classification: In-line 

May contain: link 

Closing tag: The closing eartlink is required. 

See also: "artwork" 

5.2.3 artwork 

Description: The artwork tag declares a bit-mapped image to be included in the help file. Windows and 

OS/2 BMP files are supported, wipfc looks for images in the directories pointed to by the 
IPFCARTWORK environment variable (see "Environment Variables" on page 5). 

Attributes: 
name= ’filename.ext’ 

The name of the bitmap image file. This attribute is required. 
align=left I center I right 

Specifies how the image is to be aligned in the current window. Can be one of left, center, 
or right. 

linkfile= ’filename.ext’ 

A direct reference to a file containing artlink/eartlink tags and its associated link tags. This 
allows the image to act as a hyper-graphic link. 

runin This flag places the image within the line of text surrounding it. Otherwise, it acts as a 

block with the text appearing above and below. 

fit This flag causes the image to be scaled to fill the window. Note that this may distort the 

image if the aspect ratio of the window and image differ. 

Classification: In-line 

May contain: None 

See also: "artlink" 
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5.2.4 caution 


Description: 

Closing tag: 
Attributes: 
text= ’message ’ 
Classification: 
May contain: 
See also: 

5.2.5 cgraphic 

Description: 


Closing tag: 
Classification: 
May contain: 
See also: 

5.2.6 color 

Description: 


Displays a locale-specific cautionary message ("Caution: " in the en_US locale) followed 
on the next line by the contents enclosed by the caution tag block. 

The closing ecaution is required. 


Use ’message’ instead of 'CAUTION: ’ as the introductory text. 

Block 

Text, Formatting, In-line, Block (except acviewport, fn, hl-h6). List-block 
"note" on page 30, "nt" on page 30, "warning" on page 35 


Creates a "text graphic." Any text in the cgraphic block will be rendered mono-spaced, and 
spaces and new-lines will be honored. If the text does not fit within the window, it will be 
clipped. Although in-line formatting is allowed, mixing bold and normal fonts will throw 
the spacing off. 

The closing ecgraphic is required. 

Block 

Text, Formatting, In-line 

"artwork" on page 17, "fig" on page 22, "lines" on page 27 


Changes the fore- and background color of the text. The color change remains in effect 
until another color is specified or the next heading tag (hi - h6) is reached. 


Attributes: 

fc=default I black I blue I red I pink I green I cyan I yellow I neutral I brown (a synonym for neutral) I 
darkgray I darkblue I darkred I darkpink I darkgreen I darkcyan I palegray 
This sets the foreground color of the text. 

bc=default I black I blue I red I pink I green I cyan I yellow I neutral I brown (a synonym for neutral) I 
darkgray I darkblue I darkred I darkpink I darkgreen I darkcyan I palegray 
This sets the background color of the text. 

Classification: Formatting 

May contain: Text, Formatting, In-line, Block, List-block 
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5.2.7 Ctrl 

Description: Defines which push-buttons are displayed in the control area, and where. For on-line 

documents, the default push-buttons are: Previous, Search, Print, Index, Contents, Back, 
Forward, Tutorial (if a tutorial is present). These are displayed in the control area of the 
cover window. For help windows, the default buttons are: Previous, Search, Print, Index, 
Tutorial (if a tutorial is present). 

Attributes: 

ctrlid=text Specifies the id by which this control group can be referenced. Alphanumeric. Duplicate 
ids are not allowed. 

controls= ’search print index contents esc back forward custom-id’ 

A space-separated list of the ids of the buttons you want to display, in the order to be 
displayed. If you define your own button (using the pbutton tag), use the id from that tag as 
the custom-id. 

page Put the buttons in the control area of a page. 

coverpage Put the buttons in the control area of the cover (main) page. 

Conditions The Ctrl tag must be enclosed in a ctrldef block, and must follow all pbutton tags 

Classification: Document Header 

May contain: None 

See also: "ctrldef", "pbutton" on page 32 

5.2.8 ctrldef 

Description: Defines a control area and its contents. It must follow the docprof tag and precede the first 

hi tag. 

Closing tag: The closing ectrldef is required. 

Classification: Document Header 

May contain: pbutton, Ctrl 

See also: "docprof" on page 21, "ctrl", "pbutton" on page 32 

5.2.9 ddf 

Description: Display dynamically formatted text in an application-controlled window. 

Attributes: 

res=number The resource id number. Must be between 1 and 64000. 
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Classification: Block 
May contain: None 
See also: "acviewport" on page 16 

5.2.10 dl 

Description: Begin a definition list (a sequence of terms and their definitions). 

Closing tag: The closing edl is required. 

Attributes: 

compact Omit inserting a blank line between each term-description pair. 

tsize=number Sets the width of the "term " column (the default is 10). 
break=none I fit I all 

Controls how a description follows a term. If break is set to "none", descriptions are on the 
same line as the term, even if the length of the term exceeds "tsize" characters. If break is 
set to "fit", descriptions are placed on the next line only if the length of the term exceeds 
"tsize" characters. If break is set to "all" descriptions are always placed on the next line. 

Conditions: The dthd and ddhd tags must occur before any dt and dd tags. Multiple consecutive dt tags 

are allowed (synonyms), but only one dd tag is allowed for each set of dt tags. 

Classification: List-block 

May contain: "dthd", "ddhd", "dt" on page 21, "dd" on page 21, Block, List-block 
See also: "ol" on page 31, "parml" on page 31, "ul" on page 35, "si" on page 33 

5.2.10.1 dthd 

Description: 

Conditions: 

Classification 
May contain: 

See also: 

5.2.10.2 ddhd 

Description: The definition header for a definition list. It acts as a column title for all definition 

elements. 

Conditions: Must appear after a dthd tag and before the first dt or dd tag. 


The term header for a definition list. It acts as a column title for all term elements. 
Must appear before the first ddhd, dt, or dd tag. 

Block 

Text, Formatting, In-line 
"ddhd" 
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Classification: Block 

May contain: Text, Formatting, In-line 

See also: "dthd" on page 20 

5.2.10.3 dt 

Description: A term to be defined. 

Classification: Block 

May contain: Text, Formatting, In-line 

See also: "dd" 

5.2.10.4 dd 

Description: A definition of a term. 

Classification: Block 

May contain: Text, Formatting, In-line 

See also: "dt" 

5.2.11 docprof 

Description: Describes the document profile, which includes which (if any ) dynamic link librarys to 

load, what level headers trigger new pages, where controls are displayed. The tag must 
follow the userdoc tag and (if present) the title tag. 

Attributes: 

toc=numbers Controls which heading levels are included in the table of contents. For example, ’ 123’ 

(the default) places headings defined by the hi, h2, and h3 tags in the table of contents. 

The numbers must be consecutive, beginning with 1. 

dll= ’text’ Specifies a dll to load. This dll can act as a communication object and alter the behavior of 
the viewer. 

objectname= text’ 

The dll entry point. 

objectinfo= ’text’ 

Parameters to pass to the dll. 

ctrlarea=none I coverpage I page I both 

Specifies where the control area that contains push buttons is located. If ’page’ is specified, 
place the control area on the text window. If ’coverpage’ is specified, place the control 
area on the cover page. If ’both' is specified, place the control are in both locations. If 
’none’ is specified, suppress the control area. 
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Classification: 
May contain: 

5.2.12 fig 

Description: 

Closing tag: 
Classification: 
May contain: 
See also: 

5.2.13 figcap 

Description: 

Classification: 
May contain: 
See also: 

5.2.14 font 

Description: 


Document Header 
None 


A block of text representing a figure. A proportional font is used, but spaces and line 
breaks are honored so that the text is layed out as entered. If the text exceeds the current 
window dimensions, it will be clipped. 

The closing efig is required. 

Block 

Text, Formatting, In-line, figcap 

"cgraphic" on page 18, "figcap", "lines" on page 27 


Specifies the title for a figure. This tag must occur in a fig/efig block, either at the 
beginning or end of the figure. The caption text must be on the same line as the tag, or on 
the next line. 

Block 

Text 

"fig" 


Change the font face, size, or encoding for the text in the page (fonts reset at the next 
header defining a new page). 


Attributes: 
facename= ’text’ 

Sets the name of the font to use. If set to ’default’, resets the font to the default face and 
size. This attribute is required. 

size=HxW Sets the height and width of the font. If either value is 0, resets the font to the default face 
and size. This attribute is required. The ’x’ separating the numbers is required. 

codepage=n umber 

Sets the encoding of the displayed text. The value is a 3 digit number. 

Classification: Formatting 

May contain: Text, Formatting, In-line, Block, List-block 
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5.2.15 fn 

Description: Defines a pop-up window that acts as a footnote. The window is activated when the user 

clicks a link. 

Closing tag: The closing efn is required. 

Attributes: 

id=text Specifies a unique alphanumeric identifier used as the target of a link tag. This attribute is 

required. 

Conditions: The index tags (il, i2, icmd, isyn) are not allowed. Footnotes cannot be nested within other 

footnotes, nor can they contain headings (hi - h6). The link to a footnote cannot appear in 
a child window. The text of footnotes is not searchable. 

Classification: Block 

May contain: Text, Formatting, Block (except fn, hi - h6). List-block 

See also: "link" on page 28 

5.2.16 hi -h6 

Description: A heading tag defines a new page (window), provided the heading level is less than the 

maximum value set using the docprof tag. The text of the header immediately follows the 
close of the tag, either on the same or the next line. The attributes of the heading tag can be 
used to set the properties of the window that displays the page of information. Heading 
tags must appear in consecutive ascending (but not descending) order. That is, you cannot 
go from hi to h3 without an intervening h2, but you can go from h3 to hi. 

Attributes: 

res=number 


id=text 
name=text 
global 
tutorial=text 
x=measurement 

The x origin of the window in the parent window. See "Units of Measure" on page 9. 

y=measurement 

The y origin of the window in the parent window. See "Units of Measure" on page 9. 
width=measurement 

The width of the window in the parent window. See "Units of Measure" on page 9. 


Specify the resource id of the header. It must be in the range of 1 to 64000. This attribute 
is required for HLP files. 

The id of the header. Alphanumeric. 

The name of the header. Alphanumeric. 

If set, this page can be linked to by an external HLP or INF file. 

Specifies the file name of the tutorial, and adds the tutorial button to the control area. 
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height=measurement 

The height of the window in the parent window. See "Units of Measure" on page 9. 

Note: You cannot mix absolute units with dynamic or relative units when specifying x and width, 

or y and height. 

group=number The group number of the window (1 to 64000). All pages in the same group are displayed 
in the same window, one replacing the other. 

viewport Force the opening of a new window for this page. 

clear Close any open windows before opening a new one to display this page. 

titlebar=yes I sysmenu I minmax I both I none 

Set what contents appear in the title bar. The default is ’both'. Useful for secondary 
windows. 

scroll=horizontal I vertical I both I none (default: both) 

Set which scroll bars appear. The default is 'both'. Useful for secondary windows. 

rules=border I sizeborder I none 

Set the type of border on the window. The default is 'sizeborder'. Useful for secondary 
windows. 

nosearch When searching, do not jump to this secondary window. Instead, jump to the parent 
window that contains it. 

noprint Do not print the contents of a secondary window separately. Print it as part of the parent 

window contents. 

hide Do not include this header in the table of contents. 

toc=numbers Controls which heading levels are included in the table of contents. For example, ’ 123’ 
(the default) places headings defined by the hi, h2, and h3 tags in the table of contents. 

The numbers must be consecutive, beginning with 1. Valid until the end of the file or until 
the next header with a toe attribute. 


ctrlareci=page\none 

Specifies where the control area that contains push buttons is located. If 'page’ is specified, 
place the control area on the text window. If ’none’ is specified, suppress the control area 
on this page. This overrides the value set in the docprof tag. 

ctrlrefid=text An alphanumeric identifier of the set of controls you wish to display. 

Classification: Block 


May contain: 


Text, Formatting, In-line, Block, List-block 


See also: "fn" on page 23 
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5.2.17 hdref 


Description: 

Attributes: 

res=number 

refid=text 

Classification: 

May contain: 

See also: 

5.2.18 hide 

Description: 

Closing tag: 
Attributes: 
key= ’text’ 


Conditions: 

Classification. 
May contain: 

5.2.19 hpl -hp9 

Description: 

Closing tag: 
Conditions 


Classification: 


Link to a heading. The text of the link is "Reference". 

The resource id of the header tag. 

The id of the header tag. Alphanumeric. 

In-line 

None 

"link" on page 28 


Hide a section of information unless the IPF_KEYS environment variable contains the 
correct key. 

The closing ehide is required. 


The key that will unhide the enclosed information. Multiple keys can be specified by 
enclosing each key in single quotes then concatenating them with the plus sign. So, 

’ key 1’+' key2 ’+... wipfc will also accept ’ key 1 +key2+... ’ 

You cannot nest hide tags within each other. You cannot include a header tag with the ’res’ 
attribute set (in other words, you cannot jump to hidden material). Note that the Open 
Watcom OS/2 Help Compiler does not check for this error. 

Formatting 

Text, Formatting, In-line, Block, List-block 


Change the style of the text. The style can be a combination of bold, italic, or underlined, 
or a color change, hpl is italic. hp2 is bold. hp3 is bold italic. hp4 is blue. hp5 is 
underlined. hp6 is underlined italic. hp7 is underlined bold. hp8 is red. hp9 is pink. 

The closing matching tag is required. 

Highlighting tags cannot nest. Note that the Open Watcom OS/2 Help Compiler allows this 
as an extension, but still issues a warning. In this case the opening and closing tags must 
match at each nesting level. Also note that nested highlighting tags are not additive: an 
hpl (italic) inside hp2 (bold) does not make an hp3 (bold italic). 

Formatting 
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May contain: Text, Formatting, In-line, Block, List-block 

5.2.20 il 

Description: Add a primary entry to the index. The text for the entry must be on the same line as the tag 

and cannot contain other tags. 

Attributes: 

id=text A cross-reference for use by a secondary index (i2) tag. 

global For HLP files, allows this entry to also appear in the global index. 

roots= ’text’ Specifies a space separated list of root words (as defined by isyn) that act as index entries to 

specific topics. 

sortkey= ’key-text ’. index-text 

Specify a string used to sort this entry in the index, and a string to use in its place. In other 
words, place index-text where key-text would sort in index. 

Conditions Cannot appear in a footnote (fn/efn block). 

Classification: Block 

May contain: Text 

See also: "i2", "icmd" on page 27, "isyn" on page 27 

5.2.2112 

Description: Add a secondary entry to the index. The text for the entry must be on the same line as the 

tag and cannot contain other tags. 

Attributes: 

refid=text The id of the primary index entry to which this belongs. 
global For HLP files, allows this entry to also appear in the global index. 

sortkey= ’key-text ’. index-text 

Specify a string used to sort this entry in the index, and a string to use in its place. In other 
words, place index-text where key-text would sort in index. 

Conditions Cannot appear in a fn/efn footnote. If the global flag is set for the il tag, it must be set for 
the i2 tag. 

Classification: Block 
May contain: Text 
See also: "il" 
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5.2.22 icmd 


Description: 

Conditions 
Classification: 
May contain: 
See also: 

5.2.23 isyn 

Description: 


Attributes: 
root=text 

Classification: 
May contain: 
See also: 

5.2.24 li 

Description: 
Classification: 
May contain: 
See also: 

5.2.25 lines 

Description: 

Closing tag: 


Show that this page describes a command. The text for the command must be on the same 
line as the tag and cannot contain other tags. If the page contains information on more than 
one command, there should be one icmd tag for each documented command. 

The icmd tag must directly follow a heading tag, or other index tags (il, i2 or isyn). 

Block 

Text 

"il" on page 26, "i2" on page 26 


Create a list of synonyms or variations of a word in a primary index tag (il). If the user 
enters one of the words in the isyn list, the corresponding il index referencing the root 
word is returned. The synonyms themselves do not appear in the index. The isyn tag can 
be placed on any page that contains related il tags. The list of synonyms must be on the 
same line as the tag and cannot contain other tags. 


The root word for which the synonyms apply. This word will also appear in the ’roots’ 
attribute of the il tag. 

Block 

Text 

"il" on page 26 


Begins a list item. This tag is only valid inside a simple, ordered, or unordered lists. 
Block 

Text, Formatting, In-line, Block, List-block 
"ol" on page 31, "si" on page 33, "id" on page 35 


Renders the enclosed block in a proportional font, but honoring white space and line breaks 
to preserve the formatting of the text as it was entered. The text can be left or right aligned, 
or centered. 

The closing elines is required. 
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Attributes: 

align=left I center I right 

Left, center, or right align the block of text in the window. 

Classification: Block 

May contain: Text, Formatting, In-line 

See also: "ce" on page 11, "fig" on page 22, "xmp" on page 36 

5.2.26 link 

Description: A link to additional information. Activating the link may jump to a different location in the 

same or a different document, open a footnote, launch an application, or send a notification 
to another running process. 

Closing tag: The closing elink is required. Unless the link is contained in an artlink tag, or if reftype is 
’inform’. 

Attributes: 

reftype=hd \fn I launch I inform 

If reftype is ’hd’, then it links to a heading and the refid attribute must be specified. If the 
heading is in an external file, the database must also be set and the heading must have its 
’global’ attribute set. If reftype is ’fn’, the link is to a footnote and the ’refid’ attribute 
must be set. Note that a split window cannot contain a link to a footnote. If reftype is 
’launch’, the link starts the external program specified by the ’object’ attribute with 
parameters specified in the ’data’ attribute. If reftype is ’inform’, the value of the ’res’ 
attribute is sent to the application. 

res=number The resource id of the header tag. 

refid=text The id of the header. Alphanumeric. 

database = ’text’ 

The name of the external INF or HLP file. 
object= ’text’ The name of a program to execute. 
data- ’text’ The parameters to pass to program being started. 

auto Automatically trigger this link when the page that contains it is displayed. Footnotes 

cannot be opened automatically. The link tag must follow a heading tag before other tags 
and text. 

viewport Open a secondary window when the link that refers to it is opened. 

dependent Make the automatically opened window close when the secondary window that opened it is 

closed. 
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split Open a secondary window when the link is activated. Note that the primary window can 

only contain links to secondary windows. Each of the secondary windows must have a 
different group number if they are to be displayed at the same time. 

child Open the page being linked to as a child of the current page, clipped to fit within the 

current page. The child is always on top, is closed when the parent is closed, resized when 
the parent’s size is changed. If only the child is minimized, its icon appears within the 
parent’s border. 

group=number The group number of the window (1 to 64000). All pages in the same group are displayed 
in the same window, one replacing the other. 

vpx=measurement 

The x origin of the window. See "Units of Measure" on page 9. Not valid for footnotes. 
vpy=measurement 

The y origin of the window. See "Units of Measure" on page 9. Not valid for footnotes. 
vpcx=measurement 

The width of the window. Absolute or dynamic units only. See "Units of Measure" on 
page 9. Not valid for footnotes. 

vpcy=measurement 

The height of the window. Absolute or dynamic units only. See "Units of Measure" on 
page 9. Not valid for footnotes. 

titlebar=yes\sysmenu I minmax\both I none 

Set what contents appear in the title bar. The default is ’both'. Useful for secondary 
windows. 

scroll=horizontal\vertical\both\none 

Set which scroll bars appear. The default is ’both'. Useful for secondary windows. 
rules=border\sizeborder\none 

Set the type of border on the window. The default is ’ sizeborder'. Useful for secondary 
windows. 

The x origin of the active area of the graphic. Valid only if the link is in an artlink. 

The y origin of the active area of the graphic. Valid only if the link is in an artlink. 

The width of the active area of the graphic. Valid only if the link is in an artlink. 

The height of the active area of the graphic. Valid only if the link is in an artlink. 

If the link is to contain an image, the link must be enclosed in an artlink tag block. 

In-line 

Text, Formatting, In-line 
"artlink" on page 17, "hdref" on page 25 


x=number 

y=number 

cx=number 

cy=number 

Note: 

Classification: 
May contain: 
See also: 
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5.2.271m 


Description: Sets the left margin. The margin remains in effect until it is reset or until the end of the 

current page. 

Attributes: 

margin=number 

The number of character spaces. If the tag appears more than ’margin' character spaces 
into a line of text, the margin becomes effective on the next line. 

Classification: Formatting 

May contain: Text, Formatting, In-line, Block, List-block 
See also: "rm" on page 33 


5.2.28 Ip 


Description: 

Classification: 
May contain: 
See also: 


Add a paragraph to a list. The resulting block of text is indented to the same level as the 
list text, but is not numbered or bulleted. 

Block 

Text, Formatting, In-line, Block, List-block 
"p" on page 31 


5.2.29 note 

Description: Begins a note. The text that follows the tag (up to the next block-class tag) is used as the 

text of the note. This text appears after the local-specific phrase ("Note: " in the en_US 
locale) and on the same line. 

Attributes: 


text= ’text ’ 
Classification: 
May contain: 
See also: 


Substitute 'text' for the default "Note: " phrase. 
Block 

Text, Formatting, In-line 

"caution" on page 18, "nt", "warning" on page 35 


5.2.30 nt 

Description: Begins a multi-paragraph note. All of the text in the note left aligns with the first word 

after the message text. The text begins with a local-specific phrase ("Note: " in the en_US 
locale). 
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Closing tag: 
Attributes: 
text= ’text’ 
Classification: 
May contain: 
See also: 

5.2.31 ol 

Description: 

Closing tag: 
Attributes: 
compact 
verycompact 

Classification: 
May contain: 
See also: 

5.2.32 p 

Description: 

Classification: 
May contain: 

5.2.33 par ml 

Description: 


Attributes: 

tsize=number 


The closing ent is required. 

Substitute ’text' for the default "Note: " phrase. 

Block 

Text, Formatting, In-line, Block, List-block 

"caution" on page 18, "note" on page 30, "warning" on page 35 


An ordered list (numbers precede each list item). List items begin with the li tag and can be 
continued in another paragraph (without numbering) by using the lp tag. 

The closing eol is required. 

Do not put blank lines between each list item. 

Do not put blank lines between each list item, and do not put blank lines before or after the 
list. An Open Watcom OS/2 Help Compiler extension. 

List-block 

Text, Formatting, In-line, Block, List-block 

"li" on page 27, "lp" on page 30, "si" on page 33, "ul" on page 35 


A paragraph. Each paragraph is preceded by a blank line, and is terminated by the next 
block-level tag. Text doesn’t have to be in a paragraph, but it helps. 

Block 

Text, Formatting, In-line 


A two-column list of parameters and their definitions, similar to a definition list (dl tag). A 
pt tag defines the term, and a pd tag defines a definition of the term. Each pt tag must have 
a pd tag. Multiple consecutive pt tags are allowed (synonyms), but only one pd tag is 
allowed for each set of pt tags. Other lists and blocks may be nested in a parameter table. 


The width of the term column. The default is 10. 
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break=all I fit I none 

If break is ’all' then each description is on a line below the term. This is the default. If 
break is ’fit’ then the description is on the same line as the term provided that the width of 
the term is less than tsize characters. If break is ’none’ then the description is on the same 
line as the term. 

compact Do not add blank lines between each term/description pair. 

Classification: List-block 
May contain: "pt", "pd" 

See also: "dl" on page 20 

5.2.33.1 pt 

Description: The parameter to be described. Multiple pt tags (synonyms) may described by a single pd 

tag. 

Classification: List-block 

May contain: Text, Formatting, In-line, "pd", pt 

5.2.33.2 pd 

Description: The description of the parameter. 

Classification: List-block 

May contain: Text, Formatting, In-line 

See also: "pt" 

5.2.34 pbutton 

Description: Defines a custom (author-defined) push button. 

Attributes: 

id=text An alphanumeric identifier that will be referenced by the Ctrl tag when using the button. 

res=number The resource identifier for the button (returned by window messages). Must be greater 

256; values of 256 or less are reserved. 

text= ’text’ The button text. May include spaces. May not include entity references. Must not conflict 
with any pre-defined buttons. 

Note: All pbutton tags must appear inside a ctrldef block and before any Ctrl tags. 

Classification: Document Header 
May contain: None 
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See also: "ctrl" on page 19, "ctrldef" on page 19 

5.2.35 rm 

Description: Sets the right margin. The margin remains in effect until it is reset or until the end of the 

current page. 

Attributes: 

margin=number 

The number of character spaces. If the tag appears more than ’margin' character spaces 
into a line of text, the margin becomes effective on the next line. 

Classification: Formatting 

May contain: Text, Formatting, In-line, Block, List-block 
See also: "lm" on page 30 

5.2.36 si 

Description: A simple list (neither numbered, nor bulleted). List items begin with the li tag and can be 

continued in another paragraph ( without numbering) by using the lp tag. 

Closing tag: The closing esl is required. 

Attributes: 

compact Do not put blank lines between each list item. 

verycompact Do not put blank lines between each list item, and do not put blank lines before or after the 
list. An Open Watcom OS/2 Help Compiler extension. 

Classification: List-block 

May contain: Text, Formatting, In-line, Block, List-block 

See also: "li" on page 27, "lp" on page 30, "ol" on page 31, "ul" on page 35 

5.2.37 table 

Description: Begins a table. Tables use a mono-spaced font to ensure that the column width are 

respected. If you change the font (using the font tag) or change make the font bold, the 
spacing will be thrown off. 

Attributes: 

co!s= ’number number... ’ 

Specifies both the width of each column ('number') and the number of columns (the 
number of ’number’s). 


Reference 33 




The Open Watcom OS/2 Help Compiler 


rules=both I horiz I vert I none 

Specify whether the table will have horizontal or vertical rules. If the rule is not drawn, 
blank space appears in it place. The default is ’both’. 

frame=rule\box\none 

Specifies the frame around the table. If no frame is drawn, blank space appears in its place. 
The default is ’box’. 

Classification: Block 

May contain: "row" 

5.2.37.1 row 

Description: A table row. If the number of cells supplied for a row is greater or less than the number 

specified in the table tag, a warning is generated. 

Classification: Block 

May contain: "c" 

5.2.37.2 c 

Description: A table cell. If the width of the text exceeds the width of the cell, the text is wrapped. If 

the length of a single word exceeds the width of the cell, that word will be truncated to the 
width of the cell. 

Classification: Block 

May contain: Text, "color" on page 18, "font" on page 22, "hpl - hp9" on page 25, "lines" on page 27, 
"link" on page 28 

Note: Using the lines tag does not change the font to a proportional spaced font. It simply makes 

the whitespace and new lines significant so that the cell is formatted as entered. All 
attributes for the lines tag are ignored. 

5.2.38 title 

Description: Sets the title of the help document. The maximum length of the title is 47 characters 

(including spaces and blanks) and is displayed in a single line. Other than text, the title 
may contain entity references and nameit expansions. 

Note: The title tag may only appear in the document header. It cannot appear on individual pages 

because it applies to the document as a whole. 

Classification: Document Header 

May contain: Text 
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5.2.39 ul 

Description: 

Closing tag: 
Attributes: 
compact 
verycompact 

Classification: 
May contain: 
See also: 

5.2.40 userdoc 

Description: 

Closing tag: 
Classification: 
May contain: 

5.2.41 warning 

Description: 

Closing tag: 
Attributes: 
text= ’message ’ 
Classification: 
May contain: 
See also: 


An unordered list (bullets precede each list item). List items begin with the li tag and can 
be continued in another paragraph (without numbering) by using the Ip tag. 

The closing eul is required. 


Do not put blank lines between each list item. 

Do not put blank lines between each list item, and do not put blank lines before or after the 
list. An Open Watcom OS/2 Help Compiler extension. 

List-block 

Text, Formatting, In-line, Block, List-block 

"li" on page 27, "lp" on page 30, "ol" on page 31, "si" on page 33 


Delimit the compilable source text, userdoc must be the first tag in the file. Only 
comments may precede the userdoc tag. Only comments may follow the terminating 
euserdoc tag. 

The closing euserdoc is required. 

Block 

Everything 


Displays a locale-specific warning message ("Warning: " in the en_US locale) followed 
immediately by the contents enclosed by the warning tag block. 

The closing ewaming is required. 


Use ’message’ instead of ’Warning: ’ as the introductory text. 

Block 

Text, Formatting, In-line, Block (except acviewport, fn, hl-h6). List-block 
"caution" on page 18, "note" on page 30, "nt" on page 30 


Reference 


35 




The Open Watcom OS/2 Help Compiler 


5.2.42 xmp 


Description: 

Closing tag: 
Classification: 
May contain: 
See also: 


Renders the enclosed text in a monospaced font, honoring whitespace and line breaks. In 
other words, exactly as it is entered. If the width of the text exceeds the width of the 
window, the text is clipped, not wrapped. 

The closing exmp is required. 

Block 

Text, Formatting, In-line 

"cgraphic" on page 18, "lines" on page 27 
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6 Error Messages 


The Open Watcom OS/2 Help Compiler generates four kinds of diagnostic messages: Errors and three 
levels of warnings. Despite their name, warnings are really errors and indicate that wipfc has produced a 
file that is probably not exactly the way you wanted. 


6.1 Errors 


Errors are always fatal and cause Open Watcom OS/2 Help Compiler to stop immediately. 

"The length of the file path is too long" 

The maximum length of the file path depends on the operating system. You may need to 
re-arrange the project’s layout on disk. 

"Cannot open file " 

A source file cannot be opened, usually because it doesn't exist. Check the spelling of the 
file name. 

"Cannot open image file" 

A image file cannot be opened, usually because it doesn’t exist. Check the spelling of the 
file name. 

"Cannot read from file" 

For some reason, reading the file has failed. 

"Cannot write to file" 

For some reason, writing to the file has failed. The disk might be full. 

"Unexpected end of file " 

The source file has unexpectedly ended. This can occur if you have forgotten the euserdoc 
tag. 

"Text conversion error" 

wipfc uses wide characters internally. All text is converted from multi-byte characters to 
wide characters when read, and back to multi-byte characters when written. If a character 
cannot be converted successfully, this error is generated. 


"Syntax error" 

A syntax error has occurred. Usually, this is because an end-of-tag delimiter is missing. 
"Invalid country code or codepage" 

The appropriate file of entity references cannot be found or cannot be read. Usually, this is 
because the WIPFC environment variable is pointing to the wrong place. 

"Invalid language code" 

The appropriate nls file cannot be found or cannot be read. Usually, this is because the 
WIPFC environment variable is pointing to the wrong place. 
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"Missing userdoc or euserdoc" 

The document is not correctly formed. The userdoc and euserdoc tags are required. 

"Too many unique words—the document is too big" 

A document can contain a maximum of 64000 unique words. 

"The document has no words" 

A document cannot be empty. Add some text. 

"The document has too many pages" 

A document cannot have more than 65535 pages. 

"The document has too many index or icmd entries" 

The document cannot have more than 65535 index entries. 

"The document has no visible table of contents entries" 

At least one of the pages must be visible. Don't hide them all. 

6.2 Level 1 Warnings 

Level 1 warnings are the most serious. Unless they are corrected, your help file is not likely to contain 
information presented as you intended. 

"This command is not defined" 

Commands begin with a in the first column of a row of text. You probably have a line 
beginning with a period. 

"This tag is not defined" 

You are trying to use a tag that wipfc does not recognize. Try replacing the character 
with an entity reference. 

"This attribute is not defined for this tag" 

Check the spelling of the attribute, or delete it. 

"Attributes are not allowed for this tag—probably missing. to end the tag" 

This tag has no attributes. 

"The tag, word, or command is not allowed in this context" 

This is usually because the enclosing tag can only contain specific tags or no tags at all. 

"Syntax error in tag" 

There is something wrong within the tag. 

"Ignoring text before the 111 tag" 

Text and most tags cannot appear before the first heading tag. 

"Ignoring text after the euserdoc tag" 

Text and tags cannot appear after the terminating document tag. 

"Heading levels are not in consecutive order" 

The offending heading tag is more than one level greater than the heading that contains it. 
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"The required refid attribute is missing" 

A refid or res attribute is required to specify the target of a link or secondary index, but not 
present. 

"Unable to find the resource identifier for this reference" 

A non-existent resource id is being referenced. 

"The required resource identifier is missing" 

A ddf tag is missing a valid resource identifier. 

"Unable to find the id or name for this reference" 

The referenced id or name does not exist. 

"The required id for this footnote is missing" 

A footnote tag is missing a required id. 

"Ignoring a list item tag that is not part of a list" 

List elements can only appear within a list. 

"The required end the list is missing" 

The list has not been closed. 

"A ddlid tag must be preceded by a dtlid tag" 

Definition list header tags must appear in the correct order. 

"A dd tag must be preceded by a dt tag" 

Definition list elements must appear in the correct order. 

"Too many external files have been linked to" 

A maximum of 256 external files can be linked. 

"The required graphics file name is not present" 

You have to specify the name of the bit-mapped graphics file if you expect wipfc to find it. 

"wipfc does not support this graphics file format" 

Only Windows and OS/2 bmp files are supported by wipfc. 

"Cannot hide a header with the res attribute set" 

Either don’t hide the header, or remove the res attribute so it can’t be a link target. 

"No valid cols have been specified" 

A table needs its column widths specified in advance. 

"The total width of the table is >250 characters" 

The total width of a table (including borders) cannot exceed 250 characters. 

"Ignoring text before c tag" 

Text in a table must be inside of a cell. Put it after the c tag. 

"Ignoring invalid tag in table cell" 

Table cells cannot contain other block-level tags. 

"Text in this table column is too long, truncating" 

If a single word is longer than the table cell is wide, it is truncated. 
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"Ignoring extra table columns in this row" 

You have more c tags in the row than you have columns specified in the table tag. 

"Not enough columns have been specified for this row" 

You have fewer c tags in the row than you have columns specified in the table tag. 

"The required elink tag is missing, but has been appended to this column" 

You forgot to close the link, so wipfc has added an elink tag at the end of the cell. 

"This page has too many elements (words, punctuation, etc.) " 

The maximum number of text elements in a single page is 64000. 


6.3 Level 2 Warnings 

Level 2 warnings are less serious. 

"Invalid or missing attribute value" 

A required attribute is either missing, or has an invalid value. 

"Invalid symbol (entity reference or .nameit expansion)" 

The entity reference or nameit macro is not defined. Check the spelling. 

"Invalid tag nesting" 

Text hiding tags and highlighting tags cannot nest with themselves. 

"Footnote cannot be indexed" 

Footnotes cannot have ini, in2, or icmd tags. 

"Too many (> 14) fonts have been used" 

You need to user fewer fonts. 

"Title or index text is too long" 

The length of title text is limited to 47 characters; index text, to 255 characters. 

"Subindexes of a global index must be global, too" 

If an index is global, all of its subindexes must be global, too. Set the ’global’ flag. 

"An index entry requires text" 

Text must follow an ini, in2, or icmd tag. 


6.4 Level 3 Warnings 

Level 3 warnings are less serious still. 

"This id or name is already in use" 

If the id or name is the target of a link tag, you’re not likely to get to the right place. 
"This res number is already in use" 

If the resource id is the target of a link tag, you’re not likely to get to the right place. 
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"Redefinition of.nameit symbol" 

A nameit symbol can only be defined once. It cannot be redefined. 

"This synonym set is already defined" 

A synonym set can only be defined once. 

"This synonym set is not defined" 

A synonym set must be defined before it can be used. 

"Control group references an undefined button " 

A push button definition is missing. 

"Cannot mix dynamic and absolute units" 

Absolute and relative units cannot be used at the same time. 

"Footnotes cannot be opened automatically" 

Footnotes are special. 

"Footnote cannot be opened from a split window" 

Footnotes are special. 
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7 IPF Symbols 


Special symbols can be incorporated into OS/2 help file by using entity references in the form of 
&symbol-name. Each entity reference begins with the ’&’ character and ends with the character. New 
symbols can be created by using the nameit command (see "nameit" on page 12), but each language 
encoding has a pre-defined set of symbols associated with it. For the en_US locale (and other locales using 
the IBM 850 code page), the predefined symbols are as follows (symbols that cannot appear in this 
document are left blank): 
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Char 

Hex 

value 

Unicode 
code point 

Entity 

name 

Description 


0x10 

\u25BA 

rarrow 

Black right-pointing pointer 


0x10 

\u25BA 

rahead 

Black right-pointing pointer 


0x11 

\u25C4 

lahead 

Black left-pointing pointer 


0x11 

\u25C4 

larrow 

Black left-pointing pointer 


0x18 

\u25B2 

uarrow 

Black up-pointing triangle 


0x19 

\u25BC 

darrow 

Black down-pointing triangle 


0x20 

\u0020 

rbl 

Required blank 

1 

0x21 

\u0021 

xclm 

Exclamation mark 

1 

0x21 

\u0021 

xclam 

Exclamation mark 

If 

0x22 

\u201D 

odq 

Left double quotation mark 

I! 

0x22 

\u201C 

cdq 

Right double quotation mark 

# 

0x23 

\u0023 

numsign 

Number sign 

$ 

0x24 

\u0024 

dollar 

Dollar sign 

o, 

o 

0x25 

\u0025 

percent 

Percent sign 

& 

0x26 

\u002 6 

amp 

Ampersand 

r 

0x27 

\u0027 

apos 

Apostrophe 

\ 

0x60 

\u2018 

osq 

Left single quotation mark 

r 

0x27 

\u2019 

esq 

right single quotation mark 

\ 

0x60 

\u0060 

grave 

Grave accent 

( 

0x28 

\u002 8 

lpar 

Left parenthesis 

( 

0x28 

\u0028 

lparen 

Left parenthesis 

) 

0x29 

\u002 9 

rpar 

Right parenthesis 

) 

0x29 

\u002 9 

rparen 

right parenthesis 

★ 

0x2A 

\u002A 

asterisk 

Asterisk 

+ 

0x2B 

\u002B 

plus 

Plus sign 

r 

0x2C 

\u002C 

comma 

Comma 

- 

0x2D 

\u002D 

dash 

Hyphen-minus 

- 

0x2D 

\u002D 

emdash 

Hyphen-minus 

- 

0x2D 

\u002D 

mdash 

Hyphen-minus 

- 

0x2D 

\u002D 

endash 

Hyphen-minus 

- 

0x2D 

\u002D 

ndash 

Hyphen-minus 

- 

0x2D 

\u002D 

hyphen 

Hyphen-minus 

- 

0x2D 

\u002D 

minus 

Hyphen-minus 

. 

0x2E 

\u002E 

period 

Full stop 

. 

0x2E 

\u002E 

per 

Full stop 

/ 

0x2F 

\u002F 

slash 

Solidus 

/ 

0x2F 

\u002F 

sir 

Solidus 

l 

0x3A 

\u003A 

colon 

Colon 

i 

0x3B 

\u003B 

semi 

Semicolon 

< 

0x3C 

\u003C 

it 

Less-than sign 

< 

0x3C 

\u003C 

ltsym 

Less-than sign 

= 

0x3D 

\u003D 

eq 

Equals sign 

= 

0x3D 

\u003D 

equals 

Equals sign 

= 

0x3D 

\u003D 

eqsym 

Equals sign 

> 

0x3E 

\u003E 

gt 

Greater-than sign 

> 

0x3E 

\u003E 

gtsym 

Greater-than sign 

@ 

0x40 

\u0040 

atsign 

Commercial at 

[ 

0x5B 

\u005B 

lbracket 

Left square bracket 

[ 

0x5B 

\u005B 

lbrk 

Left square bracket 

\ 

0x5C 

\u005C 

bslash 

Reverse solidus 

\ 

0x5C 

\u005C 

bsl 

Reverse solidus 

] 

0x5D 

\u005D 

rbracket 

Right square bracket 

] 

0x5D 

\u005D 

rbrk 

Right square bracket 

A 

0x5E 

\u005E 

caret 

Circumflex accent 
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A 0x5E 

\u005E 

and 

Circumflex , 

accent 




0x5F 

\u005F 

us 

Low line 




\ 

( 0x7B 

\u007B 

lbrace 

Left curly bracket 



\ 

I” 0x7B 

\u007B 

lbrc 

Left curly bracket 




0x7C 

\u00A6 

splitvbar 

Split 

vertical bar 




0x7C 

\u007C 

vbar 

Vertical bar 




0x7C 

\u007C 

lor 

Vertical bar 



} 

J 

\ 0x7D 

\u007D 

rbrace 

Right 

curly 

bracket 



1 

J 

\ 0x7D 

\u007D 

rbrc 

Right 

curly 

bracket 




0x7E 

\u007E 

tilde 

Tilde 






0x7E 

\u007E 

similar 

Tilde 






0x7F 

\u2302 

house 

House 






0x80 

\u00C7 

Cc 

Latin 

capital letter 

C with 

cedilla 









0x81 

XuOOFC 

ue 

Latin 

small 

letter 

U 

with 

diaeresis 









0x82 

\u00E9 

ea 

Latin 

small 

letter 

E 

with 

acute 









0x83 

\u00E2 

ac 

Latin 

small 

letter 

A 

with 

circumflex 









0x84 

\u00E4 

ae 

Latin 

small 

letter 

A 

with 

diaeresis 









0x85 

\u00E0 

ag 

Latin 

small 

letter 

A 

with 

grave 









0x86 

\u00E5 

ao 

Latin 

small 

letter 

A 

with 

ring above 









0x87 

\u00E7 

cc 

Latin 

small 

letter 

C 

with 

cedilla 









0x88 

\u00EA 

ec 

Latin 

small 

letter 

E 

with 

circumflex 









0x89 

\u00EB 

ee 

Latin 

small 

letter 

E 

with 

diaeresis 









0x8A 

\u00E8 

eg 

Latin 

small 

letter 

E 

with 

grave 









0x8B 

\u00EF 

ie 

Latin 

small 

letter 

I 

with 

diaeresis 









0x8C 

\u00EE 

ic 

Latin 

small 

letter 

I 

with 

circumflex 









0x8D 

\u00EC 

ig 

Latin 

small 

letter 

I 

with 

grave 









0x8E 

\u00C4 

Ae 

Latin 

capital letter 

A with 

diaeresis 









0x8F 

\u00C5 

Ao 

Latin 

capital letter 

A with 

ring above 









0x8F 

\u00C5 

angstrom 

Latin 

capital letter 

A with 

ring above 









0x90 

\u00C9 

Ea 

Latin 

capital letter 

E with 

acute 









0x91 

\u00E6 

aelig 

Latin 

small 

letter 

Ae 


0x92 

\u00C6 

AElig 

Latin 

capital letter 

Ae 


0x93 

\u00F4 

oc 

Latin 

small 

letter 

0 

with 

circumflex 









0x94 

\u00F6 

oe 

Latin 

small 

letter 

0 

with 

diaeresis 









0x95 

\u00F2 

og 

Latin 

small 

letter 

0 

with 

grave 









0x96 

XuOOFB 

uc 

Latin 

small 

letter 

u 

with 

circumflex 









0x97 

\u00F9 

ug 

Latin 

small 

letter 

u 

with 
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grave 



0x98 

\uOOFF 

ye 

Latin small letter Y with 

diaeresis 





0x99 

\u00D6 

Oe 

Latin capital letter 0 with 

diaeresis 





0x9A 

\uOODC 

Ue 

Latin capital letter U with 

diaeresis 





0x9B 

\u00A2 

cent 

Cent sign 


0x9C 

\u00A3 

Lsterling 

Pound sign 


0x9D 

\u00A5 

yen 

Yen sign 


0x9F 

\u0192 

fnof 

Latin small letter F with 

hook 

OxAO 

\uOOEl 

aa 

Latin small letter A with 

acute 

i 

OxAl 

\uOOED 

ia 

Latin small letter I with 

acute 





C 

0xA2 

\u00F3 

oa 

Latin small letter 0 with 

acute 





£ 

0xA3 

\uOOFA 

ua 

Latin small letter U with 

acute 





/ 

0xA4 

\uOOFl 

nt 

Latin small letter N with 

tilde 





¥ 

0xA5 

\uOODl 

Nt 

Latin capital letter N with 

tilde 





f 

0xA6 

\uOOAA 

aus 

Feminine ordinal indicator 

§ 

0xA7 

\u 0 0 BA 

ous 

Masculine ordinal indicator 

n 

0xA8 

\uOOBF 

invq 

Inverted question mark 

1 

0xA9 

\u2310 

lnotrev 

Reversed not sign 

W 

OxAA 

\uOOAC 

lnot 

Not sign 

W 

OxAA 

\uOOAC 

notsym 

Not sign 

« 

OxAB 

\u00bd 

fracl2 

Vulgar fraction one half 

< 

Ox AC 

\uOOBC 

fracl4 

Vulgar fraction one quarter 

> 

Ox AD 

\u00A1 

inve 

Inverted exclamation mark 

fi 

OxAE 

\u00ab 

odqf 

Left-pointing double angle 

quotation mark 




• 

OxAF 

XuOObb 

cdqf 

Right-pointing double angle 

quotation mark 





OxBO 

\u2591 

boxl4 

Light shade 

- 

OxBl 

\u2592 

boxl2 

Medium shade 

t 

0xB2 

\u2593 

box34 

Dark shade 

t 

0xB3 

\u2502 

bxv 

Box drawings light vertical 

• 

0xB4 

\u2524 

bxri 

Box drawings light vertical 

and left 




• 

0xB4 

\u2524 

bxr j 

Box drawings light vertical 

and left 





0xB5 

\u2561 

bxl012 

Box drawings vertical single 

and left 

double 




1 

0xB6 

\u2562 

bx2021 

Box drawings vertical double 

and left 

single 




• 

0xB7 

\u2556 

bx0021 

Box drawings down double and 

left single 




r 

0xB8 

\u2555 

bx0012 

Box drawings down single and 

left double 





0xB9 

\u2563 

bx2022 

Box drawings double vertical 

and left 




rr 

OxBA 

\u2551 

bx2020 

Box drawings double vertical 

» 

OxBB 

\u2557 

bx0022 

Box drawings double down and 

left 

OxBC 

\u255D 

bx2002 

Box drawings double up and 
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to OxBD 

\u255C 

left single 


OxBE 

\u255B 

left double 


OxBF 

\u2510 

left 


OxCO 

\u2514 

right 


OxCl 

\u2534 

horizontal 


OxCl 

\u2534 

horizontal 


0xC2 

\u252C 

horizontal 


0xC2 

\u252C 

horizontal 


0xC3 

\u251C 

and right 


0xC3 

\u251C 

and right 


0xC4 

\u2500 

horizontal 


0xC5 

\u253C 

and horizontal 


0xC5 

\u253C 

and horizontal 


0xC6 

\u255E 

and right double 

0xC7 

\u255F 

and right single 

0xC8 

\u255A 

right 


0xC9 

\u2554 

right 


OxCA 

\u2569 

horizontal 


OxCB 

\u2566 

horizontal 


OxCC 

\u2560 

and right 


OxCD 

\u2550 

horizontal 


OxCE 

\u256C 

and horizontal 


OxCF 

\u2567 

horizontal double 

OxDO 

\u2568 

horizontal single 

OxDl 

\u2564 

horizontal double 

0xD2 

\u2565 

horizontal single 

0xD3 

\u255 9 

right single 


0xD4 

\u2558 

right double 


0xD5 

\u2552 


bx2001 

Box 

drawings 

up double and 

bxl002 

Box 

drawings 

up single and 

bxur 

Box 

drawings 

light 

down and 

bxll 

Box 

drawings 

light 

up and 

bxas 

Box 

drawings 

light 

up and 

bxb j 

Box 

drawings 

light 

up and 

bxde 

Box 

drawings 

light 

down and 

bxt j 

Box 

drawings 

light 

down and 

bxle 

Box 

drawings 

light 

vertical 

bxl j 

Box 

drawings 

light 

vertical 

bxh 

Box 

drawings 

light 


bxcr 

Box 

drawings 

light 

vertical 

bxc j 

Box 

drawings 

light 

vertical 

bxl210 

Box 

drawings 

vertical single 

bx2120 

Box 

drawings 

vertical double 

bx2200 

Box 

drawings 

double 

up and 

bx0220 

Box 

drawings 

double 

down and 

bx2202 

Box 

drawings 

double 

up and 

bx0222 

Box 

drawings 

double 

down and 

bx2220 

Box 

drawings 

double 

vertical 

bx0202 

Box 

drawings 

double 


bx2222 

Box 

drawings 

double 

vertical 

bxl202 

Box 

drawings 

up single and 

bxl201 

Box 

drawings 

up double and 

bx0212 

Box 

drawings 

down single and 

bx0121 

Box 

drawings 

down double and 

bx2100 

Box 

drawings 

up double and 

bxl200 

Box 

drawings 

up single and 

bx0210 

Box 

drawings 

down single and 
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0xD6 

\u2553 

bx0120 

Box drawings down double and 

right 

single 

0xD7 

\u256B 

bx2121 

Box drawings vertical double 

and horizontal 
0xD8 

single 

\u256A 

bxl212 

Box drawings vertical single 

and horizontal 
0xD9 

double 

\u2518 

bxlr 

Box drawings light up and 

left 


OxDA 

\u250C 

bxul 

Box drawings light down and 

right 


OxDB 

\u2588 

BOX 

Box drawings Full block 


OxDC 

\u2584 

BOXBOT 

Box drawings Lower half 

block 


OxDD 

\u258C 

BOXLEFT 

Box drawings Left half block 


OxDE 

\u2590 

BOXRIGHT 

Box drawings Right half 

block 


OxDF 

\u2580 

BOXTOP 

Box drawings Upper half 

block 


OxEO 

\u03Bl 

alpha 

Greek small letter alpha 

A 

0x41 

\u0391 

Alpha 

Greek capital letter alpha 

E 

OxEl 

\uOODF 

Beta 

Latin small letter sharp s 


0xE2 

\u0393 

Gamma 

Greek capital letter gamma 

a 

0xE3 

\u03C0 

Pi 

Greek small letter pi 


0xE4 

\u03A3 

Sigma 

Greek capital letter sigma 


0xE5 

\u03C3 

sigma 

Greek small letter sigma 


0xE6 

\u00B4 

mu 

Micro sign 


0xE7 

\u03C4 

tau 

Greek small letter tau 


0xE8 

\u03A6 

Phi 

Greek capital letter phi 

0 

0xE9 

\u0398 

Theta 

Greek capital letter theta 


OxEA 

\u03A9 

Omega 

Greek capital letter omega 

o 

OxEB 

\u03B4 

delta 

Greek small letter delta 


OxEC 

\u221E 

infinity 

Infinity 


OxED 

\u03C6 

phi 

Greek small letter phi 


OxEE 

\u03B5 

epsilon 

Greek small letter epsilon 


OxEF 

\u222 9 

intersect 

Intersection 


OxFO 

\u2261 

identical 

Identical to 

as 

OxFl 

\uOOBl 

plusmin 

Plus-minus sign 

as 

OxFl 

\uOOBl 

pm 

Plus-minus sign 


0xF2 

\u2265 

ge 

Greater-than or equal to 


0xF2 

\u2265 

gesym 

Greater-than or equal to 


0xF3 

\u2264 

le 

Less-than or equal to 


0xF3 

\u2264 

lesym 

Less-than or equal to 


0xF4 

\u2320 

inttop 

Top half integral 

1 

0xF5 

\u2321 

intbot 

Bottom half integral 


0xF6 

\u00F7 

divide 

Division sign 


0xF7 

\u2248 

nearly 

Almost equal to 

1 

0xF8 

\uOOBO 

degree 

Degree sign 

1 

0xF8 

XuOOBO 

deg 

Degree sign 

0 

0xF9 

\u2219 

bullet 

Bullet operator 

oe 

OxFA 

\u00B7 

dot 

Middle dot 

ft 

OxFB 

\u221A 

sqrt 

Square root 


OxFC 

\u207F 

supn 

Superscript Latin small 

letter 

n 

OxFD 

\u00B2 

sup2 

Superscript 2 


OxFE 

\u25A0 

sqbul 

Black square 
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Index 



* 11 

.br 11 
.ce 11 
.im 11 
.nameit 12 


pt 32 
row 34 
table 33 
warning 35 
xmp 36 
Break 11 


c 


A 


acviewport 16 

Application controlled window 16 
artlink 17 
artwork 17 


B 


Block 

acviewport 16 
c 34 

caution 18 
dd 21 
ddhd 20 
dt 21 
dthd 20 
figcap 22 
fn 23 
hi 23 
h2 23 
h3 23 
h4 23 
h5 23 
h6 23 

11 26 

12 26 
icmd 27 
isyn 27 
li 27 
lines 27 
note 30 
nt 30 

p 31 
pd 32 


c 34 

caution 18 
Center 11 
cgraphic 18 
color 18 
Command 
.* 11 
.br 11 
.ce 11 
.nameit 12 
break 11 
center 11 
comment 11 
nameit 12 

Command line format 
wipfc 5 

Command line option 
localization 6 
output-name 6 
warning-level 6 
Command line switch 
inf 5 
quiet 5 

suppress-search 5 
xref 5 
Commands 
.im 11 
imbed 11 
Comment 11 
Ctrl 19 
ctrldef 19 


D 


dd 21 
ddf 19 
ddhd 20 

Definition list 20 
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Index 


definition 21 
definition header 20 
term 21 
term header 20 
dl 20 
docprof 21 
Document header 
Ctrl 19 
ctrldef 19 
docprof 21 
pbutton 32 
title 34 
dt 21 
dthd 20 

Dynamic data formatting 19 


hpl 25 
hp2 25 
hp3 25 
hp4 25 
hp5 25 
hp6 25 
hp7 25 
hp8 25 
hp9 25 
lm 30 
rm 33 


G 


E 


Entity references 8 
Environment variable 
IPFC ARTW ORK 5 
IPFCIMBED 5 
TMP 5 
WIPFC 5 
Example 36 


Generated text 
caution 18 
header reference 25 
note 30 
nt 30 

warning 35 


H 


F 


fig 22 
figcap 22 
Figures 

caption 22 
character 18 
images 17 
text 22 
Flag 
inf 5 
quiet 5 

suppress-search 5 
xref 5 
fn 23 
font 22 
Footnote 23 
Formatting 
color 18 
font 22 
hide 25 


hi 23 
h2 23 
h3 23 
h4 23 
h5 23 
h6 23 
hdref 25 
Headings 23 
hide 25 

Highlighted phrase 25 

hpl 25 

hp2 25 

hp3 25 

hp4 25 

hp5 25 

hp6 25 

hp7 25 

hp8 25 

hp9 25 
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Index 



11 26 

12 26 
icmd 27 
Imbed 11 
In-line 

artlink 17 
artwork 17 
link 28 
Indexing 

commands 27 
primary entry 26 
secondary entry 26 
synonyms 27 
inf switch 5 

Invoking the Open Watcom OS/2 Help Compiler 
5 

IPFC ART WORK environment variable 5 
IPFCIMBED environment variable 5 
isyn 27 


L 


li 27 
lines 27 
link 28 
Links 

header 25 
images 17 
text 28 
List item 27 
List part 30 
List-block 
dl 20 
ol 31 
parml 31 
si 33 
ul 35 
Lists 

definition 20-21 
definition header 20 
item 27 
ordered 31 
parameter 31 
parameter description 32 
parameter term 32 


part of an item 30 
simple 33 
term 21 
term header 20 
unordered 35 
lm 30 

localization option 6 
Ip 30 


M 


Margin 
left 30 
right 33 


N 


Nameit 12 
note 30 
Notices 
caution 18 
note 30 
nt 30 

warning 35 
nt 30 


0 


ol 31 
Option 

localization 6 
output-name 6 
warning-level 6 
Ordered list 31 
output-name option 6 


P 


p 31 
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Index 


Paragraph 31 
Parameter list 31 
description 32 
term 32 
parml 31 
pbutton 32 
pd 32 
pt 32 

punctuation 7 


Q 


quiet switch 5 


R 


rm 33 
row 34 


s 


Simple list 33 
si 33 

suppress-search switch 5 
symbols 8 


T 


Table 33 
column 34 
row 34 
Tags 

and text 9 
attributes 8 
ending 9 
nesting 9 
syntax 8 
Text 7 

entity references 8 


punctuation 7 
symbols 8 
whitespace 7 
words 7 
title 34 

TMP environment variable 5 


u 


ul 35 

Unordered list 35 
userdoc 35 


w 


warning 35 
warning-level option 6 
whitespace 7 
wipfc 

Command line format 5 
wipfc command line 

invoking wipfc 5 
WIPFC environment variable 5 
words 7 


X 


xmp 36 
xref switch 5 
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